Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

feat: what the machine already has (v1.50.0) (#168)

Sol Aitkenaa73af4b3e73
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 1aaddd3c..94e47cc2 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.49.0",
+ "version": "1.50.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index ecc89f9c..54eabb6e 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.49.0",
+ "version": "1.50.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"hooks": "./hooks/hooks.json",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 76416ed0..1d8b1f46 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,77 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.50.0] - 2026-08-16
+
+Nine tracker items, picked off the board by priority and read against the real source before anything was designed, turned out to be one question seen from nine sides: what does Open Second Brain know about the machine it is installed on, where is that knowledge declared, and what proves it is true. Three of the nine were not missing features. They were contracts already written into the type system with nothing behind them - `InstallAdapter.sessionPaths` with ten declarations and no caller, `ExportFormat` imported nowhere while the command inlined its two literals, and four maintenance task names that were not a vocabulary at all but two independent lists in two files, which is why the command line and the tool surface had drifted apart two releases running.
+
+Reconnaissance corrected three task bodies before a line was written. A committed vault-level configuration already existed; what was missing was that install and hook generation never read it, and that no resolver anywhere could say which layer a value came from. The tool-profile mechanism already existed; what was missing was the one adapter whose host publishes a limit selecting nothing. And the tool count on the card was 90 against a measured 110.
+
+Then the finished branch went to six reviewers who did not know how it was built, four by area, one told only to find tests that cannot fail, and one to fix what they found. They returned forty-one confirmed defects with reproductions, and the release is what survived that. Two were secret leaks inside the code that exists to stop secret leaks. Three were data-loss paths in a command whose entire purpose is moving data safely. One reviewer finding was rejected with an argument, and the duplication underneath it fixed instead.
+
+### Added
+
+- **One declaration per runtime.** A closed target vocabulary and a fact table stating, per agent runtime, its published tool ceiling, the profile that fits under it, the session adapter it maps to, where it keeps session logs, and how its binary can be asked what it has registered. Session roots are pure functions of an injected home and environment, and a test poisons the real environment to prove nothing leaks in. A census derives the population from the live adapter registry and compares it to the table in both directions, so neither an adapter without a row nor a row without an adapter can ship.
+- **A capped host gets a surface that fits it.** Cursor publishes a per-workspace ceiling of about forty tools and was being handed 110. Its generated registration now names the `catalog` profile: seven advertised, every verb still reachable through `tool_hydrate`. The count is not asserted from a fixture - the test builds a real server and calls `tools/list`. An unchecked ceiling is a third state, never folded into "no limit": eight runtimes publish nothing anyone has found, they get no profile, and the capability report says so with the reason rather than staying quiet.
+- **`o2b install --friction`** compares hosts by capability dimension, every cell derived from the fact table and the adapter's own plan rather than a hand-written column. Three further dimensions were dropped rather than faked, each with the reason in the module: they have no structural source, and a column read from one adapter's private constant is a hand-written table in disguise.
+- **Hosts that can be asked are asked.** Every configuration comparison used to end with the same sentence about no handshake being attempted. A runtime that declares a probe now gets a keyless, free `mcp list`-style query - no model turn, a ten-second cap - and prints either the host's own answer or a named skip. The blanket sentence survives only where no probe exists, which is where it is true.
+- **A Codex install adapter**, so a four-step manual procedure becomes `o2b install --target codex --apply`. It reuses the existing TOML editor rather than growing a second one, and every unrelated table in the operator's configuration survives byte for byte. Its probe is deliberately not the JSON form: the shared parser reads the first token of each line, which under `--json` is the same key on every line, so a JSON probe would report every host as empty - a false negative dressed as an answer.
+- **`o2b state status`** reports all forty declared state surfaces with the path each resolved to, whether this run could reach it, and which configuration layer put it there. Reachability is a tri-state: a permission error reports unchecked with its errno rather than being rounded down to absent, because "it is not there" and "I could not look" have different repairs. Rows are tiered by recovery story rather than by location.
+- **`o2b state migrate` and `o2b state rollback`** move that state and put it back, binding source type, roots, path inventory, byte counts and per-file digests into a manifest. Every check runs before anything is committed, and the whole plan is refused rather than half applied - on a symlink, a special file, an occupied destination, insufficient space, a reserved namespace, an unreadable surface, or a held index writer lock, the one loss a digest cannot undo. Within the apply, every file is copied and re-digested at the destination before a single source byte is removed.
+- **Both transports drain.** On a termination signal the server stops accepting, reports draining with an in-flight count on the unauthenticated health endpoint, waits a bounded ten seconds, names any still-open request on standard error rather than dropping it, and exits with the signal's code so the hooks that checkpoint the index and release locks still run.
+- **`o2b brain import-session --status` and `--discover`** answer what session logs this machine holds and which were never imported, keyed by content digest so an unchanged log is reported as imported without being parsed again. Found equals imported plus gap plus unparsable, and a Cursor database counts unparsable rather than gap, because a gap is work an operator can close.
+- **`o2b brain export --format transcripts-jsonl`** emits one JSON record per conversation. Not instruction-and-response pairs: that is a lossy projection needing three judgements the runtime never recorded, and while a harness can derive pairs from a conversation, nothing derives the conversation back. Tool names travel; tool inputs never do.
+- **A committed `install:` block** in the vault configuration supplies the generated hook timeout and the tool profile, and outranks the machine-local tier on purpose - two machines cloning one vault must not generate different hooks because one of them has a stale local key.
+
+### Changed
+
+- **Config values can say which layer produced them.** A provenance-returning resolver was added and the existing one delegates to it, so none of its roughly fifty-five call sites changed and a test asserts the two agree on every branch. The alternative - widening the shared function - was the largest risk in the design and bought nothing.
+- **The environment tier no longer reaches a written registration.** The invariant is not how many tiers there are but which survive to the next invocation: a committed file and a machine-local file do, a shell variable does not, and a verifier that reconstructs from one cannot be fed by the other. The variable still selects the surface of a server you start yourself.
+- **The maintenance lane's task names are a vocabulary**, and its values are operation references rather than fresh strings, so a lane task is by construction an operation that has a deadline budget. Both surfaces build their lists from it, and a census derives the command-line flag set and the tool property set from source and requires each member to reach the other or carry a written exemption - now including the bounds, since the two accepted different ranges for the same knob.
+- **`brain_dream` with a single step runs under a deadline.** It was the one path that did not, and the pass is synchronous, so an unbounded step held the whole server. The two functions it calls take a guard now. What is not interruptible is stated precisely rather than glossed: the vault listing and the phrase build are single phases, so the guarantee is one page plus whichever of those is running.
+- **`brain_maintenance` reaches the escapes the command line already had.** Its streak refusal used to tell every caller to use a flag half of them cannot reach; it names both now. The `force` description named two gates while force disabled four.
+- **Session parsing streams.** All five adapters read whole files and split them, so peak retention was about twice the file before the first turn was yielded. Measured on a 10.79 MB session: 12,058,624 bytes retained before turn one, against a 262,144-byte window now. Byte identity was proved rather than claimed, by diffing the old and new adapters over sixty file pairs including a character straddling a chunk boundary.
+- **Session log roots are declared once.** The discipline scanners independently knew where three runtimes keep their logs and swept them for a different question; both consumers read one table now, proved by a test that relocates a root and watches both follow.
+- **The egress site is renamed** from a name that said preferences to one that says export, because it now guards whole recorded conversations.
+
+### Fixed
+
+- **A refusal printed the secret it was refusing to write.** When the transcript export declined because a session filename was secret-shaped, it prefixed the refusal with that filename - into CI logs and shell scrollback, on the one path whose purpose is not letting it out. The guard's own message says locations rather than values; the command printed the value in front of it.
+- **The redactor could not see a prefixed environment assignment.** Its rule opened with a word boundary, and an underscore is a word character, so `API_KEY=x` was caught and `ANTHROPIC_API_KEY=x` was not. Everything that appeared to work was being caught by the vendor-prefix rule on the value instead. That is the most common shape a key takes in an agent transcript, and this release is what first ships transcripts off the machine.
+- **A bare high-entropy identifier left verbatim.** A session filename and a turn id are named by a foreign harness, and the reasoning that lets vault-authored identifiers skip the entropy scan does not transfer to them.
+- **Rollback could destroy the only surviving copy.** It read the source root from the manifest without checking it still existed, so an operator who migrated and then renamed their vault had the old path recreated, the destination copy removed, the manifest deleted, and a success exit. It refuses by name now, and `--to` names where the vault went.
+- **Rollback overwrote a file written between plan and apply**, deciding "already in place" once and copying later without re-checking - the one thing the module says it must never do.
+- **The reserved-namespace checks compared resolved strings without following links**, so a symlinked destination ancestor moved the whole state tree inside the vault it was migrating.
+- **`o2b update` hashed a payload it does not write**, so it reported no change while `o2b install --check` reported drift on the same target, and a Cursor install kept its oversized registration. Two commands contradicting each other about one file.
+- **The host probe asked the ambient machine** rather than the one being verified, so a relocated Codex home could verify against a different home's registrations.
+- **A directory import recorded files that failed to import as imported**, making them permanently invisible to the coverage report until their bytes changed - including after a future release ships an adapter that could read them.
+- **A ledger failure after a successful import reported the import as failed** and suppressed its report, so the machine-readable consumer got nothing while the signal was on disk.
+- **One empty transcript aborted the whole export.** Agent runtimes leave zero-length files routinely, and the offered remedy was to move them out of a directory holding a thousand.
+- **`--since` silently dropped transcripts with no clock**, which is precisely the case its own comment forbade: the guarantee held only for a malformed timestamp, which never occurs, while the synthesised epoch sentinel took the forbidden path.
+- **An unreadable vault configuration escaped as a stack trace** and took every install target with it, because the detection sweep runs all adapters and one of them reads that file.
+- **`o2b install --friction` crashed on the same file**, though it is documented as a report that never exits non-zero.
+- **A failed removal still dropped the install manifest entry**, so the retry demanded a force flag to clean up what it had just forgotten.
+- **A commented-out table counted as a declared server**, so an operator who commented both out and removed the binary from the path was told the install was fine.
+- **The snapshot gate reported a cause it invented and hid the one it had.** Reported from outside as a Windows failure, root-caused here as a platform-independent defect and reproduced on Linux. The retry key matched any `EEXIST` anywhere in an error's cause chain, without regard for which path collided - and the first thing a snapshot does is create its own archive directory. So a failure to make `Brain/.snapshots` read as "another process took this candidate run id", laddered through all sixty-four candidates, and reported that every one was claimed, while the real error sat in a `cause` neither command-line wrapper printed. Nothing had claimed anything, and the directory need not have existed at all. The retry now matches only a collision naming this candidate's own archive; an error carrying the code but no path no longer counts, because treating unknown as "yours" is what produced the fiction. The directory is diagnosed before it is written into, naming what was actually found there, and error causes reach the operator through one renderer rather than being dropped at the last line.
+
+### Notes
+
+Some of what the reviewers asked for is not here, and each absence is a decision.
+
+Three adapters answer a refuting probe differently and were not collapsed into one verdict, because collapsing them would make one wrong: one leaves no artifact, so the host's registry is the record and its no means the registration is gone; the other two compared an artifact and found it correct, so the host has not reloaded. The defect was that one rule was argued three times in three bodies. It is argued once now.
+
+The streaming bound is asserted on the reader's own accounting rather than on resident memory, and the suite says so and records the adapter it cannot catch - one that streams correctly and also holds the file. Repeated measurement showed resident size swinging between zero and sixty-six megabytes on the same code path, because mid-iteration heap is dominated by parse garbage rather than by the reader's window. A bound that reports thirty megabytes for a reader holding two hundred and fifty-six kilobytes is not a bound.
+
+Two progress emitters cannot produce an advance record in a test - one needs an embedding provider and a network call, the other owns no loop - so they carry declared exceptions checked in both directions, and an exception that outlives its condition fails.
+
+With `--recall` set, session import still accumulates every kept turn in memory, about 1.4 times the file, because the recall store takes a materialised array. The adapters underneath it no longer do. Bounding that means changing the store's signature, which is its own unit.
+
+A defect that could not be given a failing test is named rather than quietly fixed: the platform refusal in the grok adapter's detection path reads the process platform directly with no seam, so it cannot be driven from this one.
+
+The Windows half of the report that produced the snapshot fix is not fixed, and will not be claimed. Whether this runtime raises `EEXIST` when asked to create a directory that already exists on that platform is a question no machine here can answer, there is no Windows job in continuous integration, and shipping an unverifiable fix is the thing this release exists to stop doing. What did ship makes the next report falsifiable: the command now names the directory and what is in it instead of a run-id ladder that never ran.
+
+That report also stood inside a boundary this project declares and does not hold. Windows is listed as an unsupported platform, but the refusal sits on the third branch of configuration-path resolution, after two environment variables have been consulted - so setting either one runs the whole product on a platform it says it refuses, and the code already documents that as intentional. It is a sign on an open door. Making it a real boundary would break two documented ways people are using today, and calling it advisory means saying so in the README and stopping treating those reports as in-scope. That is a decision for the operator, and it is recorded rather than taken.
+
## [1.49.0] - 2026-08-16
Ten tracker items, picked by priority off the board and read against the real source before anything was designed, turned out to describe one defect seen from ten sides: the product declares a boundary and puts nothing behind it. An owner-isolation filter whose field no writer ever emitted. A gate that enforced whichever scope the caller asked for. A confidence floor compared against a number that could not vary with match quality. An egress registry built to stop an unguarded export, with an unguarded export outside it. A census whose docblock claimed to have closed the mis-parse class that was live inside it.
@@ -7186,6 +7257,7 @@ plugin config (vault field)`, and exits with a clear
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[1.50.0]: https://github.com/itechmeat/open-second-brain/compare/v1.49.0...v1.50.0
[1.49.0]: https://github.com/itechmeat/open-second-brain/compare/v1.48.0...v1.49.0
[1.48.0]: https://github.com/itechmeat/open-second-brain/compare/v1.47.0...v1.48.0
[1.47.0]: https://github.com/itechmeat/open-second-brain/compare/v1.46.0...v1.47.0
diff --git a/README.md b/README.md
index f93d9bf0..9bbb71e4 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ Enable Open Second Brain as the memory provider in `~/.hermes/config.yaml` (`mem
| Runtime | Install |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Claude Code | Marketplace plugin (bundled `.mcp.json` + hooks) - [`install/claudecode.md`](install/claudecode.md) |
-| OpenAI Codex | `codex plugin marketplace add ...` - [`install/codex.md`](install/codex.md) |
+| OpenAI Codex | `codex plugin marketplace add ...` then `o2b install --target codex --apply` (MCP servers via `codex mcp add`, or a `config.toml` merge without the binary) - [`install/codex.md`](install/codex.md) |
| OpenClaw | Native JS plugin, no MCP needed - [`install/openclaw.md`](install/openclaw.md) |
| opencode | `o2b install --target opencode --apply` (MCP servers + native plugin) - [`install/opencode.md`](install/opencode.md) |
| Grok Build | `o2b install --target grok --apply` (MCP in `config.toml` + native hooks) - [`install/grok.md`](install/grok.md) |
@@ -128,11 +128,13 @@ Each non-Hermes target writes a sidecar manifest under `<vault>/.open-second-bra
- **A today surface for the operator, and prose that writes back.** `o2b brain today` (and `brain_brief view=today`) renders a read-only, live-derived dashboard - due and overdue obligations, open loops, a chronologically merged typed activity timeline with relative ages, and totals - where every section is re-derived on demand from the vault, never stored, and a failing section reports its error while the rest still render. Jot `@osb loop <text>` in any note to keep an intention visible until you close it with `@osb loop close id=<id>` (ids are printed on the dashboard; loop markers survive scans and are never consumed). Jot `@osb set note=<target> field=<field> value=<value>` and `o2b brain apply-markers --apply` turns it into a schema-validated frontmatter mutation - fail-closed target resolution (ambiguous titles list candidates instead of guessing), one `attribute-write` audit event per applied change with the prior value, idempotent consumption of applied markers, and the whole write path gated behind the opt-in `guardrails.marker_writeback` flag. Report mode needs no flag and writes nothing.
+- **It knows the machine it is installed on.** `o2b install --friction` lays every supported runtime side by side - how it is installed, whether it caps the tool surface, whether a `--check` on it is a file comparison or a live question put to the host, and whether this build can read the transcripts that runtime writes. Two hosts can now be ASKED (`codex mcp list`, `copilot mcp list`) instead of inferred from a config file, so "installed" and "actually loaded" stop being the same answer. `o2b state status` does the same for the vault: forty declared state locations, each with where it resolved, whether it is reachable, and which setting put it there - and `o2b state migrate` moves the lot to another directory behind a digest manifest, refusing before it commits and reversible after. `o2b brain import-session --discover` finds the session logs already on your disk and says which have never been imported, so cross-agent recall no longer depends on your knowing where each runtime keeps its transcripts.
+
That is the day-to-day picture. The full capability surface, every CLI verb, and the mental model live in the [documentation](#documentation) below.
## Safety
-- Plain Markdown on your filesystem. No daemon, no background writes. The MCP server is a stdio subprocess that exits with the parent runtime. An optional HTTP transport (`o2b mcp --transport http`) is off by default and safe by design: it binds loopback (`127.0.0.1`), enforces a Host/Origin DNS-rebinding guard on every request, and exposes an unauthenticated `GET /health` liveness probe. A bearer token (`--api-key`) is optional on loopback and mandatory when binding a non-loopback host - the server refuses to expose an unauthenticated endpoint on the network.
+- Plain Markdown on your filesystem. No daemon, no background writes. The MCP server is a stdio subprocess that exits with the parent runtime. An optional HTTP transport (`o2b mcp --transport http`) is off by default and safe by design: it binds loopback (`127.0.0.1`), enforces a Host/Origin DNS-rebinding guard on every request, and exposes an unauthenticated `GET /health` liveness probe. A bearer token (`--api-key`) is optional on loopback and mandatory when binding a non-loopback host - the server refuses to expose an unauthenticated endpoint on the network. On `SIGTERM`/`SIGINT` either transport stops accepting new work, finishes what is already running under a bounded deadline (`O2B_MCP_DRAIN_MS`, ten seconds by default), and only then exits - so a shutdown never truncates a tool call, and `/health` reports `draining` while it happens.
- Your vault is the only source of truth - no hidden state, no cloud copy.
- Brain mutations (`dream`, `merge`, `upgrade`) take a pre-run snapshot with a SHA-256 sidecar; `o2b brain rollback` aborts on drift unless `--force-rollback`. Destructive cleanups (`forget-source --confirm`, `entity prune --confirm`) run behind the same snapshot gate and report their recovery point; dry runs take no snapshot.
- Store hardening: `o2b brain doctor --remediate` can tighten existing `Brain/` files to owner-only permissions (dry-run first, idempotent), the doctor flags vault-internal symlinks that resolve outside the vault, and MCP responses carry an opaque `vault://` store reference instead of the absolute host path unless `expose_host_paths: true` is set.
diff --git a/docs/architecture.md b/docs/architecture.md
index 3574f5bc..44bb6b06 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -61,17 +61,31 @@ The adapter should focus on:
### Codex adapter
-Codex supports plugins as installable distribution units for reusable skills and apps. The Codex adapter should include:
+Codex support has two halves. The distribution half is a plugin:
```text
-.codex-plugin/plugin.json
+.codex-plugin/plugin.json # declares "skills": "./skills" and "hooks": "./hooks/hooks.json"
skills/
-.mcp.json # later, optional
-hooks/ # later, optional
-assets/ # later, optional
+hooks/hooks.json
```
-v0 should keep Codex support simple: plugin manifest plus shared skills and scripts.
+The MCP half is a runtime install adapter
+(`src/core/install/adapters/codex.ts`), reached the same way every other
+adapter-backed runtime is: `o2b install --target codex --apply`. It has two
+paths into the same file. With the `codex` binary on PATH it drives
+`codex mcp add`, which persists the servers into `$CODEX_HOME/config.toml`;
+without it, it merges the two `[mcp_servers.*]` tables into that file
+directly, leaving every unrelated table byte-for-byte intact.
+
+`verify` therefore asks two different questions of one file. In fallback
+mode this build serialised the tables, so any edit is drift. In subprocess
+mode the Codex CLI serialised them in a layout this build has no published
+grammar for, so `verify` checks only that the two tables are still DECLARED
+and lets `codex mcp list` answer whether the host is actually serving them.
+Both the file half and the probe half resolve `CODEX_HOME` from the
+adapter's own injected environment, so a relocated Codex home cannot verify
+against the operator's real `~/.codex`. Operator steps:
+[`install/codex.md`](../install/codex.md).
### OpenClaw adapter
@@ -150,6 +164,17 @@ with backup/sync. It describes:
indexing, not a boundary); an empty `ignore_paths` keeps its meaning of
"exclude nothing". Both keys share one grammar: no slash is a bare name
matched at any depth, a slash is a vault-relative path matched exactly;
+- an optional `install:` block with the two settings that parameterise
+ GENERATED install output: `tool_profile` (the MCP tool surface a
+ generated registration selects) and `hook_timeout_seconds` (1–600, the
+ cap on a generated lifecycle hook entry). They live here rather than in
+ the machine-local config because install verification works by
+ RE-CONSTRUCTION rather than a stored hash: a knob only one machine could
+ see would make the other report drift it cannot explain and re-apply a
+ file that was already correct. This block therefore OUTRANKS the
+ machine-local `mcp_tool_profile` / `install_hook_timeout_seconds` keys,
+ and an unreadable `_brain.yaml` refuses the resolution rather than
+ falling back to a default the operator never chose;
- optional `write_binding.path_prefixes` (where a CALLER-NAMED write may
land: `brain_create_note`, `brain_update_note`, `brain_append_note`,
`brain_write_batch`). This is a write boundary over caller-named paths,
@@ -171,6 +196,19 @@ Recommended behavior:
- `o2b export-config` writes a redacted machine snapshot into the vault;
- secrets are excluded and represented as `***REDACTED***` only when needed.
+What "the vault" contains is enumerated rather than assumed.
+`src/core/state/surfaces.ts` declares every durable location this build
+keeps INSIDE a vault β€” 40 of them β€” each with the layer that can move it
+and what its loss costs, split into `derived` (rebuildable, so deleting it
+costs time) and `vault-content` (the memory itself, permanent without a
+backup). `o2b state status` measures that catalogue against one vault and
+the `vault_health` MCP tool carries the same value; `o2b state migrate`
+is the one operation that changes where a surface lives, and it binds every
+byte it moves with a digest manifest so the move is reversible. The sibling
+population β€” what this build can leave OUTSIDE a vault β€” is
+`src/core/install/ownership.ts`, reported by the ownership statement
+`o2b install --target <t> --apply` prints.
+
## Vault layout
The agent owns one directory in the vault for its own artefacts:
diff --git a/docs/brainstorm/what-the-machine-already-has/cli-output/claude.md b/docs/brainstorm/what-the-machine-already-has/cli-output/claude.md
new file mode 100644
index 00000000..03c42ec0
--- /dev/null
+++ b/docs/brainstorm/what-the-machine-already-has/cli-output/claude.md
@@ -0,0 +1,46 @@
+### Variant 1: One host-facts table
+
+- **Approach**: Introduce a single frozen population β€” `HOST_FACTS` β€” keyed by a new closed `INSTALL_TARGET_ID` vocabulary in the house form (frozen object, derived union, members array, guard), where each row carries everything the project claims to know about one runtime: tool-surface ceiling, config file location and format, install mechanism (json-merge / subprocess), session-log roots, and the state surfaces that runtime causes to exist. State surfaces (item 7) are folded in as rows of the same table under a synthetic `vault` target, so `OUT_OF_VAULT_STATE` becomes a projection of `HOST_FACTS` rather than a sibling list. Every consumer β€” profile selection, install adapters, `sessionPaths()`, session discovery, `second_brain_capabilities`, the inventory verb β€” reads the table and nothing else; a new `tests/core/architecture/host-facts-census.test.ts` derives the population structurally and fails on any row without a reader or any reader with a literal the table could supply.
+- **Trade-offs**:
+ - Pro: maximal DRY β€” one place a maintainer edits when a new runtime appears, and adding Codex (item 5) is one row plus one adapter, not five scattered edits.
+ - Pro: the ceiling fact (item 1) and the log-root fact (item 4) sit on the same row, so `discipline/transcripts` and `brain/sessions` are forced to converge on one declaration instead of two half-truths.
+ - Pro: a single census can prove the whole substrate; the ratchet is one equality count, easy to review.
+ - Con: forces a false union. A tool-surface ceiling, a TOML config path and a writer-lock file are not the same kind of fact; the row type degenerates into a wide bag of optionals, which is exactly the shape that let `sessionPaths?()` (item 3) become declared-and-unread.
+ - Con: state surfaces are keyed by surface identity, not by target identity; grafting them onto a target-keyed table needs a synthetic key that carries no meaning.
+ - Con: one table with one census makes the units less separable β€” several of the nine can only land after the table exists, which weakens the atomic-unit constraint.
+ - Con: says nothing about provenance (item 6); `envOrConfig` still returns a bare value.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 2: Two closed registries and a provenance spine
+
+- **Approach**: Split the substrate along its two real key spaces and add the missing third dimension. `RUNTIME_FACTS` is keyed by a closed `INSTALL_TARGET_ID` and holds per-host contract knowledge (tool ceiling and the resulting profile floor, config format, install mechanism, session-log roots, the `SESSION_ADAPTER_ID` it maps to β€” collapsing item 3's orphan `format` union into the live vocabulary rather than adding a sixth one). `STATE_SURFACES` is keyed by a closed surface id and extends `OUT_OF_VAULT_STATE` in place β€” every row gains a resolver reference, a reachability tri-state modelled on `SearchIndexVerdict`, and the override key that can move it. Cutting across both, `envOrConfig` in `src/core/validate.ts` is widened to return a value plus a declared origin layer (env / user config / `Brain/_brain.yaml` / default), which is what lets install and hook generation finally read the committed vault tier without a stale key winning silently, and what lets a single `o2b doctor`-adjacent inventory verb print, for every runtime and every surface, the value, where it came from, and whether it is reachable.
+- **Trade-offs**:
+ - Pro: each registry has one honest key space and one reader family, so neither row type degenerates into optionals; the house closed-vocabulary pattern applies cleanly to all three.
+ - Pro: provenance is the one addition that makes the other eight verifiable rather than merely declared β€” a census can assert that every fact printed by the inventory names its origin, which is a much stronger ratchet than "row exists".
+ - Pro: separates cleanly into atomic units β€” the ratchet on the origin type, `RUNTIME_FACTS` plus the ceiling-aware profile floor, the Codex adapter, the surface inventory, the maintenance-task vocabulary (item 8), and the streaming session reader (item 9) each land and test independently, in any order after the vocabularies exist.
+ - Pro: `MaintenanceTask.name` and the `ExportFormat` orphan become instances of the same fix β€” a closed vocabulary with one declaration site β€” rather than two unrelated cleanups.
+ - Con: three new shared constructs to review at once; the widened `envOrConfig` touches roughly fifty-five call sites, and a mechanical sweep that large hides mistakes.
+ - Con: two registries can still drift from each other if a future runtime is added to one and not the other; needs a cross-census asserting the mapping between target ids and session adapter ids is total.
+ - Con: still declares rather than measures β€” a wrong ceiling in `RUNTIME_FACTS` is invisible until a user reports dropped tools.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 3: Owner-local obligation plus live probe
+
+- **Approach**: Declare no central table. Instead make the existing `InstallAdapter` interface carry the knowledge as required (not optional) members β€” a limits descriptor, a session-paths descriptor, a state-surfaces contribution β€” so each adapter owns the facts about its own host and TypeScript itself refuses an adapter that omits one, which is the structural fix for `sessionPaths?()` being declared with nothing behind it. Proof shifts from declaration to measurement: extend `tests/docs/install-verify-conformance.test.ts` into a per-adapter friction comparison, and give every adapter a `probe()` on the `copilot-cli` precedent (injectable runner, explicit skip reason when the host binary is absent) so `verify()` stops ending in "no MCP handshake attempted" for hosts that can actually answer. The tool-surface ceiling is then not a hardcoded number but a measured, recorded observation with a declared fallback.
+- **Trade-offs**:
+ - Pro: knowledge lives next to the code that acts on it, which is the strongest anti-drift force available and needs no synthetic key space.
+ - Pro: required interface members are compiler-enforced β€” a stronger guarantee than a census for the completeness half of the problem.
+ - Pro: probing produces facts about the machine actually installed on, which is the only thing that can catch a host whose ceiling changed upstream.
+ - Pro: fits the re-construction convention and keeps generated payloads byte-identical, since probes inform reporting rather than payload content.
+ - Con: does not answer the cross-cutting questions at all. "Which session logs exist and were never imported" and "where does every state surface live" require an inventory across owners; with owner-local declaration only, the reader has to enumerate the registry and can never prove the enumeration is complete for non-adapter surfaces (the search index, the maintenance lease, the hook audit have no adapter to own them).
+ - Con: probes are environment-dependent, so CI must exercise the skip path far more often than the live path, which is how "no handshake attempted" reappears under a new name.
+ - Con: leaves item 6 untouched β€” provenance is not an adapter concern β€” and item 8's vocabulary problem is unaddressed.
+ - Con: mandatory interface members are a breaking change to every existing adapter in one commit, which fights the separable-atomic-units constraint.
+- **Complexity**: medium
+- **Risk**: high
+
+### Recommended: Variant 2
+
+**Rationale**: The nine items drifted for one reason β€” a fact was declared in one place and read in none, or read in two places from two declarations β€” and only Variant 2 attacks both halves, because provenance is what converts "a row exists" into "this value won, from this layer, and here is the surface that proves it reachable". Variant 1's single table is more DRY on paper but unions two key spaces that are genuinely different, reproducing the wide-optional shape that produced item 3 in the first place; Variant 3's owner-local obligation is the right instinct for adapters yet structurally cannot answer the inventory questions in items 4 and 7, since the state surfaces with no owning adapter are exactly the ones nobody tracks. Variant 2 also decomposes best against the hard constraint that this ship as separable atomic units on one branch, and it should still borrow Variant 3's probe as one column of `RUNTIME_FACTS` β€” declared ceiling, measured ceiling, explicit skip reason β€” so the substrate reports what it knows and how it knows it rather than asserting either alone.
diff --git a/docs/brainstorm/what-the-machine-already-has/cli-output/prompt.md b/docs/brainstorm/what-the-machine-already-has/cli-output/prompt.md
new file mode 100644
index 00000000..35804f6c
--- /dev/null
+++ b/docs/brainstorm/what-the-machine-already-has/cli-output/prompt.md
@@ -0,0 +1,220 @@
+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.
+
+# Task
+
+Nine tracker items were selected together because reconnaissance showed they are one
+question seen from nine sides: **what does Open Second Brain know about the machine it
+is installed on, where is that knowledge declared, and what proves it is true?**
+
+The nine, with what verification against the live source at v1.49.0 actually found:
+
+1. **A capped host never selects a bounded tool profile.** `src/mcp/profiles.ts` ships
+ `TOOL_SURFACE_PROFILES` (full / writer / catalog / recall / minimal) selectable by
+ config key `mcp_tool_profile`, env `OPEN_SECOND_BRAIN_MCP_TOOL_PROFILE`, or
+ `o2b mcp --tool-profile`. Selection fails OPEN: an unknown name degrades to the full
+ surface. `src/core/install/adapters/cursor.ts` is a plain JSON merge with zero
+ occurrences of "profile". Measured live: `buildToolTable("full").length === 110`.
+ Cursor's documented per-workspace ceiling is about 40. So the host silently drops
+ tools with no `second_brain_capabilities` row to say which or why. Fail-open is right
+ for an unknown profile NAME and wrong for a host with a KNOWN ceiling.
+
+2. **No install adapter is ever exercised against a live host.**
+ `tests/docs/install-verify-conformance.test.ts` derives the adapter population from
+ the runtime registry, performs a real plan+apply into a temp home and temp vault,
+ and compares `renderVerifyTable(adapter.verify(env))` to an expected-output block in
+ `install/<target>.md`. That is strong, but every `verify()` on a JSON host ends with
+ the literal note `"configuration comparison; no MCP handshake attempted"`. Only
+ `copilot-cli` probes liveness. There is no per-adapter friction comparison telling a
+ maintainer which pain is one host's contract problem and which is ours.
+
+3. **`InstallAdapter.sessionPaths?()` is declared with nothing behind it.**
+ `src/core/install/types.ts:147`. Zero implementations, zero call sites repo-wide. Its
+ `format` union `"claude-jsonl" | "codex-json" | "cursor-sqlite" | "unknown"` is the
+ only occurrence of those literals anywhere in `src/` or `tests/`, and it is disjoint
+ from the live `SESSION_ADAPTER_ID` vocabulary (claude, codex, hermes, opencode, grok).
+
+4. **Nothing can answer "which session logs exist on this machine and which were never
+ imported".** `o2b brain import-session <path>` requires an explicit path. No session
+ adapter knows where its own logs live β€” verified, there is no `homedir`, no
+ `process.env` and no path join anywhere under `src/core/brain/sessions/`; the log
+ roots exist only as English prose in docblocks. Meanwhile a PARALLEL subsystem,
+ `src/core/discipline/transcripts/`, does know roots for claude-code, codex and cursor
+ and scans them by mtime day-window for activity metrics β€” a different question with
+ the same input.
+
+5. **Codex is a distribution target this project already maintains, with no install
+ adapter.** `.codex-plugin/plugin.json` and `plugins/codex/.codex-plugin/plugin.json`
+ are versioned manifests; `codex-json` session import already exists. `install/codex.md`
+ documents a manual `codex mcp add ...` procedure and is currently listed in the
+ conformance test's `PIPELINE_HOSTED_DOCS` exception map. Verified on a live machine:
+ `codex mcp add|remove|list --json` works and `~/.codex/config.toml` holds
+ `[mcp_servers.<name>]` with `command` and `args`. The `copilot-cli` adapter is the
+ existing precedent for a subprocess-primary adapter with an injectable runner and a
+ file-merge fallback.
+
+6. **There is no committed project-level tier feeding install and hook generation, and
+ no resolver anywhere reports where a value came from.** Correction to the original
+ task text: a committed vault-level config DOES exist β€” `<vault>/Brain/_brain.yaml`,
+ read by `src/core/brain/policy/load.ts` with a per-block safe-loader family. What is
+ missing is (a) install/hook generation never reads it, and (b) `ConfigDiscovery` is
+ `{path, exists, data}` with no provenance, so an rc value that silently loses to a
+ stale user-level key is indistinguishable from one that won. The single choke point
+ is `envOrConfig(env, config, envKey, configKey)` in `src/core/validate.ts:100-111`,
+ which drives roughly 55 search keys plus `search_db_path`.
+
+7. **State surfaces are scattered with no inventory.** Roughly fourteen surfaces under
+ `<vault>/.open-second-brain/` (search index + its query-cache table + writer lock,
+ secret custody, ingest manifest, ingest checkpoints, install manifest, protect
+ manifest, maintenance lease, maintenance journal, hook audit, watchdog audit, inject
+ fail-open cache, aider context artifact) and roughly twenty under `<vault>/Brain/`,
+ each resolved by its own function. There is no single command answering "where does
+ every state surface actually live, is it reachable, and what override put it there",
+ no digest-bound migrate/rollback, and no graceful drain: `src/mcp/http.ts` has no
+ signal handling at all and `HttpServerHandle.close` does not await in-flight requests.
+ Prior art that must be extended rather than duplicated: `OUT_OF_VAULT_STATE` in
+ `src/core/install/ownership.ts:125-259` is already a declared population of
+ out-of-vault state with a sweep test demanding every home/XDG/temp-rooted path builder
+ in the tree be attributed to a row or excused with a written reason, and
+ `SearchIndexVerdict` there is already a `inside_vault | outside_vault | unchecked`
+ plus path plus reason tri-state.
+
+8. **The MCP and CLI maintenance surfaces have drifted apart two releases running.**
+ `brain_dream` action=step returns `runDreamStep(vault, step)` with no safeguard while
+ every sibling branch builds one; `scanBrain(vault)` and `runHealEnrichment(vault)`
+ accept no options at all. `brain_maintenance` has no per-task retry while the CLI has
+ `--retry`, and the lane's own streak refusal message tells the caller to use `--retry`
+ β€” a flag an MCP caller cannot reach. Root cause: the four lane task names are not a
+ closed vocabulary. `MaintenanceTask.name` is a bare `string` and the names live as
+ inline literals in two independent lists.
+
+9. **Session parsing is monolithic and the transcript corpus has no way out.** All five
+ session adapters do `readFileSync` then `split("\n")`, so peak memory is about twice
+ the file size before the first turn is yielded, and `async *iterate` yields lazily
+ over an already-materialised array. Autodetect reads the whole file a second time.
+ Separately, `export type ExportFormat = "json" | "llms-txt"` at
+ `src/core/brain/export.ts:83` is declared and never imported β€” the CLI verb inlines
+ the two literals β€” and there is no path from recorded session transcripts to any
+ machine-consumable dataset.
+
+The design question this brainstorm must answer is the shape of the shared substrate:
+where per-runtime and per-state-surface knowledge is declared, who reads it, and how it
+is proved. Nine units either collapse onto one honest abstraction or become nine
+independent additions that will drift apart the same way items 3, 6 and 8 already did.
+
+# Project context
+
+Open Second Brain β€” TypeScript on Bun, a CLI (`o2b`) plus two MCP servers over an
+Obsidian-compatible Markdown vault. The vault is replicated by Syncthing; there is no
+git transport and every `git` invocation under `src/` is read-only.
+
+Recent commits:
+```
+b49af81e feat: a label is not a boundary (v1.49.0) (#166)
+280469d2 feat: nothing runs unwatched (v1.48.0) (#165)
+aa818084 feat: wiring what exists (v1.47.0) (#164)
+a6d10dab feat: evidence at the boundary (v1.46.0) (#162)
+29ea0099 fix: the flush that never landed (v1.45.1) (#158)
+8d05a62a feat: silence is not an answer (v1.45.0) (#159)
+34f96b84 fix: reuse and reap Hermes MCP bridges (v1.44.1) (#156)
+3ee1963a feat: what the index already knew (v1.44.0) (#157)
+0ae4b097 feat: provenance at the boundary (v1.43.0) (#154)
+7e6a5672 refactor: module boundaries and the fallbacks behind them (v1.42.0) (#153)
+5ac866eb feat: signals that survive (v1.41.0) (#152)
+0963ef0a feat: no dead ends - every diagnosis names its exit (v1.40.0) (#151)
+f91a698b feat: context integrity gates (v1.39.0) (#150)
+c31a2574 feat: semantic-health baseline watermark (v1.38.0) (#148)
+b0c37977 feat: retrieval quality and context delivery (v1.37.0) (#146)
+842d690f feat: knowledge intake and consolidation (v1.36.0) (#145)
+95dc8577 feat: trusted recall and memory write surface (v1.35.0) (#144)
+426d06f8 fix(vault): parse block-style YAML lists in frontmatter (#142)
+4b8100ca feat: source pipeline integrity and operator tooling (v1.34.0) (#143)
+77513f2b feat: belief lifecycle and decision memory (v1.33.0) (#141)
+```
+
+Related files:
+- `src/core/install/types.ts`, `registry.ts`, `payload.ts`, `payload-equals.ts`,
+ `manifest.ts`, `json-merge.ts`, `identity.ts`, `grok-asset.ts`, `ownership.ts`
+- `src/core/install/adapters/` β€” `_json-mcp.ts`, `cursor.ts`, `gemini-cli.ts`, `kiro.ts`,
+ `opencode.ts`, `copilot-cli.ts`, `grok.ts`, `aider.ts`, `pi.ts`, `generic.ts`, `all.ts`
+- `src/mcp/profiles.ts`, `capabilities.ts`, `tool-contract.ts`, `server.ts`, `http.ts`,
+ `tools.ts`, `coerce.ts`, `brain/admin-tools.ts`, `brain/feedback-tools.ts`, `brain/shared.ts`
+- `src/core/brain/sessions/` β€” `types.ts`, `registry.ts`, `import.ts`, and five adapters
+- `src/core/discipline/transcripts/` β€” `types.ts`, `claude-code.ts`, `codex.ts`, `cursor.ts`, `index.ts`
+- `src/core/brain/ingest/content-manifest.ts`, `checkpoint.ts`
+- `src/core/brain/export.ts`, `src/cli/brain/verbs/export.ts`
+- `src/core/egress/guard.ts`, `src/core/egress/registry.ts`
+- `src/core/integrity/digest.ts`, `src/core/brain/dedup-hash.ts`
+- `src/core/config.ts`, `src/core/validate.ts`, `src/core/types.ts`,
+ `src/core/brain/policy/load.ts`, `src/core/brain/paths.ts`, `src/core/brain/path-constants.ts`
+- `src/core/brain/safeguard.ts`, `progress.ts`, `dream-step.ts`, `dream-scan.ts`,
+ `heal-run.ts`, `maintenance/lane.ts`, `maintenance/journal.ts`
+- `src/core/doctor.ts`, `src/core/doctor-readiness.ts`, `src/core/maintenance/ensure-current.ts`
+- `src/cli/main.ts`, `src/cli/command-manifest.ts`, `src/cli/install/`,
+ `src/cli/brain/verbs/` (`maintenance.ts`, `import-session.ts`, `upgrade.ts`, `doctor.ts`)
+- `tests/core/architecture/` β€” `egress-census.test.ts`, `write-site-census.test.ts`,
+ `destructive-site-census.test.ts`, `progress-census.test.ts`,
+ `verdict-vocabulary-census.test.ts`, `import-cycles.test.ts`
+- `tests/docs/install-verify-conformance.test.ts`, `tests/cli/manifest-completeness.test.ts`,
+ `tests/cli/progress-emitter-census.test.ts`, `tests/cli/help-surface-parity.test.ts`
+
+Conventions:
+- Closed vocabulary house pattern: a frozen object, a union derived from it, a frozen
+ members array, and a type guard. Used correctly by `SESSION_ADAPTER_ID`
+ (`src/core/brain/sessions/types.ts:37-60`), `TOOL_SCOPE`, `MAINTENANCE_VERDICT`,
+ `OPERATION`. The install subsystem uses a weaker `Set`-plus-conditional-type form with
+ no guard and has no target-id vocabulary at all.
+- Census and ratchet tests derive their population STRUCTURALLY from source or from a
+ live registry, never from a hand-written list. Exceptions are declared in a frozen map
+ with a written reason of a minimum length. A census that found nothing must fail. A
+ count that has drifted is pinned as an equality, not a floor. There is a shared source
+ lexer at `tests/helpers/source-lexer.ts`.
+- Install verification works by RE-CONSTRUCTION, never a stored hash: same input yields
+ byte-identical output, which is what makes `--apply` idempotent and lets `verify()`
+ detect drift. `expectedPayloadFromEnv(env)` recomputes from `InstallEnv` alone.
+- Mutating commands preview by default. The canonical ladder is
+ `src/cli/brain/verbs/upgrade.ts`: `--dry-run` and `--apply` mutually exclusive,
+ `--check` exits 2 when work pends, `--apply` refused without `--yes` when `--json` or
+ a non-TTY, a TTY prompt accepting only y/yes, and a pre-apply snapshot.
+- Anything leaving the vault passes `redactForEgress` and carries a declared entry in
+ `EGRESS_SITES`; the egress census counts guard calls against destination declarations
+ in the same module.
+- Any options type that accepts a `Safeguard` must also accept a `ProgressSink`, or
+ carry a written exemption. Progress stage names are identifiers, never prose.
+- The kernel calls no model. LLM work leaves through a `needs-llm-step` envelope.
+- Public artifacts use the full project name, never an abbreviation.
+
+Constraints:
+- No new external dependencies.
+- No misleading fallbacks. A path that silently does nothing, or degrades without saying
+ so, is forbidden; an error must be explicit and name its remedy. No stubs.
+- No hardcoded natural-language word lists of any kind. Language-specific behaviour must
+ be expressed structurally.
+- Do not break existing public CLI or MCP surfaces. Existing generated install output
+ must stay byte-identical unless a change is deliberate and pinned by an updated
+ expected-output block.
+- Adding an argument to the generated MCP payload is only safe if the new dimension is
+ derivable from `InstallEnv`, because `verify()` recomputes the expected payload from
+ `InstallEnv` alone and would otherwise report permanent drift.
+- `Operation` (used by both the safeguard and the progress rail) is a closed enum;
+ adding a long-running operation means adding a member and satisfying both censuses.
+- The work must land as separable atomic units on one branch, each independently
+ testable, because they ship as one release.
+- SOLID, KISS, DRY. Anything that can be lifted into a shared local or module constant
+ should be.
+
+# Required output format
+
+Produce exactly 3 distinct architectural variants. For each variant:
+
+### Variant N: <short name>
+- **Approach**: 2-3 sentences describing the variant.
+- **Trade-offs**: bullet list of pros and cons.
+- **Complexity**: small | medium | large
+- **Risk**: low | medium | high
+
+After the three variants, add exactly one recommendation:
+
+### Recommended: Variant N
+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.
+
+Output nothing outside of these sections.
diff --git a/docs/brainstorm/what-the-machine-already-has/design.md b/docs/brainstorm/what-the-machine-already-has/design.md
new file mode 100644
index 00000000..44ff564e
--- /dev/null
+++ b/docs/brainstorm/what-the-machine-already-has/design.md
@@ -0,0 +1,195 @@
+# What the machine already has - one declaration per fact about the host
+
+**Status:** draft
+**Author:** claude-dev-agent (via feature-release-playbook)
+**Audience:** implementation
+
+## Problem statement
+
+Nine tracker items were picked together because reconnaissance against v1.49.0 showed
+they are one question seen from nine sides: what does Open Second Brain know about the
+machine it is installed on, where is that knowledge declared, and what proves it is true.
+Three of the nine are not missing features at all - they are contracts already declared
+in the type system with nothing behind them, which is the previous release's theme
+surviving into this one. `InstallAdapter.sessionPaths?()` has zero implementations and
+zero call sites. `export type ExportFormat` is never imported; the CLI inlines its two
+literals. The four maintenance lane task names are not a vocabulary at all - they are
+inline string literals in two independent lists, which is why the CLI and MCP surfaces
+have drifted apart two releases running.
+
+## Scope
+
+Eleven atomic units across nine tracker items.
+
+- A closed `INSTALL_TARGET_ID` vocabulary and a `RUNTIME_FACTS` population: one row per
+ agent runtime carrying its tool ceiling, its declared tool profile, the session
+ adapter it maps to, where that runtime stores session logs, and how a host binary can
+ be probed.
+- A committed vault-level configuration tier that install and hook generation read, with
+ a `CONFIG_ORIGIN` vocabulary so every resolved value reports which layer produced it.
+- A ceiling-aware tool profile baked into the generated MCP payload for hosts that
+ publish a per-workspace limit, with the advertised count pinned under the ceiling by a
+ test that cannot pass vacuously.
+- A per-adapter friction comparison and a keyless host probe that replaces the blanket
+ "no MCP handshake attempted" with either a real answer or a named skip reason.
+- A `LANE_TASK` vocabulary, a cooperative deadline on `brain_dream` action=step, per-task
+ retry on `brain_maintenance`, and a CLI-to-MCP parity census derived from source.
+- A `STATE_SURFACES` population and an inventory reporting, per surface, its resolved
+ path, reachability, and the override that placed it there.
+- A digest-bound `state migrate` / `state rollback` pair on the established dry-run
+ ladder, and a graceful drain on both MCP transports.
+- A Codex CLI install adapter on the `copilot-cli` subprocess-primary precedent.
+- Machine-wide session-log discovery with a found-vs-imported status report.
+- A line-streaming session reader replacing whole-file reads in all five adapters.
+- A session-transcript dataset export riding `ExportFormat` and the egress registry.
+
+## Out of scope
+
+- A `{action, args}` dispatch tool. `catalog` plus `tool_hydrate` already answers the
+ token-overhead half without putting verbs behind an envelope no capability report can
+ enumerate. Build it only if a host ceiling is low enough that the smallest bounded
+ profile does not fit; none is.
+- `.cursor/rules/*.mdc` context delivery. It is a workaround for a Cursor-side race in
+ hook `additional_context`; a workaround for a bug that may be fixed is a permanent
+ maintenance cost with no expiry, and the race has not been re-confirmed.
+- Adapters for Cline, Continue.dev, ForgeCode, Goose, Antigravity, Pi and Copilot-CLI
+ ingest. Their gate is confirming an external product's config path and registration
+ shape, which is not a code question. Codex is included precisely because that gate is
+ already satisfied in this repository.
+- The three extra session formats named upstream (OpenClaw, ChatGPT and Claude.ai
+ `conversations.json`). Separable from discovery, and discovery must not wait on them.
+- Two-tier extraction routing and blog/feed ingestion. The privacy wall - deciding what a
+ cheap triage model may see - is a design decision, not a routing detail.
+- Widening `envOrConfig` itself across its ~55 call sites. See the design decisions.
+
+## Chosen approach
+
+Variant 2 of the consultant's three: two closed registries keyed by their own honest key
+spaces, plus a provenance dimension cutting across both. Variant 1's single table unions
+a tool ceiling, a TOML config path and a writer-lock file into one row type that
+degenerates into a bag of optionals - the exact shape that produced the dead
+`sessionPaths?()` seam. Variant 3's owner-local obligation is the right instinct for
+adapters and structurally cannot answer the two inventory questions, because the state
+surfaces nobody tracks - the search index, the maintenance lease, the hook audit - have
+no owning adapter to declare them.
+
+One graft from Variant 3 is adopted: `RUNTIME_FACTS` carries a probe specification, so a
+host that can answer about its own registration is asked rather than assumed. What is
+declared and what is measured stay distinct columns; neither is allowed to stand in for
+the other.
+
+## Design decisions
+
+- **`envOrConfig` gains a sibling, not a signature change.** A provenance-returning
+ `resolveWithOrigin` is added and `envOrConfig` delegates to it, returning `.value`.
+ Zero call sites change. The consultant flagged a fifty-five-site mechanical sweep as
+ the largest risk in the recommended variant, and it buys nothing: the callers that need
+ provenance are the install, hook-generation and inventory surfaces, and they are few.
+
+- **`unknown` is not `unbounded`.** `TOOL_CEILING_KIND` has three members. A host nobody
+ has checked reports `unknown` with a reason and gets no profile baked in - the current
+ behaviour - but the capability report and the install check say the ceiling is
+ unchecked rather than staying silent. Collapsing `unknown` into `unbounded` would be
+ the misleading fallback this project forbids, one layer up from the fail-open profile
+ selection that made the original card true.
+
+- **The profile is declared per host, not computed.** `RUNTIME_FACTS` names the profile
+ and the ceiling side by side, and a census asserts the selected profile's advertised
+ tool count is at or under the ceiling, pinned as an equality so a new tool cannot drift
+ the surface back over the line. A selection algorithm would be cleverer and would move
+ the failure from a review-time diff to a runtime surprise.
+
+- **Reconstruction is preserved by making the new dimension a pure function of what
+ `verify()` already has.** `expectedPayloadFromEnv(env)` recomputes from `InstallEnv`
+ alone, and the JSON adapter body applies its spec's transform to that result, so the
+ target is in scope on both the apply and the verify path. The tool profile is therefore
+ derivable and byte-identical regeneration holds. The vault-level tier is readable from
+ `env.vault` for the same reason.
+
+- **An unreadable vault configuration refuses rather than defaults.** v1.49.0 established
+ that an unreadable config resolves to the strict fallback for readers, and found the
+ one writer wired to that rationale by mistake. Generated install and hook content is a
+ writer: it cannot infer an operator's intent from a file it could not parse, so it names
+ the parse failure and stops.
+
+- **State surfaces extend the ownership population rather than starting a parallel one.**
+ `OUT_OF_VAULT_STATE` already declares out-of-vault state with a source sweep demanding
+ every home, XDG or temp-rooted path builder be attributed to a row or excused with a
+ written reason, and `SearchIndexVerdict` is already a tri-state-with-reason. The
+ in-vault population is the missing half of the same instrument, and the two render
+ through one value with two renderings, never two hand-written copies.
+
+- **`sessionPaths()` becomes required, but its return type is corrected first.** Its
+ orphan `format` union is the only occurrence of those literals in the tree and is
+ disjoint from the live `SESSION_ADAPTER_ID` vocabulary. It is replaced by that
+ vocabulary rather than a sixth one, and the roots come from `RUNTIME_FACTS` so
+ `src/core/discipline/transcripts/` and `src/core/brain/sessions/` stop knowing
+ different halves of the same fact.
+
+- **Discovery reports coverage; it does not import by default.** A bare invocation
+ reports what would import. The privacy posture of the existing importer is matched, not
+ relaxed: redaction before write, no tool payloads in pages.
+
+- **The lane vocabulary is the fix; the two parameters are consequences.** Adding
+ `retry_tasks` to the MCP tool without closing the vocabulary would leave the same two
+ inline lists free to disagree on the next addition. The parity census derives the CLI
+ flag set from source and the MCP property set from the tool definition and requires
+ each to map or carry a declared exemption, so a third divergence fails a test rather
+ than shipping.
+
+## File changes
+
+New:
+- `src/core/runtime/host-facts.ts` - `INSTALL_TARGET_ID`, `TOOL_CEILING_KIND`,
+ `RUNTIME_FACTS`, accessors. A leaf module; importing it back from the install
+ aggregator would close a cycle the architecture ratchet gates.
+- `src/core/state/surfaces.ts` - `STATE_SURFACE_ID`, `STATE_SURFACES`,
+ `inventoryStateSurfaces`.
+- `src/core/state/migrate.ts` - digest manifest, plan, apply, rollback.
+- `src/core/install/adapters/codex.ts` - Codex adapter with injectable runner.
+- `src/core/brain/sessions/discover.ts` - root walk and found-vs-imported classification.
+- `src/core/brain/sessions/read-lines.ts` - streaming line reader.
+- `src/core/brain/export-transcripts.ts` - dataset renderer.
+- `src/cli/brain/verbs/state.ts`, `src/cli/state-render.ts`.
+- Tests mirroring each, plus `tests/core/architecture/host-facts-census.test.ts`,
+ `tests/core/architecture/state-surface-census.test.ts`,
+ `tests/mcp/maintenance-parity-census.test.ts`.
+
+Modified:
+- `src/core/install/types.ts` - `sessionPaths` required, return type retyped, target id
+ typed from the new vocabulary.
+- `src/core/install/adapters/_json-mcp.ts`, `cursor.ts`, `opencode.ts`, `grok.ts`,
+ `copilot-cli.ts`, `all.ts`, `payload.ts`, `payload-equals.ts`, `ownership.ts`.
+- `src/core/validate.ts`, `src/core/config.ts`, `src/core/brain/policy/load.ts`.
+- `src/core/brain/safeguard.ts` (one new `Operation` member), `dream-step.ts`,
+ `dream-scan.ts`, `heal-run.ts`, `maintenance/lane.ts`.
+- `src/mcp/brain/feedback-tools.ts`, `admin-tools.ts`, `capabilities.ts`, `http.ts`,
+ `stdio.ts`, `tools.ts`.
+- `src/core/brain/sessions/` - `types.ts`, `registry.ts`, `import.ts` and five adapters.
+- `src/core/brain/export.ts`, `src/cli/brain/verbs/export.ts`, `src/core/egress/registry.ts`.
+- `src/core/discipline/transcripts/index.ts` - roots read from `RUNTIME_FACTS`.
+- `src/cli/main.ts`, `command-manifest.ts`, `brain/help-text.ts`, `install/`.
+- `docs/mcp.md`, `docs/cli-reference.md`, `install/codex.md`, `install/cursor.md`,
+ `README.md`, `CHANGELOG.md`.
+
+## Risks and open questions
+
+- The generated Cursor payload changes. Any operator with an existing Cursor install sees
+ drift on the next `--check` until they re-apply. The drift message must name the profile
+ as the cause; a silent re-apply would hide a surface narrowing from the operator.
+- Making `sessionPaths` required is a compile-time break for every adapter in one commit.
+ It lands in the discovery unit together with all ten implementations, so no
+ intermediate commit is broken, but it cannot be split further. A runtime that stores no
+ session logs - `generic`, `aider`, `pi` - returns `null`, which is a stated answer
+ rather than an absent member.
+- A new `Operation` member must satisfy both the safeguard resolver and the progress
+ emitter census, including a drivable entry point with a fixture. If the discovery sweep
+ turns out too fast to be worth a progress rail, the honest outcome is no safeguard and
+ no sink rather than an emitter that fires once.
+- `state migrate` moves live state. It refuses on symlinks, special files, destination
+ conflicts, insufficient space and reserved namespaces before it commits anything, and
+ the writer lock must be observed - a migration racing a reindex is the one failure that
+ digests cannot undo.
+- The transcript dataset export is a new bulk egress path opened immediately after a
+ release spent on egress. It enters through `ExportFormat` and the census, never as a
+ standalone pipeline.
diff --git a/docs/brainstorm/what-the-machine-already-has/plan.md b/docs/brainstorm/what-the-machine-already-has/plan.md
new file mode 100644
index 00000000..f227e85c
--- /dev/null
+++ b/docs/brainstorm/what-the-machine-already-has/plan.md
@@ -0,0 +1,206 @@
+# What the machine already has - implementation plan
+
+Eleven atomic units across nine tracker items, on one branch, each its own commit.
+Every unit is test-first: the test is written, run, and observed failing for the expected
+reason before the implementation exists.
+
+Tracker mapping:
+
+| unit | tracker item |
+| --- | --- |
+| 1, 3, 4 | t_9f5b974b, t_367a31c1 |
+| 2 | t_85cc975b |
+| 5 | t_9b209fbe |
+| 6, 7 | t_53e77d0a |
+| 8 | t_553ce8f6 |
+| 9 | t_3745dd4b |
+| 10 | t_7c89c306 |
+| 11 | t_2866fef9 |
+
+## Tasks
+
+### Task 1: Runtime facts substrate
+- **Files**: `src/core/runtime/host-facts.ts` (new); `src/core/install/types.ts`;
+ `tests/core/runtime/host-facts.test.ts` (new);
+ `tests/core/architecture/host-facts-census.test.ts` (new);
+ `tests/core/architecture/verdict-vocabulary-census.test.ts`
+- **Acceptance**: `INSTALL_TARGET_ID` / `InstallTargetId` / `INSTALL_TARGET_IDS` /
+ `isInstallTargetId` follow the house closed-vocabulary pattern and are enrolled in the
+ vocabulary census. `TOOL_CEILING_KIND` has exactly three members and `unknown` carries
+ a reason. A census derives the target population from `registerAllAdapters().targets()`
+ and asserts it equals the `RUNTIME_FACTS` key set in both directions; the census fails
+ if the population is empty. `InstallAdapter.target` is typed `InstallTargetId`.
+- **Depends on**: none
+
+### Task 2: Committed vault tier and config provenance
+- **Files**: `src/core/validate.ts`; `src/core/config.ts`; `src/core/brain/policy/load.ts`;
+ `src/core/brain/policy/blocks/install.ts` (new); `src/core/install/payload.ts`;
+ `src/core/install/grok-asset.ts`; `tests/core/config-origin.test.ts` (new);
+ `tests/core/brain/policy/install-block.test.ts` (new)
+- **Acceptance**: `CONFIG_ORIGIN` is a closed vocabulary (`env`, `user-config`,
+ `vault-config`, `default`). `resolveWithOrigin` returns value plus origin and
+ `envOrConfig` delegates to it with no call-site change - proved by a test that asserts
+ the two agree on every branch. An `install:` block in `<vault>/Brain/_brain.yaml`
+ supplies `hook_timeout_seconds` and `tool_profile`; an env var beats it, a user-level
+ key loses to it, and each resolution reports its origin. An unreadable or malformed
+ vault config makes install and hook generation refuse by name rather than default.
+ Regeneration from identical inputs stays byte-identical.
+- **Depends on**: none
+
+### Task 3: Ceiling-aware tool profile in the generated payload
+- **Files**: `src/core/install/payload.ts`; `src/core/install/payload-equals.ts`;
+ `src/core/install/adapters/_json-mcp.ts`, `cursor.ts`, `opencode.ts`, `grok.ts`,
+ `copilot-cli.ts`; `src/mcp/capabilities.ts`; `install/cursor.md`;
+ `tests/core/install/tool-ceiling.test.ts` (new); `tests/mcp/profiles.test.ts`
+- **Acceptance**: for every target whose `RUNTIME_FACTS` row declares a ceiling, the
+ generated `full` entry carries `--tool-profile <name>` and the advertised tool count
+ under that profile is at or under the ceiling - asserted with the real
+ `buildToolTable` count, pinned as an equality, and driven by the derived population so
+ a new target with a ceiling cannot avoid the check. A target with an `unknown` ceiling
+ gets no profile and `second_brain_capabilities` reports the ceiling as unchecked with
+ its reason. `verify()` still reconstructs the expected payload from `InstallEnv` alone
+ and reports no drift on a fresh apply. `install/cursor.md`'s expected-output block is
+ updated to whatever `verify()` now prints, and
+ `tests/docs/install-verify-conformance.test.ts` is the check that the two agree.
+- **Precedence, stated once**: `OPEN_SECOND_BRAIN_MCP_TOOL_PROFILE` beats an `install:`
+ block `tool_profile` in `<vault>/Brain/_brain.yaml`, which beats the profile declared
+ on the `RUNTIME_FACTS` row, which beats no profile at all. Each resolution reports its
+ `CONFIG_ORIGIN`, and a test drives all four layers.
+- **Depends on**: 1, 2
+
+### Task 4: Adapter friction diff and keyless host probe
+- **Files**: `src/core/install/friction.ts` (new); `src/core/install/types.ts`;
+ `src/cli/install/install.ts`; `src/cli/install/render.ts`;
+ `src/cli/command-manifest.ts`; `docs/cli-reference.md`;
+ `tests/core/install/friction.test.ts` (new); `tests/cli/install-friction.test.ts` (new)
+- **Acceptance**: `o2b install --friction [--base <t> --compare <t>] [--json]` renders one
+ row per capability dimension per target, derived from `RUNTIME_FACTS` and the adapter
+ registry rather than a hand-written table, and a diff form names which dimensions
+ differ. For a target declaring a host probe, `verify()` returns either a real
+ registration-shape answer or a named skip reason; the blanket
+ "no MCP handshake attempted" note survives only where no probe is declared, and a test
+ asserts that string no longer appears for probe-bearing targets. The probe runner is
+ injectable and both branches are driven.
+- **Depends on**: 1
+
+### Task 5: Lane vocabulary, step deadline, maintenance retry, parity census
+- **Files**: `src/core/brain/maintenance/lane.ts`; `src/core/brain/dream-step.ts`;
+ `src/core/brain/dream-scan.ts`; `src/core/brain/heal-run.ts`;
+ `src/mcp/brain/feedback-tools.ts`; `src/mcp/brain/admin-tools.ts`;
+ `src/cli/brain/verbs/maintenance.ts`; `docs/mcp.md`; `docs/cli-reference.md`;
+ `tests/mcp/maintenance-parity-census.test.ts` (new);
+ `tests/mcp/long-running-tools.test.ts`; `tests/cli/brain-maintenance.test.ts`;
+ `tests/core/brain/maintenance/maintenance.test.ts`
+- **Acceptance**: `LANE_TASK` is a closed vocabulary with a guard, and both the CLI task
+ list and the MCP task list are built from it - a source census asserts neither module
+ contains a bare lane-name literal. `runDreamStep(vault, step, opts)` accepts a
+ safeguard and a progress sink, `scanBrain` and `runHealEnrichment` honour checkpoints,
+ and a jumping-clock test proves `brain_dream action=run step=<x>` trips the deadline
+ and names the operation. `brain_maintenance` accepts `retry_tasks`, `busy_minutes`,
+ `busy_threshold` and `limit`; an unknown retry name is refused by name, matching the
+ CLI. The `force` description names every gate it disables. A parity census derives the
+ CLI flag set from the verb's flag table and the MCP property set from the tool
+ definition and requires each to map or carry a declared exemption with a written
+ reason; it fails if either population is empty. The `docs/mcp.md` deadline row for
+ `step` no longer reads **none**.
+- **Depends on**: none
+
+### Task 6: State surface inventory
+- **Files**: `src/core/state/surfaces.ts` (new); `src/core/install/ownership.ts`;
+ `src/core/doctor.ts`; `src/mcp/tools.ts`; `src/cli/brain/verbs/state.ts` (new);
+ `src/cli/state-render.ts` (new); `src/cli/main.ts`; `src/cli/command-manifest.ts`;
+ `tests/core/state/surfaces.test.ts` (new);
+ `tests/core/architecture/state-surface-census.test.ts` (new)
+- **Acceptance**: `STATE_SURFACE_ID` is a closed vocabulary; every row carries a
+ resolver, tier, override env key, override config key, whether it carries memory, and
+ a written reason. `inventoryStateSurfaces(vault)` returns per-surface resolved path,
+ reachability as a tri-state with a reason, and the origin that placed it, rendered
+ through one value with two renderings (`o2b state status` and the `vault_health`
+ field). A source census sweeps for path builders under the derived-store directory and
+ demands each be attributed to a row or excused with a reason of a minimum length; it
+ fails if the population is empty, and its count is pinned as an equality.
+- **Depends on**: 2
+
+### Task 7: State migrate, rollback, and graceful drain
+- **Files**: `src/core/state/migrate.ts` (new); `src/mcp/http.ts`; `src/mcp/stdio.ts`;
+ `src/cli/brain/verbs/state.ts`; `src/cli/main.ts`; `docs/cli-reference.md`;
+ `tests/core/state/migrate.test.ts` (new); `tests/mcp/http-drain.test.ts` (new)
+- **Acceptance**: `o2b state migrate --to <dir>` plans by default and mutates only under
+ `--apply --yes`, refused non-interactively without `--yes`, following the
+ `brain upgrade` ladder. The manifest binds source type, canonical roots, the path
+ inventory, byte counts and SHA-256 digests through `sha256Hex` and `canonicalJson`. It
+ refuses before committing on a symlink, a special file, a destination conflict,
+ insufficient space, a reserved namespace, or a held writer lock. `o2b state rollback`
+ restores only manifest-bound content whose digest still matches and refuses to delete
+ anything that changed after the migration, naming each. On SIGTERM or SIGINT the HTTP
+ transport stops accepting, reports `draining` on `/health`, awaits in-flight requests
+ to a bounded deadline, then closes - proved by a test holding a request open across the
+ signal - and the exit hooks that checkpoint the search index and release locks still
+ run afterwards. The drain deadline defaults to ten seconds and is overridable; when it
+ expires, the still-open requests are named on stderr rather than dropped silently.
+- **Depends on**: 6
+
+### Task 8: Codex CLI install adapter
+- **Files**: `src/core/install/adapters/codex.ts` (new); `src/core/install/adapters/all.ts`;
+ `src/core/runtime/host-facts.ts`; `install/codex.md`;
+ `tests/core/install/adapters/codex.test.ts` (new);
+ `tests/docs/install-verify-conformance.test.ts`
+- **Acceptance**: the adapter registers both server keys through an injectable
+ `CodexRunner` driving `codex mcp add|remove|list --json`, with a TOML section merge into
+ `~/.codex/config.toml` as the fallback when the binary is absent; unrelated sections and
+ the existing `[plugins."..."]` and `[marketplaces....]` blocks survive byte-for-byte.
+ `detect`, `plan`, `apply`, `uninstall` and `verify` are driven on both branches, apply
+ is idempotent, and `install/codex.md` carries an expected-output block matching
+ `verify()`. Its `PIPELINE_HOSTED_DOCS` exemption is removed, and the conformance test
+ binds it like any other adapter.
+- **Depends on**: 1, 4
+
+### Task 9: Machine-wide session discovery and coverage status
+- **Files**: `src/core/brain/sessions/discover.ts` (new); `src/core/brain/sessions/types.ts`;
+ `src/core/install/types.ts` and all ten adapters (`sessionPaths` implementations);
+ `src/core/discipline/transcripts/index.ts`; `src/cli/brain/verbs/import-session.ts`;
+ `src/cli/brain/help-text.ts`; `src/cli/command-manifest.ts`;
+ `src/core/brain/safeguard.ts`; `tests/core/brain/sessions/discover.test.ts` (new);
+ `tests/cli/session-discovery.test.ts` (new); `tests/cli/progress-emitter-census.test.ts`
+- **Acceptance**: `sessionPaths()` is a required member returning roots from
+ `RUNTIME_FACTS` and a `SessionAdapterId`; a runtime that stores no session logs
+ (`generic`, `aider`, `pi`) returns `null`, which is a stated answer rather than an
+ absent member. The orphan
+ `"claude-jsonl" | "codex-json" | "cursor-sqlite"` union is gone from the tree.
+ `o2b brain import-session --discover` reports what would import without importing;
+ `--status` reports per runtime the found count, the imported count and the gap, keyed
+ by content hash in a manifest under the derived-store directory so an unchanged file is
+ reported as imported without re-parsing. `--discover --all` imports the gap. Roots are
+ read once: `src/core/discipline/transcripts/` consumes the same declaration, proved by
+ a test that changes a root in `RUNTIME_FACTS` and observes both consumers move. If the
+ sweep carries a safeguard it carries a progress sink and satisfies the emitter census
+ with a drivable entry point; if it carries neither, that is stated in the module.
+- **Depends on**: 1, 8
+
+### Task 10: Streaming session parse
+- **Files**: `src/core/brain/sessions/read-lines.ts` (new); five session adapters;
+ `src/core/brain/sessions/import.ts`; `tests/core/brain/sessions/read-lines.test.ts` (new);
+ `tests/core/brain/sessions/streaming-memory.test.ts` (new)
+- **Acceptance**: all five adapters consume a shared line reader that yields without
+ materialising the whole file, and autodetect reads only the first chunk instead of the
+ whole file a second time. A test drives a synthetic session larger than the previous
+ whole-file path would comfortably hold and asserts peak retained bytes stay bounded,
+ and every existing session-import test still passes with byte-identical vault output.
+ `ImportSessionOptions` gains a safeguard and a progress sink together, or neither.
+- **Depends on**: 9
+
+### Task 11: Session transcript dataset export
+- **Files**: `src/core/brain/export.ts`; `src/core/brain/export-transcripts.ts` (new);
+ `src/cli/brain/verbs/export.ts`; `src/core/egress/registry.ts`;
+ `src/cli/brain/help-text.ts`; `docs/cli-reference.md`;
+ `tests/core/brain/export-transcripts.test.ts` (new);
+ `tests/cli/brain-export.test.ts`; `tests/core/architecture/egress-census.test.ts`
+- **Acceptance**: `ExportFormat` becomes a closed vocabulary with a guard and is the
+ single dispatch - a source test asserts the CLI verb no longer inlines format literals.
+ A transcript format emits JSONL conversation records built from the streaming reader,
+ filterable by runtime and date range. Every branch calls `redactForEgress` before
+ producing bytes, the guard-call count meets the destination-declaration count in the
+ module, the site is declared in `EGRESS_SITES` with a written reason, and a refused
+ verdict writes nothing and exits non-zero. A record carrying a secret-shaped identifier
+ is refused by name in a test.
+- **Depends on**: 10
diff --git a/docs/brainstorm/what-the-machine-already-has/variants.md b/docs/brainstorm/what-the-machine-already-has/variants.md
new file mode 100644
index 00000000..87aa906f
--- /dev/null
+++ b/docs/brainstorm/what-the-machine-already-has/variants.md
@@ -0,0 +1,107 @@
+# What the machine already has - variant audit trail
+
+## Consultant run
+
+- **Primary consultant**: `claude` (Claude Code), one run, exit 0, well inside the
+ five-minute budget. Three parseable variants and one recommendation returned, so the
+ Codex fallback was not invoked.
+- **Prompt**: `cli-output/prompt.md`
+- **Raw output**: `cli-output/claude.md`
+
+The prompt carried the nine tracker items as reconnaissance findings against the live
+source rather than as their filed text, because verification had already falsified part
+of three of them: a committed vault-level configuration does exist, the tool-profile
+mechanism does exist, and the measured tool count is 110 rather than the 90 on the card.
+Asking for variants against the filed text would have produced designs for a repository
+that does not exist.
+
+## Variants, verbatim
+
+### Variant 1: One host-facts table
+
+- **Approach**: Introduce a single frozen population β€” `HOST_FACTS` β€” keyed by a new closed `INSTALL_TARGET_ID` vocabulary in the house form (frozen object, derived union, members array, guard), where each row carries everything the project claims to know about one runtime: tool-surface ceiling, config file location and format, install mechanism (json-merge / subprocess), session-log roots, and the state surfaces that runtime causes to exist. State surfaces (item 7) are folded in as rows of the same table under a synthetic `vault` target, so `OUT_OF_VAULT_STATE` becomes a projection of `HOST_FACTS` rather than a sibling list. Every consumer β€” profile selection, install adapters, `sessionPaths()`, session discovery, `second_brain_capabilities`, the inventory verb β€” reads the table and nothing else; a new `tests/core/architecture/host-facts-census.test.ts` derives the population structurally and fails on any row without a reader or any reader with a literal the table could supply.
+- **Trade-offs**:
+ - Pro: maximal DRY β€” one place a maintainer edits when a new runtime appears, and adding Codex (item 5) is one row plus one adapter, not five scattered edits.
+ - Pro: the ceiling fact (item 1) and the log-root fact (item 4) sit on the same row, so `discipline/transcripts` and `brain/sessions` are forced to converge on one declaration instead of two half-truths.
+ - Pro: a single census can prove the whole substrate; the ratchet is one equality count, easy to review.
+ - Con: forces a false union. A tool-surface ceiling, a TOML config path and a writer-lock file are not the same kind of fact; the row type degenerates into a wide bag of optionals, which is exactly the shape that let `sessionPaths?()` (item 3) become declared-and-unread.
+ - Con: state surfaces are keyed by surface identity, not by target identity; grafting them onto a target-keyed table needs a synthetic key that carries no meaning.
+ - Con: one table with one census makes the units less separable β€” several of the nine can only land after the table exists, which weakens the atomic-unit constraint.
+ - Con: says nothing about provenance (item 6); `envOrConfig` still returns a bare value.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 2: Two closed registries and a provenance spine
+
+- **Approach**: Split the substrate along its two real key spaces and add the missing third dimension. `RUNTIME_FACTS` is keyed by a closed `INSTALL_TARGET_ID` and holds per-host contract knowledge (tool ceiling and the resulting profile floor, config format, install mechanism, session-log roots, the `SESSION_ADAPTER_ID` it maps to β€” collapsing item 3's orphan `format` union into the live vocabulary rather than adding a sixth one). `STATE_SURFACES` is keyed by a closed surface id and extends `OUT_OF_VAULT_STATE` in place β€” every row gains a resolver reference, a reachability tri-state modelled on `SearchIndexVerdict`, and the override key that can move it. Cutting across both, `envOrConfig` in `src/core/validate.ts` is widened to return a value plus a declared origin layer (env / user config / `Brain/_brain.yaml` / default), which is what lets install and hook generation finally read the committed vault tier without a stale key winning silently, and what lets a single `o2b doctor`-adjacent inventory verb print, for every runtime and every surface, the value, where it came from, and whether it is reachable.
+- **Trade-offs**:
+ - Pro: each registry has one honest key space and one reader family, so neither row type degenerates into optionals; the house closed-vocabulary pattern applies cleanly to all three.
+ - Pro: provenance is the one addition that makes the other eight verifiable rather than merely declared β€” a census can assert that every fact printed by the inventory names its origin, which is a much stronger ratchet than "row exists".
+ - Pro: separates cleanly into atomic units β€” the ratchet on the origin type, `RUNTIME_FACTS` plus the ceiling-aware profile floor, the Codex adapter, the surface inventory, the maintenance-task vocabulary (item 8), and the streaming session reader (item 9) each land and test independently, in any order after the vocabularies exist.
+ - Pro: `MaintenanceTask.name` and the `ExportFormat` orphan become instances of the same fix β€” a closed vocabulary with one declaration site β€” rather than two unrelated cleanups.
+ - Con: three new shared constructs to review at once; the widened `envOrConfig` touches roughly fifty-five call sites, and a mechanical sweep that large hides mistakes.
+ - Con: two registries can still drift from each other if a future runtime is added to one and not the other; needs a cross-census asserting the mapping between target ids and session adapter ids is total.
+ - Con: still declares rather than measures β€” a wrong ceiling in `RUNTIME_FACTS` is invisible until a user reports dropped tools.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 3: Owner-local obligation plus live probe
+
+- **Approach**: Declare no central table. Instead make the existing `InstallAdapter` interface carry the knowledge as required (not optional) members β€” a limits descriptor, a session-paths descriptor, a state-surfaces contribution β€” so each adapter owns the facts about its own host and TypeScript itself refuses an adapter that omits one, which is the structural fix for `sessionPaths?()` being declared with nothing behind it. Proof shifts from declaration to measurement: extend `tests/docs/install-verify-conformance.test.ts` into a per-adapter friction comparison, and give every adapter a `probe()` on the `copilot-cli` precedent (injectable runner, explicit skip reason when the host binary is absent) so `verify()` stops ending in "no MCP handshake attempted" for hosts that can actually answer. The tool-surface ceiling is then not a hardcoded number but a measured, recorded observation with a declared fallback.
+- **Trade-offs**:
+ - Pro: knowledge lives next to the code that acts on it, which is the strongest anti-drift force available and needs no synthetic key space.
+ - Pro: required interface members are compiler-enforced β€” a stronger guarantee than a census for the completeness half of the problem.
+ - Pro: probing produces facts about the machine actually installed on, which is the only thing that can catch a host whose ceiling changed upstream.
+ - Pro: fits the re-construction convention and keeps generated payloads byte-identical, since probes inform reporting rather than payload content.
+ - Con: does not answer the cross-cutting questions at all. "Which session logs exist and were never imported" and "where does every state surface live" require an inventory across owners; with owner-local declaration only, the reader has to enumerate the registry and can never prove the enumeration is complete for non-adapter surfaces (the search index, the maintenance lease, the hook audit have no adapter to own them).
+ - Con: probes are environment-dependent, so CI must exercise the skip path far more often than the live path, which is how "no handshake attempted" reappears under a new name.
+ - Con: leaves item 6 untouched β€” provenance is not an adapter concern β€” and item 8's vocabulary problem is unaddressed.
+ - Con: mandatory interface members are a breaking change to every existing adapter in one commit, which fights the separable-atomic-units constraint.
+- **Complexity**: medium
+- **Risk**: high
+
+## Recommendation, verbatim
+
+### Recommended: Variant 2
+
+**Rationale**: The nine items drifted for one reason β€” a fact was declared in one place and read in none, or read in two places from two declarations β€” and only Variant 2 attacks both halves, because provenance is what converts "a row exists" into "this value won, from this layer, and here is the surface that proves it reachable". Variant 1's single table is more DRY on paper but unions two key spaces that are genuinely different, reproducing the wide-optional shape that produced item 3 in the first place; Variant 3's owner-local obligation is the right instinct for adapters yet structurally cannot answer the inventory questions in items 4 and 7, since the state surfaces with no owning adapter are exactly the ones nobody tracks. Variant 2 also decomposes best against the hard constraint that this ship as separable atomic units on one branch, and it should still borrow Variant 3's probe as one column of `RUNTIME_FACTS` β€” declared ceiling, measured ceiling, explicit skip reason β€” so the substrate reports what it knows and how it knows it rather than asserting either alone.
+
+## Orchestrator decision
+
+Variant 2 is adopted, with the consultant's own suggested graft and two refinements.
+
+**Adopted as argued.** The nine items drifted for one reason, and the consultant named
+it precisely: a fact was declared in one place and read in none, or read in two places
+from two declarations. Variant 1 is more DRY on paper and unions two genuinely different
+key spaces into one wide-optional row - which is the shape that produced the dead
+`sessionPaths?()` seam this release exists to close, so adopting it would reproduce the
+defect while claiming to fix it. Variant 3's owner-local obligation is right for adapters
+and structurally cannot reach the state surfaces that have no owning adapter, which are
+exactly the ones nobody tracks today.
+
+**Graft taken.** `RUNTIME_FACTS` carries a probe specification, as the recommendation
+suggests. Declared and measured stay separate columns; a declared ceiling is never
+presented as a measurement, and a probe that could not run reports a named skip reason
+rather than an absence.
+
+**Refinement 1 - no fifty-five-site sweep.** The consultant flagged widening
+`envOrConfig` across its call sites as the largest risk in its own recommended variant.
+That risk is avoidable and the sweep buys nothing: a provenance-returning
+`resolveWithOrigin` is added, `envOrConfig` delegates to it and returns `.value`, and no
+existing call site changes. The surfaces that need provenance - install, hook generation,
+the inventory - are few and named.
+
+**Refinement 2 - three ceiling states, not two.** The consultant's rows imply a ceiling
+that is either declared or absent. A host nobody has checked is a third thing, and
+folding it into "unbounded" would be a silent default of exactly the kind this project
+forbids - the same defect one layer up from the fail-open profile selection that made the
+original card true. `TOOL_CEILING_KIND` therefore has `declared`, `unbounded` and
+`unknown`, and `unknown` carries its reason into the capability report.
+
+One thing the consultant got right that is worth recording because it changed the plan's
+shape: its criticism that Variant 2 "still declares rather than measures" is correct and
+is not fully answered. A wrong ceiling in `RUNTIME_FACTS` stays invisible until a user
+reports dropped tools. What the plan can do, and does, is make the declaration falsifiable
+in one direction - a test proves the selected profile fits under the declared ceiling, so
+the pair can never silently disagree with each other, even though neither can prove
+itself against the real host.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 36877018..9330876a 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -10,14 +10,16 @@ Most verbs accept `--vault <path>` and `--config <path>`; the values default to
o2b status Show config / vault status
o2b init Bootstrap the vault profile (idempotent)
o2b init --interactive Guided first-time setup wizard
-o2b install Runtime installer: bare form detects, --target <name> plans, --target <name> --apply writes, --check verifies (see "Exit codes" below)
+o2b install Runtime installer: bare form detects, --target <name> plans, --target <name> --apply writes, --check verifies (see "Exit codes" below); --friction reports what each host costs instead of acting on one
o2b install-cli Symlink o2b and vault-log into ~/.local/bin
o2b-mcp Console-script alias for `o2b mcp`, forwards all flags
o2b doctor Run vault + adapter checks
o2b index Rebuild the Markdown page index
o2b export-config Write a redacted config snapshot
o2b secrets list|status Inspect $secret:NAME references without printing values
-o2b mcp Run the MCP tool server (stdio by default; --transport http requires --api-key); --scope full|writer|catalog, --tool-profile full|writer|catalog|recall|minimal, --probe, --allow-tool, --disable-tool, --max-tools
+o2b mcp Run the MCP tool server (stdio by default; --transport http binds loopback, and --api-key is required only for a non-loopback --host); --scope full|writer|catalog, --tool-profile full|writer|catalog|recall|minimal, --host-target <runtime>, --probe, --allow-tool, --disable-tool, --max-tools
+o2b state status|migrate|rollback
+ Inventory the state this vault holds, move it to another directory, or put it back (see "State surfaces" below)
o2b tool-call Invoke an MCP tool handler from the CLI
o2b help --json Print the command/flag manifest as JSON
o2b completions --shell zsh Print completions for bash|zsh|fish|elvish|nushell|powershell
@@ -53,10 +55,15 @@ unreachable BECAUSE its config drifted, so `--apply` is the first move
and a liveness verdict taken over a wrong config means nothing.
`mcp-unreachable` is reachable only from an adapter that asks a runtime CLI
-whether the servers are registered. Today `copilot-cli` is the one target
-that can produce it - see [`install/copilot-cli.md`](../install/copilot-cli.md).
-Every other adapter verifies off disk, so it can report `ok`, `drift`, or
-`not-installed` but never `mcp-unreachable`.
+whether the servers are registered. Two targets can produce it: `copilot-cli`
+(`copilot mcp list`) and, since v1.50.0, `codex` (`codex mcp list`) - see
+[`install/copilot-cli.md`](../install/copilot-cli.md) and
+[`install/codex.md`](../install/codex.md). Those are exactly the two rows of
+`src/core/runtime/host-facts.ts` that declare a `hostProbe`; every other
+adapter verifies off disk, so it can report `ok`, `drift`, or
+`not-installed` but never `mcp-unreachable`. What a refuting probe MEANS
+differs between the two install modes - see "Host probes and what a verify
+proves" below.
### `o2b doctor` exit codes
@@ -108,6 +115,191 @@ from one that ran and passed. A machine with no codegraph CLI, and a
directory that is not a code project, still both print nothing at all -
those two remain indistinguishable from each other in the doctor's output.
+### `o2b install --friction` (since v1.50.0)
+
+```text
+o2b install --friction Every registered runtime, one row per capability dimension
+o2b install --friction --target <t> One runtime
+o2b install --friction --base <a> --compare <b>
+ Only the dimensions the two answer differently
+```
+
+A REPORT, and it exits `0` whatever it finds: the matrix has no notion of
+a bad answer, only of an honest one. The only non-zero exits are usage
+refusals - an unknown runtime name (the message lists the registered
+ones), `--target` combined with the diff pair, or a diff missing half of
+its pair. `--json` emits the same values under a `friction` key, and the
+diff under `friction_diff`.
+
+Six dimensions, computed from `src/core/runtime/host-facts.ts` and from
+the live adapter rather than from a table maintained beside this page:
+
+| Dimension | What the cell answers |
+| --- | --- |
+| `install-mechanism` | the step kinds the adapter's own plan uses - `json-merge`, `managed-block`, `subprocess`, `file-copy`, `symlink`, `print` - with the artifact paths it writes on the citation line |
+| `tool-ceiling` | the host's published per-workspace tool limit: `declared: N tools` with its source, `unbounded` with its source, or `unknown` with the reason nobody has one |
+| `tool-profile` | the profile the generated registration will actually carry, and which tier of the ladder produced it; `not carried` for a target that writes no MCP command line at all |
+| `verify-evidence` | what a `--check` on this target is evidence OF: `host probe: <command>` for a runtime that can be asked, `configuration comparison only` for one that cannot |
+| `session-transcripts` | the transcript roots this adapter DECLARES, resolved against the machine, with each root's glob and on-disk format. Declared, not measured - whether the directory exists here is a discovery question |
+| `session-parser` | which adapter in this build reads those roots, or `none ships` naming the format nothing parses |
+
+A diff prints only the differing dimensions and COUNTS the rest, because a
+diff that reprints everything is the table the reader already asked to
+skip; the count is what stops the silence reading as "there was nothing
+else to compare".
+
+Three dimensions were considered and deliberately left out rather than
+guessed at, and `src/core/install/friction.ts` records why: whether the
+host takes MCP at all (no structural fact distinguishes a managed block
+that registers servers from one that does not), whether lifecycle hooks
+are wired (one adapter knows, privately), and whether runtime identity is
+stamped (applied at apply time, and no read-only adapter surface carries
+it). Each becomes derivable the day the adapter contract states it.
+
+A cell whose input cannot be resolved reads `unresolved` and carries the
+obstacle. That is how a `Brain/_brain.yaml` this run cannot parse arrives:
+the ladder below refuses rather than defaulting, and a report that turned
+that refusal into a stack trace would stop being total.
+
+### Host probes and what a `verify` proves (since v1.50.0)
+
+An adapter whose runtime publishes a way to ask it now asks. The two
+declared probes are `codex mcp list` and `copilot mcp list`; both are
+keyless, start no model turn, and write nothing. A clean `--check` on
+those targets prints what the host said - beside what the config file
+declares where an artifact backs the registration, and instead of it where
+the host's own registry is the only record.
+
+The blanket note `configuration comparison; no MCP handshake attempted`
+survives only where no probe is declared. Where one IS declared and could
+not run, the check says which obstacle it hit - so a skip is never
+rendered as a handshake:
+
+```text
+host probe skipped: `codex` is not on PATH
+host probe skipped: `codex mcp list` exited 1: <the command's first line of stderr>
+```
+
+The wait is capped at **10 seconds**. A host CLI that blocks on a network
+call or an interactive authentication prompt would otherwise hang a
+synchronous `--check` with no message; past the cap the child is killed
+and the kill becomes one more named skip.
+
+The probe runs under the adapter's own injected `HOME` and environment,
+not the ambient process environment, so a relocated `CODEX_HOME` cannot
+verify `ok` against the operator's real `~/.codex`.
+
+**A refuting probe means two different things**, and which one it means
+depends on whether an artifact backs the registration:
+
+| The host answered "not registered", and | Verdict | Repair |
+| --- | --- | --- |
+| this build wrote an artifact and that artifact still matches the canonical payload | `mcp-unreachable` | restart the runtime so it reloads its MCP configuration; re-applying would rewrite bytes that are already correct |
+| the host's own registry IS the record (`copilot mcp add` leaves no file; a Codex `config.toml` that declares no tables has no artifact to be right) | `drift` | `o2b install --target <t> --apply` |
+
+A probe that could not RUN refutes nothing. Demoting a correct install
+because a binary was absent would be the same over-claim as a blanket
+`ok`, pointed the other way.
+
+### Tool ceilings, `--host-target`, and the tool-profile ladder (since v1.50.0)
+
+**The ceiling vocabulary has three states and `unknown` is never read as
+`unbounded`.** `declared` carries a number and the place it is published;
+`unbounded` carries the place the ABSENCE of a limit is published;
+`unknown` carries the reason nobody has established one. Collapsing the
+third into the second is the misleading default the whole substrate exists
+to remove, because the layer above it selects a tool surface fail-open.
+Today exactly one row is `declared` - Cursor, at 40 tools across every
+enabled MCP server - and no row is `unbounded`; the member exists so a host
+that documents "no limit" is not recorded as unchecked.
+
+**`o2b mcp --host-target <runtime>`** tells a running server which runtime
+launched it. Install adapters write it into the registration they generate;
+an unrecognised value is refused with exit `2` naming the known ids, rather
+than dropped - silently ignoring it would report the ceiling as unchecked on
+a host that publishes one. It carries no other behaviour.
+
+`second_brain_capabilities` reads it back and reports a `host_ceiling`
+object beside the tool counts: `target`, `kind`, `max_tools`, `source`,
+`reason`, and `within_ceiling` (the ADVERTISED count against the limit,
+which is what `tools/list` hands the host). A server nobody told - started
+by hand, or by a payload written before the flag existed - reports
+`kind: "unknown"` with a reason naming the flag and the command that
+regenerates the registration. An unchecked ceiling is never an absent one.
+
+**The tool-profile ladder has three tiers, highest first**, and the
+generated registration is what it parameterises:
+
+| Tier | Source |
+| --- | --- |
+| 1 | `install.tool_profile` in `<vault>/Brain/_brain.yaml` - the COMMITTED tier |
+| 2 | `mcp_tool_profile` in the machine-local `config.yaml` |
+| 3 | the host's own `RUNTIME_FACTS` row - `catalog` for Cursor, nothing for every other target |
+
+Tier 1 above tier 2 is the reverse of the guess, and it is the point.
+Install verification works by RE-CONSTRUCTION rather than a stored hash, so
+two machines cloning one vault must rebuild the same bytes; a stale key in
+one operator's `~/.config/open-second-brain/config.yaml` outranking the file
+their teammate committed would make each machine report the other's correct
+install as drift.
+
+**There is no environment tier, and its removal is the reason to state the
+rule.** `OPEN_SECOND_BRAIN_MCP_TOOL_PROFILE` used to sit above all three. It
+cannot: `verify()` rebuilds the expected artifact from the `InstallEnv`, so
+an input present on the apply invocation and absent on the next one makes a
+CORRECT install report drift - and the fix it offers would silently
+downgrade the profile the operator asked for. Every surviving tier is a
+file, and a file is still there tomorrow. The variable still selects the
+surface of the RUNNING server, which is the per-process act it is good for;
+it does not reach a generated registration.
+
+The bottom tier resolving to nothing is not the same answer as `full`: it
+leaves the surface unnamed, which is the flag-free registration every host
+had before the ladder existed. An unknown profile NAME in either file tier
+is a hard refusal listing the valid names - the opposite of the running
+server, which fails open to the full surface rather than locking an agent
+out mid-session. Nothing is locked out here; an artifact is being generated,
+and generating one for a profile that does not exist installs a surface the
+operator never named.
+
+Three of the ten targets carry neither dimension, because they write no MCP
+command line for a flag to land on: `generic` prints a payload for a host it
+was never told the name of, `aider` is wired through a managed YAML block
+and a sidecar context file, and `pi` is a skill symlink.
+
+### The committed `install:` block (since v1.50.0)
+
+An optional `install:` block in `<vault>/Brain/_brain.yaml` carries the two
+settings that parameterise GENERATED output:
+
+```yaml
+install:
+ tool_profile: catalog # full | writer | catalog | recall | minimal
+ hook_timeout_seconds: 10 # 1..600; the generated Grok hook entry's cap
+```
+
+Both live in the vault rather than in the machine-local config for the
+reason the ladder above gives: verification is re-construction, so a knob
+only one machine can see makes the other report drift it cannot explain and
+re-apply a file that was already correct. `hook_timeout_seconds` bounds a
+generated lifecycle hook entry: `0` is not "no timeout" in any host that
+reads these entries - it is a hook killed before it can run - and ten
+minutes is the ceiling, past which the value is a unit error rather than an
+intent. Both bounds are hard errors at load, never clamped, because a
+clamped timeout is indistinguishable from one nobody set. Each key has a
+machine-local counterpart one tier down - `mcp_tool_profile` and
+`install_hook_timeout_seconds` in `config.yaml` - which the block outranks.
+
+An **unreadable** `_brain.yaml` REFUSES rather than defaulting. An absent
+config is a vault with no settings to contradict; a malformed one is
+settings that exist and are not in force, and a writer cannot infer intent
+from bytes it could not parse. With the environment tier gone the vault tier
+is read on every resolution, so the refusal is unconditional - before, an
+environment variable short-circuited the ladder above it and a broken vault
+config went unnoticed for exactly those runs. `o2b install --friction` is
+the one surface that reports the refusal in a cell instead of raising,
+because it is a report and generates nothing.
+
## Brain (observing memory)
```text
@@ -133,7 +325,7 @@ o2b brain snapshot log (CLI-only) Newest-first listing of every recovery
o2b brain snapshot diff (CLI-only) Read-only diff between two snapshots, or snapshot vs live Brain/
o2b brain rollback (CLI-only) Restore Brain/ from a snapshot (--dry-run previews; drift abort vs --force-rollback); --list, the prompt and --json name the snapshot reason ('unknown' when the sidecar records none)
o2b brain upgrade (CLI-only) Migrate release-owned files forward (_brain.yaml, _BRAIN.md, _OPEN_SECOND_BRAIN.md); --dry-run / --check / --apply --yes
-o2b brain export Read-only dump of active preferences (--format json|llms-txt [--out <path>] [--force]). Since v1.49.0 the bytes pass the shared egress redactor (stderr carries a notice when anything was removed), and a `pref-*.md` the parser cannot read is REFUSED, not skipped: exit 1 naming every unreadable file in one run rather than exit 0 over a shorter list. `o2b brain doctor` reports the same files
+o2b brain export Read-only dump of active preferences, or (since v1.50.0) a session-transcript dataset: --format json|llms-txt|transcripts-jsonl [--out <path>] [--force]; the transcript form takes --transcripts <file|dir> and reads no vault at all (see "The transcript corpus" below). Since v1.49.0 the preference bytes pass the shared egress redactor (stderr carries a notice when anything was removed), and a `pref-*.md` the parser cannot read is REFUSED, not skipped: exit 1 naming every unreadable file in one run rather than exit 0 over a shorter list. `o2b brain doctor` reports the same files
o2b brain bank-export (CLI-only) One-file backup bundle: preferences, the page graph, page contracts, the sources dashboard. Redacted on the way out; refuses with exit 1 on an unreadable `pref-*.md` (since v1.49.0)
o2b brain bank-import (CLI-only) Restore a bank bundle (--mode skip|overwrite|merge). A malformed preference already in the DESTINATION does not abort the import: the rows restore and the run prints `topic-key check incomplete: <path>` for each rule the topic-collision scan could not read, because that list is then a partial answer (since v1.49.0)
o2b brain explorer (CLI-only) Force-directed HTML graph of Brain/preferences + retired; live HTTP on 127.0.0.1 or --export <path> single-file. Keyboard-accessible listbox + localStorage layout persistence. Double-click a node to open it in Obsidian (live mode). Since v1.49.0 BOTH modes refuse a Brain file they cannot parse - `--export` writes nothing and exits 1, and live mode does not start, because a browser showing a silently smaller graph is the same lie as a written file - and `--export` runs the shared redactor over the graph, so its output differs from a pre-v1.49.0 export on any vault holding a credential-shaped value
@@ -156,7 +348,7 @@ o2b brain backlinks List inbound references to a Brain artifact id
o2b brain semantics-backfill Dry-run typed preference-edge backfill preview (since v0.24.0): --json returns missing inverse superseded_by proposals; no writes
o2b brain mcp-landscape List MCP servers configured across the vault (since v0.19.0): name, source file, packages, required env-var names (values never read)
o2b brain scan-inline Capture `@osb` markers from folders listed under `notes.read_paths` in _brain.yaml
-o2b brain import-session Replay signals from a registered agent session .jsonl (or directory); --recall also stores turns in the session recall DAG
+o2b brain import-session Replay signals from a registered agent session .jsonl (or directory); --recall also stores turns in the session recall DAG. Since v1.50.0 the path argument has a machine-wide sibling: --status reports per-runtime coverage, --discover lists what has never been imported, --discover --all imports it (see "Session logs this machine already has" below)
o2b brain session-hook Internal hook bridge: read one lifecycle payload from stdin, capture prompt markers / brain_feedback, append lifecycle audit/log rows
o2b brain context-receipts List/show opt-in prompt context receipt continuity records (since v0.29.0)
o2b brain recall-telemetry List/summarise opt-in recall telemetry continuity records (since v0.29.0)
@@ -329,7 +521,7 @@ o2b brain maintenance run [--force] [--retry <task>] [--window H-H] [--t
The schema pack gains four additive ontology fields (`labels`, `link_constraints`, `attributes`, `frontmatter_tiers`) with audited mutations through `o2b brain schema apply`. Link constraints enforce at index materialization: a typed edge whose endpoint page types violate the declared pairs falls back to an untyped link, `o2b brain schema lint` lists each violation, and removing the constraint restores the edges on the next index run. Tier drift detection rides the same index pass - the snapshot keeps the expected value, so reindexes never absorb a hand-edit, and `brain_doctor` warns with the open count. Filter labelled recall with `o2b search <q> --property labels=<dim>/<value>`. Secrets protect against context leakage and vault sync exposure, not against root; every custody operation lands a no-values record in `Brain/log/secret-custody/`. A maintenance gate skip exits 0 so cron never alarms on a quiet hour.
-The lane's two vault-side knobs live in `Brain/_brain.yaml` under `maintenance:`, because they answer what the cron line cannot. `host_pressure_percent` adds a fourth gate: skip when the host's one-minute run queue stands at or above that percentage of the CPUs this process may use. Unset by default, which leaves the gate off. Where the metric is degenerate - a platform whose load average is a constant, or a cgroup with a CPU bandwidth quota, where the run queue is the whole host's - the gate stays **open** and the journal carries a separate `pressure:unmeasurable` row naming the reason, so an unreadable host is never reported as a quiet one. `failure_streak_limit` (default 3) refuses a lane task that has failed that many times in a row in the run journal, naming the streak; a single journaled success clears it. The refusal is per task - the other three still run under the same lease - and there are two ways past it: `--retry <task>` (repeatable) attempts just that task with every gate the operator configured still in force, and `--force` runs the whole lane past every soft gate and every refusal. A refused task is reported as `REFUSED`, never `FAILED`, and the run exits **7** rather than 1: nothing was attempted, so nothing failed, but a standing refusal is not the quiet hour that exits 0 either. An attempted failure still exits 1 and outranks a refusal in the same run. The `refused:streak` journal row carries the count it refused on, so the streak does not silently reset when its evidence rolls off the journal cap.
+The lane's two vault-side knobs live in `Brain/_brain.yaml` under `maintenance:`, because they answer what the cron line cannot. `host_pressure_percent` adds a fourth gate: skip when the host's one-minute run queue stands at or above that percentage of the CPUs this process may use. Unset by default, which leaves the gate off. Where the metric is degenerate - a platform whose load average is a constant, or a cgroup with a CPU bandwidth quota, where the run queue is the whole host's - the gate stays **open** and the journal carries a separate `pressure:unmeasurable` row naming the reason, so an unreadable host is never reported as a quiet one. `failure_streak_limit` (default 3) refuses a lane task that has failed that many times in a row in the run journal, naming the streak; a single journaled success clears it. The refusal is per task - the other three still run under the same lease - and there are two ways past it: `--retry <task>` (repeatable) attempts just that task with every gate the operator configured still in force, and `--force` runs the whole lane past every soft gate and every refusal. Both escapes exist on the MCP surface too - `brain_maintenance` takes `retry_tasks`, `busy_minutes`, `busy_threshold` and a `status` `limit`, so an agent reading the refusal can act on it without reaching for `force`, which switches off three gates it never meant to touch. A refused task is reported as `REFUSED`, never `FAILED`, and the run exits **7** rather than 1: nothing was attempted, so nothing failed, but a standing refusal is not the quiet hour that exits 0 either. An attempted failure still exits 1 and outranks a refusal in the same run. The `refused:streak` journal row carries the count it refused on, so the streak does not silently reset when its evidence rolls off the journal cap.
### Link and recall intelligence (since v0.45.0)
@@ -699,6 +891,143 @@ An installed channel that delivered at least once reports nothing, and a
channel nothing asked to run reports nothing. The check is fail-soft: it
can never fail the doctor pass it rides on.
+### Session logs this machine already has (since v1.50.0)
+
+`o2b brain import-session <path>` needs a path, which made cross-agent
+recall worth nothing for any session nobody knew to import: an operator had
+to already know that Claude Code writes under `~/.claude/projects`, that
+Codex has moved its rollouts between four subdirectories of `$CODEX_HOME`,
+that Grok encodes the working directory into a path component - and then run
+the verb once per file. Three flags are the machine-wide half, sweeping the
+roots `src/core/runtime/host-facts.ts` declares:
+
+```text
+o2b brain import-session --status Per-runtime found / imported / gap counts, and the roots each was looked for under
+o2b brain import-session --discover The same report, plus the absolute path of every log that has never been imported
+o2b brain import-session --discover --all Import that gap, one file at a time, through the same importSession the path form calls
+o2b brain import-session --status|--discover --progress
+ Newline-delimited progress on stderr under the `sessions` operation, one `hash` stage
+```
+
+The modes never blend, and a conflicting combination is refused by name
+rather than ranked: a path with `--discover` or `--status`, `--discover`
+with `--status`, or `--all` without `--discover`. Either ranking would be a
+guess about which one the operator meant.
+
+`--discover --all` writes through the same `importSession` the path form
+calls rather than a second copy of it, so redaction, the tool-payload
+exclusion and the dedup index are the ones that were already there. One
+unreadable log does not lose the rest of the sweep: the failure is named on
+stderr, the run carries on, and the exit is `1` if anything failed.
+
+**The ledger is keyed by content, and lives with the other derived state**
+at `<vault>/.open-second-brain/session-import-ledger.json` - the
+`session_import_ledger` row of `o2b state status`. Each entry records the
+SHA-256 of the file's bytes at the moment it was imported, so a log whose
+bytes have not changed is reported as imported without anything opening it
+again; re-importing an unchanged log used to re-parse every byte to discover
+it had nothing to write, because dedup suppresses the WRITES and not the
+read. Content and not mtime: an rsync, a Syncthing round trip or a
+`git checkout` moves the clock and not a byte, and a ledger that believed
+the clock would re-import the whole machine after any of them. A named-path
+import records its file too, when that file sits under a declared root, so a
+later `--status` does not offer back what the operator already imported by
+hand. A corrupt or unknown-schema ledger is a hard error rather than a
+silent reset, which would report an operator's entire imported machine as
+outstanding.
+
+**A Cursor database is counted as `unparsable`, not as a gap.** Cursor keeps
+per-workspace chat state in `state.vscdb`, a SQLite file this build can
+LOCATE and no adapter it ships can read. A gap is work an operator can close;
+an unreadable format is not, and folding the two would put a permanent
+number in a column an operator is trying to drive to zero. So the identity
+the report prints is `found = imported + gap + unparsable`, and the third
+term is visible in both the human lines and `--json`. Roots that exist and
+could not be listed, and files that could not be hashed, are carried
+separately again as `unreadable`, because a partial sweep found less than it
+should have and the counts alone cannot say so.
+
+The sweep reads only to hash and writes nothing - not even the ledger, which
+records imports and would be lying if a report updated it. It runs under the
+`sessions` cooperative deadline (`safeguard_timeout_sessions_seconds`); see
+"Forward pointers" below for why that operation has a budget of its own.
+
+### The transcript corpus (since v1.50.0)
+
+```text
+o2b brain export --format transcripts-jsonl --transcripts <file|dir>
+ [--runtime <adapter-id>] [--since <iso>] [--until <iso>]
+ [--out <path>] [--force]
+```
+
+One JSON object per line, **one object per CONVERSATION**: `schema`,
+`runtime` (the adapter the file was detected as), `session_id` (the
+transcript's basename, never its absolute path), `started_at`, `ended_at`,
+`message_count`, and the ordered `messages`.
+
+The alternative - one instruction/response PAIR per line, the shape a
+supervised fine-tuning harness eats directly - was considered and rejected,
+and the reason is worth stating because picking either silently is how a
+guess becomes an authoritative fact downstream. A pair set is a lossy
+projection: producing it means deciding which turn is the instruction, what
+to do with system and tool turns, and where a multi-turn exchange breaks
+into pairs - three judgements the runtime never recorded and this exporter
+cannot recover. A harness that wants pairs can derive them from a
+conversation; nothing derives the conversation back from the pairs.
+
+A message carries `turn_id`, `role`, `timestamp`, `text`, and the NAMES of
+the tools that turn called. **Tool names travel and tool inputs never do**:
+inputs are host paths, command lines and pasted payloads, and this is a
+conversation dataset rather than a tool-trace one. A turn with neither text
+nor a tool call - a runtime queue event, a payload-less meta line - is not a
+message and is counted rather than emitted.
+
+`--transcripts` names a file or a directory; a directory is walked for
+`*.jsonl` with symlinks skipped rather than followed, and a tree nesting
+deeper than 32 directories is refused by name rather than overflowing the
+stack. A path naming a FILE is taken whatever its extension, because the
+operator named that file, and a level of the walk that cannot be listed
+refuses too - an unreadable source is not an empty one.
+`--runtime` keeps one adapter's transcripts and is resolved for its
+refusal, so an unknown id lists the registered set instead of reporting an
+empty corpus.
+
+**`--since` / `--until` select whole conversations by their START**, so a
+kept conversation is never sliced at the window edge and the rest of a
+rejected file is never read. `--until` is exclusive. A first turn whose
+timestamp cannot be read refuses the export rather than guessing which side
+of the window it falls on - including the case that actually happens, where
+the runtime recorded no clock and the adapter reports the epoch, which sorts
+before any window an operator would type.
+
+The corpus never exists whole in memory. Records are guarded and written one
+at a time to a spool file the operator never named, then `rename(2)`-d into
+`--out` or streamed to stdout a chunk at a time; peak memory is one
+conversation plus one chunk.
+
+**Refusals.** A `*.jsonl` under the named source that no adapter recognises
+stops the export, naming the file: a corpus that quietly omits a transcript
+reads exactly like a machine that never recorded it. A ZERO-BYTE file is the
+one exception and is counted (`empty`) instead - it carries nothing to omit,
+Claude Code leaves them behind whenever a session is killed before its first
+turn flushes, and refusing on them made the export unusable against a real
+store. And a **secret-shaped identifier refuses the whole export and writes
+nothing**: the spool is deleted and no file the operator can see was ever
+touched. The refusal names the conversation by its basename - except when
+the basename IS the secret-shaped identifier, where it is named by runtime
+and start instant instead, because printing it is the one thing that code
+path exists to prevent.
+
+An export that matched nothing says which filter emptied it, on stderr, with
+every scanned file on exactly one counter:
+
+```text
+note: no conversation matched; <scanned> transcript file(s) scanned, <n> from another runtime, <n> outside the window, <n> with no exportable turn, <n> empty
+```
+
+The four reasons sum to `scanned` minus the exported records, so an empty
+file under exit `0` can never be read as a machine that recorded nothing.
+
## Stability and trust (since v1.0.0)
```text
@@ -721,9 +1050,9 @@ Verbs that carry it today: `o2b status`, `o2b brain init`, `bridges list|discove
**When there is no command.** About two thirds of the doctor's issue codes resolve to none, because the repair is a judgement over content or an edit whose target shape the finding cannot supply. Those are not silent: `o2b brain doctor` prints `no exit: <code> - <reason>` once per reported code, and `--json` (and MCP `brain_doctor`) carries the same reasons in an additive `no_exit` object beside the issue streams - once per code rather than repeated on each record, because a reason is about a class. Every doctor code is one or the other; `tests/core/brain/doctor-exit-census.test.ts` enumerates them from the detector and fails on a code that is neither, so an unregistered code can no longer mean "nobody got round to it". The key and the lines are absent whenever every reported code has an exit, and on a clean vault.
-Long-running operations (dream, `o2b search index | reindex | vector-backfill`, bridges discover, clusters run, architect, the maintenance lane) run under a cooperative safeguard deadline: `safeguard_timeout_seconds` (default 600, `0` disables, env `OPEN_SECOND_BRAIN_SAFEGUARD_TIMEOUT`) with per-operation overrides like `safeguard_timeout_dream_seconds`. A tripped deadline aborts at the next checkpoint - between atomic writes - and reports `{ok:false, timed_out:true}` on exit 1; maintenance-lane task results carry `timed_out` per task. The frozen-surface policy lives in `docs/stability.md`; the 0.x to 1.0.0 migration table in `docs/updating.md`.
+Long-running operations (dream, `o2b search index | reindex | vector-backfill`, bridges discover, clusters run, architect, the machine-wide session sweep, the maintenance lane) run under a cooperative safeguard deadline: `safeguard_timeout_seconds` (default 600, `0` disables, env `OPEN_SECOND_BRAIN_SAFEGUARD_TIMEOUT`) with per-operation overrides like `safeguard_timeout_dream_seconds`. The session sweep's key is `safeguard_timeout_sessions_seconds`: it is the one operation whose cost is dominated by bytes rather than by candidates - hashing transcripts that live on somebody else's disk - so its budget is worth setting separately from the passes that walk the vault. A tripped deadline aborts at the next checkpoint - between atomic writes - and reports `{ok:false, timed_out:true}` on exit 1; maintenance-lane task results carry `timed_out` per task. The frozen-surface policy lives in `docs/stability.md`; the 0.x to 1.0.0 migration table in `docs/updating.md`.
-**Watching one.** The same verbs take `--progress`, which writes one newline-delimited JSON record per checkpoint to **stderr** - `{"schema":"o2b.progress.v1","operation":…,"kind":…,"stage":…,"completed":N}`, where `kind` is `started`, `advanced`, `finished` or `stopped`, and `total` is present only where a denominator is known before the loop starts (the embedding phase knows its pending count; the index walk consumes a generator and cannot). A CLI progress stream never carries `refused` - no counter emits it; it is an MCP-only shape on a different transport, so a CLI reader that handles it writes dead code. `stage` is an identifier from the operation's own phase vocabulary, never a sentence. Stdout is untouched, so a `--json` payload is byte-identical with and without the flag, and `o2b search index --verbose` keeps its separate per-file stream unchanged - the two answer different questions. Progress is opt-in for the same reason `--verbose` is; when a stream cannot carry it the verb says `progress: not emitted (<reason>)` rather than writing into a buffer nobody will read in time. `o2b brain maintenance run --progress` forwards the stream of whichever task is running rather than counting its own four steps, so every record names the operation that emitted it. `o2b search reindex --progress` opens a `lock` stage before it waits for the writer lock (that wait can be the length of a competing rebuild) and does not report `finished` until after the `swap` stage that renames the staging build over the live index - the run is not over when the build is. `o2b search vector-backfill --progress` reports under `reindex` too, because the pass IS that run's embedding phase on its own: a `plan` stage while it counts, then the shared `embed` stage with the pending count as its denominator.
+**Watching one.** The same verbs take `--progress`, which writes one newline-delimited JSON record per checkpoint to **stderr** - `{"schema":"o2b.progress.v1","operation":…,"kind":…,"stage":…,"completed":N}`, where `kind` is `started`, `advanced`, `finished` or `stopped`, and `total` is present only where a denominator is known before the loop starts (the embedding phase knows its pending count; the index walk consumes a generator and cannot). A CLI progress stream never carries `refused` - no counter emits it; it is an MCP-only shape on a different transport, so a CLI reader that handles it writes dead code. `stage` is an identifier from the operation's own phase vocabulary, never a sentence. Stdout is untouched, so a `--json` payload is byte-identical with and without the flag, and `o2b search index --verbose` keeps its separate per-file stream unchanged - the two answer different questions. Progress is opt-in for the same reason `--verbose` is; when a stream cannot carry it the verb says `progress: not emitted (<reason>)` rather than writing into a buffer nobody will read in time. `o2b brain maintenance run --progress` forwards the stream of whichever task is running rather than counting its own four steps, so every record names the operation that emitted it. `o2b brain dream --step <s> --progress` reports under `dream` with the step's own name as the stage (`scan`, `heal-enrich`) rather than the five stages of a full pass, and runs under the same `dream` deadline: a step asked for on its own IS the run. Under `--json` a tripped deadline comes back as `{ok:false, step, timed_out:true, message}`, the same marker the staged actions and the inline pass carry. The deadline is checked per file and per directory in `scan`, and per page in each of `heal-enrich`'s two loops. Two phases of `heal-enrich` cross no boundary of their own and are therefore not interruptible at all: the vault listing, which walks every page and parses its frontmatter in one call, and the one-shot title/alias phrase build. The listing is the first thing the step does, so the only checkpoint it has is the one immediately AFTER it; the phrase build is bracketed on both sides, so an already-elapsed budget refuses to pay for it. Either way a step already inside one of them runs it to the end before it can stop. `o2b search reindex --progress` opens a `lock` stage before it waits for the writer lock (that wait can be the length of a competing rebuild) and does not report `finished` until after the `swap` stage that renames the staging build over the live index - the run is not over when the build is. `o2b search vector-backfill --progress` reports under `reindex` too, because the pass IS that run's embedding phase on its own: a `plan` stage while it counts, then the shared `embed` stage with the pending count as its denominator.
Which emitters those verbs actually have is not taken on trust. `tests/cli/progress-emitter-census.test.ts` enumerates every `progressCounter(` call site in `src/` from the source, maps each to the entry point that reaches it, then RUNS each entry point against a fixture and requires records carrying that site's operation and stage to arrive with a terminator. A call site no entry point reaches is a failure, which is how `vector-backfill` - which had grown the whole spine in core with no flag to reach it - was found.
@@ -734,8 +1063,9 @@ Which emitters those verbs actually have is not taken on trust. `tests/cli/progr
| `o2b search index`, `o2b search reindex` | Stops the run at the next checkpoint - between files, between embed batches, never mid-write - and exits **130** (SIGINT) or **143** (SIGTERM). A stopped rebuild leaves the live index exactly as it found it, because the staging build is abandoned before the swap. |
| `o2b search vector-backfill` | Stops **between embed batches** and exits **130** / **143**; vectors already written stay written, because each chunk commits as it is computed. The dry run and the planning query are synchronous SQLite between two awaits, so a keystroke landing there is not observed at a checkpoint - it ends the process on release instead, which is the same outcome the un-suppressed keystroke would have had. |
| `o2b brain maintenance run` | Stops the lane at a task boundary and exits **130** / **143**. The lane journals the stop and releases its lease, so the vault is never left leased. |
-| `o2b brain dream` (including `stage`/`validate`/`apply`), `o2b brain bridges discover`, `o2b brain clusters run`, `o2b brain architect` | **Terminates the process immediately**, the ordinary shell behaviour. These four passes are synchronous end to end, so no cooperative stop is possible and none is claimed. Every artifact they write is written atomically, so a killed pass leaves no half-written note - it leaves the vault as it was before the pass, or after the last completed write. Their deadline (`safeguard_timeout_*_seconds`, above) is the only cooperative stop they have. |
+| `o2b brain dream` (including `stage`/`validate`/`apply`), `o2b brain bridges discover`, `o2b brain clusters run`, `o2b brain architect`, `o2b brain import-session --status \| --discover` | **Terminates the process immediately**, the ordinary shell behaviour. These passes are synchronous end to end, so no cooperative stop is possible and none is claimed. Every artifact they write is written atomically, so a killed pass leaves no half-written note - it leaves the vault as it was before the pass, or after the last completed write. Their deadline (`safeguard_timeout_*_seconds`, above) is the only cooperative stop they have. |
| `o2b search watch` | Exits **0**, unchanged: stopping is how that command ends. |
+| `o2b mcp` (both transports, since v1.50.0) | Stops accepting new requests, waits for the in-flight ones to a bounded deadline, closes, and exits **130** / **143**. It is the one verb here that calls `process.exit` rather than re-raising, because two `exit` hooks - the search-store WAL checkpoint and the lock release - do not run when a process dies by signal. See "Shutdown and draining" in [`mcp.md`](mcp.md). |
For the two verbs that do hold a handle, a second interrupt is not intercepted and falls through to the default handler, so a wedged run is always killable by pressing the key twice. And an interrupt that arrives while such a verb is in a region with no checkpoint - opening a store, writing a report - is not swallowed: the verb prints `interrupted: SIGINT arrived while … stopping now` and ends with the signal's code rather than returning 0. A run the operator stopped never exits 0.
@@ -792,6 +1122,176 @@ admitted). The human transcript prints an `index: not indexed (<reason>)`
line under an included path whose admission was refused, and prints
nothing there when the path is admitted.
+## State surfaces (since v1.50.0)
+
+```text
+o2b state status One row per declared state surface: where it resolved, whether it is reachable, which layer put it there
+o2b state migrate --to <dir> Plan the move of every in-vault state surface to <dir>; --apply --yes performs it, --dry-run is the explicit form of the plan
+o2b state rollback --from <dir>
+ Put back what the migration's manifest binds and whose digest still matches; --to <vault> names a vault that has moved since
+```
+
+All three take `--json`; `status` and `migrate` also take `--vault` and
+`--config`.
+
+Three questions an operator asks before they copy, migrate or delete a
+vault had no surface that answered them: where each surface lives on this
+machine, whether it is reachable, and which layer put it there. `o2b state
+status` is that surface, and the `vault_health` MCP tool carries the same
+value under `state_surfaces` - one report rendered two ways rather than two
+hand-written copies.
+
+### The catalogue and the two tiers
+
+**40 declared surfaces**, printed whole. A row says what this build CAN keep
+at that location, never that this machine has it; presence is the measured
+half. They are grouped by what losing one costs, which is the first thing a
+migration needs:
+
+| Tier | Meaning |
+| --- | --- |
+| `derived` | rebuildable from the vault, so deleting it costs time and not memory |
+| `vault-content` | the memory itself, so a loss here is permanent without a backup |
+
+The tier is a RECOVERY story, not a location: `Brain/.state/anticipatory/`
+sits inside the Markdown tree and is `derived` because deleting it costs one
+recomputation, and the search index sits outside it and is `derived` for the
+same reason. Whether a surface can hold memory CONTENT is a separate axis,
+reported per row and counted in the summary line - 15 of the 40 can.
+
+Only two overrides move anything: `OPEN_SECOND_BRAIN_SEARCH_DB` /
+`search_db_path` relocate the search store and everything that follows it,
+and `O2B_DEVICE_ID` / `device_id` select which shard of the log and the
+truth ledger this machine writes. The second is reported as provenance and
+not substituted into the path, because it names a file inside a directory
+the inventory reports at directory granularity. Every other row prints `at
+its only location - nothing can move it`.
+
+### Reachability is a tri-state, and it carries its reason
+
+An unreadable surface is not an absent one. A boolean would have to spell "I
+could not look" as `false`, which reads as "it is not there" at every call
+site and sends an operator to recreate something that already exists under a
+mode they cannot read.
+
+| `state` | Rendered as | Meaning |
+| --- | --- | --- |
+| `present` | `present` | the probe found something at the resolved path |
+| `absent` | `absent - nothing has created it in this vault yet` | absence is a state, not a failure |
+| `unchecked` | `NOT CHECKED - could not be probed (<errno>): <message>` | an `EACCES` on the parent, an `ELOOP`, an `EIO` from a dying disk |
+
+`o2b state status` exits `0` whenever the inventory COMPLETED, including
+over an `unchecked` row: turning a reporting verb into a gate would
+duplicate `o2b doctor`. The probe falls back to `lstat` after `stat`, so a
+surface whose root is a dangling symlink answers `present` rather than
+`absent` - something IS at that path, and saying so is what carries it to
+the migration check that knows how to explain a link.
+
+### Migration refuses before it commits, and returns every reason at once
+
+`o2b state migrate` runs every check and returns ALL of them; it never
+short-circuits on the first refusal and never touches the filesystem while
+planning. An operator who fixes a symlink only to be told about a held
+writer lock, then about a full disk, learns their vault's problems one
+interrupted migration at a time.
+
+Seven refusal classes, each a distinct repair:
+
+| Code | Refused because |
+| --- | --- |
+| `symlink` | a bound path is a symbolic link. A migration copies bytes, so the link would arrive pointing at the OLD location and its target would silently stay behind |
+| `special_file` | a FIFO, socket or device node, which has no bytes to copy; copying it would produce a plain file that only looks like the original |
+| `destination_occupied` | the destination exists and is not an empty directory, or could not be examined or listed. Merging would make the manifest unable to say which files this migration put there |
+| `insufficient_space` | the destination filesystem has less free space than the plan needs, or its free space could not be measured at all |
+| `reserved_namespace` | the destination is inside the vault, an ancestor of it, the filesystem root, or the home directory itself. Every comparison is made over the REALPATH, so a symlink cannot smuggle the state tree back into the vault it is leaving |
+| `writer_lock_held` | the search index writer lock is held by a live writer, or its state could not be determined. Bytes appended after this run hashed the index would land in neither copy - the one loss a digest cannot detect afterwards |
+| `unreadable_surface` | a declared surface, a directory in the tree, or a file in it could not be probed, listed or read. A tree this run cannot enumerate cannot be bound by a manifest, and an unbound file is not restorable |
+
+Every refusal names what was found AND the remedy. A surface an override put
+outside the vault is not a refusal: it is reported separately as left where
+it is, because migrating the vault does not move it.
+
+**The dry-run ladder is `o2b brain upgrade`'s, verb for verb**, copied
+rather than reinvented because an operator who has learned one destructive
+verb in this CLI has learned all of them:
+
+| Form | Behaviour |
+| --- | --- |
+| bare `--to <dir>` | plans and prints; writes nothing |
+| `--dry-run` | the same plan, said explicitly. Mutually exclusive with `--apply` |
+| `--apply --yes` | performs it |
+| `--apply` on a TTY | prints the plan, states how many files and bytes are about to MOVE and where the rollback manifest will be, and prompts; only `y` or `yes` proceeds |
+| `--apply` under `--json` or a non-TTY stdin | refused - nobody can answer the prompt |
+
+Within the apply the same rule holds one level down. Every file is COPIED
+and its landed bytes re-digested BEFORE any source byte is removed. A copy
+that fails half way unwinds what it wrote - including the empty directory
+skeleton, so the identical retry is not blocked by the abort - and leaves
+the source exactly as it found it. Only once the whole tree has landed and
+verified does the removal pass run, and it prunes only directories that are
+now empty, so an operator's own file inside a state root keeps its parent
+alive.
+
+The destination gets `state-migration.json`: a schema version, the digest
+algorithm, the source type, the absolute source and destination roots, the
+minimal set of vault-relative directories covering every moved file
+(`canonical_roots` - a declared surface nested inside another is absorbed by
+the one that contains it, so no byte is bound twice), a byte count and a
+SHA-256 per file, and one digest over all of it.
+
+### Rollback needs `--from`, and takes `--to`
+
+`--from <dir>` is the directory a migration was moved TO - the directory
+holding its manifest - and it is required. `--to <vault>` is optional and
+answers a vault that has MOVED since: the manifest records an absolute
+source root, and a rollback into a dead path recreated the directory, copied
+into it, removed the destination copies and exited `0`, leaving the live
+vault with nothing. A recorded root that is no longer a directory is
+therefore refused BY NAME before a single entry is classified, and the plan
+prints the recorded root beside the override either way, so restoring
+somewhere else is something the operator reads rather than remembers typing.
+
+The ladder is the migration's: a bare invocation (or `--dry-run`) plans and
+prints, `--apply --yes` performs it, and `--apply` without `--yes` prompts
+on a TTY and is refused under `--json` or a non-TTY stdin.
+
+Only what the manifest binds AND whose digest still matches goes back.
+Everything else is refused by name and left exactly where it is: nothing
+this verb can do makes an operator's later edit recoverable, so the one
+thing it must never do is delete it.
+
+| Code | Left alone because |
+| --- | --- |
+| `digest_mismatch` | the destination copy has changed since the migration |
+| `missing_at_destination` | the manifest binds it and nothing is there now |
+| `source_diverged` | something has written the source path since the migration |
+| `unreadable` | this run could not read one end of it, so it cannot be shown to be the file the manifest binds |
+
+Every entry is measured AGAIN at apply time, because a plan is a statement
+about the moment it was made. The manifest is removed only when there is
+nothing left to refuse from either half - an incomplete rollback keeps it,
+since the refused entries are the only record of where those bytes came
+from.
+
+A manifest that does not verify against its own digest, declares a schema
+version this build does not read, or is not parseable JSON is refused rather
+than repaired: a rollback driven by an edited manifest is a restore of
+something nobody measured.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | the inventory completed, the plan was printed with no refusals, or the operation did what it was asked |
+| `1` | a REFUSAL: a migration that will not run, a rollback that left files behind, or a plan that could not be built |
+| `2` | a usage error: a missing `--to` or `--from`, `--dry-run` with `--apply`, an unknown subcommand, or `--apply` without `--yes` where nobody can answer a prompt |
+
+The split is the point. A refusal is an ANSWER - the command did what it was
+asked and the answer is no - and a supervisor that cannot tell it from a
+broken invocation retries the wrong one. A rollback that restored four of
+five files exits `1` even though everything it DID do succeeded, because
+"restored 4 of 5" is not a success.
+
## Discipline (daily logging cron)
```text
@@ -1111,6 +1611,27 @@ Every export that writes a FILE - `brain export`, `brain explorer --export`,
`export-config`, `install --out` - runs the shared redactor over its bytes
before they land, and prints a notice on stderr when it removed something.
+**The widest of them is `brain export --format transcripts-jsonl`** (since
+v1.50.0), and it is worth naming apart from the other six. The rest carry
+vault artifacts an agent composed; this one carries whole recorded
+conversations from whichever runtimes wrote them, which is where a key
+pasted into a prompt actually lives. Three properties follow from that:
+
+- its records are guarded **one at a time**, so a single oversized turn
+ cannot push a machine's whole corpus past the redactor's scan window;
+- it is the one call site that judges identifiers as FOREIGN. `session_id`
+ and `turn_id` were named by the harness that wrote the transcript, so the
+ guard's default narrowing - an argument about ids this vault constructs -
+ does not cover them, and the full bare-token detector is used instead;
+- a secret-shaped identifier refuses the whole export and **writes nothing**
+ the operator can see, because the only file that exists at that point is
+ an unnamed spool and it is deleted.
+
+The registry entry is `brain-export` (renamed from
+`brain-preference-export` when the third format joined), and it covers all
+three of the verb's formats: the JSON and transcript forms are redacted as
+TREES and serialised afterwards, llms-txt as text.
+
Five paths send vault-derived bytes to a NETWORK destination and are
**not** scanned. That is a stated exposure, not an oversight: redacting an
embedding input produces a vector for the placeholder rather than for the
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index bc1d9ab5..1dfce54f 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -190,7 +190,7 @@ Four independent paths land a signal in `Brain/inbox/`:
- **Live** - the agent calls `brain_feedback` (MCP) or `o2b brain feedback` (CLI) the moment the rule is formulated. This is the path the end-to-end sequence above documents.
- **Inline** - the user (or agent) writes an `@osb` marker into any vault Markdown file. `o2b brain scan-inline` finds every marker, creates the corresponding signal, and annotates the source file with `@osbβœ“ [[sig-...]]` so a re-run is a no-op. Two marker shapes: a single line `@osb feedback negative topic=... principle="..."` or a fenced ` ```osb` block with YAML inside.
-- **Session import** - `o2b brain import-session <path>` reads a Claude Code / Codex CLI / Hermes session JSONL and extracts both `@osb` markers from message text and replays of `brain_feedback` tool-use calls. Useful when MCP was not available at recording time or the agent did not make the call live.
+- **Session import** - `o2b brain import-session <path>` reads a Claude Code / Codex CLI / Hermes session JSONL and extracts both `@osb` markers from message text and replays of `brain_feedback` tool-use calls. Useful when MCP was not available at recording time or the agent did not make the call live. Since v1.50.0 the same verb also sweeps the machine: `--status` reports per-runtime coverage over the session roots this build declares, `--discover` lists the logs that have never been imported, and `--discover --all` imports them through the same code path a named path takes. A content-digest ledger under `<vault>/.open-second-brain/` keeps a re-run from re-parsing a log whose bytes have not changed.
- **Lifecycle hook** - Claude Code / Codex hooks call `o2b brain session-hook` through `hooks/session-capture.ts`. `UserPromptSubmit` prompt markers and `PostToolUse` `brain_feedback` inputs are captured immediately through the same signal dedup hash, while SessionStart / Stop / SessionEnd / PostCompact observations append non-blocking lifecycle audit/log rows.
Session capture is role-filterable (since v0.37.0): `session_capture_roles`
@@ -536,6 +536,7 @@ are mirrored in MCP; destructive operations are CLI-only by design.
| Restore snapshot | `o2b brain rollback` | β€” (CLI-only) | overwrites Brain/ from snapshot; from v0.10.6 aborts on drift unless `--force-rollback`, see [Snapshots and rollback](#snapshots-and-rollback) |
| Upgrade managed files | `o2b brain upgrade` | β€” (CLI-only) | migrates the three release-owned files (`_brain.yaml`, `_BRAIN.md`, `_OPEN_SECOND_BRAIN.md`) forward. `_brain.yaml` is text-merged additively (user values, comments, and ordering preserved); the other two are byte-compared and overwritten. `--dry-run` prints a per-file plan; `--check` exits 2 on pending updates (CI-friendly); `--apply --yes` takes an `upgrade-<ts>` snapshot before rewriting. |
| Export active prefs | `o2b brain export --format json\|llms-txt` | β€” (CLI-only) | read-only dump of `confirmed \| unconfirmed \| quarantine` preferences from `Brain/preferences/`. `--out <path>` writes a file (refuses to overwrite without `--force`); default sink is stdout. Retired and signal artifacts are deliberately excluded. |
+| Export a transcript corpus | `o2b brain export --format transcripts-jsonl --transcripts <file\|dir>` | β€” (CLI-only) | since v1.50.0: one JSON object per line, one per CONVERSATION, built from recorded session logs. Reads no vault. Messages carry role, text and the NAMES of the tools a turn called, never the tool inputs. `--runtime` filters by adapter; `--since`/`--until` select whole conversations by their start. Guarded record by record; a secret-shaped identifier refuses the whole export and writes nothing. Full contract in [`cli-reference.md`](cli-reference.md). |
| Force-directed explorer | `o2b brain explorer [--port \| --export]` | β€” (CLI-only) | live HTTP on `127.0.0.1` (default `:7777`) or single-file HTML at `<path>`; renders preferences + retired as a graph; zero backend. Keyboard-accessible `<ul role="listbox">` mirror of visible nodes (ArrowUp/Down/Home/End/Enter/Escape); layout + filter state persisted to `localStorage` under `osb-explorer-layout:<vault_basename>`; "Reset layout" button clears the key. |
| Import Claude memory | `o2b brain import-claude-memory` | β€” (CLI-only) | imports `metadata.type=feedback` entries from a Claude Code memory directory into `Brain/preferences/`. `--dry-run` prints a per-file plan; `--apply --yes` takes an `import-claude-memory-<ts>` snapshot before writing. Sidecar manifest `Brain/.imports/claude-memory.json` keys idempotency on body sha256. `UPDATE` preserves the eight evidence-related frontmatter fields. `CONFLICT` (existing pref outside the manifest) lands the safe writes and exits 2. |
| Daily discipline report | `o2b discipline {report\|install\|uninstall}` | β€” (CLI-only) | renders a deterministic Telegram MarkdownV2 block comparing per-agent brain-events vs runtime-agnostic activity (git/mtime/vault delta) plus a complexity-to-thinking ratio. `install` writes a Hermes cron entry (`--telegram-target` required; `--weekly` installs a Monday digest; `uninstall --weekly` removes only the weekly job). `alert` fires when taste events (`feedback`+`apply_evidence`) are zero while activity is non-zero, or when structural churn grows much faster than recorded thinking. |
diff --git a/docs/mcp.md b/docs/mcp.md
index 765cd2aa..546e2986 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -117,19 +117,29 @@ than the lane. Two more reach a consolidation pass without carrying its
name and report on the same terms: `brain_brief` with `view: "operator"`,
whose operator summary runs a dry-run pass, and
`brain_review_candidates`, whose projection is that same dry run
-reshaped.
+reshaped. A single-step `brain_dream` call reports too, under the stage
+that names the step rather than the five stages of a full pass β€” the
+step owns the stream, because on that path it IS the run.
**Which tools are bounded.** Every call that reaches one of those long
operations runs under a cooperative deadline resolved from
`safeguard_timeout_<operation>_seconds`, then `safeguard_timeout_seconds`,
-then the built-in default. Bounded and observed are the same population,
-with one stated exception β€” the row below marked **none**:
+then the built-in default. Bounded and observed are now the same
+population with no exception: the `step` row below was the one that read
+**none**, because the two step functions took no guard and dropped the
+sink, and a single step over a large tree therefore held the server for
+its whole duration with nothing to show for it. Both halves are wired.
+That sentence is not left to prose β€” `tests/mcp/long-running-tools.test.ts`
+reads the rows out of this table, fails on any row whose deadline or
+`reports` cell reads `none`, and fails on a row naming a tool it does not
+itself drive through both halves. The `**none**` row went stale for a
+release because nothing checked it; its replacement is checked.
| tool | long operation it reaches | deadline | reports |
| --- | --- | --- | --- |
| `brain_dream` (`run`) | `dream`, twice when `expect`/`strict` asks for a guard preview | `dream` β€” one budget for the whole call, preview included | yes |
| `brain_dream` (`stage`/`validate`/`apply`) | `dream`, through the staged bundle | `dream` | yes |
-| `brain_dream` (`step`) | one step (`scan` or `heal-enrich`), not a pass | **none** β€” the step functions take no guard | no |
+| `brain_dream` (`step`) | one step (`scan` or `heal-enrich`), not a pass | `dream` β€” a step is part of a dream pass, so it draws on that budget. Checked per file and per directory in `scan`, and per page in each of `heal-enrich`'s two loops, plus around the two phases that cross no boundary of their own β€” the vault listing (checkpoint after it only) and the one-shot title/alias phrase build (before and after). So it stops within one page **plus** whichever of those two is running, not within one page flat | yes, under the step's own stage (`scan` / `heal-enrich`) |
| `brain_bridges` (`discover`) | `bridges` | `bridges` | yes |
| `brain_clusters` (`run`) | `clusters` | `clusters` | yes |
| `brain_maintenance` (`run`) | all four, sequentially | one fresh guard per task; a tripped task is a `timed_out` row, not an aborted call | yes, in its tasks' voices |
@@ -142,6 +152,24 @@ the deadline the operation's next checkpoint throws, at a boundary where
writes are already atomic. Setting `safeguard_timeout_dream_seconds: 0`
disables the deadline for every row above whose budget is `dream`.
+Cooperative also means the guarantee is "stops at the next boundary", and
+a phase that crosses no boundary is therefore not interruptible however
+long the budget has been gone. Two such phases exist and both are in
+`heal-enrich`. They are NOT bracketed alike, and the difference is worth
+stating rather than rounding to "both sides":
+
+- the **vault listing**, which walks every page and parses its frontmatter
+ in one call, is the first thing the step does. Its only checkpoint is the
+ one immediately AFTER it β€” there is nothing before it to check β€” so a
+ budget that has already elapsed still pays for the listing once.
+- the **phrase build**, which sorts and regex-escapes the whole title/alias
+ set in one, is bracketed on both sides: the checkpoint immediately before
+ it means an elapsed budget refuses to pay for it, and the first page of
+ the rewrite loop honours it again on the far side.
+
+Either way a call that has already entered one of them runs it to the end.
+`src/core/brain/heal-run.ts` names the same two and the same asymmetry.
+
## Tool Highlights
The full server currently advertises 110 tools; the 18 deprecated predecessor
@@ -160,7 +188,7 @@ flags for a narrower per-process full server.
| `second_brain_capabilities` | Report the tools available to this MCP process and the withheld-tool reasons after runtime capability filtering. | β€” |
| `second_brain_status` | Report config and vault status, with secrets redacted. | β€” |
| `second_brain_query` | List vault pages with an optional case-insensitive title substring. | β€” |
-| `vault_health` | Run vault, config, and plugin manifest health checks. | β€” |
+| `vault_health` | Run vault, config, and plugin manifest health checks. Since v1.50.0 the response also carries `state_surfaces`: the same inventory `o2b state status` renders (every declared in-vault state surface with its resolved path, tier, reachability verdict and the configuration layer that placed it), as a sibling FIELD rather than a contribution to `ok` β€” an absent surface is normal on a young vault and an unchecked one carries its own reason. An unreadable machine config resolves to no overrides here rather than failing the report; the `checks` array already names that fault. | β€” |
| `brain_health` | Run semantic Brain Health checks and return the health verdict/domains. | β€” |
| `brain_mcp_landscape` | List the MCP servers configured across the vault: name, source config file, packages, and required env-var names. Env values never read. | β€” |
| `brain_codegraph_report` | Read-only codegraph partner report: in-scope code project, index state (`no_project`/`absent`/`not_indexed`/`indexed` with counts/`error`), and structural `Cargo.toml` workspace members. When indexed, attaches a non-blocking `index.health` graph-health gate (`empty-graph`, `collapsed-edges`, `dangling-references`, `self-loops`, `cache-root-mismatch`) surfaced before labeling/import/recall trust the graph. Never installs, extracts, or mutates; non-Rust projects report `cargo_workspace: null` with a reason. | β€” |
@@ -366,11 +394,13 @@ Optional flags:
- `--repo PATH` β€” repository root used for plugin manifest checks.
- `--scope full|writer` β€” choose the full server or the always-loaded writer subset.
- `--writer-only` β€” alias for `--scope writer`.
+- `--tool-profile full|writer|catalog|recall|minimal` β€” a named scope-plus-window bundle (see "Tool-surface profiles" below).
+- `--host-target <runtime>` β€” name the runtime that launched this server, so the capability report can cite that host's published tool ceiling. Install adapters write it into the registration they generate; an unrecognised value exits `2` naming the known ids. It changes nothing else.
- `--probe` β€” start an in-process handshake and print whether the server can advertise tools, then exit.
- `--transport stdio|http` β€” choose stdio (default) or Streamable HTTP.
- `--host HOST` β€” HTTP bind host (default `127.0.0.1`).
- `--port PORT` β€” HTTP bind port (default `0`, choose an available port).
-- `--api-key KEY` β€” required for `--transport http`; accepted as `Authorization: Bearer KEY` or `X-API-Key: KEY` on every request.
+- `--api-key KEY` β€” optional on the loopback default, REQUIRED when `--host` names a non-loopback interface; accepted as `Authorization: Bearer KEY` or `X-API-Key: KEY` on every request.
- `--json` β€” with `--probe`, print a machine-readable capability report.
- `--allow-tool NAME` β€” expose only named tools from the static scope. Repeatable.
- `--disable-tool NAME` β€” withhold named tools from the static scope. Repeatable.
@@ -378,14 +408,83 @@ Optional flags:
The stdio server logs its banner to `stderr` and only writes JSON-RPC frames to
`stdout`, so it is safe to use as a subprocess in any MCP client. HTTP refuses
-to start without `--api-key`, checks the key on every request using a generic
-constant-time comparison, and returns the same `401 Unauthorized` body for a
+to start when `--host` is not loopback and no `--api-key` was given; with a key
+configured it checks that key on every request using a generic constant-time
+comparison, and returns the same `401 Unauthorized` body for a
missing or wrong key. JSON responses are the default; clients that send
`Accept: text/event-stream` receive a single SSE `message` event for the same
JSON-RPC response β€” one event, then the connection closes, which is why a
progress token sent over HTTP is refused by name rather than honoured (see
"Progress notifications" above).
+## Shutdown and draining (since v1.50.0)
+
+Neither transport could stop without cutting a request in half. The HTTP
+handle's `close` was `server.close()` and nothing else β€” it stops the
+listener and returns, while the promise the request callback returns was
+floated, so a `tools/call` in flight was answered with a dead socket. The
+stdio loop had no shutdown path at all: a SIGTERM took the default
+disposition and killed the process mid-dispatch with no frame written.
+
+`SIGINT` and `SIGTERM` now drain. The sequence is the same on both
+transports:
+
+1. stop accepting NEW work;
+2. wait for the requests already begun, to a bounded deadline;
+3. close the transport;
+4. exit **130** (SIGINT) or **143** (SIGTERM).
+
+**The deadline is 10 000 ms**, overridable with `O2B_MCP_DRAIN_MS` (a
+non-negative number of milliseconds). A value that is not one THROWS rather
+than falling back: an operator who set the variable did so to change the
+behaviour, and quietly using ten seconds because they typed `10s` is the
+misleading quiet the drain exists to remove.
+
+A drain that hits its deadline still exits, and the requests it gave up on
+are NAMED on stderr first, each with how long it had been open, plus the
+variable that lengthens the wait β€” a shutdown that silently truncates a tool
+call is indistinguishable from a crash to whoever was waiting on it.
+
+**The `exit` hooks still run.** This is why the signal handler calls
+`process.exit(128 + signo)` instead of re-raising, which is what every
+foreground CLI verb does. Two `process.on("exit")` hooks have to run after
+the transport closes β€” the search store synchronously checkpoints the WAL of
+every open writer, and the sync lockfile unlinks every held lock β€” and the
+default disposition for a terminating signal runs neither, because the
+process dies by signal and no `exit` event is emitted. Exiting reports the
+same thing to the shell AND emits `exit`, which is why the drain has to
+complete before the exit rather than beside it.
+
+A SECOND signal is not intercepted and falls through to the default
+handler, so an operator who decides the drain is taking too long is never
+trapped by it.
+
+**What each transport does while draining:**
+
+| | HTTP | stdio |
+| --- | --- | --- |
+| new work | answered `503` with `Retry-After: 1` and `Connection: close` β€” a code a client retries, not a protocol error | the next line is left unread; the loop stops cleanly at a request boundary rather than half-serving the shutdown |
+| the listener | deliberately stays up until the drain finishes, so a supervisor can watch | β€” |
+| in-flight | tracked from the first header to the response's `close` event, so a request is not counted as finished while its bytes are still queued | tracked across the dispatch AND the response write |
+
+`GET /health` gains a third field and is **never refused during a drain** β€” a
+shutdown a supervisor cannot observe is a shutdown it will report as a
+crash:
+
+```json
+{ "status": "draining", "transport": "http", "in_flight": 2 }
+```
+
+`status` is `ok` while serving and `draining` once a drain has started;
+`in_flight` says how much of the wait is left. The probe is not counted as
+in-flight work itself: counting it would make the number a supervisor reads
+include the act of reading it, and a probe arriving as the last request
+finishes would restart the wait it was checking on. A request that arrives
+after the drain started is not counted either β€” it is refused, never
+dispatched, and counting it would let a client retrying in a tight loop hold
+the shutdown open for its whole deadline over work the server had already
+declined.
+
## Runtime capability window
Runtime capability flags are evaluated after the static scope. They can narrow
@@ -402,10 +501,48 @@ o2b mcp --vault /path/to/vault --allow-tool brain_context --allow-tool brain_fee
o2b mcp --vault /path/to/vault --max-tools 12
```
-`second_brain_capabilities` returns `scope`, `server_name`, static and available
-tool counts, an `available[]` list, and a `withheld[]` list. Withheld reasons
-are stable strings such as `disabled by runtime capability window`, `not allowed
-by runtime capability window`, and `outside runtime capability max tool window`.
+`second_brain_capabilities` returns `scope`, `server_name`,
+`static_tool_count`, `available_tool_count`, `advertised_tool_count`,
+`host_ceiling`, an `available[]` list, and a `withheld[]` list. Withheld
+reasons are stable strings such as `disabled by runtime capability window`,
+`not allowed by runtime capability window`, and `outside runtime capability
+max tool window`.
+
+`advertised_tool_count` is the number a host actually LISTS: available minus
+the tools marked hidden, which `tools/list` filters out. Under the `catalog`
+surface the two numbers are a hundred and three apart, and it is the
+advertised one a host's ceiling applies to.
+
+### The host ceiling (since v1.50.0)
+
+`host_ceiling` reports what this build can say about the per-workspace tool
+limit of the runtime that launched the server, and it is present on every
+report β€” especially when the answer is "nobody has established one". A host
+that caps a workspace at forty tools and is handed a hundred and ten drops
+the excess in silence, so omitting the field where no limit is known would
+be indistinguishable from a host with no limit at all.
+
+| Field | Meaning |
+| --- | --- |
+| `target` | the install target from `--host-target`; `null` when the server was never told |
+| `kind` | `declared`, `unbounded`, or `unknown` β€” three states, and `unknown` is never read as `unbounded` |
+| `max_tools` | the published limit; `null` unless `kind` is `declared` |
+| `source` | where the limit, or the published absence of one, is stated; `null` when `kind` is `unknown` |
+| `reason` | why there is no answer; `null` unless `kind` is `unknown` |
+| `within_ceiling` | `advertised_tool_count` against `max_tools`; `null` when there is no number to compare |
+
+A server started by hand, or by a registration written before
+`--host-target` existed, reports `kind: "unknown"` with a reason naming the
+flag and the `o2b install --target <runtime> --apply` that regenerates a
+registration carrying it. That is an UNCHECKED ceiling, not an absent one.
+
+Today exactly one runtime declares a limit β€” Cursor, 40 tools across every
+enabled MCP server β€” which is why the generated Cursor registration selects
+the `catalog` profile. No runtime is `unbounded`; the member exists so a
+host that publishes "no limit" is not recorded as unchecked. The full
+resolution ladder for the profile that ends up in a registration is
+documented under "Tool ceilings, `--host-target`, and the tool-profile
+ladder" in [`cli-reference.md`](cli-reference.md).
## Tool-surface profiles and the two-pass catalog (since v0.37.0)
diff --git a/docs/updating.md b/docs/updating.md
index 97805858..96b9c099 100644
--- a/docs/updating.md
+++ b/docs/updating.md
@@ -47,6 +47,52 @@ instruction files such as `CLAUDE.md`/`AGENTS.md`, installed
`.claude/skills/`) and warns with the exact replacement for any stale
reference it finds (`removed-tool-reference`).
+## Upgrading to 1.50.0
+
+Nothing below needs a migration step. Two of the four change what an
+existing script or supervisor sees, so they are written here rather than
+left to be discovered at the terminal.
+
+**The first `o2b install --check` after upgrading reports `drift` on a
+target installed by an earlier release.** A generated registration now
+carries `--host-target <runtime>` on both server entries, and Cursor's also
+carries `--tool-profile catalog`. Verification works by re-construction, so
+an entry written by 1.49.0 no longer equals what this build would write.
+Seven targets gain the flags β€” `codex`, `copilot-cli`, `cursor`,
+`gemini-cli`, `grok`, `kiro`, `opencode` β€” and the ones whose `verify`
+compares the entry byte for byte will say so. (`aider`, `generic` and `pi`
+write no MCP command line and are unaffected; a Codex installed through
+`codex mcp add` is also unaffected, because there `verify` checks only that
+the two tables are still declared, the CLI's own serialisation having no
+published grammar to compare against.) **Fix:** `o2b install --target <name> --apply`, or
+`o2b update`, which now hashes the payload AS WRITTEN and so stops reporting
+"up-to-date, payload unchanged" for a target whose host dimensions moved.
+The Cursor case is not cosmetic: without the profile that host silently
+drops every tool past its 40-tool ceiling.
+
+**`codex` joins `copilot-cli` as a target that can exit `5`.** `o2b install
+--check --target codex` now asks `codex mcp list` what the host has
+registered instead of only reading `$CODEX_HOME/config.toml`, so a Codex
+that has not loaded a correct configuration is reported as
+`mcp-unreachable` and exits `5` rather than `0`. A script that treated a
+zero exit as "everything is fine" for Codex was reading a file comparison
+as a liveness answer. **Fix:** restart Codex when the configuration is
+right (the check says so); `--apply` when it is not.
+
+**A running `o2b mcp` server no longer dies instantly on SIGTERM.** Both
+transports now stop accepting, wait for in-flight requests to a **10 000 ms**
+deadline, close, and exit 130/143. A supervisor with a shorter kill timeout
+than that will escalate to SIGKILL where it previously saw a clean exit; the
+`GET /health` body gains `"status": "draining"` and `in_flight` so the wait
+is observable. **Fix:** raise the supervisor's stop timeout, or lower the
+deadline with `O2B_MCP_DRAIN_MS` (a non-negative number of milliseconds; a
+value that is not one is refused rather than silently defaulted).
+
+**`o2b brain export --format` accepts a third value.** `json` and
+`llms-txt` are unchanged byte for byte. `transcripts-jsonl` is additive and
+requires `--transcripts <file|dir>`; a `--format` typo is still exit `2`,
+now listing three names instead of two.
+
## Upgrading to 1.49.0
1.49.0 is a MINOR release that nevertheless changes behaviour for input
@@ -78,7 +124,9 @@ every failure in the directory (one run names them all) and refuses. Three
verbs that exited 0 on such a vault now exit **1** with
`N preference file(s) could not be parsed …`:
-- `o2b brain export` (both `--format` values, with or without `--out`)
+- `o2b brain export` (the two preference formats, `json` and `llms-txt`,
+ with or without `--out`; the `transcripts-jsonl` format added in 1.50.0
+ reads no vault and so reads no preference file either)
- `o2b brain bank-export`
- `o2b brain explorer --export <path>` - and nothing is written
diff --git a/install/codex.md b/install/codex.md
index 2027b301..a263f169 100644
--- a/install/codex.md
+++ b/install/codex.md
@@ -1,6 +1,8 @@
# Codex
-Codex installs OSB through its marketplace + MCP subsystems.
+Codex installs OSB through its marketplace + MCP subsystems. The MCP
+registration is driven by the `codex` install adapter, so the steps below
+are the same two commands every other adapter-backed runtime uses.
## 1. Install the plugin
@@ -34,34 +36,66 @@ o2b init --vault /path/to/vault --name "My Second Brain" \
o2b brain init --vault /path/to/vault
```
-## 4. Register the MCP server
+## 4. Register the MCP servers
```bash
-codex mcp add open-second-brain \
- --env VAULT_AGENT_NAME=codex-<host>-agent \
- --env VAULT_TIMEZONE=<chosen-tz> \
- -- o2b mcp --vault /path/to/vault
+o2b install --target codex --vault /path/to/vault
+o2b install --target codex --vault /path/to/vault --apply
```
-`VAULT_AGENT_NAME` makes Codex attribute its Brain writes to its OWN
-host-qualified identity rather than the shared operator name - so Codex
-activity is distinguishable per runtime, and in a shared multi-device vault
-also per device.
-
-Build the value by keeping the host segment of your configured `agent_name`
-and substituting `codex` as the vendor token: if `agent_name` is
-`claude-vps-agent`, use `codex-vps-agent`; on a Mac box named
-`claude-mac-agent`, use `codex-mac-agent`. A name that does not fit the
-`<vendor>-<host>-agent` shape is prefixed with `codex-` instead. This mirrors
-what the `grok` and `opencode` adapters derive automatically.
+The first command plans and writes nothing; the second applies. With the
+`codex` binary on PATH the adapter registers both servers through
+`codex mcp add`, which persists them into `$CODEX_HOME/config.toml`.
+Without it, the adapter merges the same two `[mcp_servers.*]` tables into
+that file directly, leaving every other table - including the
+`[plugins."..."]` and `[marketplaces....]` blocks above - byte-for-byte
+intact.
+
+`$CODEX_HOME` is written that way throughout this page rather than as
+`~/.codex`, because the variable is what the adapter resolves and
+`~/.codex` is only its default. Setting `CODEX_HOME` relocates the whole
+Codex configuration directory, and the adapter follows it on every path:
+the file it merges, the `CODEX_HOME` it exports to the `codex mcp add`
+subprocess, the `codex mcp list` it runs to verify, and the session roots
+`o2b` sweeps for transcripts.
+
+The adapter sets `VAULT_AGENT_NAME` for you, to Codex's own
+host-qualified identity: it keeps the host segment of your configured
+`agent_name` and substitutes `codex` as the vendor token, so an
+`agent_name` of `claude-vps-agent` registers as `codex-vps-agent`. That
+makes Codex's Brain writes distinguishable per runtime, and in a shared
+multi-device vault also per device - the same derivation the `grok` and
+`opencode` adapters apply.
## 5. Verify
```bash
+o2b install --check --target codex --vault /path/to/vault
o2b doctor --vault /path/to/vault --repo .
-codex mcp list
```
+A successful check prints:
+
+<!-- expected-output: o2b install --check --target codex -->
+
+```text
+o2b install --check
+--------------------
+ codex ok `codex mcp list` reports both OSB servers registered
+```
+
+That line is the host's own answer: the check runs `codex mcp list` and
+reports what Codex says it has registered. When the binary is not on
+PATH, or exits non-zero, or does not answer within the probe's timeout,
+the check names that obstacle instead and falls back to what
+`$CODEX_HOME/config.toml` declares - and it declares a table only where
+the header stands on its own line, so a commented-out
+`# [mcp_servers.open-second-brain]` reads as absent, which is what an
+operator who commented it out meant. This block is asserted
+against the adapter's real `verify()` output by
+`tests/docs/install-verify-conformance.test.ts`, so it cannot drift from
+the code.
+
Run the daily-identity check from `install/prerequisites.md`.
## Lifecycle hooks (auto-enabled)
@@ -91,7 +125,12 @@ codex plugin marketplace upgrade open-second-brain
## Uninstall
```bash
-codex mcp remove open-second-brain
+o2b uninstall --target codex --vault /path/to/vault --apply
codex plugin marketplace remove open-second-brain
o2b uninstall --apply-local --remove-cli
```
+
+`o2b uninstall --target codex` removes only the two OSB server
+registrations - through `codex mcp remove` when the binary is present,
+and by stripping the two tables from `~/.codex/config.toml` when it is
+not. Every other table in that file is left alone.
diff --git a/install/copilot-cli.md b/install/copilot-cli.md
index c15fbd82..565ea025 100644
--- a/install/copilot-cli.md
+++ b/install/copilot-cli.md
@@ -23,8 +23,19 @@ mirrors the same path.
o2b install --check --target copilot-cli
```
-Verify queries `copilot mcp list` when the CLI is available, or
-inspects the fallback file otherwise.
+Verify always asks `copilot mcp list` what this host has registered - the
+probe is declared on the `copilot-cli` row of the runtime fact table, it
+needs no API key and starts no model turn. When the binary is absent or
+exits non-zero, the check says so by name ("host probe skipped: `copilot`
+is not on PATH") rather than reporting a handshake it never attempted.
+
+What the answer is worth depends on how the install was applied. In
+subprocess mode the host CLI holds the only record, so a probe that
+cannot run leaves nothing verified and the check exits `5`. In
+file-fallback mode the config file is compared as well, so a skipped
+probe still leaves a verified configuration - and a probe that ANSWERS
+without listing the servers means the host has not loaded that file,
+which is also exit `5`.
A successful check prints:
@@ -33,7 +44,7 @@ A successful check prints:
```text
o2b install --check
--------------------
- copilot-cli ok both OSB names registered with copilot CLI
+ copilot-cli ok `copilot mcp list` reports both OSB servers registered
```
`$HOME` stands in for your home directory. This block is asserted
diff --git a/install/cursor.md b/install/cursor.md
index 341013a4..23256e1d 100644
--- a/install/cursor.md
+++ b/install/cursor.md
@@ -2,8 +2,49 @@
`o2b install --target cursor --apply` writes the OSB MCP servers
into `~/.cursor/mcp.json` via JSON-merge. The two registered names
-are `open-second-brain` (full tool set) and `open-second-brain-writer`
-(always-loaded writer / `brain_context` subset).
+are `open-second-brain` (the **`catalog` two-pass surface** - see
+"The tool surface Cursor gets" below) and `open-second-brain-writer`
+(always-loaded writer / `brain_context` subset, five tools).
+
+## The tool surface Cursor gets
+
+Cursor sends at most the **first 40 tools** across every enabled MCP
+server to the model; anything past that is unreachable and the host
+says nothing about it. The full Open Second Brain surface advertises
+110 tools, so registering it here would silently strand most of them.
+
+The generated `open-second-brain` entry therefore carries
+`--tool-profile catalog`:
+
+```json
+"open-second-brain": {
+ "command": "o2b",
+ "args": ["mcp", "--vault", "/path/to/vault", "--tool-profile", "catalog", "--host-target", "cursor"]
+}
+```
+
+`catalog` **advertises 7 tools** and keeps every one of the 110
+registered verbs callable through `tool_hydrate`, which fetches a
+verb's schema on demand. Nothing is withheld - the surface is narrowed,
+not truncated - and `second_brain_capabilities` reports the ceiling
+this server runs under, its published source, and whether the
+advertised count fits inside it.
+
+`--host-target cursor` is what lets the running server name that
+ceiling; it carries no other behaviour.
+
+To choose a different profile, set `install.tool_profile` in
+`<vault>/Brain/_brain.yaml` (travels with the vault, and outranks the
+machine-local `mcp_tool_profile` key), then re-apply. Raising it back to
+`full` re-exposes the 110-tool surface **and the silent 40-tool cut**
+that goes with it.
+
+`OPEN_SECOND_BRAIN_MCP_TOOL_PROFILE` deliberately does not reach the
+written registration. What `--apply` writes is verified by
+re-construction, so every input has to survive to the next invocation:
+a committed file and a machine-local file do, a shell variable does not,
+and a registration fed by one would report drift against itself. The
+variable still selects the surface of a server you start yourself.
## Prerequisites
@@ -61,6 +102,9 @@ which keys to remove). User-authored entries stay intact.
- `--scope project` (writing into `<cwd>/.cursor/mcp.json`) is
deferred to a follow-up release. v0.10.11 always targets the
user-scope path.
+- An install written before the profile existed reports `drift` on the
+ next `--check`: its `args` carry no `--tool-profile`. Re-run
+ `o2b install --target cursor --apply` to regenerate it.
- If a previous OSB version wrote to `.cursor/mcp.json` without
recording a manifest entry, use
`o2b uninstall --target cursor --apply --force-from-snippet`
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index bb242be0..f47f53c1 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "1.49.0",
+ "version": "1.50.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/openclaw/index.js b/openclaw/index.js
index 6af831d3..8519f541 100644
--- a/openclaw/index.js
+++ b/openclaw/index.js
@@ -1560,7 +1560,7 @@ var import_proper_lockfile2 = __toESM(require_proper_lockfile(), 1);
import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
import { createHmac, randomBytes } from "node:crypto";
import { homedir } from "node:os";
-import { dirname as dirname2, isAbsolute, join as join2, resolve } from "node:path";
+import { dirname as dirname2, isAbsolute, join as join2, resolve as resolve2 } from "node:path";
// src/core/fs-atomic.ts
import {
@@ -1575,7 +1575,7 @@ import {
unlinkSync,
writeSync
} from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
function atomicWriteFileSync(target, contents, opts = {}) {
if (opts.skipIfUnchanged && isUnchanged(target, contents))
return false;
@@ -1833,7 +1833,7 @@ var VAULT_STORE_REF_PREFIX = "vault://";
var VAULT_STORE_REF_HEX_LEN = 32;
function vaultStoreReference(vaultPath, configPath) {
const key = resolveInstallationSecret(configPath);
- const digest = createHmac("sha256", key).update(resolve(vaultPath)).digest("hex").slice(0, VAULT_STORE_REF_HEX_LEN);
+ const digest = createHmac("sha256", key).update(resolve2(vaultPath)).digest("hex").slice(0, VAULT_STORE_REF_HEX_LEN);
return `${VAULT_STORE_REF_PREFIX}${digest}`;
}
function resolveConfigFlag(envKey, configKey, configPath) {
@@ -1889,7 +1889,7 @@ var SECRET_KEY_NAME_RE = new RegExp(`(?:${KEY_PATTERN}|${SECRET_KEY_NAME_FRAGMEN
function isSecretKeyName(name) {
return typeof name === "string" && SECRET_KEY_NAME_RE.test(name);
}
-var ENV_RE = new RegExp(`\\b(${KEY_PATTERN})(\\s*=\\s*)([^\\s\\r\\n]+)`, "gi");
+var ENV_RE = new RegExp(`(?<![A-Za-z0-9])(${KEY_PATTERN})(\\s*=\\s*)([^\\s\\r\\n]+)`, "gi");
var COLON_VALUE_RE = new RegExp(`(?<!")\\b(${KEY_PATTERN})([ \\t]*:[ \\t]*)("[^"]*"|'[^']*'|[^\\r\\n]+)`, "gi");
var YAML_SECRET_BLOCK_RE = new RegExp(`^([ \\t]*)(${KEY_PATTERN})[ \\t]*:[ \\t]*(?:[|>][+-]?\\d{0,2})?[ \\t]*\\r?\\n` + "(?:\\1[ \\t]+[^\\r\\n]*\\r?\\n?)+", "gim");
var JSON_ENTRY_RE = new RegExp(`("(?:${KEY_PATTERN})"\\s*:\\s*)("(?:[^"\\\\]|\\\\.)*"|true|false|null|-?\\d+(?:\\.\\d+)?)`, "gi");
@@ -2081,15 +2081,21 @@ var VENDOR_TOKEN_TEST_RE = new RegExp(VENDOR_TOKEN_RE.source);
function identifierCarriesSecret(value) {
return VENDOR_TOKEN_TEST_RE.test(value);
}
-function keyNameCarriesSecret(name) {
- if (identifierCarriesSecret(name))
+function carriesBareCredential(value) {
+ if (identifierCarriesSecret(value))
return true;
- for (const match of name.matchAll(HIGH_ENTROPY_TOKEN_RE)) {
+ for (const match of value.matchAll(HIGH_ENTROPY_TOKEN_RE)) {
if (!isPreservedIdentifier(match[0]))
return true;
}
return false;
}
+function keyNameCarriesSecret(name) {
+ return carriesBareCredential(name);
+}
+function foreignIdentifierCarriesSecret(value) {
+ return carriesBareCredential(value);
+}
var MAX_REPORTED_IDENTIFIERS = 12;
function isPlainContainer(value) {
const proto = Object.getPrototypeOf(value);
@@ -2111,7 +2117,8 @@ function redactStructured(input, opts = {}) {
return PLACEHOLDER;
}
if (typeof value === "string" && (underIdentifierKey || isPathLikeValue(value))) {
- if (identifierCarriesSecret(value))
+ const secretShaped = opts.foreignIdentifiers === true && underIdentifierKey ? foreignIdentifierCarriesSecret(value) : identifierCarriesSecret(value);
+ if (secretShaped)
record(location);
const cleaned = opts.redactInfra === true || opts.redactUrlCredentials === true ? redactUrlCredentials(value) : value;
if (cleaned !== value)
@@ -2187,12 +2194,12 @@ var EGRESS_SITES = Object.freeze({
redaction: R.sharedRedactor,
reason: "the only export that carries page bodies VERBATIM, which is its interchange " + "contract and also why it is the widest leak by volume. The manifest is redacted " + "as a tree and `okf.json` re-serialised from it; the markdown files are redacted " + "as text. A bundle whose secrets were removed is no longer a lossless round-trip " + "of the vault, and the verb says so rather than implying otherwise. What it does NOT " + "do is filter by label: a page carrying `private: true` in its frontmatter exports in " + "full, because the `<private>` region marker is this product's only content-derived " + "privacy primitive and these composers are content composers, not visibility filters."
},
- "brain-preference-export": {
- id: "brain-preference-export",
+ "brain-export": {
+ id: "brain-export",
verb: "o2b brain export",
module: "src/cli/brain/verbs/export.ts",
redaction: R.sharedRedactor,
- reason: "preference principles are free text an agent wrote, and the llms-txt form is " + "meant to be pasted into a foreign prompt - the destination least likely to be " + "read before it is shared."
+ reason: "preference principles are free text an agent wrote, and the llms-txt form is " + "meant to be pasted into a foreign prompt - the destination least likely to be " + "read before it is shared. One entry covers all three of the verb's formats " + "because the census keys on the MODULE and the destination is declared once, in " + "the verb: the JSON and transcript forms are redacted as TREES and serialised " + "afterwards, llms-txt as text. What proves each branch scans is a per-handler " + "check in the census, not the guard-call count - counting guards against " + "DESTINATIONS is an inequality, and this module declares one destination against " + "three guards, so a fourth handler that scanned nothing would satisfy it. The " + "transcript form is the widest of the three by far - whole recorded " + "conversations with whichever runtime wrote them, which is where a key pasted " + "into a prompt actually lives. Its records are guarded ONE AT A TIME, so a " + "single oversized turn cannot put a machine's whole corpus past the scan window, " + "and a refusal names the conversation rather than the run - by its basename, " + "except when the basename is itself the secret-shaped identifier, where it is " + "named by runtime and start instant instead. The transcript branch is also the " + "one caller that passes `foreignIdentifiers`, because its `session_id` and " + "`turn_id` were named by the harness that wrote the transcript rather than by " + "this vault, so the guard's vendor-prefix-only rule for identifiers - an " + "argument about ids this build constructs - does not cover them."
},
"config-export": {
id: "config-export",
@@ -2308,7 +2315,7 @@ import { dirname as dirname4, join as join4 } from "node:path";
// src/core/partner/codegraph.ts
import { existsSync as existsSync2, readdirSync, realpathSync } from "node:fs";
-import { dirname as dirname3, join as join3, resolve as resolve2 } from "node:path";
+import { dirname as dirname3, join as join3, resolve as resolve3 } from "node:path";
// src/core/partner/codegraph-health.ts
var GRAPH_HEALTH_CODES = Object.freeze({
@@ -2408,7 +2415,7 @@ function findCodeProjects(opts) {
const consider = (raw) => {
if (scanned >= limit)
return;
- const path = resolve2(raw);
+ const path = resolve3(raw);
if (seen.has(path))
return;
seen.add(path);
@@ -2419,7 +2426,7 @@ function findCodeProjects(opts) {
found.push(path);
};
consider(opts.cwd);
- const vaultParent = dirname3(resolve2(opts.vault));
+ const vaultParent = dirname3(resolve3(opts.vault));
if (isDir(vaultParent)) {
let entries = [];
try {
@@ -2982,9 +2989,9 @@ function doctor(opts) {
// src/core/identity-reminder.ts
import { readFileSync as readFileSync4 } from "node:fs";
-import { dirname as dirname5, resolve as resolve3 } from "node:path";
+import { dirname as dirname5, resolve as resolve4 } from "node:path";
import { fileURLToPath } from "node:url";
-var TEMPLATE_PATH = resolve3(dirname5(fileURLToPath(import.meta.url)), "..", "..", "templates", "identity-reminder.txt");
+var TEMPLATE_PATH = resolve4(dirname5(fileURLToPath(import.meta.url)), "..", "..", "templates", "identity-reminder.txt");
var RUNTIME_TARGET = Object.freeze({
hermes: "hermes",
openclaw: "openclaw"
@@ -3010,8 +3017,8 @@ function loadReminderTemplate() {
});
}
}
-var TEMPLATES_DIR = resolve3(dirname5(fileURLToPath(import.meta.url)), "..", "..", "templates");
-var PER_TARGET_PATHS = Object.freeze(Object.fromEntries(KNOWN_RUNTIME_TARGETS.map((t) => [t, resolve3(TEMPLATES_DIR, `identity-reminder.${t}.txt`)])));
+var TEMPLATES_DIR = resolve4(dirname5(fileURLToPath(import.meta.url)), "..", "..", "templates");
+var PER_TARGET_PATHS = Object.freeze(Object.fromEntries(KNOWN_RUNTIME_TARGETS.map((t) => [t, resolve4(TEMPLATES_DIR, `identity-reminder.${t}.txt`)])));
var TEMPLATE_CACHE = new Map;
function tryReadTargetTemplate(target) {
const cached = TEMPLATE_CACHE.get(target);
@@ -3100,9 +3107,9 @@ function emitDegradationNotice(sink, input) {
}
// src/core/path-safety.ts
-import { dirname as dirname6, posix, relative, resolve as resolve4, sep } from "node:path";
+import { dirname as dirname6, posix, relative, resolve as resolve5, sep } from "node:path";
function vaultRelative(target, vault) {
- const rel = relative(resolve4(vault), resolve4(target));
+ const rel = relative(resolve5(vault), resolve5(target));
return rel.split(/[\\/]/).filter((p) => p.length > 0).join(posix.sep);
}
diff --git a/package.json b/package.json
index 3329d482..040ba00b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.49.0",
+ "version": "1.50.0",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
diff --git a/plugin.yaml b/plugin.yaml
index 111c0ed0..8f3368be 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.49.0"
+version: "1.50.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index 46683e3a..b6cf0347 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.49.0",
+ "version": "1.50.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 111c0ed0..8f3368be 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.49.0"
+version: "1.50.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/pyproject.toml b/pyproject.toml
index bcd1c702..5c3c7893 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
# CLI entry points (those moved to `package.json` `bin`).
[project]
name = "open-second-brain"
-version = "1.49.0"
+version = "1.50.0"
description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/src/cli/brain/help-text.ts b/src/cli/brain/help-text.ts
index fc883a2c..e694a062 100644
--- a/src/cli/brain/help-text.ts
+++ b/src/cli/brain/help-text.ts
@@ -58,7 +58,8 @@ Brain verbs (observing memory):
unprotect Remove OSB-managed deny rules for the chosen target (--target)
merge Merge two near-duplicate preferences (<keep> <drop>; --dry-run, --force)
upgrade Migrate release-owned files forward (--dry-run by default; --apply --yes)
- export Dump active preferences (--format json|llms-txt [--out <path>])
+ export Dump preferences or a transcript dataset
+ (--format json|llms-txt|transcripts-jsonl [--out <path>])
okf-export Write a portable Open Knowledge Format bundle (--out <dir> [--force])
okf-import Import an OKF bundle (<dir>; staged as review candidates, --trusted writes direct)
explorer Launch the loopback HTML explorer; --export <path> writes a single offline file
@@ -677,6 +678,8 @@ export const VERB_HELP: Record<string, string> = {
" [--ingest-scope <label>] [--filter-role <role> ...] [--filter-text <substring>]\n" +
" [--preserve-event-time]\n" +
" [--recall-session-id <id>] [--recall-summary-group-size <n>] [--json]\n" +
+ " o2b brain import-session --status [--vault <vault>] [--progress] [--json]\n" +
+ " o2b brain import-session --discover [--all] [--vault <vault>] [--progress] [--json]\n" +
"Extract signals from a registered agent session .jsonl file (or\n" +
"directory of .jsonl files). Two extraction paths run in parallel:\n" +
"@osb markers in user/assistant messages, and replay of brain_feedback\n" +
@@ -688,7 +691,15 @@ export const VERB_HELP: Record<string, string> = {
"import wall-clock, so backfilling an old log stays historically\n" +
"faithful. Turns with an absent/unparseable/future timestamp fall back\n" +
"to now.\n" +
- "Autodetect failure exits 2 β€” pass --format to override.\n",
+ "Autodetect failure exits 2 β€” pass --format to override.\n" +
+ "--status sweeps the session roots this build declares and reports, per\n" +
+ "runtime, how many logs were found, how many are already imported, and\n" +
+ "the gap between them. --discover lists the gap without importing it;\n" +
+ "--discover --all imports it. Coverage is keyed by content hash in\n" +
+ "<vault>/.open-second-brain/session-import-ledger.json, so a log whose\n" +
+ "bytes have not changed is reported as imported without being re-parsed.\n" +
+ "A <path> and --discover/--status are mutually exclusive and refuse by\n" +
+ "name; --all on its own does the same.\n",
merge:
"usage: o2b brain merge <keep-pref-id> <drop-pref-id>\n" +
" [--dry-run] [--force] [--vault <path>] [--json]\n" +
@@ -703,12 +714,22 @@ export const VERB_HELP: Record<string, string> = {
"--force skips the interactive prompt but does NOT bypass invariant\n" +
"guards (topic/scope mismatch, pin parity).\n",
export:
- "usage: o2b brain export --format json|llms-txt [--vault <path>]\n" +
- " [--out <path>] [--force]\n" +
+ "usage: o2b brain export --format json|llms-txt|transcripts-jsonl\n" +
+ " [--vault <path>] [--out <path>] [--force]\n" +
+ " o2b brain export --format transcripts-jsonl --transcripts <file|dir>\n" +
+ " [--runtime <id>] [--since <iso>] [--until <iso>]\n" +
"Read-only dump of active preferences (confirmed | unconfirmed |\n" +
"quarantine) from Brain/preferences/. Retired and signal entries\n" +
"are not included. JSON is single-line; llms-txt follows the\n" +
"llmstxt.org H1 + summary + H2-section shape.\n" +
+ "transcripts-jsonl reads no vault: it emits one JSON conversation\n" +
+ "record per line from the session logs under --transcripts, with\n" +
+ "ordered role/text messages and the names (never the inputs) of the\n" +
+ "tools each turn called. --runtime keeps one adapter's transcripts;\n" +
+ "--since / --until select whole conversations by their START, so a\n" +
+ "kept conversation is never sliced across the window edge.\n" +
+ "Every format is scanned by the shared egress guard before a byte is\n" +
+ "written, and a secret-shaped identifier refuses the export outright.\n" +
"Default sink is stdout; --out writes to <path> (refuses to\n" +
"overwrite without --force).\n",
upgrade:
diff --git a/src/cli/brain/helpers.ts b/src/cli/brain/helpers.ts
index f5048307..98ef554d 100644
--- a/src/cli/brain/helpers.ts
+++ b/src/cli/brain/helpers.ts
@@ -95,7 +95,7 @@ export function parse(
// ── Re-exports (the barrel that verb handlers import from) ──────────────────
export { CliError } from "../argparse.ts";
-export { fail, failWith, info, ok, okJson } from "../output.ts";
+export { describeErrorChain, fail, failWith, info, ok, okJson } from "../output.ts";
/**
* Usage / argument error: plain message to stderr, exit code 2. Distinct
diff --git a/src/cli/brain/verbs/dream.ts b/src/cli/brain/verbs/dream.ts
index fe2016c2..b68dddce 100644
--- a/src/cli/brain/verbs/dream.ts
+++ b/src/cli/brain/verbs/dream.ts
@@ -52,7 +52,15 @@ import {
import { nextCommandField } from "../../../core/brain/next-step.ts";
import { emitNextStep } from "../../advisory-rail.ts";
import { attachProgress, reportProgressRefusal } from "../../progress-rail.ts";
-import { brainVerbContext, fail, ok, okJson, parse, parseOptionalIsoDate } from "../helpers.ts";
+import {
+ brainVerbContext,
+ describeErrorChain,
+ fail,
+ ok,
+ okJson,
+ parse,
+ parseOptionalIsoDate,
+} from "../helpers.ts";
// The runnable set is read from the step registry, never retyped: a
// usage line that advertises a step the pass refuses is its own dead end.
@@ -216,9 +224,28 @@ export async function cmdBrainDream(argv: string[]): Promise<number> {
});
if (wantsStep) {
+ // A step is a whole run on this surface, so it is guarded and
+ // watched like one: `scan` walks the Brain tree and `heal-enrich`
+ // reads and rewrites every user page, and neither had a deadline or
+ // a sink before. The step itself owns the counter - the two units
+ // report under their own stage names - so this attaches the rail and
+ // forwards, exactly as the maintenance lane does over its tasks.
+ const stepObservation =
+ flags["progress"] === true
+ ? // The rail is told what was actually dispatched, not a label
+ // for it: `brain.ts` hands this verb the tail AFTER `dream`, and
+ // `["dream", "step"]` named a positional this verb has never had
+ // - `--step` is a flag. The two sibling call sites below pass
+ // the real action for the same reason.
+ attachProgress({ command: "brain", argv: ["dream", ...argv], jsonRequested: asJson })
+ : null;
+ reportProgressRefusal(stepObservation);
let result: DreamStepResult;
try {
- result = runDreamStep(vault, stepRequest);
+ result = runDreamStep(vault, stepRequest, {
+ safeguard: guard(),
+ ...(stepObservation?.sink !== undefined ? { onProgress: stepObservation.sink } : {}),
+ });
} catch (exc) {
if (exc instanceof DreamStepNotRunnableError) {
return refuse(exc.message, asJson, {
@@ -229,7 +256,19 @@ export async function cmdBrainDream(argv: string[]): Promise<number> {
}
const message = `dream step ${stepRequest} failed: ${(exc as Error).message ?? exc}`;
if (asJson) {
- okJson({ ok: false, step: stepRequest, message });
+ // The same marker the staged-action catch and the inline-pass
+ // catch emit, for the same reason and on the same contract
+ // (`docs/cli-reference.md`, "Long-running operations"): a machine
+ // caller has to be able to tell a budget it can raise or retry
+ // past from a defect it cannot. This branch is the one the step
+ // deadline was added for, so it was the one place a timeout came
+ // back indistinguishable from a crash.
+ okJson({
+ ok: false,
+ step: stepRequest,
+ ...(exc instanceof SafeguardTimeoutError ? { timed_out: true } : {}),
+ message,
+ });
return 1;
}
return fail(message);
@@ -434,7 +473,7 @@ export async function cmdBrainDream(argv: string[]): Promise<number> {
okJson({ ok: false, timed_out: true, message: exc.message });
return 1;
}
- return fail(`dream failed: ${(exc as Error).message ?? exc}`);
+ return fail(`dream failed: ${describeErrorChain(exc)}`);
}
for (const w of summary.warnings ?? []) {
process.stderr.write(`warning: ${w.code}: ${w.message}\n`);
diff --git a/src/cli/brain/verbs/export.ts b/src/cli/brain/verbs/export.ts
index 788aa236..65d2185c 100644
--- a/src/cli/brain/verbs/export.ts
+++ b/src/cli/brain/verbs/export.ts
@@ -1,68 +1,433 @@
-import { existsSync } from "node:fs";
+import {
+ closeSync,
+ existsSync,
+ openSync,
+ readSync,
+ renameSync,
+ unlinkSync,
+ writeSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
import { atomicWriteFileSync } from "../../../core/fs-atomic.ts";
-import { exportPreferencesJson, exportPreferencesLlmsTxt } from "../../../core/brain/export.ts";
+import {
+ EXPORT_FORMAT,
+ EXPORT_FORMATS,
+ exportPreferencesJson,
+ exportPreferencesLlmsTxt,
+ isExportFormat,
+ type ExportFormat,
+} from "../../../core/brain/export.ts";
+import {
+ streamTranscriptConversations,
+ type TranscriptConversation,
+ type TranscriptExportOptions,
+ type TranscriptExportSummary,
+} from "../../../core/brain/export-transcripts.ts";
import {
EGRESS_OUTCOME,
EGRESS_REDACTION_NOTICE,
redactForEgress,
+ type EgressRefused,
} from "../../../core/egress/guard.ts";
-import { brainVerbContext, fail, ok, parse } from "../helpers.ts";
+import {
+ brainVerbContext,
+ fail,
+ ok,
+ parse,
+ parseOptionalIsoDate,
+ usageError,
+ type BrainVerbFlags,
+} from "../helpers.ts";
/**
- * `o2b brain export --format json|llms-txt [--out <file>] [--force]`.
+ * `o2b brain export --format <format> [--out <file>] [--force]`.
*
- * Preference principles are free text an agent wrote, and the llms-txt
- * form exists to be pasted into a foreign prompt - the destination least
- * likely to be read before it is shared. Both forms go through the shared
- * egress guard (registry entry `brain-preference-export`): the JSON as a
- * tree, serialised afterwards, and llms-txt as text.
+ * Three formats, one dispatch: {@link EXPORT_FORMAT} is the key set of
+ * {@link FORMAT_HANDLERS}, so a format the vocabulary declares and nobody
+ * implemented does not compile. The verb used to compare the raw argv
+ * string against two inline literals while the type that named them sat
+ * unimported in the core module.
+ *
+ * Every format goes through the shared egress guard (registry entry
+ * `brain-export`), and the asymmetry between them is deliberate:
+ * a tree is redacted and serialised AFTERWARDS, so a principle or a
+ * transcript line containing a quote cannot disturb the document, while
+ * llms-txt is already text and is redacted as text.
+ */
+const EGRESS_SITE = "brain-export";
+
+/**
+ * What one format produced. Four arms.
+ *
+ * A format can fail two ways that are not the same exit code: an argument
+ * the operator must fix (2) and a payload the boundary refused (1).
+ * Collapsing those would report a missing flag as a redaction failure.
+ *
+ * And a format can produce its bytes two ways. `body` is the whole answer
+ * in memory, which is right for the preference forms - they are bounded by
+ * the vault's rule set. `spooled` names a file the handler has already
+ * written record by record, which is what the transcript corpus needs and
+ * what the memory bound below is about; the caller renames it into place
+ * or streams it to stdout rather than ever holding it.
+ */
+type FormatOutcome =
+ | { readonly kind: "body"; readonly body: string; readonly redacted: boolean }
+ | { readonly kind: "spooled"; readonly spool: string; readonly redacted: boolean }
+ | { readonly kind: "usage"; readonly detail: string }
+ | { readonly kind: "refused"; readonly detail: string };
+
+/** Lift an egress verdict over already-composed bytes into an outcome. */
+function released(body: string, redacted: boolean): FormatOutcome {
+ return { kind: "body", body, redacted };
+}
+
+async function exportJson(flags: BrainVerbFlags): Promise<FormatOutcome> {
+ const { vault } = brainVerbContext(flags);
+ const verdict = redactForEgress(EGRESS_SITE, exportPreferencesJson(vault));
+ if (verdict.outcome !== EGRESS_OUTCOME.released) {
+ return { kind: "refused", detail: verdict.detail };
+ }
+ return released(JSON.stringify(verdict.payload) + "\n", verdict.redacted);
+}
+
+async function exportLlmsTxt(flags: BrainVerbFlags): Promise<FormatOutcome> {
+ const { vault } = brainVerbContext(flags);
+ const verdict = redactForEgress(EGRESS_SITE, exportPreferencesLlmsTxt(vault));
+ if (verdict.outcome !== EGRESS_OUTCOME.released) {
+ return { kind: "refused", detail: verdict.detail };
+ }
+ return released(verdict.payload, verdict.redacted);
+}
+
+/** `--since` / `--until` as instants, or the operator's error. */
+function windowOf(flags: BrainVerbFlags): { since?: Date; until?: Date } | string {
+ const since = parseOptionalIsoDate(flags, "since");
+ if (since.error !== null) return since.error;
+ const until = parseOptionalIsoDate(flags, "until");
+ if (until.error !== null) return until.error;
+ return {
+ ...(since.value !== null ? { since: since.value } : {}),
+ ...(until.value !== null ? { until: until.value } : {}),
+ };
+}
+
+/**
+ * The tree location `redactStructured` reports for a conversation's own
+ * name. Top-level key, so the location is the key itself.
*/
+const SESSION_ID_LOCATION = "session_id";
+
+/**
+ * How a refusal names the conversation it refused, WITHOUT writing the
+ * thing it refused to write.
+ *
+ * `session_id` is the transcript's basename. Prefixing the guard's
+ * sentence with it was right for the ordinary case - a secret-shaped turn
+ * id inside an ordinarily-named file - and was a leak in the case the
+ * guard exists for: when the FILENAME is the secret-shaped identifier,
+ * this line printed it to stderr, into CI logs and shell scrollback, on
+ * the one code path whose entire purpose is not letting it out. The
+ * guard's own message is careful about exactly this and says so:
+ * "(Locations, not values: the identifier is the secret.)"
+ *
+ * So the name is printed only when the name is not what was refused, and
+ * otherwise the conversation is identified by two facts that are not
+ * identifiers - the runtime that wrote it and the instant it started.
+ * Those locate one file in a session store without naming it, which is
+ * what an operator needs to go and rename it.
+ */
+function refusalPrefix(record: TranscriptConversation, verdict: EgressRefused): string {
+ if (!verdict.secretIdentifiers.includes(SESSION_ID_LOCATION)) return record.session_id;
+ return (
+ `the ${record.runtime} conversation starting ${record.started_at} ` +
+ "(its filename is itself the secret-shaped identifier, so it is not printed here)"
+ );
+}
+
+/**
+ * Where the corpus is written while it is being scanned.
+ *
+ * A sibling of `--out` when there is one, so the finishing `rename(2)` is
+ * within one filesystem and therefore atomic; otherwise the system temp
+ * directory, since a stdout run has no target directory to borrow.
+ */
+function spoolPathFor(outPath: string | undefined): string {
+ const unique = `o2b-transcripts-${process.pid}-${crypto.randomUUID()}.partial`;
+ return outPath === undefined ? join(tmpdir(), unique) : join(dirname(outPath), `.${unique}`);
+}
+
+/**
+ * The transcript corpus, one JSONL conversation record per line.
+ *
+ * No vault is resolved: the corpus lives in the runtimes' own session
+ * directories, and a format that never reads a vault must not refuse for
+ * the want of one.
+ *
+ * Each record is guarded on its own rather than the corpus as a whole. A
+ * per-record scan is what keeps one oversized turn from putting a whole
+ * machine's transcripts past the redactor's scan window, and it is what
+ * lets the refusal name the conversation the operator has to fix.
+ *
+ * ## Two guarantees that pull against each other, and how both are kept
+ *
+ * The producer streams: `streamTranscriptConversations` holds one
+ * conversation at a time and says so. This consumer used to collect every
+ * released record into an array and `join` it, which put the whole corpus
+ * in memory twice over and made the producer's bound meaningless - by
+ * construction linear in the corpus, against the 596 MB store
+ * `discover.ts` cites as its sizing case.
+ *
+ * The obvious fix - write each line as it is released - would trade that
+ * for the other guarantee: a refusal must leave nothing written, which is
+ * what lets the operator treat a refused export as an export that did not
+ * happen. Writing straight to `--out` or to stdout breaks it, because the
+ * guard cannot refuse a record it has not reached yet.
+ *
+ * So each released record is written immediately, to a SPOOL file the
+ * operator never named. A refusal deletes the spool and nothing else has
+ * been touched; a completed scan renames it into `--out` (one atomic
+ * `rename(2)`, no copy) or streams it to stdout a chunk at a time. Peak
+ * memory is one conversation plus one chunk, and "a refusal writes
+ * nothing" is still literally true of every path the operator can see.
+ */
+async function exportTranscripts(flags: BrainVerbFlags): Promise<FormatOutcome> {
+ const source = flags["transcripts"] as string | undefined;
+ if (source === undefined || source.trim() === "") {
+ return {
+ kind: "usage",
+ detail:
+ `--format ${EXPORT_FORMAT.transcriptsJsonl} requires --transcripts <file|dir> naming ` +
+ "the session logs to export; this build has no machine-wide transcript discovery",
+ };
+ }
+ const window = windowOf(flags);
+ if (typeof window === "string") return { kind: "usage", detail: window };
+
+ const options: TranscriptExportOptions = {
+ source,
+ ...window,
+ ...(typeof flags["runtime"] === "string" ? { runtime: flags["runtime"] } : {}),
+ };
+
+ const spool = spoolPathFor(flags["out"] as string | undefined);
+ // `wx`: a spool path that already exists is somebody else's file, and
+ // truncating it would be this verb destroying data it never named.
+ const handle = openSync(spool, "wx");
+ let outcome: SpoolOutcome;
+ try {
+ outcome = await spoolTranscriptCorpus(streamTranscriptConversations(options), (line) => {
+ writeSync(handle, line);
+ });
+ } finally {
+ closeSync(handle);
+ }
+ if (outcome.kind === "refused") {
+ // A refusal writes nothing the operator can see: the spool is the only
+ // file that exists, it was never named, and it goes now.
+ unlinkSync(spool);
+ return { kind: "refused", detail: outcome.detail };
+ }
+ if (outcome.written === 0) reportEmptyCorpus(outcome.summary);
+ return { kind: "spooled", spool, redacted: outcome.redacted };
+}
+
+/** What the spooling loop produced. */
+export type SpoolOutcome =
+ | {
+ readonly kind: "written";
+ readonly written: number;
+ readonly redacted: boolean;
+ readonly summary: TranscriptExportSummary;
+ }
+ | { readonly kind: "refused"; readonly detail: string };
+
+/**
+ * Guard each conversation and hand the released one straight to `write`.
+ *
+ * Exported for the one property that cannot be observed from outside the
+ * process and is the whole point of the loop: record N is written BEFORE
+ * record N+1 is asked for. Peak RSS was tried as the instrument and does
+ * not discriminate - `sessions/streaming-memory.test.ts` says why at
+ * length, and the same held here (a 63 MB corpus grew peak resident set
+ * by ~66 MB whether the records were spooled or buffered, because what
+ * dominates is uncollected `JSON.parse` garbage rather than anything the
+ * loop retains). The interleaving is the property; the memory profile is
+ * its consequence, and the property is exact where the consequence is
+ * noise.
+ *
+ * `write` takes the serialised line rather than a file handle so the test
+ * can be the observer, and so this function never learns where the bytes
+ * go - the spool, the rename and the refusal cleanup all stay with the
+ * caller that owns them.
+ *
+ * A throw out of `records` propagates: the caller closes the handle in a
+ * `finally` and the walk's own refusals (an unrecognised transcript, an
+ * unreadable directory) are already typed and named.
+ */
+export async function spoolTranscriptCorpus(
+ records: AsyncGenerator<TranscriptConversation, TranscriptExportSummary>,
+ write: (line: string) => void,
+): Promise<SpoolOutcome> {
+ let written = 0;
+ let redacted = false;
+ for (;;) {
+ // The corpus is read one conversation at a time, and the summary rides
+ // out as the generator's return value - `for await` would discard it.
+ // oxlint-disable-next-line no-await-in-loop
+ const step = await records.next();
+ if (step.done === true) return { kind: "written", written, redacted, summary: step.value };
+ // `foreignIdentifiers`: this record's `session_id` and `turn_id` were
+ // named by whichever harness wrote the transcript, so the guard's
+ // default "an id is a long mixed run by construction" narrowing - an
+ // argument about ids this vault generates - does not hold for them.
+ const verdict = redactForEgress(EGRESS_SITE, step.value, { foreignIdentifiers: true });
+ if (verdict.outcome !== EGRESS_OUTCOME.released) {
+ // Abandoning the generator here leaks nothing: a record is yielded
+ // only after its own transcript has been read to the end, so the
+ // suspended frame sits between files with none of them open.
+ return {
+ kind: "refused",
+ detail: `${refusalPrefix(step.value, verdict)}: ${verdict.detail}`,
+ };
+ }
+ write(`${JSON.stringify(verdict.payload)}\n`);
+ written += 1;
+ redacted = redacted || verdict.redacted;
+ }
+}
+
+/**
+ * An empty file under exit 0 reads like a machine that recorded nothing.
+ * Say what was looked at and which filter emptied it - every scanned file
+ * is on exactly one of these counters, so the numbers add up to `scanned`
+ * and the operator can see which one to change.
+ */
+function reportEmptyCorpus(summary: TranscriptExportSummary): void {
+ process.stderr.write(
+ `note: no conversation matched; ${summary.scanned} transcript file(s) scanned, ` +
+ `${summary.other_runtime} from another runtime, ${summary.outside_window} outside ` +
+ `the window, ${summary.no_messages} with no exportable turn, ` +
+ `${summary.empty} empty\n`,
+ );
+}
+
+/**
+ * One handler per declared format. Typed by the vocabulary, so the table
+ * and the `--format` guard cannot disagree about what this verb supports.
+ */
+const FORMAT_HANDLERS: Readonly<
+ Record<ExportFormat, (flags: BrainVerbFlags) => Promise<FormatOutcome>>
+> = Object.freeze({
+ [EXPORT_FORMAT.json]: exportJson,
+ [EXPORT_FORMAT.llmsTxt]: exportLlmsTxt,
+ [EXPORT_FORMAT.transcriptsJsonl]: exportTranscripts,
+});
+
export async function cmdBrainExport(argv: string[]): Promise<number> {
const { flags } = parse(argv, {
vault: { type: "string" },
format: { type: "string" },
+ transcripts: { type: "string" },
+ runtime: { type: "string" },
+ since: { type: "string" },
+ until: { type: "string" },
out: { type: "string" },
force: { type: "boolean" },
});
- const { vault } = brainVerbContext(flags);
- const format = flags["format"] as string | undefined;
- if (format !== "json" && format !== "llms-txt") {
- process.stderr.write("error: --format is required and must be one of json|llms-txt\n");
- return 2;
+ const format = flags["format"];
+ if (!isExportFormat(format)) {
+ return usageError(`--format is required and must be one of ${EXPORT_FORMATS.join("|")}`);
+ }
+
+ const outPath = flags["out"] as string | undefined;
+ // Asked BEFORE the handler runs, not after. This check used to sit at
+ // the very end, so `--out` naming an existing file read, hashed and
+ // redacted a whole machine's transcripts and then refused over a flag
+ // that was knowable from argv alone. An argument error is cheap to
+ // report and must not be paid for with the work it invalidates.
+ if (outPath !== undefined && existsSync(outPath) && !flags["force"]) {
+ return fail(`${outPath} exists; pass --force to overwrite`);
}
- let body: string;
- let redacted: boolean;
+ let outcome: FormatOutcome;
try {
- if (format === "json") {
- const verdict = redactForEgress("brain-preference-export", exportPreferencesJson(vault));
- if (verdict.outcome !== EGRESS_OUTCOME.released) return fail(verdict.detail);
- body = JSON.stringify(verdict.payload) + "\n";
- redacted = verdict.redacted;
- } else {
- const verdict = redactForEgress("brain-preference-export", exportPreferencesLlmsTxt(vault));
- if (verdict.outcome !== EGRESS_OUTCOME.released) return fail(verdict.detail);
- body = verdict.payload;
- redacted = verdict.redacted;
- }
+ outcome = await FORMAT_HANDLERS[format](flags);
} catch (exc) {
return fail(`export failed: ${(exc as Error).message ?? exc}`);
}
+ if (outcome.kind === "usage") return usageError(outcome.detail);
+ if (outcome.kind === "refused") return fail(outcome.detail);
- const outPath = flags["out"] as string | undefined;
+ const code =
+ outcome.kind === "spooled"
+ ? deliverSpool(outcome.spool, outPath)
+ : deliverBody(outcome.body, outPath);
+ if (code === 0 && outcome.redacted) process.stderr.write(EGRESS_REDACTION_NOTICE);
+ return code;
+}
+
+/** A composed answer, to stdout or to `--out`. */
+function deliverBody(body: string, outPath: string | undefined): number {
if (outPath === undefined) {
process.stdout.write(body);
- if (redacted) process.stderr.write(EGRESS_REDACTION_NOTICE);
return 0;
}
- if (existsSync(outPath) && !flags["force"])
- return fail(`${outPath} exists; pass --force to overwrite`);
try {
atomicWriteFileSync(outPath, body);
} catch (exc) {
return fail(`failed to write ${outPath}: ${(exc as Error).message ?? exc}`);
}
ok(`wrote ${outPath}`);
- if (redacted) process.stderr.write(EGRESS_REDACTION_NOTICE);
return 0;
}
+
+/**
+ * A spooled answer, moved into place or streamed out - and never read
+ * whole, which is the whole point of it having been spooled.
+ *
+ * `rename(2)` into `--out` is the same atomic publish `atomicWriteFileSync`
+ * performs, minus the copy: the spool was written as a sibling for exactly
+ * this. The stdout path has no rename available, so it copies through a
+ * fixed-size buffer; a `StringDecoder` carries any multi-byte character
+ * that straddles a chunk boundary rather than emitting U+FFFD, the same
+ * care `read-lines.ts` takes one layer down.
+ */
+function deliverSpool(spool: string, outPath: string | undefined): number {
+ try {
+ if (outPath !== undefined) {
+ renameSync(spool, outPath);
+ ok(`wrote ${outPath}`);
+ return 0;
+ }
+ pipeToStdout(spool);
+ return 0;
+ } catch (exc) {
+ return fail(`failed to write ${outPath ?? "stdout"}: ${(exc as Error).message ?? exc}`);
+ } finally {
+ // A rename consumed the spool; a stdout run and a failed rename did
+ // not, and neither may leave a stray file behind.
+ if (existsSync(spool)) unlinkSync(spool);
+ }
+}
+
+/** Bytes moved per read when the spool is copied to stdout. */
+const SPOOL_CHUNK_BYTES = 256 * 1024;
+
+function pipeToStdout(spool: string): void {
+ const fd = openSync(spool, "r");
+ const decoder = new StringDecoder("utf8");
+ try {
+ const buffer = Buffer.allocUnsafe(SPOOL_CHUNK_BYTES);
+ for (;;) {
+ const read = readSync(fd, buffer, 0, SPOOL_CHUNK_BYTES, null);
+ if (read === 0) break;
+ process.stdout.write(decoder.write(buffer.subarray(0, read)));
+ }
+ const tail = decoder.end();
+ if (tail !== "") process.stdout.write(tail);
+ } finally {
+ closeSync(fd);
+ }
+}
diff --git a/src/cli/brain/verbs/import-session.ts b/src/cli/brain/verbs/import-session.ts
index e1b85a52..c423109e 100644
--- a/src/cli/brain/verbs/import-session.ts
+++ b/src/cli/brain/verbs/import-session.ts
@@ -1,3 +1,26 @@
+/**
+ * `o2b brain import-session`: one path, or the whole machine.
+ *
+ * The verb took a path and nothing else, which meant an operator had to
+ * already know that Claude Code writes under `~/.claude/projects`, that
+ * Codex has moved its rollouts between four subdirectories of
+ * `$CODEX_HOME`, and that Grok encodes the working directory into a path
+ * component - and then run this once per file. `--status` and
+ * `--discover` are the machine-wide half, over the roots
+ * `src/core/runtime/host-facts.ts` declares.
+ *
+ * The two modes never blend. A path names exactly one thing to import; a
+ * sweep imports what the declared roots hold. Given both, the verb
+ * refuses and names both rather than ranking them, because either
+ * ranking is a guess about which one the operator meant.
+ *
+ * `--discover --all` is the only sweeping form that writes, and it writes
+ * through the same `importSession` the path form calls - not a second
+ * copy of it. That is what keeps the privacy posture identical rather
+ * than merely similar: redaction, the tool-payload exclusion and the
+ * dedup index are the ones that were already there.
+ */
+
import { statSync } from "node:fs";
import { resolveAgentName, resolveSessionCaptureRoles } from "../../../core/config.ts";
import {
@@ -5,7 +28,22 @@ import {
importSessionPath,
IMPORT_WRITE_MODE,
} from "../../../core/brain/sessions/import.ts";
+import {
+ discoverSessions,
+ discoveryGap,
+ recordSessionImports,
+ runtimeForPath,
+ type RuntimeCoverage,
+ type SessionDiscovery,
+ type SessionImportRecord,
+} from "../../../core/brain/sessions/discover.ts";
import { SessionImportError, type SessionAdapterId } from "../../../core/brain/sessions/types.ts";
+import {
+ createSafeguard,
+ OPERATION,
+ resolveSafeguardTimeoutMs,
+} from "../../../core/brain/safeguard.ts";
+import { attachProgress, reportProgressRefusal } from "../../progress-rail.ts";
import {
isSessionAdapterId,
sessionAdapterFormatChoices,
@@ -39,10 +77,17 @@ export async function cmdBrainImportSession(argv: string[]): Promise<number> {
"filter-role": { type: "string-array" },
"filter-text": { type: "string" },
"preserve-event-time": { type: "boolean" },
+ discover: { type: "boolean" },
+ status: { type: "boolean" },
+ all: { type: "boolean" },
+ progress: { type: "boolean" },
json: { type: "boolean" },
});
- if (positional.length < 1) return fail("brain import-session requires a <path> argument");
- const sessionPath = positional[0]!;
+ const discover = flags["discover"] === true;
+ const status = flags["status"] === true;
+ const importAll = flags["all"] === true;
+ const sessionPath = positional[0] ?? null;
+ assertOneMode(sessionPath, discover, status, importAll);
const { config, vault } = brainVerbContext(flags);
const explicitAgent = normalizeFlagString(flags["agent"]);
if (flags["agent"] !== undefined && explicitAgent === null) {
@@ -71,7 +116,6 @@ export async function cmdBrainImportSession(argv: string[]): Promise<number> {
}
const filterText = normalizeFlagString(flags["filter-text"] as string | undefined);
const preserveEventTime = Boolean(flags["preserve-event-time"]);
-
const formatRaw = flags["format"] as string | undefined;
let format: SessionAdapterId | undefined;
if (formatRaw !== undefined && formatRaw !== "auto") {
@@ -83,6 +127,42 @@ export async function cmdBrainImportSession(argv: string[]): Promise<number> {
const { value: since, error: sinceErr } = parseOptionalIsoDate(flags, "since");
if (sinceErr) return fail(sinceErr);
+ const dryRun = Boolean(flags["dry-run"]);
+ const recall = Boolean(flags["recall"]);
+ const asJson = flags["json"] === true;
+
+ // Built once and handed to every import this invocation performs, so a
+ // discovered import and a named-path import cannot diverge in what they
+ // filter, what they stamp, or what they withhold.
+ const importOptions = {
+ agent,
+ ...(format ? { format } : {}),
+ ...(since ? { since } : {}),
+ dryRun,
+ recall,
+ ...(recallSessionId !== null ? { recallSessionId } : {}),
+ ...(recallSummaryGroupSize !== undefined ? { recallSummaryGroupSize } : {}),
+ ...(ingestScope !== null ? { ingestScope } : {}),
+ ...(filterRoles.length > 0 ? { filterRoles } : {}),
+ ...(filterText !== null ? { filterTextIncludes: filterText } : {}),
+ ...(preserveEventTime ? { preserveEventTime } : {}),
+ };
+
+ if (sessionPath === null) {
+ return await sweep({
+ vault,
+ config,
+ agent,
+ asJson,
+ recall,
+ dryRun,
+ discover,
+ importAll,
+ progress: flags["progress"] === true,
+ importOptions,
+ });
+ }
+
let stat;
try {
stat = statSync(sessionPath);
@@ -90,124 +170,362 @@ export async function cmdBrainImportSession(argv: string[]): Promise<number> {
return fail(`cannot stat ${sessionPath}: ${(err as Error).message ?? err}`);
}
+ let result: Awaited<ReturnType<typeof importSessionPath>>;
try {
- const result = stat.isDirectory()
- ? await importSessionPath(vault, sessionPath, {
- agent,
- ...(format ? { format } : {}),
- ...(since ? { since } : {}),
- dryRun: Boolean(flags["dry-run"]),
- recall: Boolean(flags["recall"]),
- ...(recallSessionId !== null ? { recallSessionId } : {}),
- ...(recallSummaryGroupSize !== undefined
- ? { recallSummaryGroupSize: recallSummaryGroupSize }
- : {}),
- ...(ingestScope !== null ? { ingestScope } : {}),
- ...(filterRoles.length > 0 ? { filterRoles } : {}),
- ...(filterText !== null ? { filterTextIncludes: filterText } : {}),
- ...(preserveEventTime ? { preserveEventTime } : {}),
- })
- : {
- files: [
- await importSession(vault, sessionPath, {
- agent,
- ...(format ? { format } : {}),
- ...(since ? { since } : {}),
- dryRun: Boolean(flags["dry-run"]),
- recall: Boolean(flags["recall"]),
- ...(recallSessionId !== null ? { recallSessionId } : {}),
- ...(recallSummaryGroupSize !== undefined
- ? { recallSummaryGroupSize: recallSummaryGroupSize }
- : {}),
- ...(ingestScope !== null ? { ingestScope } : {}),
- ...(filterRoles.length > 0 ? { filterRoles } : {}),
- ...(filterText !== null ? { filterTextIncludes: filterText } : {}),
- ...(preserveEventTime ? { preserveEventTime } : {}),
- }),
- ],
- warnings: [],
- };
-
- if (!flags["dry-run"]) {
- for (const f of result.files) {
- try {
- appendLogEvent(vault, {
- timestamp: isoSecond(new Date()),
- eventType: BRAIN_LOG_EVENT_KIND.importSession,
- body: {
- agent,
- file: `[[${f.file}]]`,
- format: f.format,
- turns_scanned: String(f.turns_scanned),
- signals_created: String(f.signals_created),
- signals_deduped: String(f.signals_deduped),
- tool_replays: String(f.tool_replays),
- malformed: String(f.malformed),
- },
- });
- } catch (err) {
- process.stderr.write(
- `warning: append import-session log failed: ${(err as Error).message}\n`,
- );
- }
+ result = stat.isDirectory()
+ ? await importSessionPath(vault, sessionPath, importOptions)
+ : { files: [await importSession(vault, sessionPath, importOptions)], warnings: [] };
+ } catch (exc) {
+ return reportImportFailure(exc);
+ }
+
+ // Past this line the import HAPPENED: signals are on disk. Everything
+ // that follows is bookkeeping about it, and a bookkeeping failure is
+ // reported as itself rather than as a failed import. The ledger write
+ // used to sit inside the same `try` as the import above, so a corrupt
+ // ledger printed `import-session failed: …`, exited 1 and emitted no
+ // report at all - for a run whose signals had already been written and
+ // whose log events had already been appended.
+ let ledgerError: string | null = null;
+ if (!dryRun) {
+ logImports(vault, agent, result.files);
+ try {
+ // A named path is still coverage. Recording it is what stops a
+ // later `--status` from reporting a log the operator has already
+ // imported by hand as outstanding - the exact false gap this whole
+ // surface exists to remove.
+ //
+ // The files that were actually IMPORTED, not the files that were
+ // found. `importSessionPath` collects a per-file failure into
+ // `warnings` and carries on, so walking the directory again here
+ // recorded the ones that failed as imported: they left the ledger
+ // at their current bytes, vanished from `--status` and `--discover`
+ // until something edited them, and would stay invisible even after
+ // a later release shipped an adapter that could read them.
+ recordUnderDeclaredRoots(
+ vault,
+ result.files.map((f) => f.file),
+ );
+ } catch (exc) {
+ ledgerError = (exc as Error).message ?? String(exc);
+ }
+ }
+
+ emitImportReport(result, { asJson, recall });
+ if (ledgerError !== null) return reportLedgerFailure(ledgerError);
+ return 0;
+}
+
+/**
+ * The import landed and the coverage ledger did not.
+ *
+ * Non-zero, because something the operator asked for did not happen - but
+ * named as what it is. The repair is different from a failed import (the
+ * signals are already in the vault; re-running would only re-import work
+ * dedup will suppress), and the consequence is bounded and worth stating:
+ * the next sweep offers these files again.
+ */
+function reportLedgerFailure(detail: string): number {
+ process.stderr.write(
+ `error: the import completed and its signals were written, but the session import ledger ` +
+ `could not be updated: ${detail}. A later --status or --discover will offer these files ` +
+ "again; re-importing them is safe, because dedup suppresses the writes.\n",
+ );
+ return 1;
+}
+
+/**
+ * Refuse a combination rather than rank it.
+ *
+ * Each message names BOTH halves of the conflict and says what each one
+ * does, because the operator asked for two things and the repair is
+ * choosing between them - a message that named only the flag it dropped
+ * would leave them guessing which behaviour they still have.
+ */
+function assertOneMode(
+ sessionPath: string | null,
+ discover: boolean,
+ status: boolean,
+ importAll: boolean,
+): void {
+ if (discover && status) {
+ throw new CliError(
+ "--discover and --status ask two different questions of one sweep: --status reports the " +
+ "per-runtime found/imported/gap counts, --discover lists the files it would import. " +
+ "Pass one.",
+ );
+ }
+ if (importAll && !discover) {
+ throw new CliError(
+ "--all only means something alongside --discover: it turns the discovery report into an " +
+ "import of the gap it just listed. Pass --discover --all.",
+ );
+ }
+ if (sessionPath !== null && (discover || status)) {
+ throw new CliError(
+ `${sessionPath} and ${discover ? "--discover" : "--status"} cannot both be given: a path ` +
+ "imports exactly that path, and the sweep works over the session roots this build " +
+ "declares. Drop one.",
+ );
+ }
+ if (sessionPath === null && !discover && !status) {
+ throw new CliError(
+ "brain import-session requires a <path> argument, or --discover / --status to sweep the " +
+ "session stores this machine declares.",
+ );
+ }
+}
+
+interface SweepRequest {
+ readonly vault: string;
+ readonly config: string | null;
+ readonly agent: string;
+ readonly asJson: boolean;
+ readonly recall: boolean;
+ readonly dryRun: boolean;
+ readonly discover: boolean;
+ readonly importAll: boolean;
+ readonly progress: boolean;
+ readonly importOptions: Parameters<typeof importSession>[2];
+}
+
+/** The machine-wide half: `--status`, `--discover`, and `--discover --all`. */
+async function sweep(req: SweepRequest): Promise<number> {
+ // Progress is opt-in: attaching a sink by default would change the
+ // stderr of every existing invocation. The rail decides whether the
+ // stream can carry it at all.
+ const observation = req.progress
+ ? attachProgress({ command: "brain", argv: ["import-session"], jsonRequested: req.asJson })
+ : null;
+ reportProgressRefusal(observation);
+
+ let discovery: SessionDiscovery;
+ try {
+ discovery = discoverSessions(req.vault, {
+ safeguard: createSafeguard({
+ operation: OPERATION.sessions,
+ timeoutMs: resolveSafeguardTimeoutMs(OPERATION.sessions, req.config ?? undefined),
+ }),
+ ...(observation?.sink !== undefined ? { onProgress: observation.sink } : {}),
+ });
+ } catch (exc) {
+ return fail(`session discovery failed: ${(exc as Error).message ?? exc}`);
+ }
+
+ if (!req.importAll) {
+ emitCoverage(discovery, { asJson: req.asJson, listGap: req.discover });
+ return 0;
+ }
+
+ const gap = discoveryGap(discovery);
+ const files: Awaited<ReturnType<typeof importSession>>[] = [];
+ const failures: Array<{ path: string; message: string }> = [];
+ const imported: SessionImportRecord[] = [];
+ for (const entry of gap) {
+ try {
+ // Sequential on purpose: `importSession` builds and consults one
+ // dedup index per call, and two concurrent imports would each miss
+ // the other's writes.
+ // oxlint-disable-next-line no-await-in-loop
+ files.push(await importSession(req.vault, entry.path, req.importOptions));
+ imported.push(entry);
+ } catch (exc) {
+ // One unreadable log must not lose the rest of the sweep; the
+ // failure is named and the run carries on.
+ failures.push({ path: entry.path, message: (exc as Error).message ?? String(exc) });
+ }
+ }
+
+ // Same ordering as the path form, for the same reason: the imports have
+ // landed, so a lock timeout or a read-only vault in the ledger write is
+ // a bookkeeping failure and must not swallow the report of what was
+ // imported. This call was not in a `try` at all, so it took the whole
+ // run's report down with it.
+ let ledgerError: string | null = null;
+ if (!req.dryRun) {
+ logImports(req.vault, req.agent, files);
+ if (imported.length > 0) {
+ try {
+ recordSessionImports(req.vault, imported);
+ } catch (exc) {
+ ledgerError = (exc as Error).message ?? String(exc);
}
}
+ }
- if (flags["json"]) {
- okJson({
- files: result.files.map((f) => ({
- file: f.file,
+ emitImportReport({ files, warnings: [] }, { asJson: req.asJson, recall: req.recall, failures });
+ if (ledgerError !== null) return reportLedgerFailure(ledgerError);
+ return failures.length > 0 ? 1 : 0;
+}
+
+/** `path -> the runtime whose declared root contains it`, recorded in the ledger. */
+function recordUnderDeclaredRoots(vault: string, paths: ReadonlyArray<string>): void {
+ const records: SessionImportRecord[] = [];
+ for (const path of paths) {
+ const runtime = runtimeForPath(path);
+ if (runtime !== null) records.push({ path, runtime });
+ }
+ if (records.length > 0) recordSessionImports(vault, records);
+}
+
+/** Append one `import-session` log event per imported file, fail-soft. */
+function logImports(
+ vault: string,
+ agent: string,
+ files: ReadonlyArray<Awaited<ReturnType<typeof importSession>>>,
+): void {
+ for (const f of files) {
+ try {
+ appendLogEvent(vault, {
+ timestamp: isoSecond(new Date()),
+ eventType: BRAIN_LOG_EVENT_KIND.importSession,
+ body: {
+ agent,
+ file: `[[${f.file}]]`,
format: f.format,
- write_mode: f.write_mode,
- turns_scanned: f.turns_scanned,
- signals_created: f.signals_created,
- signals_withheld: f.signals_withheld,
- signals_deduped: f.signals_deduped,
- facts_extracted: f.facts_extracted,
- facts_withheld: f.facts_withheld,
- tool_replays: f.tool_replays,
- malformed: f.malformed,
- filtered_turns: f.filtered_turns,
- recall_turns_imported: f.recall_turns_imported,
- recall_summary_nodes: f.recall_summary_nodes,
- errors: f.errors,
- })),
- warnings: result.warnings,
+ turns_scanned: String(f.turns_scanned),
+ signals_created: String(f.signals_created),
+ signals_deduped: String(f.signals_deduped),
+ tool_replays: String(f.tool_replays),
+ malformed: String(f.malformed),
+ },
});
- } else {
- for (const f of result.files) {
- ok(`file: ${f.file}`);
- ok(` format: ${f.format}`);
- ok(` write_mode: ${f.write_mode}`);
- ok(` turns_scanned: ${f.turns_scanned}`);
- ok(` signals_created: ${f.signals_created}`);
- // Printed only on a rehearsal, where it is the whole answer; an
- // applied run's withheld count is zero by construction.
- if (f.write_mode === IMPORT_WRITE_MODE.dryRun) {
- ok(` signals_withheld: ${f.signals_withheld}`);
- ok(` facts_withheld: ${f.facts_withheld}`);
- }
- ok(` signals_deduped: ${f.signals_deduped}`);
- ok(` tool_replays: ${f.tool_replays}`);
- ok(` filtered_turns: ${f.filtered_turns}`);
- if (flags["recall"]) {
- ok(` recall_turns_imported: ${f.recall_turns_imported}`);
- ok(` recall_summary_nodes: ${f.recall_summary_nodes}`);
- }
- if (f.malformed > 0) ok(` malformed: ${f.malformed}`);
- for (const e of f.errors) info(` error: ${e.path}: ${e.message}`);
- }
- for (const w of result.warnings) info(` warning: ${w.path}: ${w.message}`);
+ } catch (err) {
+ process.stderr.write(
+ `warning: append import-session log failed: ${(err as Error).message}\n`,
+ );
}
- return 0;
- } catch (exc) {
- if (exc instanceof SessionImportError) {
- process.stderr.write(`error: ${exc.message}\n`);
- if (exc.code === "DETECT_FAIL" || exc.code === "UNKNOWN_FORMAT") return 2;
- return 1;
+ }
+}
+
+/** One coverage row, as the JSON surface serialises it. */
+function coverageJson(row: RuntimeCoverage): Record<string, unknown> {
+ return {
+ runtime: row.runtime,
+ found: row.found,
+ imported: row.imported,
+ gap: row.gap,
+ unparsable: row.unparsable,
+ roots: row.roots.map((root) => ({
+ id: root.id,
+ path: root.path,
+ present: root.present,
+ adapter: root.adapter,
+ format: root.format,
+ })),
+ };
+}
+
+/** Report what the sweep found, without importing anything. */
+function emitCoverage(
+ discovery: SessionDiscovery,
+ opts: { asJson: boolean; listGap: boolean },
+): void {
+ if (opts.asJson) {
+ okJson({
+ found: discovery.found,
+ imported: discovery.imported,
+ gap: discovery.gap,
+ unparsable: discovery.unparsable,
+ unreadable: discovery.unreadable,
+ by_runtime: discovery.byRuntime.map(coverageJson),
+ ...(opts.listGap
+ ? { would_import: discovery.byRuntime.flatMap((row) => [...row.gapPaths]) }
+ : {}),
+ });
+ return;
+ }
+ ok(`found: ${discovery.found}`);
+ ok(`imported: ${discovery.imported}`);
+ ok(`gap: ${discovery.gap}`);
+ if (discovery.unparsable > 0) ok(`unparsable: ${discovery.unparsable}`);
+ for (const row of discovery.byRuntime) {
+ ok(`runtime: ${row.runtime}`);
+ ok(` found: ${row.found}`);
+ ok(` imported: ${row.imported}`);
+ ok(` gap: ${row.gap}`);
+ if (row.unparsable > 0) ok(` unparsable: ${row.unparsable}`);
+ // Where it looked. "found: 0" without the root it looked under is an
+ // answer an operator cannot act on or disbelieve.
+ for (const root of row.roots) {
+ ok(` root: ${root.path} (${root.present ? "present" : "absent"})`);
}
- return fail(`import-session failed: ${(exc as Error).message ?? exc}`);
+ if (opts.listGap) for (const path of row.gapPaths) ok(` would import: ${path}`);
+ }
+ for (const line of discovery.unreadable) info(` unreadable: ${line}`);
+}
+
+/** The per-file import report, shared by the path form and the sweep. */
+function emitImportReport(
+ result: {
+ files: ReadonlyArray<Awaited<ReturnType<typeof importSession>>>;
+ warnings: ReadonlyArray<{ path: string; message: string }>;
+ },
+ opts: {
+ asJson: boolean;
+ recall: boolean;
+ failures?: ReadonlyArray<{ path: string; message: string }>;
+ },
+): void {
+ const failures = opts.failures ?? [];
+ if (opts.asJson) {
+ okJson({
+ files: result.files.map((f) => ({
+ file: f.file,
+ format: f.format,
+ write_mode: f.write_mode,
+ turns_scanned: f.turns_scanned,
+ signals_created: f.signals_created,
+ signals_withheld: f.signals_withheld,
+ signals_deduped: f.signals_deduped,
+ facts_extracted: f.facts_extracted,
+ facts_withheld: f.facts_withheld,
+ tool_replays: f.tool_replays,
+ malformed: f.malformed,
+ filtered_turns: f.filtered_turns,
+ recall_turns_imported: f.recall_turns_imported,
+ recall_summary_nodes: f.recall_summary_nodes,
+ errors: f.errors,
+ })),
+ warnings: result.warnings,
+ ...(failures.length > 0 ? { failed: failures } : {}),
+ });
+ return;
+ }
+ for (const f of result.files) {
+ ok(`file: ${f.file}`);
+ ok(` format: ${f.format}`);
+ ok(` write_mode: ${f.write_mode}`);
+ ok(` turns_scanned: ${f.turns_scanned}`);
+ ok(` signals_created: ${f.signals_created}`);
+ // Printed only on a rehearsal, where it is the whole answer; an
+ // applied run's withheld count is zero by construction.
+ if (f.write_mode === IMPORT_WRITE_MODE.dryRun) {
+ ok(` signals_withheld: ${f.signals_withheld}`);
+ ok(` facts_withheld: ${f.facts_withheld}`);
+ }
+ ok(` signals_deduped: ${f.signals_deduped}`);
+ ok(` tool_replays: ${f.tool_replays}`);
+ ok(` filtered_turns: ${f.filtered_turns}`);
+ if (opts.recall) {
+ ok(` recall_turns_imported: ${f.recall_turns_imported}`);
+ ok(` recall_summary_nodes: ${f.recall_summary_nodes}`);
+ }
+ if (f.malformed > 0) ok(` malformed: ${f.malformed}`);
+ for (const e of f.errors) info(` error: ${e.path}: ${e.message}`);
+ }
+ for (const w of result.warnings) info(` warning: ${w.path}: ${w.message}`);
+ for (const f of failures) process.stderr.write(`error: ${f.path}: ${f.message}\n`);
+}
+
+/** Map a session-import throw onto this verb's exit codes. */
+function reportImportFailure(exc: unknown): number {
+ if (exc instanceof SessionImportError) {
+ process.stderr.write(`error: ${exc.message}\n`);
+ if (exc.code === "DETECT_FAIL" || exc.code === "UNKNOWN_FORMAT") return 2;
+ return 1;
}
+ return fail(`import-session failed: ${(exc as Error).message ?? exc}`);
}
function normalizeRoleFilter(
diff --git a/src/cli/brain/verbs/maintenance.ts b/src/cli/brain/verbs/maintenance.ts
index 215d1b2c..850e32b5 100644
--- a/src/cli/brain/verbs/maintenance.ts
+++ b/src/cli/brain/verbs/maintenance.ts
@@ -29,19 +29,23 @@ import {
createSafeguard,
OPERATION,
resolveSafeguardTimeoutMs,
- type Operation,
} from "../../../core/brain/safeguard.ts";
import { isoSecond } from "../../../core/brain/time.ts";
import { Store } from "../../../core/search/store.ts";
import { currentLease, MAINTENANCE_LEASE_NAME } from "../../../core/brain/maintenance/lease.ts";
import {
+ isLaneTask,
+ LANE_TASK,
MAINTENANCE_BUSY_MINUTES,
+ MAINTENANCE_BUSY_MINUTES_MAX,
MAINTENANCE_BUSY_THRESHOLD,
+ MAINTENANCE_BUSY_THRESHOLD_MAX,
runMaintenance,
type DailyWindow,
+ type LaneTask,
type MaintenanceTask,
} from "../../../core/brain/maintenance/lane.ts";
-import { listJournal } from "../../../core/brain/maintenance/journal.ts";
+import { listJournal, MAINTENANCE_JOURNAL_CAP } from "../../../core/brain/maintenance/journal.ts";
import { resolveAgentName } from "../../../core/config.ts";
import { indexVault, resolveSearchConfig } from "../../../core/search/index.ts";
import { onInterrupt } from "../../interrupt.ts";
@@ -87,9 +91,6 @@ export const MAINTENANCE_EXIT = Object.freeze({
export type MaintenanceExit = (typeof MAINTENANCE_EXIT)[keyof typeof MAINTENANCE_EXIT];
-/** The four long operations the lane dispatches, in its own order. */
-type LaneOperation = Extract<Operation, "dream" | "reindex" | "bridges" | "clusters">;
-
export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
@@ -116,10 +117,17 @@ export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
try {
if (op === "status") {
+ // Bounded on the journal's own ring size, which is also the bound
+ // `brain_maintenance` enforces. Unbounded here, `--limit 100000`
+ // was accepted on this surface and refused on the other for the
+ // same lane; and the ring cannot hold more than its cap anyway, so
+ // a larger number was never a request the journal could answer.
const limitRaw = flags["limit"] as string | undefined;
const limit = limitRaw !== undefined ? Number(limitRaw) : 10;
- if (!Number.isInteger(limit) || limit < 1) {
- process.stderr.write("brain maintenance status: --limit must be a positive integer\n");
+ if (!Number.isInteger(limit) || limit < 1 || limit > MAINTENANCE_JOURNAL_CAP) {
+ process.stderr.write(
+ `brain maintenance status: --limit must be an integer between 1 and ${MAINTENANCE_JOURNAL_CAP}\n`,
+ );
return MAINTENANCE_EXIT.usage;
}
const lease = currentLease(vault, { name: MAINTENANCE_LEASE_NAME, now });
@@ -153,11 +161,24 @@ export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
}
window = { startHour, endHour, tz: (flags["tz"] as string | undefined) ?? "UTC" };
}
- const busyMinutes = numberFlag(flags["busy-minutes"], MAINTENANCE_BUSY_MINUTES);
- const busyThreshold = numberFlag(flags["busy-threshold"], MAINTENANCE_BUSY_THRESHOLD);
+ // Same ceilings the MCP tool's schema declares and its handler
+ // enforces, read from the same constants beside the defaults: one
+ // lane must not accept through one door what it refuses at the other.
+ const busyMinutes = numberFlag(
+ flags["busy-minutes"],
+ MAINTENANCE_BUSY_MINUTES,
+ MAINTENANCE_BUSY_MINUTES_MAX,
+ );
+ const busyThreshold = numberFlag(
+ flags["busy-threshold"],
+ MAINTENANCE_BUSY_THRESHOLD,
+ MAINTENANCE_BUSY_THRESHOLD_MAX,
+ );
if (busyMinutes === null || busyThreshold === null) {
process.stderr.write(
- "brain maintenance run: --busy-minutes/--busy-threshold must be positive integers\n",
+ `brain maintenance run: --busy-minutes must be an integer between 1 and ` +
+ `${MAINTENANCE_BUSY_MINUTES_MAX} and --busy-threshold between 1 and ` +
+ `${MAINTENANCE_BUSY_THRESHOLD_MAX}\n`,
);
return MAINTENANCE_EXIT.usage;
}
@@ -202,7 +223,10 @@ export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
// One fresh deadline per lane task: each long pass gets its own
// budget (per-op key -> global -> default), created lazily so the
// clock starts when the task starts, not when the lane is gated.
- const laneSafeguard = (operation: LaneOperation) =>
+ // A lane task IS one of the guarded operations - `LANE_TASK` reads its
+ // values out of `OPERATION` - so the task name is the budget key, and
+ // the union this used to retype locally is gone from both surfaces.
+ const laneSafeguard = (operation: LaneTask) =>
createSafeguard({
operation,
timeoutMs: resolveSafeguardTimeoutMs(operation, config ?? undefined),
@@ -211,20 +235,24 @@ export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
let result: Awaited<ReturnType<typeof runMaintenance>>;
try {
// Built once and read twice - the lane runs these, and `--retry` is
- // checked against their names. A second hard-coded list of the same
- // four names is a list that can disagree with this one.
+ // checked against their names. That intent is unchanged; what
+ // changed is where the names come from. They were four literals
+ // here and four more in `admin-tools.ts`, and the two lists drifted
+ // apart twice, so both are now built from `LANE_TASK` and `--retry`
+ // validates against the vocabulary rather than against whichever
+ // list happens to be nearest.
//
// Inside the `try`, because the check below can return: a return
// between `onInterrupt()` and the `try` would skip `release`.
const laneTasks: ReadonlyArray<MaintenanceTask> = [
{
- name: "dream",
+ name: LANE_TASK.dream,
run: async () => {
dream(vault, { now, safeguard: laneSafeguard(OPERATION.dream), ...laneProgress });
},
},
{
- name: "reindex",
+ name: LANE_TASK.reindex,
run: async () => {
await indexVault(searchConfig, {
safeguard: laneSafeguard(OPERATION.reindex),
@@ -237,7 +265,7 @@ export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
// reindex so they see fresh edges. Both are fail-soft inside:
// a vault without embeddings simply proposes nothing.
{
- name: "bridges",
+ name: LANE_TASK.bridges,
run: async () => {
const store = await Store.open(searchConfig, { mode: "read" });
try {
@@ -267,7 +295,7 @@ export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
},
},
{
- name: "clusters",
+ name: LANE_TASK.clusters,
run: async () => {
const store = await Store.open(searchConfig, { mode: "read" });
try {
@@ -297,10 +325,8 @@ export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
},
},
];
- const retryTasks = stringArrayFlag(flags["retry"]);
- const unknownRetries = retryTasks.filter(
- (name) => !laneTasks.some((task) => task.name === name),
- );
+ const requested = stringArrayFlag(flags["retry"]);
+ const unknownRetries = requested.filter((name) => !isLaneTask(name));
if (unknownRetries.length > 0) {
// Named, not ignored: a typo that silently retried nothing would
// leave the operator reading a refusal they thought they had just
@@ -311,6 +337,7 @@ export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
);
return MAINTENANCE_EXIT.usage;
}
+ const retryTasks = requested.filter(isLaneTask);
result = await runMaintenance(vault, {
now,
holder,
@@ -372,8 +399,9 @@ function stringArrayFlag(raw: unknown): string[] {
: [];
}
-function numberFlag(raw: unknown, fallback: number): number | null {
+/** An integer flag inside `1..max`, its default, or null when refused. */
+function numberFlag(raw: unknown, fallback: number, max: number): number | null {
if (raw === undefined) return fallback;
const value = Number(raw);
- return Number.isInteger(value) && value > 0 ? value : null;
+ return Number.isInteger(value) && value > 0 && value <= max ? value : null;
}
diff --git a/src/cli/brain/verbs/upgrade.ts b/src/cli/brain/verbs/upgrade.ts
index 2e0ca3c7..f6f695db 100644
--- a/src/cli/brain/verbs/upgrade.ts
+++ b/src/cli/brain/verbs/upgrade.ts
@@ -6,6 +6,7 @@ import {
} from "../../../core/brain/upgrade.ts";
import {
brainVerbContext,
+ describeErrorChain,
fail,
ok,
okJson,
@@ -96,7 +97,7 @@ export async function cmdBrainUpgrade(argv: string[]): Promise<number> {
process.stderr.write(`error: ${exc.message}\n`);
return 1;
}
- return fail(`upgrade failed: ${(exc as Error).message ?? exc}`);
+ return fail(`upgrade failed: ${describeErrorChain(exc)}`);
}
if (flags["json"]) {
diff --git a/src/cli/command-manifest.ts b/src/cli/command-manifest.ts
index 49b47039..88096950 100644
--- a/src/cli/command-manifest.ts
+++ b/src/cli/command-manifest.ts
@@ -60,6 +60,7 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
flag("scope", "string"),
flag("writer-only", "boolean"),
flag("tool-profile", "string"),
+ flag("host-target", "string"),
flag("probe", "boolean"),
flag("allow-tool", "string-array"),
flag("disable-tool", "string-array"),
@@ -68,7 +69,24 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
command("help", "Print command help or the command manifest"),
command("completions", "Print shell completion script for o2b", [flag("shell", "string")]),
command("install-cli", "Create symlinks for o2b and vault-log"),
- command("install", "Multi-runtime install orchestrator"),
+ // The whole flag set, not only the two the friction mode added:
+ // `tests/cli/help-surface-parity.test.ts` renders the human help from
+ // this list, so declaring one flag on a verb that parses twelve would
+ // advertise a surface narrower than the verb's own argument parser.
+ command("install", "Multi-runtime install orchestrator", [
+ flag("target", "string"),
+ flag("apply", "boolean"),
+ flag("check", "boolean"),
+ flag("friction", "boolean"),
+ flag("base", "string"),
+ flag("compare", "string"),
+ flag("dry-run", "boolean"),
+ flag("force", "boolean"),
+ flag("out", "string"),
+ flag("format", "string"),
+ flag("vault", "string"),
+ flag("config", "string"),
+ ]),
command("update", "Update Open Second Brain across detected runtimes", [
flag("target", "string"),
flag("dry-run", "boolean"),
@@ -164,7 +182,16 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
),
command("rollback", "Restore Brain from a snapshot"),
command("upgrade", "Migrate release-owned Brain files"),
- command("export", "Export active preferences"),
+ command("export", "Export active preferences or a session-transcript dataset", [
+ flag("vault", "string"),
+ flag("format", "string"),
+ flag("transcripts", "string"),
+ flag("runtime", "string"),
+ flag("since", "string"),
+ flag("until", "string"),
+ flag("out", "string"),
+ flag("force", "boolean"),
+ ]),
command("explorer", "Open or export Brain graph explorer"),
command("doctor", "Check Brain invariants"),
command("status", "Unified operator status snapshot with next-command hints", [
@@ -243,7 +270,30 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
flag("agent", "string"),
flag("json", "boolean"),
]),
- command("import-session", "Replay registered agent sessions"),
+ // Every flag the parser accepts, following the `o2b install`
+ // precedent from earlier in this release: advertising a narrower
+ // surface than the parser takes is the discoverability dead end
+ // `manifest-completeness.test.ts` exists to prevent, and this
+ // verb declared none of the thirteen it already parsed.
+ command("import-session", "Replay registered agent sessions", [
+ flag("vault", "string"),
+ flag("format", "string"),
+ flag("since", "string"),
+ flag("dry-run", "boolean"),
+ flag("agent", "string"),
+ flag("recall", "boolean"),
+ flag("recall-session-id", "string"),
+ flag("recall-summary-group-size", "string"),
+ flag("ingest-scope", "string"),
+ flag("filter-role", "string-array"),
+ flag("filter-text", "string"),
+ flag("preserve-event-time", "boolean"),
+ flag("discover", "boolean"),
+ flag("status", "boolean"),
+ flag("all", "boolean"),
+ flag("progress", "boolean"),
+ flag("json", "boolean"),
+ ]),
command("handoff", "Write an operator-readable session handoff note"),
command("intention", "Manage scoped current-intention chains"),
command("project", "Link project directories to their owning vault"),
@@ -609,6 +659,48 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
command("map", "Print vault-map role tokens"),
],
),
+ command(
+ "state",
+ "In-vault state surface verbs",
+ [],
+ [
+ command(
+ "status",
+ "Report every state surface in the vault with its path, reachability, and the override that placed it",
+ [flag("vault", "string"), flag("config", "string"), flag("json", "boolean")],
+ ),
+ command(
+ "migrate",
+ "Plan (or, with --apply --yes, perform) a digest-bound move of the vault's state to another directory",
+ [
+ flag("to", "string"),
+ flag("vault", "string"),
+ flag("config", "string"),
+ flag("dry-run", "boolean"),
+ flag("apply", "boolean"),
+ flag("yes", "boolean"),
+ flag("json", "boolean"),
+ ],
+ ),
+ command(
+ "rollback",
+ "Restore a migration's manifest-bound files whose digests still match, refusing anything changed since",
+ [
+ flag("from", "string"),
+ // `--to` rescues a vault that moved after the migration, which
+ // is the one case the rollback plan refuses by name. Leaving it
+ // undeclared hid the remedy from `o2b help --json` and from
+ // shell completions - the two places an operator looks when the
+ // refusal tells them a flag exists.
+ flag("to", "string"),
+ flag("dry-run", "boolean"),
+ flag("apply", "boolean"),
+ flag("yes", "boolean"),
+ flag("json", "boolean"),
+ ],
+ ),
+ ],
+ ),
command(
"discipline",
"Daily logging discipline verbs",
diff --git a/src/cli/install/init-interactive.ts b/src/cli/install/init-interactive.ts
index ac7890ed..222f9601 100644
--- a/src/cli/install/init-interactive.ts
+++ b/src/cli/install/init-interactive.ts
@@ -15,6 +15,7 @@ import { dirname, join } from "node:path";
import { validateTimezoneName } from "../../core/config.ts";
import { defaultRegistry } from "../../core/install/registry.ts";
import "../../core/install/adapters/aider.ts";
+import "../../core/install/adapters/codex.ts";
import "../../core/install/adapters/copilot-cli.ts";
import "../../core/install/adapters/cursor.ts";
import "../../core/install/adapters/gemini-cli.ts";
diff --git a/src/cli/install/install.ts b/src/cli/install/install.ts
index ebc0eb3b..25fcf604 100644
--- a/src/cli/install/install.ts
+++ b/src/cli/install/install.ts
@@ -9,6 +9,9 @@
* o2b install --check # verify every known target
* o2b install --target generic --out <p|-> # generic adapter only
* o2b install --target generic --format json|yaml
+ * o2b install --friction # capability matrix, every runtime
+ * o2b install --friction --target X # one runtime
+ * o2b install --friction --base A --compare B # only what differs
*
* Exit codes ({@link INSTALL_EXIT}):
* 0 success / no drift
@@ -35,6 +38,14 @@ import { defaultRegistry } from "../../core/install/registry.ts";
import "../../core/install/adapters/all.ts";
import { buildPayload, PayloadError } from "../../core/install/payload.ts";
+import {
+ buildFrictionMatrix,
+ diffFrictionRows,
+ FRICTION_DIMENSIONS,
+ frictionRowFor,
+ type FrictionInput,
+} from "../../core/install/friction.ts";
+import { isInstallTargetId, type InstallTargetId } from "../../core/runtime/host-facts.ts";
import { renderDataOwnership } from "../../core/install/ownership.ts";
import type { DataOwnership } from "../../core/install/ownership.ts";
import { measureDataOwnership } from "../../core/install/ownership-measure.ts";
@@ -45,6 +56,10 @@ import {
renderApplyResult,
renderDetectJson,
renderDetectTable,
+ renderFrictionDiff,
+ renderFrictionDiffJson,
+ renderFrictionJson,
+ renderFrictionTable,
renderPlan,
renderPlanJson,
renderVerifyJson,
@@ -68,6 +83,9 @@ interface ParsedInstallArgs {
readonly target: string | null;
readonly apply: boolean;
readonly check: boolean;
+ readonly friction: boolean;
+ readonly base: string | null;
+ readonly compare: string | null;
readonly dryRun: boolean;
readonly force: boolean;
readonly json: boolean;
@@ -82,6 +100,9 @@ function parseInstallArgs(argv: string[]): ParsedInstallArgs {
target: { type: "string" },
apply: { type: "boolean" },
check: { type: "boolean" },
+ friction: { type: "boolean" },
+ base: { type: "string" },
+ compare: { type: "string" },
"dry-run": { type: "boolean" },
force: { type: "boolean" },
json: { type: "boolean" },
@@ -102,6 +123,9 @@ function parseInstallArgs(argv: string[]): ParsedInstallArgs {
target: (flags["target"] as string | undefined) ?? null,
apply: Boolean(flags["apply"]),
check: Boolean(flags["check"]),
+ friction: Boolean(flags["friction"]),
+ base: (flags["base"] as string | undefined) ?? null,
+ compare: (flags["compare"] as string | undefined) ?? null,
dryRun: Boolean(flags["dry-run"]),
force: Boolean(flags["force"]),
json: Boolean(flags["json"]),
@@ -138,10 +162,26 @@ export function resolveInstallVault(explicitVault: string | null, configPath: st
return explicitVault ?? resolveVault(configPath) ?? "";
}
+/**
+ * The `InstallEnv` every adapter on this run is handed.
+ *
+ * `OPEN_SECOND_BRAIN_CONFIG` is stamped from the resolved `--config` so
+ * that ONE file parameterises the whole run. It did not used to be: the
+ * agent name, timezone and vault came from `--config`, while
+ * `install_hook_timeout_seconds` and `mcp_tool_profile` were read by
+ * `installSettingsSource` out of `~/.config/open-second-brain/config.yaml`
+ * because `InstallEnv` carried no config path and the resolver fell back
+ * to the machine default. On a box with both files populated, `--apply`
+ * generated from one and `--check` verified against the other. Publishing
+ * the choice as the variable `resolveDefaultConfigPath` already consults
+ * first keeps a single override in a single place, and keeps `InstallEnv`
+ * the complete description of the run it is documented to be.
+ */
function buildInstallEnv(args: ParsedInstallArgs): InstallEnv {
const cfg = discoverConfig(args.config).data;
const vault = resolveInstallVault(args.vault, args.config);
const env = { ...process.env } as Record<string, string>;
+ env["OPEN_SECOND_BRAIN_CONFIG"] = args.config;
if (cfg["agent_name"]) env["VAULT_AGENT_NAME"] = cfg["agent_name"];
if (cfg["timezone"]) env["VAULT_TIMEZONE"] = cfg["timezone"];
return {
@@ -225,6 +265,11 @@ export async function cmdInstall(argv: string[]): Promise<number> {
throw e;
}
+ // `--friction` is a report over the registry rather than an operation
+ // on one target, so it is settled before `--target` is read as "act on
+ // this runtime".
+ if (args.friction) return runFriction(args);
+
// `--check` is its own mode β€” runs verify per target.
if (args.check) return runCheck(args);
@@ -246,15 +291,101 @@ function runDetect(args: ParsedInstallArgs): number {
return INSTALL_EXIT.ok;
}
-function runTarget(args: ParsedInstallArgs): number {
- const adapter = defaultRegistry.get(args.target!);
- if (!adapter) {
+/**
+ * Refuse a runtime nobody registered, by name and with the spelling.
+ *
+ * One function because three flags now accept a target, and an operator
+ * who mistyped one is owed the same answer whichever they mistyped.
+ */
+function refuseUnknownTarget(flag: string, value: string): number {
+ process.stderr.write(
+ `error: unknown ${flag}: ${value}. Available: ${defaultRegistry.targets().join(", ")}\n`,
+ );
+ return INSTALL_EXIT.usage;
+}
+
+/**
+ * The registered target `value` names, or `null`.
+ *
+ * Both halves are required: the registry answers whether an adapter
+ * exists, the guard answers whether the id is a member of the closed
+ * vocabulary the fact table is keyed by. A value that passes one and not
+ * the other is the contradiction
+ * `tests/core/architecture/host-facts-census.test.ts` exists to prevent,
+ * and it is refused here rather than indexed into the table.
+ */
+function resolveTarget(value: string): InstallTargetId | null {
+ if (defaultRegistry.get(value) === undefined) return null;
+ return isInstallTargetId(value) ? value : null;
+}
+
+/**
+ * `o2b install --friction` - what each host costs, side by side.
+ *
+ * A report, so it never returns a non-zero code for what it FOUND: the
+ * matrix has no notion of a bad answer, only of an honest one. The only
+ * refusals are usage refusals, and each one names the flag and the
+ * spelling it wanted.
+ */
+function runFriction(args: ParsedInstallArgs): number {
+ const wantsDiff = args.base !== null || args.compare !== null;
+ if (wantsDiff && args.target !== null) {
process.stderr.write(
- `error: unknown --target: ${args.target}. ` +
- `Available: ${defaultRegistry.targets().join(", ")}\n`,
+ "error: --friction takes either --target <t> or --base <a> --compare <b>, not both\n",
);
return INSTALL_EXIT.usage;
}
+ if (wantsDiff && (args.base === null || args.compare === null)) {
+ const missing = args.base === null ? "--base" : "--compare";
+ process.stderr.write(
+ `error: --friction diff needs both --base and --compare; ${missing} is missing\n`,
+ );
+ return INSTALL_EXIT.usage;
+ }
+ for (const [flag, value] of [
+ ["--target", args.target],
+ ["--base", args.base],
+ ["--compare", args.compare],
+ ] as const) {
+ if (value !== null && resolveTarget(value) === null) return refuseUnknownTarget(flag, value);
+ }
+
+ const env = buildInstallEnv(args);
+ let payload;
+ try {
+ payload = loadPayload(args, env);
+ } catch (e) {
+ if (e instanceof UsageError || e instanceof PayloadError) {
+ process.stderr.write(`error: ${e.message}\n`);
+ return INSTALL_EXIT.usage;
+ }
+ throw e;
+ }
+ const input: FrictionInput = { env, payload, adapters: defaultRegistry.list() };
+
+ if (wantsDiff) {
+ const diff = diffFrictionRows(
+ frictionRowFor(resolveTarget(args.base!)!, input),
+ frictionRowFor(resolveTarget(args.compare!)!, input),
+ );
+ process.stdout.write(args.json ? renderFrictionDiffJson(diff) : renderFrictionDiff(diff));
+ return INSTALL_EXIT.ok;
+ }
+
+ const matrix =
+ args.target === null
+ ? buildFrictionMatrix(input)
+ : {
+ dimensions: FRICTION_DIMENSIONS,
+ rows: [frictionRowFor(resolveTarget(args.target)!, input)],
+ };
+ process.stdout.write(args.json ? renderFrictionJson(matrix) : renderFrictionTable(matrix));
+ return INSTALL_EXIT.ok;
+}
+
+function runTarget(args: ParsedInstallArgs): number {
+ const adapter = defaultRegistry.get(args.target!);
+ if (!adapter) return refuseUnknownTarget("--target", args.target!);
const env = buildInstallEnv(args);
let payload;
try {
diff --git a/src/cli/install/render.ts b/src/cli/install/render.ts
index 3813c837..52c7a51a 100644
--- a/src/cli/install/render.ts
+++ b/src/cli/install/render.ts
@@ -20,6 +20,7 @@
*/
import type { DataOwnership } from "../../core/install/ownership.ts";
+import type { FrictionDiff, FrictionMatrix } from "../../core/install/friction.ts";
import type {
ApplyResult,
DetectResult,
@@ -195,3 +196,93 @@ export function renderVerifyJson(
...(ownership === null ? {} : { [DATA_OWNERSHIP_KEY]: ownership }),
});
}
+
+/** Column widths shared by the friction table and its diff. */
+const FRICTION_TARGET_WIDTH = 14;
+const FRICTION_DIMENSION_WIDTH = 22;
+/** Where a citation continuation line starts: past both columns. */
+const FRICTION_DETAIL_INDENT = " ".repeat(2 + FRICTION_TARGET_WIDTH + FRICTION_DIMENSION_WIDTH);
+
+/**
+ * The friction matrix: one line per host per dimension, with the
+ * citation on a continuation line beneath it.
+ *
+ * The citation is printed rather than reserved for `--json` because the
+ * answers it explains are one word each - `unknown`, `none ships` - and a
+ * one-word answer with no source is the shape of claim this whole verb
+ * spent a release removing.
+ */
+export function renderFrictionTable(matrix: FrictionMatrix): string {
+ if (matrix.rows.length === 0) return "o2b install --friction β€” no adapters registered\n";
+ const lines: string[] = ["o2b install --friction", "-".repeat(22)];
+ for (const row of matrix.rows) {
+ for (const cell of row.cells) {
+ lines.push(
+ ` ${row.target.padEnd(FRICTION_TARGET_WIDTH)}` +
+ `${cell.dimension.padEnd(FRICTION_DIMENSION_WIDTH)}${cell.value}`,
+ );
+ if (cell.detail !== null) lines.push(`${FRICTION_DETAIL_INDENT}${cell.detail}`);
+ }
+ lines.push("");
+ }
+ lines.push(
+ `${matrix.rows.length} runtime(s) Γ— ${matrix.dimensions.length} dimension(s), ` +
+ `derived from the fact table and the live adapter registry.`,
+ );
+ lines.push("");
+ return lines.join("\n");
+}
+
+export function renderFrictionJson(matrix: FrictionMatrix): string {
+ return installJson({
+ friction: {
+ dimensions: matrix.dimensions,
+ targets: matrix.rows.map((row) => ({
+ target: row.target,
+ label: row.label,
+ cells: row.cells,
+ })),
+ },
+ });
+}
+
+/**
+ * The diff: the dimensions the two hosts answer differently, and a count
+ * of the ones they do not. The shared dimensions are counted rather than
+ * printed - a diff that reprints everything is the table the reader
+ * already has - and the count is what keeps the silence from reading as
+ * "there was nothing else to compare".
+ */
+export function renderFrictionDiff(diff: FrictionDiff): string {
+ const lines: string[] = [
+ `o2b install --friction --base ${diff.base} --compare ${diff.compare}`,
+ "-".repeat(52),
+ ];
+ for (const difference of diff.differing) {
+ lines.push(` ${difference.dimension}`);
+ lines.push(` ${diff.base.padEnd(FRICTION_TARGET_WIDTH)}${difference.baseValue}`);
+ lines.push(` ${diff.compare.padEnd(FRICTION_TARGET_WIDTH)}${difference.compareValue}`);
+ }
+ lines.push("");
+ lines.push(
+ `${diff.differing.length} dimension(s) differ; ` +
+ `the other ${diff.shared} are answered identically and are not listed.`,
+ );
+ lines.push("");
+ return lines.join("\n");
+}
+
+export function renderFrictionDiffJson(diff: FrictionDiff): string {
+ return installJson({
+ friction_diff: {
+ base: diff.base,
+ compare: diff.compare,
+ shared: diff.shared,
+ differing: diff.differing.map((difference) => ({
+ dimension: difference.dimension,
+ base_value: difference.baseValue,
+ compare_value: difference.compareValue,
+ })),
+ },
+ });
+}
diff --git a/src/cli/install/uninstall-target.ts b/src/cli/install/uninstall-target.ts
index e4616586..055e5393 100644
--- a/src/cli/install/uninstall-target.ts
+++ b/src/cli/install/uninstall-target.ts
@@ -14,6 +14,7 @@ import { parseFlags } from "../argparse.ts";
import { defaultConfigPath, discoverConfig } from "../../core/config.ts";
import { defaultRegistry } from "../../core/install/registry.ts";
import "../../core/install/adapters/aider.ts";
+import "../../core/install/adapters/codex.ts";
import "../../core/install/adapters/copilot-cli.ts";
import "../../core/install/adapters/cursor.ts";
import "../../core/install/adapters/gemini-cli.ts";
diff --git a/src/cli/interrupt.ts b/src/cli/interrupt.ts
index e5458e5d..337b6826 100644
--- a/src/cli/interrupt.ts
+++ b/src/cli/interrupt.ts
@@ -127,6 +127,11 @@ const YIELDS_TO_EVENT_LOOP: Readonly<Record<Operation, boolean>> = Object.freeze
[OPERATION.architect]: false,
[OPERATION.reindex]: true,
[OPERATION.maintenance]: true,
+ // The session sweep is synchronous end to end: the walk and the hash
+ // pass are both sync fs calls, so a signal handler cannot run while it
+ // does. Leaving SIGINT alone keeps the keystroke lethal, which is the
+ // only way this pass can actually be stopped.
+ [OPERATION.sessions]: false,
});
/**
diff --git a/src/cli/json-helpers.ts b/src/cli/json-helpers.ts
index 2b4d644a..efdfb19a 100644
--- a/src/cli/json-helpers.ts
+++ b/src/cli/json-helpers.ts
@@ -51,6 +51,7 @@ export const COMMANDS_WITH_INTERNAL_JSON: ReadonlySet<string> = new Set([
"brain",
"search",
"vault",
+ "state",
"discipline",
"partner",
"doctor",
diff --git a/src/cli/main.ts b/src/cli/main.ts
index 6eca0228..f2c36bf1 100644
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -19,6 +19,7 @@ import {
setConfigValue,
validateTimezoneName,
} from "../core/config.ts";
+import { BrainConfigError } from "../core/brain/policy/errors.ts";
import { EGRESS_OUTCOME, redactForEgress } from "../core/egress/guard.ts";
import { listSecretReferences } from "../core/secret-ref.ts";
import { BRAIN_INDEX_REL } from "../core/brain/paths.ts";
@@ -34,6 +35,8 @@ import { handleBrainSubcommand } from "./brain.ts";
import { handleDisciplineSubcommand } from "./discipline.ts";
import { handlePartnerSubcommand } from "./partner.ts";
import { handleSearchSubcommand } from "./search.ts";
+import { handleStateSubcommand } from "./state.ts";
+import { installMcpSignalDrain, type McpSignalDrainHandle } from "./mcp-drain.ts";
import { handleVaultSubcommand } from "./vault.ts";
import {
NoVaultConfiguredError,
@@ -71,6 +74,11 @@ import { buildToolTable } from "../mcp/tools.ts";
import { evaluateToolCapabilities, type RuntimeCapabilityWindow } from "../mcp/capabilities.ts";
import { resolveToolSurface, toolSurfaceProfileNames } from "../mcp/profiles.ts";
import { TOOL_SCOPE, TOOL_SCOPES, isToolScope, type ToolScope } from "../mcp/tool-contract.ts";
+import {
+ INSTALL_TARGET_IDS,
+ isInstallTargetId,
+ type InstallTargetId,
+} from "../core/runtime/host-facts.ts";
// ── Subcommands ─────────────────────────────────────────────────────────────
@@ -601,6 +609,7 @@ async function cmdMcp(argv: string[]): Promise<number> {
scope: { type: "string" },
"writer-only": { type: "boolean" },
"tool-profile": { type: "string" },
+ "host-target": { type: "string" },
probe: { type: "boolean" },
json: { type: "boolean" },
transport: { type: "string", default: "stdio" },
@@ -631,6 +640,22 @@ async function cmdMcp(argv: string[]): Promise<number> {
return 2;
}
+ // Which runtime launched this server. Written into the generated
+ // registration by the install adapter, and read back only by the
+ // capability report, which cites that host's published tool ceiling.
+ // An unrecognised value is refused rather than dropped: silently
+ // ignoring it would report the ceiling as unchecked on a host that
+ // publishes one, which is the exact silence this flag exists to end.
+ const hostTargetFlag = flags["host-target"] as string | undefined;
+ if (hostTargetFlag !== undefined && !isInstallTargetId(hostTargetFlag)) {
+ process.stderr.write(
+ `o2b mcp: invalid --host-target value: ${hostTargetFlag}; ` +
+ `expected one of: ${INSTALL_TARGET_IDS.join(", ")}\n`,
+ );
+ return 2;
+ }
+ const hostTarget = hostTargetFlag as InstallTargetId | undefined;
+
const config = (flags["config"] as string | undefined) ?? defaultConfigPath();
const transport = flags["transport"] as string;
if (transport !== "stdio" && transport !== "http") {
@@ -685,6 +710,7 @@ async function cmdMcp(argv: string[]): Promise<number> {
serverName,
json: Boolean(flags["json"]),
capabilityWindow,
+ hostTarget,
});
}
@@ -706,7 +732,7 @@ async function cmdMcp(argv: string[]): Promise<number> {
const handle = await startHttp(
{ vault, configPath: config, repoRoot },
{ host, port, apiKey },
- { scope, serverName, capabilityWindow },
+ { scope, serverName, capabilityWindow, hostTarget },
);
// Log the actually-bound endpoint. With the default --port 0 the OS
// assigns an ephemeral port, so the requested `port` value ("0") would
@@ -714,20 +740,43 @@ async function cmdMcp(argv: string[]): Promise<number> {
process.stderr.write(
`[mcp] ${serverName} ${SERVER_VERSION} listening on ${handle.url} (vault=${vault})\n`,
);
- // `closed` rather than `resolve`: this module imports `resolve` from
- // `node:path`, and shadowing it here hid that import inside the closure.
- await new Promise<void>((closed) => handle.server.once("close", closed));
- return 0;
+ // A served transport outlives every other verb in this CLI, so it is
+ // the one place a shutdown signal has work to do: stop accepting,
+ // finish what is running, then let the registered `exit` hooks
+ // checkpoint the index and release the locks. Released in a `finally`
+ // because the listeners are process-global.
+ const signals = installMcpSignalDrain({ close: () => handle.close() });
+ try {
+ // `closed` rather than `resolve`: this module imports `resolve` from
+ // `node:path`, and shadowing it here hid that import inside the closure.
+ await new Promise<void>((closed) => handle.server.once("close", closed));
+ } finally {
+ signals.release();
+ }
+ return signals.exitCode() ?? 0;
}
process.stderr.write(
`[mcp] ${serverName} ${SERVER_VERSION} listening on stdio (vault=${vault})\n`,
);
- return await serveStdio(
- { vault, configPath: config, repoRoot },
- {},
- { scope, serverName, capabilityWindow },
- );
+ // A holder rather than a `let`, because the assignment happens inside a
+ // callback: the compiler cannot see that it ran and would narrow a bare
+ // binding to `null` at both reads below.
+ const stdio: { signals: McpSignalDrainHandle | null } = { signals: null };
+ try {
+ const code = await serveStdio(
+ { vault, configPath: config, repoRoot },
+ {
+ onStart: (transport) => {
+ stdio.signals = installMcpSignalDrain({ close: () => transport.close() });
+ },
+ },
+ { scope, serverName, capabilityWindow, hostTarget },
+ );
+ return stdio.signals?.exitCode() ?? code;
+ } finally {
+ stdio.signals?.release();
+ }
}
function parseCapabilityWindow(
@@ -759,6 +808,7 @@ async function runMcpProbe(args: {
serverName: string;
json: boolean;
capabilityWindow: RuntimeCapabilityWindow | undefined;
+ hostTarget: InstallTargetId | undefined;
}): Promise<number> {
// The probe is an in-process MCP handshake: it counts the tools the
// server would advertise and exits. Used by `o2b install --check`
@@ -775,6 +825,7 @@ async function runMcpProbe(args: {
scope: args.scope,
serverName: args.serverName,
window: args.capabilityWindow,
+ hostTarget: args.hostTarget,
});
if (args.json) {
process.stdout.write(
@@ -998,6 +1049,8 @@ async function dispatchCommand(command: string, rest: string[]): Promise<number>
return await handleDisciplineSubcommand(rest);
case "search":
return await handleSearchSubcommand(rest);
+ case "state":
+ return await handleStateSubcommand(rest);
case "vault":
return await handleVaultSubcommand(rest);
case "partner":
@@ -1019,6 +1072,21 @@ async function dispatchCommand(command: string, rest: string[]): Promise<number>
if (exc instanceof ConfigReadError) {
return reportConfigReadError(exc, command, rest);
}
+ if (exc instanceof BrainConfigError) {
+ // Joins `NoVaultConfiguredError` on exit 1 for the reason stated at
+ // {@link reportConfigReadError}: nothing is wrong with the argv, the
+ // machine cannot answer. The message already names the file and the
+ // field, because {@link BrainConfigError} composes both.
+ //
+ // Reached from `o2b install` and `o2b update`, where the settings
+ // ladder reads `<vault>/Brain/_brain.yaml` and REFUSES an unreadable
+ // one rather than regenerating a default the operator never chose.
+ // The refusal is right; printing it as a stack trace was not, and it
+ // took every other target's status down with it - `detectAll` walks
+ // ten adapters and one of them reads that file.
+ process.stderr.write(`error: ${exc.message}\n`);
+ return 1;
+ }
throw exc;
}
}
diff --git a/src/cli/mcp-drain.ts b/src/cli/mcp-drain.ts
new file mode 100644
index 00000000..17366d23
--- /dev/null
+++ b/src/cli/mcp-drain.ts
@@ -0,0 +1,132 @@
+/**
+ * SIGTERM and SIGINT reach a running MCP server.
+ *
+ * `src/mcp/drain.ts` knows how to wait for in-flight requests and knows
+ * nothing about signals; `src/cli/interrupt.ts` owns this project's
+ * signal vocabulary - `SIGINT_EXIT = 130`, `SIGTERM_EXIT = 143` - and
+ * knows nothing about transports. This module is the ten lines that join
+ * them, and it lives on the CLI side because the process belongs to the
+ * CLI: a transport module reaching for `process.once("SIGTERM")` is how a
+ * project ends up with two signal conventions.
+ *
+ * ## Why it exits rather than re-raising
+ *
+ * `interrupt.ts` settles an unacknowledged signal by removing its own
+ * listeners and re-raising, so the default disposition ends the process
+ * the way the keystroke would have. That is right for a foreground verb
+ * and wrong here. Two `process.on("exit")` hooks have to run AFTER the
+ * transport closes - `src/core/search/store-exit.ts` synchronously
+ * checkpoints the WAL of every open writer, and
+ * `src/core/brain/sync-lockfile.ts` unlinks every held lock - and the
+ * default disposition for a terminating signal runs neither: the process
+ * dies by signal, not by exit, and no `exit` event is emitted. Calling
+ * `process.exit(128 + signo)` reports the same thing to the shell AND
+ * emits `exit`, so both hooks run, in their own registration order, once
+ * the last request has been answered. That ordering is the whole reason
+ * the drain has to complete before the exit rather than beside it.
+ *
+ * `process.once` rather than `process.on`, matching `interrupt.ts`: a
+ * SECOND signal is not intercepted and falls through to the default
+ * handler that kills immediately, so an operator who decides the drain is
+ * taking too long is never trapped by it.
+ */
+
+import { EXIT_INTERRUPTED, EXIT_TERMINATED } from "./interrupt.ts";
+import { describeAbandonedRequests, DRAIN_STATE, type DrainOutcome } from "../mcp/drain.ts";
+
+/** The signals a served transport shuts down for. */
+const HANDLED_SIGNALS = Object.freeze(["SIGINT", "SIGTERM"] as const);
+
+type HandledSignal = (typeof HANDLED_SIGNALS)[number];
+
+const EXIT_FOR_SIGNAL: Readonly<Record<HandledSignal, number>> = Object.freeze({
+ SIGINT: EXIT_INTERRUPTED,
+ SIGTERM: EXIT_TERMINATED,
+});
+
+/** The narrow slice of a stream this module writes to. */
+export interface DrainReportStream {
+ write(chunk: string): void;
+}
+
+export interface McpSignalDrainOptions {
+ /** Stop accepting, await in-flight work, close. Usually `handle.close`. */
+ readonly close: () => Promise<DrainOutcome>;
+ readonly stderr?: DrainReportStream;
+ /**
+ * How the process ends. Injected only by tests, which cannot let a
+ * real `process.exit` run; the product uses the real one, and it is
+ * the call that lets the registered `exit` hooks run.
+ */
+ readonly exit?: (code: number) => void;
+}
+
+export interface McpSignalDrainHandle {
+ /**
+ * The exit code for the signal that arrived, or `null` while none has.
+ *
+ * The caller returns it, because the caller is also awaiting the
+ * transport's own close and there is no ordering between "the close
+ * promise resolves" and "the handler's `exit` runs". Whichever wins,
+ * the process ends with the same code - the handler's `process.exit`
+ * and the verb's return value agree by construction rather than by
+ * timing.
+ */
+ readonly exitCode: () => number | null;
+ /**
+ * Stop listening. MUST be called when the server stops for a reason
+ * other than a signal: the listeners are process-global, and one left
+ * behind would drain a transport that has already gone.
+ */
+ readonly release: () => void;
+}
+
+/**
+ * Drain and close the transport when a shutdown signal arrives.
+ *
+ * Returns immediately; the work happens in the handler. A drain that hits
+ * its deadline still exits - the requests it gave up on are NAMED on
+ * stderr first, because a shutdown that silently truncates a tool call is
+ * indistinguishable from a crash to whoever was waiting on it.
+ */
+export function installMcpSignalDrain(opts: McpSignalDrainOptions): McpSignalDrainHandle {
+ const stderr = opts.stderr ?? process.stderr;
+ const exit = opts.exit ?? ((code: number) => process.exit(code));
+ const listeners = new Map<HandledSignal, () => void>();
+ let released = false;
+ let exitCode: number | null = null;
+
+ const release = (): void => {
+ if (released) return;
+ released = true;
+ for (const [name, listener] of listeners) process.removeListener(name, listener);
+ listeners.clear();
+ };
+
+ for (const name of HANDLED_SIGNALS) {
+ const listener = (): void => {
+ exitCode = EXIT_FOR_SIGNAL[name];
+ stderr.write(`[mcp] ${name} received; draining in-flight requests before closing\n`);
+ void opts
+ .close()
+ .then((outcome) => {
+ if (outcome.state === DRAIN_STATE.deadlineExpired) {
+ stderr.write(describeAbandonedRequests(outcome));
+ } else {
+ stderr.write(`[mcp] drained in ${outcome.waited_ms}ms; closing\n`);
+ }
+ })
+ .catch((error: unknown) => {
+ stderr.write(`[mcp] shutdown failed while draining: ${String(error)}\n`);
+ })
+ .finally(() => {
+ release();
+ exit(EXIT_FOR_SIGNAL[name]);
+ });
+ };
+ listeners.set(name, listener);
+ process.once(name, listener);
+ }
+
+ return Object.freeze({ exitCode: () => exitCode, release });
+}
diff --git a/src/cli/output.ts b/src/cli/output.ts
index 08f41d08..795c0c15 100644
--- a/src/cli/output.ts
+++ b/src/cli/output.ts
@@ -45,7 +45,49 @@ export function writeJson(
* expression of a catch arm so the subcommand keeps its single-exit shape.
*/
export function failWith(action: string, exc: unknown): number {
- const reason = (exc as Error)?.message ?? String(exc);
- process.stderr.write(`error: failed to ${action}: ${reason}\n`);
+ process.stderr.write(`error: failed to ${action}: ${describeErrorChain(exc)}\n`);
return 1;
}
+
+/** Upper bound on the `cause` chain rendered, since a chain can be cyclic. */
+const CAUSE_RENDER_LIMIT = 4;
+
+/**
+ * An error's message PLUS the chain of causes underneath it.
+ *
+ * Every catch arm in this CLI used to render `(exc as Error).message` and
+ * stop, which discards exactly the half of the error that says what actually
+ * happened. GitHub #167 is the case that made this expensive rather than
+ * untidy: the snapshot gate's id-exhaustion error attached the real failure
+ * as `cause`, the operator was shown only the summary, and the summary was
+ * wrong - the message described a full archive directory while the cause said
+ * `mkdir Brain/.snapshots` had failed. An error that constructs a `cause`
+ * has already decided the detail is load-bearing; the renderer is not the
+ * place to overrule it.
+ *
+ * A cause whose text the outer message already carries is skipped, because
+ * the common wrapper re-states its cause and `X: Y; caused by: Y` reads as
+ * two failures. The walk is bounded for the same reason the `cause` walk in
+ * `fs-atomic.ts` is: a chain can be made cyclic, and a hang while reporting
+ * an error is worse than a truncated report.
+ */
+export function describeErrorChain(exc: unknown): string {
+ let rendered = messageOf(exc);
+ let current: unknown = (exc as { readonly cause?: unknown })?.cause;
+ // The bound counts LINKS WALKED, not lines printed: a chain of repeated
+ // messages is skipped for being redundant, and counting only what is
+ // printed would let such a chain spin forever if it were cyclic.
+ for (let depth = 0; depth < CAUSE_RENDER_LIMIT; depth += 1) {
+ if (current === undefined || current === null) break;
+ const text = messageOf(current);
+ if (text.length > 0 && !rendered.includes(text)) rendered += `; caused by: ${text}`;
+ current = (current as { readonly cause?: unknown }).cause;
+ }
+ return rendered;
+}
+
+/** One error's own text, for anything a `throw` can carry. */
+function messageOf(exc: unknown): string {
+ const message = (exc as Error | null)?.message;
+ return typeof message === "string" && message.length > 0 ? message : String(exc);
+}
diff --git a/src/cli/state.ts b/src/cli/state.ts
new file mode 100644
index 00000000..0830ebb0
--- /dev/null
+++ b/src/cli/state.ts
@@ -0,0 +1,311 @@
+/**
+ * `o2b state` - the verbs that answer "where does this vault keep its
+ * state, and can it be moved".
+ *
+ * Only `status` exists today: an inventory, and nothing more. It is a
+ * dispatcher rather than a single verb from the first commit because the
+ * sibling that moves state (`state migrate` / `state rollback`) is a
+ * separate unit on the established `--dry-run` / `--apply --yes` ladder,
+ * and bolting a subcommand onto a flat verb later means reshaping the
+ * surface an operator has already learned.
+ *
+ * The report itself is built and rendered in `core/state/surfaces.ts`, so
+ * this file resolves inputs and picks a stream - the human sentence or the
+ * same value as JSON. It never composes a second copy of the report; that
+ * is the drift `renderDataOwnership` exists to prevent and this verb
+ * follows it.
+ */
+
+import { defaultConfigPath, discoverConfig } from "../core/config.ts";
+import {
+ applyStateMigration,
+ applyStateRollback,
+ planStateMigration,
+ planStateRollback,
+ renderMigrationPlan,
+ renderRollbackPlan,
+ StateMigrationError,
+ type MigrationPlan,
+ type RollbackPlan,
+} from "../core/state/migrate.ts";
+import { inventoryStateSurfaces, renderStateInventory } from "../core/state/surfaces.ts";
+import { parseFlags } from "./argparse.ts";
+import { readSingleLine } from "./brain/rollback-prompt.ts";
+import { requireVault, sortedReplacer } from "./helpers.ts";
+
+const USAGE = [
+ "usage: o2b state status [--vault <dir>] [--config <file>] [--json]",
+ " o2b state migrate --to <dir> [--vault <dir>] [--config <file>]",
+ " [--dry-run | --apply [--yes]] [--json]",
+ " o2b state rollback --from <dir> [--to <vault>] [--apply [--yes]] [--json]",
+].join("\n");
+
+/**
+ * Exit codes these verbs return.
+ *
+ * `refused` is separate from a crash on purpose. A migration that will
+ * not run, and a rollback that left files behind, are ANSWERS - the
+ * command did what it was asked and the answer is no. A supervisor that
+ * cannot tell them from a broken invocation retries the wrong one, so
+ * `2` stays reserved for a mistake in the argv.
+ */
+const STATE_EXIT = Object.freeze({ ok: 0, refused: 1, usage: 2 } as const);
+
+export async function handleStateSubcommand(argv: ReadonlyArray<string>): Promise<number> {
+ const verb = argv[0];
+ if (verb === undefined || verb === "-h" || verb === "--help") {
+ process.stdout.write(`${USAGE}\n`);
+ return verb === undefined ? STATE_EXIT.usage : STATE_EXIT.ok;
+ }
+ const rest = argv.slice(1);
+ switch (verb) {
+ case "status":
+ return cmdStateStatus(rest);
+ case "migrate":
+ return cmdStateMigrate(rest);
+ case "rollback":
+ return cmdStateRollback(rest);
+ default:
+ process.stderr.write(`error: unknown state verb: ${verb}\n${USAGE}\n`);
+ return STATE_EXIT.usage;
+ }
+}
+
+/**
+ * `o2b state status` - one row per declared state surface.
+ *
+ * Exit 0 whenever the inventory completed, including when a surface could
+ * not be probed. An `unchecked` verdict is an answer this command was
+ * asked for and it carries its own reason; turning it into a non-zero exit
+ * would make a reporting verb into a gate, and the gate already exists
+ * (`o2b doctor`).
+ */
+async function cmdStateStatus(argv: ReadonlyArray<string>): Promise<number> {
+ const { flags } = parseFlags([...argv], {
+ vault: { type: "string" },
+ config: { type: "string" },
+ json: { type: "boolean" },
+ });
+ const configPath = (flags["config"] as string | undefined) ?? defaultConfigPath();
+ const vault = requireVault(flags["vault"] as string | undefined, configPath);
+ const inventory = inventoryStateSurfaces({
+ vault,
+ env: process.env,
+ config: discoverConfig(configPath).data,
+ });
+ process.stdout.write(
+ flags["json"]
+ ? `${JSON.stringify(inventory, sortedReplacer, 2)}\n`
+ : renderStateInventory(inventory),
+ );
+ return STATE_EXIT.ok;
+}
+
+/**
+ * `o2b state migrate --to <dir>` - move the vault's state, or say why not.
+ *
+ * The ladder is `brain upgrade`'s, verb for verb: `--dry-run` and
+ * `--apply` are mutually exclusive, a bare invocation plans, `--apply`
+ * without `--yes` is refused whenever nobody can answer a prompt
+ * (`--json`, or a non-TTY stdin), and the TTY prompt accepts only `y` or
+ * `yes`. It is copied rather than reinvented because an operator who has
+ * learned one destructive verb in this CLI has learned all of them.
+ */
+async function cmdStateMigrate(argv: ReadonlyArray<string>): Promise<number> {
+ const { flags } = parseFlags([...argv], {
+ to: { type: "string" },
+ vault: { type: "string" },
+ config: { type: "string" },
+ "dry-run": { type: "boolean" },
+ apply: { type: "boolean" },
+ yes: { type: "boolean" },
+ json: { type: "boolean" },
+ });
+ const asJson = Boolean(flags["json"]);
+ const destination = flags["to"] as string | undefined;
+ if (destination === undefined || destination.trim() === "") {
+ process.stderr.write(`error: state migrate requires --to <dir>\n${USAGE}\n`);
+ return STATE_EXIT.usage;
+ }
+ if (flags["dry-run"] && flags["apply"]) {
+ process.stderr.write("error: state migrate: --dry-run and --apply are mutually exclusive\n");
+ return STATE_EXIT.usage;
+ }
+
+ const configPath = (flags["config"] as string | undefined) ?? defaultConfigPath();
+ const vault = requireVault(flags["vault"] as string | undefined, configPath);
+
+ let plan: MigrationPlan;
+ try {
+ plan = planStateMigration({
+ vault,
+ destination,
+ env: process.env,
+ config: discoverConfig(configPath).data,
+ });
+ } catch (exc) {
+ process.stderr.write(`error: state migrate could not plan: ${(exc as Error).message}\n`);
+ return STATE_EXIT.refused;
+ }
+
+ if (!flags["apply"]) {
+ writePlan(plan, asJson);
+ return plan.refusals.length > 0 ? STATE_EXIT.refused : STATE_EXIT.ok;
+ }
+ if (plan.refusals.length > 0) {
+ writePlan(plan, asJson);
+ return STATE_EXIT.refused;
+ }
+ if (plan.manifest.entries.length === 0) {
+ writePlan(plan, asJson);
+ if (!asJson) process.stdout.write("state migrate: nothing to move.\n");
+ return STATE_EXIT.ok;
+ }
+ if (!flags["yes"]) {
+ if (asJson || !process.stdin.isTTY) {
+ process.stderr.write(
+ "error: state migrate --apply requires --yes in non-interactive mode " +
+ "(--json or non-TTY stdin)\n",
+ );
+ return STATE_EXIT.usage;
+ }
+ process.stderr.write(
+ `${renderMigrationPlan(plan)}About to MOVE ${plan.manifest.entries.length} file(s) ` +
+ `(${plan.manifest.total_bytes} bytes) out of ${plan.source}.\n` +
+ `A manifest is written to ${plan.destination} so \`o2b state rollback --from ` +
+ `${plan.destination}\` can put them back.\nProceed? [y/N] `,
+ );
+ const answer = (await readSingleLine()).toLowerCase();
+ if (answer !== "y" && answer !== "yes") {
+ process.stdout.write("state migrate cancelled\n");
+ return STATE_EXIT.ok;
+ }
+ }
+
+ try {
+ const result = applyStateMigration(plan);
+ if (asJson) {
+ process.stdout.write(`${JSON.stringify({ plan, result }, sortedReplacer, 2)}\n`);
+ } else {
+ process.stdout.write(
+ `state migrate: moved ${result.moved.length} file(s), ${result.bytes} byte(s).\n` +
+ `manifest: ${result.manifest_path}\n` +
+ `roll back with: o2b state rollback --from ${plan.destination} --apply --yes\n`,
+ );
+ }
+ return STATE_EXIT.ok;
+ } catch (exc) {
+ if (exc instanceof StateMigrationError) {
+ process.stderr.write(`error: ${exc.message}\n`);
+ return STATE_EXIT.refused;
+ }
+ throw exc;
+ }
+}
+
+/**
+ * `o2b state rollback --from <dir>` - put back what still matches.
+ *
+ * The refusal list is part of the exit contract rather than a warning
+ * nobody reads: a rollback that left files behind exits `1` even when
+ * everything it DID do succeeded, because "restored 4 of 5" is not a
+ * success and a supervisor reading only the exit code has to be told so.
+ */
+async function cmdStateRollback(argv: ReadonlyArray<string>): Promise<number> {
+ const { flags } = parseFlags([...argv], {
+ from: { type: "string" },
+ to: { type: "string" },
+ "dry-run": { type: "boolean" },
+ apply: { type: "boolean" },
+ yes: { type: "boolean" },
+ json: { type: "boolean" },
+ });
+ const asJson = Boolean(flags["json"]);
+ const from = flags["from"] as string | undefined;
+ // `--to` is the answer to a vault that has MOVED since the migration.
+ // The manifest records an absolute source root, and without an override
+ // a renamed vault leaves the rollback with nowhere honest to put the
+ // files; the plan refuses that case by name and points here.
+ const to = flags["to"] as string | undefined;
+ if (from === undefined || from.trim() === "") {
+ process.stderr.write(
+ "error: state rollback requires --from <dir>: the directory a migration was moved TO, " +
+ `which is where its manifest was written\n${USAGE}\n`,
+ );
+ return STATE_EXIT.usage;
+ }
+ if (flags["dry-run"] && flags["apply"]) {
+ process.stderr.write("error: state rollback: --dry-run and --apply are mutually exclusive\n");
+ return STATE_EXIT.usage;
+ }
+
+ let plan: RollbackPlan;
+ try {
+ plan = planStateRollback({
+ destination: from,
+ ...(to === undefined || to.trim() === "" ? {} : { vault: to }),
+ });
+ } catch (exc) {
+ process.stderr.write(`error: state rollback could not plan: ${(exc as Error).message}\n`);
+ return STATE_EXIT.refused;
+ }
+
+ if (!flags["apply"]) {
+ process.stdout.write(
+ asJson ? `${JSON.stringify(plan, sortedReplacer, 2)}\n` : renderRollbackPlan(plan),
+ );
+ return plan.refusals.length > 0 ? STATE_EXIT.refused : STATE_EXIT.ok;
+ }
+ if (!flags["yes"]) {
+ if (asJson || !process.stdin.isTTY) {
+ process.stderr.write(
+ "error: state rollback --apply requires --yes in non-interactive mode " +
+ "(--json or non-TTY stdin)\n",
+ );
+ return STATE_EXIT.usage;
+ }
+ process.stderr.write(
+ `${renderRollbackPlan(plan)}About to restore ${plan.restore.length} file(s) to ` +
+ `${plan.source}.\nProceed? [y/N] `,
+ );
+ const answer = (await readSingleLine()).toLowerCase();
+ if (answer !== "y" && answer !== "yes") {
+ process.stdout.write("state rollback cancelled\n");
+ return STATE_EXIT.ok;
+ }
+ }
+
+ try {
+ const result = applyStateRollback(plan);
+ if (asJson) {
+ process.stdout.write(`${JSON.stringify({ plan, result }, sortedReplacer, 2)}\n`);
+ } else {
+ process.stdout.write(
+ `state rollback: restored ${result.restored.length} file(s) to ${plan.source}.\n`,
+ );
+ if (result.refused.length > 0) {
+ process.stdout.write(
+ `${result.refused.length} file(s) were left at ${plan.destination}; the manifest is ` +
+ "kept so they stay traceable:\n" +
+ result.refused
+ .map((refusal) => ` - ${refusal.relative_path} (${refusal.code})\n`)
+ .join(""),
+ );
+ }
+ }
+ return result.refused.length > 0 ? STATE_EXIT.refused : STATE_EXIT.ok;
+ } catch (exc) {
+ if (exc instanceof StateMigrationError) {
+ process.stderr.write(`error: ${exc.message}\n`);
+ return STATE_EXIT.refused;
+ }
+ throw exc;
+ }
+}
+
+/** One plan, one place it reaches a stream. */
+function writePlan(plan: MigrationPlan, asJson: boolean): void {
+ const stream = plan.refusals.length > 0 ? process.stderr : process.stdout;
+ if (asJson) process.stdout.write(`${JSON.stringify(plan, sortedReplacer, 2)}\n`);
+ else stream.write(renderMigrationPlan(plan));
+}
diff --git a/src/cli/update.ts b/src/cli/update.ts
index d4f8d88f..c9eae15c 100644
--- a/src/cli/update.ts
+++ b/src/cli/update.ts
@@ -15,6 +15,7 @@ import { parseFlags } from "./argparse.ts";
import { defaultConfigPath, discoverConfig, resolveVault } from "../core/config.ts";
import { defaultRegistry } from "../core/install/registry.ts";
import "../core/install/adapters/aider.ts";
+import "../core/install/adapters/codex.ts";
import "../core/install/adapters/copilot-cli.ts";
import "../core/install/adapters/cursor.ts";
import "../core/install/adapters/gemini-cli.ts";
@@ -50,9 +51,14 @@ export function parseUpdateArgs(argv: string[]): ParsedUpdateArgs {
}
function buildEnv(): InstallEnv {
- const cfg = discoverConfig(defaultConfigPath()).data;
+ const configPath = defaultConfigPath();
+ const cfg = discoverConfig(configPath).data;
const vault = resolveVault() ?? "";
const env = { ...process.env } as Record<string, string>;
+ // The one config file this run is parameterised by, published where
+ // `installSettingsSource` reads it - see `buildInstallEnv` in
+ // `./install/install.ts` for why the adapters may not re-derive it.
+ env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
if (cfg["agent_name"]) env["VAULT_AGENT_NAME"] = cfg["agent_name"];
if (cfg["timezone"]) env["VAULT_TIMEZONE"] = cfg["timezone"];
return { vault, home: homedir(), cwd: process.cwd(), env, now: new Date() };
diff --git a/src/core/brain/config-template.ts b/src/core/brain/config-template.ts
index 1acc07b7..d7d8bcb7 100644
--- a/src/core/brain/config-template.ts
+++ b/src/core/brain/config-template.ts
@@ -51,6 +51,9 @@ import {
BRAIN_TEMPORAL_DEFAULTS,
DEFAULT_BRAIN_CONFIG,
INJECT_BUDGET_CHARS_DEFAULT,
+ INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT,
+ INSTALL_TOOL_PROFILE_DEFAULT,
+ INSTALL_TOOL_PROFILE_NAMES,
LESSONS_CORROBORATION_MIN_DEFAULT,
LESSONS_HALF_LIFE_DAYS_DEFAULT,
LESSONS_LIMIT_DEFAULT,
@@ -470,6 +473,36 @@ export const BRAIN_CONFIG_TEMPLATE: ReadonlyArray<BrainTemplateBlock> = Object.f
]),
],
},
+ {
+ key: "install",
+ doc: [
+ "Inputs to GENERATED install and hook output (`o2b install`).",
+ "They live here rather than in the machine-local config.yaml",
+ "because install verification re-CONSTRUCTS the expected file",
+ "instead of storing a hash: two machines that clone this vault",
+ "must rebuild the same bytes, or each reports the other's correct",
+ "install as drift. An environment variable still wins over both.",
+ ],
+ emit: "commented-default",
+ keys: [
+ def("hook_timeout_seconds", INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT, [
+ "Seconds a generated lifecycle hook entry may run before the host",
+ "kills it. Every hook runs inside a turn the operator is waiting",
+ "on, so the ceiling is ten minutes; a larger number is a unit",
+ "error rather than an intent.",
+ ]),
+ def("tool_profile", INSTALL_TOOL_PROFILE_DEFAULT, [
+ "Named MCP tool-surface profile the generated registration",
+ `selects (${INSTALL_TOOL_PROFILE_NAMES.join(", ")}). Setting it`,
+ "here overrides the per-host choice: a runtime that publishes a",
+ "tool ceiling (Cursor caps a workspace at 40) gets the bounded",
+ "profile its RUNTIME_FACTS row declares, and every other runtime",
+ "gets no profile at all, which advertises every tool. An unknown",
+ "name is refused here, not failed open: generating a registration",
+ "for a profile that does not exist installs a surface nobody named.",
+ ]),
+ ],
+ },
{
key: "notes",
doc: [
diff --git a/src/core/brain/dream-apply.ts b/src/core/brain/dream-apply.ts
index a0431d2a..aab0687f 100644
--- a/src/core/brain/dream-apply.ts
+++ b/src/core/brain/dream-apply.ts
@@ -27,6 +27,7 @@ import { existsSync, renameSync } from "node:fs";
import { appendDecisionChangeReceipt } from "./decisions/receipts.ts";
import { preferenceSlug, type PlanState } from "./dream-plan.ts";
+import { SafeguardAbortError, SafeguardTimeoutError, type Safeguard } from "./safeguard.ts";
import type { RefreshResult } from "./dream-refresh.ts";
import type { DreamGatedRetireEntry } from "./dream-types.ts";
import { WORKRUN_PHASE, type WorkrunHandle } from "./dream-workrun.ts";
@@ -65,6 +66,14 @@ export interface DreamApplyInput {
readonly wikilinkToRun: string;
/** Resolved `dream.heal_enrich` gate for this run. */
readonly healEnrichEnabled: boolean;
+ /**
+ * The pass's cooperative deadline, forwarded to the one sub-unit here
+ * that is unbounded in the vault's size: the opt-in heal enrichment,
+ * which reads and rewrites every user page outside `Brain/`. Nothing
+ * else in this module iterates over anything but the decided plan, so
+ * nothing else needs it.
+ */
+ readonly safeguard?: Safeguard;
readonly workrun: WorkrunHandle | null;
}
@@ -112,7 +121,9 @@ export function applyDreamPlan(input: DreamApplyInput): DreamApplyResult {
workrun?.checkpoint(WORKRUN_PHASE.retireComplete);
const moved = moveConsumedSignals(vault, plan);
- const healEnriched = input.healEnrichEnabled ? runHealEnrichmentSafely(vault) : 0;
+ const healEnriched = input.healEnrichEnabled
+ ? runHealEnrichmentSafely(vault, input.safeguard)
+ : 0;
// Heal's second half (the optional enrichment) is durable here; its
// first half was the retire loop above. The marker sits at the later
@@ -348,11 +359,22 @@ function moveConsumedSignals(vault: string, plan: PlanState): string[] {
* retire/move mutations (heal-after-mutations). Off by default so the
* default install stays byte-identical; a failure is a warning, never
* fatal to the dream pass.
+ *
+ * A SAFEGUARD STOP IS NOT SUCH A FAILURE, and the difference is the whole
+ * reason this catch is narrowed. "Heal could not enrich a page" is a
+ * hygiene miss the pass survives; "the operator cancelled" and "the pass
+ * is past its budget" are decisions about the RUN, and swallowing either
+ * into a stderr warning plus `0` would report a pass that enriched
+ * nothing where the truth is a pass that was stopped. The pass's own
+ * post-mutation checkpoint would throw an instant later anyway - so
+ * absorbing it here only ever bought a wrong `heal_enriched: 0` on the
+ * way to the same error.
*/
-function runHealEnrichmentSafely(vault: string): number {
+function runHealEnrichmentSafely(vault: string, safeguard: Safeguard | undefined): number {
try {
- return runHealEnrichment(vault).enriched;
+ return runHealEnrichment(vault, safeguard ? { safeguard } : {}).enriched;
} catch (err) {
+ if (err instanceof SafeguardTimeoutError || err instanceof SafeguardAbortError) throw err;
process.stderr.write(`warning: heal enrichment failed: ${(err as Error).message}\n`);
return 0;
}
diff --git a/src/core/brain/dream-scan.ts b/src/core/brain/dream-scan.ts
index 0d8732d6..6a58708c 100644
--- a/src/core/brain/dream-scan.ts
+++ b/src/core/brain/dream-scan.ts
@@ -25,9 +25,60 @@ import { isTombstoned } from "./lifecycle/tombstone.ts";
import { brainDirs } from "./paths.ts";
import { parsePreference } from "./preference.ts";
import { parseSignal } from "./signal.ts";
+import {
+ OPERATION,
+ progressCounter,
+ withProgress,
+ type ProgressCounter,
+ type ProgressSink,
+} from "./progress.ts";
+import type { Safeguard } from "./safeguard.ts";
const MARKDOWN_EXT = ".md";
+/** The one stage this read has: it walks the four Brain directories. */
+const SCAN_STAGE = "scan";
+
+/**
+ * What a caller may hand the scan.
+ *
+ * Both members are optional and absence means nobody asked, which is the
+ * house observer idiom. They arrived together because the scan is one of
+ * the two units `runDreamStep` runs on its own: reached that way it is a
+ * whole call rather than a phase of one, and a call that can walk a large
+ * tree needs a deadline and something to say while it does.
+ */
+export interface ScanBrainOptions {
+ /**
+ * Cooperative deadline; checked once per file read and once per
+ * directory.
+ *
+ * `dream()` DOES pass this one, and the asymmetry with `onProgress`
+ * below is deliberate rather than an oversight. A deadline is about the
+ * wall-clock the work costs, and the work costs the same inside a pass
+ * as it does on its own: the scan is where a large `Brain/` tree is
+ * read, so a pass whose scan was unguarded would sit past its budget
+ * with the next checkpoint hundreds of files away. A stream, by
+ * contrast, is about who is speaking, and inside a pass that is the
+ * pass.
+ */
+ readonly safeguard?: Safeguard;
+ /**
+ * Where this scan reports, when it is the whole run.
+ *
+ * `dream()` deliberately does NOT pass one: its own counter already
+ * owns a `scan` stage and hands the same sink a second stream would
+ * duplicate. A counter with no sink emits nothing, so the pass costs
+ * the full run exactly what it did before.
+ */
+ readonly onProgress?: ProgressSink;
+}
+
+/** The per-file boundary every collector crosses: deadline, then tick. */
+interface DirectoryWalk {
+ step(): void;
+}
+
/** Absolute paths of the `.md` files directly inside `dir`, or nothing when it does not exist. */
function markdownFilesIn(dir: string): string[] {
if (!existsSync(dir)) return [];
@@ -43,12 +94,14 @@ function markdownFilesIn(dir: string): string[] {
* the `active` flag they stamp on each record, so they share this walk.
*/
function collectSignals(
- dir: string,
+ files: ReadonlyArray<string>,
active: boolean,
signals: SignalRecord[],
corrupted: CorruptedEntry[],
+ walk: DirectoryWalk,
): void {
- for (const full of markdownFilesIn(dir)) {
+ for (const full of files) {
+ walk.step();
// Belief lifecycle suite (t_7d5a3589): a tombstoned signal is
// excluded from the dream pass so it is never re-clustered.
if (isTombstoned(parseFrontmatter(full)[0])) continue;
@@ -61,11 +114,13 @@ function collectSignals(
}
function collectPreferences(
- dir: string,
+ files: ReadonlyArray<string>,
preferences: PreferenceRecord[],
corrupted: CorruptedEntry[],
+ walk: DirectoryWalk,
): void {
- for (const full of markdownFilesIn(dir)) {
+ for (const full of files) {
+ walk.step();
const rawMeta = parseFrontmatter(full)[0];
if (isTombstoned(rawMeta)) continue;
// Belief lifecycle suite (A4): capture the raw superseded_by pointer
@@ -83,8 +138,14 @@ function collectPreferences(
}
}
-function collectRetired(dir: string, retired: RetiredRecord[], corrupted: CorruptedEntry[]): void {
- for (const full of markdownFilesIn(dir)) {
+function collectRetired(
+ files: ReadonlyArray<string>,
+ retired: RetiredRecord[],
+ corrupted: CorruptedEntry[],
+ walk: DirectoryWalk,
+): void {
+ for (const full of files) {
+ walk.step();
// Retired files we only need for topic + id (for supersede
// bookkeeping) plus the optional `user_rejected_reason` that
// drives signal-suppression (v0.10.1, _summary Β§6). We do a
@@ -121,17 +182,63 @@ function collectRetired(dir: string, retired: RetiredRecord[], corrupted: Corrup
* no clock and touches nothing on disk, which is why it is the one part of
* the pass that is provably runnable on its own (see `dream-step.ts`).
*/
-export function scanBrain(vault: string): ScanResult {
+export function scanBrain(vault: string, opts: ScanBrainOptions = {}): ScanResult {
+ const progress = progressCounter(OPERATION.dream, opts.onProgress);
+ return withProgress(progress, () => scanBrainRun(vault, opts, progress));
+}
+
+function scanBrainRun(
+ vault: string,
+ opts: ScanBrainOptions,
+ progress: ProgressCounter,
+): ScanResult {
const dirs = brainDirs(vault);
+ // The four listings are `readdirSync` with no parse, so front-loading
+ // them costs a directory read each and buys the stage its denominator:
+ // the file count IS the unit this stage ticks in, and a reader watching
+ // a bare counter cannot tell a scan a tenth of the way through from one
+ // about to finish. The stage still opens before the first checkpoint,
+ // so an already-elapsed guard leaves a stream that spoke once.
+ const inbox = markdownFilesIn(dirs.inbox);
+ const processed = markdownFilesIn(dirs.processed);
+ const preferenceFiles = markdownFilesIn(dirs.preferences);
+ const retiredFiles = markdownFilesIn(dirs.retired);
+ progress.start(
+ SCAN_STAGE,
+ inbox.length + processed.length + preferenceFiles.length + retiredFiles.length,
+ );
const signals: SignalRecord[] = [];
const preferences: PreferenceRecord[] = [];
const retired: RetiredRecord[] = [];
const corrupted: CorruptedEntry[] = [];
+ // One boundary for all four collectors: the per-file read is where the
+ // work is, so it is where the deadline is honoured and where a reader
+ // learns the scan is still moving. Collapsed into one object because
+ // four collectors taking two more parameters each is four chances to
+ // thread one of them and forget the other.
+ const walk: DirectoryWalk = {
+ step: () => {
+ opts.safeguard?.checkpoint();
+ progress.advance(SCAN_STAGE);
+ },
+ };
- collectSignals(dirs.inbox, true, signals, corrupted);
- collectSignals(dirs.processed, false, signals, corrupted);
- collectPreferences(dirs.preferences, preferences, corrupted);
- collectRetired(dirs.retired, retired, corrupted);
+ // The directory boundary is a checkpoint too, and not only for
+ // symmetry: a tree with no markdown in it crosses no per-file boundary
+ // at all, and a deadline that only a populated vault can trip is a
+ // deadline that is absent exactly where a caller cannot predict it.
+ // The tick stays per file - a directory is not a unit of work a reader
+ // can count.
+ const collectors: ReadonlyArray<() => void> = [
+ () => collectSignals(inbox, true, signals, corrupted, walk),
+ () => collectSignals(processed, false, signals, corrupted, walk),
+ () => collectPreferences(preferenceFiles, preferences, corrupted, walk),
+ () => collectRetired(retiredFiles, retired, corrupted, walk),
+ ];
+ for (const collect of collectors) {
+ opts.safeguard?.checkpoint();
+ collect();
+ }
return { signals, preferences, retired, corrupted };
}
diff --git a/src/core/brain/dream-step.ts b/src/core/brain/dream-step.ts
index 8928adb0..b79122f0 100644
--- a/src/core/brain/dream-step.ts
+++ b/src/core/brain/dream-step.ts
@@ -43,6 +43,8 @@ import { scanBrain } from "./dream.ts";
import { DREAM_PHASE, type DreamPhase } from "./dream-phases.ts";
import { runHealEnrichment } from "./heal-run.ts";
import { vaultRelative } from "./paths.ts";
+import type { ProgressSink } from "./progress.ts";
+import type { Safeguard } from "./safeguard.ts";
/** The units of dream work that are provably runnable on their own. */
export const DREAM_STEP = Object.freeze({
@@ -145,6 +147,28 @@ export interface DreamHealEnrichStepResult {
export type DreamStepResult = DreamScanStepResult | DreamHealEnrichStepResult;
+/**
+ * What a caller may hand a single-step request.
+ *
+ * A step is a whole call, not a phase of one: nothing above it holds a
+ * deadline or a stream, so both belong here and both are forwarded
+ * unchanged to whichever step runs. This is a DISPATCHER over two units
+ * of work and owns no counter of its own - each step opens exactly one
+ * stream, named for the stage it is - which is the same shape the
+ * maintenance lane takes over its four tasks, and for the same reason: a
+ * second counter here would put two terminators on one run.
+ *
+ * Until this existed the MCP `step` branch passed neither, so a step over
+ * a large tree held the server's event loop with no upper bound and said
+ * nothing while it did.
+ */
+export interface DreamStepOptions {
+ /** Cooperative deadline, honoured at the step's own iteration boundary. */
+ readonly safeguard?: Safeguard;
+ /** Where the step reports; absence means nobody asked. */
+ readonly onProgress?: ProgressSink;
+}
+
/**
* Run exactly one dream step, or refuse by name.
*
@@ -152,10 +176,14 @@ export type DreamStepResult = DreamScanStepResult | DreamHealEnrichStepResult;
* function cannot honour in full throws {@link DreamStepNotRunnableError}
* and writes nothing.
*/
-export function runDreamStep(vault: string, step: string): DreamStepResult {
+export function runDreamStep(
+ vault: string,
+ step: string,
+ opts: DreamStepOptions = {},
+): DreamStepResult {
switch (step) {
case DREAM_STEP.scan: {
- const scan = scanBrain(vault);
+ const scan = scanBrain(vault, opts);
return Object.freeze({
step: DREAM_STEP.scan,
partial: true,
@@ -167,7 +195,7 @@ export function runDreamStep(vault: string, step: string): DreamStepResult {
} satisfies DreamScanStepResult);
}
case DREAM_STEP.healEnrich: {
- const result = runHealEnrichment(vault);
+ const result = runHealEnrichment(vault, opts);
return Object.freeze({
step: DREAM_STEP.healEnrich,
partial: true,
diff --git a/src/core/brain/dream.ts b/src/core/brain/dream.ts
index 3163e187..f4f88233 100644
--- a/src/core/brain/dream.ts
+++ b/src/core/brain/dream.ts
@@ -214,7 +214,14 @@ function dreamRun(
// parse-errors) are surfaced separately so the planning phase
// can emit `skip-corrupted-frontmatter` log entries without
// aborting.
- const scan = scanBrain(vault);
+ //
+ // The guard goes in and the sink does not, and the two decisions
+ // have different reasons - see `ScanBrainOptions`. The scan is the
+ // largest unbounded read in the pass, so leaving it unguarded put
+ // the whole `Brain/` tree between two of the pass's five
+ // checkpoints; the stream, by contrast, is this counter's, which
+ // already owns a `scan` stage.
+ const scan = scanBrain(vault, opts.safeguard ? { safeguard: opts.safeguard } : {});
progress.advance(DREAM_STAGE.scan);
const intentReview = buildIntentReview(vault, { now });
progress.start(DREAM_STAGE.plan, scan.preferences.length);
@@ -345,6 +352,7 @@ function dreamRun(
agentName: opts.agentName,
wikilinkToRun,
healEnrichEnabled,
+ ...(opts.safeguard ? { safeguard: opts.safeguard } : {}),
workrun: handle,
});
return { applied, handle };
diff --git a/src/core/brain/export-transcripts.ts b/src/core/brain/export-transcripts.ts
new file mode 100644
index 00000000..3dad3bb9
--- /dev/null
+++ b/src/core/brain/export-transcripts.ts
@@ -0,0 +1,358 @@
+/**
+ * JSONL conversation records built from recorded session transcripts.
+ *
+ * Two capabilities already existed and were not connected: five adapters
+ * that read a runtime's session log, and an export surface that writes
+ * vault-derived bytes through the egress guard. Nothing carried the
+ * transcript corpus to anything a training or evaluation harness can read.
+ * This module is that carriage, and nothing else - it is reached only
+ * through `o2b brain export --format transcripts-jsonl`, never as a
+ * pipeline of its own, because the corpus serves a secondary operator
+ * persona and this product's thesis is preference distillation.
+ *
+ * ## The record shape, and why it is this one
+ *
+ * One JSON object per line, one object per CONVERSATION: a session
+ * identity plus its ordered messages. The alternative - one
+ * instruction/response PAIR per line, the shape a supervised fine-tuning
+ * harness eats directly - was considered and rejected, and the reason is
+ * worth stating because picking either silently is how a guess becomes an
+ * authoritative fact downstream.
+ *
+ * A pair set is a LOSSY PROJECTION of a conversation. Producing it means
+ * deciding which turn is the instruction, what to do with system and tool
+ * turns, and where a multi-turn exchange breaks into pairs - three
+ * judgements the runtime never recorded and this exporter cannot recover.
+ * A harness that wants pairs can derive them from a conversation; nothing
+ * can derive the conversation back from the pairs. So the superset is what
+ * leaves, and the pairing decision stays with the reader who knows which
+ * one they want.
+ *
+ * The cost, stated rather than discovered: one conversation is held in
+ * memory while its record is built. The line reader underneath never
+ * materialises the file (`sessions/read-lines.ts`), so the bound is the size of
+ * one session's text, not of the corpus or of the largest file.
+ *
+ * ## What a message carries
+ *
+ * Role, timestamp, turn id, text, and the NAMES of the tools the turn
+ * called. Not the tool inputs: those are host paths, command lines and
+ * pasted payloads, and this is a conversation dataset rather than a
+ * tool-trace one. A turn with neither text nor a tool call - a runtime
+ * queue event, a payload-less meta line - is not a message and is counted
+ * rather than emitted.
+ *
+ * ## What it refuses
+ *
+ * A `.jsonl` under the named source that no adapter recognises stops the
+ * export, naming the file. This is the same answer `collectExportRows`
+ * gives an unparseable preference, for the same reason: a corpus that
+ * quietly omits a transcript reads exactly like a machine that never
+ * recorded it, and the file that would say otherwise is the one the
+ * recipient does not have.
+ *
+ * A ZERO-BYTE file is the one thing that does not refuse, and is counted
+ * instead ({@link TranscriptExportSummary.empty}). It carries nothing to
+ * omit, Claude Code leaves them behind whenever a session is killed
+ * before its first turn flushes, and refusing on them made the export
+ * unusable against a real store.
+ *
+ * Redaction is NOT this module's job - it composes records, and the export
+ * verb hands each one to `redactForEgress` before any byte is written. The
+ * split is deliberate: the guard call belongs at the boundary that names
+ * the destination, which is where the egress census can see it.
+ */
+
+import { statSync } from "node:fs";
+import { basename } from "node:path";
+
+import { readFirstLine } from "./sessions/read-lines.ts";
+import { detectAdapter, getAdapter, SESSION_ADAPTER_REGISTRY } from "./sessions/registry.ts";
+import type { SessionAdapterRegistry } from "./sessions/registry.ts";
+import { sessionFilesUnder } from "./sessions/session-files.ts";
+import {
+ SESSION_TIMESTAMP_UNKNOWN,
+ SessionImportError,
+ type SessionTurn,
+} from "./sessions/types.ts";
+
+/**
+ * Versions the RECORD, not the corpus. A field added later is additive and
+ * needs no bump - a reader written against version 1 keeps working, the
+ * same contract `BRAIN_EXPORT_SCHEMA_VERSION` states for the
+ * preference envelope. A field that changes meaning is what would force it.
+ */
+export const TRANSCRIPT_EXPORT_SCHEMA_VERSION = 1 as const;
+
+/** One turn of a conversation, as a dataset row sees it. */
+export interface TranscriptMessage {
+ /** The adapter's own turn id - the join back to the source transcript. */
+ readonly turn_id: string;
+ readonly role: SessionTurn["role"];
+ readonly timestamp: string;
+ /** Flat text of the turn. Empty when the turn was only a tool call. */
+ readonly text: string;
+ /** Tool names, in call order. Absent when the turn called none. */
+ readonly tools?: ReadonlyArray<string>;
+}
+
+/** One session transcript, as one JSONL line. */
+export interface TranscriptConversation {
+ readonly schema: typeof TRANSCRIPT_EXPORT_SCHEMA_VERSION;
+ /** Adapter id the file was detected as (`claude`, `codex`, …). */
+ readonly runtime: string;
+ /**
+ * The transcript's basename, never its absolute path: the same portable
+ * identity `sessionRefIdentity` uses for imported provenance, so a
+ * dataset row and a vault signal join on one key and neither bakes in a
+ * host directory.
+ */
+ readonly session_id: string;
+ readonly started_at: string;
+ readonly ended_at: string;
+ readonly message_count: number;
+ readonly messages: ReadonlyArray<TranscriptMessage>;
+}
+
+export interface TranscriptExportOptions {
+ /** A transcript file, or a directory walked for `*.jsonl`. */
+ readonly source: string;
+ /** Keep only conversations recorded by this adapter id. */
+ readonly runtime?: string;
+ /** Keep conversations that STARTED at or after this instant. */
+ readonly since?: Date;
+ /** Keep conversations that STARTED strictly before this instant. */
+ readonly until?: Date;
+ /** Adapter set to detect against. Defaults to the shipped registry. */
+ readonly registry?: SessionAdapterRegistry;
+}
+
+/**
+ * What the walk did, returned when the stream ends.
+ *
+ * Every scanned file is accounted for by exactly one counter, so an empty
+ * export can say which filter emptied it. "No records" and "no transcripts
+ * to begin with" are different facts, and a caller that cannot tell them
+ * apart reports a filter typo as an idle machine.
+ */
+export interface TranscriptExportSummary {
+ readonly scanned: number;
+ readonly exported: number;
+ /** Recognised, but written by a runtime the filter excluded. */
+ readonly other_runtime: number;
+ /** Recognised, but started outside the requested window. */
+ readonly outside_window: number;
+ /** Recognised, and carrying no turn a dataset can learn from. */
+ readonly no_messages: number;
+ /**
+ * Holding no bytes at all, so there was nothing to detect a format
+ * from.
+ *
+ * Counted rather than refused, which is the one exception to the
+ * refuse-what-you-cannot-read rule below, and it is not a softening of
+ * it. A zero-byte transcript is not a file this walk failed to
+ * understand - it is a file with no content to understand, which is
+ * what Claude Code leaves behind routinely when a session opens and the
+ * process is killed before the first turn flushes. Refusing on those
+ * made the whole export unusable against a real store and offered a
+ * remedy ("move this file out of the source directory") that does not
+ * scale to a thousand of them. A file that HAS content no adapter
+ * recognises still refuses: there, something was recorded and this
+ * build cannot say what.
+ */
+ readonly empty: number;
+}
+
+/** Tool names of a turn, in call order. */
+function toolNames(turn: SessionTurn): ReadonlyArray<string> {
+ return (turn.toolCalls ?? []).map((call) => call.name);
+}
+
+/** A turn as a message, or `null` when it carries nothing to learn from. */
+function messageOf(turn: SessionTurn): TranscriptMessage | null {
+ const text = typeof turn.text === "string" ? turn.text : "";
+ const tools = toolNames(turn);
+ if (text.trim() === "" && tools.length === 0) return null;
+ return Object.freeze({
+ turn_id: turn.turnId,
+ role: turn.role,
+ timestamp: turn.timestamp,
+ text,
+ ...(tools.length > 0 ? { tools: Object.freeze([...tools]) } : {}),
+ });
+}
+
+/**
+ * The conversation's start as an instant, for the window comparison only.
+ *
+ * A timestamp this module cannot READ is refused rather than treated as
+ * either inside or outside the window: both readings are a guess, and one
+ * of them silently drops a transcript from the corpus. Only reached when a
+ * window is actually set - with no `--since` / `--until` nothing depends
+ * on the value, and refusing an export over a field nobody read would be a
+ * refusal for its own sake.
+ *
+ * "Cannot read" has TWO cases, and for a long time this function handled
+ * only the one that never happens. A string `Date.parse` rejects is the
+ * obvious case; it does not occur, because no adapter ever emits one. The
+ * case that does occur is {@link SESSION_TIMESTAMP_UNKNOWN}: every adapter
+ * synthesises the epoch when the line it read carried no clock, that
+ * parses perfectly well, and it sorts before any window an operator would
+ * type - so the transcript took the silently-dropped path this docblock
+ * forbids, on the exact input the guarantee was written for.
+ */
+function startInstant(record: TranscriptMessage, path: string): number {
+ if (record.timestamp === SESSION_TIMESTAMP_UNKNOWN) {
+ throw new SessionImportError(
+ "PARSE",
+ `the first turn of ${path} carries no timestamp - the runtime did not record one, and ` +
+ "the adapter reports that as the epoch - so --since / --until cannot say whether this " +
+ "conversation is in the window; drop the window flags to export it, or narrow " +
+ "--transcripts to the files that are timestamped",
+ );
+ }
+ const ms = Date.parse(record.timestamp);
+ if (!Number.isFinite(ms)) {
+ throw new SessionImportError(
+ "PARSE",
+ `cannot read the first timestamp of ${path} ('${record.timestamp}'), so --since / ` +
+ "--until cannot say whether this conversation is in the window; repair the " +
+ "transcript or drop the window flags",
+ );
+ }
+ return ms;
+}
+
+function inWindow(startedAtMs: number, options: TranscriptExportOptions): boolean {
+ if (options.since !== undefined && startedAtMs < options.since.getTime()) return false;
+ if (options.until !== undefined && startedAtMs >= options.until.getTime()) return false;
+ return true;
+}
+
+/**
+ * True when `path` holds zero bytes.
+ *
+ * A stat that fails answers `false` rather than `true`: the file was
+ * listed a moment ago, so a failure here is a race or a permission
+ * change, and reading that as "empty" would drop a transcript on the
+ * strength of an error. It falls through to the detect refusal, which
+ * names the file.
+ */
+function holdsNoBytes(path: string): boolean {
+ try {
+ return statSync(path).size === 0;
+ } catch {
+ return false;
+ }
+}
+
+/** Why a scanned file produced no record, when it produced none. */
+type SkipKind = "outside_window" | "no_messages";
+
+async function conversationOf(
+ path: string,
+ runtime: string,
+ iterate: AsyncIterable<SessionTurn>,
+ options: TranscriptExportOptions,
+): Promise<TranscriptConversation | SkipKind> {
+ const windowed = options.since !== undefined || options.until !== undefined;
+ const messages: TranscriptMessage[] = [];
+ for await (const turn of iterate) {
+ const message = messageOf(turn);
+ if (message === null) continue;
+ if (windowed && messages.length === 0 && !inWindow(startInstant(message, path), options)) {
+ // The window selects whole conversations by their start, so the rest
+ // of this file cannot change the answer and is never read.
+ return "outside_window";
+ }
+ messages.push(message);
+ }
+ if (messages.length === 0) return "no_messages";
+ return Object.freeze({
+ schema: TRANSCRIPT_EXPORT_SCHEMA_VERSION,
+ runtime,
+ session_id: basename(path),
+ started_at: messages[0]!.timestamp,
+ ended_at: messages[messages.length - 1]!.timestamp,
+ message_count: messages.length,
+ messages: Object.freeze(messages),
+ });
+}
+
+/**
+ * Stream one conversation record per recognised transcript under
+ * `options.source`, then return {@link TranscriptExportSummary}.
+ *
+ * A generator rather than an array: the caller writes each record as it
+ * arrives, so the corpus is never held whole. The summary rides out as the
+ * generator's RETURN value, which is why a caller that needs it drives
+ * `next()` itself instead of using `for await` - `for await` discards it,
+ * and a counter nobody can read is not a report.
+ *
+ * @throws SessionImportError when the source is unreadable, a file matches
+ * no adapter, or a window comparison meets an unparseable timestamp.
+ */
+export async function* streamTranscriptConversations(
+ options: TranscriptExportOptions,
+): AsyncGenerator<TranscriptConversation, TranscriptExportSummary> {
+ const registry = options.registry ?? SESSION_ADAPTER_REGISTRY;
+ // Resolved for its refusal, which names the registered set: an unknown
+ // `--runtime` would otherwise match nothing and report an empty corpus.
+ if (options.runtime !== undefined) getAdapter(options.runtime, registry);
+
+ const files = sessionFilesUnder(options.source);
+ let exported = 0;
+ let otherRuntime = 0;
+ let outsideWindow = 0;
+ let noMessages = 0;
+ let empty = 0;
+
+ for (const path of files) {
+ // oxlint-disable-next-line no-await-in-loop
+ const firstLine = await readFirstLine(path);
+ if (firstLine === "" && holdsNoBytes(path)) {
+ // Accounted for and stepped over - see `empty` on the summary for
+ // why this one case is not the refusal below. The size check is what
+ // keeps it to that case: `readFirstLine` also returns `""` for a
+ // file whose first line is blank and whose second line is a turn,
+ // and skipping THAT would be the silent omission the refusal exists
+ // to prevent.
+ empty += 1;
+ continue;
+ }
+ const adapter = detectAdapter(firstLine, registry);
+ if (adapter === null) {
+ throw new SessionImportError(
+ "DETECT_FAIL",
+ `could not autodetect a session format for ${path}; every *.jsonl under the ` +
+ "exported source must be a session transcript, so move this file out of the " +
+ "source directory or point --transcripts at one that holds only transcripts",
+ );
+ }
+ if (options.runtime !== undefined && adapter.id !== options.runtime) {
+ otherRuntime += 1;
+ continue;
+ }
+ // oxlint-disable-next-line no-await-in-loop
+ const record = await conversationOf(path, adapter.id, adapter.iterate(path), options);
+ if (record === "outside_window") {
+ outsideWindow += 1;
+ continue;
+ }
+ if (record === "no_messages") {
+ noMessages += 1;
+ continue;
+ }
+ exported += 1;
+ yield record;
+ }
+
+ return Object.freeze({
+ scanned: files.length,
+ exported,
+ other_runtime: otherRuntime,
+ outside_window: outsideWindow,
+ no_messages: noMessages,
+ empty,
+ });
+}
diff --git a/src/core/brain/export.ts b/src/core/brain/export.ts
index 5a5da437..e151c149 100644
--- a/src/core/brain/export.ts
+++ b/src/core/brain/export.ts
@@ -80,7 +80,42 @@ export class PreferenceParseError extends Error {
}
}
-export type ExportFormat = "json" | "llms-txt";
+/**
+ * What `o2b brain export --format` accepts.
+ *
+ * Closed, and a vocabulary rather than the type alias it used to be: the
+ * alias was declared here and imported by nobody, while the verb compared
+ * the raw argv string against two inline literals. A contract with nothing
+ * behind it is not a contract - adding a third format meant editing a
+ * comparison in the CLI and hoping this line was noticed. The guard is now
+ * the boundary the argv value crosses, and the object's key set is what the
+ * verb's dispatch table is typed against, so a format with no handler is a
+ * compile error.
+ *
+ * `transcripts-jsonl` names its shape on purpose. `json` and `llms-txt`
+ * each produce ONE document; this one produces a stream of records, and an
+ * operator who redirects it into a `.json` file learns that from the flag
+ * rather than from a parse error downstream.
+ */
+export const EXPORT_FORMAT = Object.freeze({
+ json: "json",
+ llmsTxt: "llms-txt",
+ transcriptsJsonl: "transcripts-jsonl",
+} as const);
+
+export type ExportFormat = (typeof EXPORT_FORMAT)[keyof typeof EXPORT_FORMAT];
+
+/** The formats, in the order the help text and the refusal message list them. */
+export const EXPORT_FORMATS: ReadonlyArray<ExportFormat> = Object.freeze([
+ EXPORT_FORMAT.json,
+ EXPORT_FORMAT.llmsTxt,
+ EXPORT_FORMAT.transcriptsJsonl,
+]);
+
+/** Takes `unknown`: the value arrives as a raw `--format` argument. */
+export function isExportFormat(value: unknown): value is ExportFormat {
+ return typeof value === "string" && (EXPORT_FORMATS as ReadonlyArray<string>).includes(value);
+}
export interface ExportedPreferenceRow {
readonly id: string;
diff --git a/src/core/brain/heal-run.ts b/src/core/brain/heal-run.ts
index cfefdad6..d4cfc948 100644
--- a/src/core/brain/heal-run.ts
+++ b/src/core/brain/heal-run.ts
@@ -26,6 +26,60 @@ import {
import { BRAIN_ROOT_REL } from "./paths.ts";
import { planHealEnrichmentPrepared, prepareHealPhrases } from "./heal-enrich.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
+import {
+ OPERATION,
+ progressCounter,
+ withProgress,
+ type ProgressCounter,
+ type ProgressSink,
+} from "./progress.ts";
+import type { Safeguard } from "./safeguard.ts";
+
+/** The one stage this pass has: it walks the vault's user pages. */
+const HEAL_ENRICH_STAGE = "heal-enrich";
+
+/**
+ * What a caller may hand the enrichment.
+ *
+ * Same pair, same reason as `ScanBrainOptions`: reached through
+ * `runDreamStep` this is the whole call, and it reads and rewrites every
+ * user page in the vault. Inside a full pass the dream run owns the
+ * counter and passes no sink, so the counter here stays inert and the
+ * pass costs what it did before - but it DOES pass the safeguard, because
+ * the enrichment is the same unbounded walk on either path.
+ *
+ * ## Exactly what the deadline bounds
+ *
+ * Cooperative means bounded at the boundaries the code crosses, and this
+ * pass has two phases that cross none. Naming them is the honest half of
+ * the contract:
+ *
+ * - {@link listVaultPages} walks the whole vault and parses the
+ * frontmatter of every page in one call. It is the first thing the
+ * run does and it is NOT interruptible: the deadline is honoured on
+ * the checkpoint immediately after it returns.
+ * - {@link prepareHealPhrases} sorts and regex-escapes the entire
+ * title/alias set in one native `toSorted` plus one map, and is NOT
+ * interruptible either. The deadline is honoured on the checkpoint
+ * immediately BEFORE it - so an already-elapsed budget never pays for
+ * the build - and again on the first page of the rewrite loop.
+ *
+ * Everything else - both per-page loops, read and rewrite alike - is
+ * checked once per page. So the guarantee is "stops within one page-read
+ * plus one listing plus one phrase build", not "stops within one page";
+ * `docs/mcp.md`'s `step` row says the same thing rather than claiming the
+ * whole step is bounded.
+ */
+export interface HealRunOptions {
+ /**
+ * Cooperative deadline; checked once per page in each of the two
+ * loops, plus once on each side of the two uninterruptible phases named
+ * above.
+ */
+ readonly safeguard?: Safeguard;
+ /** Where this pass reports, when it is the whole run. */
+ readonly onProgress?: ProgressSink;
+}
export interface HealRunResult {
/** Pages scanned (outside the Brain root). */
@@ -40,7 +94,16 @@ export interface HealRunResult {
* Run deterministic enrichment over the vault's user pages. Returns the
* scan/enrich counts. Writes only changed pages.
*/
-export function runHealEnrichment(vault: string): HealRunResult {
+export function runHealEnrichment(vault: string, opts: HealRunOptions = {}): HealRunResult {
+ const progress = progressCounter(OPERATION.dream, opts.onProgress);
+ return withProgress(progress, () => healEnrichmentRun(vault, opts, progress));
+}
+
+function healEnrichmentRun(
+ vault: string,
+ opts: HealRunOptions,
+ progress: ProgressCounter,
+): HealRunResult {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertVaultIdentityForWrite(vault);
// BRAIN_ROOT_REL is the Brain dir name relative to the vault (its
@@ -51,6 +114,20 @@ export function runHealEnrichment(vault: string): HealRunResult {
// config, or the trash.
const brainDir = BRAIN_ROOT_REL.split("/")[0] ?? "Brain";
const pages = listVaultPages(vault, { skipDirs: [...EXCLUDED_DIRS, brainDir] });
+ // The stage opens with its denominator, which is why it opens HERE and
+ // not before the listing: the page count is the one number a reader
+ // wants and it does not exist until the walk returns. It still opens
+ // BEFORE the first checkpoint, so a guard that has already elapsed
+ // produces a stream that spoke and then stopped rather than silence.
+ progress.start(HEAL_ENRICH_STAGE, pages.length);
+ // The listing walk is itself unbounded in the vault's size and crosses
+ // no per-page boundary, so the deadline is honoured once it returns -
+ // otherwise a vault with nothing to enrich could never trip one. It
+ // cannot be honoured DURING the walk without a safeguard parameter on
+ // `listVaultPages`, which every other caller of that walker would then
+ // carry; the header states the residual bound rather than implying one
+ // that does not exist.
+ opts.safeguard?.checkpoint();
// Build the known title/alias index from every page once, plus a
// per-page exclusion map so a page is never linked to its own title
@@ -58,6 +135,11 @@ export function runHealEnrichment(vault: string): HealRunResult {
const known = new Set<string>();
const ownTokens = new Map<string, Set<string>>();
for (const p of pages) {
+ // Both loops are per page and both are unbounded in the vault's size,
+ // so both honour the deadline. Only the second one ticks: one stage
+ // whose counter ran to the page count twice would report a pass of
+ // twice the length it has.
+ opts.safeguard?.checkpoint();
const own = new Set<string>();
if (p.title.trim().length > 0) {
known.add(p.title);
@@ -78,10 +160,20 @@ export function runHealEnrichment(vault: string): HealRunResult {
// Sort + regex-escape the whole known set ONCE; per page we only exclude
// that page's own few terms (see planHealEnrichmentPrepared) instead of
// re-sorting and recompiling the K-phrase set from scratch.
+ //
+ // That "once" is a single native sort over every title and alias in the
+ // vault - unbounded in the vault's size and crossing no boundary of its
+ // own, exactly like the listing above. The deadline is honoured here,
+ // before the build, so a guard that has already elapsed refuses to pay
+ // for it; the first page of the rewrite loop honours it on the far
+ // side. The build itself is not interruptible, and the header says so.
+ opts.safeguard?.checkpoint();
const prepared = prepareHealPhrases([...known]);
const changed: string[] = [];
for (const p of pages) {
+ opts.safeguard?.checkpoint();
+ progress.advance(HEAL_ENRICH_STAGE);
// Unit F: `parseFrontmatter` cannot throw (it reads inside its own
// try; everything after is string work), so the `catch { continue }`
// that stood here was unreachable - a page was never actually
diff --git a/src/core/brain/maintenance/lane.ts b/src/core/brain/maintenance/lane.ts
index a3bcd560..fc568108 100644
--- a/src/core/brain/maintenance/lane.ts
+++ b/src/core/brain/maintenance/lane.ts
@@ -53,7 +53,7 @@
*/
import { listRecallTelemetry } from "../recall-telemetry.ts";
-import { capOutput, SafeguardTimeoutError } from "../safeguard.ts";
+import { capOutput, OPERATION, SafeguardTimeoutError } from "../safeguard.ts";
import { loadMaintenanceConfigSafe } from "../policy/load.ts";
import { acquireLease, MAINTENANCE_LEASE_NAME, releaseLease } from "./lease.ts";
import {
@@ -73,6 +73,22 @@ export const MAINTENANCE_LEASE_TTL_MS = 30 * 60 * 1000;
export const MAINTENANCE_BUSY_THRESHOLD = 5;
/** Default busy lookback window in minutes. */
export const MAINTENANCE_BUSY_MINUTES = 10;
+/**
+ * Ceilings for the two busy-gate knobs, beside the defaults they bound
+ * rather than in whichever surface first needed them.
+ *
+ * A day is the longest lookback that still describes "recent interactive
+ * use"; past that the gate answers a different question than the one it
+ * was built for. Ten thousand queries in that day is well past any real
+ * traffic and is the point at which a number stops being a threshold and
+ * starts being a typo.
+ *
+ * They live here because BOTH front doors have to refuse the same
+ * values. They were an MCP-only constant, so `--busy-minutes 100000` was
+ * accepted on the CLI and refused over MCP - one lane, two contracts.
+ */
+export const MAINTENANCE_BUSY_MINUTES_MAX = 24 * 60;
+export const MAINTENANCE_BUSY_THRESHOLD_MAX = 10_000;
export interface DailyWindow {
/** Local hour [0..23] the window opens (inclusive). */
@@ -126,8 +142,61 @@ export interface MaintenanceGateDecision {
/** Cap for persisted per-task error strings (journal + results). */
const LANE_ERROR_MAX_BYTES = 4096;
+/**
+ * The heavy passes this lane dispatches.
+ *
+ * A closed vocabulary rather than four string literals because the names
+ * are read on THREE surfaces - the CLI verb's task list, the MCP tool's
+ * task list, and `--retry`/`retry_tasks` validation on both - and they
+ * were written out by hand on each. Two releases running, the two lists
+ * disagreed about what the lane runs, which is the drift a vocabulary
+ * exists to make impossible: a fifth task is added here or nowhere.
+ *
+ * The values come from {@link OPERATION} rather than being retyped, so a
+ * lane task is by construction an operation with a safeguard budget and a
+ * progress vocabulary of its own. That is not decoration: each surface
+ * builds one deadline per task from the task's own name, and a name that
+ * was not an operation would resolve a budget nothing reads.
+ *
+ * One consequence, stated rather than left to be discovered: the
+ * tree-wide vocabulary census reads values out of an object LITERAL, so
+ * borrowing them here keeps this vocabulary outside its population. The
+ * same audit - object, list and guard agree - runs in
+ * `tests/mcp/maintenance-parity-census.test.ts`, together with the
+ * assertion that every value is still an operation.
+ */
+export const LANE_TASK = Object.freeze({
+ dream: OPERATION.dream,
+ reindex: OPERATION.reindex,
+ bridges: OPERATION.bridges,
+ clusters: OPERATION.clusters,
+} as const);
+
+export type LaneTask = (typeof LANE_TASK)[keyof typeof LANE_TASK];
+
+/**
+ * Membership list for {@link isLaneTask}, in the order the surfaces
+ * register their tasks and the order a refusal lists them. The lane
+ * itself runs them stale-first, so this is a vocabulary, not a schedule.
+ */
+export const LANE_TASKS: ReadonlyArray<LaneTask> = Object.freeze([
+ LANE_TASK.dream,
+ LANE_TASK.reindex,
+ LANE_TASK.bridges,
+ LANE_TASK.clusters,
+]);
+
+/**
+ * Whether `value` names a task this build dispatches. Takes `unknown`
+ * because it arrives from a `--retry` argument a person typed or from a
+ * `retry_tasks` array a client sent.
+ */
+export function isLaneTask(value: unknown): value is LaneTask {
+ return typeof value === "string" && (LANE_TASKS as ReadonlyArray<string>).includes(value);
+}
+
export interface MaintenanceTask {
- readonly name: string;
+ readonly name: LaneTask;
readonly run: () => Promise<void>;
}
@@ -144,12 +213,12 @@ export interface RunMaintenanceOptions extends EvaluateGatesOptions {
* gate still applies; a name that is not a registered task is the
* caller's to reject, because only the caller knows what it registered.
*/
- readonly retryTasks?: ReadonlyArray<string>;
+ readonly retryTasks?: ReadonlyArray<LaneTask>;
readonly leaseTtlMs?: number;
}
export interface MaintenanceTaskResult {
- readonly name: string;
+ readonly name: LaneTask;
readonly ok: boolean;
readonly duration_ms: number;
readonly error?: string;
@@ -353,7 +422,7 @@ function resolvePressureGate(
/** The task-result and journal rows of a streak refusal, or `undefined` to run. */
function refuseOnStreak(
vault: string,
- task: string,
+ task: LaneTask,
limit: number,
):
| { result: MaintenanceTaskResult; entry: Omit<MaintenanceJournalEntry, "ts" | "holder"> }
@@ -364,11 +433,16 @@ function refuseOnStreak(
// result are read on different surfaces, and an operator who sees only
// one of them still has to know how deep the hole is and how to climb
// out of it.
+ //
+ // Both spellings of the narrow escape are named, because the message is
+ // read on both surfaces and naming only the CLI flag made the refusal a
+ // dead end for an MCP caller: it prescribed a remedy that surface did
+ // not have. It has `retry_tasks` now, and the sentence says so.
const error =
`refused: ${streak} consecutive journaled failures reached the ` +
`maintenance.failure_streak_limit of ${limit}; fix the cause, then re-run with ` +
- `--retry ${task} to attempt this task alone with every other gate still in force, ` +
- `or --force to run the whole lane past every soft gate`;
+ `--retry ${task} (retry_tasks: ["${task}"] over MCP) to attempt this task alone with ` +
+ `every other gate still in force, or --force to run the whole lane past every soft gate`;
return {
result: { name: task, ok: false, duration_ms: 0, error, refused: true, failure_streak: streak },
// No `ok` on the row: a refusal is not an attempt, and recording one
diff --git a/src/core/brain/policy.ts b/src/core/brain/policy.ts
index 177784b1..337deba9 100644
--- a/src/core/brain/policy.ts
+++ b/src/core/brain/policy.ts
@@ -57,6 +57,7 @@ export {
loadGuardrailsConfigSafe,
loadIntegrityConfigForWrite,
loadIntegrityConfigSafe,
+ loadInstallBlockSafe,
loadMaintenanceConfigSafe,
loadNotesConfigSafe,
loadSnapshotDerivedStorePolicySafe,
@@ -109,6 +110,14 @@ export {
MAINTENANCE_HOST_PRESSURE_PERCENT_MIN,
resolveMaintenance,
} from "./policy/blocks/maintenance.ts";
+export {
+ BRAIN_INSTALL_DEFAULTS,
+ INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT,
+ INSTALL_HOOK_TIMEOUT_SECONDS_MAX,
+ INSTALL_HOOK_TIMEOUT_SECONDS_MIN,
+ INSTALL_TOOL_PROFILE_DEFAULT,
+ INSTALL_TOOL_PROFILE_NAMES,
+} from "./policy/blocks/install.ts";
export {
BRAIN_GUARDRAIL_DEFAULTS,
INSTRUCTION_FILE_MAX_LINES_CEILING,
diff --git a/src/core/brain/policy/blocks/install.ts b/src/core/brain/policy/blocks/install.ts
new file mode 100644
index 00000000..8d2186c0
--- /dev/null
+++ b/src/core/brain/policy/blocks/install.ts
@@ -0,0 +1,131 @@
+/**
+ * The `install:` block - the two settings that parameterise GENERATED
+ * install and hook output.
+ *
+ * One reason to change: what a generated artifact needs to know that the
+ * machine running the generator cannot answer. Both keys are here rather
+ * than in the machine-local `config.yaml` for the same reason: install
+ * verification works by RE-CONSTRUCTION, never a stored hash, so two
+ * machines that clone one vault must reconstruct the same bytes. A knob
+ * that lived only on one machine would make the other report drift it
+ * cannot explain and re-apply a file that was already correct.
+ *
+ * Out-of-range values are hard errors, following `../field-checks.ts`: a
+ * clamped timeout would be indistinguishable from the operator never
+ * having set one, and the operator would believe a bound is in force
+ * that is not.
+ */
+
+import type { BrainInstallConfig, ResolvedBrainInstallConfig } from "../../types.ts";
+import { BrainConfigError } from "../errors.ts";
+import { describe, readBoundedInt } from "../field-checks.ts";
+import { openBlock, warnUnknownKeys, type BlockParseContext } from "../key-index.ts";
+
+const BLOCK = "install";
+
+/**
+ * Seconds a generated lifecycle hook entry may run before the host kills
+ * it. Ten, because that is the value the shipped hook set
+ * (`hooks/hooks.json`) and the grok generator both carried before this
+ * block existed - so a vault that declares nothing regenerates exactly
+ * the bytes it already has on disk.
+ */
+export const INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT = 10;
+
+/**
+ * One second is the floor. Zero is not "no timeout" in any host that
+ * reads these entries - it is a hook that is killed before it can run -
+ * and a negative number is not a duration at all.
+ */
+export const INSTALL_HOOK_TIMEOUT_SECONDS_MIN = 1;
+
+/**
+ * Ten minutes is the ceiling. Every hook in this tree runs inside a
+ * session turn the operator is waiting on, so a larger number is a unit
+ * error (milliseconds written where seconds belong) rather than an
+ * intent, and accepting it would hang the host instead of the hook.
+ */
+export const INSTALL_HOOK_TIMEOUT_SECONDS_MAX = 600;
+
+/**
+ * The MCP tool-surface profile generated install content selects. `full`
+ * is every tool advertised, which is what generated content selected
+ * before this key existed.
+ */
+export const INSTALL_TOOL_PROFILE_DEFAULT = "full";
+
+/**
+ * The profile names `tool_profile` accepts.
+ *
+ * A second declaration of the `TOOL_SURFACE_PROFILES` key set, and
+ * deliberately so: that table lives in `src/mcp/profiles.ts` and carries
+ * the scope and window of each profile, which is an MCP concern, and
+ * nothing under `src/core/` imports `src/mcp/`. What travels down here is
+ * only the NAME vocabulary, and
+ * `tests/core/brain/policy/install-block.test.ts` requires the two lists
+ * to be equal so the copy cannot drift.
+ */
+export const INSTALL_TOOL_PROFILE_NAMES: ReadonlyArray<string> = Object.freeze([
+ "full",
+ "writer",
+ "catalog",
+ "recall",
+ "minimal",
+]);
+
+const KNOWN_KEYS = ["hook_timeout_seconds", "tool_profile"] as const;
+
+/**
+ * Defaults for an absent block: the output every vault generated before
+ * the block existed.
+ */
+export const BRAIN_INSTALL_DEFAULTS: ResolvedBrainInstallConfig = Object.freeze({
+ hook_timeout_seconds: INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT,
+ tool_profile: INSTALL_TOOL_PROFILE_DEFAULT,
+}) as ResolvedBrainInstallConfig;
+
+export function parseInstallBlock(ctx: BlockParseContext): BrainInstallConfig | undefined {
+ const map = openBlock(ctx, BLOCK);
+ if (map === undefined) return undefined;
+
+ const hookTimeoutSeconds = readBoundedInt(
+ map,
+ "hook_timeout_seconds",
+ INSTALL_HOOK_TIMEOUT_SECONDS_MIN,
+ INSTALL_HOOK_TIMEOUT_SECONDS_MAX,
+ `${BLOCK}.hook_timeout_seconds`,
+ ctx.source,
+ );
+
+ let toolProfile: string | undefined;
+ if ("tool_profile" in map) {
+ const raw = map["tool_profile"];
+ if (typeof raw !== "string" || !INSTALL_TOOL_PROFILE_NAMES.includes(raw)) {
+ throw new BrainConfigError(
+ `must name a tool-surface profile (${INSTALL_TOOL_PROFILE_NAMES.join(", ")}); ` +
+ `got ${describe(raw)}`,
+ `${BLOCK}.tool_profile`,
+ ctx.source,
+ );
+ }
+ toolProfile = raw;
+ }
+
+ warnUnknownKeys(ctx, map, KNOWN_KEYS, BLOCK);
+ return Object.freeze({
+ ...(hookTimeoutSeconds !== undefined ? { hook_timeout_seconds: hookTimeoutSeconds } : {}),
+ ...(toolProfile !== undefined ? { tool_profile: toolProfile } : {}),
+ });
+}
+
+/**
+ * This block ships no `resolveInstall(cfg)` sibling, unlike every other
+ * block here, and the omission is deliberate. Its only consumer -
+ * `src/core/install/settings.ts` - sits in the MIDDLE of a four-tier
+ * ladder and has to tell "the vault block set this key" from "the vault
+ * block did not", because the answer decides whether the user-level tier
+ * gets to speak. A resolved value cannot express that distinction: it
+ * has already folded the two into one number. The consumer therefore
+ * reads the raw block and falls back to {@link BRAIN_INSTALL_DEFAULTS}
+ * itself, at the bottom of the ladder where the default belongs.
+ */
diff --git a/src/core/brain/policy/load.ts b/src/core/brain/policy/load.ts
index 2fb9c7d7..2fc39f94 100644
--- a/src/core/brain/policy/load.ts
+++ b/src/core/brain/policy/load.ts
@@ -20,7 +20,7 @@
*/
import { existsSync, readFileSync } from "node:fs";
-import type { BrainConfig, ResolvedBrainIntegrityConfig } from "../types.ts";
+import type { BrainConfig, BrainInstallConfig, ResolvedBrainIntegrityConfig } from "../types.ts";
import { parseBrainYaml, type ParsedBlock } from "../yaml-parse.ts";
import { brainConfigPath } from "../paths.ts";
import { BrainConfigError, type BrainConfigLoadWarning } from "./errors.ts";
@@ -261,6 +261,32 @@ export const loadMaintenanceConfigSafe = makeAbsentTolerantLoader(
BRAIN_MAINTENANCE_DEFAULTS,
);
+/**
+ * Load the RAW `install:` block, or `undefined` when the config file is
+ * absent or declares no block.
+ *
+ * The one loader here that hands back the unresolved block rather than a
+ * resolved value, because its consumer
+ * (`src/core/install/settings.ts`) sits in the middle of a four-tier
+ * ladder: the committed vault tier outranks the machine-local
+ * `config.yaml`, so "the block set this key" and "the block did not" must
+ * stay distinguishable. Resolving here would fold them together and hand
+ * the compiled default a victory over a user-level key that should have
+ * won.
+ *
+ * An unreadable config raises, and for this reader that is the whole
+ * point rather than a side effect: generated install and hook content is
+ * a WRITER, and it cannot infer an operator's intent from a file it could
+ * not parse. Defaulting would silently regenerate the shipped timeout
+ * over a vault whose `_brain.yaml` merely has a typo, and the
+ * re-construction check would then report the operator's own file as
+ * drift on every other machine.
+ */
+export const loadInstallBlockSafe = makeAbsentTolerantLoader(
+ (config: BrainConfig) => config.install,
+ undefined as BrainInstallConfig | undefined,
+);
+
/**
* Load + resolve `active.most_applied`, falling back to
* `BRAIN_MOST_APPLIED_DEFAULTS` when the config file is absent, so a vault
diff --git a/src/core/brain/policy/validate.ts b/src/core/brain/policy/validate.ts
index 854a0bd4..d2414582 100644
--- a/src/core/brain/policy/validate.ts
+++ b/src/core/brain/policy/validate.ts
@@ -27,6 +27,7 @@ import { parseVaultBlock } from "./blocks/vault-scope.ts";
import { parseActiveBlock } from "./blocks/active.ts";
import { parseLessonsBlock } from "./blocks/lessons.ts";
import { parseMaintenanceBlock } from "./blocks/maintenance.ts";
+import { parseInstallBlock } from "./blocks/install.ts";
import { parseDisciplineReportBlock } from "./blocks/discipline-report.ts";
import { parseGuardrailsBlock } from "./blocks/guardrails.ts";
import { parseRollupBlock } from "./blocks/rollup.ts";
@@ -104,6 +105,7 @@ export function validateBrainConfigDetailed(
const active = parseActiveBlock(ctx);
const lessons = parseLessonsBlock(ctx);
const maintenance = parseMaintenanceBlock(ctx);
+ const install = parseInstallBlock(ctx);
const disciplineReport = parseDisciplineReportBlock(ctx);
const guardrails = parseGuardrailsBlock(ctx);
const rollup = parseRollupBlock(ctx);
@@ -134,6 +136,7 @@ export function validateBrainConfigDetailed(
...(active !== undefined ? { active } : {}),
...(lessons !== undefined ? { lessons } : {}),
...(maintenance !== undefined ? { maintenance } : {}),
+ ...(install !== undefined ? { install } : {}),
...(disciplineReport !== undefined ? { discipline_report: disciplineReport } : {}),
...(rollup !== undefined ? { rollup } : {}),
...(guardrails !== undefined ? { guardrails } : {}),
diff --git a/src/core/brain/safeguard.ts b/src/core/brain/safeguard.ts
index 19395076..26b90788 100644
--- a/src/core/brain/safeguard.ts
+++ b/src/core/brain/safeguard.ts
@@ -48,6 +48,14 @@ import { discoverConfig } from "../config.ts";
* (`interruptIsObservable` in `src/cli/interrupt.ts`), because the
* lane awaits between tasks and so is the level at which a Ctrl-C
* can actually be seen. That is its one producer.
+ *
+ * `sessions` is the machine-wide session sweep
+ * (`brain/sessions/discover.ts`). It is the one member whose cost is
+ * dominated by bytes rather than by candidates: measured on a store of
+ * 1227 transcripts totalling 596 MB, one sweep is 3.1 s warm and 6.0 s
+ * cold, of which the walk is 4 ms and the hashing is everything else. It
+ * earns a deadline for the same reason a reindex does - the input is
+ * unbounded and lives on somebody else's disk.
*/
export const OPERATION = Object.freeze({
dream: "dream",
@@ -56,6 +64,7 @@ export const OPERATION = Object.freeze({
clusters: "clusters",
maintenance: "maintenance",
architect: "architect",
+ sessions: "sessions",
} as const);
export type Operation = (typeof OPERATION)[keyof typeof OPERATION];
@@ -68,6 +77,7 @@ export const OPERATIONS: ReadonlyArray<Operation> = Object.freeze([
OPERATION.clusters,
OPERATION.maintenance,
OPERATION.architect,
+ OPERATION.sessions,
]);
/**
diff --git a/src/core/brain/sessions/claude.ts b/src/core/brain/sessions/claude.ts
index 4dc7a95a..fd52aae8 100644
--- a/src/core/brain/sessions/claude.ts
+++ b/src/core/brain/sessions/claude.ts
@@ -24,8 +24,8 @@
* sub-agent transcript parses as an ordinary session of its parent.
*/
-import { readFileSync } from "node:fs";
-
+import { readLines } from "./read-lines.ts";
+import { SESSION_TIMESTAMP_UNKNOWN } from "./types.ts";
import type { SessionAdapter, SessionToolCall, SessionTurn } from "./types.ts";
interface ClaudeBlock {
@@ -65,7 +65,7 @@ function turnFromLine(obj: unknown, fallbackIndex: number): SessionTurn | null {
const timestamp =
typeof o["timestamp"] === "string" && o["timestamp"].length > 0
? o["timestamp"]
- : new Date(0).toISOString();
+ : SESSION_TIMESTAMP_UNKNOWN;
const message = o["message"];
if (message === null || typeof message !== "object") {
@@ -122,10 +122,8 @@ export const claudeAdapter: SessionAdapter = {
return hasClaudeShape;
},
async *iterate(path: string): AsyncIterable<SessionTurn> {
- const text = readFileSync(path, "utf8");
- const lines = text.split("\n");
let i = 0;
- for (const line of lines) {
+ for await (const line of readLines(path)) {
i++;
const trimmed = line.trim();
if (trimmed === "") continue;
diff --git a/src/core/brain/sessions/codex.ts b/src/core/brain/sessions/codex.ts
index fe3d9869..a2166a35 100644
--- a/src/core/brain/sessions/codex.ts
+++ b/src/core/brain/sessions/codex.ts
@@ -21,8 +21,8 @@
* orchestrator can construct a stable `session_ref` for dedup.
*/
-import { readFileSync } from "node:fs";
-
+import { readLines } from "./read-lines.ts";
+import { SESSION_TIMESTAMP_UNKNOWN } from "./types.ts";
import type { SessionAdapter, SessionToolCall, SessionTurn } from "./types.ts";
interface CodexBlock {
@@ -37,7 +37,7 @@ function buildMessageTurn(obj: Record<string, unknown>, fallbackIndex: number):
if (role !== "user" && role !== "assistant" && role !== "system") return null;
const turnId = `codex-msg-${fallbackIndex}`;
const timestamp =
- typeof obj["timestamp"] === "string" ? (obj["timestamp"] as string) : new Date(0).toISOString();
+ typeof obj["timestamp"] === "string" ? (obj["timestamp"] as string) : SESSION_TIMESTAMP_UNKNOWN;
const content = payload["content"];
if (!Array.isArray(content)) {
@@ -96,7 +96,7 @@ function buildFunctionCallTurn(
};
const turnId = callId !== undefined ? `codex-fc-${callId}` : `codex-fc-${fallbackIndex}`;
const timestamp =
- typeof obj["timestamp"] === "string" ? (obj["timestamp"] as string) : new Date(0).toISOString();
+ typeof obj["timestamp"] === "string" ? (obj["timestamp"] as string) : SESSION_TIMESTAMP_UNKNOWN;
return {
turnId,
timestamp,
@@ -123,9 +123,8 @@ export const codexAdapter: SessionAdapter = {
return p["originator"] === "codex_exec" || typeof p["cli_version"] === "string";
},
async *iterate(path: string): AsyncIterable<SessionTurn> {
- const text = readFileSync(path, "utf8");
let i = 0;
- for (const line of text.split("\n")) {
+ for await (const line of readLines(path)) {
i++;
const trimmed = line.trim();
if (trimmed === "") continue;
diff --git a/src/core/brain/sessions/discover.ts b/src/core/brain/sessions/discover.ts
new file mode 100644
index 00000000..73d8ca1a
--- /dev/null
+++ b/src/core/brain/sessions/discover.ts
@@ -0,0 +1,447 @@
+/**
+ * What session logs exist on this machine, and which were never imported.
+ *
+ * `importSession` needs a path. That made cross-agent recall worth nothing
+ * for any session nobody knew to import: an operator had to already know
+ * that Claude Code writes under `~/.claude/projects`, that Codex has moved
+ * its rollouts between four subdirectories of `$CODEX_HOME`, that Grok
+ * encodes the working directory into a path component, and then run the
+ * verb once per file. This module is the other half - the sweep that says
+ * what is here and what is still outstanding - and the ledger that makes
+ * the second run cheap.
+ *
+ * ## The ledger is keyed by content, and lives beside the other derived state
+ *
+ * Re-importing an unchanged log used to re-parse every byte of it to
+ * discover it had nothing to write: dedup suppresses the WRITES, not the
+ * read. So an entry records the SHA-256 of the file's bytes at the moment
+ * it was imported, and a file whose hash still matches is reported as
+ * imported without anything opening it again. Content and not mtime, for
+ * the reason `ingest/content-manifest.ts` gives at length: an rsync, a
+ * Syncthing round trip or a `git checkout` moves the clock and not a byte,
+ * and a ledger that believed the clock would re-import the whole machine
+ * after any of them.
+ *
+ * That manifest is the same SHAPE and is deliberately NOT reused. Its keys
+ * are canonical vault-RELATIVE paths, resolved against the vault on every
+ * lookup (`classifyPaths` does `join(vault, canonicalNotePath(path))`);
+ * session logs live outside the vault at absolute machine paths, which
+ * `canonicalNotePath` exists to reject. Only the primitive both need -
+ * {@link hashFile} - is shared.
+ *
+ * ## Why the sweep carries a deadline and a progress rail
+ *
+ * Measured before it was decided, on the shape of a real store: 1227
+ * transcripts totalling 596 MB under `~/.claude/projects`, swept as a
+ * synthetic fixture of the same size. {@link discoverSessions} takes
+ * 3.1 s warm and 6.0 s on the first pass over a cold cache; the walk is
+ * 4 ms of that and the hashing is all the rest. It emits 1229 progress
+ * records, not one. So it gets both a rail whose denominator is known
+ * once the walk is done, and the same cooperative deadline every other
+ * long operation here carries - a run that would trip 600 s is one over
+ * a store this could not otherwise report on at all. Neither is on by
+ * default: the sink is opt-in at the CLI edge, and an absent safeguard is
+ * a no-op.
+ *
+ * Nothing here parses a transcript. Discovery reads bytes to hash them and
+ * makes no attempt to interpret them, which is what keeps a sweep over a
+ * store this build has no adapter for (Cursor's `state.vscdb`) honest: it
+ * is reported as FOUND and never as a gap, because a gap is work an
+ * operator can close.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { atomicWriteFileSync } from "../../fs-atomic.ts";
+import {
+ resolveSessionRootsFor,
+ isSessionRuntimeId,
+ SESSION_RUNTIME_IDS,
+ type HostContext,
+ type ResolvedSessionRoot,
+ type SessionRuntimeId,
+} from "../../runtime/host-facts.ts";
+import { hashFile } from "../ingest/content-manifest.ts";
+import { DERIVED_STORE_DIR } from "../path-constants.ts";
+import { progressCounter, type ProgressSink } from "../progress.ts";
+import { OPERATION, type Safeguard } from "../safeguard.ts";
+import { acquireLockSyncWithRetry } from "../sync-lockfile.ts";
+import { isoSecond } from "../time.ts";
+import { assertVaultIdentityForWrite } from "../vault-identity.ts";
+
+/** Only ledger schema this build understands. Anything else is refused. */
+export const SESSION_LEDGER_SCHEMA_VERSION = 1 as const;
+
+/** Basename of the import ledger inside the derived store. */
+const SESSION_LEDGER_FILE = "session-import-ledger.json";
+
+/**
+ * The progress stage this sweep opens. One stage, because the walk is
+ * three orders of magnitude cheaper than the hashing and a rail that
+ * announced it would be reporting on nothing.
+ */
+const HASH_STAGE = "hash";
+
+/** Absolute path of the session import ledger for a vault. */
+export function sessionLedgerPath(vault: string): string {
+ return join(vault, DERIVED_STORE_DIR, SESSION_LEDGER_FILE);
+}
+
+/** What was recorded about one imported session log. */
+export interface SessionLedgerEntry {
+ /** SHA-256 hex of the file's bytes at the moment it was imported. */
+ readonly hash: string;
+ /** Which runtime wrote it, for the per-runtime coverage report. */
+ readonly runtime: SessionRuntimeId;
+ /** When this build imported it, to the second. */
+ readonly imported_at: string;
+}
+
+/** Absolute log path β†’ what was recorded about it. */
+export interface SessionImportLedger {
+ readonly schema_version: typeof SESSION_LEDGER_SCHEMA_VERSION;
+ readonly entries: Readonly<Record<string, SessionLedgerEntry>>;
+}
+
+/** One declared root, measured against the host. */
+export interface DiscoveredRoot extends ResolvedSessionRoot {
+ /** Whether the directory exists here. Absent is not empty. */
+ readonly present: boolean;
+}
+
+/** One runtime's coverage: what is here, and how much of it is outstanding. */
+export interface RuntimeCoverage {
+ readonly runtime: SessionRuntimeId;
+ readonly roots: ReadonlyArray<DiscoveredRoot>;
+ /** Session logs found under this runtime's roots. */
+ readonly found: number;
+ /** Of those, the ones the ledger records at their current bytes. */
+ readonly imported: number;
+ /**
+ * Of those, the ones an import would still have work to do on: never
+ * recorded, or recorded at different bytes.
+ */
+ readonly gap: number;
+ /**
+ * Of those, the ones no adapter in this build can parse. Counted apart
+ * from the gap because a gap is work an operator can close, and
+ * `found = imported + gap + unparsable` only reads as a coverage answer
+ * when the third term is visible.
+ */
+ readonly unparsable: number;
+ /** The gap, as absolute paths, sorted. */
+ readonly gapPaths: ReadonlyArray<string>;
+}
+
+/** What one machine-wide sweep found. */
+export interface SessionDiscovery {
+ readonly byRuntime: ReadonlyArray<RuntimeCoverage>;
+ readonly found: number;
+ readonly imported: number;
+ readonly gap: number;
+ readonly unparsable: number;
+ /**
+ * Roots and files that exist and could not be read. Carried even when
+ * something was found: a partial sweep found less than it should have,
+ * and the counts alone cannot say so.
+ */
+ readonly unreadable: ReadonlyArray<string>;
+}
+
+export interface DiscoverSessionsOptions {
+ /** The machine to ask about. Defaults to the one this process runs on. */
+ readonly host?: HostContext;
+ /** Cooperative deadline, checked once per file. */
+ readonly safeguard?: Safeguard;
+ /** Where per-file progress goes. Absent means nobody is watching. */
+ readonly onProgress?: ProgressSink;
+}
+
+/** One file to record as imported. */
+export interface SessionImportRecord {
+ readonly path: string;
+ readonly runtime: SessionRuntimeId;
+}
+
+/** The host this process is running on, when the caller named none. */
+function currentHost(): HostContext {
+ return { home: process.env["HOME"] ?? "", env: process.env };
+}
+
+/**
+ * Read the ledger. A missing file is an empty ledger - every log then
+ * classifies as a gap, which is the correct answer for a vault that has
+ * imported nothing. A CORRUPT or unknown-schema file is a hard error: a
+ * silent reset would report an operator's entire already-imported machine
+ * as outstanding and send them to re-import all of it.
+ */
+export function readSessionLedger(vault: string): SessionImportLedger {
+ const path = sessionLedgerPath(vault);
+ if (!existsSync(path)) return { schema_version: SESSION_LEDGER_SCHEMA_VERSION, entries: {} };
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(readFileSync(path, "utf8"));
+ } catch (e) {
+ throw new Error(`session import ledger is corrupted JSON: ${path}`, { cause: e });
+ }
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+ throw new Error(`session import ledger is not an object: ${path}`);
+ }
+ const obj = parsed as Record<string, unknown>;
+ if (obj["schema_version"] !== SESSION_LEDGER_SCHEMA_VERSION) {
+ throw new Error(
+ `session import ledger schema_version ${String(obj["schema_version"])} not supported ` +
+ `(expected ${SESSION_LEDGER_SCHEMA_VERSION}): ${path}`,
+ );
+ }
+ const entries: Record<string, SessionLedgerEntry> = {};
+ const raw = obj["entries"];
+ if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+ for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+ const entry = readEntry(value);
+ if (entry !== null) entries[key] = entry;
+ }
+ }
+ return { schema_version: SESSION_LEDGER_SCHEMA_VERSION, entries };
+}
+
+/**
+ * One entry, or `null` when it is not one this build can read.
+ *
+ * The runtime went through JSON, so it is a string until the guard says
+ * otherwise: a release that adds a runtime writes entries this one cannot
+ * attribute, and attributing them to an arbitrary runtime would be worse
+ * than treating the file as never imported.
+ */
+function readEntry(value: unknown): SessionLedgerEntry | null {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+ const row = value as Record<string, unknown>;
+ const hash = row["hash"];
+ const runtime = row["runtime"];
+ const importedAt = row["imported_at"];
+ if (typeof hash !== "string" || !isSessionRuntimeId(runtime)) return null;
+ return {
+ hash,
+ runtime,
+ imported_at: typeof importedAt === "string" ? importedAt : "",
+ };
+}
+
+/** Canonical ledger bytes: keys sorted, so a no-op rerun is byte-identical. */
+function serializeLedger(entries: Record<string, SessionLedgerEntry>): string {
+ const sorted: Record<string, SessionLedgerEntry> = {};
+ for (const key of Object.keys(entries).toSorted()) sorted[key] = entries[key]!;
+ return (
+ JSON.stringify({ schema_version: SESSION_LEDGER_SCHEMA_VERSION, entries: sorted }, null, 2) +
+ "\n"
+ );
+}
+
+/**
+ * Record `imports` as imported at their current bytes. Returns `true` when
+ * the ledger was rewritten, `false` on a byte-identical no-op.
+ *
+ * A path that has since vanished is dropped rather than recorded, so it
+ * re-classifies as new if it ever reappears. The read, the merge and the
+ * write are one critical section under the same lock every other Brain
+ * read-modify-write takes: `--discover --all` and an explicit-path import
+ * can be running in two processes at once, and two snapshots written back
+ * in sequence would each lose the other's entry.
+ *
+ * Every OTHER entry that no longer names a file is dropped in the same
+ * pass. Dropping only the re-submitted ones left a dead key behind for
+ * every transcript a runtime renamed, rotated or deleted - and nothing
+ * ever removed it, because a re-submission is the one moment the ledger
+ * hears a path's name again. The pruning happens here and not in
+ * {@link discoverSessions} on purpose: discovery writes nothing, and a
+ * report that quietly rewrote the state it reports on would be a report
+ * nobody could re-run. The cost is one `existsSync` per entry, on a write
+ * path that already hashes a file per record.
+ */
+export function recordSessionImports(
+ vault: string,
+ imports: ReadonlyArray<SessionImportRecord>,
+ now: Date = new Date(),
+): boolean {
+ assertVaultIdentityForWrite(vault);
+ const path = sessionLedgerPath(vault);
+ const handle = acquireLockSyncWithRetry(path);
+ try {
+ const entries: Record<string, SessionLedgerEntry> = { ...readSessionLedger(vault).entries };
+ const stamp = isoSecond(now);
+ for (const record of imports) {
+ if (!existsSync(record.path)) {
+ delete entries[record.path];
+ continue;
+ }
+ entries[record.path] = {
+ hash: hashFile(record.path),
+ runtime: record.runtime,
+ imported_at: stamp,
+ };
+ }
+ for (const path of Object.keys(entries)) {
+ if (!existsSync(path)) delete entries[path];
+ }
+ const next = serializeLedger(entries);
+ if (existsSync(path) && readFileSync(path, "utf8") === next) return false;
+ atomicWriteFileSync(path, next);
+ return true;
+ } finally {
+ handle.release();
+ }
+}
+
+/** Every file matching `root`'s declared glob, sorted, or a read failure. */
+function filesUnder(root: DiscoveredRoot): { files: ReadonlyArray<string>; unreadable: string[] } {
+ if (!root.present) return { files: [], unreadable: [] };
+ try {
+ const found = [
+ ...new Bun.Glob(root.glob).scanSync({
+ cwd: root.path,
+ onlyFiles: true,
+ // A symlink cycle would drive the walk into unbounded recursion,
+ // and a sweep that follows links out of a declared root is
+ // reaching further than the declaration says.
+ followSymlinks: false,
+ // A plain `readdirSync` walk sees dotfiles, and `~/.codex/.tmp`
+ // is a declared root; matching it would be inconsistent.
+ dot: true,
+ }),
+ ].map((rel) => join(root.path, rel));
+ found.sort();
+ return { files: found, unreadable: [] };
+ } catch (err) {
+ // The root is there and this process cannot see inside it. Reporting
+ // zero without saying so is the failure this branch exists to avoid.
+ const detail = err instanceof Error ? err.message : String(err);
+ return { files: [], unreadable: [`${root.path}: ${detail}`] };
+ }
+}
+
+/** Whether the declared root exists here, without letting an errno escape. */
+function rootPresent(path: string): boolean {
+ try {
+ return statSync(path).isDirectory();
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Sweep every declared session root on `opts.host` and report, per
+ * runtime, what is here and what has never been imported into `vault`.
+ *
+ * Reads only to hash. Writes nothing - not even the ledger, which records
+ * imports and would be lying if a report updated it.
+ */
+export function discoverSessions(
+ vault: string,
+ opts: DiscoverSessionsOptions = {},
+): SessionDiscovery {
+ const host = opts.host ?? currentHost();
+ const ledger = readSessionLedger(vault);
+ const unreadable: string[] = [];
+
+ // Walk first, so the counter has a denominator before it starts.
+ const perRuntime = SESSION_RUNTIME_IDS.map((runtime) => {
+ const roots: DiscoveredRoot[] = resolveSessionRootsFor(runtime, host).map((root) => ({
+ ...root,
+ present: rootPresent(root.path),
+ }));
+ const files: Array<{ path: string; root: DiscoveredRoot }> = [];
+ for (const root of roots) {
+ const scan = filesUnder(root);
+ unreadable.push(...scan.unreadable);
+ for (const path of scan.files) files.push({ path, root });
+ }
+ return { runtime, roots, files };
+ });
+
+ const total = perRuntime.reduce((sum, r) => sum + r.files.length, 0);
+ const progress = progressCounter(OPERATION.sessions, opts.onProgress);
+ progress.start(HASH_STAGE, total);
+
+ const byRuntime: RuntimeCoverage[] = [];
+ try {
+ for (const entry of perRuntime) {
+ let imported = 0;
+ let unparsable = 0;
+ const gapPaths: string[] = [];
+ for (const file of entry.files) {
+ opts.safeguard?.checkpoint();
+ progress.advance(HASH_STAGE);
+ if (file.root.adapter === null) {
+ unparsable += 1;
+ continue;
+ }
+ let hash: string;
+ try {
+ hash = hashFile(file.path);
+ } catch (err) {
+ const detail = err instanceof Error ? err.message : String(err);
+ unreadable.push(`${file.path}: ${detail}`);
+ continue;
+ }
+ if (ledger.entries[file.path]?.hash === hash) imported += 1;
+ else gapPaths.push(file.path);
+ }
+ gapPaths.sort();
+ byRuntime.push({
+ runtime: entry.runtime,
+ roots: Object.freeze(entry.roots),
+ found: entry.files.length,
+ imported,
+ gap: gapPaths.length,
+ unparsable,
+ gapPaths: Object.freeze(gapPaths),
+ });
+ }
+ } catch (err) {
+ // The stream promises to terminate whichever way the run ends; a
+ // sweep that simply stopped arriving reads as one that hung.
+ progress.stop("failed");
+ throw err;
+ }
+ progress.finish();
+
+ return Object.freeze({
+ byRuntime: Object.freeze(byRuntime),
+ found: byRuntime.reduce((sum, r) => sum + r.found, 0),
+ imported: byRuntime.reduce((sum, r) => sum + r.imported, 0),
+ gap: byRuntime.reduce((sum, r) => sum + r.gap, 0),
+ unparsable: byRuntime.reduce((sum, r) => sum + r.unparsable, 0),
+ unreadable: Object.freeze(unreadable.toSorted()),
+ });
+}
+
+/**
+ * Which declared root `path` sits under, or `null` when it sits under
+ * none.
+ *
+ * Pure path arithmetic - no walk, no stat, no hash - because the caller
+ * is an explicit-path import that has already done its work and only
+ * needs to know whether the file it just imported is part of this
+ * machine's coverage. A log the operator copied to `/tmp` is not, and
+ * recording it would put a path in the ledger that no sweep will ever
+ * look for again.
+ */
+export function runtimeForPath(path: string, host?: HostContext): SessionRuntimeId | null {
+ const ctx = host ?? currentHost();
+ for (const runtime of SESSION_RUNTIME_IDS) {
+ for (const root of resolveSessionRootsFor(runtime, ctx)) {
+ if (path === root.path || path.startsWith(`${root.path}/`)) return runtime;
+ }
+ }
+ return null;
+}
+
+/** Every outstanding log across every runtime, with the runtime that wrote it. */
+export function discoveryGap(discovery: SessionDiscovery): ReadonlyArray<SessionImportRecord> {
+ const out: SessionImportRecord[] = [];
+ for (const row of discovery.byRuntime) {
+ for (const path of row.gapPaths) out.push({ path, runtime: row.runtime });
+ }
+ return Object.freeze(out);
+}
diff --git a/src/core/brain/sessions/grok.ts b/src/core/brain/sessions/grok.ts
index f16e5982..dcc93f2e 100644
--- a/src/core/brain/sessions/grok.ts
+++ b/src/core/brain/sessions/grok.ts
@@ -24,10 +24,10 @@
* `session/update`, or the import throws PARSE.
*/
-import { readFileSync } from "node:fs";
import { basename, dirname } from "node:path";
-import { SessionImportError } from "./types.ts";
+import { readLines } from "./read-lines.ts";
+import { SESSION_TIMESTAMP_UNKNOWN, SessionImportError } from "./types.ts";
import type { SessionAdapter, SessionTurn } from "./types.ts";
interface GrokUpdate {
@@ -47,7 +47,7 @@ function isoFrom(ts: unknown): string {
if (typeof ts === "number" && Number.isFinite(ts)) {
return new Date(ts * 1000).toISOString();
}
- return new Date(0).toISOString();
+ return SESSION_TIMESTAMP_UNKNOWN;
}
/** Parse one line into its `session/update` payload, or null if it is not one. */
@@ -89,6 +89,13 @@ function bareToolName(title: string): string {
return sep === -1 ? title : title.slice(sep + 2);
}
+function notAGrokStream(): SessionImportError {
+ return new SessionImportError(
+ "PARSE",
+ "grok session: first line is not an ACP session/update; not a grok updates.jsonl stream",
+ );
+}
+
const ROLE_BY_KIND: Readonly<Record<string, "user" | "assistant">> = {
user_message_chunk: "user",
agent_message_chunk: "assistant",
@@ -102,16 +109,11 @@ export const grokAdapter: SessionAdapter = {
},
async *iterate(path: string): AsyncIterable<SessionTurn> {
- const lines = readFileSync(path, "utf8").split("\n");
- const firstNonEmpty = lines.find((l) => l.trim() !== "");
- if (firstNonEmpty === undefined || parseUpdateLine(firstNonEmpty.trim()) === null) {
- throw new SessionImportError(
- "PARSE",
- "grok session: first line is not an ACP session/update; not a grok updates.jsonl stream",
- );
- }
-
- const sessionId = parseUpdateLine(firstNonEmpty.trim())?.sessionId ?? basename(dirname(path));
+ // The structural gate is the first non-empty line. Streaming cannot
+ // rewind, so that line is gated as it arrives and then processed by the
+ // same loop body as every other line.
+ let sessionId = "";
+ let gated = false;
let seq = 0;
const nextId = (): string => `${sessionId}:${seq++}`;
@@ -129,10 +131,15 @@ export const grokAdapter: SessionAdapter = {
return turn;
};
- for (const rawLine of lines) {
+ for await (const rawLine of readLines(path)) {
const trimmed = rawLine.trim();
if (trimmed === "") continue;
const parsed = parseUpdateLine(trimmed);
+ if (!gated) {
+ gated = true;
+ if (parsed === null) throw notAGrokStream();
+ sessionId = parsed.sessionId ?? basename(dirname(path));
+ }
if (parsed === null) continue;
const timestamp = parsed.timestamp;
@@ -172,6 +179,9 @@ export const grokAdapter: SessionAdapter = {
// tool_call_update, plan, ...) is intentionally skipped.
}
+ // A file that is empty or entirely blank never reached the gate.
+ if (!gated) throw notAGrokStream();
+
const tail = flush();
if (tail !== null) yield tail;
},
diff --git a/src/core/brain/sessions/hermes.ts b/src/core/brain/sessions/hermes.ts
index 5d6e57d2..d0e7b5ab 100644
--- a/src/core/brain/sessions/hermes.ts
+++ b/src/core/brain/sessions/hermes.ts
@@ -21,8 +21,8 @@
* the same with `new Date()`.
*/
-import { readFileSync } from "node:fs";
-
+import { readLines } from "./read-lines.ts";
+import { SESSION_TIMESTAMP_UNKNOWN } from "./types.ts";
import type { SessionAdapter, SessionToolCall, SessionTurn } from "./types.ts";
interface HermesToolCall {
@@ -60,7 +60,7 @@ function buildTurn(obj: Record<string, unknown>, fallbackIndex: number): Session
const timestamp =
typeof obj["timestamp"] === "string" && obj["timestamp"].length > 0
? (obj["timestamp"] as string)
- : new Date(0).toISOString();
+ : SESSION_TIMESTAMP_UNKNOWN;
const text =
typeof obj["content"] === "string" && obj["content"].length > 0
@@ -113,9 +113,8 @@ export const hermesAdapter: SessionAdapter = {
return Array.isArray(o["tools"]);
},
async *iterate(path: string): AsyncIterable<SessionTurn> {
- const text = readFileSync(path, "utf8");
let i = 0;
- for (const line of text.split("\n")) {
+ for await (const line of readLines(path)) {
i++;
const trimmed = line.trim();
if (trimmed === "") continue;
diff --git a/src/core/brain/sessions/import.ts b/src/core/brain/sessions/import.ts
index 39fbca52..4390cf56 100644
--- a/src/core/brain/sessions/import.ts
+++ b/src/core/brain/sessions/import.ts
@@ -25,8 +25,8 @@
* second run on the same file finds every hash already present.
*/
-import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { basename, resolve } from "node:path";
import { delegatedAgentName } from "../../agent-identity.ts";
import { readSkillOfferId, SKILL_OFFER_ID_KEY } from "../../surface/skill-offer.ts";
@@ -37,7 +37,9 @@ import { writeSignal } from "../signal.ts";
import { importSessionRecall } from "../session-recall.ts";
import { isoDate, isoSecond } from "../time.ts";
import { BRAIN_SIGNAL_SOURCE_TYPE } from "../types.ts";
+import { readFirstLine } from "./read-lines.ts";
import { detectAdapter, getAdapter } from "./registry.ts";
+import { sessionFilesUnder } from "./session-files.ts";
import {
SessionImportError,
type SessionAdapter,
@@ -197,15 +199,6 @@ export interface ImportSessionPathResult {
readonly warnings: ReadonlyArray<{ path: string; message: string }>;
}
-function firstLineOfFile(path: string): string {
- // Read the file and slice up to the first newline. Cheaper than a
- // streaming reader for our small fixtures, fine for production
- // session files that are typically 50-500 KB.
- const text = readFileSync(path, "utf8");
- const nl = text.indexOf("\n");
- return nl < 0 ? text : text.slice(0, nl);
-}
-
/**
* Portable session identity for provenance refs (Vault portability suite).
*
@@ -222,12 +215,18 @@ export function sessionRefIdentity(absPath: string, recallSessionId?: string): s
return explicit && explicit.length > 0 ? explicit : basename(absPath);
}
-/** Pick an adapter β€” by explicit format, or autodetect. */
-function chooseAdapter(path: string, format?: SessionAdapterId): SessionAdapter {
+/**
+ * Pick an adapter β€” by explicit format, or autodetect.
+ *
+ * Autodetect needs exactly one line, and `readFirstLine` stops at the first
+ * newline: the file used to be read whole here and then read a second time by
+ * `adapter.iterate`. An explicit `--format` reads nothing at all.
+ */
+async function chooseAdapter(path: string, format?: SessionAdapterId): Promise<SessionAdapter> {
if (format !== undefined) {
return getAdapter(format);
}
- const first = firstLineOfFile(path);
+ const first = await readFirstLine(path);
const a = detectAdapter(first);
if (!a) {
throw new SessionImportError(
@@ -246,7 +245,7 @@ export async function importSession(
if (!existsSync(path)) {
throw new SessionImportError("IO", `session file does not exist: ${path}`);
}
- const adapter = chooseAdapter(path, opts.format);
+ const adapter = await chooseAdapter(path, opts.format);
// Reuse the caller-supplied index when present (directory walk lifts
// the build out of the per-file loop). Otherwise build our own.
const dedup = opts.dedupIndex ?? buildDedupIndex(vault);
@@ -669,30 +668,9 @@ export async function importSessionPath(
// as new signals are written, so cross-file dedup happens too.
const files: ImportSessionResult[] = [];
const warnings: { path: string; message: string }[] = [];
- const queue: string[] = [];
- const collect = (dir: string): void => {
- for (const name of readdirSync(dir)) {
- const full = join(dir, name);
- let st;
- try {
- // lstat (not stat) so symlink cycles can't drive the walker
- // into infinite recursion. Symlink-following session-exports
- // are atypical; if real demand surfaces we can switch to a
- // visited-inode set instead.
- st = lstatSync(full);
- } catch {
- continue;
- }
- if (st.isSymbolicLink()) continue;
- if (st.isDirectory()) {
- collect(full);
- continue;
- }
- if (name.endsWith(".jsonl")) queue.push(full);
- }
- };
- collect(path);
- queue.sort();
+ // Shared with the transcript dataset export, so both agree on what a
+ // session log is and neither can quietly widen the rule alone.
+ const queue = sessionFilesUnder(path);
const sharedDedup = opts.dedupIndex ?? buildDedupIndex(vault);
const perFileOpts: ImportSessionOptions = {
diff --git a/src/core/brain/sessions/opencode.ts b/src/core/brain/sessions/opencode.ts
index 1272ee83..b517e76e 100644
--- a/src/core/brain/sessions/opencode.ts
+++ b/src/core/brain/sessions/opencode.ts
@@ -18,9 +18,8 @@
* fields it does not understand.
*/
-import { readFileSync } from "node:fs";
-
-import { SessionImportError } from "./types.ts";
+import { readLines } from "./read-lines.ts";
+import { SESSION_TIMESTAMP_UNKNOWN, SessionImportError } from "./types.ts";
import type { SessionAdapter, SessionToolCall, SessionTurn } from "./types.ts";
const ORIGINATOR = "open-second-brain-opencode-plugin";
@@ -51,7 +50,7 @@ function buildTurn(obj: Record<string, unknown>): SessionTurn | null {
const role = obj["role"];
if (role !== "user" && role !== "assistant" && role !== "system") return null;
const timestamp =
- typeof obj["timestamp"] === "string" ? obj["timestamp"] : new Date(0).toISOString();
+ typeof obj["timestamp"] === "string" ? obj["timestamp"] : SESSION_TIMESTAMP_UNKNOWN;
const toolCalls: SessionToolCall[] = [];
if (Array.isArray(obj["toolCalls"])) {
@@ -82,46 +81,57 @@ export const opencodeAdapter: SessionAdapter = {
return parseMetaLine(firstLine) !== null;
},
async *iterate(path: string): AsyncIterable<SessionTurn> {
- const text = readFileSync(path, "utf8");
- const lines = text.split("\n");
// Hard gate even under explicit `--format opencode`: a file whose
- // first line is not our meta line must not partially import.
- const meta = lines.length > 0 ? parseMetaLine(lines[0]!.trim()) : null;
- if (meta === null) {
- throw new SessionImportError(
- "PARSE",
- `opencode spool meta line missing or invalid; expected first line ` +
- `with originator ${ORIGINATOR}`,
- );
- }
- const format = meta["format"];
- if (typeof format !== "number") {
- throw new SessionImportError(
- "PARSE",
- `opencode spool meta line carries no numeric format field; ` +
- `expected format ${SUPPORTED_FORMAT}`,
- );
- }
- if (format > SUPPORTED_FORMAT) {
- throw new SessionImportError(
- "PARSE",
- `opencode spool format ${format} is newer than supported ` +
- `format ${SUPPORTED_FORMAT}; upgrade Open Second Brain to import it`,
- );
- }
- for (const line of lines.slice(1)) {
- const trimmed = line.trim();
- if (trimmed === "") continue;
- let obj: unknown;
- try {
- obj = JSON.parse(trimmed);
- } catch {
- continue;
+ // first line is not our meta line must not partially import. The head
+ // is pulled on its own so the gate still runs before the body streams.
+ const lines = readLines(path);
+ try {
+ const head = await lines.next();
+ const meta = head.done === true ? null : parseMetaLine(head.value.trim());
+ if (meta === null) {
+ throw new SessionImportError(
+ "PARSE",
+ `opencode spool meta line missing or invalid; expected first line ` +
+ `with originator ${ORIGINATOR}`,
+ );
+ }
+ const format = meta["format"];
+ if (typeof format !== "number") {
+ throw new SessionImportError(
+ "PARSE",
+ `opencode spool meta line carries no numeric format field; ` +
+ `expected format ${SUPPORTED_FORMAT}`,
+ );
+ }
+ if (format > SUPPORTED_FORMAT) {
+ throw new SessionImportError(
+ "PARSE",
+ `opencode spool format ${format} is newer than supported ` +
+ `format ${SUPPORTED_FORMAT}; upgrade Open Second Brain to import it`,
+ );
+ }
+ for (;;) {
+ // A stream is read one line at a time, by definition.
+ // oxlint-disable-next-line no-await-in-loop
+ const next = await lines.next();
+ if (next.done === true) break;
+ const trimmed = next.value.trim();
+ if (trimmed === "") continue;
+ let obj: unknown;
+ try {
+ obj = JSON.parse(trimmed);
+ } catch {
+ continue;
+ }
+ const o = asRecord(obj);
+ if (!o) continue;
+ const turn = buildTurn(o);
+ if (turn) yield turn;
}
- const o = asRecord(obj);
- if (!o) continue;
- const turn = buildTurn(o);
- if (turn) yield turn;
+ } finally {
+ // A gate throw leaves the reader suspended mid-file; close it here
+ // rather than waiting for the handle to be collected.
+ await lines.return(undefined);
}
},
};
diff --git a/src/core/brain/sessions/read-lines.ts b/src/core/brain/sessions/read-lines.ts
new file mode 100644
index 00000000..5c4883db
--- /dev/null
+++ b/src/core/brain/sessions/read-lines.ts
@@ -0,0 +1,147 @@
+/**
+ * The one line reader every session adapter uses.
+ *
+ * Each adapter used to `readFileSync(path, "utf8")` and then `split("\n")`,
+ * which retained the whole file twice over - once as the text, once as the
+ * array of lines - before the first turn was yielded. The `iterate` contract
+ * has always been `AsyncIterable<SessionTurn>`, so the laziness was there in
+ * the signature and nowhere in the behaviour. This module supplies it: a
+ * chunked read over Bun's file stream that never holds more than one chunk
+ * plus the partial line carried across the chunk boundary.
+ *
+ * Line semantics match what `split("\n")` gave the adapters, deliberately:
+ *
+ * - `\n` terminates a line; a `\r` immediately before it is part of the
+ * terminator, not the content (a lone `\r` mid-line is content).
+ * - A blank line in the middle is yielded as `""`.
+ * - A final line with no trailing newline is still yielded.
+ * - A trailing newline does NOT produce a phantom empty final line, which
+ * is the one place this differs from `split("\n")`. Every adapter skips
+ * blank lines, so the turns they emit - and the line numbers they derive
+ * fallback turn ids from - are unchanged.
+ * - An empty file yields nothing.
+ *
+ * A multi-byte character split across a chunk boundary is the case the
+ * whole-file read could never hit and a naive chunked reader always gets
+ * wrong; `TextDecoder`'s streaming mode holds the partial sequence instead of
+ * emitting U+FFFD.
+ */
+
+import { SessionImportError } from "./types.ts";
+
+/**
+ * High-water mark, in bytes, of the largest window this module has held:
+ * the chunk being scanned plus the partial line carried into it. Module-level
+ * because `SessionAdapter.iterate(path)` takes only a path - there is no seam
+ * to hand an observer through - and because the number worth bounding is the
+ * peak across every reader alive at once, which is exactly what a shared mark
+ * measures. Kept always-on: it costs one comparison per chunk, and a bound
+ * that is only measured when someone remembers to ask for it is not a bound.
+ */
+let retainedHighWaterBytes = 0;
+
+/** Peak retained window in bytes since the last {@link resetLineReaderRetainedBytes}. */
+export function lineReaderRetainedBytes(): number {
+ return retainedHighWaterBytes;
+}
+
+/** Drop the high-water mark so a measurement can start from a known zero. */
+export function resetLineReaderRetainedBytes(): void {
+ retainedHighWaterBytes = 0;
+}
+
+function recordWindow(chunkBytes: number, carry: string): void {
+ const window = chunkBytes + Buffer.byteLength(carry, "utf8");
+ if (window > retainedHighWaterBytes) retainedHighWaterBytes = window;
+}
+
+function ioError(path: string, err: unknown): SessionImportError {
+ const detail = err instanceof Error ? err.message : String(err);
+ return new SessionImportError(
+ "IO",
+ `cannot read session file ${path}: ${detail}; check the path exists and is readable`,
+ );
+}
+
+/** Strip the `\r` of a `\r\n` terminator, leaving any other CR as content. */
+function stripTerminatorCr(line: string): string {
+ return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+
+/**
+ * Open the byte stream. Split out so the `IO` translation wraps the open and
+ * nothing else β€” in particular never a `yield`, whose completion would
+ * otherwise be caught and mislabelled as a read failure.
+ */
+function openReader(path: string) {
+ try {
+ return Bun.file(path).stream().getReader();
+ } catch (err) {
+ throw ioError(path, err);
+ }
+}
+
+async function readChunk(reader: ReturnType<typeof openReader>, path: string) {
+ try {
+ return await reader.read();
+ } catch (err) {
+ throw ioError(path, err);
+ }
+}
+
+/**
+ * Yield the lines of `path` without ever materialising the file.
+ *
+ * Throws {@link SessionImportError} with code `IO` if the file cannot be
+ * opened or read; a caller walking a directory can then report the file and
+ * carry on rather than losing the whole run to a raw errno.
+ */
+export async function* readLines(path: string): AsyncGenerator<string> {
+ const reader = openReader(path);
+ const decoder = new TextDecoder("utf-8");
+ let carry = "";
+ try {
+ for (;;) {
+ // Chunk n+1 cannot be requested before chunk n is scanned β€” that is
+ // the bound this module exists to hold.
+ // oxlint-disable-next-line no-await-in-loop
+ const chunk = await readChunk(reader, path);
+ if (chunk.done === true || chunk.value === undefined) break;
+
+ recordWindow(chunk.value.byteLength, carry);
+ const text = carry + decoder.decode(chunk.value, { stream: true });
+ // Scan by offset rather than re-slicing the remainder each time: a
+ // chunk holding thousands of lines would otherwise be quadratic.
+ let start = 0;
+ let nl = text.indexOf("\n", start);
+ while (nl >= 0) {
+ yield stripTerminatorCr(text.slice(start, nl));
+ start = nl + 1;
+ nl = text.indexOf("\n", start);
+ }
+ carry = start === 0 ? text : text.slice(start);
+ }
+ // Flush any bytes the decoder was still holding, then the last unterminated
+ // line. A file ending in `\n` leaves nothing here - no phantom empty line.
+ carry += decoder.decode();
+ if (carry.length > 0) yield stripTerminatorCr(carry);
+ } finally {
+ // Reached on normal completion AND when the consumer breaks early
+ // (`readFirstLine` always does), so the file handle never outlives the
+ // loop that opened it.
+ await reader.cancel().catch(() => undefined);
+ }
+}
+
+/**
+ * The first line of `path`, read by stopping at the first newline instead of
+ * reading the file. Autodetect needs one line; it used to pay for the whole
+ * file, and then the adapter read the same file a second time.
+ *
+ * An empty file has no first line and returns `""` - the same value
+ * `split("\n")[0]` produced, and one no adapter's `detect` accepts.
+ */
+export async function readFirstLine(path: string): Promise<string> {
+ for await (const line of readLines(path)) return line;
+ return "";
+}
diff --git a/src/core/brain/sessions/session-files.ts b/src/core/brain/sessions/session-files.ts
new file mode 100644
index 00000000..3e1335cc
--- /dev/null
+++ b/src/core/brain/sessions/session-files.ts
@@ -0,0 +1,124 @@
+/**
+ * Which files under an operator-named path are session transcripts.
+ *
+ * The walk lived inside `importSessionPath` as a closure, which was right
+ * while one caller existed. A second one appeared - the transcript dataset
+ * export - and two copies of "a session log is a `*.jsonl` that is not a
+ * symlink, sorted so runs are reproducible" is exactly the drift a shared
+ * primitive prevents: the day the extension set widens, one copy would
+ * widen with it. Same reason `read-lines.ts` exists one file over.
+ *
+ * A THIRD copy existed anyway, one layer out: the globs in
+ * `src/core/runtime/host-facts.ts` decide what the machine-wide sweep
+ * enrols, and the Codex rows named a wider extension set than this walk
+ * accepted. The extension itself therefore lives in the session
+ * vocabulary now ({@link SESSION_FILE_EXTENSION}), which both this
+ * primitive and those rows read.
+ *
+ * Symlinks are skipped rather than followed. A cycle would drive the walker
+ * into unbounded recursion, and a session export that follows links out of
+ * the directory the operator named is reaching further than they asked.
+ */
+
+import { lstatSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { SESSION_FILE_EXTENSION, SessionImportError } from "./types.ts";
+
+/**
+ * How deep the walk goes before it refuses.
+ *
+ * Symlinks are skipped, so a cycle cannot drive the recursion - but a
+ * pathologically deep real tree still can, and an unbounded recursive
+ * walk answers that with a stack overflow rather than a sentence. Every
+ * declared session root is at most four components deep below its own
+ * base (`~/.claude/projects/<encoded-cwd>/<file>`,
+ * `~/.grok/sessions/<cwd>/<id>/updates.jsonl`), so 32 is far past any
+ * layout this build expects and still a bound.
+ */
+const MAX_WALK_DEPTH = 32;
+
+/**
+ * True when a file inside a directory is a session transcript by name.
+ *
+ * Exported so the machine-wide sweep and this walk cannot answer the
+ * question differently - see {@link SESSION_FILE_EXTENSION} for the three
+ * answers that existed before there was one.
+ */
+export function isSessionFileName(name: string): boolean {
+ return name.endsWith(SESSION_FILE_EXTENSION);
+}
+
+/**
+ * Every session transcript under `path`, sorted.
+ *
+ * A path naming a FILE is returned as the single-element list, whatever
+ * its extension: the operator named that file, so filtering it out would
+ * answer an explicit request with silence. Inside a DIRECTORY the
+ * extension is the only thing separating a transcript from a README, so
+ * there it is applied.
+ *
+ * Throws {@link SessionImportError} with code `IO` when the path does not
+ * exist or cannot be stat'ed, when a subdirectory of it cannot be listed,
+ * or when the tree is deeper than {@link MAX_WALK_DEPTH} - an unreadable
+ * source is not an empty one, and that has to hold for every level of the
+ * walk rather than only for the level the caller named. A `readdirSync`
+ * that was left unguarded turned one mode-000 subdirectory into a raw
+ * `EACCES` errno escaping through both the import and the transcript
+ * export, where the sibling sweep in `discover.ts` reports the same
+ * condition as `unreadable` and carries on.
+ */
+export function sessionFilesUnder(path: string): ReadonlyArray<string> {
+ let root;
+ try {
+ root = statSync(path);
+ } catch (err) {
+ throw ioRefusal(path, err);
+ }
+ if (root.isFile()) return Object.freeze([path]);
+
+ const found: string[] = [];
+ const collect = (dir: string, depth: number): void => {
+ if (depth > MAX_WALK_DEPTH) {
+ throw new SessionImportError(
+ "IO",
+ `session path ${path} nests deeper than ${MAX_WALK_DEPTH} directories at ${dir}; ` +
+ "point the import or export at the subdirectory that holds the transcripts",
+ );
+ }
+ let names: string[];
+ try {
+ names = readdirSync(dir);
+ } catch (err) {
+ throw ioRefusal(dir, err);
+ }
+ for (const name of names) {
+ const full = join(dir, name);
+ let entry;
+ try {
+ // lstat, not stat: a symlink cycle would otherwise recurse forever.
+ entry = lstatSync(full);
+ } catch {
+ continue;
+ }
+ if (entry.isSymbolicLink()) continue;
+ if (entry.isDirectory()) {
+ collect(full, depth + 1);
+ continue;
+ }
+ if (isSessionFileName(name)) found.push(full);
+ }
+ };
+ collect(path, 0);
+ found.sort();
+ return Object.freeze(found);
+}
+
+/** One spelling of "this level of the walk could not be read". */
+function ioRefusal(at: string, err: unknown): SessionImportError {
+ const detail = err instanceof Error ? err.message : String(err);
+ return new SessionImportError(
+ "IO",
+ `cannot read session path ${at}: ${detail}; check the path exists and is readable`,
+ );
+}
diff --git a/src/core/brain/sessions/types.ts b/src/core/brain/sessions/types.ts
index 254e0101..17cb6404 100644
--- a/src/core/brain/sessions/types.ts
+++ b/src/core/brain/sessions/types.ts
@@ -22,6 +22,51 @@
* from the caller, or from the delegated turn itself.
*/
+/**
+ * The extension a session transcript is written with, stated once for
+ * every consumer that has to decide whether a file is one.
+ *
+ * There were three answers to that question and they disagreed.
+ * `session-files.ts` - the primitive extracted precisely so the two
+ * walkers could not drift - accepted `.jsonl`; the Codex rows in
+ * `src/core/runtime/host-facts.ts` declared `**` + `/*.json*`, so the
+ * machine-wide sweep enrolled `.json` files that `import-session <dir>`
+ * and `export --transcripts <dir>` then skipped without a word; and every
+ * shipped adapter parses line-delimited JSON and can read neither a
+ * pretty-printed `.json` nor anything else. This constant is the one
+ * answer, and it sits in the vocabulary module because that is the only
+ * thing `host-facts.ts` is allowed to import from here.
+ *
+ * Narrow rather than wide on purpose. Enrolling `.json` into discovery
+ * does not make a `.json` importable - no adapter in this build can read
+ * one - it only turns every such file into a `DETECT_FAIL` that drives
+ * `--discover --all` to exit 1. Finding a file this build cannot parse is
+ * worse than not finding it, because a failure an operator cannot fix is
+ * indistinguishable from one they can.
+ */
+export const SESSION_FILE_EXTENSION = ".jsonl";
+
+/**
+ * What every adapter puts in {@link SessionTurn.timestamp} when the line
+ * it read carried no usable one: the Unix epoch, as an ISO instant.
+ *
+ * `SessionTurn.timestamp` is not optional, so an adapter facing a line
+ * without a clock has to write something, and all five write this. That
+ * made the sentinel a real part of the contract while it was spelled
+ * `new Date(0).toISOString()` in five files and described in prose in a
+ * sixth (`resolveEventInstant`, which already reads `ms <= 0` as "no
+ * timestamp"). A consumer that did not know the convention could not
+ * distinguish "recorded at the epoch" from "not recorded", and the
+ * transcript export's `--since` window did exactly that: it compared the
+ * sentinel as an instant, found it before every realistic window, and
+ * silently dropped the transcript - the outcome its own docblock forbids.
+ *
+ * Naming it is what lets a consumer ask the question. It is a SENTINEL,
+ * not a time: code that means "is this turn inside a window" must check
+ * for it before it parses.
+ */
+export const SESSION_TIMESTAMP_UNKNOWN = new Date(0).toISOString();
+
/**
* The runtimes whose adapters ship in this tree.
*
diff --git a/src/core/brain/snapshot-gate.ts b/src/core/brain/snapshot-gate.ts
index 42651abc..c88262f9 100644
--- a/src/core/brain/snapshot-gate.ts
+++ b/src/core/brain/snapshot-gate.ts
@@ -42,7 +42,7 @@
import { existsSync } from "node:fs";
import { loadSnapshotRetentionSafe } from "./policy.ts";
-import { isFileAlreadyExists } from "../fs-atomic.ts";
+import { isFileAlreadyExistsAt } from "../fs-atomic.ts";
import {
classifyRecoverability,
DEFAULT_DESTRUCTIVE_BLAST_RADIUS,
@@ -157,14 +157,14 @@ const MAX_SNAPSHOT_ID_ATTEMPTS = 64;
* {@link collisionCandidateName}, and retry when the create reports that
* the name was already taken.
*
- * The retry is keyed on the TYPED collision predicate. It used to be keyed
- * on re-running `existsSync` after the throw, which answered a different
- * question than the one being asked: any failure that happened to leave
- * bytes at the path - a compressor that died part-way through its output -
- * read as a collision, was retried up to the bound, and was finally
- * reported as an id exhaustion naming neither the real failure nor its
- * cause. Only "the name was taken" retries now; everything else propagates
- * from the attempt that raised it.
+ * The retry is keyed on the TYPED collision predicate, applied to THIS
+ * candidate's archive path. It used to be keyed on re-running `existsSync`
+ * after the throw, which answered a different question than the one being
+ * asked: any failure that happened to leave bytes at the path - a compressor
+ * that died part-way through its output - read as a collision, was retried up
+ * to the bound, and was finally reported as an id exhaustion naming neither
+ * the real failure nor its cause. Only "the name was taken" retries now;
+ * everything else propagates from the attempt that raised it.
*
* `create` is injected for the same reason `allocateAndCreate` takes one:
* it is the seam that makes the lost-race behaviour testable as a
@@ -176,13 +176,26 @@ const MAX_SNAPSHOT_ID_ATTEMPTS = 64;
* rather than two: the dream pass had its own copy, over the same
* candidate sequence, with a different bound.
*
- * Caveat worth stating rather than hiding: `createSnapshot` today flattens
- * its own "refusing to overwrite an existing archive" into an untyped
- * `BrainSnapshotError`, so a genuinely lost race reaches the operator as
- * that loud, accurate error instead of being retried here. Making it
- * retryable is a one-line change in `snapshot.ts` (carry the collision as
- * `cause`), deliberately left outside this unit's file scope. Loud and
- * correct beats silently retried and mislabelled.
+ * Which path the collision names is the whole discriminator, not a detail.
+ * `createSnapshot` wraps its "refusing to overwrite an existing archive" in a
+ * `BrainSnapshotError` carrying a {@link FileAlreadyExistsError} as `cause`,
+ * and the gzip write carries the raw `wx` errno the same way, so a lost race
+ * IS recognised and retried here. But an EEXIST is not self-evidently a lost
+ * race: `createSnapshot`'s first disk touch is `mkdir Brain/.snapshots`, and
+ * on a host where that directory is a regular file the errno it raises is an
+ * EEXIST about the DIRECTORY, before any archive exists to lose a race over.
+ * Keyed on the errno alone (GitHub #167) that laddered through every
+ * candidate and reported an id exhaustion nobody had caused, with the real
+ * failure hidden on `cause`. Keyed on
+ * {@link snapshotPath}`(vault, candidate)` it propagates from attempt 1.
+ *
+ * Not covered, and stated rather than hidden: the derived-store archive's
+ * own "refusing to overwrite an existing archive" (`snapshot.ts`,
+ * `coverDerivedStore`) is an untyped `BrainSnapshotError` with no `cause`,
+ * so a stale `<runId>.store.sqlite.zst` beside a free `<runId>.tar.zst`
+ * aborts here where the tar collision would ladder. That is the loud and
+ * accurate failure, not a silent one, and giving it a cause is a change in
+ * `snapshot.ts` with its own coverage to write.
*/
export function createUniqueSnapshot(
vault: string,
@@ -194,12 +207,13 @@ export function createUniqueSnapshot(
let lostRace: unknown;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const candidate = collisionCandidateName(baseRunId, attempt);
- if (existsSync(snapshotPath(vault, candidate))) continue;
+ const candidatePath = snapshotPath(vault, candidate);
+ if (existsSync(candidatePath)) continue;
if (!available(candidate)) continue;
try {
return { runId: candidate, path: create(candidate), prune: null };
} catch (err) {
- if (!isFileAlreadyExists(err)) throw err;
+ if (!isFileAlreadyExistsAt(err, candidatePath)) throw err;
lostRace = err;
}
}
diff --git a/src/core/brain/snapshot.ts b/src/core/brain/snapshot.ts
index 22d172ec..2e5259d7 100644
--- a/src/core/brain/snapshot.ts
+++ b/src/core/brain/snapshot.ts
@@ -77,6 +77,7 @@ import {
closeSync,
cpSync,
existsSync,
+ lstatSync,
mkdirSync,
mkdtempSync,
openSync,
@@ -111,6 +112,7 @@ import {
import {
BRAIN_ROOT_REL,
BRAIN_SNAPSHOT_EXCLUDED_ENTRIES,
+ BRAIN_SNAPSHOTS_REL,
brainDirs,
brainDirsForWrite,
SNAPSHOT_ARCHIVE_SUFFIX,
@@ -147,8 +149,9 @@ export class BrainSnapshotError extends Error {
/**
* `cause` is forwarded rather than flattened into the message because the
* caller that allocates a unique run id retries a lost race and has to
- * recognise a collision by its errno. `createUniqueSnapshot` keys on
- * `isFileAlreadyExists`, which walks the cause chain; an error that only
+ * recognise a collision by its errno AND the path it names.
+ * `createUniqueSnapshot` keys on
+ * `isFileAlreadyExistsAt`, which walks the cause chain; an error that only
* described its errno in prose would turn a retriable collision into a
* terminal failure, which is the shape this release removes.
*/
@@ -591,6 +594,74 @@ function detectTooling(): ToolAvailability {
// ----- createSnapshot ------------------------------------------------------
+/**
+ * Make `Brain/.snapshots/` exist, or say what is there instead.
+ *
+ * This `mkdir` is the first disk touch of every snapshot, which makes it the
+ * first thing that can fail and the worst place to fail opaquely. It used to
+ * be a bare `mkdirSync`, so its errno left the module naming a syscall and a
+ * path and nothing else - and, worse, reached the run-id allocator in
+ * `snapshot-gate.ts`, which read the EEXIST as a lost race over the run id
+ * and reported an id exhaustion that had never happened (GitHub #167).
+ *
+ * `recursive: true` already tolerates the normal case of the directory
+ * existing, so a throw from here means the path is NOT a usable directory.
+ * Which of the several ways that can be true is the only question the
+ * operator has, and it is answerable on the spot: `lstat` the path and say
+ * what is really there. A regular file, a symlink, a socket left by some
+ * other tool, a parent that is not a directory, a permission fault - each has
+ * a different remedy and the errno alone distinguishes none of them.
+ *
+ * The errno is carried as `cause`, not folded away: the diagnosis explains
+ * the failure, it does not replace the evidence. A {@link BrainSnapshotError}
+ * rather than a bare throw so this leaves the module in the one shape every
+ * caller of {@link createSnapshot} already handles, run id included.
+ */
+function ensureSnapshotsDirectory(path: string, runId: string): void {
+ try {
+ mkdirSync(path, { recursive: true });
+ return;
+ } catch (err) {
+ throw new BrainSnapshotError(
+ `cannot use the archive directory ${BRAIN_SNAPSHOTS_REL} at ${path}: ` +
+ `${describeExistingPath(path)} (${(err as Error).message ?? String(err)}); ` +
+ `no recovery point can be written until ${BRAIN_SNAPSHOTS_REL} is a writable directory`,
+ runId,
+ { cause: err },
+ );
+ }
+}
+
+/**
+ * What is actually at `path`, in one clause an operator can act on.
+ *
+ * `lstat` rather than `stat` because a dangling or looping symlink is one of
+ * the states that produces this failure, and `stat` would report the target's
+ * absence instead of the link's presence. Its own failure is reported rather
+ * than swallowed: "the path cannot even be inspected" is a different remedy
+ * (permissions on the parent) from "the path holds the wrong kind of thing".
+ */
+function describeExistingPath(path: string): string {
+ let info: ReturnType<typeof lstatSync>;
+ try {
+ info = lstatSync(path);
+ } catch (err) {
+ const code = (err as NodeJS.ErrnoException).code;
+ if (code === "ENOENT") return "nothing is there, so the directory itself could not be created";
+ return `it could not be inspected either (${code ?? (err as Error).message})`;
+ }
+ if (info.isDirectory()) return "it is a directory, but it could not be created or opened as one";
+ if (info.isSymbolicLink()) {
+ return existsSync(path)
+ ? "it is a symbolic link to something that is not a usable directory"
+ : "it is a symbolic link whose target does not exist";
+ }
+ if (info.isFile()) return "it is a regular file";
+ if (info.isSocket()) return "it is a socket";
+ if (info.isFIFO()) return "it is a FIFO";
+ return "it is not a directory";
+}
+
/**
* Archive `Brain/` (minus {@link BRAIN_SNAPSHOT_EXCLUDED_ENTRIES}) into
* `Brain/.snapshots/<run_id>.tar.zst`, optionally beside a compressed
@@ -616,7 +687,7 @@ export function createSnapshot(
): CreateSnapshotResult {
validateRunId(runId);
const dirs = brainDirsForWrite(vault);
- mkdirSync(dirs.snapshots, { recursive: true });
+ ensureSnapshotsDirectory(dirs.snapshots, runId);
const outPath = snapshotPath(vault, runId);
const tools = detectTooling();
diff --git a/src/core/brain/types.ts b/src/core/brain/types.ts
index 1c900307..a3f28692 100644
--- a/src/core/brain/types.ts
+++ b/src/core/brain/types.ts
@@ -1429,6 +1429,29 @@ export interface ResolvedBrainMaintenanceConfig {
readonly failure_streak_limit: number;
}
+/**
+ * The `install:` block: the two settings that parameterise GENERATED
+ * install and hook output.
+ *
+ * They live in the committed vault configuration rather than the
+ * machine-local `config.yaml` because generated content is compared by
+ * re-construction, so two machines sharing one vault must reconstruct the
+ * same bytes. A knob that lived only on the machine would make one of
+ * them report drift the other cannot see.
+ */
+export interface BrainInstallConfig {
+ /** Seconds a generated lifecycle hook entry may run before the host kills it. */
+ readonly hook_timeout_seconds?: number;
+ /** Name of the MCP tool-surface profile generated install content selects. */
+ readonly tool_profile?: string;
+}
+
+/** {@link BrainInstallConfig} with every field decided. */
+export interface ResolvedBrainInstallConfig {
+ readonly hook_timeout_seconds: number;
+ readonly tool_profile: string;
+}
+
export interface BrainLessonsConfig {
/** Exponential half-life of the recency decay, in days. */
readonly half_life_days?: number;
@@ -1623,6 +1646,12 @@ export interface BrainConfig {
* `resolveMaintenance`, which leaves the pressure gate unconfigured.
*/
readonly maintenance?: BrainMaintenanceConfig;
+ /**
+ * Optional `install:` block. Parameterises generated install and hook
+ * output; absent leaves `BRAIN_INSTALL_DEFAULTS` in force, which is the
+ * output every vault generated before the block existed.
+ */
+ readonly install?: BrainInstallConfig;
/** Optional daily discipline-report configuration (Β§D). Absent when not configured. */
readonly discipline_report?: DisciplineReportConfig;
/**
diff --git a/src/core/discipline/transcripts/claude-code.ts b/src/core/discipline/transcripts/claude-code.ts
index 20084974..652ffa62 100644
--- a/src/core/discipline/transcripts/claude-code.ts
+++ b/src/core/discipline/transcripts/claude-code.ts
@@ -1,62 +1,78 @@
/**
* Claude Code session-transcript paths for the discipline report.
*
- * Reuses the same `~/.claude/projects/*` layout that
- * `o2b brain import-claude-memory` walks. We treat any `.jsonl`
- * session file as evidence of agent activity on the day matching
- * its mtime.
+ * The `~/.claude/projects/*` layout used to be spelled here, a second
+ * time in `src/core/brain/claude-memory-paths.ts`, and a third time in
+ * the docblock of the session adapter. It is now declared once in
+ * `src/core/runtime/host-facts.ts` and read from there; what stays local
+ * is this scanner's own question - which files were TOUCHED inside the
+ * report's local day - and the `TRANSCRIPT_SCAN` vocabulary that answers
+ * which emptiness produced an empty list.
*/
import { existsSync, readdirSync, statSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
+import {
+ resolveSessionRootsFor,
+ SESSION_RUNTIME_ID,
+ type HostContext,
+} from "../../runtime/host-facts.ts";
import {
classifyTranscriptScan,
type TranscriptRuntime,
type TranscriptScanResult,
} from "./types.ts";
+/** The declared roots for Claude Code against one host. */
+function roots(ctx: HostContext): ReadonlyArray<string> {
+ return resolveSessionRootsFor(SESSION_RUNTIME_ID.claudeCode, ctx).map((root) => root.path);
+}
+
export const claudeCodeTranscript: TranscriptRuntime = {
runtime: "claudecode",
agentHint: "claude-vps-agent",
- scan(dayStartMs, dayEndMs, home = homedir()): TranscriptScanResult {
- const base = join(home, ".claude", "projects");
+ scan(dayStartMs, dayEndMs, home = homedir(), env = process.env): TranscriptScanResult {
const files: string[] = [];
const unreadable: string[] = [];
- if (!existsSync(base)) return classifyTranscriptScan(false, files, unreadable);
+ let rootsPresent = false;
+ for (const base of roots({ home, env })) {
+ if (!existsSync(base)) continue;
+ rootsPresent = true;
- let entries: string[];
- try {
- entries = readdirSync(base);
- } catch {
- // The store is there; we simply cannot see inside it. Reporting zero
- // files here without saying so is the defect this scan exists to fix.
- unreadable.push(base);
- return classifyTranscriptScan(true, files, unreadable);
- }
- for (const entry of entries) {
- const projectDir = join(base, entry);
- let projectFiles: string[];
+ let entries: string[];
try {
- projectFiles = readdirSync(projectDir);
+ entries = readdirSync(base);
} catch {
- unreadable.push(projectDir);
+ // The store is there; we simply cannot see inside it. Reporting zero
+ // files here without saying so is the defect this scan exists to fix.
+ unreadable.push(base);
continue;
}
- for (const name of projectFiles) {
- if (!name.endsWith(".jsonl")) continue;
- const full = join(projectDir, name);
+ for (const entry of entries) {
+ const projectDir = join(base, entry);
+ let projectFiles: string[];
try {
- const ms = statSync(full).mtimeMs;
- if (ms >= dayStartMs && ms < dayEndMs) files.push(full);
+ projectFiles = readdirSync(projectDir);
} catch {
- // A file whose mtime cannot be read cannot be placed in or out of
- // the window, so it is uncounted rather than assumed absent.
- unreadable.push(full);
+ unreadable.push(projectDir);
+ continue;
+ }
+ for (const name of projectFiles) {
+ if (!name.endsWith(".jsonl")) continue;
+ const full = join(projectDir, name);
+ try {
+ const ms = statSync(full).mtimeMs;
+ if (ms >= dayStartMs && ms < dayEndMs) files.push(full);
+ } catch {
+ // A file whose mtime cannot be read cannot be placed in or out of
+ // the window, so it is uncounted rather than assumed absent.
+ unreadable.push(full);
+ }
}
}
}
- return classifyTranscriptScan(true, files, unreadable);
+ return classifyTranscriptScan(rootsPresent, files, unreadable);
},
};
diff --git a/src/core/discipline/transcripts/codex.ts b/src/core/discipline/transcripts/codex.ts
index 32a08029..ff015dce 100644
--- a/src/core/discipline/transcripts/codex.ts
+++ b/src/core/discipline/transcripts/codex.ts
@@ -1,45 +1,40 @@
/**
* Codex session-transcript paths for the discipline report.
*
- * Codex stores per-session JSON files under `~/.codex/`. The exact
- * subdirectory has moved between CLI releases (`sessions/`, `.tmp/`,
- * etc.); we walk every immediate subdirectory of `~/.codex/` and look
- * for `.json` files whose mtime falls in the day window.
+ * Codex stores per-session JSON files under `$CODEX_HOME` (default
+ * `~/.codex`), and the exact subdirectory has moved between CLI releases
+ * (`sessions/`, `session/`, `history/`, `.tmp/`). That list used to be
+ * spelled here AND in `src/core/runtime/host-facts.ts`; it is now
+ * declared once there and read from here. What stays local is this
+ * scanner's own question - which `.json` files were TOUCHED inside the
+ * report's local day, three levels deep - and the `TRANSCRIPT_SCAN`
+ * vocabulary that answers which emptiness produced an empty list.
*/
import { existsSync, readdirSync, statSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
+import { resolveSessionRootsFor, SESSION_RUNTIME_ID } from "../../runtime/host-facts.ts";
import {
classifyTranscriptScan,
type TranscriptRuntime,
type TranscriptScanResult,
} from "./types.ts";
-/** Subdirectories of `~/.codex/` that have held session files across releases. */
-const CANDIDATE_SUBDIRS: ReadonlyArray<string> = Object.freeze([
- "sessions",
- "session",
- "history",
- ".tmp",
-]);
-
const MAX_DEPTH = 3;
export const codexTranscript: TranscriptRuntime = {
runtime: "codex",
agentHint: "codex-vps-agent",
- scan(dayStartMs, dayEndMs, home = homedir()): TranscriptScanResult {
- const base = join(home, ".codex");
+ scan(dayStartMs, dayEndMs, home = homedir(), env = process.env): TranscriptScanResult {
const files: string[] = [];
const unreadable: string[] = [];
let rootsPresent = false;
- for (const sub of CANDIDATE_SUBDIRS) {
- const dir = join(base, sub);
- if (!existsSync(dir)) continue;
+ for (const root of resolveSessionRootsFor(SESSION_RUNTIME_ID.codex, { home, env })) {
+ if (!existsSync(root.path)) continue;
rootsPresent = true;
- pushJsonInRange(dir, dayStartMs, dayEndMs, files, unreadable, MAX_DEPTH);
+ pushJsonInRange(root.path, dayStartMs, dayEndMs, files, unreadable, MAX_DEPTH);
}
return classifyTranscriptScan(rootsPresent, files, unreadable);
},
diff --git a/src/core/discipline/transcripts/cursor.ts b/src/core/discipline/transcripts/cursor.ts
index aa2c181b..0ac4e77e 100644
--- a/src/core/discipline/transcripts/cursor.ts
+++ b/src/core/discipline/transcripts/cursor.ts
@@ -2,17 +2,22 @@
* Cursor session-transcript paths for the discipline report.
*
* Cursor stores per-workspace chat history in `state.vscdb` SQLite
- * files. We probe both the Linux layout
- * (`~/.config/Cursor/User/workspaceStorage/<hash>/state.vscdb`) and
- * the macOS layout (under `~/Library/Application Support/Cursor/`).
- * collect() remains the mtime probe for backward compat; collectDetail()
- * does a deeper SQLite parse when bun:sqlite is available.
+ * files, under one of three layouts different builds have used. Those
+ * three used to be listed here; they are declared once in
+ * `src/core/runtime/host-facts.ts` and read from there. What stays local
+ * is this scanner's own question - which databases were TOUCHED inside
+ * the report's local day - and the deeper `collectDetail` parse.
*/
import { existsSync, readdirSync, statSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
+import {
+ resolveSessionRootsFor,
+ SESSION_RUNTIME_ID,
+ type HostContext,
+} from "../../runtime/host-facts.ts";
import {
classifyTranscriptScan,
type TranscriptDetail,
@@ -20,19 +25,14 @@ import {
type TranscriptScanResult,
} from "./types.ts";
-/** Every layout a Cursor build has used for per-workspace storage. */
-function workspaceStorageRoots(home: string): ReadonlyArray<string> {
- return [
- join(home, ".config", "Cursor", "User", "workspaceStorage"),
- join(home, "Library", "Application Support", "Cursor", "User", "workspaceStorage"),
- // macOS XDG-style fallback used by some Cursor builds
- join(home, ".cursor", "workspaceStorage"),
- ];
+/** Every layout a Cursor build has used, from the one declaration. */
+function workspaceStorageRoots(ctx: HostContext): ReadonlyArray<string> {
+ return resolveSessionRootsFor(SESSION_RUNTIME_ID.cursor, ctx).map((root) => root.path);
}
-function findDatabases(home: string): string[] {
+function findDatabases(ctx: HostContext): string[] {
const out: string[] = [];
- for (const root of workspaceStorageRoots(home)) {
+ for (const root of workspaceStorageRoots(ctx)) {
if (!existsSync(root)) continue;
let dirs: import("node:fs").Dirent[];
try {
@@ -123,11 +123,11 @@ function queryCursorDb(
export const cursorTranscript: TranscriptRuntime = {
runtime: "cursor",
agentHint: "cursor-vps-agent",
- scan(dayStartMs, dayEndMs, home = homedir()): TranscriptScanResult {
+ scan(dayStartMs, dayEndMs, home = homedir(), env = process.env): TranscriptScanResult {
const files: string[] = [];
const unreadable: string[] = [];
let rootsPresent = false;
- for (const root of workspaceStorageRoots(home)) {
+ for (const root of workspaceStorageRoots({ home, env })) {
if (!existsSync(root)) continue;
rootsPresent = true;
let dirs: import("node:fs").Dirent[];
@@ -151,8 +151,13 @@ export const cursorTranscript: TranscriptRuntime = {
}
return classifyTranscriptScan(rootsPresent, files, unreadable);
},
- collectDetail(dayStartMs, dayEndMs, home = homedir()): TranscriptDetail | null {
- const dbs = findDatabases(home);
+ collectDetail(
+ dayStartMs,
+ dayEndMs,
+ home = homedir(),
+ env = process.env,
+ ): TranscriptDetail | null {
+ const dbs = findDatabases({ home, env });
let totalSessions = 0;
let totalMessages = 0;
diff --git a/src/core/discipline/transcripts/index.ts b/src/core/discipline/transcripts/index.ts
index 91edc383..974df934 100644
--- a/src/core/discipline/transcripts/index.ts
+++ b/src/core/discipline/transcripts/index.ts
@@ -32,6 +32,13 @@ export interface CollectTranscriptOpts {
readonly dayStartMs: number;
readonly dayEndMs: number;
readonly home?: string;
+ /**
+ * The environment the declared roots resolve against. Carried beside
+ * `home` because several roots are moved by a variable rather than by
+ * the home directory (`$CODEX_HOME`, `$GROK_HOME`), and a caller that
+ * could only inject `home` would silently miss a relocated store.
+ */
+ readonly env?: Readonly<Record<string, string | undefined>>;
readonly runtimes?: ReadonlyArray<TranscriptRuntime>;
}
@@ -49,7 +56,7 @@ export function collectTranscriptActivity(opts: CollectTranscriptOpts): Transcri
for (const r of runtimes) {
let scan;
try {
- scan = r.scan(opts.dayStartMs, opts.dayEndMs, opts.home);
+ scan = r.scan(opts.dayStartMs, opts.dayEndMs, opts.home, opts.env);
} catch (err) {
scan = {
state: TRANSCRIPT_SCAN.unreadable,
@@ -59,7 +66,7 @@ export function collectTranscriptActivity(opts: CollectTranscriptOpts): Transcri
}
let detail = null;
try {
- detail = r.collectDetail?.(opts.dayStartMs, opts.dayEndMs, opts.home) ?? null;
+ detail = r.collectDetail?.(opts.dayStartMs, opts.dayEndMs, opts.home, opts.env) ?? null;
} catch {
// The detail pass is an enrichment of a count that already stands; its
// failure is reported by the scan state, not by losing the count.
diff --git a/src/core/discipline/transcripts/types.ts b/src/core/discipline/transcripts/types.ts
index 1d6bbcf1..87aff4c8 100644
--- a/src/core/discipline/transcripts/types.ts
+++ b/src/core/discipline/transcripts/types.ts
@@ -87,10 +87,28 @@ export interface TranscriptRuntime {
/**
* Walk this runtime's store for transcript files that show activity
* inside the half-open day window `[dayStartMs, dayEndMs)`, and report
- * which emptiness produced an empty list. `home` is injectable for tests.
+ * which emptiness produced an empty list.
+ *
+ * `home` and `env` together are the {@link HostContext} the runtime's
+ * declared roots resolve against. Both are injectable and both default
+ * to this machine: the roots live in `src/core/runtime/host-facts.ts`
+ * and several of them are moved by an environment variable
+ * (`$CODEX_HOME`, `$GROK_HOME`), so a scanner that took only `home`
+ * could be pointed at a test fixture and still miss a relocated store
+ * on a real one.
*/
- scan(dayStartMs: number, dayEndMs: number, home?: string): TranscriptScanResult;
- collectDetail?(dayStartMs: number, dayEndMs: number, home?: string): TranscriptDetail | null;
+ scan(
+ dayStartMs: number,
+ dayEndMs: number,
+ home?: string,
+ env?: Readonly<Record<string, string | undefined>>,
+ ): TranscriptScanResult;
+ collectDetail?(
+ dayStartMs: number,
+ dayEndMs: number,
+ home?: string,
+ env?: Readonly<Record<string, string | undefined>>,
+ ): TranscriptDetail | null;
}
export interface TranscriptDetail {
diff --git a/src/core/doctor-readiness.ts b/src/core/doctor-readiness.ts
index 53068eb1..123925aa 100644
--- a/src/core/doctor-readiness.ts
+++ b/src/core/doctor-readiness.ts
@@ -430,9 +430,10 @@ export async function probeRuntimeAdapterWiring(opts: ReadinessOptions): Promise
*
* Delegating to `verify` rather than re-reading the runtime config files
* here is the whole point: the adapter already knows where its config
- * lives, what the canonical payload looks like for it, and - for the one
- * runtime that has a CLI to ask (`copilot-cli`) - how to consult the
- * runtime itself. Re-implementing any of that in a doctor probe would
+ * lives, what the canonical payload looks like for it, and - for the
+ * runtimes that have a CLI to ask (`copilot-cli`, `codex`) - how to
+ * consult the runtime itself. Re-implementing any of that in a doctor
+ * probe would
* produce a second, quietly divergent opinion about the same disk.
*
* The closed `VerifyStatus` vocabulary maps onto readiness with no
@@ -444,9 +445,10 @@ export async function probeRuntimeAdapterWiring(opts: ReadinessOptions): Promise
* manifest we cannot read is not a machine with nothing installed.
*/
/**
- * NOTE ON THE TIMEOUT: every `verify` here is synchronous, and
- * `copilot-cli` verifies by spawning its own CLI synchronously. While that
- * spawn runs, the event loop is blocked and the runner's timeout timer
+ * NOTE ON THE TIMEOUT: every `verify` here is synchronous, and both
+ * `copilot-cli` and `codex` verify by spawning their own CLI
+ * synchronously. While that spawn runs, the event loop is blocked and the
+ * runner's timeout timer
* cannot fire, so this probe is the one the module-level timeout promise
* does not cover. Making it interruptible means an async adapter contract,
* which is a change to every adapter and belongs in its own unit.
diff --git a/src/core/egress/guard.ts b/src/core/egress/guard.ts
index b0edfbb4..424e4d1b 100644
--- a/src/core/egress/guard.ts
+++ b/src/core/egress/guard.ts
@@ -109,6 +109,21 @@ export interface EgressRefused {
| typeof EGRESS_OUTCOME.refusedSecretIdentifier;
/** Operator-facing sentence naming the verb and what to do about it. */
readonly detail: string;
+ /**
+ * The tree locations the structural scan reported as secret-shaped
+ * identifiers, already inside {@link detail} and carried structurally as
+ * well. Empty on the truncation arm.
+ *
+ * A caller composing its own prefix around `detail` has to know WHICH
+ * identifier was refused before it can decide what is safe to say. The
+ * transcript export is the case: it named each refused record by its
+ * `session_id`, which is the transcript's basename - so when the
+ * basename was itself the secret-shaped identifier, the refusal printed
+ * the exact value it had just declined to write. Reading the list is
+ * what lets that caller withhold the name on that one branch and keep
+ * printing it on every other.
+ */
+ readonly secretIdentifiers: ReadonlyArray<string>;
}
/**
@@ -139,16 +154,43 @@ const SCAN_WINDOW_MIB = MAX_REDACTOR_INPUT / (1024 * 1024);
export const EGRESS_REDACTION_NOTICE =
"note: secret-shaped content was redacted; this export no longer matches the vault byte for byte\n";
+/**
+ * What a call site may vary about the one policy above.
+ *
+ * Deliberately not a second policy constant: the redaction options stay
+ * single, and this names the one decision that cannot be answered once for
+ * every site because it depends on WHERE the payload's identifiers were
+ * named rather than on where they are going.
+ */
+export interface EgressPolicy {
+ /**
+ * The payload's identifiers were named outside this vault, so judge them
+ * with the full bare-token detector rather than vendor prefixes alone.
+ * Set by the transcript corpus and nothing else - see
+ * `foreignIdentifierCarriesSecret` in the redactor for why the default
+ * is right for every vault-authored export.
+ */
+ readonly foreignIdentifiers?: boolean;
+}
+
/**
* Redact `payload` for `site`, or refuse it. The payload may be a string
* or any JSON-shaped tree; see `redactStructured` for why the tree form
* exists rather than a pass over serialised bytes.
*/
-export function redactForEgress<T>(site: EgressSiteId, payload: T): EgressVerdict<T> {
- const scanned = redactStructured(payload, EGRESS_REDACTION_OPTIONS);
+export function redactForEgress<T>(
+ site: EgressSiteId,
+ payload: T,
+ policy: EgressPolicy = {},
+): EgressVerdict<T> {
+ const scanned = redactStructured(payload, {
+ ...EGRESS_REDACTION_OPTIONS,
+ ...(policy.foreignIdentifiers === true ? { foreignIdentifiers: true } : {}),
+ });
if (scanned.truncated) {
return {
outcome: EGRESS_OUTCOME.refusedScanTruncated,
+ secretIdentifiers: Object.freeze([]),
detail:
`${EGRESS_SITES[site].verb} refused to write: a field exceeded the redactor ` +
`scan window (${SCAN_WINDOW_MIB} MiB), so only part of it was scanned and this ` +
@@ -159,6 +201,7 @@ export function redactForEgress<T>(site: EgressSiteId, payload: T): EgressVerdic
if (scanned.secretIdentifiers.length > 0) {
return {
outcome: EGRESS_OUTCOME.refusedSecretIdentifier,
+ secretIdentifiers: scanned.secretIdentifiers,
detail:
`${EGRESS_SITES[site].verb} refused to write: an identifier is secret-shaped, and an ` +
"identifier is never rewritten - a redacted filename merges the pages it names and a " +
diff --git a/src/core/egress/registry.ts b/src/core/egress/registry.ts
index 1c40c172..b528d2dc 100644
--- a/src/core/egress/registry.ts
+++ b/src/core/egress/registry.ts
@@ -141,15 +141,32 @@ export const EGRESS_SITES = Object.freeze({
"full, because the `<private>` region marker is this product's only content-derived " +
"privacy primitive and these composers are content composers, not visibility filters.",
},
- "brain-preference-export": {
- id: "brain-preference-export",
+ "brain-export": {
+ id: "brain-export",
verb: "o2b brain export",
module: "src/cli/brain/verbs/export.ts",
redaction: R.sharedRedactor,
reason:
"preference principles are free text an agent wrote, and the llms-txt form is " +
"meant to be pasted into a foreign prompt - the destination least likely to be " +
- "read before it is shared.",
+ "read before it is shared. One entry covers all three of the verb's formats " +
+ "because the census keys on the MODULE and the destination is declared once, in " +
+ "the verb: the JSON and transcript forms are redacted as TREES and serialised " +
+ "afterwards, llms-txt as text. What proves each branch scans is a per-handler " +
+ "check in the census, not the guard-call count - counting guards against " +
+ "DESTINATIONS is an inequality, and this module declares one destination against " +
+ "three guards, so a fourth handler that scanned nothing would satisfy it. The " +
+ "transcript form is the widest of the three by far - whole recorded " +
+ "conversations with whichever runtime wrote them, which is where a key pasted " +
+ "into a prompt actually lives. Its records are guarded ONE AT A TIME, so a " +
+ "single oversized turn cannot put a machine's whole corpus past the scan window, " +
+ "and a refusal names the conversation rather than the run - by its basename, " +
+ "except when the basename is itself the secret-shaped identifier, where it is " +
+ "named by runtime and start instant instead. The transcript branch is also the " +
+ "one caller that passes `foreignIdentifiers`, because its `session_id` and " +
+ "`turn_id` were named by the harness that wrote the transcript rather than by " +
+ "this vault, so the guard's vendor-prefix-only rule for identifiers - an " +
+ "argument about ids this build constructs - does not cover them.",
},
"config-export": {
id: "config-export",
diff --git a/src/core/fs-atomic.ts b/src/core/fs-atomic.ts
index 00c4be06..157101cf 100644
--- a/src/core/fs-atomic.ts
+++ b/src/core/fs-atomic.ts
@@ -23,7 +23,7 @@ import {
unlinkSync,
writeSync,
} from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
export interface AtomicWriteOptions {
/**
@@ -202,13 +202,63 @@ function fileAlreadyExistsMessage(displayPath: string, kind: string | undefined)
* for why it shares the kernel's code.
*/
export function isFileAlreadyExists(err: unknown): boolean {
+ return findFileAlreadyExists(err, () => true) !== null;
+}
+
+/**
+ * Is `err` a collision on THIS path specifically?
+ *
+ * The errno alone answers "something already existed", which is a weaker
+ * question than most callers are actually asking. A caller that resolves a
+ * collision by trying a different NAME - the snapshot run-id ladder in
+ * `brain/snapshot-gate.ts` - needs the collision to be about the name it is
+ * laddering, because every other EEXIST on the way to that write is a
+ * different failure with a different remedy. It read the errno alone until
+ * GitHub #167, where `mkdir Brain/.snapshots` failing with EEXIST - the
+ * archive DIRECTORY, before any archive was touched - was resolved as
+ * "a peer took this run id", laddered through every candidate, and reported
+ * as an id exhaustion that had not happened.
+ *
+ * Kept beside {@link isFileAlreadyExists} rather than in the one module that
+ * needs it today, because the two share the whole of their difficulty: the
+ * errno constant, the bounded `cause` walk, and the fact that a collision can
+ * arrive as the typed class, as the raw errno, or nested under a wrapper.
+ * A private copy elsewhere would be a second answer to the same question and
+ * would drift from this one.
+ *
+ * A node in the chain that carries the errno but no `path` does not match:
+ * it cannot be shown to be about `path`, and treating "unknown" as "yours"
+ * is exactly the assumption that produced the fictional error above. Paths
+ * are compared after `resolve`, so a relative and an absolute spelling of
+ * the same file agree.
+ */
+export function isFileAlreadyExistsAt(err: unknown, path: string): boolean {
+ const target = resolve(path);
+ return (
+ findFileAlreadyExists(err, (node) => {
+ const found = (node as { readonly path?: unknown }).path;
+ return typeof found === "string" && resolve(found) === target;
+ }) !== null
+ );
+}
+
+/**
+ * The shared bounded walk behind both predicates: the first node in the
+ * `cause` chain that carries the EEXIST errno AND satisfies `accept`, or
+ * `null`. Bounded rather than recursive-until-null because a `cause` chain
+ * can be made cyclic by a caller, and a hang inside an error handler is a
+ * worse failure than a missed match.
+ */
+function findFileAlreadyExists(err: unknown, accept: (node: object) => boolean): object | null {
let current: unknown = err;
for (let depth = 0; depth < CAUSE_WALK_LIMIT; depth += 1) {
- if (typeof current !== "object" || current === null) return false;
- if ((current as NodeJS.ErrnoException).code === FILE_EXISTS_CODE) return true;
+ if (typeof current !== "object" || current === null) return null;
+ if ((current as NodeJS.ErrnoException).code === FILE_EXISTS_CODE && accept(current)) {
+ return current;
+ }
current = (current as { readonly cause?: unknown }).cause;
}
- return false;
+ return null;
}
/**
diff --git a/src/core/install/adapters/_json-mcp.ts b/src/core/install/adapters/_json-mcp.ts
index 2e7f3878..105f6e89 100644
--- a/src/core/install/adapters/_json-mcp.ts
+++ b/src/core/install/adapters/_json-mcp.ts
@@ -20,8 +20,11 @@ import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
import { dirname } from "node:path";
import { atomicWriteFileSync } from "../../fs-atomic.ts";
+import type { InstallTargetId } from "../../runtime/host-facts.ts";
+import { handshakeNote, probeHost, probeRefutedVerdict, probeRefutes } from "../host-probe.ts";
import { payloadWithRuntimeIdentity } from "../identity.ts";
import { mergeMcpServers, removeMcpServers, OSB_KEY_FULL, OSB_KEY_WRITER } from "../json-merge.ts";
+import { payloadForHost } from "../payload-host.ts";
import { recordEntry, readManifest, removeEntry } from "../manifest.ts";
import { deepJsonEquals, expectedPayloadFromEnv, payloadKeyEquals } from "../payload-equals.ts";
import {
@@ -35,20 +38,15 @@ import {
type ManifestEntry,
type McpPayload,
type McpServerEntry,
+ type SessionPathsResult,
type UninstallResult,
type VerifyResult,
} from "../types.ts";
-
-/**
- * Stated on every clean `verify` so an `ok` cannot be read as "the
- * runtime answered". One constant, because the sentence is a property of
- * this adapter body and every target that reuses it must say it the same
- * way.
- */
-const NO_HANDSHAKE_NOTE = "configuration comparison; no MCP handshake attempted";
+import { sessionPathsFor } from "../session-paths.ts";
export interface JsonMcpAdapterSpec {
- readonly target: string;
+ /** The runtime this spec installs into; becomes `InstallAdapter.target`. */
+ readonly target: InstallTargetId;
readonly label: string;
/** Top-level key under which MCP servers live. Default `mcpServers`. */
readonly topLevelKey?: string;
@@ -91,6 +89,36 @@ function identifyPayload(spec: JsonMcpAdapterSpec, payload: McpPayload): McpPayl
return spec.runtimeIdentity ? payloadWithRuntimeIdentity(payload, spec.target) : payload;
}
+/**
+ * The payload as this target's config file must hold it: the host's own
+ * dimensions (tool profile, host id) then the runtime-identity rule.
+ *
+ * Both transforms are pure functions of the spec and the `InstallEnv`,
+ * and every path that touches the file - plan, apply, verify - goes
+ * through this one function. That is what keeps re-construction honest:
+ * a transform applied on apply but not on verify would report drift
+ * against bytes this adapter had just written itself.
+ */
+function payloadForSpec(
+ spec: JsonMcpAdapterSpec,
+ payload: McpPayload,
+ env: InstallEnv,
+): McpPayload {
+ return identifyPayload(spec, payloadForHost(spec.target, payload, env));
+}
+
+/**
+ * The same composition as {@link payloadForSpec}, rebuilt from the
+ * `InstallEnv` alone - the verify side of re-construction. It exists so
+ * the two sides cannot be assembled in different orders by accident:
+ * `verify` once applied the identity rule and not the host rule, which
+ * made every runtime-identity adapter report drift against the file it
+ * had just written.
+ */
+function expectedPayloadForSpec(spec: JsonMcpAdapterSpec, env: InstallEnv): McpPayload {
+ return identifyPayload(spec, expectedPayloadFromEnv(env, spec.target));
+}
+
function readFileOrEmpty(path: string): string {
try {
return readFileSync(path, "utf8");
@@ -265,8 +293,13 @@ export function createJsonMcpAdapter(spec: JsonMcpAdapterSpec): InstallAdapter {
};
},
- plan(payload: McpPayload, env: InstallEnv): InstallPlan {
+ plan(rawPayload: McpPayload, env: InstallEnv): InstallPlan {
const path = spec.resolveConfigPath(env);
+ // The PREVIEW prints the args that will actually be written, not
+ // the un-transformed canonical ones: a plan whose command line
+ // differs from the applied one is a plan the operator cannot use
+ // to review the change.
+ const payload = payloadForSpec(spec, rawPayload, env);
const preview =
`json-merge two keys into ${topKey} at ${path}: ` +
`${OSB_KEY_FULL} β†’ ${payload.full.command} ${payload.full.args.join(" ")}; ` +
@@ -285,7 +318,7 @@ export function createJsonMcpAdapter(spec: JsonMcpAdapterSpec): InstallAdapter {
opts: ApplyOpts,
): ApplyResult {
const path = spec.resolveConfigPath(env);
- const payload = identifyPayload(spec, rawPayload);
+ const payload = payloadForSpec(spec, rawPayload, env);
const onDisk = readOnDisk(spec, env, payload);
const manifestEntry = readManifest(env.vault).installs[spec.target];
@@ -384,6 +417,15 @@ export function createJsonMcpAdapter(spec: JsonMcpAdapterSpec): InstallAdapter {
return { target: spec.target, removed_keys, removed_paths, skipped };
},
+ /**
+ * Read off `RUNTIME_FACTS`, not off the spec. Every JSON-MCP host's
+ * session store is already declared there, and a `sessionRoots` field
+ * on {@link JsonMcpAdapterSpec} would be a second place to spell it.
+ */
+ sessionPaths(env: InstallEnv): SessionPathsResult | null {
+ return sessionPathsFor(spec.target, env);
+ },
+
verify(env: InstallEnv): VerifyResult {
const path = spec.resolveConfigPath(env);
const stored = readManifest(env.vault).installs[spec.target];
@@ -434,7 +476,7 @@ export function createJsonMcpAdapter(spec: JsonMcpAdapterSpec): InstallAdapter {
fix_hint: spec.fixHintForDrift ?? `o2b install --target ${spec.target} --apply`,
};
}
- const expected = identifyPayload(spec, expectedPayloadFromEnv(env));
+ const expected = expectedPayloadForSpec(spec, env);
const equals = resolveEntryEquals(spec);
if (
!equals(block[OSB_KEY_FULL] as Record<string, unknown> | undefined, expected.full) ||
@@ -447,24 +489,37 @@ export function createJsonMcpAdapter(spec: JsonMcpAdapterSpec): InstallAdapter {
fix_hint: spec.fixHintForDrift ?? `o2b install --target ${spec.target} --apply`,
};
}
- // The `ok` below is a CONFIGURATION comparison and nothing more, and
- // it now says so. This is where an optional `probeMcp(env)` seam used
- // to sit: declared on the spec, called here, and implemented by zero
- // adapters in the tree, so every JSON-MCP runtime reported `ok` on the
- // strength of two matching JSON keys while the branch that could have
- // said otherwise was unreachable. The seam is deleted rather than
- // implemented because implementing it here would mean this process
- // spawning each runtime's MCP server to speak a handshake to itself,
- // which proves that WE can run `o2b`, not that Cursor or Gemini CLI
- // loaded the entry - and no caller wanted that answer today. Liveness
- // stays reachable where a runtime genuinely exposes it: `copilot-cli`
- // asks `copilot mcp list` and returns `mcp-unreachable` from a real
- // failure. An operator reading this verdict is owed the distinction,
- // so the detail carries it instead of a bare "both OSB keys present".
+ // The config matches. What that is EVIDENCE of depends on the host,
+ // and the fact table is what decides: a target whose `RUNTIME_FACTS`
+ // row declares a `hostProbe` gets asked, and the answer - or the
+ // named reason there is none - replaces the blanket note. Nothing in
+ // this body spawns a runtime's own MCP server to speak a handshake
+ // to itself: that would prove WE can run `o2b`, not that Cursor
+ // loaded the entry. It asks the host's own CLI what it has
+ // registered, which is the only question a host can answer about
+ // itself, and no row in this body's population declares one today -
+ // so they keep the blanket note, and keep it honestly.
+ const probe = probeHost(spec.target, env);
+ if (probeRefutes(probe)) {
+ // The file was just compared and matches, so the shared rule reads
+ // this as a host that has not reloaded it - never as a lost
+ // registration.
+ const verdict = probeRefutedVerdict({
+ target: spec.target,
+ label: spec.label,
+ artifactMatches: true,
+ });
+ return {
+ target: spec.target,
+ status: verdict.status,
+ details: [`${path}: matches the canonical payload, but ${handshakeNote(probe)}`],
+ fix_hint: verdict.fixHint,
+ };
+ }
return {
target: spec.target,
status: "ok",
- details: [`${path}: both OSB keys match the canonical payload (${NO_HANDSHAKE_NOTE})`],
+ details: [`${path}: both OSB keys match the canonical payload (${handshakeNote(probe)})`],
fix_hint: null,
};
},
diff --git a/src/core/install/adapters/aider.ts b/src/core/install/adapters/aider.ts
index 55d9c666..9c6d3cff 100644
--- a/src/core/install/adapters/aider.ts
+++ b/src/core/install/adapters/aider.ts
@@ -43,7 +43,9 @@ import {
type McpPayload,
type UninstallResult,
type VerifyResult,
+ type SessionPathsResult,
} from "../types.ts";
+import { sessionPathsFor } from "../session-paths.ts";
import { defaultRegistry } from "../registry.ts";
// The sidecar snapshot logic is shared with the live session-bracketing
// wrapper (E1) so the static and wrapped paths render byte-identical sidecars.
@@ -305,6 +307,14 @@ export const aiderAdapter: InstallAdapter = {
fix_hint: null,
};
},
+
+ /**
+ * Where this runtime keeps session logs, from the one declaration.
+ * `aider is wired through a managed YAML block and a sidecar context file and writes no transcript store, so the declaration is empty and the answer is null.`
+ */
+ sessionPaths(env: InstallEnv): SessionPathsResult | null {
+ return sessionPathsFor(TARGET, env);
+ },
};
defaultRegistry.register(aiderAdapter);
diff --git a/src/core/install/adapters/all.ts b/src/core/install/adapters/all.ts
index 391b3784..2f7ae427 100644
--- a/src/core/install/adapters/all.ts
+++ b/src/core/install/adapters/all.ts
@@ -13,6 +13,7 @@
import { defaultRegistry } from "../registry.ts";
import "./aider.ts";
+import "./codex.ts";
import "./copilot-cli.ts";
import "./cursor.ts";
import "./gemini-cli.ts";
diff --git a/src/core/install/adapters/codex.ts b/src/core/install/adapters/codex.ts
new file mode 100644
index 00000000..eb50d581
--- /dev/null
+++ b/src/core/install/adapters/codex.ts
@@ -0,0 +1,580 @@
+/**
+ * Codex CLI adapter β€” subprocess-driven, with a TOML section merge into
+ * `$CODEX_HOME/config.toml` when the `codex` binary is absent.
+ *
+ * Primary path:
+ * - `codex mcp remove <name>` (best-effort; non-zero is fine when the
+ * server was not registered)
+ * - `codex mcp add <name> [--env K=V ...] -- <command> <args...>`
+ *
+ * Fallback path:
+ * - upsert the two `[mcp_servers.<name>]` tables into
+ * `$CODEX_HOME/config.toml`, which is where `codex mcp add` persists
+ * them anyway. Every unrelated table - `[plugins."..."]`,
+ * `[marketplaces....]`, a foreign `[mcp_servers.*]` - survives
+ * byte-for-byte.
+ *
+ * ## Why `verify` asks two different questions of one file
+ *
+ * Unlike `copilot-cli`, whose subprocess mode leaves NO artifact, both
+ * Codex paths end in the same `config.toml`. What differs is who wrote
+ * the bytes:
+ *
+ * - **fallback mode**: this build serialised the tables, so `verify`
+ * compares them against the payload it would write today. Any edit
+ * is drift.
+ * - **subprocess mode**: the Codex CLI serialised them in its own
+ * layout, which this build has no published grammar for and must not
+ * guess at. `verify` therefore checks that the two tables are still
+ * DECLARED and lets `codex mcp list` answer whether the host is
+ * actually serving them. That is a presence check, not a byte check,
+ * and the detail line says so rather than implying more.
+ *
+ * ## The Codex home is injected, never ambient
+ *
+ * `CODEX_HOME` relocates the whole Codex configuration directory, and the
+ * Codex CLI REFUSES to start when it points at a path that does not
+ * exist. The runner seam therefore takes the resolved home as its first
+ * argument and the default runner creates it before spawning: an adapter
+ * that resolved `InstallEnv.home` for its own file writes while its
+ * subprocess wrote the ambient `~/.codex` would install into two places
+ * at once - and would mutate the operator's real machine from a test.
+ *
+ * Two seams, for the reason `copilot-cli.ts` states: `CodexRunner` owns
+ * the commands that CHANGE this host, while `../host-probe.ts` owns the
+ * read-only question "what does this host say it has registered",
+ * declared once in `RUNTIME_FACTS[codex].hostProbe`. BOTH seams take the
+ * injected home - the probe through `hostProbeEnvironment(env)` - so the
+ * file half and the handshake half of a `verify` describe one machine.
+ * They described two for a release: the file half read the relocated
+ * `CODEX_HOME` while `codex mcp list` answered about the operator's real
+ * `~/.codex`.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { atomicWriteFileSync } from "../../fs-atomic.ts";
+import { codexHome as resolveCodexHome, INSTALL_TARGET_ID } from "../../runtime/host-facts.ts";
+import { hasMcpServers, removeMcpServers, upsertMcpServers } from "../grok-config.ts";
+import type { GrokMcpEntry } from "../grok-config.ts";
+import {
+ handshakeNote,
+ probeHost,
+ probeRefutedVerdict,
+ probeRefutes,
+ HOST_PROBE_RESULT,
+} from "../host-probe.ts";
+import { payloadWithRuntimeIdentity } from "../identity.ts";
+import { OSB_KEY_FULL, OSB_KEY_WRITER } from "../json-merge.ts";
+import { readManifest, recordEntry, removeEntry } from "../manifest.ts";
+import { expectedPayloadFromEnv } from "../payload-equals.ts";
+import { payloadForHost } from "../payload-host.ts";
+import { defaultRegistry } from "../registry.ts";
+import {
+ InstallError,
+ type ApplyOpts,
+ type ApplyResult,
+ type DetectResult,
+ type InstallAdapter,
+ type InstallEnv,
+ type InstallPlan,
+ type ManifestEntry,
+ type McpPayload,
+ type McpServerEntry,
+ type UninstallResult,
+ type VerifyResult,
+ type SessionPathsResult,
+} from "../types.ts";
+import { sessionPathsFor } from "../session-paths.ts";
+
+const TARGET = INSTALL_TARGET_ID.codex;
+const LABEL = "Codex CLI";
+const FIX_HINT = `o2b install --target ${TARGET} --apply`;
+const SERVER_NAMES: ReadonlyArray<string> = Object.freeze([OSB_KEY_FULL, OSB_KEY_WRITER]);
+
+/**
+ * Codex's vendor token, combined with the operator's host segment into a
+ * host-qualified identity by `../identity.ts` - so a Brain write made
+ * through Codex says `codex-<host>-agent` instead of masquerading as the
+ * operator's own name, exactly as grok and opencode already do.
+ */
+export const CODEX_RUNTIME_ID = TARGET;
+
+// ---------- Injectable subprocess runner ----------
+
+export interface CodexRunResult {
+ readonly exitCode: number;
+ readonly stdout: string;
+ readonly stderr: string;
+}
+
+export interface CodexRunner {
+ available(): boolean;
+ /** `codex <args>` with `CODEX_HOME` set to `home`, which must exist. */
+ run(home: string, args: ReadonlyArray<string>): CodexRunResult;
+}
+
+const defaultRunner: CodexRunner = {
+ available(): boolean {
+ try {
+ return Bun.which("codex") !== null;
+ } catch {
+ return false;
+ }
+ },
+ run(home, args) {
+ // Codex refuses to load a configuration whose `CODEX_HOME` does not
+ // exist, so the directory is created before the spawn rather than
+ // letting the operator read that refusal as an OSB failure.
+ if (!existsSync(home)) mkdirSync(home, { recursive: true });
+ const r = Bun.spawnSync({
+ cmd: ["codex", ...args],
+ env: { ...process.env, CODEX_HOME: home },
+ stdout: "pipe",
+ stderr: "pipe",
+ });
+ return {
+ exitCode: r.exitCode ?? 1,
+ stdout: r.stdout?.toString() ?? "",
+ stderr: r.stderr?.toString() ?? "",
+ };
+ },
+};
+
+let activeRunner: CodexRunner = defaultRunner;
+
+export function setCodexRunner(runner: CodexRunner): void {
+ activeRunner = runner;
+}
+
+export function resetCodexRunner(): void {
+ activeRunner = defaultRunner;
+}
+
+// ---------- Paths and payload ----------
+
+/**
+ * The Codex configuration directory this install is about.
+ *
+ * Delegated to `../../runtime/host-facts.ts` rather than re-derived: that
+ * module already resolves the same `$CODEX_HOME`-or-`~/.codex` rule for
+ * the session roots, and two copies of a relocation rule is two answers
+ * waiting to disagree.
+ */
+function codexHome(env: InstallEnv): string {
+ return resolveCodexHome({ home: env.home, env: env.env });
+}
+
+function configPath(env: InstallEnv): string {
+ return join(codexHome(env), "config.toml");
+}
+
+function readFileOrEmpty(path: string): string {
+ try {
+ return readFileSync(path, "utf8");
+ } catch {
+ return "";
+ }
+}
+
+/** The payload as this host must receive it: host dimensions, then identity. */
+function codexPayload(raw: McpPayload, env: InstallEnv): McpPayload {
+ return payloadWithRuntimeIdentity(payloadForHost(TARGET, raw, env), CODEX_RUNTIME_ID);
+}
+
+/** The same payload rebuilt from the env alone, for the verify path. */
+function expectedPayload(env: InstallEnv): McpPayload {
+ return payloadWithRuntimeIdentity(expectedPayloadFromEnv(env, TARGET), CODEX_RUNTIME_ID);
+}
+
+/**
+ * The two tables to write, in the shape `../grok-config.ts` serialises.
+ *
+ * That module is reused rather than re-implemented: Codex and grok name
+ * the same `[mcp_servers.<name>]` table with the same `command` /
+ * `args` / `env` value shapes, and a second line-section TOML editor in
+ * this tree would be one more place for the byte-for-byte preservation
+ * guarantee to be got wrong.
+ */
+function tomlEntry(entry: McpServerEntry): GrokMcpEntry {
+ return {
+ command: entry.command,
+ args: [...entry.args],
+ ...(entry.env ? { env: { ...entry.env } } : {}),
+ };
+}
+
+function codexMcpServers(payload: McpPayload): Record<string, GrokMcpEntry> {
+ return {
+ [OSB_KEY_FULL]: tomlEntry(payload.full),
+ [OSB_KEY_WRITER]: tomlEntry(payload.writer),
+ };
+}
+
+/**
+ * Whether `toml` DECLARES the `[mcp_servers.<name>]` table.
+ *
+ * Anchored to a whole line, and that is the point. A substring search
+ * matches `# [mcp_servers.open-second-brain]` as readily as the table
+ * itself, so an operator who commented both tables out - the ordinary way
+ * to turn a server off - got `detect: installed` and `verify: ok` for a
+ * registration Codex would not load. A commented header is the operator
+ * saying no, and a reader that cannot tell it from a yes is reporting on a
+ * file it did not understand.
+ *
+ * Leading whitespace is tolerated because TOML permits an indented table
+ * header; anything else on the line - a `#`, a second table, trailing
+ * prose - means this is not that header.
+ */
+function declaresTable(toml: string, name: string): boolean {
+ const header = `[mcp_servers.${name}]`;
+ return toml.split("\n").some((line) => line.trim() === header);
+}
+
+/** Whether both of our tables are declared at all, whoever wrote them. */
+function declaresBothServers(toml: string): boolean {
+ return SERVER_NAMES.every((name) => declaresTable(toml, name));
+}
+
+function declaredServers(toml: string): ReadonlyArray<string> {
+ return SERVER_NAMES.filter((name) => declaresTable(toml, name));
+}
+
+/** The clause naming which of the two tables the file is missing. */
+function undeclared(toml: string): string {
+ const missing = SERVER_NAMES.filter((name) => !declaresTable(toml, name));
+ return `does not declare ${missing.join(", ")}`;
+}
+
+// ---------- Apply helpers ----------
+
+/** `codex mcp add <name> [--env K=V ...] -- <command> <args...>`. */
+function addArgs(name: string, entry: McpServerEntry): string[] {
+ const args = ["mcp", "add", name];
+ for (const [key, value] of Object.entries(entry.env ?? {})) args.push("--env", `${key}=${value}`);
+ args.push("--", entry.command, ...entry.args);
+ return args;
+}
+
+function applyViaCli(
+ env: InstallEnv,
+ payload: McpPayload,
+ stderr: NodeJS.WriteStream | NodeJS.WritableStream,
+): boolean {
+ const base = codexHome(env);
+ for (const name of SERVER_NAMES) activeRunner.run(base, ["mcp", "remove", name]);
+ for (const [name, entry] of [
+ [OSB_KEY_FULL, payload.full],
+ [OSB_KEY_WRITER, payload.writer],
+ ] as const) {
+ const result = activeRunner.run(base, addArgs(name, entry));
+ if (result.exitCode !== 0) {
+ stderr.write(
+ `codex mcp add failed for ${name} (exit ${result.exitCode}): ${result.stderr.trim()}\n`,
+ );
+ return false;
+ }
+ }
+ return true;
+}
+
+function applyViaFile(
+ env: InstallEnv,
+ payload: McpPayload,
+ stderr: NodeJS.WriteStream | NodeJS.WritableStream,
+ dryRun: boolean,
+): void {
+ const path = configPath(env);
+ const next = upsertMcpServers(readFileOrEmpty(path), codexMcpServers(payload));
+ if (!dryRun) {
+ const dir = dirname(path);
+ if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+ atomicWriteFileSync(path, next);
+ }
+ stderr.write(`codex: wrote the MCP servers to ${path} (file-fallback mode)\n`);
+}
+
+/**
+ * Strip our two tables, leaving every other section untouched. Returns
+ * whether the file carried any of them.
+ */
+function stripOurTables(env: InstallEnv, dryRun: boolean): boolean {
+ const path = configPath(env);
+ const current = readFileOrEmpty(path);
+ if (declaredServers(current).length === 0) return false;
+ const next = removeMcpServers(current, SERVER_NAMES).replace(/\s*$/, "");
+ if (!dryRun) atomicWriteFileSync(path, next.length > 0 ? `${next}\n` : "");
+ return true;
+}
+
+// ---------- Adapter ----------
+
+export const codexAdapter: InstallAdapter = {
+ target: TARGET,
+ label: LABEL,
+
+ detect(env: InstallEnv): DetectResult {
+ const path = configPath(env);
+ const declared = declaredServers(readFileOrEmpty(path));
+ const cliNote = activeRunner.available()
+ ? "codex CLI present; registration goes through `codex mcp add`"
+ : "codex CLI not on PATH; registration goes through the config.toml merge";
+ if (declared.length === SERVER_NAMES.length) {
+ return { target: TARGET, status: "installed", configPath: path, notes: [cliNote] };
+ }
+ if (declared.length > 0) {
+ return {
+ target: TARGET,
+ status: "drift",
+ configPath: path,
+ notes: [cliNote, `only ${declared.join(", ")} is declared`],
+ };
+ }
+ return { target: TARGET, status: "not-installed", configPath: path, notes: [cliNote] };
+ },
+
+ plan(rawPayload: McpPayload, env: InstallEnv): InstallPlan {
+ const path = configPath(env);
+ // The preview prints the args that will actually be registered, for
+ // the reason `_json-mcp.ts` prints them: a plan whose command line
+ // differs from the applied one is a plan the operator cannot use to
+ // review the change - and the host dimensions this transform adds
+ // (`--tool-profile`, `--host-target`) are exactly what a reviewer of
+ // a capped host is looking for.
+ const payload = codexPayload(rawPayload, env);
+ if (activeRunner.available()) {
+ const commands = [
+ ...SERVER_NAMES.map((name) => `codex mcp remove ${name}`),
+ ...(
+ [
+ [OSB_KEY_FULL, payload.full],
+ [OSB_KEY_WRITER, payload.writer],
+ ] as const
+ ).map(([name, entry]) => `codex ${addArgs(name, entry).join(" ")}`),
+ ];
+ return {
+ target: TARGET,
+ steps: [
+ {
+ kind: "subprocess",
+ // Named even though the CLI writes it: this is where the
+ // registration lands, and an operator reading a plan is owed
+ // the file it will change.
+ path,
+ preview: `${commands.join("; ")} (persisted to ${path})`,
+ },
+ ],
+ postNotes: [`codex CLI present; CODEX_HOME resolves to ${codexHome(env)}`],
+ };
+ }
+ const tables = Object.entries(codexMcpServers(payload)).map(
+ ([name, entry]) => `[mcp_servers.${name}] β†’ ${entry.command} ${entry.args.join(" ")}`,
+ );
+ return {
+ target: TARGET,
+ steps: [
+ {
+ kind: "managed-block",
+ path,
+ preview:
+ `codex CLI not on PATH; merge the two [mcp_servers.*] tables into ${path}: ` +
+ tables.join("; "),
+ },
+ ],
+ postNotes: [
+ "the codex CLI was not detected; using the config.toml merge, which is the same file " +
+ "`codex mcp add` would have written",
+ "codex loads the MCP servers on its next session start",
+ ],
+ };
+ },
+
+ apply(_plan: InstallPlan, rawPayload: McpPayload, env: InstallEnv, opts: ApplyOpts): ApplyResult {
+ const payload = codexPayload(rawPayload, env);
+ let viaCli: boolean;
+ if (activeRunner.available()) {
+ viaCli = opts.dryRun ? true : applyViaCli(env, payload, opts.stderr);
+ if (!viaCli && !opts.dryRun) applyViaFile(env, payload, opts.stderr, false);
+ } else {
+ viaCli = false;
+ applyViaFile(env, payload, opts.stderr, opts.dryRun);
+ }
+
+ const manifest: ManifestEntry = {
+ target: TARGET,
+ applied_at: env.now.toISOString(),
+ operation: viaCli ? "subprocess" : "managed-block",
+ config_path: configPath(env),
+ owned_keys: [...SERVER_NAMES],
+ ...(viaCli ? {} : { fallback_file: configPath(env) }),
+ };
+ if (!opts.dryRun) recordEntry(env.vault, manifest);
+ return { target: TARGET, manifest, steps_executed: opts.dryRun ? 0 : 1 };
+ },
+
+ uninstall(env: InstallEnv, opts: ApplyOpts & { fromSnippet?: boolean }): UninstallResult {
+ const stored = readManifest(env.vault).installs[TARGET];
+ if (!stored && !opts.fromSnippet) {
+ throw new InstallError(
+ `${TARGET}: no install manifest entry found`,
+ TARGET,
+ "manifest-missing",
+ `o2b uninstall --target ${TARGET} --apply --force-from-snippet`,
+ );
+ }
+ const removed_keys: string[] = [];
+ const removed_paths: string[] = [];
+ const skipped: Array<readonly [string, string]> = [];
+ // A skip is not a failure. "No OSB tables declared" means there was
+ // nothing left to remove, which is a completed uninstall; only a
+ // removal this build attempted and could not carry out may keep the
+ // manifest entry alive. Tracked apart from `skipped` for that reason.
+ let failed = false;
+
+ if (stored?.operation === "subprocess" && activeRunner.available()) {
+ if (opts.dryRun) {
+ // A dry run must not touch the host's registry; report what the
+ // two removals would take out.
+ removed_keys.push(...SERVER_NAMES);
+ } else {
+ for (const name of SERVER_NAMES) {
+ const result = activeRunner.run(codexHome(env), ["mcp", "remove", name]);
+ if (result.exitCode === 0) removed_keys.push(name);
+ else {
+ skipped.push([name, `codex mcp remove exited ${result.exitCode}`]);
+ failed = true;
+ }
+ }
+ }
+ } else if (stripOurTables(env, opts.dryRun)) {
+ // Also the repair path for a subprocess install whose CLI has since
+ // left the machine: the registration is in a file either way. The
+ // file is reported as a touched path, exactly as grok reports its
+ // hooks file - an uninstall that changed a file and named none left
+ // the operator nothing to check.
+ removed_keys.push(...SERVER_NAMES);
+ removed_paths.push(configPath(env));
+ } else {
+ skipped.push([configPath(env), "no OSB tables declared"]);
+ }
+
+ // Dropping the manifest entry after a FAILED removal is what makes the
+ // retry impossible: the next `o2b uninstall` finds no entry, throws
+ // `manifest-missing` and demands `--force-from-snippet` for a server
+ // that is still registered. grok already guards this; codex did not.
+ if (!opts.dryRun && !failed) removeEntry(env.vault, TARGET);
+ return { target: TARGET, removed_keys, removed_paths, skipped };
+ },
+
+ verify(env: InstallEnv): VerifyResult {
+ const stored = readManifest(env.vault).installs[TARGET];
+ if (!stored) {
+ return {
+ target: TARGET,
+ status: "not-installed",
+ details: ["no install manifest entry"],
+ fix_hint: FIX_HINT,
+ };
+ }
+ const path = configPath(env);
+ const toml = readFileOrEmpty(path);
+ const probe = probeHost(TARGET, env);
+ const declaresBoth = declaresBothServers(toml);
+
+ if (stored.operation === "subprocess") {
+ // The Codex CLI owns these bytes, so the host's own answer is the
+ // strongest evidence available and is taken first. That is only
+ // sound because the probe is asked about the SAME home this adapter
+ // resolved - `probeHost` spawns under `hostProbeEnvironment(env)`,
+ // so a relocated `CODEX_HOME` cannot be verified against the
+ // operator's ambient `~/.codex`. The file is consulted only where
+ // that answer is absent or negative - and it is consulted for
+ // PRESENCE, because this build has no published grammar for the
+ // layout the CLI writes and will not guess one.
+ if (probe.kind === HOST_PROBE_RESULT.answered) {
+ if (probe.missing.length === 0) {
+ return { target: TARGET, status: "ok", details: [handshakeNote(probe)], fix_hint: null };
+ }
+ const verdict = probeRefutedVerdict({
+ target: TARGET,
+ label: LABEL,
+ artifactMatches: declaresBoth,
+ });
+ return {
+ target: TARGET,
+ status: verdict.status,
+ details: [
+ declaresBoth
+ ? `${path}: declares both OSB servers, but ${handshakeNote(probe)}`
+ : `${path}: ${undeclared(toml)} (${handshakeNote(probe)})`,
+ ],
+ fix_hint: verdict.fixHint,
+ };
+ }
+ if (!declaresBoth) {
+ return {
+ target: TARGET,
+ status: "drift",
+ details: [`${path}: ${undeclared(toml)} (${handshakeNote(probe)})`],
+ fix_hint: FIX_HINT,
+ };
+ }
+ return {
+ target: TARGET,
+ status: "ok",
+ details: [
+ `${path}: both OSB servers declared, in the layout the codex CLI wrote ` +
+ `(${handshakeNote(probe)})`,
+ ],
+ fix_hint: null,
+ };
+ }
+
+ // File-fallback mode: this build wrote the bytes, so it compares
+ // them. A probe that answers cannot substitute for that - it reports
+ // which names are registered and nothing about the command, the
+ // arguments or the environment behind them.
+ if (!hasMcpServers(toml, codexMcpServers(expectedPayload(env)))) {
+ return {
+ target: TARGET,
+ status: "drift",
+ details: [
+ declaresBoth
+ ? `${path}: the OSB tables differ from the canonical payload`
+ : `${path}: ${undeclared(toml)}`,
+ ],
+ fix_hint: FIX_HINT,
+ };
+ }
+ if (probeRefutes(probe)) {
+ const verdict = probeRefutedVerdict({
+ target: TARGET,
+ label: LABEL,
+ artifactMatches: true,
+ });
+ return {
+ target: TARGET,
+ status: verdict.status,
+ details: [`${path}: matches the canonical payload, but ${handshakeNote(probe)}`],
+ fix_hint: verdict.fixHint,
+ };
+ }
+ return {
+ target: TARGET,
+ status: "ok",
+ details: [`${path}: both OSB tables match the canonical payload (${handshakeNote(probe)})`],
+ fix_hint: null,
+ };
+ },
+
+ /**
+ * Where this runtime keeps session logs, from the one declaration.
+ * `Codex has moved its rollout files between four subdirectories of $CODEX_HOME across releases; all four are declared.`
+ */
+ sessionPaths(env: InstallEnv): SessionPathsResult | null {
+ return sessionPathsFor(TARGET, env);
+ },
+};
+
+defaultRegistry.register(codexAdapter);
diff --git a/src/core/install/adapters/copilot-cli.ts b/src/core/install/adapters/copilot-cli.ts
index 56ef93cc..ef222ce8 100644
--- a/src/core/install/adapters/copilot-cli.ts
+++ b/src/core/install/adapters/copilot-cli.ts
@@ -14,13 +14,32 @@
*
* The subprocess seam is injectable via `setCopilotRunner` so tests
* can drive both branches deterministically.
+ *
+ * Two seams, not one, and the split is deliberate: `CopilotRunner` owns
+ * the commands that CHANGE this host (`mcp add`, `mcp remove`) and the
+ * presence check that decides which path apply takes, while
+ * `src/core/install/host-probe.ts` owns the read-only question "what does
+ * this host say it has registered". The read is declared once, in
+ * `RUNTIME_FACTS[copilot-cli].hostProbe`, so `verify` asks the same
+ * question every other probe-bearing target will be asked, in the same
+ * words - see the note that used to be blanket in `_json-mcp.ts`.
*/
import { existsSync, mkdirSync, readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { atomicWriteFileSync } from "../../fs-atomic.ts";
+import { INSTALL_TARGET_ID } from "../../runtime/host-facts.ts";
+import {
+ handshakeNote,
+ hostProbeEnvironment,
+ HOST_PROBE_RESULT,
+ probeHost,
+ probeRefutedVerdict,
+ probeRefutes,
+} from "../host-probe.ts";
import { mergeMcpServers, removeMcpServers, OSB_KEY_FULL, OSB_KEY_WRITER } from "../json-merge.ts";
+import { payloadForHost } from "../payload-host.ts";
import { expectedPayloadFromEnv, payloadKeyEquals } from "../payload-equals.ts";
import { recordEntry, readManifest, removeEntry } from "../manifest.ts";
import { defaultRegistry } from "../registry.ts";
@@ -37,9 +56,11 @@ import {
type McpServerEntry,
type UninstallResult,
type VerifyResult,
+ type SessionPathsResult,
} from "../types.ts";
+import { sessionPathsFor } from "../session-paths.ts";
-const TARGET = "copilot-cli";
+const TARGET = INSTALL_TARGET_ID.copilotCli;
const LABEL = "GitHub Copilot CLI";
// ---------- Injectable subprocess runner ----------
@@ -50,6 +71,12 @@ export interface CopilotRunResult {
readonly stderr: string;
}
+/**
+ * What `detect` needs from the host: which OSB names it reports, or that
+ * it could not be asked. `verify` does NOT read this - it asks
+ * {@link probeHost} directly, so the reason a probe was skipped survives
+ * into the verdict instead of collapsing into `ok: false`.
+ */
export interface CopilotListResult {
readonly ok: boolean;
readonly names: ReadonlyArray<string>;
@@ -57,8 +84,24 @@ export interface CopilotListResult {
export interface CopilotRunner {
available(): boolean;
- run(args: ReadonlyArray<string>): CopilotRunResult;
- list(): CopilotListResult;
+ /**
+ * `copilot <args>` against the host `env` describes.
+ *
+ * The environment is a parameter for the same reason `list` takes one:
+ * `mcp add` persists into Copilot's own configuration root, and an
+ * `apply` that wrote to the ambient machine while `verify` asked the
+ * injected one would report drift against a registration it had just
+ * made.
+ */
+ run(args: ReadonlyArray<string>, env: InstallEnv): CopilotRunResult;
+ /**
+ * Ask the host named by `env` what it has registered. The environment is
+ * a parameter for the reason the probe seam takes one: Copilot derives
+ * its own `${XDG_CONFIG_HOME:-$HOME/.config}/github-copilot` root, and a
+ * question asked of the ambient process is a question about a different
+ * machine than the one `fallbackPath(env)` writes to.
+ */
+ list(env: InstallEnv): CopilotListResult;
}
const defaultRunner: CopilotRunner = {
@@ -70,25 +113,37 @@ const defaultRunner: CopilotRunner = {
return false;
}
},
- run(args) {
- const r = Bun.spawnSync({ cmd: ["copilot", ...args], stdout: "pipe", stderr: "pipe" });
+ run(args, env) {
+ const r = Bun.spawnSync({
+ cmd: ["copilot", ...args],
+ // The machine `env` describes, plus a PATH. `PATH` is not part of
+ // "which machine's configuration" - it is how the `copilot`
+ // executable was located in the first place, and `available()`
+ // above locates it with the ambient one - so an `InstallEnv` that
+ // carries no PATH must not make the very binary this runner just
+ // confirmed present unspawnable. Everything that decides WHICH
+ // configuration root Copilot writes (`HOME`, `XDG_CONFIG_HOME`)
+ // comes from `env`, so apply and verify address one machine.
+ env: {
+ PATH: process.env["PATH"] ?? "",
+ ...hostProbeEnvironment(env),
+ },
+ stdout: "pipe",
+ stderr: "pipe",
+ });
return {
exitCode: r.exitCode ?? 1,
stdout: r.stdout?.toString() ?? "",
stderr: r.stderr?.toString() ?? "",
};
},
- list(): CopilotListResult {
- const r = Bun.spawnSync({ cmd: ["copilot", "mcp", "list"], stdout: "pipe", stderr: "pipe" });
- if (r.exitCode !== 0) return { ok: false, names: [] };
- const stdout = r.stdout?.toString() ?? "";
- const names = stdout
- .split("\n")
- .map((line) => line.trim())
- .filter((l) => l.length > 0)
- .map((line) => line.split(/\s+/)[0]!)
- .filter((n) => n === OSB_KEY_FULL || n === OSB_KEY_WRITER);
- return { ok: true, names };
+ list(env: InstallEnv): CopilotListResult {
+ // One implementation of "ask copilot what it has registered", shared
+ // with `verify` through the declared `RUNTIME_FACTS` probe rather
+ // than spelled a second time here.
+ const outcome = probeHost(TARGET, env);
+ if (outcome.kind !== HOST_PROBE_RESULT.answered) return { ok: false, names: [] };
+ return { ok: true, names: outcome.registered };
},
};
@@ -130,18 +185,19 @@ interface ApplyOutcome {
}
function applyViaCli(
+ env: InstallEnv,
payload: McpPayload,
stderr: NodeJS.WriteStream | NodeJS.WritableStream,
): { ok: boolean; reason?: string } {
// best-effort remove
for (const name of [OSB_KEY_FULL, OSB_KEY_WRITER]) {
- activeRunner.run(["mcp", "remove", name]);
+ activeRunner.run(["mcp", "remove", name], env);
}
for (const [name, entry] of [
[OSB_KEY_FULL, payload.full],
[OSB_KEY_WRITER, payload.writer],
] as const) {
- const r = activeRunner.run(addArgs(name, entry));
+ const r = activeRunner.run(addArgs(name, entry), env);
if (r.exitCode !== 0) {
stderr.write(`copilot mcp add failed for ${name} (exit ${r.exitCode}): ${r.stderr.trim()}\n`);
return { ok: false, reason: r.stderr.trim() || `exit ${r.exitCode}` };
@@ -167,13 +223,25 @@ function applyViaFile(
return path;
}
-function uninstallViaCli(): { removed: string[] } {
+/**
+ * Remove both servers from the host's own registry.
+ *
+ * `failed` is reported apart from the removed names because the manifest
+ * entry may only be dropped when nothing was left behind - see the guard
+ * in `uninstall`.
+ */
+function uninstallViaCli(env: InstallEnv): {
+ removed: string[];
+ failures: Array<readonly [string, string]>;
+} {
const removed: string[] = [];
+ const failures: Array<readonly [string, string]> = [];
for (const name of [OSB_KEY_FULL, OSB_KEY_WRITER]) {
- const r = activeRunner.run(["mcp", "remove", name]);
+ const r = activeRunner.run(["mcp", "remove", name], env);
if (r.exitCode === 0) removed.push(name);
+ else failures.push([name, `copilot mcp remove exited ${r.exitCode}`]);
}
- return { removed };
+ return { removed, failures };
}
function uninstallViaFile(
@@ -201,7 +269,7 @@ export const copilotCliAdapter: InstallAdapter = {
detect(env: InstallEnv): DetectResult {
const cliAvailable = activeRunner.available();
if (cliAvailable) {
- const lst = activeRunner.list();
+ const lst = activeRunner.list(env);
if (lst.ok) {
const has = (n: string) => lst.names.includes(n);
if (has(OSB_KEY_FULL) && has(OSB_KEY_WRITER)) {
@@ -295,10 +363,13 @@ export const copilotCliAdapter: InstallAdapter = {
};
},
- apply(_plan: InstallPlan, payload: McpPayload, env: InstallEnv, opts: ApplyOpts): ApplyResult {
+ apply(_plan: InstallPlan, rawPayload: McpPayload, env: InstallEnv, opts: ApplyOpts): ApplyResult {
+ // Same transform `verify` re-computes below, so a fresh install
+ // compares against the bytes it just registered.
+ const payload = payloadForHost(TARGET, rawPayload, env);
let outcome: ApplyOutcome;
if (activeRunner.available()) {
- const r = opts.dryRun ? { ok: true } : applyViaCli(payload, opts.stderr);
+ const r = opts.dryRun ? { ok: true } : applyViaCli(env, payload, opts.stderr);
if (r.ok) {
outcome = { viaCli: true, fallbackFile: null };
} else {
@@ -341,6 +412,10 @@ export const copilotCliAdapter: InstallAdapter = {
);
}
+ // A skip is not a failure: an unchanged fallback file means there was
+ // nothing left to remove. Only a removal this build attempted and
+ // could not carry out may keep the manifest entry alive.
+ let failed = false;
const viaCli = stored?.operation === "subprocess";
if (viaCli) {
if (opts.dryRun) {
@@ -348,8 +423,10 @@ export const copilotCliAdapter: InstallAdapter = {
// the two removals so the operator sees what would happen.
removed_keys.push(OSB_KEY_FULL, OSB_KEY_WRITER);
} else {
- const { removed } = uninstallViaCli();
+ const { removed, failures } = uninstallViaCli(env);
for (const r of removed) removed_keys.push(r);
+ for (const f of failures) skipped.push(f);
+ failed = failures.length > 0;
}
} else {
const { path, touched } = uninstallViaFile(
@@ -363,7 +440,11 @@ export const copilotCliAdapter: InstallAdapter = {
skipped.push([path, "fallback file unchanged"]);
}
}
- if (!opts.dryRun) removeEntry(env.vault, TARGET);
+ // Dropping the manifest entry after a FAILED removal makes the retry
+ // impossible: the next `o2b uninstall` finds no entry, throws
+ // `manifest-missing` and demands `--force-from-snippet` for a server
+ // the host still has. grok already guards this; this adapter did not.
+ if (!opts.dryRun && !failed) removeEntry(env.vault, TARGET);
return { target: TARGET, removed_keys, removed_paths, skipped };
},
@@ -377,30 +458,47 @@ export const copilotCliAdapter: InstallAdapter = {
fix_hint: null,
};
}
+ // The host's own answer, or the named reason there is none. Asked
+ // before the branch because BOTH modes are owed it: the subprocess
+ // mode has nothing else to compare, and the file mode has a
+ // comparison that cannot establish the host ever loaded the file.
+ const probe = probeHost(TARGET, env);
if (stored.operation === "subprocess") {
- const lst = activeRunner.list();
- if (!lst.ok) {
+ // In this mode the host CLI IS the registry - there is no file to
+ // fall back on - so a probe that could not run leaves nothing
+ // verified, and says which of the two obstacles it hit.
+ if (probe.kind !== HOST_PROBE_RESULT.answered) {
return {
target: TARGET,
status: "mcp-unreachable",
- details: ["`copilot mcp list` failed"],
- fix_hint: "ensure copilot CLI is on PATH and authenticated",
+ details: [handshakeNote(probe)],
+ fix_hint:
+ "put the copilot CLI on PATH and authenticate it - in subprocess mode it holds the " +
+ "only record of this registration",
};
}
- const has = (n: string) => lst.names.includes(n);
- if (has(OSB_KEY_FULL) && has(OSB_KEY_WRITER)) {
+ if (probe.missing.length === 0) {
return {
target: TARGET,
status: "ok",
- details: ["both OSB names registered with copilot CLI"],
+ details: [handshakeNote(probe)],
fix_hint: null,
};
}
+ // Subprocess mode leaves no artifact, so `artifactMatches` is false
+ // and the shared rule returns DRIFT rather than unreachable: the
+ // host was reached, the host IS the record, and it reported the
+ // registration itself as incomplete. Re-applying is what repairs it.
+ const verdict = probeRefutedVerdict({
+ target: TARGET,
+ label: LABEL,
+ artifactMatches: false,
+ });
return {
target: TARGET,
- status: "drift",
- details: [`missing: ${[OSB_KEY_FULL, OSB_KEY_WRITER].filter((n) => !has(n)).join(", ")}`],
- fix_hint: "o2b install --target copilot-cli --apply",
+ status: verdict.status,
+ details: [handshakeNote(probe)],
+ fix_hint: verdict.fixHint,
};
}
// file-fallback path
@@ -416,7 +514,7 @@ export const copilotCliAdapter: InstallAdapter = {
try {
const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
const block = (parsed["mcpServers"] ?? {}) as Record<string, unknown>;
- const expected = expectedPayloadFromEnv(env);
+ const expected = expectedPayloadFromEnv(env, TARGET);
if (
payloadKeyEquals(
block[OSB_KEY_FULL] as Record<string, unknown> | undefined,
@@ -427,10 +525,26 @@ export const copilotCliAdapter: InstallAdapter = {
expected.writer,
)
) {
+ // The file is right. Whether the host READ it is the probe's
+ // question, and a host that answers and does not list the servers
+ // has not loaded the file the operator just verified.
+ if (probeRefutes(probe)) {
+ const verdict = probeRefutedVerdict({
+ target: TARGET,
+ label: LABEL,
+ artifactMatches: true,
+ });
+ return {
+ target: TARGET,
+ status: verdict.status,
+ details: [`${path}: matches the canonical payload, but ${handshakeNote(probe)}`],
+ fix_hint: verdict.fixHint,
+ };
+ }
return {
target: TARGET,
status: "ok",
- details: [`${path}: both keys present`],
+ details: [`${path}: both keys present (${handshakeNote(probe)})`],
fix_hint: null,
};
}
@@ -457,6 +571,14 @@ export const copilotCliAdapter: InstallAdapter = {
};
}
},
+
+ /**
+ * Where this runtime keeps session logs, from the one declaration.
+ * `GitHub Copilot CLI keeps no transcript store this build can locate, so the declaration is empty and the answer is null.`
+ */
+ sessionPaths(env: InstallEnv): SessionPathsResult | null {
+ return sessionPathsFor(TARGET, env);
+ },
};
defaultRegistry.register(copilotCliAdapter);
diff --git a/src/core/install/adapters/generic.ts b/src/core/install/adapters/generic.ts
index 82ea21b1..b0295191 100644
--- a/src/core/install/adapters/generic.ts
+++ b/src/core/install/adapters/generic.ts
@@ -29,7 +29,9 @@ import type {
McpServerEntry,
UninstallResult,
VerifyResult,
+ SessionPathsResult,
} from "../types.ts";
+import { sessionPathsFor } from "../session-paths.ts";
import { defaultRegistry } from "../registry.ts";
const TARGET = "generic";
@@ -167,6 +169,14 @@ export const genericAdapter: InstallAdapter = {
fix_hint: null,
};
},
+
+ /**
+ * Where this runtime keeps session logs, from the one declaration.
+ * `The generic target prints a payload for a host it was never told the name of, so there is no store to name and the answer is null.`
+ */
+ sessionPaths(env: InstallEnv): SessionPathsResult | null {
+ return sessionPathsFor(TARGET, env);
+ },
};
defaultRegistry.register(genericAdapter);
diff --git a/src/core/install/adapters/grok.ts b/src/core/install/adapters/grok.ts
index 29975189..f80f81e5 100644
--- a/src/core/install/adapters/grok.ts
+++ b/src/core/install/adapters/grok.ts
@@ -22,12 +22,16 @@ import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
import { dirname, join } from "node:path";
import { atomicWriteFileSync } from "../../fs-atomic.ts";
+import { UnsupportedPlatformError } from "../../config.ts";
+import type { InstallTargetId } from "../../runtime/host-facts.ts";
import { GROK_HOOKS_FILENAME, grokHooksJson, grokMcpServers } from "../grok-asset.ts";
import { hasMcpServers, removeMcpServers, upsertMcpServers } from "../grok-config.ts";
import { OSB_KEY_FULL, OSB_KEY_WRITER } from "../json-merge.ts";
import { readManifest, recordEntry, removeEntry } from "../manifest.ts";
+import { payloadForHost } from "../payload-host.ts";
import { expectedPayloadFromEnv } from "../payload-equals.ts";
import { defaultRegistry } from "../registry.ts";
+import { installSettingsSource, resolveInstallHookTimeoutSeconds } from "../settings.ts";
import type {
ApplyOpts,
ApplyResult,
@@ -38,9 +42,11 @@ import type {
McpPayload,
UninstallResult,
VerifyResult,
+ SessionPathsResult,
} from "../types.ts";
+import { sessionPathsFor } from "../session-paths.ts";
-const TARGET = "grok";
+const TARGET: InstallTargetId = "grok";
const LABEL = "Grok Build";
const FIX_HINT = "o2b install --target grok --apply";
const SERVER_NAMES = [OSB_KEY_FULL, OSB_KEY_WRITER] as const;
@@ -73,14 +79,31 @@ interface DesiredState {
readonly currentHooks: string;
}
+/**
+ * The resolved `install.hook_timeout_seconds` for this env.
+ *
+ * Read on BOTH the apply and the verify path, from the same
+ * `InstallEnv`, because verification here is re-construction: a value
+ * only one of the two could see would make a fresh apply report drift.
+ * An unreadable `<vault>/Brain/_brain.yaml` raises out of here rather
+ * than resolving the default - the refusal this generator owes an
+ * operator whose settings exist and are not in force.
+ */
+function hookTimeoutSeconds(env: InstallEnv): number {
+ return resolveInstallHookTimeoutSeconds(installSettingsSource(env)).value;
+}
+
/** Compute the target config.toml + hooks content for the current env/payload. */
-function desired(payload: McpPayload, env: InstallEnv): DesiredState {
+function desired(rawPayload: McpPayload, env: InstallEnv): DesiredState {
const currentToml = readFileOrEmpty(configPath(env));
const currentHooks = readFileOrEmpty(hooksPath(env));
+ // The same host transform `syncState` re-computes from the env alone,
+ // so an applied install is in sync with what verification expects.
+ const payload = payloadForHost(TARGET, rawPayload, env);
return {
currentToml,
nextToml: upsertMcpServers(currentToml, grokMcpServers(payload)),
- hooksContent: grokHooksJson(payload),
+ hooksContent: grokHooksJson(payload, hookTimeoutSeconds(env)),
currentHooks,
};
}
@@ -89,9 +112,9 @@ function desired(payload: McpPayload, env: InstallEnv): DesiredState {
function syncState(env: InstallEnv): { mcpOk: boolean; hooksOk: boolean; anyPresent: boolean } {
const toml = readFileOrEmpty(configPath(env));
const hooks = readFileOrEmpty(hooksPath(env));
- const payload = expectedPayloadFromEnv(env);
+ const payload = expectedPayloadFromEnv(env, TARGET);
const mcpOk = hasMcpServers(toml, grokMcpServers(payload));
- const hooksOk = hooks === grokHooksJson(payload);
+ const hooksOk = hooks === grokHooksJson(payload, hookTimeoutSeconds(env));
const anyMcp = SERVER_NAMES.some((n) => toml.includes(`[mcp_servers.${n}]`));
return { mcpOk, hooksOk, anyPresent: anyMcp || hooks.length > 0 };
}
@@ -100,8 +123,34 @@ export const grokAdapter = {
target: TARGET,
label: LABEL,
+ /**
+ * The status vocabulary has a member for "this machine is not one this
+ * build has a layout for", and `detect` owes it rather than a throw.
+ *
+ * The reachable path to that condition is new: `syncState` resolves the
+ * hook timeout, which resolves the machine-local config path, which
+ * refuses on a platform with no `$HOME/.config` convention and no
+ * operator override. Before this adapter read a setting, `detect` could
+ * not fail that way; after it, an unsupported platform turned a
+ * read-only status query into an exception that also took down
+ * `detectAll`'s other nine targets.
+ */
detect(env: InstallEnv): DetectResult {
- const { mcpOk, hooksOk, anyPresent } = syncState(env);
+ let state: { mcpOk: boolean; hooksOk: boolean; anyPresent: boolean };
+ try {
+ state = syncState(env);
+ } catch (exc) {
+ if (exc instanceof UnsupportedPlatformError) {
+ return {
+ target: TARGET,
+ status: "unsupported-on-this-platform",
+ configPath: null,
+ notes: [exc.message],
+ };
+ }
+ throw exc;
+ }
+ const { mcpOk, hooksOk, anyPresent } = state;
const status = !anyPresent ? "not-installed" : mcpOk && hooksOk ? "installed" : "drift";
return { target: TARGET, status, configPath: configPath(env), notes: [] };
},
@@ -199,6 +248,14 @@ export const grokAdapter = {
if (!opts.dryRun && skipped.length === 0) removeEntry(env.vault, TARGET);
return { target: TARGET, removed_keys: removedKeys, removed_paths: removedPaths, skipped };
},
+
+ /**
+ * Where this runtime keeps session logs, from the one declaration.
+ * `Grok persists one ACP update stream per session under $GROK_HOME/sessions/<encoded-cwd>/<id>/.`
+ */
+ sessionPaths(env: InstallEnv): SessionPathsResult | null {
+ return sessionPathsFor(TARGET, env);
+ },
};
defaultRegistry.register(grokAdapter);
diff --git a/src/core/install/adapters/pi.ts b/src/core/install/adapters/pi.ts
index 906a54b1..549cd33e 100644
--- a/src/core/install/adapters/pi.ts
+++ b/src/core/install/adapters/pi.ts
@@ -41,7 +41,9 @@ import {
type McpPayload,
type UninstallResult,
type VerifyResult,
+ type SessionPathsResult,
} from "../types.ts";
+import { sessionPathsFor } from "../session-paths.ts";
import { recordEntry, readManifest, removeEntry } from "../manifest.ts";
import { defaultRegistry } from "../registry.ts";
@@ -243,6 +245,14 @@ export const piAdapter: InstallAdapter = {
fix_hint: null,
};
},
+
+ /**
+ * Where this runtime keeps session logs, from the one declaration.
+ * `Pi is installed as a skill symlink and keeps no transcript store, so the declaration is empty and the answer is null.`
+ */
+ sessionPaths(env: InstallEnv): SessionPathsResult | null {
+ return sessionPathsFor(TARGET, env);
+ },
};
function buildManifest(env: InstallEnv, target: string): ManifestEntry {
diff --git a/src/core/install/friction.ts b/src/core/install/friction.ts
new file mode 100644
index 00000000..3e3541c0
--- /dev/null
+++ b/src/core/install/friction.ts
@@ -0,0 +1,391 @@
+/**
+ * What each agent host costs this build, one row per capability
+ * dimension.
+ *
+ * The product's claim is "it installs into host X and recall works
+ * there". Nine adapters make that claim and no surface said what the nine
+ * cost differently: which host caps the tool surface, which one can be
+ * asked whether it loaded the entry, which one keeps transcripts this
+ * build can read. A maintainer wanting to know whether a friction is the
+ * HOST's contract problem or OURS had nine adapter files and one fact
+ * table to read and no way to line them up.
+ *
+ * ## Derived, never written
+ *
+ * Every cell below is computed from {@link RUNTIME_FACTS} or from the
+ * live adapter handed in - never from a table maintained here. That is
+ * the whole design constraint: a hand-written comparison is a document
+ * that starts drifting the day a runtime is added, which is exactly the
+ * failure the fact table was introduced to end. The population is the
+ * caller's adapter list, so a runtime registered without a fact row (or
+ * the reverse) fails `tests/core/architecture/host-facts-census.test.ts`
+ * before it can reach this module.
+ *
+ * ## The dimensions this build can honestly answer, and three it cannot
+ *
+ * Carried: the install mechanism (the live plan's own step kinds), the
+ * tool ceiling, the resolved tool profile with its origin, what a
+ * `verify()` on this target is EVIDENCE of, whether session transcripts
+ * are declared, and whether anything in this build parses them.
+ *
+ * Dropped, with the reason, because inventing a column is worse than
+ * admitting there is no source for one:
+ *
+ * - **whether the host takes MCP at all.** Nothing structural answers
+ * it. `InstallStepKind` does not distinguish grok's managed TOML
+ * block (which registers MCP servers) from aider's managed YAML block
+ * (which does not), and the only other candidate is matching English
+ * in a plan preview. The mechanism cell plus the artifact paths in
+ * its detail carry the same information without a claim nothing can
+ * back.
+ * - **whether lifecycle hooks are wired.** One runtime gets them and
+ * the knowledge lives entirely inside `grok-asset.ts`, private to
+ * that adapter. A column read out of one adapter's private constant
+ * is a hand-written table wearing a derivation's clothes.
+ * - **whether runtime identity is stamped.** It is applied to the
+ * payload's `env` at apply time (`payloadWithRuntimeIdentity`), and
+ * no read-only surface an adapter exposes - `detect`, `plan`,
+ * `verify` - carries the env of the entry it would write. Answering
+ * it would mean applying into a scratch home, which a report must not
+ * do.
+ *
+ * Each of the three becomes derivable the moment the adapter contract
+ * grows a member that states it; until then this module says nothing
+ * about them rather than guessing.
+ */
+
+import { hostProbeCommand, NO_HANDSHAKE_NOTE } from "./host-probe.ts";
+import { writtenToolProfile } from "./payload-host.ts";
+import { RUNTIME_FACTS, TOOL_CEILING_KIND, type InstallTargetId } from "../runtime/host-facts.ts";
+import { BrainConfigError } from "../brain/policy/errors.ts";
+import type { InstallAdapter, InstallEnv, McpPayload } from "./types.ts";
+
+/**
+ * The capability dimensions a host is compared on.
+ *
+ * A frozen vocabulary with a membership list and no guard: these ids are
+ * printed and diffed, never parsed from argv or a config file, so there
+ * is no raw boundary for a guard to stand on. A `--dimension` filter
+ * would add one, and would add the guard with it.
+ */
+export const FRICTION_DIMENSION = Object.freeze({
+ mechanism: "install-mechanism",
+ toolCeiling: "tool-ceiling",
+ toolProfile: "tool-profile",
+ verifyEvidence: "verify-evidence",
+ sessionTranscripts: "session-transcripts",
+ sessionParser: "session-parser",
+} as const);
+
+export type FrictionDimension = (typeof FRICTION_DIMENSION)[keyof typeof FRICTION_DIMENSION];
+
+/** The dimensions, in the order every row and every diff prints them. */
+export const FRICTION_DIMENSIONS: ReadonlyArray<FrictionDimension> = Object.freeze([
+ FRICTION_DIMENSION.mechanism,
+ FRICTION_DIMENSION.toolCeiling,
+ FRICTION_DIMENSION.toolProfile,
+ FRICTION_DIMENSION.verifyEvidence,
+ FRICTION_DIMENSION.sessionTranscripts,
+ FRICTION_DIMENSION.sessionParser,
+]);
+
+/** One host's answer on one dimension. */
+export interface FrictionCell {
+ readonly dimension: FrictionDimension;
+ /**
+ * The comparable answer. Short, and the ONLY thing a diff compares:
+ * two hosts whose citations differ but whose answers do not are not
+ * different on that dimension.
+ */
+ readonly value: string;
+ /** Where the answer is published, or why there is none. */
+ readonly detail: string | null;
+}
+
+/** One host, answered on every dimension, in {@link FRICTION_DIMENSIONS} order. */
+export interface FrictionRow {
+ readonly target: InstallTargetId;
+ readonly label: string;
+ readonly cells: ReadonlyArray<FrictionCell>;
+}
+
+export interface FrictionMatrix {
+ readonly dimensions: ReadonlyArray<FrictionDimension>;
+ readonly rows: ReadonlyArray<FrictionRow>;
+}
+
+/** One dimension two hosts answer differently. */
+export interface FrictionDifference {
+ readonly dimension: FrictionDimension;
+ readonly baseValue: string;
+ readonly compareValue: string;
+}
+
+export interface FrictionDiff {
+ readonly base: InstallTargetId;
+ readonly compare: InstallTargetId;
+ readonly differing: ReadonlyArray<FrictionDifference>;
+ /** Dimensions the two answer identically. Counted, never listed. */
+ readonly shared: number;
+}
+
+/**
+ * Everything a row is computed from.
+ *
+ * The adapters arrive as a parameter rather than through
+ * `defaultRegistry`, for the reason `ownership.ts` takes the same
+ * argument: a module that reaches for the global registry cannot be
+ * driven against a registry a test controls, and importing the registry
+ * here would put this module downstream of every adapter.
+ */
+export interface FrictionInput {
+ readonly env: InstallEnv;
+ readonly payload: McpPayload;
+ readonly adapters: ReadonlyArray<InstallAdapter>;
+}
+
+/**
+ * The answer for a cell whose input could not be resolved, naming the
+ * obstacle.
+ *
+ * `--friction` is a REPORT and is documented as one that never exits
+ * non-zero, so a vault whose `_brain.yaml` will not parse must not turn it
+ * into a stack trace - which it did the moment `plan()` began resolving
+ * the tool profile, because `loadInstallBlockSafe` refuses an unreadable
+ * config by design and `runFriction` caught only usage and payload
+ * errors. Reporting the refusal in the cell keeps both properties: the
+ * report stays total, and the refusal is still stated rather than papered
+ * over with a default the operator never chose. Nothing is generated from
+ * this value, which is why a report may hold what a writer must not.
+ */
+function unresolvedCell(dimension: FrictionDimension, exc: BrainConfigError): FrictionCell {
+ return { dimension, value: "unresolved", detail: exc.message };
+}
+
+/** `compute()`, or the named refusal when the vault config will not parse. */
+function orUnresolved(dimension: FrictionDimension, compute: () => FrictionCell): FrictionCell {
+ try {
+ return compute();
+ } catch (exc) {
+ if (exc instanceof BrainConfigError) return unresolvedCell(dimension, exc);
+ throw exc;
+ }
+}
+
+/** The install mechanism, as the live adapter's own plan describes it. */
+function mechanismCell(adapter: InstallAdapter, input: FrictionInput): FrictionCell {
+ const steps = adapter.plan(input.payload, input.env).steps;
+ const kinds = [...new Set(steps.map((step) => step.kind))].toSorted();
+ const paths = [...new Set(steps.map((step) => step.path).filter((p) => p !== null))];
+ return {
+ dimension: FRICTION_DIMENSION.mechanism,
+ value: kinds.join(", "),
+ detail: paths.length === 0 ? null : `writes ${paths.join("; ")}`,
+ };
+}
+
+/** The published per-workspace tool limit, with its citation or its excuse. */
+function ceilingCell(target: InstallTargetId): FrictionCell {
+ const ceiling = RUNTIME_FACTS[target].toolCeiling;
+ switch (ceiling.kind) {
+ case TOOL_CEILING_KIND.declared:
+ return {
+ dimension: FRICTION_DIMENSION.toolCeiling,
+ value: `${ceiling.kind}: ${ceiling.maxTools} tools`,
+ detail: ceiling.source,
+ };
+ case TOOL_CEILING_KIND.unbounded:
+ return {
+ dimension: FRICTION_DIMENSION.toolCeiling,
+ value: ceiling.kind,
+ detail: ceiling.source,
+ };
+ case TOOL_CEILING_KIND.unknown:
+ return {
+ dimension: FRICTION_DIMENSION.toolCeiling,
+ value: ceiling.kind,
+ detail: ceiling.reason,
+ };
+ }
+}
+
+/**
+ * The profile the generated registration will actually carry, asked of the
+ * one function the write path asks - not the fact row's bottom tier, which
+ * is only one of the three and is the one an operator is least likely to
+ * be looking at.
+ *
+ * Three targets carry no profile because they write no MCP command line at
+ * all, and they answer so by name. Resolving the ladder for them anyway
+ * printed `generic tool-profile minimal / resolved from ...` beside a
+ * `--target generic --apply` that emits no `--tool-profile` argument - a
+ * cell contradicting the artifact it claims to describe.
+ */
+function profileCell(target: InstallTargetId, input: FrictionInput): FrictionCell {
+ const resolved = writtenToolProfile(target, input.env);
+ if (resolved === null) {
+ return {
+ dimension: FRICTION_DIMENSION.toolProfile,
+ value: "not carried",
+ detail: "this target writes no MCP command line, so no profile is selected for it",
+ };
+ }
+ return {
+ dimension: FRICTION_DIMENSION.toolProfile,
+ value: resolved.value ?? "none",
+ detail: `resolved from ${resolved.origin}`,
+ };
+}
+
+/** What a `verify()` on this target is evidence OF. The point of the table. */
+function evidenceCell(target: InstallTargetId): FrictionCell {
+ const probe = RUNTIME_FACTS[target].hostProbe;
+ if (probe === null) {
+ return {
+ dimension: FRICTION_DIMENSION.verifyEvidence,
+ value: "configuration comparison only",
+ detail: NO_HANDSHAKE_NOTE,
+ };
+ }
+ return {
+ dimension: FRICTION_DIMENSION.verifyEvidence,
+ value: `host probe: ${hostProbeCommand(probe)}`,
+ detail: probe.answers,
+ };
+}
+
+/**
+ * The transcript roots THIS ADAPTER answers for, resolved against the
+ * injected machine.
+ *
+ * Asked of `adapter.sessionPaths(env)` rather than read out of
+ * `RUNTIME_FACTS` directly, and that is the point: the member shipped
+ * required with ten implementations and no caller anywhere in `src/`,
+ * which is the exact defect - a declaration nothing reads - that this
+ * release exists to remove. These two cells are per target and
+ * adapter-keyed and already hold an `InstallEnv`, so they are the caller
+ * the member was written for. The adapters all delegate to
+ * `sessionPathsFor`, so the answer still comes from the one declaration;
+ * what changes is that the seam is now load-bearing and a broken
+ * implementation is visible in a surface an operator reads.
+ *
+ * Declared, not measured: whether the directory exists on this box is a
+ * discovery question, and answering it here would turn a capability table
+ * into a machine report.
+ */
+function transcriptCell(adapter: InstallAdapter, input: FrictionInput): FrictionCell {
+ const answered = adapter.sessionPaths(input.env);
+ if (answered === null || answered.roots.length === 0) {
+ return {
+ dimension: FRICTION_DIMENSION.sessionTranscripts,
+ value: "none declared",
+ detail: null,
+ };
+ }
+ return {
+ dimension: FRICTION_DIMENSION.sessionTranscripts,
+ value: `${answered.roots.length} declared root(s)`,
+ detail: answered.roots.map((root) => `${root.path}/${root.glob} (${root.format})`).join("; "),
+ };
+}
+
+/** Whether anything in this build reads those transcripts. */
+function parserCell(adapter: InstallAdapter, input: FrictionInput): FrictionCell {
+ const answered = adapter.sessionPaths(input.env);
+ const roots = answered === null ? [] : answered.roots;
+ // Each root names its own parser, so a runtime whose stores are split
+ // between a readable and an unreadable format says both rather than
+ // rounding to the row's single answer.
+ const adapters = [...new Set(roots.map((root) => root.adapter).filter((a) => a !== null))];
+ if (adapters.length > 0) {
+ return {
+ dimension: FRICTION_DIMENSION.sessionParser,
+ value: adapters.toSorted().join(", "),
+ detail: null,
+ };
+ }
+ const formats = [...new Set(roots.map((root) => root.format))];
+ return {
+ dimension: FRICTION_DIMENSION.sessionParser,
+ value: "none ships",
+ detail:
+ formats.length === 0
+ ? null
+ : `roots are declared but nothing in this build parses ${formats.join(", ")}`,
+ };
+}
+
+/** One host's row. */
+function rowFor(adapter: InstallAdapter, input: FrictionInput): FrictionRow {
+ const target = adapter.target;
+ return {
+ target,
+ label: adapter.label,
+ cells: [
+ orUnresolved(FRICTION_DIMENSION.mechanism, () => mechanismCell(adapter, input)),
+ ceilingCell(target),
+ orUnresolved(FRICTION_DIMENSION.toolProfile, () => profileCell(target, input)),
+ evidenceCell(target),
+ transcriptCell(adapter, input),
+ parserCell(adapter, input),
+ ],
+ };
+}
+
+/** Every supplied adapter, one row each, in registration order. */
+export function buildFrictionMatrix(input: FrictionInput): FrictionMatrix {
+ return {
+ dimensions: FRICTION_DIMENSIONS,
+ rows: input.adapters.map((adapter) => rowFor(adapter, input)),
+ };
+}
+
+/**
+ * One host's row, refused by name when nothing registered that target.
+ *
+ * The refusal lists the known targets for the same reason the `--target`
+ * validation does: an operator who mistyped a runtime name needs the
+ * spelling, not the news that theirs is wrong.
+ */
+export function frictionRowFor(target: InstallTargetId, input: FrictionInput): FrictionRow {
+ const adapter = input.adapters.find((candidate) => candidate.target === target);
+ if (adapter === undefined) {
+ throw new Error(
+ `unknown install target: ${target}. ` +
+ `Known: ${input.adapters.map((a) => a.target).join(", ")}`,
+ );
+ }
+ return rowFor(adapter, input);
+}
+
+/** The one cell of `row` for `dimension`; rows are total over the set. */
+function cellOf(row: FrictionRow, dimension: FrictionDimension): FrictionCell {
+ const found = row.cells.find((cell) => cell.dimension === dimension);
+ if (found === undefined) {
+ throw new Error(`${row.target} has no ${dimension} cell; the row is not total`);
+ }
+ return found;
+}
+
+/**
+ * What the two hosts answer differently, and how many answers they share.
+ *
+ * The shared dimensions are COUNTED rather than listed: a diff that
+ * reprints everything is a table, and the reader asking for a diff has
+ * already got the table. The count is what stops the silence being read
+ * as "there was nothing else to compare".
+ */
+export function diffFrictionRows(base: FrictionRow, compare: FrictionRow): FrictionDiff {
+ const differing: FrictionDifference[] = [];
+ let shared = 0;
+ for (const dimension of FRICTION_DIMENSIONS) {
+ const baseValue = cellOf(base, dimension).value;
+ const compareValue = cellOf(compare, dimension).value;
+ if (baseValue === compareValue) {
+ shared += 1;
+ continue;
+ }
+ differing.push({ dimension, baseValue, compareValue });
+ }
+ return { base: base.target, compare: compare.target, differing, shared };
+}
diff --git a/src/core/install/grok-asset.ts b/src/core/install/grok-asset.ts
index f5ce00bc..d4fe2d54 100644
--- a/src/core/install/grok-asset.ts
+++ b/src/core/install/grok-asset.ts
@@ -19,6 +19,7 @@
import { join } from "node:path";
+import { INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT } from "../brain/policy/blocks/install.ts";
import { payloadWithRuntimeIdentity, runtimeAgentNameFromPayload } from "./identity.ts";
import { OSB_KEY_FULL, OSB_KEY_WRITER } from "./json-merge.ts";
import type { GrokMcpEntry } from "./grok-config.ts";
@@ -129,8 +130,20 @@ const HOOK_SPEC: ReadonlyArray<{ event: string; groups: ReadonlyArray<HookGroupS
* not the shared operator name. Generated at install time (machine-specific
* paths and identity), so `verify` compares the installed file against this
* exact output.
+ *
+ * `hookTimeoutSeconds` is the resolved `install.hook_timeout_seconds`
+ * (see `./settings.ts`) and is REQUIRED, like every other input to a
+ * generator in this file. It carried a default of
+ * {@link INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT} - the bottom tier of that
+ * same ladder - which made "forgot to resolve it" and "the vault
+ * configures nothing" produce identical bytes, so a future caller that
+ * dropped the argument would silently write the compiled default over the
+ * operator's configured value and no test would notice. A vault that
+ * configures nothing still regenerates byte-identical output, because the
+ * resolver returns that same constant; the difference is that the caller
+ * has to have asked.
*/
-export function grokHooksJson(payload: McpPayload): string {
+export function grokHooksJson(payload: McpPayload, hookTimeoutSeconds: number): string {
const agentName = runtimeAgentNameFromPayload(payload, GROK_RUNTIME_ID);
const hooks: Record<string, unknown[]> = {};
for (const { event, groups } of HOOK_SPEC) {
@@ -140,7 +153,7 @@ export function grokHooksJson(payload: McpPayload): string {
type: "command",
command: hookCommand(name),
env: { VAULT_AGENT_NAME: agentName },
- timeout: 10,
+ timeout: hookTimeoutSeconds,
})),
}));
}
diff --git a/src/core/install/grok-config.ts b/src/core/install/grok-config.ts
index 4b7223be..6ec84f58 100644
--- a/src/core/install/grok-config.ts
+++ b/src/core/install/grok-config.ts
@@ -9,6 +9,10 @@
* PATH). So the grok install target writes the two Open Second Brain servers
* here, with an absolute command.
*
+ * Codex names the same `[mcp_servers.<name>]` table with the same value
+ * shapes, so `./adapters/codex.ts` reuses this editor rather than adding
+ * a second one - a change here changes both hosts.
+ *
* The project ships `dependencies = []`, so rather than pull in a TOML
* library this edits by line-section: it only ever writes/removes the exact
* `[mcp_servers.open-second-brain]` / `[mcp_servers.open-second-brain-writer]`
diff --git a/src/core/install/host-probe.ts b/src/core/install/host-probe.ts
new file mode 100644
index 00000000..b3d65876
--- /dev/null
+++ b/src/core/install/host-probe.ts
@@ -0,0 +1,381 @@
+/**
+ * Asking a host what it has actually registered.
+ *
+ * Every JSON-config adapter's `verify()` ended on one sentence -
+ * {@link NO_HANDSHAKE_NOTE} - because a config comparison is all it did.
+ * That sentence is honest where nothing better is available and a lie of
+ * omission where something is: {@link RUNTIME_FACTS} declares a
+ * `hostProbe` for the runtimes that can be ASKED, and a target that
+ * carries one has no business printing "no handshake attempted" when the
+ * handshake is one keyless subprocess away.
+ *
+ * Three rules this module is written under:
+ *
+ * - **Keyless and free.** The probe asks the host which servers it has
+ * registered. It starts no model turn, needs no API key, and writes
+ * nothing. `RUNTIME_FACTS[t].hostProbe.answers` states, per row, what
+ * a successful run establishes.
+ * - **A skip is named.** The absence of an answer is a member of
+ * {@link HOST_PROBE_RESULT} carrying the reason - the binary is not on
+ * PATH, or it exited non-zero with this stderr - never an assumed
+ * `ok`. A probe that reports success when it could not run is the
+ * misleading default this module exists to remove.
+ * - **The subprocess is injectable.** {@link setHostProbeRunner} is the
+ * seam, exactly as `CopilotRunner` already is for that adapter's
+ * mutation commands, so both branches are drivable in a test on a
+ * machine where the host binary does not exist.
+ * - **The host asked is the host being verified.** The probe takes the
+ * adapter's own {@link InstallEnv} and spawns under
+ * {@link hostProbeEnvironment}, never under the ambient process
+ * environment. `codex.ts` declares "the Codex home is injected, never
+ * ambient" for its mutation runner; a probe that ignored the same
+ * injection would let a relocated `CODEX_HOME` verify `ok` against the
+ * operator's real `~/.codex`, which is a wrong answer wearing a live
+ * host's authority.
+ *
+ * ## Two verdicts for one probe answer
+ *
+ * "The host answered and does not list our servers" is not one condition,
+ * and {@link probeRefutedVerdict} is the one place that splits it:
+ *
+ * - the registration is backed by an ARTIFACT this build wrote and that
+ * artifact still matches the canonical payload. The configuration is
+ * right and the host has not loaded it, so the verdict is
+ * `mcp-unreachable` and the repair is a restart. Re-applying would
+ * rewrite bytes that are already correct and change nothing.
+ * - the host's own registry IS the record - `copilot mcp add` leaves no
+ * file, and a Codex config that does not declare the tables has no
+ * artifact to be right - so the host saying "no" means the
+ * registration is gone. The verdict is `drift` and the repair is
+ * `--apply`.
+ *
+ * Stated here rather than in each adapter because the three probe-bearing
+ * bodies reached the same two verdicts by three separate arguments, and a
+ * rule argued three times is a rule that will be argued differently once.
+ *
+ * LEAF module: `RUNTIME_FACTS`, the install types and the two server-key
+ * constants, and nothing from `./adapters/`.
+ * `src/core/install/adapters/_json-mcp.ts` and `copilot-cli.ts` read it;
+ * importing either back into here would close a cycle
+ * `tests/core/architecture/import-cycles.test.ts` gates.
+ */
+
+import { RUNTIME_FACTS, type HostProbeSpec, type InstallTargetId } from "../runtime/host-facts.ts";
+import { OSB_KEY_FULL, OSB_KEY_WRITER } from "./json-merge.ts";
+import type { InstallEnv, VerifyStatus } from "./types.ts";
+
+/**
+ * Stated on every clean `verify` of a target that declares no probe, so
+ * an `ok` cannot be read as "the runtime answered". One constant, because
+ * the sentence is a property of the whole install surface and every
+ * target that cannot be asked must say it the same way.
+ */
+export const NO_HANDSHAKE_NOTE = "configuration comparison; no MCP handshake attempted";
+
+/** The two server names an Open Second Brain install registers. */
+const OSB_SERVER_KEYS: ReadonlyArray<string> = Object.freeze([OSB_KEY_FULL, OSB_KEY_WRITER]);
+
+/**
+ * What came back when this build asked a host about its registrations.
+ *
+ * `not-declared` is a member rather than an absent value: "this runtime
+ * publishes no way to ask it" is an answer, and it is the one that earns
+ * {@link NO_HANDSHAKE_NOTE}. No guard ships with it - unlike the target
+ * ids, these values never arrive from argv or a config file, so there is
+ * no raw boundary for a guard to stand on.
+ */
+export const HOST_PROBE_RESULT = Object.freeze({
+ answered: "answered",
+ binaryMissing: "binary-missing",
+ probeFailed: "probe-failed",
+ notDeclared: "not-declared",
+} as const);
+
+export type HostProbeResult = (typeof HOST_PROBE_RESULT)[keyof typeof HOST_PROBE_RESULT];
+
+/** The host ran the probe and named its registrations. */
+export interface AnsweredProbe {
+ readonly kind: typeof HOST_PROBE_RESULT.answered;
+ /** `bin` plus `argv`, the way a reader would re-run it. */
+ readonly command: string;
+ /** OSB server names the host reported. */
+ readonly registered: ReadonlyArray<string>;
+ /** OSB server names it did not report. Empty is the clean answer. */
+ readonly missing: ReadonlyArray<string>;
+}
+
+/** The probe could not run, and this is why. */
+export interface SkippedProbe {
+ readonly kind: typeof HOST_PROBE_RESULT.binaryMissing | typeof HOST_PROBE_RESULT.probeFailed;
+ readonly command: string;
+ /** A sentence naming the obstacle; never empty. */
+ readonly reason: string;
+}
+
+/** The runtime publishes nothing to ask. */
+export interface UndeclaredProbe {
+ readonly kind: typeof HOST_PROBE_RESULT.notDeclared;
+}
+
+export type HostProbeOutcome = AnsweredProbe | SkippedProbe | UndeclaredProbe;
+
+/** One probe run, as the seam reports it. */
+export interface HostProbeRunResult {
+ readonly exitCode: number;
+ readonly stdout: string;
+ readonly stderr: string;
+}
+
+/**
+ * The machine the probe is asked ABOUT, as a child process environment.
+ *
+ * `InstallEnv.env` is the environment the adapter writes its artifacts
+ * against, and `InstallEnv.home` is the home those artifacts are resolved
+ * under - which is not necessarily the ambient `HOME`, because every
+ * install surface accepts an injected one. `HOME` is set from it so a host
+ * that derives its own configuration directory (`~/.codex`,
+ * `~/.config/github-copilot`) derives the SAME one the adapter just wrote,
+ * and an explicit `CODEX_HOME` / `XDG_CONFIG_HOME` already in `env.env`
+ * rides through untouched.
+ */
+export type HostProbeEnvironment = Readonly<Record<string, string>>;
+
+export function hostProbeEnvironment(env: InstallEnv): HostProbeEnvironment {
+ return { ...env.env, HOME: env.home };
+}
+
+/**
+ * How long a probe may take before it is a failed probe.
+ *
+ * `o2b install --check` is a synchronous command an operator runs to find
+ * out whether their machine is wired up. A host CLI that blocks on a
+ * network call or an interactive authentication prompt would hang it with
+ * no way out and no message, which is worse than the named skip a refusal
+ * produces - so the wait is bounded and the timeout becomes one more named
+ * reason. Generous enough that a cold process start on a loaded machine
+ * is not reported as a broken host.
+ */
+export const HOST_PROBE_TIMEOUT_MS = 10_000;
+
+/**
+ * The subprocess seam. `available` answers whether the binary resolves on
+ * PATH at all, which is a different failure from a binary that ran and
+ * refused - the two produce different named skips, so they cannot share a
+ * branch. Both take the {@link HostProbeEnvironment} because both questions
+ * are about the injected machine: the PATH that resolves the binary is the
+ * one that machine has.
+ */
+export interface HostProbeRunner {
+ available(bin: string, env: HostProbeEnvironment): boolean;
+ run(bin: string, argv: ReadonlyArray<string>, env: HostProbeEnvironment): HostProbeRunResult;
+}
+
+/**
+ * The real subprocess runner, with its wait bounded by `timeoutMs`.
+ *
+ * A factory rather than a constant so the timeout branch is drivable
+ * against a harmless slow binary in a fraction of a second, instead of
+ * being the one path in this module that ships untested because exercising
+ * it would mean waiting {@link HOST_PROBE_TIMEOUT_MS} for it.
+ */
+export function createHostProbeRunner(timeoutMs: number): HostProbeRunner {
+ return {
+ available(bin: string, env: HostProbeEnvironment): boolean {
+ try {
+ const path = env["PATH"];
+ return (path === undefined ? Bun.which(bin) : Bun.which(bin, { PATH: path })) !== null;
+ } catch {
+ return false;
+ }
+ },
+ run(bin: string, argv: ReadonlyArray<string>, env: HostProbeEnvironment): HostProbeRunResult {
+ try {
+ const r = Bun.spawnSync({
+ cmd: [bin, ...argv],
+ env: { ...env },
+ stdout: "pipe",
+ stderr: "pipe",
+ timeout: timeoutMs,
+ });
+ if (r.signalCode !== null) {
+ // A killed child has no answer to report, and its partial stdout
+ // must not be parsed as one. The signal is named because the
+ // timeout kill and a host that crashed arrive the same way, and
+ // guessing between them would be inventing the reason.
+ return {
+ exitCode: r.exitCode ?? 1,
+ stdout: "",
+ stderr: `killed by ${r.signalCode}; the probe is capped at ${timeoutMs} ms`,
+ };
+ }
+ return {
+ exitCode: r.exitCode ?? 1,
+ stdout: r.stdout?.toString() ?? "",
+ stderr: r.stderr?.toString() ?? "",
+ };
+ } catch (e) {
+ // The shell's own "command not found" code, so the reason a reader
+ // sees is the reason the shell would have printed.
+ return { exitCode: 127, stdout: "", stderr: (e as Error).message };
+ }
+ },
+ };
+}
+
+const defaultRunner: HostProbeRunner = createHostProbeRunner(HOST_PROBE_TIMEOUT_MS);
+
+let activeRunner: HostProbeRunner = defaultRunner;
+
+export function setHostProbeRunner(runner: HostProbeRunner): void {
+ activeRunner = runner;
+}
+
+export function resetHostProbeRunner(): void {
+ activeRunner = defaultRunner;
+}
+
+/** The probe as a reader would re-run it. */
+export function hostProbeCommand(spec: HostProbeSpec): string {
+ return [spec.bin, ...spec.argv].join(" ");
+}
+
+/**
+ * The OSB server names `stdout` reports.
+ *
+ * The first whitespace-delimited token of each line is the name column of
+ * every `mcp list` output this build has seen; anything else on the line
+ * (a state, a transport, a command) is not compared. Only the two names
+ * this tool registers are returned, so a host with fifty other servers
+ * answers the same question as a host with none.
+ *
+ * The HEADER row of a padded table (`Name Command Args …`, which is what
+ * real `codex mcp list` prints - see
+ * `tests/fixtures/install/codex-mcp-list.txt`) therefore contributes the
+ * token `Name`, and that is left in rather than stripped. Stripping it
+ * would mean recognising each host's header, which is a per-host grammar
+ * this build would then have to keep up with; leaving it in is safe by
+ * CONSTRUCTION rather than by luck, because the return value is an
+ * intersection with two fixed names and no host can print a column header
+ * called `open-second-brain`. `tests/core/install/host-probe.test.ts`
+ * drives the real capture and holds that property.
+ */
+function registeredNames(stdout: string): ReadonlyArray<string> {
+ const tokens = new Set(
+ stdout
+ .split("\n")
+ .map((line) => line.trim().split(/\s+/)[0] ?? "")
+ .filter((token) => token.length > 0),
+ );
+ return OSB_SERVER_KEYS.filter((key) => tokens.has(key));
+}
+
+/** The first non-empty line of `text`, trimmed; `""` when there is none. */
+function firstLine(text: string): string {
+ return (
+ text
+ .split("\n")
+ .find((line) => line.trim().length > 0)
+ ?.trim() ?? ""
+ );
+}
+
+/**
+ * Ask `target`'s host what it has registered.
+ *
+ * Total: a target with no declared probe gets {@link UndeclaredProbe}
+ * rather than a thrown error, because "nothing to ask" is the answer the
+ * majority of rows legitimately have.
+ */
+export function probeHost(target: InstallTargetId, env: InstallEnv): HostProbeOutcome {
+ const spec = RUNTIME_FACTS[target].hostProbe;
+ if (spec === null) return { kind: HOST_PROBE_RESULT.notDeclared };
+ const command = hostProbeCommand(spec);
+ const probeEnv = hostProbeEnvironment(env);
+ if (!activeRunner.available(spec.bin, probeEnv)) {
+ return {
+ kind: HOST_PROBE_RESULT.binaryMissing,
+ command,
+ reason: `\`${spec.bin}\` is not on PATH`,
+ };
+ }
+ const run = activeRunner.run(spec.bin, spec.argv, probeEnv);
+ if (run.exitCode !== 0) {
+ const stderr = firstLine(run.stderr);
+ return {
+ kind: HOST_PROBE_RESULT.probeFailed,
+ command,
+ reason:
+ `\`${command}\` exited ${run.exitCode}` +
+ (stderr.length > 0 ? `: ${stderr}` : " with no output"),
+ };
+ }
+ const registered = registeredNames(run.stdout);
+ return {
+ kind: HOST_PROBE_RESULT.answered,
+ command,
+ registered,
+ missing: OSB_SERVER_KEYS.filter((key) => !registered.includes(key)),
+ };
+}
+
+/**
+ * The clause a `verify` detail carries about host confirmation.
+ *
+ * One function so the JSON-config adapter body and the Copilot adapter
+ * cannot word the same four outcomes differently - the drift that let one
+ * of them print a blanket claim while the other asked a real question.
+ */
+export function handshakeNote(outcome: HostProbeOutcome): string {
+ switch (outcome.kind) {
+ case HOST_PROBE_RESULT.answered:
+ return outcome.missing.length === 0
+ ? `\`${outcome.command}\` reports both OSB servers registered`
+ : `\`${outcome.command}\` does not report: ${outcome.missing.join(", ")}`;
+ case HOST_PROBE_RESULT.binaryMissing:
+ case HOST_PROBE_RESULT.probeFailed:
+ return `host probe skipped: ${outcome.reason}`;
+ case HOST_PROBE_RESULT.notDeclared:
+ return NO_HANDSHAKE_NOTE;
+ }
+}
+
+/**
+ * Whether the host CONTRADICTED a configuration that otherwise verified.
+ *
+ * True only for an answer: a probe that could not run refutes nothing,
+ * and demoting a correct install because a binary was absent would be the
+ * same over-claim as the blanket `ok`, pointed the other way.
+ */
+export function probeRefutes(outcome: HostProbeOutcome): boolean {
+ return outcome.kind === HOST_PROBE_RESULT.answered && outcome.missing.length > 0;
+}
+
+/** The verdict a refuting probe earns, and the repair that matches it. */
+export interface ProbeRefutedVerdict {
+ readonly status: VerifyStatus;
+ readonly fixHint: string;
+}
+
+/**
+ * What a refuting probe MEANS, decided once for every probe-bearing
+ * adapter. See "Two verdicts for one probe answer" at the top of this
+ * module for why the same answer earns two different verdicts.
+ *
+ * `artifactMatches` is the caller's own comparison: true when this build
+ * wrote a registration artifact and that artifact still equals the
+ * canonical payload, false when the host's registry is the only record or
+ * when the artifact does not carry the registration at all.
+ */
+export function probeRefutedVerdict(args: {
+ readonly target: InstallTargetId;
+ readonly label: string;
+ readonly artifactMatches: boolean;
+}): ProbeRefutedVerdict {
+ if (args.artifactMatches) {
+ return {
+ status: "mcp-unreachable",
+ fixHint: `restart ${args.label} so it reloads its MCP configuration`,
+ };
+ }
+ return { status: "drift", fixHint: `o2b install --target ${args.target} --apply` };
+}
diff --git a/src/core/install/ownership.ts b/src/core/install/ownership.ts
index 1a23f01b..57cefc79 100644
--- a/src/core/install/ownership.ts
+++ b/src/core/install/ownership.ts
@@ -289,6 +289,22 @@ export const OUT_OF_VAULT_SWEEP_EXCLUSIONS: ReadonlyMap<string, string> = new Ma
"fields the statement prints, and it writes nothing at all - it takes the vault, the " +
"backing verdict and the measurements as parameters and returns text",
],
+ [
+ "src/core/install/settings.ts",
+ "the only out-of-vault path it builds is the machine-local config.yaml already enumerated " +
+ "by the machine_config row, and it builds that path only to READ the third tier of the " +
+ "install-settings ladder. It resolves the location from the adapter's own InstallEnv " +
+ "rather than from process.env so apply and verify reconstruct from the same inputs; it " +
+ "creates no file and removes none",
+ ],
+ [
+ "src/core/install/host-probe.ts",
+ "it builds no path at all: the only home it touches is `InstallEnv.home`, copied into the " +
+ "environment of a read-only `<host> mcp list` subprocess so the host answers about the " +
+ "machine being verified rather than the ambient one. The probe starts no model turn, needs " +
+ "no key, writes nothing, and whatever the host reads under that home belongs to the " +
+ "runtime_config_blocks row the adapters already declare",
+ ],
[
"src/cli/install/install.ts",
"the only out-of-vault path it builds is `InstallEnv.home`, which it hands to the adapters; " +
@@ -349,6 +365,41 @@ export const OUT_OF_VAULT_SWEEP_EXCLUSIONS: ReadonlyMap<string, string> = new Ma
"state under the home directory and reads them. The runtime wrote those files and owns " +
"them; this module creates nothing and deletes nothing there",
],
+ [
+ "src/cli/brain/verbs/export.ts",
+ "the transcript export streams each redacted record to a spool as it is produced rather " +
+ "than building the corpus in memory, and the spool sits beside --out so the finish is a " +
+ "rename on one filesystem; only when the operator named no destination does it fall back " +
+ "to the temp directory, and either way the file is renamed into place or unlinked before " +
+ "the command returns. Nothing durable is left outside the vault",
+ ],
+ [
+ "src/core/state/migrate.ts",
+ "it reads the home directory once, as a REFUSAL: a destination equal to $HOME itself is " +
+ "rejected, because state scattered across a home directory stops being one tree an " +
+ "operator can move, back up or delete as a unit. It never builds a path under the home " +
+ "directory, and every location it does move comes from the declared state-surface " +
+ "inventory, whose rows are enumerated in their own census",
+ ],
+ [
+ "src/core/runtime/host-facts.ts",
+ "it DECLARES where each agent runtime keeps its own session logs, as pure functions of an " +
+ "injected home and environment. The runtimes wrote those files and own them; this module " +
+ "opens nothing, writes nothing, and resolves no path until a caller hands it a machine",
+ ],
+ [
+ "src/core/install/session-paths.ts",
+ "it answers `InstallAdapter.sessionPaths` by resolving the session roots `host-facts.ts` " +
+ "declares against the home and environment already carried on `InstallEnv`. The agent " +
+ "runtimes wrote those logs and own them; this module opens nothing and writes nothing",
+ ],
+ [
+ "src/core/brain/sessions/discover.ts",
+ "it READS the declared session roots of every agent runtime on this machine to hash what it " +
+ "finds. The only thing it writes is the import ledger, which lives inside the vault under " +
+ "the derived store and is enrolled as a row in the state-surface inventory; nothing it " +
+ "creates is left outside the vault",
+ ],
[
"src/core/brain/gates/durability.ts",
"the temp-directory tokens in it are a REFUSAL list: the gate matches a candidate vault path " +
diff --git a/src/core/install/payload-equals.ts b/src/core/install/payload-equals.ts
index 8008faab..f690537e 100644
--- a/src/core/install/payload-equals.ts
+++ b/src/core/install/payload-equals.ts
@@ -1,12 +1,25 @@
import { buildPayload } from "./payload.ts";
+import { payloadForHost } from "./payload-host.ts";
import type { InstallEnv, McpPayload, McpServerEntry } from "./types.ts";
+import type { InstallTargetId } from "../runtime/host-facts.ts";
-export function expectedPayloadFromEnv(env: InstallEnv): McpPayload {
- return buildPayload({
- vault: env.vault,
- agent_name: env.env["VAULT_AGENT_NAME"] ?? null,
- timezone: env.env["VAULT_TIMEZONE"] ?? null,
- });
+/**
+ * The payload `verify()` compares the disk against, rebuilt from the
+ * `InstallEnv` and the adapter's own target - the two things every
+ * adapter has on both the apply and the verify path. Nothing else may
+ * enter it: a dimension only one of the two paths can see would make a
+ * freshly applied install report drift against itself.
+ */
+export function expectedPayloadFromEnv(env: InstallEnv, target: InstallTargetId): McpPayload {
+ return payloadForHost(
+ target,
+ buildPayload({
+ vault: env.vault,
+ agent_name: env.env["VAULT_AGENT_NAME"] ?? null,
+ timezone: env.env["VAULT_TIMEZONE"] ?? null,
+ }),
+ env,
+ );
}
/**
diff --git a/src/core/install/payload-host.ts b/src/core/install/payload-host.ts
new file mode 100644
index 00000000..b1b146b2
--- /dev/null
+++ b/src/core/install/payload-host.ts
@@ -0,0 +1,160 @@
+/**
+ * The host-dependent dimensions of the generated MCP payload.
+ *
+ * {@link buildPayload} is pure and stays that way: same config in, same
+ * two entries out. What it cannot know is WHICH runtime the entries are
+ * about, and two things in the registration depend on exactly that:
+ *
+ * - the tool-surface profile a capped host needs. Cursor sends at
+ * most the first forty tools of every enabled MCP server to the
+ * model; the full surface advertises a hundred and ten, so without
+ * a profile the host drops seventy of them and says nothing.
+ * - the runtime's own id, so the server the payload launches can name
+ * its host in `second_brain_capabilities` instead of reporting a
+ * ceiling it has no way to look up.
+ *
+ * Both are applied HERE rather than inside `buildPayload` because they
+ * are impure - the profile walks the environment, the committed
+ * `<vault>/Brain/_brain.yaml` and the machine-local config before
+ * falling back to the host row - and because the adapters are the only
+ * callers that know a target at all. `install --target generic` prints
+ * a payload for a host it was never told the name of and therefore
+ * never comes through here.
+ *
+ * The rule that constrains the shape: `verify()` reconstructs the
+ * expected payload from {@link InstallEnv} ALONE, never from a stored
+ * hash. Every argument added here is therefore a pure function of the
+ * `InstallEnv` plus the target id the adapter carries in its spec, so
+ * apply and verify compute byte-identical args and a fresh install
+ * reports no drift.
+ */
+
+import { installSettingsSource, resolveInstallToolProfile } from "./settings.ts";
+import type { InstallEnv, McpPayload, McpServerEntry } from "./types.ts";
+import { INSTALL_TARGET_ID, type InstallTargetId } from "../runtime/host-facts.ts";
+import type { ResolvedInstallSetting } from "./settings.ts";
+
+/** Names the runtime the generated entry was written for. */
+export const HOST_TARGET_FLAG = "--host-target";
+/** Names the tool-surface profile the generated entry selects. */
+export const TOOL_PROFILE_FLAG = "--tool-profile";
+
+/**
+ * The targets whose generated registration passes through
+ * {@link payloadForHost}, and therefore carries the host dimensions.
+ *
+ * Three of the ten do not, and it is not an oversight: `generic` prints a
+ * payload for a host it was never told the name of, `aider` is wired
+ * through a managed YAML block and a sidecar context file rather than an
+ * MCP server, and `pi` is a skill symlink. None of the three writes an MCP
+ * command line at all, so there is nothing for `--tool-profile` or
+ * `--host-target` to land on.
+ *
+ * Declared here because this is the module the dimensions live in, and
+ * read by everything that must not claim a dimension a target never
+ * carries: `o2b update`'s payload hash, and `--friction`'s profile cell -
+ * which printed `generic tool-profile minimal` for a registration that
+ * carries no profile flag at all.
+ * `tests/core/install/payload-host.test.ts` holds the declaration against
+ * the artifacts the ten adapters actually write.
+ */
+export const HOST_PAYLOAD_TARGETS: ReadonlySet<InstallTargetId> = Object.freeze(
+ new Set<InstallTargetId>([
+ INSTALL_TARGET_ID.codex,
+ INSTALL_TARGET_ID.copilotCli,
+ INSTALL_TARGET_ID.cursor,
+ INSTALL_TARGET_ID.geminiCli,
+ INSTALL_TARGET_ID.grok,
+ INSTALL_TARGET_ID.kiro,
+ INSTALL_TARGET_ID.opencode,
+ ]),
+);
+
+/** Whether `target`'s generated registration carries the host dimensions. */
+export function carriesHostDimensions(target: InstallTargetId): boolean {
+ return HOST_PAYLOAD_TARGETS.has(target);
+}
+
+/**
+ * The profile `target`'s registration will actually carry, or `null` when
+ * the registration carries no profile at all.
+ *
+ * The two `null`s are different answers and both are honest: a member of
+ * {@link HOST_PAYLOAD_TARGETS} whose ladder resolves to `null` writes a
+ * flag-free MCP command line, while a non-member writes no MCP command
+ * line for a flag to be absent from. Callers that print the answer say
+ * which one they mean.
+ */
+export function writtenToolProfile(
+ target: InstallTargetId,
+ env: InstallEnv,
+): ResolvedInstallSetting<string | null> | null {
+ if (!carriesHostDimensions(target)) return null;
+ return resolveInstallToolProfile(installSettingsSource(env), target);
+}
+
+/**
+ * The canonical payload with this host's dimensions baked in.
+ *
+ * The profile lands on the FULL entry only. The writer entry advertises
+ * five tools on every host in the table, so no ceiling can bind it and
+ * naming a profile there would only be a second place for the two to
+ * disagree. `--host-target` lands on both, because the ceiling question
+ * is about the host and both servers run on it.
+ */
+export function payloadForHost(
+ target: InstallTargetId,
+ payload: McpPayload,
+ env: InstallEnv,
+): McpPayload {
+ const resolved = writtenToolProfile(target, env);
+ if (resolved === null) {
+ // A caller outside {@link HOST_PAYLOAD_TARGETS} is a programming
+ // error, not an operator one: the declaration and the routing would
+ // have silently disagreed, and every surface that reads the
+ // declaration to describe the registration would have described the
+ // wrong one.
+ throw new Error(
+ `payloadForHost: ${target} is not declared in HOST_PAYLOAD_TARGETS; ` +
+ "add it there, or stop routing this target's payload through here",
+ );
+ }
+ const profile = resolved.value;
+ return {
+ full: withArgs(payload.full, [
+ ...(profile === null ? [] : [TOOL_PROFILE_FLAG, profile]),
+ HOST_TARGET_FLAG,
+ target,
+ ]),
+ writer: withArgs(payload.writer, [HOST_TARGET_FLAG, target]),
+ };
+}
+
+/**
+ * The payload `target` will actually be registered with, whether or not
+ * that target carries host dimensions.
+ *
+ * The total function {@link payloadForHost} deliberately is not. It exists
+ * for `o2b update`, which decides whether an installed target needs
+ * re-applying by hashing the payload and comparing it against the stored
+ * `payload_hash`: a hash taken over the CANONICAL payload cannot see the
+ * host dimensions, so an operator whose vault, agent name and timezone
+ * were unchanged got "up-to-date, payload unchanged" while `--check`
+ * reported drift on the same target, and a 110-tool registration stayed
+ * under Cursor's 40-tool ceiling. Hashing what is written closes that,
+ * and hashing the canonical payload for the three targets that write no
+ * MCP command line keeps the hash from claiming dimensions they do not
+ * carry.
+ */
+export function payloadAsWritten(
+ target: InstallTargetId,
+ payload: McpPayload,
+ env: InstallEnv,
+): McpPayload {
+ return carriesHostDimensions(target) ? payloadForHost(target, payload, env) : payload;
+}
+
+/** One entry with `extra` appended; argument order is the byte identity. */
+function withArgs(entry: McpServerEntry, extra: ReadonlyArray<string>): McpServerEntry {
+ return { ...entry, args: [...entry.args, ...extra] };
+}
diff --git a/src/core/install/session-paths.ts b/src/core/install/session-paths.ts
new file mode 100644
index 00000000..72a74bf4
--- /dev/null
+++ b/src/core/install/session-paths.ts
@@ -0,0 +1,41 @@
+/**
+ * The one implementation of `InstallAdapter.sessionPaths`.
+ *
+ * Ten adapters answer the question and none of them knows a path. That is
+ * deliberate: an adapter that spelled its own session roots would be the
+ * fifth place in this tree to know where a runtime keeps its transcripts,
+ * and the whole argument of `src/core/runtime/host-facts.ts` is that there
+ * is exactly one. So every adapter delegates here, and here reads the
+ * declaration.
+ *
+ * Which means the member is not ceremony: it is the seam through which the
+ * install layer - which already holds a resolved `InstallEnv` for the host
+ * being installed into - can be asked about that host's logs without the
+ * caller assembling a {@link HostContext} of its own.
+ */
+
+import { resolveSessionRoots, RUNTIME_FACTS, type InstallTargetId } from "../runtime/host-facts.ts";
+import type { InstallEnv, SessionPathsResult } from "./types.ts";
+
+/**
+ * `target`'s session roots on the host `env` describes, or `null` when
+ * this runtime writes no session logs at all.
+ *
+ * `null` is a stated answer rather than an absence: `generic` prints a
+ * payload for a host it was never told the name of, and `aider` and `pi`
+ * are wired without a transcript store, so there is nothing on disk for a
+ * sweep to find. Reporting an empty root list instead would put three
+ * runtimes into every coverage report with a permanent zero.
+ */
+export function sessionPathsFor(
+ target: InstallTargetId,
+ env: InstallEnv,
+): SessionPathsResult | null {
+ const runtime = RUNTIME_FACTS[target].sessionRuntime;
+ if (runtime === null) return null;
+ return Object.freeze({
+ target,
+ runtime,
+ roots: resolveSessionRoots(target, { home: env.home, env: env.env }),
+ });
+}
diff --git a/src/core/install/settings.ts b/src/core/install/settings.ts
new file mode 100644
index 00000000..6e6e8e5d
--- /dev/null
+++ b/src/core/install/settings.ts
@@ -0,0 +1,231 @@
+/**
+ * Resolution of the settings that parameterise GENERATED install and
+ * hook output, with the layer that produced each one.
+ *
+ * One reason to change: where a generated artifact's inputs may come
+ * from. Three tiers, highest first:
+ *
+ * 1. the `install:` block of `<vault>/Brain/_brain.yaml` - the
+ * COMMITTED vault tier;
+ * 2. the machine-local `config.yaml` key;
+ * 3. the compiled default - which for a per-host setting is the
+ * host's own `RUNTIME_FACTS` row, not one number for every
+ * runtime (see {@link resolveInstallToolProfile}).
+ *
+ * Tier 1 above tier 2 is the whole point and is the reverse of the
+ * ordering a reader would guess. Generated content is verified by
+ * RE-CONSTRUCTION rather than a stored hash, so two machines cloning one
+ * vault must reconstruct the same bytes; letting a stale key in one
+ * operator's `~/.config/open-second-brain/config.yaml` outrank the file
+ * their teammate committed would make each machine report the other's
+ * correct install as drift.
+ *
+ * ## Why there is no environment tier
+ *
+ * There was one, above all three, on the argument that an environment
+ * variable is "a deliberate act at the moment of the run". That argument
+ * is sound for a value a running process consumes and wrong for a value a
+ * writer bakes into a file, and this ladder only ever feeds the second
+ * kind. Verification here is re-construction: `verify()` rebuilds the
+ * expected artifact from the `InstallEnv` and compares. An input that is
+ * present on the apply invocation and absent on the next one therefore
+ * makes a CORRECT install report drift - measured, with
+ * `OPEN_SECOND_BRAIN_MCP_TOOL_PROFILE=minimal o2b install --apply`
+ * followed by a plain `o2b install --check`, which reported drift and
+ * offered a fix that would have silently downgraded the profile the
+ * operator asked for.
+ *
+ * Every remaining tier survives the next invocation: a committed file, a
+ * machine-local file, a compiled constant. That property, not the tier
+ * count, is the rule - a setting that cannot be read back identically
+ * tomorrow cannot parameterise an artifact verified by re-construction.
+ * An operator who wants a non-default profile or hook timeout writes it
+ * into one of the two files, where the next `--check` can still see it.
+ * `OPEN_SECOND_BRAIN_MCP_TOOL_PROFILE` still selects the surface of the
+ * RUNNING server (`src/core/config.ts`), which is exactly the per-process
+ * act it is good for.
+ *
+ * An UNREADABLE `_brain.yaml` refuses. {@link loadInstallBlockSafe}
+ * raises a {@link BrainConfigError} naming the parse failure and the
+ * file, and nothing here catches it: an absent config is a vault with no
+ * settings to contradict, but a malformed one is settings that exist and
+ * are not in force, and a writer cannot infer intent from bytes it could
+ * not parse. With the environment tier gone the refusal is also
+ * UNCONDITIONAL - the vault tier is now read on every resolution, where
+ * before an environment variable short-circuited the ladder above it and
+ * a broken vault config went unnoticed for exactly those runs.
+ */
+
+import { discoverConfig, resolveDefaultConfigPath } from "../config.ts";
+import { loadInstallBlockSafe } from "../brain/policy/load.ts";
+import {
+ BRAIN_INSTALL_DEFAULTS,
+ INSTALL_HOOK_TIMEOUT_SECONDS_MAX,
+ INSTALL_HOOK_TIMEOUT_SECONDS_MIN,
+ INSTALL_TOOL_PROFILE_NAMES,
+} from "../brain/policy/blocks/install.ts";
+import { RUNTIME_FACTS, type InstallTargetId } from "../runtime/host-facts.ts";
+import { CONFIG_ORIGIN, parseInteger, type ConfigOrigin } from "../validate.ts";
+import type { BrainInstallConfig } from "../brain/types.ts";
+import type { InstallEnv } from "./types.ts";
+
+/** Machine-local `config.yaml` key for the generated hook entry timeout. */
+export const INSTALL_HOOK_TIMEOUT_CONFIG_KEY = "install_hook_timeout_seconds";
+
+/**
+ * Machine-local `config.yaml` key for the tool-surface profile. The SAME
+ * key the running MCP server already reads, not a second one: an operator
+ * who pinned a profile for their sessions meant it for the generated
+ * registration too, and two keys would let the advertised surface and the
+ * installed one disagree.
+ */
+export const INSTALL_TOOL_PROFILE_CONFIG_KEY = "mcp_tool_profile";
+
+/**
+ * Everything the four tiers are read from. Every field is derivable from
+ * an {@link InstallEnv} (see {@link installSettingsSource}), which is
+ * what keeps `verify()`'s reconstruction honest: it recomputes the
+ * expected output from `InstallEnv` alone, so a setting it cannot reach
+ * from there would make apply and verify disagree.
+ */
+export interface InstallSettingsSource {
+ /** Vault whose committed `Brain/_brain.yaml` supplies the vault tier. */
+ readonly vault: string;
+ /** The machine-local `config.yaml`. */
+ readonly configPath: string;
+}
+
+/** A resolved install setting and the layer that produced it. */
+export interface ResolvedInstallSetting<T> {
+ readonly value: T;
+ readonly origin: ConfigOrigin;
+}
+
+/**
+ * The source an install adapter resolves from.
+ *
+ * `configPath` is derived from the adapter's own `InstallEnv` rather than
+ * from `process.env` directly, for two reasons. A test that hands the
+ * adapter a temporary home must not silently read the developer's own
+ * configuration - and, more importantly, `o2b install --config <p>` is the
+ * operator naming the file this run is parameterised by. That override
+ * used to be dropped here: `--config` supplied the agent name, the
+ * timezone and the vault while `install_hook_timeout_seconds` and
+ * `mcp_tool_profile` came from `~/.config/open-second-brain/config.yaml`,
+ * so one generated artifact was fed by two different files and `--check`
+ * split the same way. The CLI now publishes its resolved choice as
+ * `OPEN_SECOND_BRAIN_CONFIG` in `InstallEnv.env` (see `buildInstallEnv`),
+ * which is the variable {@link resolveDefaultConfigPath} already consults
+ * first - so there is one override, honoured in one place, and the
+ * `InstallEnv` remains the complete description of the run it claims to be.
+ *
+ * @throws {@link UnsupportedPlatformError} when the operator has named
+ * neither `OPEN_SECOND_BRAIN_CONFIG` nor `XDG_CONFIG_HOME` and the
+ * platform has no `$HOME/.config` convention. Callers that owe a status
+ * rather than a throw - `grokAdapter.detect` - catch it by name.
+ */
+export function installSettingsSource(env: InstallEnv): InstallSettingsSource {
+ return {
+ vault: env.vault,
+ configPath: resolveDefaultConfigPath({
+ platform: process.platform,
+ home: env.home,
+ env: env.env,
+ }),
+ };
+}
+
+/**
+ * The shared three-tier walk. `fromVault` reads the one key out of the
+ * raw block, `parse` turns the string tier into the typed value (naming
+ * the key it came from when it refuses), and `fallback` is the compiled
+ * default.
+ *
+ * The vault tier is consulted FIRST and unconditionally, so the refusal an
+ * unreadable `_brain.yaml` owes is not something another tier can skip
+ * past.
+ */
+function resolveLayered<T>(
+ source: InstallSettingsSource,
+ configKey: string,
+ fromVault: (block: BrainInstallConfig) => T | undefined,
+ parse: (raw: string, field: string) => T,
+ fallback: T,
+): ResolvedInstallSetting<T> {
+ // Raises on an unreadable `_brain.yaml`; absent yields `undefined`.
+ const block = loadInstallBlockSafe(source.vault);
+ const declared = block === undefined ? undefined : fromVault(block);
+ if (declared !== undefined) {
+ return { value: declared, origin: CONFIG_ORIGIN.vaultConfig };
+ }
+
+ const configured = discoverConfig(source.configPath).data[configKey];
+ if (configured !== undefined && configured !== "") {
+ return { value: parse(configured, configKey), origin: CONFIG_ORIGIN.userConfig };
+ }
+ return { value: fallback, origin: CONFIG_ORIGIN.default };
+}
+
+/** Seconds a generated lifecycle hook entry may run, and where that came from. */
+export function resolveInstallHookTimeoutSeconds(
+ source: InstallSettingsSource,
+): ResolvedInstallSetting<number> {
+ return resolveLayered(
+ source,
+ INSTALL_HOOK_TIMEOUT_CONFIG_KEY,
+ (block) => block.hook_timeout_seconds,
+ (raw, field) =>
+ parseInteger(raw, BRAIN_INSTALL_DEFAULTS.hook_timeout_seconds, field, {
+ min: INSTALL_HOOK_TIMEOUT_SECONDS_MIN,
+ max: INSTALL_HOOK_TIMEOUT_SECONDS_MAX,
+ }),
+ BRAIN_INSTALL_DEFAULTS.hook_timeout_seconds,
+ );
+}
+
+/**
+ * The MCP tool-surface profile generated content selects for one host,
+ * and where it came from.
+ *
+ * The bottom tier is the host's own {@link RUNTIME_FACTS} row rather
+ * than a single compiled name, because the question the bottom tier
+ * answers is per host: Cursor caps a workspace at forty tools across
+ * every enabled MCP server, so the profile that fits there is not the
+ * profile that fits a host with no published limit. A row that declares
+ * nothing resolves to `null` - NO profile, which is the flag-free
+ * registration every host got before this existed - and `null` is not
+ * the same answer as `full`: one leaves the surface unnamed, the other
+ * would write a name into the payload of eight hosts that never asked
+ * for one.
+ */
+export function resolveInstallToolProfile(
+ source: InstallSettingsSource,
+ target: InstallTargetId,
+): ResolvedInstallSetting<string | null> {
+ return resolveLayered<string | null>(
+ source,
+ INSTALL_TOOL_PROFILE_CONFIG_KEY,
+ (block) => block.tool_profile,
+ requireToolProfileName,
+ RUNTIME_FACTS[target].toolProfile,
+ );
+}
+
+/**
+ * An unknown profile name from the string tier is a hard refusal, unlike
+ * the RUNNING server's `resolveToolSurface`, which fails open to the
+ * full surface rather than locking an agent out mid-session. The
+ * asymmetry is the reader/writer split: nothing is locked out here, an
+ * artifact is being generated, and generating a registration for a
+ * profile that does not exist would install a surface the operator never
+ * named and only discover it on the next session start.
+ */
+function requireToolProfileName(raw: string, field: string): string {
+ if (!INSTALL_TOOL_PROFILE_NAMES.includes(raw)) {
+ throw new Error(
+ `${field} must name a tool-surface profile ` +
+ `(${INSTALL_TOOL_PROFILE_NAMES.join(", ")}), got '${raw}'`,
+ );
+ }
+ return raw;
+}
diff --git a/src/core/install/types.ts b/src/core/install/types.ts
index e30d0817..5040744c 100644
--- a/src/core/install/types.ts
+++ b/src/core/install/types.ts
@@ -10,6 +10,12 @@
* field semantics.
*/
+import type {
+ InstallTargetId,
+ ResolvedSessionRoot,
+ SessionRuntimeId,
+} from "../runtime/host-facts.ts";
+
// ---------- Constant sets (runtime checkable) ----------
export const ADAPTER_STATUSES = new Set([
@@ -130,21 +136,58 @@ export interface VerifyResult {
readonly fix_hint: string | null;
}
+/**
+ * Where one runtime keeps its session logs on the host `env` describes.
+ *
+ * The `format` this used to carry was a four-member union
+ * (`"claude-jsonl" | "codex-json" | "cursor-sqlite" | "unknown"`) that was
+ * the only occurrence of those literals anywhere in the tree and named
+ * none of the adapters `src/core/brain/sessions/` ships. It could not be
+ * joined to anything, which is what a union with no implementations and
+ * no call sites always turns out to mean. Each root now carries a real
+ * {@link SessionAdapterId} - or `null` beside a NAMED non-session format,
+ * for a store like Cursor's `state.vscdb` that this build can find and
+ * cannot parse.
+ */
export interface SessionPathsResult {
- readonly target: string;
- readonly paths: ReadonlyArray<string>;
- readonly format: "claude-jsonl" | "codex-json" | "cursor-sqlite" | "unknown";
+ readonly target: InstallTargetId;
+ /** Which {@link SESSION_ROOTS} entry these roots are. */
+ readonly runtime: SessionRuntimeId;
+ /** The declared roots, resolved against `env`, in declared order. */
+ readonly roots: ReadonlyArray<ResolvedSessionRoot>;
}
export interface InstallAdapter {
- readonly target: string;
+ /**
+ * Which runtime this adapter installs into.
+ *
+ * A member of the closed {@link InstallTargetId} vocabulary rather than
+ * a bare string: the id is carried through the manifest, the ownership
+ * statement and the `--target` argument, and until this was typed the
+ * only thing standing between a typo and all three was a registry
+ * lookup that misses at the very end of that journey.
+ * `tests/core/architecture/host-facts-census.test.ts` holds the
+ * vocabulary and the registered population equal in both directions.
+ */
+ readonly target: InstallTargetId;
readonly label: string;
detect(env: InstallEnv): DetectResult;
plan(payload: McpPayload, env: InstallEnv): InstallPlan;
apply(plan: InstallPlan, payload: McpPayload, env: InstallEnv, opts: ApplyOpts): ApplyResult;
uninstall(env: InstallEnv, opts: ApplyOpts & { fromSnippet?: boolean }): UninstallResult;
verify(env: InstallEnv): VerifyResult;
- sessionPaths?(env: InstallEnv): SessionPathsResult | null;
+ /**
+ * Where this runtime keeps its session logs, or `null` when it keeps
+ * none.
+ *
+ * REQUIRED, and that is the whole point of it. As an optional member it
+ * had zero implementations and zero call sites for four releases, and
+ * an absent member cannot be told apart from a runtime with nothing to
+ * say. `null` is the stated answer for `generic`, `aider` and `pi`;
+ * every implementation reads {@link SESSION_ROOTS} through
+ * `sessionPathsFor` rather than knowing its own paths.
+ */
+ sessionPaths(env: InstallEnv): SessionPathsResult | null;
}
// ---------- Errors ----------
diff --git a/src/core/install/update.ts b/src/core/install/update.ts
index 10f98dea..5431fab4 100644
--- a/src/core/install/update.ts
+++ b/src/core/install/update.ts
@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
import type { Registry } from "./registry.ts";
import { buildPayload } from "./payload.ts";
+import { payloadAsWritten } from "./payload-host.ts";
import { InstallError } from "./types.ts";
import type {
ApplyOpts,
@@ -89,7 +90,25 @@ export function runUpdate(registry: Registry, env: InstallEnv, opts: UpdateOptio
continue;
}
- const currentHash = computePayloadHash(payload);
+ // Hashed over the payload as this TARGET receives it, not the
+ // canonical one. `buildPayload` answers "what does this vault, agent
+ // name and timezone produce"; the adapter then adds the host
+ // dimensions (`--tool-profile`, `--host-target`) before writing. A
+ // hash of the first is blind to every change in the second, which is
+ // how "up-to-date, payload unchanged" was reported for a target whose
+ // `install.tool_profile` had just changed in `_brain.yaml` and whose
+ // `--check` was simultaneously reporting drift.
+ let currentHash: string;
+ try {
+ currentHash = computePayloadHash(payloadAsWritten(adapter.target, payload, env));
+ } catch (exc) {
+ results.push({
+ target: adapter.target,
+ status: "error",
+ error: `Failed to resolve the payload for ${adapter.target}: ${(exc as Error).message}`,
+ });
+ continue;
+ }
const previous = manifest.installs[adapter.target];
if (previous?.payload_hash === currentHash && !opts.force) {
results.push({ target: adapter.target, status: "up-to-date", reason: "payload unchanged" });
diff --git a/src/core/redactor.ts b/src/core/redactor.ts
index 59e867e2..9de98121 100644
--- a/src/core/redactor.ts
+++ b/src/core/redactor.ts
@@ -5,7 +5,8 @@
* The redactor catches six secret-bearing keys in four assignment
* shapes:
*
- * key=value env-style assignments
+ * key=value env-style assignments, including a
+ * prefixed name (`ANTHROPIC_API_KEY=…`)
* key: value YAML / log lines / single-line `key: token`
* "key": "value" JSON object entries
* Authorization: Bearer <token> HTTP authorization header (special case)
@@ -163,7 +164,28 @@ export function isSecretKeyName(name: unknown): boolean {
}
// `key=value` (env-style): value runs to whitespace or end of line.
-const ENV_RE = new RegExp(`\\b(${KEY_PATTERN})(\\s*=\\s*)([^\\s\\r\\n]+)`, "gi");
+//
+// The key may be the SUFFIX of a longer identifier, and the boundary here
+// has to say so explicitly. `\b` was what stood in this position, and `_`
+// is a word character, so the boundary never fired after one:
+// `export ANTHROPIC_API_KEY=…` and `MY_DB_PASSWORD=…` - the single most
+// common shape a credential takes in a shell line, a `.env` file or an
+// agent transcript - both passed through this pass untouched while the
+// unprefixed `API_KEY=…` was caught. What still came out redacted in the
+// common cases came out that way through the vendor-prefix rule on the
+// VALUE (`sk-…`, `ghp_…`), not through this key-name pass, so a
+// non-vendor secret under a prefixed name left verbatim.
+//
+// `(?<![A-Za-z0-9])` is the replacement: the key may begin at the start of
+// the identifier or immediately after a `_` / `-` separator, which is how
+// a prefixed environment variable is spelled, and nowhere else. It stays
+// deliberately narrow at both ends. `--max-tokens=4096` keeps its value,
+// because `token` there is followed by `s` rather than by the assignment.
+// `MYTOKEN=…` also keeps its value, because `TOKEN` starts mid-identifier
+// with no separator in front of it - the same under-match `\b` already
+// had, left in place rather than widened into every word that happens to
+// end in a secret name.
+const ENV_RE = new RegExp(`(?<![A-Za-z0-9])(${KEY_PATTERN})(\\s*=\\s*)([^\\s\\r\\n]+)`, "gi");
// `key: value` outside of JSON quoting. Excludes the `"key": ...` JSON
// shape and the `Authorization: Bearer X` header (handled below).
@@ -778,6 +800,24 @@ function identifierCarriesSecret(value: string): boolean {
return VENDOR_TOKEN_TEST_RE.test(value);
}
+/**
+ * The FULL detector set applied to one string: a vendor prefix anywhere in
+ * it, or a high-entropy run that is not one of the identifier shapes this
+ * boundary hands through unchanged.
+ *
+ * One predicate rather than two copies, because the two positions that ask
+ * for it - a mapping key name, and an identifier a foreign runtime named -
+ * are asking the same question and must not drift into answering it
+ * differently.
+ */
+function carriesBareCredential(value: string): boolean {
+ if (identifierCarriesSecret(value)) return true;
+ for (const match of value.matchAll(HIGH_ENTROPY_TOKEN_RE)) {
+ if (!isPreservedIdentifier(match[0])) return true;
+ }
+ return false;
+}
+
/**
* Does a mapping KEY carry a credential? The full detector set, because a
* key name is authored vocabulary rather than a generated identity: a
@@ -787,11 +827,33 @@ function identifierCarriesSecret(value: string): boolean {
* position at all.
*/
function keyNameCarriesSecret(name: string): boolean {
- if (identifierCarriesSecret(name)) return true;
- for (const match of name.matchAll(HIGH_ENTROPY_TOKEN_RE)) {
- if (!isPreservedIdentifier(match[0])) return true;
- }
- return false;
+ return carriesBareCredential(name);
+}
+
+/**
+ * Does an identifier VALUE that a FOREIGN runtime named carry a
+ * credential? The full detector set again, and the reason is that
+ * {@link identifierCarriesSecret}'s narrowing does not reach here.
+ *
+ * That narrowing - vendor prefixes only, because "record ids, slugs and
+ * build ids are long mixed runs BY CONSTRUCTION" - is an argument about
+ * identities THIS vault generates, whose construction this code knows.
+ * `session_id` and `turn_id` on a transcript record are neither: they are
+ * a foreign harness's filename and a foreign harness's turn uuid, and
+ * nothing in this build constrains their shape. A bare high-entropy run
+ * in one of them is therefore not "an id by construction", it is an
+ * unexplained secret-shaped string, and treating it as the former let a
+ * transcript named `Xk7Qp2Rm9Wz4Tn6Yb8Vc3Ld5.jsonl` export verbatim under
+ * exit 0 while its vendor-prefixed sibling refused the whole run.
+ *
+ * Opt-in ({@link RedactStructuredOptions.foreignIdentifiers}) rather than
+ * the default, because the narrowing is still correct everywhere the
+ * identifiers ARE vault-authored: turning this on for the preference and
+ * OKF exports would refuse them over their own content addresses and
+ * container ids.
+ */
+function foreignIdentifierCarriesSecret(value: string): boolean {
+ return carriesBareCredential(value);
}
/** Bound on the reported list, so a refusal message stays readable. */
@@ -827,6 +889,23 @@ export interface StructuredRedaction {
readonly secretIdentifiers: ReadonlyArray<string>;
}
+/**
+ * {@link redactStructured}'s options: the raw-scan policy every string leaf
+ * is scanned under, plus the one decision that only exists for a tree.
+ */
+export interface RedactStructuredOptions extends RedactRawOutputOptions {
+ /**
+ * When `true`, an IDENTIFIER value is judged by the full bare-token
+ * detector ({@link foreignIdentifierCarriesSecret}) instead of by vendor
+ * prefixes alone. Off by default, and set only by a boundary whose
+ * identifiers were named OUTSIDE this vault - the transcript corpus,
+ * whose `session_id` is a foreign harness's filename and whose `turn_id`
+ * is its turn uuid. See {@link foreignIdentifierCarriesSecret} for why
+ * the default narrowing is right everywhere else.
+ */
+ readonly foreignIdentifiers?: boolean;
+}
+
/** Walked as data; anything else (Date, Map, class instance) passes through. */
function isPlainContainer(value: object): boolean {
const proto = Object.getPrototypeOf(value) as object | null;
@@ -852,7 +931,7 @@ function isPlainContainer(value: object): boolean {
*/
export function redactStructured(
input: unknown,
- opts: RedactRawOutputOptions = {},
+ opts: RedactStructuredOptions = {},
): StructuredRedaction {
let redacted = false;
let truncated = false;
@@ -875,7 +954,16 @@ export function redactStructured(
}
if (typeof value === "string" && (underIdentifierKey || isPathLikeValue(value))) {
// Checked, never collapsed: see the identifier section above.
- if (identifierCarriesSecret(value)) record(location);
+ //
+ // The wider detector is applied only under an identifier KEY, never
+ // to a leaf that merely looks path-shaped: `foreignIdentifiers` is a
+ // statement about where a NAME came from, and a path-shaped run of
+ // prose carries no such provenance.
+ const secretShaped =
+ opts.foreignIdentifiers === true && underIdentifierKey
+ ? foreignIdentifierCarriesSecret(value)
+ : identifierCarriesSecret(value);
+ if (secretShaped) record(location);
// One exception, and it is not a collapse: a `user:pass@host`
// authority is not part of what an identifier identifies. Stripping
// it leaves the identifier pointing at the same resource, where
diff --git a/src/core/runtime/host-facts.ts b/src/core/runtime/host-facts.ts
new file mode 100644
index 00000000..ba171e24
--- /dev/null
+++ b/src/core/runtime/host-facts.ts
@@ -0,0 +1,687 @@
+/**
+ * One declaration per fact about an agent runtime this build installs into.
+ *
+ * Before this module the same host was described in four places that never
+ * met: the adapter knew its config path, `src/mcp/profiles.ts` knew which
+ * tool surfaces exist, `src/core/brain/sessions/` knew how to parse a
+ * transcript, and `src/core/discipline/transcripts/` knew where the
+ * transcripts were. Nothing joined them, so "which runtime, with which
+ * ceiling, storing sessions where, in a format we can read" had no answer
+ * that was not four greps.
+ *
+ * Three rules the rows are written under:
+ *
+ * - **`unknown` is not `unbounded`.** A host whose per-workspace tool
+ * limit nobody has published gets {@link TOOL_CEILING_KIND.unknown}
+ * and a reason. It never gets a number, and it never gets read as
+ * "no limit" - that collapse is a misleading default one layer above
+ * the fail-open profile selection this substrate exists to inform.
+ * - **A fact carries its citation.** `source` says where a limit is
+ * published; `reason` says why there is no answer. A row nobody can
+ * source does not get written.
+ * - **Nothing here reads the machine.** Roots are pure functions of an
+ * injected {@link HostContext}, exactly as `InstallEnv` already
+ * supplies home and environment, so one row answers for the machine
+ * this process runs on and for one it does not.
+ *
+ * This is a LEAF module: it imports the session-adapter vocabulary and
+ * nothing else. `src/core/install/` reads it; importing anything from
+ * there back into here would close a cycle
+ * `tests/core/architecture/import-cycles.test.ts` gates.
+ */
+
+import { join } from "node:path";
+
+import {
+ SESSION_ADAPTER_ID,
+ SESSION_FILE_EXTENSION,
+ type SessionAdapterId,
+} from "../brain/sessions/types.ts";
+
+// ---------- The target vocabulary ----------
+
+/**
+ * The runtimes `o2b install --target` can name.
+ *
+ * Closed, because it is what a raw argv value is validated against: a
+ * target that arrives as a string is either one of these or a typo, and
+ * {@link isInstallTargetId} is the boundary between the two. Membership
+ * is one adapter registration each - `tests/core/architecture/
+ * host-facts-census.test.ts` derives the live population from the
+ * registry and requires the two sets to be equal in both directions, so
+ * a member here with no adapter fails as loudly as an adapter with no
+ * member.
+ */
+export const INSTALL_TARGET_ID = Object.freeze({
+ aider: "aider",
+ codex: "codex",
+ copilotCli: "copilot-cli",
+ cursor: "cursor",
+ geminiCli: "gemini-cli",
+ generic: "generic",
+ grok: "grok",
+ kiro: "kiro",
+ opencode: "opencode",
+ pi: "pi",
+} as const);
+
+export type InstallTargetId = (typeof INSTALL_TARGET_ID)[keyof typeof INSTALL_TARGET_ID];
+
+/** The installable targets, in registration order. */
+export const INSTALL_TARGET_IDS: ReadonlyArray<InstallTargetId> = Object.freeze([
+ INSTALL_TARGET_ID.aider,
+ INSTALL_TARGET_ID.codex,
+ INSTALL_TARGET_ID.copilotCli,
+ INSTALL_TARGET_ID.cursor,
+ INSTALL_TARGET_ID.geminiCli,
+ INSTALL_TARGET_ID.generic,
+ INSTALL_TARGET_ID.grok,
+ INSTALL_TARGET_ID.kiro,
+ INSTALL_TARGET_ID.opencode,
+ INSTALL_TARGET_ID.pi,
+]);
+
+export function isInstallTargetId(value: unknown): value is InstallTargetId {
+ return typeof value === "string" && (INSTALL_TARGET_IDS as ReadonlyArray<string>).includes(value);
+}
+
+// ---------- The tool ceiling ----------
+
+/**
+ * What this build can say about one host's per-workspace MCP tool limit.
+ *
+ * `unbounded` is the member no row uses today, and it is not speculative
+ * padding: without it, a host that documents "no limit" would have to be
+ * recorded as unchecked, which is the same lie in the other direction.
+ */
+export const TOOL_CEILING_KIND = Object.freeze({
+ declared: "declared",
+ unbounded: "unbounded",
+ unknown: "unknown",
+} as const);
+
+export type ToolCeilingKind = (typeof TOOL_CEILING_KIND)[keyof typeof TOOL_CEILING_KIND];
+
+/** The ceiling kinds, most specific first. */
+export const TOOL_CEILING_KINDS: ReadonlyArray<ToolCeilingKind> = Object.freeze([
+ TOOL_CEILING_KIND.declared,
+ TOOL_CEILING_KIND.unbounded,
+ TOOL_CEILING_KIND.unknown,
+]);
+
+export function isToolCeilingKind(value: unknown): value is ToolCeilingKind {
+ return typeof value === "string" && (TOOL_CEILING_KINDS as ReadonlyArray<string>).includes(value);
+}
+
+/** The host publishes a limit, and this is it. */
+export interface DeclaredToolCeiling {
+ readonly kind: typeof TOOL_CEILING_KIND.declared;
+ /** Tools the host will hand the model. A positive integer. */
+ readonly maxTools: number;
+ /** Where that number is published. */
+ readonly source: string;
+}
+
+/** The host publishes that there is no limit. */
+export interface UnboundedToolCeiling {
+ readonly kind: typeof TOOL_CEILING_KIND.unbounded;
+ /** Where the absence of a limit is published. */
+ readonly source: string;
+}
+
+/** Nobody has established a limit for this host. Never read as a number. */
+export interface UnknownToolCeiling {
+ readonly kind: typeof TOOL_CEILING_KIND.unknown;
+ /** Why there is no answer, specific to this host. */
+ readonly reason: string;
+}
+
+export type ToolCeiling = DeclaredToolCeiling | UnboundedToolCeiling | UnknownToolCeiling;
+
+// ---------- Session roots ----------
+
+/**
+ * The machine a question is being asked about.
+ *
+ * Both fields are supplied by the caller for the same reason `InstallEnv`
+ * supplies them: a root derived from the ambient process is a root only
+ * this process can compute, and the install, doctor and discovery
+ * surfaces all already carry an injected home and environment.
+ */
+export interface HostContext {
+ readonly home: string;
+ readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * The runtimes whose session logs this build can LOCATE.
+ *
+ * Deliberately not {@link InstallTargetId} and deliberately not
+ * {@link SessionAdapterId}, because it is neither set:
+ *
+ * - Claude Code is here and is not an install target. Open Second Brain
+ * reaches it as a plugin rather than through `o2b install --target`,
+ * yet `~/.claude/projects` is the largest transcript store on a
+ * typical machine, and a discovery sweep that skipped it would miss
+ * most of what it exists to find.
+ * - Cursor is here and has no session adapter. Its `state.vscdb` is
+ * locatable and unreadable by anything in `src/core/brain/sessions/`,
+ * which is a coverage answer worth printing rather than a runtime
+ * worth omitting.
+ * - Hermes is a {@link SessionAdapterId} and is NOT here: this build
+ * ships a parser for its format and knows no path at which that
+ * format is written, so a root would be an invention.
+ *
+ * Closed and guarded because the value round-trips through disk: the
+ * import ledger records which runtime each imported log came from, and a
+ * ledger written by another release is a string until the guard says
+ * otherwise.
+ */
+export const SESSION_RUNTIME_ID = Object.freeze({
+ claudeCode: "claude-code",
+ codex: "codex",
+ cursor: "cursor",
+ grok: "grok",
+ opencode: "opencode",
+} as const);
+
+export type SessionRuntimeId = (typeof SESSION_RUNTIME_ID)[keyof typeof SESSION_RUNTIME_ID];
+
+/** The session runtimes, in the order a coverage report prints them. */
+export const SESSION_RUNTIME_IDS: ReadonlyArray<SessionRuntimeId> = Object.freeze([
+ SESSION_RUNTIME_ID.claudeCode,
+ SESSION_RUNTIME_ID.codex,
+ SESSION_RUNTIME_ID.cursor,
+ SESSION_RUNTIME_ID.grok,
+ SESSION_RUNTIME_ID.opencode,
+]);
+
+export function isSessionRuntimeId(value: unknown): value is SessionRuntimeId {
+ return (
+ typeof value === "string" && (SESSION_RUNTIME_IDS as ReadonlyArray<string>).includes(value)
+ );
+}
+
+/** Where one runtime keeps session logs, and what they are. */
+export interface SessionRootSpec {
+ /** Stable slug, unique within its row; the handle a report prints. */
+ readonly id: string;
+ /** Absolute root, derived from the injected home and environment. */
+ resolve(ctx: HostContext): string;
+ /** Which files under the root are session logs, relative to it. */
+ readonly glob: string;
+ /**
+ * The adapter that parses them, or `null` when none ships. `null` is a
+ * stated answer: Cursor's transcripts are readable, just not by
+ * anything in `src/core/brain/sessions/`.
+ */
+ readonly adapter: SessionAdapterId | null;
+ /** The on-disk format, named even where no adapter reads it. */
+ readonly format: string;
+}
+
+/** One {@link SessionRootSpec} against a concrete host. */
+export interface ResolvedSessionRoot {
+ readonly id: string;
+ readonly path: string;
+ readonly glob: string;
+ readonly adapter: SessionAdapterId | null;
+ readonly format: string;
+}
+
+// ---------- Host probes ----------
+
+/**
+ * A command that can be asked about this runtime's own registration.
+ *
+ * Declared rather than performed: what is MEASURED and what is DECLARED
+ * stay separate columns, so a caller that cannot spawn a subprocess
+ * reports a named skip instead of an assumed answer.
+ */
+export interface HostProbeSpec {
+ /** Binary name, resolved on PATH by whoever runs it. */
+ readonly bin: string;
+ /** Argv after the binary. */
+ readonly argv: ReadonlyArray<string>;
+ /** What a successful run establishes. */
+ readonly answers: string;
+}
+
+// ---------- The rows ----------
+
+/** Everything this build knows about one agent runtime. */
+export interface RuntimeFacts {
+ readonly target: InstallTargetId;
+ /** Human-readable name, matching the adapter's own label. */
+ readonly label: string;
+ readonly toolCeiling: ToolCeiling;
+ /**
+ * A `TOOL_SURFACE_PROFILES` key, or `null` where no profile is declared.
+ *
+ * Typed `string` rather than a key type on purpose. This module is a
+ * leaf and `TOOL_SURFACE_PROFILES` lives in `src/mcp/`, so importing it
+ * would risk the cycle the docblock names - and it buys nothing anyway:
+ * that table is annotated `Readonly<Record<string, ToolSurfaceProfile>>`,
+ * so its `keyof` IS `string`. `tests/core/runtime/host-facts.test.ts`
+ * is what holds the reference, by resolving every value against the
+ * real table.
+ */
+ readonly toolProfile: string | null;
+ /** The adapter that parses this runtime's transcripts, or `null`. */
+ readonly sessionAdapter: SessionAdapterId | null;
+ /**
+ * Which {@link SESSION_ROOTS} entry this target's logs are, or `null`
+ * where it writes none.
+ *
+ * Declared rather than derived from the target id. Four of the five
+ * session runtimes happen to spell their id the same as their install
+ * target, and a join built on that coincidence would silently break the
+ * first time one of them did not - the two vocabularies are different
+ * sets on purpose, and Claude Code is already a member of one and not
+ * the other.
+ */
+ readonly sessionRuntime: SessionRuntimeId | null;
+ readonly sessionRoots: ReadonlyArray<SessionRootSpec>;
+ readonly hostProbe: HostProbeSpec | null;
+}
+
+/** `env[key]` when it holds something, else `fallback`. */
+function envOr(ctx: HostContext, key: string, fallback: string): string {
+ const value = ctx.env[key];
+ return value !== undefined && value.length > 0 ? value : fallback;
+}
+
+/** Cursor keeps per-workspace chat state in a SQLite file, not a log. */
+const CURSOR_STATE_FORMAT = "cursor-state-vscdb";
+/** One `state.vscdb` per workspace hash directory under the root. */
+const CURSOR_STATE_GLOB = "*/state.vscdb";
+
+/**
+ * The three layouts Cursor builds have used, already probed by
+ * `src/core/discipline/transcripts/cursor.ts`. Declared here so the two
+ * subsystems stop knowing different halves of one fact.
+ */
+const CURSOR_SESSION_ROOTS: ReadonlyArray<SessionRootSpec> = Object.freeze([
+ Object.freeze({
+ id: "cursor-workspace-storage-linux",
+ resolve: (ctx: HostContext) => join(ctx.home, ".config", "Cursor", "User", "workspaceStorage"),
+ glob: CURSOR_STATE_GLOB,
+ adapter: null,
+ format: CURSOR_STATE_FORMAT,
+ }),
+ Object.freeze({
+ id: "cursor-workspace-storage-macos",
+ resolve: (ctx: HostContext) =>
+ join(ctx.home, "Library", "Application Support", "Cursor", "User", "workspaceStorage"),
+ glob: CURSOR_STATE_GLOB,
+ adapter: null,
+ format: CURSOR_STATE_FORMAT,
+ }),
+ Object.freeze({
+ id: "cursor-workspace-storage-dot-cursor",
+ resolve: (ctx: HostContext) => join(ctx.home, ".cursor", "workspaceStorage"),
+ glob: CURSOR_STATE_GLOB,
+ adapter: null,
+ format: CURSOR_STATE_FORMAT,
+ }),
+]);
+
+/**
+ * The subdirectories of the Codex home that have held session files.
+ *
+ * Not invented here: `src/core/discipline/transcripts/codex.ts` already
+ * walks exactly these four, three levels deep, because the Codex CLI has
+ * moved its transcripts between releases. Declaring the same four keeps
+ * the two subsystems from knowing different halves of one fact.
+ */
+const CODEX_SESSION_SUBDIRS: ReadonlyArray<string> = Object.freeze([
+ "sessions",
+ "session",
+ "history",
+ ".tmp",
+]);
+
+/**
+ * What a Codex transcript file is called, stated with its uncertainty.
+ *
+ * The two consumers disagree and nothing on the machine this row was
+ * written on could settle it: the discipline scanner counts `*.json`,
+ * while `src/core/brain/sessions/codex.ts` parses the `.jsonl` rollout
+ * line schema, and no session directory existed under the Codex home to
+ * measure. The glob used to cover both extensions rather than pick the
+ * one that would silently find nothing - but "find" was the wrong word
+ * for what covering both bought. A `.json` this build enrols is one no
+ * shipped adapter can read, so it is discovered as a GAP, fails
+ * `DETECT_FAIL` on import, and drives `--discover --all` to exit 1; and
+ * `sessionFilesUnder` never accepted it, so `import-session <dir>` and
+ * `export --transcripts <dir>` skipped every one of them in silence.
+ * Three definitions of "what a session log is", of which only
+ * {@link SESSION_FILE_EXTENSION} matched what the adapters parse. The
+ * format label keeps its name: the uncertainty about what Codex writes is
+ * real, and it is this build's READER that is narrow.
+ */
+const CODEX_SESSION_FORMAT = "codex-rollout-json-or-jsonl";
+const CODEX_SESSION_GLOB = `**/*${SESSION_FILE_EXTENSION}`;
+
+/** Codex keeps per-session files under `$CODEX_HOME` (default `~/.codex`). */
+const CODEX_SESSION_ROOTS: ReadonlyArray<SessionRootSpec> = Object.freeze(
+ CODEX_SESSION_SUBDIRS.map((sub) =>
+ Object.freeze({
+ // `.tmp` would give an id starting with a dot; strip it so the
+ // handle a report prints reads as a slug.
+ id: `codex-${sub.replace(/^\./, "")}`,
+ resolve: (ctx: HostContext) => join(codexHome(ctx), sub),
+ glob: CODEX_SESSION_GLOB,
+ adapter: SESSION_ADAPTER_ID.codex,
+ format: CODEX_SESSION_FORMAT,
+ }),
+ ),
+);
+
+/**
+ * `$CODEX_HOME` when the operator set one, else `~/.codex`.
+ *
+ * Exported because the Codex adapter resolves the same directory for its
+ * `config.toml` and for the `CODEX_HOME` it injects into the CLI. It had
+ * its own copy, in a module pair whose whole thesis is that a fact about a
+ * host has one home - so a relocation rule fixed in one and not the other
+ * would put the session roots and the configuration on different disks.
+ */
+export function codexHome(ctx: HostContext): string {
+ return envOr(ctx, "CODEX_HOME", join(ctx.home, ".codex"));
+}
+
+/** Grok persists one ACP update stream per session, per encoded cwd. */
+const GROK_SESSION_ROOTS: ReadonlyArray<SessionRootSpec> = Object.freeze([
+ Object.freeze({
+ id: "grok-sessions",
+ resolve: (ctx: HostContext) =>
+ join(envOr(ctx, "GROK_HOME", join(ctx.home, ".grok")), "sessions"),
+ glob: "*/*/updates.jsonl",
+ adapter: SESSION_ADAPTER_ID.grok,
+ format: "grok-acp-session-update-jsonl",
+ }),
+]);
+
+/** The spool the bundled opencode plugin writes; a format this tool owns. */
+const OPENCODE_SESSION_ROOTS: ReadonlyArray<SessionRootSpec> = Object.freeze([
+ Object.freeze({
+ id: "opencode-session-spool",
+ resolve: (ctx: HostContext) =>
+ envOr(
+ ctx,
+ "OSB_OPENCODE_SPOOL_DIR",
+ join(
+ envOr(ctx, "XDG_DATA_HOME", join(ctx.home, ".local", "share")),
+ "open-second-brain",
+ "opencode",
+ ),
+ ),
+ glob: "*.jsonl",
+ adapter: SESSION_ADAPTER_ID.opencode,
+ format: "open-second-brain-opencode-spool-jsonl",
+ }),
+]);
+
+/**
+ * Claude Code keeps one `.jsonl` per session under a per-project
+ * directory whose name is the encoded working directory.
+ *
+ * Already walked by `src/core/discipline/transcripts/claude-code.ts` and
+ * by `src/core/brain/claude-memory-paths.ts`; declared here so the two
+ * subsystems stop knowing different halves of one fact.
+ */
+const CLAUDE_CODE_SESSION_ROOTS: ReadonlyArray<SessionRootSpec> = Object.freeze([
+ Object.freeze({
+ id: "claude-code-projects",
+ resolve: (ctx: HostContext) => join(ctx.home, ".claude", "projects"),
+ glob: "*/*.jsonl",
+ adapter: SESSION_ADAPTER_ID.claude,
+ format: "claude-code-transcript-jsonl",
+ }),
+]);
+
+/** No transcripts, no roots: an empty list is the stated answer. */
+const NO_SESSION_ROOTS: ReadonlyArray<SessionRootSpec> = Object.freeze([]);
+
+/**
+ * Where every runtime this build can locate keeps its session logs.
+ *
+ * The ONE declaration. Both consumers read it: the discovery sweep
+ * (`src/core/brain/sessions/discover.ts`), which asks whether a file was
+ * ever imported, and the discipline transcript scanner
+ * (`src/core/discipline/transcripts/`), which asks whether a file was
+ * touched inside a day window. Two questions, one input, and before this
+ * table each carried its own copy of where that input lives - so
+ * relocating a runtime moved one consumer and not the other.
+ */
+export const SESSION_ROOTS: Readonly<Record<SessionRuntimeId, ReadonlyArray<SessionRootSpec>>> =
+ Object.freeze({
+ [SESSION_RUNTIME_ID.claudeCode]: CLAUDE_CODE_SESSION_ROOTS,
+ [SESSION_RUNTIME_ID.codex]: CODEX_SESSION_ROOTS,
+ [SESSION_RUNTIME_ID.cursor]: CURSOR_SESSION_ROOTS,
+ [SESSION_RUNTIME_ID.grok]: GROK_SESSION_ROOTS,
+ [SESSION_RUNTIME_ID.opencode]: OPENCODE_SESSION_ROOTS,
+ });
+
+/**
+ * What this build knows about each runtime it installs into.
+ *
+ * Total over {@link InstallTargetId}, and the census next to it is what
+ * keeps it total: a new adapter without a row here fails before it ships.
+ */
+export const RUNTIME_FACTS: Readonly<Record<InstallTargetId, RuntimeFacts>> = Object.freeze({
+ [INSTALL_TARGET_ID.aider]: Object.freeze({
+ target: INSTALL_TARGET_ID.aider,
+ label: "Aider",
+ toolCeiling: Object.freeze({
+ kind: TOOL_CEILING_KIND.unknown,
+ reason:
+ "Aider is wired through a managed block in its YAML config and a sidecar context file, " +
+ "not an MCP server, so there is no per-workspace tool surface whose limit could be cited.",
+ }),
+ toolProfile: null,
+ sessionAdapter: null,
+ sessionRuntime: null,
+ sessionRoots: NO_SESSION_ROOTS,
+ hostProbe: null,
+ }),
+ [INSTALL_TARGET_ID.codex]: Object.freeze({
+ target: INSTALL_TARGET_ID.codex,
+ label: "Codex CLI",
+ toolCeiling: Object.freeze({
+ kind: TOOL_CEILING_KIND.unknown,
+ reason:
+ "Codex publishes no per-workspace MCP tool limit; `codex mcp list --json` reports each " +
+ "server's transport, startup and tool TIMEOUTS and auth status, and nothing in that " +
+ "record - or in this tree - is a tool-count cap.",
+ }),
+ toolProfile: null,
+ sessionAdapter: SESSION_ADAPTER_ID.codex,
+ sessionRuntime: SESSION_RUNTIME_ID.codex,
+ sessionRoots: SESSION_ROOTS[SESSION_RUNTIME_ID.codex],
+ // `mcp list` and NOT `mcp list --json`: the shared probe reads the
+ // first column of each output line, which is the name column here.
+ // Under `--json` the name arrives as `"name": "open-second-brain"`,
+ // whose first token is `"name":`, so a JSON probe would report every
+ // host as having nothing registered - a false negative dressed as an
+ // answer, which is the exact failure `host-probe.ts` exists to refuse.
+ hostProbe: Object.freeze({
+ bin: "codex",
+ argv: Object.freeze(["mcp", "list"]),
+ answers:
+ "whether this host has the Open Second Brain servers registered, read from the host " +
+ "itself rather than from the `config.toml` section the adapter writes.",
+ }),
+ }),
+ [INSTALL_TARGET_ID.copilotCli]: Object.freeze({
+ target: INSTALL_TARGET_ID.copilotCli,
+ label: "GitHub Copilot CLI",
+ toolCeiling: Object.freeze({
+ kind: TOOL_CEILING_KIND.unknown,
+ reason:
+ "GitHub Copilot CLI publishes no per-workspace MCP tool limit; `copilot mcp list` " +
+ "reports which servers are registered, which is a different question.",
+ }),
+ toolProfile: null,
+ sessionAdapter: null,
+ sessionRuntime: null,
+ sessionRoots: NO_SESSION_ROOTS,
+ hostProbe: Object.freeze({
+ bin: "copilot",
+ argv: Object.freeze(["mcp", "list"]),
+ answers:
+ "whether this host has the Open Second Brain servers registered, read from the host " +
+ "itself rather than inferred from the config file the adapter writes.",
+ }),
+ }),
+ [INSTALL_TARGET_ID.cursor]: Object.freeze({
+ target: INSTALL_TARGET_ID.cursor,
+ label: "Cursor",
+ toolCeiling: Object.freeze({
+ kind: TOOL_CEILING_KIND.declared,
+ maxTools: 40,
+ source:
+ "Cursor's published MCP limit: a workspace sends at most the first 40 tools across all " +
+ "enabled MCP servers to the model, and the rest are unreachable.",
+ }),
+ // The two-pass surface advertises 7 tools and keeps every registered
+ // verb reachable through `tool_hydrate`, so the ceiling is respected
+ // without any verb being withheld.
+ toolProfile: "catalog",
+ sessionAdapter: null,
+ sessionRuntime: SESSION_RUNTIME_ID.cursor,
+ sessionRoots: SESSION_ROOTS[SESSION_RUNTIME_ID.cursor],
+ hostProbe: null,
+ }),
+ [INSTALL_TARGET_ID.geminiCli]: Object.freeze({
+ target: INSTALL_TARGET_ID.geminiCli,
+ label: "Google Gemini CLI",
+ toolCeiling: Object.freeze({
+ kind: TOOL_CEILING_KIND.unknown,
+ reason:
+ "Google Gemini CLI publishes no per-workspace MCP tool limit; nothing in this tree has " +
+ "measured one either.",
+ }),
+ toolProfile: null,
+ sessionAdapter: null,
+ sessionRuntime: null,
+ sessionRoots: NO_SESSION_ROOTS,
+ hostProbe: null,
+ }),
+ [INSTALL_TARGET_ID.generic]: Object.freeze({
+ target: INSTALL_TARGET_ID.generic,
+ label: "Generic (printout)",
+ toolCeiling: Object.freeze({
+ kind: TOOL_CEILING_KIND.unknown,
+ reason:
+ "the generic target prints a payload for a host it was never told the name of, so there " +
+ "is no host whose published limit could be cited.",
+ }),
+ toolProfile: null,
+ sessionAdapter: null,
+ sessionRuntime: null,
+ sessionRoots: NO_SESSION_ROOTS,
+ hostProbe: null,
+ }),
+ [INSTALL_TARGET_ID.grok]: Object.freeze({
+ target: INSTALL_TARGET_ID.grok,
+ label: "Grok Build",
+ toolCeiling: Object.freeze({
+ kind: TOOL_CEILING_KIND.unknown,
+ reason:
+ "Grok Build publishes no per-session MCP tool limit; nothing in this tree has measured " +
+ "one either.",
+ }),
+ toolProfile: null,
+ sessionAdapter: SESSION_ADAPTER_ID.grok,
+ sessionRuntime: SESSION_RUNTIME_ID.grok,
+ sessionRoots: SESSION_ROOTS[SESSION_RUNTIME_ID.grok],
+ hostProbe: null,
+ }),
+ [INSTALL_TARGET_ID.kiro]: Object.freeze({
+ target: INSTALL_TARGET_ID.kiro,
+ label: "kiro",
+ toolCeiling: Object.freeze({
+ kind: TOOL_CEILING_KIND.unknown,
+ reason:
+ "Kiro publishes no per-workspace MCP tool limit; nothing in this tree has measured one " +
+ "either.",
+ }),
+ toolProfile: null,
+ sessionAdapter: null,
+ sessionRuntime: null,
+ sessionRoots: NO_SESSION_ROOTS,
+ hostProbe: null,
+ }),
+ [INSTALL_TARGET_ID.opencode]: Object.freeze({
+ target: INSTALL_TARGET_ID.opencode,
+ label: "opencode",
+ toolCeiling: Object.freeze({
+ kind: TOOL_CEILING_KIND.unknown,
+ reason:
+ "opencode publishes no per-session MCP tool limit; nothing in this tree has measured one " +
+ "either.",
+ }),
+ toolProfile: null,
+ sessionAdapter: SESSION_ADAPTER_ID.opencode,
+ sessionRuntime: SESSION_RUNTIME_ID.opencode,
+ sessionRoots: SESSION_ROOTS[SESSION_RUNTIME_ID.opencode],
+ hostProbe: null,
+ }),
+ [INSTALL_TARGET_ID.pi]: Object.freeze({
+ target: INSTALL_TARGET_ID.pi,
+ label: "Pi (pi.dev)",
+ toolCeiling: Object.freeze({
+ kind: TOOL_CEILING_KIND.unknown,
+ reason:
+ "Pi is installed as a skill symlink rather than an MCP server, so there is no tool " +
+ "surface on this host whose limit could be cited.",
+ }),
+ toolProfile: null,
+ sessionAdapter: null,
+ sessionRuntime: null,
+ sessionRoots: NO_SESSION_ROOTS,
+ hostProbe: null,
+ }),
+});
+
+// ---------- Accessors ----------
+
+/** The row for `target`. Total: every member of the vocabulary has one. */
+export function runtimeFactsFor(target: InstallTargetId): RuntimeFacts {
+ return RUNTIME_FACTS[target];
+}
+
+/** One declared root against one concrete host. */
+function resolveRoot(root: SessionRootSpec, ctx: HostContext): ResolvedSessionRoot {
+ return {
+ id: root.id,
+ path: root.resolve(ctx),
+ glob: root.glob,
+ adapter: root.adapter,
+ format: root.format,
+ };
+}
+
+/** `target`'s session roots against one concrete host, in declared order. */
+export function resolveSessionRoots(
+ target: InstallTargetId,
+ ctx: HostContext,
+): ReadonlyArray<ResolvedSessionRoot> {
+ return RUNTIME_FACTS[target].sessionRoots.map((root) => resolveRoot(root, ctx));
+}
+
+/**
+ * `runtime`'s session roots against one concrete host, in declared order.
+ *
+ * The runtime-keyed sibling of {@link resolveSessionRoots}, and the one
+ * the two sweeps use: neither of them starts from an install target, and
+ * Claude Code has no install target to start from.
+ */
+export function resolveSessionRootsFor(
+ runtime: SessionRuntimeId,
+ ctx: HostContext,
+): ReadonlyArray<ResolvedSessionRoot> {
+ return SESSION_ROOTS[runtime].map((root) => resolveRoot(root, ctx));
+}
diff --git a/src/core/state/migrate.ts b/src/core/state/migrate.ts
new file mode 100644
index 00000000..b2c06ac6
--- /dev/null
+++ b/src/core/state/migrate.ts
@@ -0,0 +1,1267 @@
+/**
+ * Moving a vault's state to another place, and putting it back.
+ *
+ * `surfaces.ts` answers where the state IS. This module is the one
+ * operation that changes that answer, and it is the operation in this
+ * project with the worst failure mode: bytes that exist in neither the
+ * old location nor the new one are gone, and half the declared surfaces
+ * are `vault-content`, which by definition does not rebuild.
+ *
+ * Two decisions follow from that and shape everything below.
+ *
+ * ## Fail BEFORE commit, not on first sight
+ *
+ * {@link planStateMigration} runs every check and returns ALL of them.
+ * It never short-circuits on the first refusal, and it never touches the
+ * filesystem. An operator who fixes a symlink only to be told about a
+ * held writer lock, then about a full disk, learns their vault's
+ * problems one interrupted migration at a time; the whole plan is
+ * rejected at once instead, and {@link applyStateMigration} refuses to
+ * run a plan carrying any refusal at all.
+ *
+ * Within the apply itself the same rule holds one level down. Every file
+ * is COPIED and its landed bytes re-digested before ANY source byte is
+ * removed. A copy that fails half way unwinds the copies it made and
+ * leaves the source exactly as it found it; only once the whole tree has
+ * landed and verified does the removal pass run. A move implemented as
+ * per-file rename would be faster and would also be the shape that
+ * strands a tree across two directories.
+ *
+ * ## Put back only what is still the same
+ *
+ * {@link planStateRollback} restores what the manifest binds AND whose
+ * digest still matches. Anything else - a file edited at the destination
+ * since the migration, a file the manifest names that is no longer
+ * there, a source path that has diverged - is REFUSED BY NAME and left
+ * exactly where it is. Nothing this module can do makes an operator's
+ * later edit recoverable, so the one thing it must never do is delete
+ * it. The refusals are part of the returned value rather than a warning
+ * on stderr, which is what lets the CLI make them part of its exit code.
+ *
+ * The ROOT is checked the same way and before any of that: the manifest
+ * records an absolute source root, and a vault renamed since the
+ * migration would otherwise have that dead path recreated, restored into,
+ * and its live destination copies deleted behind it. A root that is no
+ * longer a directory is refused by name, and {@link RollbackPlanInput.vault}
+ * is how an operator says where the vault went - with the recorded root
+ * still reported, so an override is read rather than assumed.
+ *
+ * ## What the manifest binds
+ *
+ * Through {@link sha256Hex} and {@link canonicalJson}, the one digest
+ * encoding in this project: the source type, the canonical roots, the
+ * full path inventory, a byte count per file and a SHA-256 per file, and
+ * a digest over all of it. A manifest that does not verify is refused
+ * rather than repaired - a rollback driven by a manifest somebody edited
+ * is a restore of something nobody measured.
+ *
+ * ## What this module does NOT enumerate
+ *
+ * It has no list of state locations. Every path it touches comes from
+ * {@link inventoryStateSurfaces}, so a surface added to `surfaces.ts`
+ * moves without a second edit here, and a surface this module could move
+ * but the inventory does not declare cannot exist.
+ */
+
+import {
+ copyFileSync,
+ existsSync,
+ lstatSync,
+ mkdirSync,
+ readFileSync,
+ readdirSync,
+ readlinkSync,
+ realpathSync,
+ rmSync,
+ rmdirSync,
+ statSync,
+ statfsSync,
+ type Stats,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+import { atomicWriteFileSync } from "../fs-atomic.ts";
+import { canonicalJson, DIGEST_ALGORITHM, sha256Hex } from "../integrity/digest.ts";
+import { isWriterLockHeld } from "../search/store/writer-lock.ts";
+import {
+ inventoryStateSurfaces,
+ STATE_REACHABILITY,
+ STATE_SURFACE_ID,
+ type StateInventoryInput,
+ type StateSurfaceId,
+} from "./surfaces.ts";
+
+// ----- Vocabularies ---------------------------------------------------------
+
+/** The manifest file a migration leaves at its destination. */
+export const MIGRATION_MANIFEST_FILE = "state-migration.json";
+
+/** The manifest layout this build writes and is willing to read back. */
+export const MIGRATION_MANIFEST_SCHEMA_VERSION = 1;
+
+/**
+ * What a migration was taken FROM.
+ *
+ * One member today, and a field rather than an assumption for the same
+ * reason `schema_version` is: a manifest is read back by a later build,
+ * and a build that cannot name the shape it is looking at cannot refuse
+ * a shape it does not understand. {@link planStateRollback} checks it,
+ * so the field has a job rather than a plan to have one.
+ */
+export const MIGRATION_SOURCE_TYPE = Object.freeze({ vault: "vault" } as const);
+
+export type MigrationSourceType =
+ (typeof MIGRATION_SOURCE_TYPE)[keyof typeof MIGRATION_SOURCE_TYPE];
+
+/**
+ * Why a migration will not run.
+ *
+ * Closed, because every member is a distinct repair: the operator who
+ * hits `symlink` resolves a link, the one who hits `writer_lock_held`
+ * waits for an index write, and folding them into one "cannot migrate"
+ * would make the difference something they have to read prose to find.
+ */
+export const MIGRATION_REFUSAL = Object.freeze({
+ symlink: "symlink",
+ specialFile: "special_file",
+ destinationOccupied: "destination_occupied",
+ insufficientSpace: "insufficient_space",
+ reservedNamespace: "reserved_namespace",
+ writerLockHeld: "writer_lock_held",
+ unreadableSurface: "unreadable_surface",
+} as const);
+
+export type MigrationRefusalCode = (typeof MIGRATION_REFUSAL)[keyof typeof MIGRATION_REFUSAL];
+
+/** Why a rollback will not put one entry back. */
+export const ROLLBACK_REFUSAL = Object.freeze({
+ digestMismatch: "digest_mismatch",
+ missingAtDestination: "missing_at_destination",
+ sourceDiverged: "source_diverged",
+ unreadable: "unreadable",
+} as const);
+
+export type RollbackRefusalCode = (typeof ROLLBACK_REFUSAL)[keyof typeof ROLLBACK_REFUSAL];
+
+/** Raised for a condition the caller cannot plan around. Always names the remedy. */
+export class StateMigrationError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = "StateMigrationError";
+ }
+}
+
+// ----- The manifest ---------------------------------------------------------
+
+/** One file the migration binds. */
+export interface MigrationEntry {
+ /** Vault-relative, POSIX-separated, so a manifest survives a copy between hosts. */
+ readonly relative_path: string;
+ readonly bytes: number;
+ readonly digest: string;
+}
+
+/** Everything a rollback needs, bound by one digest. */
+export interface MigrationManifest {
+ readonly schema_version: number;
+ readonly algorithm: string;
+ readonly source_type: MigrationSourceType;
+ readonly source_root: string;
+ readonly destination_root: string;
+ /**
+ * The minimal set of vault-relative directories covering every moved
+ * file: a declared surface nested inside another is absorbed by the
+ * one that contains it, so no byte is bound twice.
+ */
+ readonly canonical_roots: ReadonlyArray<string>;
+ readonly entries: ReadonlyArray<MigrationEntry>;
+ readonly total_bytes: number;
+ readonly created_at: string;
+ /** `sha256Hex(canonicalJson(<this object without this field>))`. */
+ readonly digest: string;
+}
+
+/** Bind a manifest body to its digest. The one place either is computed. */
+function sealManifest(body: Omit<MigrationManifest, "digest">): MigrationManifest {
+ return { ...body, digest: sha256Hex(canonicalJson(body)) };
+}
+
+/** Whether a manifest's digest still describes its body. */
+function manifestVerifies(manifest: MigrationManifest): boolean {
+ const { digest, ...body } = manifest;
+ return sha256Hex(canonicalJson(body)) === digest;
+}
+
+// ----- Planning a migration -------------------------------------------------
+
+/** What was found, and what to do about it. Never one without the other. */
+export interface MigrationRefusal {
+ readonly code: MigrationRefusalCode;
+ /** The absolute path the refusal is about. */
+ readonly path: string;
+ readonly found: string;
+ readonly remedy: string;
+}
+
+/** A declared surface that resolved OUTSIDE the vault, and is therefore not moved. */
+export interface ExternalSurface {
+ readonly id: StateSurfaceId;
+ readonly label: string;
+ readonly path: string;
+ readonly reason: string;
+}
+
+export interface MigrationPlan {
+ readonly source: string;
+ readonly destination: string;
+ readonly manifest: MigrationManifest;
+ /** Empty exactly when the plan may be applied. */
+ readonly refusals: ReadonlyArray<MigrationRefusal>;
+ /** Surfaces an override put outside the vault; they stay where they are. */
+ readonly external: ReadonlyArray<ExternalSurface>;
+}
+
+export interface MigrationPlanInput extends StateInventoryInput {
+ /** Where the state is to be moved to. Created by the apply, never by the plan. */
+ readonly destination: string;
+ /** Timestamp the manifest records. Injected so a manifest is reproducible in tests. */
+ readonly now?: Date;
+ /**
+ * Free bytes at a path. Injected only by tests, which cannot fill a
+ * disk; the product uses `statfsSync` on the nearest existing ancestor.
+ */
+ readonly freeBytesAt?: (path: string) => number;
+ /**
+ * Whether the search writer lock is held. Injected only by tests - the
+ * product asks `isWriterLockHeld`, and a throw from it is a refusal
+ * rather than a `false`, exactly as that module's contract requires.
+ */
+ readonly writerLockHeldAt?: (dbPath: string) => boolean;
+}
+
+/**
+ * Everything that must be true before a single byte moves.
+ *
+ * Reads the filesystem and writes nothing. The returned plan is the whole
+ * answer: an empty {@link MigrationPlan.refusals} is the only licence
+ * {@link applyStateMigration} accepts.
+ */
+export function planStateMigration(input: MigrationPlanInput): MigrationPlan {
+ const source = resolve(input.vault);
+ const destination = resolve(input.destination);
+ const inventory = inventoryStateSurfaces({ ...input, vault: source });
+
+ const refusals: MigrationRefusal[] = [];
+ const external: ExternalSurface[] = [];
+ const inVaultRoots = new Map<string, StateSurfaceId>();
+
+ for (const surface of inventory.surfaces) {
+ if (surface.reachability.state === STATE_REACHABILITY.unchecked) {
+ refusals.push({
+ code: MIGRATION_REFUSAL.unreadableSurface,
+ path: surface.path,
+ found: `the ${surface.label} ${surface.reachability.reason ?? "could not be probed"}`,
+ remedy:
+ "a surface this run cannot read is a surface it cannot move, and moving the rest " +
+ "would leave it behind without saying so; make the path readable to this user, or " +
+ "run the migration as the user that owns it",
+ });
+ continue;
+ }
+ if (surface.reachability.state !== STATE_REACHABILITY.present) continue;
+ const rel = vaultRelative(source, surface.path);
+ if (rel === null) {
+ external.push({
+ id: surface.id,
+ label: surface.label,
+ path: surface.path,
+ reason:
+ `an override placed it outside ${source}, so migrating the vault does not move it; ` +
+ "it stays where it was put",
+ });
+ continue;
+ }
+ inVaultRoots.set(rel, surface.id);
+ }
+
+ const canonicalRoots = collapseNested([...inVaultRoots.keys()]);
+
+ const entries: MigrationEntry[] = [];
+ for (const root of canonicalRoots) collect(source, root, entries, refusals);
+ entries.sort((a, b) => (a.relative_path < b.relative_path ? -1 : 1));
+ const totalBytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+
+ refusals.push(...reservedNamespaceRefusals(source, destination));
+ const occupied = destinationRefusal(destination);
+ if (occupied !== null) refusals.push(occupied);
+ const space = spaceRefusal(destination, totalBytes, input.freeBytesAt ?? freeBytesAt);
+ if (space !== null) refusals.push(space);
+ const lock = writerLockRefusal(
+ inventory.surfaces.find((s) => s.id === STATE_SURFACE_ID.searchIndex)?.path ?? null,
+ input.writerLockHeldAt ?? isWriterLockHeld,
+ );
+ if (lock !== null) refusals.push(lock);
+
+ return {
+ source,
+ destination,
+ manifest: sealManifest({
+ schema_version: MIGRATION_MANIFEST_SCHEMA_VERSION,
+ algorithm: DIGEST_ALGORITHM,
+ source_type: MIGRATION_SOURCE_TYPE.vault,
+ source_root: source,
+ destination_root: destination,
+ canonical_roots: canonicalRoots,
+ entries,
+ total_bytes: totalBytes,
+ created_at: (input.now ?? new Date()).toISOString(),
+ }),
+ refusals,
+ external,
+ };
+}
+
+/**
+ * `path` as a vault-relative POSIX path, or `null` when it is not inside
+ * the vault at all. The vault itself is `null` too: a surface that
+ * resolved to the vault root would drag the whole tree in.
+ */
+function vaultRelative(vault: string, path: string): string | null {
+ const rel = relative(vault, resolve(path));
+ if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+ return rel.split(sep).join("/");
+}
+
+/** Absolute path for a vault-relative POSIX path. */
+function absolute(root: string, rel: string): string {
+ return join(root, ...rel.split("/"));
+}
+
+/** Drop every path that lies under another one in the same set, then sort. */
+function collapseNested(paths: ReadonlyArray<string>): string[] {
+ return paths
+ .filter((candidate) => !paths.some((other) => candidate.startsWith(`${other}/`)))
+ .toSorted();
+}
+
+/**
+ * Every file under one canonical root, refusing anything that is not a
+ * plain file or a directory.
+ *
+ * `lstatSync`, never `statSync`: a symlink is refused for what it IS, and
+ * a `statSync` here would follow it and copy the target's bytes into the
+ * destination under the link's name - which is a silent change of meaning
+ * rather than a move.
+ */
+function collect(
+ source: string,
+ rel: string,
+ entries: MigrationEntry[],
+ refusals: MigrationRefusal[],
+): void {
+ const path = absolute(source, rel);
+ let stat: Stats;
+ try {
+ stat = lstatSync(path);
+ } catch (error) {
+ refusals.push(unreadableInTree(path, error, "read"));
+ return;
+ }
+
+ if (stat.isSymbolicLink()) {
+ refusals.push({
+ code: MIGRATION_REFUSAL.symlink,
+ path,
+ found: `a symbolic link to ${readLinkTarget(path)}`,
+ remedy:
+ "a migration copies bytes, so a link would arrive pointing at the OLD location and " +
+ "the target would silently stay behind; replace the link with the file it names, or " +
+ "move its target out of the state tree, then plan again",
+ });
+ return;
+ }
+ if (stat.isDirectory()) {
+ // Guarded for the same reason the `lstat` above is, and it is the
+ // same one check: an `EACCES` thrown from here left `planStateMigration`
+ // through a stack rather than through a refusal, so the operator got
+ // no remedy AND every other refusal in the tree went uncomputed -
+ // which is precisely the "runs every check and returns ALL of them"
+ // contract this module leads with.
+ let children: string[];
+ try {
+ children = readdirSync(path).toSorted();
+ } catch (error) {
+ refusals.push(unreadableInTree(path, error, "listed"));
+ return;
+ }
+ for (const child of children) {
+ collect(source, `${rel}/${child}`, entries, refusals);
+ }
+ return;
+ }
+ if (!stat.isFile()) {
+ refusals.push({
+ code: MIGRATION_REFUSAL.specialFile,
+ path,
+ found: `a ${specialFileKind(stat)}, which has no bytes to copy`,
+ remedy:
+ "remove it from the state tree, or recreate it at the destination after the " +
+ "migration; copying it would produce a plain file that only looks like the original",
+ });
+ return;
+ }
+
+ let body: Buffer;
+ try {
+ body = readFileSync(path);
+ } catch (error) {
+ refusals.push(unreadableInTree(path, error, "read"));
+ return;
+ }
+ entries.push({ relative_path: rel, bytes: body.byteLength, digest: sha256Hex(body) });
+}
+
+/** The one wording for "this run could not look at part of the state tree". */
+function unreadableInTree(path: string, error: unknown, verb: string): MigrationRefusal {
+ const err = error as NodeJS.ErrnoException;
+ return {
+ code: MIGRATION_REFUSAL.unreadableSurface,
+ path,
+ found: `could not be ${verb} (${err.code ?? "unknown error"}): ${err.message}`,
+ remedy:
+ "make the path readable to this user before migrating; a tree this run cannot " +
+ "enumerate cannot be bound by a manifest, and an unbound file is not restorable",
+ };
+}
+
+function readLinkTarget(path: string): string {
+ try {
+ return readlinkSync(path);
+ } catch {
+ return "a target this run could not read";
+ }
+}
+
+/** What kind of non-file this is, in the words `stat(2)` uses for it. */
+function specialFileKind(stat: Stats): string {
+ if (stat.isFIFO()) return "FIFO (named pipe)";
+ if (stat.isSocket()) return "socket";
+ if (stat.isBlockDevice()) return "block device";
+ if (stat.isCharacterDevice()) return "character device";
+ return "file of an unrecognised type";
+}
+
+/**
+ * Destinations a migration will not write into.
+ *
+ * The two nesting arms are the ones that corrupt rather than merely
+ * surprise: a destination inside the vault is copied INTO the tree being
+ * walked, and a destination containing the vault makes every source path
+ * a child of the target. The other two are namespaces nobody dedicates to
+ * one tool: scattering forty state locations across `$HOME` or `/` is not
+ * undoable by reading a manifest.
+ *
+ * Every comparison is made over {@link realPath}, never over the argument
+ * strings. `resolve` collapses `.` and `..` and cannot see a symlink, so
+ * `/outside/link -> <vault>/Brain` was inside the vault by every test
+ * that matters and outside it by every string test - the whole state tree
+ * landed in the vault it was being migrated out of, with `refusals: []`.
+ */
+function reservedNamespaceRefusals(source: string, destination: string): MigrationRefusal[] {
+ const out: MigrationRefusal[] = [];
+ const realSource = realPath(source);
+ const realDestination = realPath(destination);
+ // Named in the finding whenever the link matters, because "a path
+ // inside the vault" about a path that visibly is not one reads as a bug
+ // in the tool rather than as the fact it is.
+ const via =
+ realDestination === destination ? "" : `; ${destination} resolves to ${realDestination}`;
+ const push = (found: string, remedy: string): void => {
+ out.push({
+ code: MIGRATION_REFUSAL.reservedNamespace,
+ path: destination,
+ found: `${found}${via}`,
+ remedy,
+ });
+ };
+ if (realDestination === realSource || realDestination.startsWith(`${realSource}${sep}`)) {
+ push(
+ `a path inside the vault being migrated (${source})`,
+ "name a destination outside the vault; copying the state tree into itself would " +
+ "recurse into the copy it is making",
+ );
+ } else if (realSource.startsWith(`${realDestination}${sep}`)) {
+ push(
+ `an ancestor of the vault being migrated (${source})`,
+ "name a destination that does not contain the vault; every source path is already " +
+ "below it, so the move has no direction",
+ );
+ }
+ if (dirname(realDestination) === realDestination) {
+ push(
+ "the filesystem root",
+ "name a directory dedicated to this vault's state; state written at the root is " +
+ "indistinguishable from everything else there",
+ );
+ }
+ if (realDestination === realPath(homedir())) {
+ push(
+ `the home directory itself (${destination})`,
+ "name a subdirectory of the home directory instead, so the state stays one tree an " +
+ "operator can move, back up, or delete as a unit",
+ );
+ }
+ return out;
+}
+
+/**
+ * `path` with every EXISTING ancestor resolved through the filesystem.
+ *
+ * A migration creates its own destination, so the leaf usually does not
+ * exist yet and `realpathSync` on the whole path would throw. This walks
+ * up to the nearest ancestor the filesystem answers for and re-appends
+ * the segments below it, which is what makes a not-yet-created
+ * destination comparable at all.
+ *
+ * A path no ancestor resolves - a permission wall on the way up - falls
+ * back to the lexical answer rather than throwing here. That is not a
+ * quiet pass: a destination this run cannot examine is refused on its own
+ * evidence by {@link destinationRefusal}, which is the check that owns
+ * that condition.
+ */
+function realPath(path: string): string {
+ const lexical = resolve(path);
+ const below: string[] = [];
+ let at = lexical;
+ for (;;) {
+ try {
+ return join(realpathSync(at), ...below.toReversed());
+ } catch {
+ const parent = dirname(at);
+ if (parent === at) return lexical;
+ below.push(basename(at));
+ at = parent;
+ }
+ }
+}
+
+/** A destination that already holds content is refused rather than merged into. */
+function destinationRefusal(destination: string): MigrationRefusal | null {
+ let stat: Stats;
+ try {
+ stat = lstatSync(destination);
+ } catch (error) {
+ const err = error as NodeJS.ErrnoException;
+ if (err.code === "ENOENT") return null;
+ return {
+ code: MIGRATION_REFUSAL.destinationOccupied,
+ path: destination,
+ found: `could not be examined (${err.code ?? "unknown error"}): ${err.message}`,
+ remedy:
+ "a destination this run cannot look at cannot be shown to be empty; fix the " +
+ "permissions on it, or name one that does not exist yet",
+ };
+ }
+ if (!stat.isDirectory()) {
+ return {
+ code: MIGRATION_REFUSAL.destinationOccupied,
+ path: destination,
+ found: "an existing non-directory",
+ remedy: "name an empty directory, or a path that does not exist yet",
+ };
+ }
+ let children: string[];
+ try {
+ children = readdirSync(destination).toSorted();
+ } catch (error) {
+ const err = error as NodeJS.ErrnoException;
+ return {
+ code: MIGRATION_REFUSAL.destinationOccupied,
+ path: destination,
+ found: `could not be listed (${err.code ?? "unknown error"}): ${err.message}`,
+ remedy:
+ "a destination this run cannot look inside cannot be shown to be empty; fix the " +
+ "permissions on it, or name one that does not exist yet",
+ };
+ }
+ if (children.length === 0) return null;
+ return {
+ code: MIGRATION_REFUSAL.destinationOccupied,
+ path: destination,
+ found: `${children.length} existing ${children.length === 1 ? "entry" : "entries"} (${children.join(", ")})`,
+ remedy:
+ "name an empty directory. Merging into an occupied one would make the manifest " +
+ "unable to say which files this migration put there, and a rollback would have to " +
+ "guess",
+ };
+}
+
+/** Free bytes on the filesystem holding the nearest existing ancestor of `path`. */
+function freeBytesAt(path: string): number {
+ let at = resolve(path);
+ while (!existsSync(at)) {
+ const parent = dirname(at);
+ if (parent === at) break;
+ at = parent;
+ }
+ const stat = statfsSync(at);
+ return Number(stat.bsize) * Number(stat.bavail);
+}
+
+function spaceRefusal(
+ destination: string,
+ needed: number,
+ probe: (path: string) => number,
+): MigrationRefusal | null {
+ let free: number;
+ try {
+ free = probe(destination);
+ } catch (error) {
+ const err = error as NodeJS.ErrnoException;
+ return {
+ code: MIGRATION_REFUSAL.insufficientSpace,
+ path: destination,
+ found: `free space could not be measured (${err.code ?? "unknown error"}): ${err.message}`,
+ remedy:
+ "a migration that runs out of space mid-copy is the case this check exists for, so " +
+ "an unmeasurable filesystem is refused rather than attempted; name a destination on " +
+ "a filesystem this user can stat",
+ };
+ }
+ if (free >= needed) return null;
+ return {
+ code: MIGRATION_REFUSAL.insufficientSpace,
+ path: destination,
+ found: `${bytesPhrase(free)} available at the destination, ${bytesPhrase(needed)} needed`,
+ remedy:
+ "free space on the destination filesystem, or name a destination with room; the copy " +
+ "runs to completion before any source byte is removed, so a full disk would abort the " +
+ "whole migration rather than lose anything",
+ };
+}
+
+function bytesPhrase(count: number): string {
+ return `${count} ${count === 1 ? "byte" : "bytes"}`;
+}
+
+/**
+ * A migration racing an index write is the one failure a digest cannot
+ * undo: the writer holds a file this run has already hashed, and the
+ * bytes it appends after the hash land nowhere. `isWriterLockHeld` is
+ * advisory - it answers about the instant it is called - which is enough
+ * here, because the alternative is not a stronger check but no check.
+ */
+function writerLockRefusal(
+ indexPath: string | null,
+ probe: (dbPath: string) => boolean,
+): MigrationRefusal | null {
+ if (indexPath === null) return null;
+ let held: boolean;
+ try {
+ held = probe(indexPath);
+ } catch (error) {
+ const err = error as NodeJS.ErrnoException;
+ return {
+ code: MIGRATION_REFUSAL.writerLockHeld,
+ path: indexPath,
+ found: `the writer lock state could not be determined (${err.code ?? "unknown error"}): ${err.message}`,
+ remedy:
+ '"I could not find out" is not "the lock is free"; make the lock path readable, ' +
+ "then plan again once no reindex is running",
+ };
+ }
+ if (!held) return null;
+ return {
+ code: MIGRATION_REFUSAL.writerLockHeld,
+ path: indexPath,
+ found: "the search index writer lock is held by a live writer",
+ remedy:
+ "wait for the running reindex or index write to finish and plan again; bytes appended " +
+ "to the index after this run hashed it would land in neither copy, and that is the one " +
+ "loss a digest cannot detect afterwards",
+ };
+}
+
+// ----- Applying a migration -------------------------------------------------
+
+export interface MigrationResult {
+ readonly manifest_path: string;
+ /** Vault-relative paths that landed and verified, in manifest order. */
+ readonly moved: ReadonlyArray<string>;
+ readonly bytes: number;
+}
+
+/**
+ * Copy every bound file, verify it landed, write the manifest, and only
+ * then remove the sources.
+ *
+ * The order is the guarantee. A failure during the copy pass unwinds what
+ * it copied and returns the source untouched; a failure after it leaves
+ * both copies plus a manifest, which {@link planStateRollback} reads as
+ * already-restored rather than as a conflict.
+ */
+export function applyStateMigration(plan: MigrationPlan): MigrationResult {
+ if (plan.refusals.length > 0) {
+ throw new StateMigrationError(
+ `refusing to migrate: ${plan.refusals.length} check(s) failed - ` +
+ plan.refusals.map((r) => `${r.code} at ${r.path} (${r.found})`).join("; ") +
+ ". Resolve them and plan again; nothing has been moved.",
+ );
+ }
+
+ const landed: string[] = [];
+ try {
+ for (const entry of plan.manifest.entries) {
+ const target = absolute(plan.destination, entry.relative_path);
+ // `destination_occupied` again, one confirmation later. The plan
+ // measured it before the operator read it, and anything that
+ // arrived since would be overwritten here AND removed by the
+ // unwind below, which cannot tell a file it created from one it
+ // clobbered. `lstat` rather than `existsSync`: a dangling symlink
+ // is something at the target too, and copying through it writes
+ // wherever it points.
+ if (lstatSync(target, { throwIfNoEntry: false }) !== undefined) {
+ throw new StateMigrationError(
+ `${target} appeared at the destination after this plan was made ` +
+ `(${MIGRATION_REFUSAL.destinationOccupied}); it is left exactly as it is and ` +
+ "nothing was copied onto it - move it aside, then plan and apply again",
+ );
+ }
+ mkdirSync(dirname(target), { recursive: true });
+ // Recorded BEFORE the write rather than after the verify: the
+ // unwind has to remove what this run WROTE, and a copy that failed
+ // part way through, or landed with the wrong bytes, has still
+ // written something. The occupancy check above is what makes that
+ // safe - nothing was at this path a moment ago, so whatever is
+ // there now is ours to take back.
+ landed.push(target);
+ copyFileSync(absolute(plan.source, entry.relative_path), target);
+ const digest = sha256Hex(readFileSync(target));
+ if (digest !== entry.digest) {
+ throw new StateMigrationError(
+ `${entry.relative_path} did not land intact: the manifest binds ${entry.digest} ` +
+ `and the copy at ${target} digests to ${digest}`,
+ );
+ }
+ }
+ } catch (error) {
+ for (const target of landed.toReversed()) rmSync(target, { force: true });
+ // From the destination ITSELF rather than from the canonical roots.
+ // The copy pass creates every intermediate directory on the way down
+ // with `mkdirSync(..., { recursive: true })`, and a prune that starts
+ // at the roots never reaches the ones above them: the empty skeleton
+ // it left behind made the identical retry fail with
+ // `destination_occupied`, so a recoverable abort needed a manual
+ // `rm -rf` before the operator could try again. `pruneIfEmpty`
+ // removes ONLY empty directories, so anything that arrived here
+ // meanwhile keeps its parents alive and is never touched.
+ pruneIfEmpty(plan.destination);
+ throw new StateMigrationError(
+ `migration aborted during the copy pass and the destination was unwound; the source ` +
+ `at ${plan.source} is untouched. Cause: ${(error as Error).message}`,
+ );
+ }
+
+ const manifestPath = join(plan.destination, MIGRATION_MANIFEST_FILE);
+ atomicWriteFileSync(manifestPath, `${JSON.stringify(plan.manifest, null, 2)}\n`);
+
+ try {
+ for (const entry of plan.manifest.entries) {
+ rmSync(absolute(plan.source, entry.relative_path), { force: true });
+ }
+ pruneEmptyDirectories(plan.source, plan.manifest.canonical_roots);
+ } catch (error) {
+ // Past the commit point, and that is the news. Every bound file is
+ // at the destination and was re-digested there, and the manifest is
+ // written, so the half-cleaned source is exactly the shape a
+ // rollback puts back - `force: true` swallows only ENOENT, so this
+ // is a real refusal from the filesystem and not a missing file.
+ // Escaping as a raw `EACCES` told the operator none of that.
+ throw new StateMigrationError(
+ `every bound file landed and verified at ${plan.destination} and the manifest at ` +
+ `${manifestPath} was written, but the source at ${plan.source} could not be cleaned ` +
+ `up: ${(error as Error).message}. Nothing is lost - the bytes are at the destination; ` +
+ `undo the whole move with \`o2b state rollback --from ${plan.destination}\`, or fix ` +
+ "the permissions on the source and remove the leftovers by hand",
+ );
+ }
+
+ return {
+ manifest_path: manifestPath,
+ moved: plan.manifest.entries.map((entry) => entry.relative_path),
+ bytes: plan.manifest.total_bytes,
+ };
+}
+
+/**
+ * Remove directories under `roots` that are now empty, deepest first.
+ *
+ * Empty ONLY: a directory still holding something this migration did not
+ * bind - an operator's own file inside a state root - keeps the root
+ * alive, which is the correct outcome and the reason this is not an
+ * `rm -r` of the root.
+ */
+function pruneEmptyDirectories(base: string, roots: ReadonlyArray<string>): void {
+ for (const root of roots) pruneIfEmpty(absolute(base, root));
+}
+
+/**
+ * Remove `path` if it is an empty directory, depth first.
+ *
+ * Returns whether it is GONE, which is what tells the caller above
+ * whether its own directory is now empty. Every uncertain answer is
+ * `false`, and that is the whole correctness argument: a child this run
+ * could not look at was reported as gone, the parent was judged empty on
+ * the strength of it, and the `rmdir` that followed threw ENOTEMPTY out
+ * of an unwind whose message was the only thing telling the operator
+ * their source was untouched. A directory left standing costs an
+ * operator one `rmdir`; a wrong "it is gone" costs a throw in the middle
+ * of the recovery path.
+ */
+function pruneIfEmpty(path: string): boolean {
+ let stat: Stats;
+ try {
+ stat = lstatSync(path);
+ } catch (error) {
+ return (error as NodeJS.ErrnoException).code === "ENOENT";
+ }
+ if (!stat.isDirectory()) return false;
+ let children: string[];
+ try {
+ children = readdirSync(path);
+ } catch {
+ return false;
+ }
+ let empty = true;
+ for (const child of children) {
+ if (!pruneIfEmpty(join(path, child))) empty = false;
+ }
+ if (!empty) return false;
+ try {
+ rmdirSync(path);
+ } catch {
+ // Empty and still not removable: a leftover directory, never a lost
+ // byte. It is reported as still there so the walk stops here instead
+ // of throwing out of a caller whose real news is elsewhere.
+ return false;
+ }
+ return true;
+}
+
+// ----- Rolling a migration back ---------------------------------------------
+
+/** One entry the rollback will put back. */
+export interface RollbackEntry {
+ readonly relative_path: string;
+ readonly from: string;
+ readonly to: string;
+ /**
+ * True when the source already holds the bound bytes and only the copy
+ * is removed. Measured at plan time, so it is what the operator is
+ * shown; {@link applyStateRollback} probes the source again rather than
+ * acting on it, because the source can change while a plan is read.
+ */
+ readonly already_in_place: boolean;
+}
+
+/** One entry the rollback will NOT touch, and why. */
+export interface RollbackRefusal {
+ readonly code: RollbackRefusalCode;
+ readonly relative_path: string;
+ readonly path: string;
+ readonly found: string;
+ readonly remedy: string;
+}
+
+export interface RollbackPlan {
+ readonly manifest_path: string;
+ readonly manifest: MigrationManifest;
+ readonly source: string;
+ readonly destination: string;
+ readonly restore: ReadonlyArray<RollbackEntry>;
+ readonly refusals: ReadonlyArray<RollbackRefusal>;
+}
+
+export interface RollbackPlanInput {
+ /** The directory a migration was moved TO; it holds the manifest. */
+ readonly destination: string;
+ /**
+ * Where to put the files back, when that is no longer the root the
+ * manifest recorded - a vault renamed or moved since the migration.
+ * Absent means the recorded root, which then has to still be there.
+ */
+ readonly vault?: string;
+}
+
+/**
+ * Read the manifest and decide, per entry, whether it can go back.
+ *
+ * Writes nothing. Every entry is classified, including the ones that
+ * cannot be restored, because the list of what will be LEFT is the half
+ * an operator has to act on.
+ */
+export function planStateRollback(input: RollbackPlanInput): RollbackPlan {
+ const destination = resolve(input.destination);
+ const manifestPath = join(destination, MIGRATION_MANIFEST_FILE);
+ const manifest = readManifest(manifestPath);
+ const source = rollbackSource(manifest, input.vault ?? null, manifestPath);
+
+ const restore: RollbackEntry[] = [];
+ const refusals: RollbackRefusal[] = [];
+
+ for (const entry of manifest.entries) {
+ const from = absolute(destination, entry.relative_path);
+ const to = absolute(source, entry.relative_path);
+ const atDestination = digestOf(from);
+ if (atDestination.state === DIGEST_PROBE.unreadable) {
+ refusals.push(unreadableRefusal(entry.relative_path, from, atDestination.reason));
+ continue;
+ }
+ if (atDestination.state === DIGEST_PROBE.absent) {
+ refusals.push({
+ code: ROLLBACK_REFUSAL.missingAtDestination,
+ relative_path: entry.relative_path,
+ path: from,
+ found: "the manifest binds it, but nothing is there now",
+ remedy:
+ "restore it from a backup into the destination and roll back again; this run will " +
+ "not invent a file it cannot read",
+ });
+ continue;
+ }
+ if (atDestination.digest !== entry.digest) {
+ refusals.push({
+ code: ROLLBACK_REFUSAL.digestMismatch,
+ relative_path: entry.relative_path,
+ path: from,
+ found: `changed since the migration (bound ${entry.digest}, now ${atDestination.digest})`,
+ remedy:
+ "it is left exactly where it is and is never deleted; copy it somewhere safe, or " +
+ "keep the destination as the live location for it",
+ });
+ continue;
+ }
+ const atSource = digestOf(to);
+ if (atSource.state === DIGEST_PROBE.unreadable) {
+ refusals.push(unreadableRefusal(entry.relative_path, to, atSource.reason));
+ continue;
+ }
+ if (atSource.state === DIGEST_PROBE.digest && atSource.digest !== entry.digest) {
+ refusals.push(divergedRefusal(entry.relative_path, to, entry.digest, atSource.digest));
+ continue;
+ }
+ restore.push({
+ relative_path: entry.relative_path,
+ from,
+ to,
+ already_in_place: atSource.state === DIGEST_PROBE.digest,
+ });
+ }
+
+ return { manifest_path: manifestPath, manifest, source, destination, restore, refusals };
+}
+
+/**
+ * Where the files go back to.
+ *
+ * `source_root` is an absolute path recorded when the migration ran, and
+ * a vault renamed since is the case that turned a rollback into a data
+ * loss: the apply recreated the dead directory, copied into it, removed
+ * the destination copies and deleted the manifest, all while exiting 0.
+ * The live vault ended up with nothing and the only surviving copy was
+ * gone. So a recorded root that is no longer a directory is refused BY
+ * NAME here, before a single entry is classified, and `vault` is the way
+ * an operator says where it went. The recorded root stays on the plan and
+ * in {@link renderRollbackPlan} either way, so an override is something
+ * they can see rather than something they have to remember.
+ */
+function rollbackSource(
+ manifest: MigrationManifest,
+ override: string | null,
+ manifestPath: string,
+): string {
+ const source = override === null ? manifest.source_root : resolve(override);
+ const overridden =
+ override === null ? "" : ` (--to; the manifest recorded ${manifest.source_root})`;
+ let stat: Stats;
+ try {
+ // `statSync`, following links: a vault reached through a symlink is
+ // an ordinary install, and what is asked here is only whether there
+ // is a directory to restore into.
+ stat = statSync(source);
+ } catch (error) {
+ const err = error as NodeJS.ErrnoException;
+ throw new StateMigrationError(
+ `the rollback would restore into ${source}${overridden}, which this run cannot use ` +
+ `(${err.code ?? "unknown error"}): ${err.message}. The manifest at ${manifestPath} and ` +
+ "every file it binds are untouched; point the rollback at the vault's current " +
+ "location with `--to <dir>`, or put the vault back where the manifest says it was",
+ );
+ }
+ if (!stat.isDirectory()) {
+ throw new StateMigrationError(
+ `the rollback would restore into ${source}${overridden}, which is not a directory. The ` +
+ `manifest at ${manifestPath} and every file it binds are untouched; point the ` +
+ "rollback at the vault's current location with `--to <dir>`",
+ );
+ }
+ return source;
+}
+
+/** The one wording for an entry this run could not read, plan or apply. */
+function unreadableRefusal(relativePath: string, path: string, reason: string): RollbackRefusal {
+ return {
+ code: ROLLBACK_REFUSAL.unreadable,
+ relative_path: relativePath,
+ path,
+ found: reason,
+ remedy:
+ "an entry this run cannot read cannot be shown to be the one the manifest binds, so it " +
+ "is left exactly as it is and the manifest is kept; make the path readable to this " +
+ "user - or move aside whatever is standing in its place - and roll back again",
+ };
+}
+
+/** The one wording for a source path something else has written. */
+function divergedRefusal(
+ relativePath: string,
+ path: string,
+ bound: string,
+ found: string,
+): RollbackRefusal {
+ return {
+ code: ROLLBACK_REFUSAL.sourceDiverged,
+ relative_path: relativePath,
+ path,
+ found: `something has written the source path since the migration (bound ${bound}, now ${found})`,
+ remedy:
+ "the newer file at the source is kept and the destination copy is left in place; " +
+ "reconcile the two by hand and remove whichever one you do not want",
+ };
+}
+
+function readManifest(manifestPath: string): MigrationManifest {
+ if (!existsSync(manifestPath)) {
+ throw new StateMigrationError(
+ `no migration manifest at ${manifestPath}; a rollback restores what a migration bound, ` +
+ "so point --from at the directory `o2b state migrate --apply` wrote to",
+ );
+ }
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+ } catch (error) {
+ throw new StateMigrationError(
+ `the migration manifest at ${manifestPath} is not readable JSON (${(error as Error).message}); ` +
+ "restore it from a backup - a rollback driven by a manifest nobody can parse would be " +
+ "a restore of something nobody measured",
+ );
+ }
+ const manifest = parsed as MigrationManifest;
+ if (manifest.schema_version !== MIGRATION_MANIFEST_SCHEMA_VERSION) {
+ throw new StateMigrationError(
+ `the migration manifest at ${manifestPath} declares schema_version ` +
+ `${String(manifest.schema_version)}; this build reads ` +
+ `${MIGRATION_MANIFEST_SCHEMA_VERSION}. Roll it back with the build that wrote it.`,
+ );
+ }
+ if (manifest.source_type !== MIGRATION_SOURCE_TYPE.vault) {
+ throw new StateMigrationError(
+ `the migration manifest at ${manifestPath} was taken from a ` +
+ `${String(manifest.source_type)}, which this build cannot restore. Roll it back with ` +
+ "the build that wrote it.",
+ );
+ }
+ if (!manifestVerifies(manifest)) {
+ throw new StateMigrationError(
+ `the migration manifest at ${manifestPath} does not match its own digest, so what it ` +
+ "binds is no longer what was measured; restore the manifest from a backup rather " +
+ "than rolling back against an edited one",
+ );
+ }
+ return manifest;
+}
+
+/** The three answers a path can give when asked for its digest. */
+const DIGEST_PROBE = Object.freeze({
+ digest: "digest",
+ absent: "absent",
+ unreadable: "unreadable",
+} as const);
+
+type DigestProbe =
+ | { readonly state: typeof DIGEST_PROBE.digest; readonly digest: string }
+ | { readonly state: typeof DIGEST_PROBE.absent }
+ | { readonly state: typeof DIGEST_PROBE.unreadable; readonly reason: string };
+
+/**
+ * What is at `path`: its digest, nothing, or a reason it could not be
+ * read - three answers rather than two.
+ *
+ * A throw here used to take the WHOLE plan with it over one entry: a
+ * single source path recreated as a directory made `planStateRollback`
+ * raise `EISDIR` and every other restorable file died with it, while
+ * {@link ROLLBACK_REFUSAL.unreadable} - the code declared for exactly
+ * this - was produced nowhere in the codebase. One unreadable entry is
+ * one refusal, like every other per-entry verdict in this module.
+ */
+function digestOf(path: string): DigestProbe {
+ try {
+ return { state: DIGEST_PROBE.digest, digest: sha256Hex(readFileSync(path)) };
+ } catch (error) {
+ const err = error as NodeJS.ErrnoException;
+ if (err.code === "ENOENT") return { state: DIGEST_PROBE.absent };
+ return {
+ state: DIGEST_PROBE.unreadable,
+ reason: `could not be read (${err.code ?? "unknown error"}): ${err.message}`,
+ };
+ }
+}
+
+export interface RollbackResult {
+ /** Vault-relative paths now back at the source. */
+ readonly restored: ReadonlyArray<string>;
+ readonly refused: ReadonlyArray<RollbackRefusal>;
+ /** True when the manifest was removed because nothing is left bound by it. */
+ readonly manifest_removed: boolean;
+}
+
+/**
+ * Put back everything the plan cleared, and nothing else.
+ *
+ * Every entry is measured AGAIN here. A plan is a statement about the
+ * moment it was made, and the moment that matters is this one: the
+ * `source_diverged` verdict was decided while the operator was still
+ * reading the plan, and a file written at the source since then used to
+ * be copied straight over. The re-check is the same refusal one
+ * confirmation later, and it joins the plan's own refusals in the result.
+ *
+ * The manifest is removed only when there is nothing left to refuse -
+ * from either half. An incomplete rollback keeps it, because the refused
+ * entries are still the only record of where those bytes came from.
+ */
+export function applyStateRollback(plan: RollbackPlan): RollbackResult {
+ const restored: string[] = [];
+ const refused: RollbackRefusal[] = [...plan.refusals];
+ for (const entry of plan.restore) {
+ const bound = plan.manifest.entries.find(
+ (candidate) => candidate.relative_path === entry.relative_path,
+ );
+ if (bound === undefined) {
+ throw new StateMigrationError(
+ `${entry.relative_path} is in this rollback plan but not in the manifest at ` +
+ `${plan.manifest_path}, so there is no digest to restore it against; nothing has ` +
+ "been done for it - plan the rollback again rather than applying a plan and a " +
+ "manifest that disagree",
+ );
+ }
+ const atSource = digestOf(entry.to);
+ if (atSource.state === DIGEST_PROBE.unreadable) {
+ refused.push(unreadableRefusal(entry.relative_path, entry.to, atSource.reason));
+ continue;
+ }
+ if (atSource.state === DIGEST_PROBE.digest && atSource.digest !== bound.digest) {
+ refused.push(divergedRefusal(entry.relative_path, entry.to, bound.digest, atSource.digest));
+ continue;
+ }
+ if (atSource.state === DIGEST_PROBE.absent) {
+ mkdirSync(dirname(entry.to), { recursive: true });
+ copyFileSync(entry.from, entry.to);
+ const digest = sha256Hex(readFileSync(entry.to));
+ if (digest !== bound.digest) {
+ throw new StateMigrationError(
+ `${entry.relative_path} did not restore intact to ${entry.to}; the destination copy ` +
+ "is still in place, so nothing is lost - investigate the source filesystem before " +
+ "rolling back again",
+ );
+ }
+ }
+ rmSync(entry.from, { force: true });
+ restored.push(entry.relative_path);
+ }
+ pruneEmptyDirectories(plan.destination, plan.manifest.canonical_roots);
+
+ const complete = refused.length === 0;
+ if (complete) rmSync(plan.manifest_path, { force: true });
+
+ return { restored, refused, manifest_removed: complete };
+}
+
+// ----- The rendering --------------------------------------------------------
+
+/**
+ * The migration plan an operator reads.
+ *
+ * The ONE place a plan becomes prose, following `renderStateInventory`
+ * and `renderDataOwnership`: the `--json` document and this sentence are
+ * two views of one value, so they cannot drift the way two hand-written
+ * reports always do.
+ */
+export function renderMigrationPlan(plan: MigrationPlan): string {
+ const lines: string[] = [
+ `State migration: ${plan.source} -> ${plan.destination}`,
+ ` ${plan.manifest.entries.length} file(s) under ` +
+ `${plan.manifest.canonical_roots.length} root(s), ${plan.manifest.total_bytes} byte(s), ` +
+ `bound by ${plan.manifest.algorithm}:${plan.manifest.digest}`,
+ ];
+ for (const root of plan.manifest.canonical_roots) {
+ const under = plan.manifest.entries.filter(
+ (entry) => entry.relative_path === root || entry.relative_path.startsWith(`${root}/`),
+ );
+ const bytes = under.reduce((sum, entry) => sum + entry.bytes, 0);
+ lines.push(` - ${root} (${under.length} file(s), ${bytes} byte(s))`);
+ }
+ if (plan.external.length > 0) {
+ lines.push("", " Left where they are, because they are not inside the vault:");
+ for (const surface of plan.external) {
+ lines.push(` - ${surface.label} β€” ${surface.path}`);
+ lines.push(` ${surface.reason}`);
+ }
+ }
+ if (plan.refusals.length > 0) {
+ lines.push("", ` REFUSED - ${plan.refusals.length} check(s) failed; nothing will move:`);
+ for (const refusal of plan.refusals) {
+ lines.push(` - ${refusal.code} at ${refusal.path}`);
+ lines.push(` found: ${refusal.found}`);
+ lines.push(` do: ${refusal.remedy}`);
+ }
+ }
+ lines.push("");
+ return lines.join("\n");
+}
+
+/** The rollback plan an operator reads. Same contract as above. */
+export function renderRollbackPlan(plan: RollbackPlan): string {
+ const lines: string[] = [
+ `State rollback: ${plan.destination} -> ${plan.source}`,
+ ` manifest ${plan.manifest_path} (taken ${plan.manifest.created_at})`,
+ ];
+ // An override is never silent: the operator is told which root the
+ // manifest recorded, so "I am restoring somewhere else" is a thing they
+ // read rather than a thing they have to remember typing.
+ if (plan.source !== plan.manifest.source_root) {
+ lines.push(
+ ` the manifest recorded ${plan.manifest.source_root}; --to overrides it, so the files ` +
+ `go to ${plan.source}`,
+ );
+ }
+ lines.push(
+ ` ${plan.restore.length} of ${plan.manifest.entries.length} bound file(s) still match ` +
+ "their recorded digest and will be restored",
+ );
+ if (plan.refusals.length > 0) {
+ lines.push(
+ "",
+ ` REFUSED - ${plan.refusals.length} file(s) are left exactly where they are and are ` +
+ "never deleted:",
+ );
+ for (const refusal of plan.refusals) {
+ lines.push(` - ${refusal.relative_path} (${refusal.code}) at ${refusal.path}`);
+ lines.push(` found: ${refusal.found}`);
+ lines.push(` do: ${refusal.remedy}`);
+ }
+ }
+ lines.push("");
+ return lines.join("\n");
+}
diff --git a/src/core/state/surfaces.ts b/src/core/state/surfaces.ts
new file mode 100644
index 00000000..1756b515
--- /dev/null
+++ b/src/core/state/surfaces.ts
@@ -0,0 +1,1181 @@
+/**
+ * Every durable state surface this tool keeps INSIDE the vault, declared
+ * once and measured on request.
+ *
+ * This is the missing half of `src/core/install/ownership.ts`. That module
+ * enumerates what can live OUTSIDE the vault and measures one thing about
+ * it - where the search index resolved. The rest of the machine's state
+ * sits inside the vault under two roots, roughly forty locations, each
+ * resolved by its own function scattered across the tree, and nothing
+ * could answer the three questions an operator actually asks before they
+ * copy, migrate or delete a vault:
+ *
+ * 1. WHERE does each surface live on this machine?
+ * 2. Is it REACHABLE - and if not, is that because nothing wrote it, or
+ * because this process could not look?
+ * 3. WHICH LAYER put it there - a default, a machine config key, or an
+ * environment variable somebody exported once?
+ *
+ * The design follows `ownership.ts` deliberately rather than starting a
+ * parallel instrument:
+ *
+ * - {@link STATE_SURFACES} is a CATALOGUE, printed whole. A row says
+ * what this build can keep at that location, never that this machine
+ * has it. Presence is the measured half.
+ * - {@link StateReachabilityVerdict} is modelled on `SearchIndexVerdict`:
+ * a tri-state carrying its own reason. `absent` and `unchecked` are
+ * separate members because "it is not there" and "I could not look"
+ * are different repairs, and an `EACCES` folded into `absent` tells an
+ * operator to create a file that is already there.
+ * - {@link inventoryStateSurfaces} produces ONE value and
+ * {@link renderStateInventory} is the only place it becomes prose, so
+ * `o2b state status` and the `vault_health` MCP field cannot drift the
+ * way two hand-written copies of a report always do.
+ *
+ * ## Why the paths are derived here rather than imported
+ *
+ * Twelve of the resolvers this file describes are module-private
+ * (`journalPath`, `leaseDbPath`, the protect manifest, the inject cache),
+ * and importing the twenty that are exported would pull the search layer,
+ * the install layer and the whole `brain/` tree into what must stay a
+ * leaf: the CLI verb and the MCP tool both reach it, and an inventory that
+ * imports its subjects is one edge away from a cycle the architecture
+ * ratchet gates. So each row DERIVES its path from the same name
+ * constants the resolvers use, and `tests/core/state/surfaces.test.ts`
+ * binds every row to its real location. A rename in `brain/paths.ts`
+ * fails that test rather than printing a path nothing writes.
+ *
+ * Two kinds of binding, because two kinds of resolver: a row whose
+ * resolver is exported is compared against it directly, and a row whose
+ * resolver is private is bound by DRIVING the module's exported writer
+ * against a temporary vault and asking whether the artifact landed at
+ * the row's own path. No row is bound by neither today; the list of
+ * deliberate exceptions is empty and its size is asserted, so a new row
+ * that binds to nothing is a decision somebody typed rather than one
+ * nobody noticed.
+ *
+ * ## What this module does not claim
+ *
+ * The `.lock` files `scanStaleLocks` finds are not rows: they are created
+ * beside whatever is being written and removed by the writer that made
+ * them, so there is no fixed location to report. The one exception is the
+ * search writer lock, which has a stable name derived from the index.
+ *
+ * `CONFIG_ORIGIN.vaultConfig` never appears in a report today. No key in
+ * `<vault>/Brain/_brain.yaml` moves a state surface, and
+ * {@link resolveWithOrigin} cannot see that tier anyway; the day one does,
+ * the caller layers it on the result exactly as `install/settings.ts`
+ * already does.
+ */
+
+import { lstatSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import {
+ BRAIN_ARTIFACTS_REL,
+ BRAIN_CAPTURES_REL,
+ BRAIN_CLAIM_GRAPH_FILE,
+ BRAIN_LOG_REL,
+ BRAIN_PROCEDURAL_MEMORY_REL,
+ BRAIN_ROLLUP_LEDGER_FILE,
+ BRAIN_ROOT_REL,
+ BRAIN_SKILL_ACCEPT_JOURNAL_REL,
+ BRAIN_SNAPSHOTS_REL,
+ BRAIN_STATE_REL,
+ DERIVED_STORE_DIR,
+ DERIVED_STORE_FILE,
+ HOOK_AUDIT_DIR,
+} from "../brain/path-constants.ts";
+import { CONFIG_ORIGIN, resolveWithOrigin, type ConfigOrigin } from "../validate.ts";
+
+// ----- Vocabularies ---------------------------------------------------------
+
+/**
+ * The id of every state surface this build keeps inside a vault.
+ *
+ * Closed, and spelled as a frozen literal map rather than read back off
+ * {@link STATE_SURFACES}, so the ids stay a UNION rather than widening to
+ * `string`. It is that union which lets a caller ask for one surface by
+ * name and be told at compile time when the name stops existing.
+ */
+export const STATE_SURFACE_ID = Object.freeze({
+ searchIndex: "search_index",
+ searchWriterLock: "search_writer_lock",
+ searchSessionFocus: "search_session_focus",
+ secretCustody: "secret_custody",
+ ingestContentManifest: "ingest_content_manifest",
+ ingestCheckpoints: "ingest_checkpoints",
+ sessionImportLedger: "session_import_ledger",
+ installManifest: "install_manifest",
+ protectManifest: "protect_manifest",
+ maintenanceLease: "maintenance_lease",
+ maintenanceJournal: "maintenance_journal",
+ hookAudit: "hook_audit",
+ hookSessionState: "hook_session_state",
+ watchdogAudit: "watchdog_audit",
+ injectFailopenCache: "inject_failopen_cache",
+ aiderContext: "aider_context_artifact",
+ brainLog: "brain_log",
+ continuityLedger: "continuity_ledger",
+ dreamRuns: "dream_runs",
+ prefAudit: "pref_audit",
+ recurrenceLedger: "recurrence_ledger",
+ queryDemandLedger: "query_demand_ledger",
+ captureDecisionLog: "capture_decision_log",
+ decisionReceipts: "decision_receipts",
+ lineageLedger: "lineage_ledger",
+ anticipatoryCache: "anticipatory_cache",
+ exactState: "exact_state",
+ searchFeedback: "search_feedback",
+ searchLearnedWeights: "search_learned_weights",
+ searchReinforce: "search_reinforce",
+ searchTuning: "search_tuning",
+ snapshots: "snapshots",
+ mcpArtifacts: "mcp_artifacts",
+ metrics: "metrics",
+ skillAcceptJournal: "skill_accept_journal",
+ claudeMemoryManifest: "claude_memory_manifest",
+ claimGraph: "claim_graph",
+ rollupLedger: "rollup_ledger",
+ proposalWatermark: "proposal_watermark",
+ captureWatermark: "capture_watermark",
+} as const);
+
+export type StateSurfaceId = (typeof STATE_SURFACE_ID)[keyof typeof STATE_SURFACE_ID];
+
+/** The declared surface ids, in catalogue order. */
+export const STATE_SURFACE_IDS: ReadonlyArray<StateSurfaceId> = Object.freeze(
+ Object.values(STATE_SURFACE_ID),
+);
+
+export function isStateSurfaceId(value: unknown): value is StateSurfaceId {
+ return typeof value === "string" && (STATE_SURFACE_IDS as ReadonlyArray<string>).includes(value);
+}
+
+/**
+ * What losing a surface costs.
+ *
+ * Two members rather than one bucket because the recovery stories are
+ * genuinely different, and the difference is the first thing an operator
+ * needs before a migration: a `derived` surface can be deleted and rebuilt
+ * from the vault, while `vault-content` is the memory itself and its loss
+ * is permanent without a backup.
+ *
+ * It is a RECOVERY story, not a location. `Brain/.state/anticipatory/` is
+ * inside the Markdown tree and is still `derived`, because deleting it
+ * costs a recomputation and nothing else; the search index is outside that
+ * tree and is `derived` for the same reason. Whether a surface can hold
+ * memory CONTENT is the separate {@link StateSurface.carries_memory} axis,
+ * as it is in `ownership.ts`.
+ */
+export const STATE_TIER = Object.freeze({
+ derived: "derived",
+ vaultContent: "vault-content",
+} as const);
+
+export type StateTier = (typeof STATE_TIER)[keyof typeof STATE_TIER];
+
+/** The tiers, most-recoverable first. */
+export const STATE_TIERS: ReadonlyArray<StateTier> = Object.freeze([
+ STATE_TIER.derived,
+ STATE_TIER.vaultContent,
+]);
+
+export function isStateTier(value: unknown): value is StateTier {
+ return typeof value === "string" && (STATE_TIERS as ReadonlyArray<string>).includes(value);
+}
+
+/**
+ * What this run could establish about one surface.
+ *
+ * Modelled on `SearchIndexVerdict`, and for the same reason: a boolean
+ * would have to spell "I could not look" as `false`, which reads as "it is
+ * not there" at every call site and sends the operator to create something
+ * that already exists under a mode they cannot read.
+ */
+export const STATE_REACHABILITY = Object.freeze({
+ present: "present",
+ absent: "absent",
+ unchecked: "unchecked",
+} as const);
+
+export type StateReachability = (typeof STATE_REACHABILITY)[keyof typeof STATE_REACHABILITY];
+
+/** The reachability states, in the order the summary counts them. */
+export const STATE_REACHABILITIES: ReadonlyArray<StateReachability> = Object.freeze([
+ STATE_REACHABILITY.present,
+ STATE_REACHABILITY.absent,
+ STATE_REACHABILITY.unchecked,
+]);
+
+export function isStateReachability(value: unknown): value is StateReachability {
+ return (
+ typeof value === "string" && (STATE_REACHABILITIES as ReadonlyArray<string>).includes(value)
+ );
+}
+
+// ----- The enumeration ------------------------------------------------------
+
+/** One durable location this tool keeps inside a vault. */
+export interface StateSurface {
+ readonly id: StateSurfaceId;
+ /** What it is, as a noun phrase the statement can print. */
+ readonly label: string;
+ readonly tier: StateTier;
+ /**
+ * The location, as a pure function of the vault and the resolved
+ * override value. Reads nothing; the second argument is `null` when no
+ * layer supplied one, exactly as `resolveIndexPath` takes it.
+ */
+ readonly derive: (vault: string, override: string | null) => string;
+ /** The environment variable that MOVES it, or null when nothing can. */
+ readonly override_env: string | null;
+ /** The machine-config key that MOVES it, or null when nothing can. */
+ readonly override_config_key: string | null;
+ /** True when this location can hold memory CONTENT rather than plumbing. */
+ readonly carries_memory: boolean;
+ /** What it holds, and what its absence or loss costs. */
+ readonly reason: string;
+ /**
+ * Repo-relative modules that own this path. A trailing `/` names the
+ * modules DIRECTLY IN that directory and not the tree beneath it -
+ * unbounded, one such entry would answer for every module under it.
+ * `tests/core/architecture/state-surface-census.test.ts` attributes
+ * swept path builders through this field, so an anchor that rots fails
+ * a test rather than silently orphaning a location.
+ */
+ readonly sources: ReadonlyArray<string>;
+}
+
+// Names the resolvers spell privately. Declared here so the derivations
+// below are pure joins; the binding test compares each against the real
+// resolver, which is what keeps a copied literal from drifting.
+const SEARCH_FOCUS_DIR = "search-focus";
+const WRITER_LOCK_SUFFIX = ".lock";
+const SECRETS_DIR = "secrets";
+const INGEST_MANIFEST_FILE = "ingest-manifest.json";
+const INGEST_CHECKPOINT_DIR = "ingest-checkpoints";
+const SESSION_LEDGER_FILE = "session-import-ledger.json";
+const INSTALL_MANIFEST_FILE = "install.lock.json";
+const PROTECT_MANIFEST_FILE = "protect.lock.json";
+const MAINTENANCE_LEASE_FILE = "maintenance.sqlite";
+const MAINTENANCE_JOURNAL_FILE = "maintenance-runs.jsonl";
+const HOOK_STATE_DIR = "hook-state";
+const WATCHDOG_AUDIT_DIR = "watchdog-audit";
+const INJECT_CACHE_DIR = "inject-cache";
+const AIDER_CONTEXT_FILE = "aider-context.md";
+const DREAM_RUNS_DIR = "dream-runs";
+const PREF_AUDIT_DIR = "pref-audit";
+const CONTINUITY_DIR = "continuity";
+const RECURRENCE_FILE = "recurrence-support.jsonl";
+const QUERY_DEMAND_FILE = "query-demand.jsonl";
+const CAPTURE_DECISIONS_FILE = "capture-decisions.jsonl";
+const CAPTURE_WATERMARK_FILE = ".catchup-watermark.json";
+const PROPOSAL_WATERMARK_FILE = "proposal-watermark.json";
+const TRUTH_DIR = "truth";
+const BRAIN_INTERNAL_STATE_DIR = ".state";
+const LINEAGE_LEDGER_FILE = "session-lineage.jsonl";
+const ANTICIPATORY_DIR = "anticipatory";
+const SEARCH_STATE_DIR = "search";
+const SEARCH_FEEDBACK_DIR = "feedback";
+const SEARCH_LEARNED_WEIGHTS_FILE = "learned-weights.json";
+const SEARCH_REINFORCE_DIR = "reinforce";
+const SEARCH_TUNING_FILE = "tuning.json";
+const METRICS_DIR = "metrics";
+const IMPORTS_DIR = ".imports";
+const CLAUDE_MEMORY_MANIFEST_FILE = "claude-memory.json";
+
+/** Environment variable and config key that move the search store. */
+const SEARCH_DB_ENV = "OPEN_SECOND_BRAIN_SEARCH_DB";
+const SEARCH_DB_CONFIG_KEY = "search_db_path";
+
+/**
+ * Environment variable and config key that select this device's log
+ * shard. They do not move a directory; they choose which FILE inside one
+ * this machine appends to, which is the same question for an operator
+ * looking for their own writes.
+ */
+const DEVICE_ID_ENV = "O2B_DEVICE_ID";
+const DEVICE_ID_CONFIG_KEY = "device_id";
+
+/** The default search store, before any override. */
+const defaultIndexPath = (vault: string): string =>
+ join(vault, DERIVED_STORE_DIR, DERIVED_STORE_FILE);
+
+/** The resolved search store: the override when there is one. */
+function indexPath(vault: string, override: string | null): string {
+ if (override !== null) {
+ const trimmed = override.trim();
+ if (trimmed !== "") return trimmed;
+ }
+ return defaultIndexPath(vault);
+}
+
+/** A location under `<vault>/.open-second-brain/`. */
+const derivedStore =
+ (...parts: ReadonlyArray<string>) =>
+ (vault: string): string =>
+ join(vault, DERIVED_STORE_DIR, ...parts);
+
+/** A location under `<vault>/Brain/`. */
+const brainTree =
+ (...parts: ReadonlyArray<string>) =>
+ (vault: string): string =>
+ join(vault, BRAIN_ROOT_REL, ...parts);
+
+/** A location under `<vault>/Brain/log/`. */
+const brainLog =
+ (...parts: ReadonlyArray<string>) =>
+ (vault: string): string =>
+ join(vault, BRAIN_LOG_REL, ...parts);
+
+/**
+ * Every durable location this tool keeps inside a vault.
+ *
+ * Ordered by root - the derived store first, then the Markdown tree -
+ * because that is the order a migration touches them and the order the
+ * rendering groups them in.
+ */
+export const STATE_SURFACES: ReadonlyArray<StateSurface> = Object.freeze([
+ {
+ id: STATE_SURFACE_ID.searchIndex,
+ label: "search index",
+ tier: STATE_TIER.derived,
+ derive: indexPath,
+ override_env: SEARCH_DB_ENV,
+ override_config_key: SEARCH_DB_CONFIG_KEY,
+ carries_memory: true,
+ reason:
+ "The SQLite store holding a copy of every indexed chunk, plus the query cache table. " +
+ "Rebuildable with `o2b search index`, so nothing is lost by deleting it - but the " +
+ "override can put that copy of your vault text anywhere on the machine.",
+ sources: ["src/core/search/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.searchWriterLock,
+ label: "search writer lock",
+ tier: STATE_TIER.derived,
+ derive: (vault, override) => `${indexPath(vault, override)}${WRITER_LOCK_SUFFIX}`,
+ override_env: SEARCH_DB_ENV,
+ override_config_key: SEARCH_DB_CONFIG_KEY,
+ carries_memory: false,
+ reason:
+ "Held for the duration of an index write and taken over after sixty seconds of silence, " +
+ "so a killed writer never wedges the index. It follows the store, because a lock beside " +
+ "a database nobody opens guards nothing.",
+ sources: ["src/core/search/store/writer-lock.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.searchSessionFocus,
+ label: "per-session search focus",
+ tier: STATE_TIER.derived,
+ derive: (vault, override) => join(dirname(indexPath(vault, override)), SEARCH_FOCUS_DIR),
+ override_env: SEARCH_DB_ENV,
+ override_config_key: SEARCH_DB_CONFIG_KEY,
+ carries_memory: false,
+ reason:
+ "One JSON file per session scope pinning a standing query and path prefix, so concurrent " +
+ "sessions never clobber each other's focus. Each entry expires on its own; deleting the " +
+ "directory only clears whatever focus is currently set.",
+ sources: ["src/core/search/session-focus.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.secretCustody,
+ label: "encrypted secret custody",
+ tier: STATE_TIER.vaultContent,
+ derive: derivedStore(SECRETS_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "The encrypted secret store and the keyfile that opens it. Nothing rebuilds this: a vault " +
+ "copied without it keeps every memory and loses every secret reference the config resolves " +
+ "through it.",
+ sources: ["src/core/brain/secrets/store.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.ingestContentManifest,
+ label: "ingest content manifest",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(INGEST_MANIFEST_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "Per-path content digests deciding what an ingest run treats as new, modified, unchanged " +
+ "or missing. Deleting it makes the next run re-ingest everything it can still see.",
+ sources: ["src/core/brain/ingest/content-manifest.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.ingestCheckpoints,
+ label: "ingest checkpoints",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(INGEST_CHECKPOINT_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "One resume point per ingest plan, so an interrupted batch continues rather than restarts. " +
+ "`OSB_INGEST_NO_CHECKPOINT` suppresses writing them; it does not move them.",
+ sources: ["src/core/brain/ingest/checkpoint.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.sessionImportLedger,
+ label: "session import ledger",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(SESSION_LEDGER_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "One content digest per agent session log this vault has imported, keyed by its absolute " +
+ "path on this machine, so `o2b brain import-session --status` can say what was found and " +
+ "what is outstanding without re-parsing anything. Deleting it reports every already- " +
+ "imported log as a gap; re-importing them is safe but pays the full parse again.",
+ sources: ["src/core/brain/sessions/discover.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.installManifest,
+ label: "install manifest",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(INSTALL_MANIFEST_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "What each install target wrote and where, so `o2b uninstall --target` removes exactly " +
+ "that. Losing it does not break an install; it makes the uninstall unable to prove what " +
+ "belongs to this tool.",
+ sources: ["src/core/install/manifest.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.protectManifest,
+ label: "protect manifest",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(PROTECT_MANIFEST_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "The managed instruction fences `o2b brain protect` owns, per target. Same shape as the " +
+ "install manifest and the same cost: without it `brain unprotect` cannot tell a fence it " +
+ "wrote from one an operator typed.",
+ sources: ["src/core/brain/protect.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.maintenanceLease,
+ label: "maintenance lease database",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(MAINTENANCE_LEASE_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "A second SQLite file holding the lease that keeps two maintenance runs off the same vault. " +
+ "Deleting it while a run is live removes that guarantee for the length of that run.",
+ sources: ["src/core/brain/maintenance/lease.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.maintenanceJournal,
+ label: "maintenance journal",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(MAINTENANCE_JOURNAL_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "The last few hundred maintenance verdicts, capped and rolled. It is the only record of " +
+ "why a lane skipped, so deleting it costs the explanation rather than the work.",
+ sources: ["src/core/brain/maintenance/journal.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.hookAudit,
+ label: "hook audit trail",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(HOOK_AUDIT_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "One line per hook decision, sharded by ISO week. It is what the doctor check asking " +
+ "whether an enabled hook ever ran actually reads, so an empty directory is a real answer " +
+ "rather than a missing file.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.hookSessionState,
+ label: "per-session hook state",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(HOOK_STATE_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "One JSON file per session scope recording what a hook has already done this session. It " +
+ "is scoped to a session by construction, so deleting it re-runs at most one session's " +
+ "worth of once-per-session work.",
+ sources: ["hooks/lib/session-state.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.watchdogAudit,
+ label: "watchdog audit fallback",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(WATCHDOG_AUDIT_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "Where a watchdog record lands when its configured audit directory refuses the write. It " +
+ "exists precisely so a failed audit is still audited; its presence is a signal that the " +
+ "primary location could not be written.",
+ sources: ["src/core/brain/watchdog.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.injectFailopenCache,
+ label: "injection fail-open cache",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(INJECT_CACHE_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "The last body each session-start injection successfully rendered, replayed when a live " +
+ "render fails. It is a copy of injected vault text, so it holds memory content even " +
+ "though nothing is lost by deleting it.",
+ sources: ["src/core/brain/inject-failopen.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.aiderContext,
+ label: "Aider context sidecar",
+ tier: STATE_TIER.derived,
+ derive: derivedStore(AIDER_CONTEXT_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "The Markdown context file the Aider wrapper regenerates before each session and hands to " +
+ "the editor. It is a rendered copy of vault text and is rewritten on the next run.",
+ sources: ["src/core/install/adapters/aider-wrapper.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.brainLog,
+ label: "Brain event log",
+ tier: STATE_TIER.vaultContent,
+ derive: (vault) => join(vault, BRAIN_LOG_REL),
+ override_env: DEVICE_ID_ENV,
+ override_config_key: DEVICE_ID_CONFIG_KEY,
+ carries_memory: true,
+ reason:
+ "The append-only record of everything the agents observed, one page and one JSONL shard " +
+ "per day, sharded again per device so two machines syncing one vault never write the same " +
+ "file. The device id selects THIS machine's shard; it is memory, and it does not rebuild.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.continuityLedger,
+ label: "continuity ledger",
+ tier: STATE_TIER.vaultContent,
+ derive: brainLog(CONTINUITY_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "One JSONL shard per month recording session handovers, so a new session can pick up what " +
+ "the previous one left unfinished. Nothing recomputes a handover that was never written.",
+ sources: ["src/core/brain/continuity/store.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.dreamRuns,
+ label: "dream workrun checkpoints",
+ tier: STATE_TIER.vaultContent,
+ derive: brainLog(DREAM_RUNS_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "One durable JSONL per dream invocation, so an interrupted pass resumes at the step it " +
+ "reached. Under the log directory on purpose: a backup that covers the log covers these.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.prefAudit,
+ label: "preference mutation audit",
+ tier: STATE_TIER.vaultContent,
+ derive: brainLog(PREF_AUDIT_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "One append-only JSONL per preference recording every promotion, edit and retirement. It " +
+ "is the provenance behind a rule the agents follow, and it cannot be reconstructed from " +
+ "the preference file it describes.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.recurrenceLedger,
+ label: "procedural recurrence ledger",
+ tier: STATE_TIER.vaultContent,
+ derive: brainLog(RECURRENCE_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "Support counts for candidate procedures: how often a sequence recurred before it was " +
+ "worth proposing. Deleting it resets the evidence, and the counts only accrue again as " +
+ "the work happens again.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.queryDemandLedger,
+ label: "query demand ledger",
+ tier: STATE_TIER.vaultContent,
+ derive: brainLog(QUERY_DEMAND_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "A byte-capped rolling log of recall queries with their coverage, aggregated to surface " +
+ "what the vault answers poorly. It carries the queries themselves, which are memory " +
+ "content by any reading.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.captureDecisionLog,
+ label: "inbound capture decision log",
+ tier: STATE_TIER.vaultContent,
+ derive: brainLog(CAPTURE_DECISIONS_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "One line per inbound update the capture bot handled - accepted, rejected or malformed - " +
+ "so no update is ever silently dropped. It is the only place a rejected capture is " +
+ "recorded at all.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.decisionReceipts,
+ label: "decision receipts",
+ tier: STATE_TIER.vaultContent,
+ derive: brainTree(TRUTH_DIR),
+ override_env: DEVICE_ID_ENV,
+ override_config_key: DEVICE_ID_CONFIG_KEY,
+ carries_memory: true,
+ reason:
+ "Per-device JSONL shards recording every change to a decision, beside the truth ledger " +
+ "they belong to. The device id names this machine's shard, and the resolver refuses " +
+ "rather than falling back when it cannot be read.",
+ sources: ["src/core/brain/decisions/receipts.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.lineageLedger,
+ label: "session lineage ledger",
+ tier: STATE_TIER.vaultContent,
+ derive: brainTree(BRAIN_INTERNAL_STATE_DIR, LINEAGE_LEDGER_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "Which session followed which, plus a companion gap file naming the observations that " +
+ "never reached it. It is how a broken chain is detectable at all, so deleting it hides " +
+ "gaps rather than closing them.",
+ sources: ["src/core/brain/lineage/ledger.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.anticipatoryCache,
+ label: "anticipatory context cache",
+ tier: STATE_TIER.derived,
+ derive: brainTree(BRAIN_INTERNAL_STATE_DIR, ANTICIPATORY_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "Pre-rendered context packs keyed by root and agent scope. Inside the Markdown tree and " +
+ "still derived: deleting it costs one recomputation, and every byte in it came from the " +
+ "vault it sits in.",
+ sources: ["src/core/brain/anticipatory-cache.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.exactState,
+ label: "exact-state lane",
+ tier: STATE_TIER.vaultContent,
+ derive: (vault) => join(vault, BRAIN_STATE_REL),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "Overwrite-only pages holding the current value of one aspect each, where the newest write " +
+ "is the whole truth. There is no history behind them, so a lost page is a lost fact.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.searchFeedback,
+ label: "search feedback events",
+ tier: STATE_TIER.vaultContent,
+ derive: brainTree(SEARCH_STATE_DIR, SEARCH_FEEDBACK_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "Which results an agent actually used, recorded per query. It is the observation the " +
+ "learned weights are computed FROM, so it is the half of the pair that cannot be " +
+ "regenerated.",
+ sources: ["src/core/search/feedback.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.searchLearnedWeights,
+ label: "learned ranking weights",
+ tier: STATE_TIER.derived,
+ derive: brainTree(SEARCH_STATE_DIR, SEARCH_LEARNED_WEIGHTS_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "Four multipliers folded out of the feedback events. Deleting it returns ranking to the " +
+ "neutral weights and the next feedback pass recomputes it.",
+ sources: ["src/core/search/feedback.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.searchReinforce,
+ label: "search reinforcement events",
+ tier: STATE_TIER.vaultContent,
+ derive: brainTree(SEARCH_STATE_DIR, SEARCH_REINFORCE_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "Which vault paths were reinforced by use, per event. Like the feedback lane it is an " +
+ "observation of what happened, and nothing replays the sessions that produced it.",
+ sources: ["src/core/search/reinforce.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.searchTuning,
+ label: "tuned search parameters",
+ tier: STATE_TIER.derived,
+ derive: brainTree(SEARCH_STATE_DIR, SEARCH_TUNING_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "The parameter point the self-tuning pass selected, re-validated against its grid on every " +
+ "read. Deleting it returns search to the shipped defaults until the next tuning run.",
+ sources: ["src/core/search/tuning-store.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.snapshots,
+ label: "pre-dream snapshots",
+ tier: STATE_TIER.vaultContent,
+ derive: (vault) => join(vault, BRAIN_SNAPSHOTS_REL),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "Archives of the Markdown tree taken before a destructive pass, and the only thing a " +
+ "rollback restores from. They ARE vault content, copied: deleting them removes the " +
+ "recovery point, not the current vault.",
+ sources: ["src/core/brain/paths.ts", "src/core/brain/snapshot.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.mcpArtifacts,
+ label: "MCP overflow artifacts",
+ tier: STATE_TIER.derived,
+ derive: (vault) => join(vault, BRAIN_ARTIFACTS_REL),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: true,
+ reason:
+ "Full payloads of tool results too large for one response, fetched back by artifact id. " +
+ "They are copies of what a tool already computed, so deleting them costs a re-run and " +
+ "invalidates any id already handed out.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.metrics,
+ label: "per-surface metrics",
+ tier: STATE_TIER.vaultContent,
+ derive: brainTree(METRICS_DIR),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "One append-only JSONL per instrumented surface, timestamped per run. They are " +
+ "observations of runs that already finished, so nothing regenerates them.",
+ sources: ["src/core/brain/metrics.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.skillAcceptJournal,
+ label: "skill proposal accept journal",
+ tier: STATE_TIER.vaultContent,
+ derive: (vault) => join(vault, BRAIN_SKILL_ACCEPT_JOURNAL_REL),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "What happened to each skill proposal after review, beside the pending, accepted and " +
+ "rejected directories it describes. It is the record of a human decision and has no other " +
+ "source.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.claudeMemoryManifest,
+ label: "Claude memory import manifest",
+ tier: STATE_TIER.derived,
+ derive: brainTree(IMPORTS_DIR, CLAUDE_MEMORY_MANIFEST_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "Content digests of everything already imported from the host runtime's own memory " +
+ "directory, so an unchanged file is skipped. Deleting it makes the next import re-read " +
+ "and re-write what it already has.",
+ sources: ["src/core/brain/claude-memory-manifest.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.claimGraph,
+ label: "claim graph projection",
+ tier: STATE_TIER.derived,
+ derive: brainTree(BRAIN_CLAIM_GRAPH_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "A projection of the claims asserted across the vault's pages, persisted so belief queries " +
+ "do not re-walk the tree. It is recomputed from those pages, which are the source of truth.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.rollupLedger,
+ label: "rollup ladder ledger",
+ tier: STATE_TIER.vaultContent,
+ derive: brainTree(BRAIN_ROLLUP_LEDGER_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "The counters deciding when accumulated material is consolidated one rung up the ladder. " +
+ "They accrue with the work rather than from it, so a reset delays consolidation instead of " +
+ "recomputing it.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.proposalWatermark,
+ label: "proposal scan watermark",
+ tier: STATE_TIER.derived,
+ derive: (vault) => join(vault, BRAIN_PROCEDURAL_MEMORY_REL, PROPOSAL_WATERMARK_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "How far the procedural proposal scan has read. Deleting it makes the next scan re-read " +
+ "from the beginning, which costs time and re-proposes nothing already accepted.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+ {
+ id: STATE_SURFACE_ID.captureWatermark,
+ label: "capture catchup watermark",
+ tier: STATE_TIER.derived,
+ derive: (vault) => join(vault, BRAIN_CAPTURES_REL, CAPTURE_WATERMARK_FILE),
+ override_env: null,
+ override_config_key: null,
+ carries_memory: false,
+ reason:
+ "The id of the last capture a `/catchup` reply acknowledged. A dot-file so the vault " +
+ "walker never indexes it; deleting it replays the acknowledgement, not the captures.",
+ sources: ["src/core/brain/paths.ts"],
+ },
+]);
+
+/**
+ * Modules the derived-store sweep finds that leave no surface behind,
+ * each with the reason it is not a place an operator will ever find state.
+ *
+ * The sweep enrols every module under `src/` that NAMES the derived-store
+ * directory, so this map is wider than a write-call rule would be and
+ * covers three shapes: a module that declares the name, a module that
+ * names it only to REFUSE to descend into it, and a module whose path
+ * under it is rooted somewhere other than a vault. Anything an operator
+ * could still discover inside their vault afterwards belongs in
+ * {@link STATE_SURFACES} instead, no matter how small.
+ */
+export const STATE_SURFACE_SWEEP_EXCLUSIONS: ReadonlyMap<string, string> = new Map([
+ [
+ "src/core/brain/path-constants.ts",
+ "it DECLARES the directory name and every other vault-relative name in this project. It " +
+ "builds no path at all - each constant is a name, and the resolvers that join them are " +
+ "the modules attributed above",
+ ],
+ [
+ "src/core/state/surfaces.ts",
+ "this module IS the enumeration: the store-directory joins in it are the derivations the " +
+ "inventory reports, and it creates nothing - it takes the vault, the environment and the " +
+ "config as parameters and returns a value",
+ ],
+ [
+ "src/core/brain/sync-lockfile.ts",
+ "it names the store directory only as one of the two roots `scanStaleLocks` WALKS looking " +
+ "for abandoned `.lock` files. The locks it finds are created beside whatever is being " +
+ "written and removed by the writer that made them, so there is no fixed location for a " +
+ "row to name; this module adds none of its own",
+ ],
+ [
+ "src/core/graph/mcp-config.ts",
+ "the directory appears in `SKIP_DIRS`, a REFUSAL list: config discovery matches candidate " +
+ "directories against it so the derived store is never descended into. A module that " +
+ "declines to read a directory creates nothing in it",
+ ],
+ [
+ "src/core/vault-scope/defaults.ts",
+ "same shape as the discovery skip list: the directory is a member of " +
+ "`DEFAULT_VAULT_IGNORE_PATHS`, so the vault walker never indexes derived state as though " +
+ "it were a note. It builds no path and writes nothing anywhere",
+ ],
+ [
+ "src/core/brain/temporal/weekly-brief.ts",
+ "the directory is a member of its `SKIPPED_DIR_NAMES` set, beside `.git` and `node_modules`, " +
+ "so the weekly walk does not read derived state as vault content. A skipped directory is " +
+ "not a surface this module owns",
+ ],
+ [
+ "src/cli/brain/verbs/bench.ts",
+ "its `.open-second-brain/bench-runs` default is resolved against the WORKING DIRECTORY, not " +
+ "against a vault, so it is not an in-vault surface at all. It is already enumerated as the " +
+ "`bench_run_artifacts` row of `OUT_OF_VAULT_STATE`, which is the population that owns " +
+ "locations outside the vault",
+ ],
+]);
+
+// ----- The measured half ----------------------------------------------------
+
+/** What this run established about one surface. */
+export interface StateReachabilityVerdict {
+ readonly state: StateReachability;
+ /** The resolved path the probe was run against. Never null. */
+ readonly path: string;
+ /** Why it is not present; null exactly when the state is `present`. */
+ readonly reason: string | null;
+}
+
+/** One catalogue row plus everything this run measured about it. */
+export interface StateSurfaceReport {
+ readonly id: StateSurfaceId;
+ readonly label: string;
+ readonly tier: StateTier;
+ /** Where it resolved on this machine, after any override. */
+ readonly path: string;
+ readonly override_env: string | null;
+ readonly override_config_key: string | null;
+ readonly carries_memory: boolean;
+ readonly reason: string;
+ readonly reachability: StateReachabilityVerdict;
+ /** Which configuration layer produced {@link path}. */
+ readonly origin: ConfigOrigin;
+}
+
+/** The machine-readable half, and the only input {@link renderStateInventory} takes. */
+export interface StateInventory {
+ readonly vault: string;
+ readonly surfaces: ReadonlyArray<StateSurfaceReport>;
+ /** One count per {@link STATE_REACHABILITIES} member, in that order. */
+ readonly summary: Readonly<Record<StateReachability, number>>;
+}
+
+/** What a probe reports about one path. `undefined` means "not there". */
+export interface StatLike {
+ readonly isDirectory: () => boolean;
+}
+
+export interface StateInventoryInput {
+ /** The vault as the canonical resolver answered it, never a raw config key. */
+ readonly vault: string;
+ /** The environment the overrides are read from. */
+ readonly env: NodeJS.ProcessEnv;
+ /** The machine config the overrides are read from. */
+ readonly config: Readonly<Record<string, string>>;
+ /**
+ * The filesystem probe. Injected only by tests, which need an `EACCES`
+ * they cannot reliably produce as the user running them; every caller
+ * in the product uses the default, so the classification below is the
+ * one the product runs.
+ */
+ readonly statAt?: (path: string) => StatLike | undefined;
+}
+
+/**
+ * The default probe: `undefined` for a missing path, a throw for anything
+ * else.
+ *
+ * The `lstat` fallback is not a detail. `statSync` FOLLOWS a symlink and
+ * reports a missing target as ENOENT, so a surface whose root is a
+ * dangling link answered `absent` - and `state migrate`, which only walks
+ * what is present, skipped it in silence and never reached the `symlink`
+ * refusal that knows what to tell the operator about a link. Something IS
+ * at that path; saying so is what carries it to the check that can
+ * explain it.
+ */
+function statOrAbsent(path: string): StatLike | undefined {
+ return statSync(path, { throwIfNoEntry: false }) ?? lstatSync(path, { throwIfNoEntry: false });
+}
+
+/** What an absent surface says. Absent is a state, not a failure. */
+const ABSENT_REASON = "nothing has created it in this vault yet";
+
+function probe(
+ path: string,
+ statAt: (path: string) => StatLike | undefined,
+): StateReachabilityVerdict {
+ try {
+ const stat = statAt(path);
+ if (stat === undefined) {
+ return { state: STATE_REACHABILITY.absent, path, reason: ABSENT_REASON };
+ }
+ return { state: STATE_REACHABILITY.present, path, reason: null };
+ } catch (error) {
+ // The one branch the tri-state exists for. An EACCES on the parent
+ // directory, an ELOOP, an EIO from a dying disk: none of them is
+ // evidence that the surface is missing, and reporting them as
+ // `absent` sends an operator to recreate what is already there.
+ const err = error as NodeJS.ErrnoException;
+ const code = err.code ?? "unknown error";
+ return {
+ state: STATE_REACHABILITY.unchecked,
+ path,
+ reason: `could not be probed (${code}): ${err.message ?? String(error)}`,
+ };
+ }
+}
+
+/**
+ * Measure every {@link STATE_SURFACES} row against one vault.
+ *
+ * One row per declared surface, in catalogue order, always - a surface
+ * that could not be probed is reported with an `unchecked` verdict rather
+ * than dropped, because a shorter list is the one failure mode an
+ * inventory must never have.
+ */
+export function inventoryStateSurfaces(input: StateInventoryInput): StateInventory {
+ const statAt = input.statAt ?? statOrAbsent;
+ const surfaces = STATE_SURFACES.map((surface): StateSurfaceReport => {
+ const resolved =
+ surface.override_env === null || surface.override_config_key === null
+ ? { value: null, origin: CONFIG_ORIGIN.default }
+ : resolveWithOrigin(
+ input.env,
+ input.config,
+ surface.override_env,
+ surface.override_config_key,
+ );
+ const path = surface.derive(input.vault, movesPath(surface) ? resolved.value : null);
+ return {
+ id: surface.id,
+ label: surface.label,
+ tier: surface.tier,
+ path,
+ override_env: surface.override_env,
+ override_config_key: surface.override_config_key,
+ carries_memory: surface.carries_memory,
+ reason: surface.reason,
+ reachability: probe(path, statAt),
+ origin: resolved.origin,
+ };
+ });
+ const summary = Object.fromEntries(
+ STATE_REACHABILITIES.map((state) => [
+ state,
+ surfaces.filter((s) => s.reachability.state === state).length,
+ ]),
+ ) as Record<StateReachability, number>;
+ return { vault: input.vault, surfaces, summary: Object.freeze(summary) };
+}
+
+/**
+ * Whether the override value is a PATH the derivation should use.
+ *
+ * The device-id override selects a shard filename inside a directory this
+ * inventory reports at directory granularity, so feeding it to the
+ * derivation would build `<vault>/Brain/<device-id>`. The origin is still
+ * reported, because "your log shard is named by an environment variable"
+ * is exactly the provenance an operator looking for their own writes
+ * needs; only the path substitution is withheld.
+ */
+function movesPath(surface: StateSurface): boolean {
+ return surface.override_env !== DEVICE_ID_ENV;
+}
+
+// ----- The rendering --------------------------------------------------------
+
+/** What one tier heading says about the recovery story below it. */
+function tierHeading(tier: StateTier): string {
+ switch (tier) {
+ case STATE_TIER.derived:
+ return "derived state - rebuildable from the vault, so deleting it costs time and not memory";
+ case STATE_TIER.vaultContent:
+ return "vault content - the memory itself, so a loss here is permanent without a backup";
+ }
+}
+
+/** What one reachability verdict says, with no arm that can read as another. */
+function reachabilityLine(verdict: StateReachabilityVerdict): string {
+ switch (verdict.state) {
+ case STATE_REACHABILITY.present:
+ return "present";
+ case STATE_REACHABILITY.absent:
+ return `absent - ${verdict.reason}`;
+ case STATE_REACHABILITY.unchecked:
+ return `NOT CHECKED - ${verdict.reason}`;
+ }
+}
+
+/** What one row says about the layer that placed it. */
+function originLine(report: StateSurfaceReport): string {
+ switch (report.origin) {
+ case CONFIG_ORIGIN.env:
+ return `placed by the environment (${report.override_env})`;
+ case CONFIG_ORIGIN.userConfig:
+ return `placed by the machine config (${report.override_config_key})`;
+ case CONFIG_ORIGIN.vaultConfig:
+ return `placed by the vault config (${report.override_config_key})`;
+ case CONFIG_ORIGIN.default:
+ return report.override_env === null
+ ? "at its only location - nothing can move it"
+ : `at its default location (${report.override_env} / ${report.override_config_key} would move it)`;
+ }
+}
+
+/**
+ * Render the inventory an operator reads.
+ *
+ * The ONE place the structured value becomes prose, following
+ * `renderDataOwnership`: the `vault_health` field and the sentence a
+ * person reads are two views of one record rather than two hand-written
+ * copies, which is how the install verb's JSON and human outputs drifted
+ * before anything tested either.
+ */
+export function renderStateInventory(inventory: StateInventory): string {
+ const carriers = inventory.surfaces.filter((s) => s.carries_memory).length;
+ const lines: string[] = [
+ `State surfaces in ${inventory.vault}:`,
+ ` ${inventory.surfaces.length} declared - ` +
+ `${inventory.summary[STATE_REACHABILITY.present]} present, ` +
+ `${inventory.summary[STATE_REACHABILITY.absent]} absent, ` +
+ `${inventory.summary[STATE_REACHABILITY.unchecked]} not checked. ` +
+ `${carriers} of them can hold memory content rather than plumbing.`,
+ ];
+ for (const tier of STATE_TIERS) {
+ const rows = inventory.surfaces.filter((s) => s.tier === tier);
+ if (rows.length === 0) continue;
+ lines.push("", ` ${tierHeading(tier)}:`);
+ for (const row of rows) {
+ lines.push(` - ${row.label} β€” ${row.path}`);
+ lines.push(` ${reachabilityLine(row.reachability)}; ${originLine(row)}`);
+ lines.push(` ${row.reason}`);
+ }
+ }
+ lines.push(
+ "",
+ " This is the catalogue of what this build keeps INSIDE a vault, measured against this one. " +
+ "What it can leave outside the vault is a separate question, answered by the ownership " +
+ "statement `o2b install --target <t> --apply` prints.",
+ "",
+ );
+ return lines.join("\n");
+}
diff --git a/src/core/validate.ts b/src/core/validate.ts
index d4de0d88..434ad677 100644
--- a/src/core/validate.ts
+++ b/src/core/validate.ts
@@ -93,9 +93,83 @@ export function parseBool(raw: string | null, default_: boolean, fieldName: stri
throw new Error(`${fieldName} must be 'true' or 'false', got '${raw}'`);
}
+/**
+ * The configuration layers a resolved value can come from, highest
+ * precedence first.
+ *
+ * Four members rather than three because a vault carries a COMMITTED
+ * configuration of its own (`<vault>/Brain/_brain.yaml`) that travels
+ * with the vault, next to the machine-local `config.yaml` that does not.
+ * Collapsing the two into one "config" answer would make the only
+ * interesting provenance question - "did this value come from something
+ * my teammate also has?" - unanswerable.
+ *
+ * `default` is a layer, not the absence of one: a caller that reports
+ * where a value came from must be able to say "nothing configured it"
+ * without inventing a null case at every call site.
+ */
+export const CONFIG_ORIGIN = Object.freeze({
+ env: "env",
+ userConfig: "user-config",
+ vaultConfig: "vault-config",
+ default: "default",
+} as const);
+
+export type ConfigOrigin = (typeof CONFIG_ORIGIN)[keyof typeof CONFIG_ORIGIN];
+
+/** The layers, in precedence order (highest first). */
+export const CONFIG_ORIGINS: ReadonlyArray<ConfigOrigin> = Object.freeze([
+ CONFIG_ORIGIN.env,
+ CONFIG_ORIGIN.vaultConfig,
+ CONFIG_ORIGIN.userConfig,
+ CONFIG_ORIGIN.default,
+]);
+
+export function isConfigOrigin(value: unknown): value is ConfigOrigin {
+ return typeof value === "string" && (CONFIG_ORIGINS as ReadonlyArray<string>).includes(value);
+}
+
+/** A resolved configuration value together with the layer that produced it. */
+export interface ResolvedConfigValue {
+ /** `null` when no layer supplied a non-empty value. */
+ readonly value: string | null;
+ readonly origin: ConfigOrigin;
+}
+
+/**
+ * {@link envOrConfig} with the layer that produced the value.
+ *
+ * The sibling exists rather than a widened `envOrConfig` because that
+ * function is the choke point for roughly fifty-five keys and only the
+ * install, hook-generation and inventory surfaces need provenance. A
+ * mechanical sweep of every call site would buy those few callers
+ * nothing and put the other fifty at risk.
+ *
+ * Only the two layers this function can see are ever reported; a caller
+ * that also consults `<vault>/Brain/_brain.yaml` layers
+ * {@link CONFIG_ORIGIN.vaultConfig} on top of this result itself (see
+ * `src/core/install/settings.ts`).
+ */
+export function resolveWithOrigin(
+ env: NodeJS.ProcessEnv,
+ config: Readonly<Record<string, string>>,
+ envKey: string,
+ configKey: string,
+): ResolvedConfigValue {
+ const e = env[envKey];
+ if (e !== undefined && e !== "") return { value: e, origin: CONFIG_ORIGIN.env };
+ const c = config[configKey];
+ if (c !== undefined && c !== "") return { value: c, origin: CONFIG_ORIGIN.userConfig };
+ return { value: null, origin: CONFIG_ORIGIN.default };
+}
+
/**
* Resolve a value from an environment variable or config map, preferring
* the environment. Returns `null` when neither source has a non-empty value.
+ *
+ * A thin delegation to {@link resolveWithOrigin} so the two can never
+ * disagree about which source wins - `tests/core/config-origin.test.ts`
+ * drives every branch through both and requires the same value.
*/
export function envOrConfig(
env: NodeJS.ProcessEnv,
@@ -103,9 +177,5 @@ export function envOrConfig(
envKey: string,
configKey: string,
): string | null {
- const e = env[envKey];
- if (e !== undefined && e !== "") return e;
- const c = config[configKey];
- if (c !== undefined && c !== "") return c;
- return null;
+ return resolveWithOrigin(env, config, envKey, configKey).value;
}
diff --git a/src/mcp/brain/admin-tools.ts b/src/mcp/brain/admin-tools.ts
index 00cb6e9a..008b3940 100644
--- a/src/mcp/brain/admin-tools.ts
+++ b/src/mcp/brain/admin-tools.ts
@@ -33,8 +33,19 @@ import { appendMetric } from "../../core/brain/metrics.ts";
import type { ProgressSink } from "../../core/brain/progress.ts";
import { requiredStringArg, toolSafeguard } from "./shared.ts";
import { currentLease } from "../../core/brain/maintenance/lease.ts";
-import { listJournal } from "../../core/brain/maintenance/journal.ts";
-import { runMaintenance, type DailyWindow } from "../../core/brain/maintenance/lane.ts";
+import { listJournal, MAINTENANCE_JOURNAL_CAP } from "../../core/brain/maintenance/journal.ts";
+import {
+ isLaneTask,
+ LANE_TASK,
+ LANE_TASKS,
+ MAINTENANCE_BUSY_MINUTES,
+ MAINTENANCE_BUSY_MINUTES_MAX,
+ MAINTENANCE_BUSY_THRESHOLD,
+ MAINTENANCE_BUSY_THRESHOLD_MAX,
+ runMaintenance,
+ type DailyWindow,
+ type LaneTask,
+} from "../../core/brain/maintenance/lane.ts";
import { writeFrontmatterAtomic } from "../../core/vault.ts";
import { resolveNotePath } from "../../core/brain/note-path.ts";
import type { FrontmatterMap } from "../../core/types.ts";
@@ -42,6 +53,7 @@ import { parseFrontmatter } from "../../core/vault.ts";
import { dream } from "../../core/brain/dream.ts";
import { isoSecond } from "../../core/brain/time.ts";
import { normalizeAgentArgument } from "../../core/agent-identity.ts";
+import { coerceInt, coerceStrList } from "../coerce.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
@@ -254,6 +266,20 @@ async function toolBrainSecrets(
// ----- brain_maintenance (t_166d1226) ------------------------------------------
+/**
+ * Bound for `retry_tasks`: naming more tasks than the lane dispatches is
+ * a mistake, not a request.
+ *
+ * The `maxItems` this feeds into the schema is ADVERTISEMENT, not
+ * enforcement - nothing in the request path validates a JSON Schema.
+ * `src/mcp/argument-guard.ts` checks argument NAMES and `coerceStrList`
+ * enforces no length of its own, so a 1000-entry array reached the lane
+ * with the schema saying it could not. The handler checks the length
+ * itself for that reason; the schema keeps the number so a client that
+ * does validate refuses before spending a round trip.
+ */
+const MAX_RETRY_TASKS = LANE_TASKS.length;
+
/** Quiet-window, lease-guarded heavy maintenance lane. */
async function toolBrainMaintenance(
ctx: ServerContext,
@@ -266,9 +292,13 @@ async function toolBrainMaintenance(
}
const now = new Date();
if (op === "status") {
+ // The journal depth is the caller's, as it is on the CLI. It was
+ // hardcoded at ten here, so an agent reading a lane that had refused
+ // a task days ago could not see far enough back to find the failures
+ // behind the streak - the one thing the journal is kept for.
return {
lease: currentLease(ctx.vault, { now }),
- journal: listJournal(ctx.vault, 10),
+ journal: listJournal(ctx.vault, coerceInt(args, "limit", 10, 1, MAINTENANCE_JOURNAL_CAP)),
};
}
let window: DailyWindow | undefined;
@@ -293,6 +323,46 @@ async function toolBrainMaintenance(
const tz = typeof args["tz"] === "string" ? (args["tz"] as string) : "UTC";
window = { startHour, endHour, tz };
}
+ // The busy gate, on the CLI's terms: same two knobs, same defaults, so
+ // an agent that wants a wider quiet window does not have to reach for
+ // `force` - which switches off three gates it never meant to touch.
+ const busy = {
+ minutes: coerceInt(
+ args,
+ "busy_minutes",
+ MAINTENANCE_BUSY_MINUTES,
+ 1,
+ MAINTENANCE_BUSY_MINUTES_MAX,
+ ),
+ threshold: coerceInt(
+ args,
+ "busy_threshold",
+ MAINTENANCE_BUSY_THRESHOLD,
+ 1,
+ MAINTENANCE_BUSY_THRESHOLD_MAX,
+ ),
+ };
+ // Refused BY NAME, exactly as the CLI refuses a `--retry` typo: a name
+ // this lane does not dispatch retries nothing, and silently accepting
+ // it would leave the caller reading a refusal it believed it had just
+ // asked past.
+ const requestedRetries = coerceStrList(args, "retry_tasks");
+ if (requestedRetries.length > MAX_RETRY_TASKS) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ `brain_maintenance run: retry_tasks accepts at most ${MAX_RETRY_TASKS} entries ` +
+ `(one per lane task: ${LANE_TASKS.join(", ")}), got ${requestedRetries.length}`,
+ );
+ }
+ const unknownRetries = requestedRetries.filter((name) => !isLaneTask(name));
+ if (unknownRetries.length > 0) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ `brain_maintenance run: retry_tasks names no lane task: ${unknownRetries.join(", ")} ` +
+ `(tasks: ${LANE_TASKS.join(", ")})`,
+ );
+ }
+ const retryTasks: ReadonlyArray<LaneTask> = requestedRetries.filter(isLaneTask);
const agentArg = args["agent"];
const agent =
normalizeAgentArgument(typeof agentArg === "string" ? agentArg : null) ??
@@ -306,8 +376,10 @@ async function toolBrainMaintenance(
// -> default. The lane is the only surface that wants a guard PER
// TASK rather than per call, so it names the shared factory four
// times instead of holding one guard.
- const laneSafeguard = (operation: "dream" | "reindex" | "bridges" | "clusters") =>
- toolSafeguard(ctx, operation);
+ // A lane task IS one of the guarded operations, so the task name is the
+ // budget key. The union that used to be retyped here is gone: both
+ // surfaces read `LANE_TASK`, whose values come from `OPERATION`.
+ const laneSafeguard = (operation: LaneTask) => toolSafeguard(ctx, operation);
// The lane is a dispatcher over four long operations, not a fifth one,
// so it forwards the caller's sink to each task rather than counting
// tasks itself: every event names the operation that emitted it, which
@@ -317,19 +389,21 @@ async function toolBrainMaintenance(
now,
holder: `${agent}@${process.pid}`,
force: args["force"] === true,
+ busy,
+ ...(retryTasks.length > 0 ? { retryTasks } : {}),
...(window !== undefined ? { window } : {}),
tasks: [
{
- name: "dream",
+ name: LANE_TASK.dream,
run: async () => {
- dream(ctx.vault, { now, safeguard: laneSafeguard("dream"), ...laneProgress });
+ dream(ctx.vault, { now, safeguard: laneSafeguard(LANE_TASK.dream), ...laneProgress });
},
},
{
- name: "reindex",
+ name: LANE_TASK.reindex,
run: async () => {
await indexVault(searchConfig, {
- safeguard: laneSafeguard("reindex"),
+ safeguard: laneSafeguard(LANE_TASK.reindex),
...laneProgress,
});
},
@@ -339,13 +413,13 @@ async function toolBrainMaintenance(
// edges; both are fail-soft without embeddings, and a metrics
// write failure never fails the task.
{
- name: "bridges",
+ name: LANE_TASK.bridges,
run: async () => {
const store = await Store.open(searchConfig, { mode: "read" });
try {
const report = discoverBridges(store, {
dismissed: readDismissedBridges(ctx.vault),
- safeguard: laneSafeguard("bridges"),
+ safeguard: laneSafeguard(LANE_TASK.bridges),
...laneProgress,
});
writeBridgeProposals(ctx.vault, report, { now });
@@ -369,12 +443,12 @@ async function toolBrainMaintenance(
},
},
{
- name: "clusters",
+ name: LANE_TASK.clusters,
run: async () => {
const store = await Store.open(searchConfig, { mode: "read" });
try {
const communities = detectCommunities(store, {
- safeguard: laneSafeguard("clusters"),
+ safeguard: laneSafeguard(LANE_TASK.clusters),
...laneProgress,
});
const materialized = materializeClusterNotes(ctx.vault, communities, { store, now });
@@ -476,12 +550,44 @@ export const ADMIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: "brain_maintenance",
description:
- "Quiet-window, lease-guarded heavy maintenance lane: run executes dream, reindex, bridges, and clusters stale-first behind the local-time window, busy gate, and an expiring lease (force bypasses the soft gates, never the lease); status renders the lease holder and recent journal.",
+ "Quiet-window, lease-guarded heavy maintenance lane: run executes dream, reindex, bridges and clusters stale-first behind the window, busy, host-pressure and streak gates and an expiring lease (force bypasses all of those but the lease); status renders the lease holder and recent journal.",
inputSchema: {
type: "object",
properties: {
operation: { type: "string", enum: ["run", "status"], description: "Tool operation." },
- force: { type: "boolean", description: "Bypass window and busy gates (run)." },
+ force: {
+ type: "boolean",
+ // The old text said "window and busy gates" and had been wrong
+ // since the pressure gate and the streak refusal were added.
+ // A caller reaching for the widest escape has to be told what
+ // it actually switches off.
+ description:
+ "Bypass the window, busy and host-pressure gates and every streak refusal - never the lease (run). retry_tasks passes one task's streak with the gates kept.",
+ },
+ retry_tasks: {
+ type: "array",
+ items: { type: "string" },
+ maxItems: MAX_RETRY_TASKS,
+ description: `Tasks to retry past their streak refusal, this run only; gates still apply. Known: ${LANE_TASKS.join(", ")}. An unknown name is refused.`,
+ },
+ busy_minutes: {
+ type: "integer",
+ minimum: 1,
+ maximum: MAINTENANCE_BUSY_MINUTES_MAX,
+ description: `Busy-gate lookback in minutes (run; default ${MAINTENANCE_BUSY_MINUTES}).`,
+ },
+ busy_threshold: {
+ type: "integer",
+ minimum: 1,
+ maximum: MAINTENANCE_BUSY_THRESHOLD_MAX,
+ description: `Recent queries in the lookback that count as busy (run; default ${MAINTENANCE_BUSY_THRESHOLD}).`,
+ },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ maximum: MAINTENANCE_JOURNAL_CAP,
+ description: "Journal rows to return, newest first (status; default 10).",
+ },
window_start_hour: {
type: "integer",
minimum: 0,
diff --git a/src/mcp/brain/feedback-tools.ts b/src/mcp/brain/feedback-tools.ts
index b710527a..0543a6c0 100644
--- a/src/mcp/brain/feedback-tools.ts
+++ b/src/mcp/brain/feedback-tools.ts
@@ -457,7 +457,19 @@ async function toolBrainDream(
);
}
try {
- return { ...runDreamStep(ctx.vault, stepArg) };
+ // Bounded and observed on the same terms as every sibling branch.
+ // This one had neither: it was the row `docs/mcp.md` marked
+ // **none**, and `dream()` being synchronous is exactly why that
+ // mattered - an unbounded step holds the server's event loop for
+ // its whole duration and the client cannot even time out and
+ // reissue. The budget is `dream`'s, because a step IS part of a
+ // dream pass; the sink is the caller's, dropped here until now.
+ return {
+ ...runDreamStep(ctx.vault, stepArg, {
+ safeguard: toolSafeguard(ctx, OPERATION.dream),
+ ...(onProgress ? { onProgress } : {}),
+ }),
+ };
} catch (exc) {
if (exc instanceof DreamStepNotRunnableError) {
throw new MCPError(INVALID_PARAMS, exc.message);
diff --git a/src/mcp/capabilities.ts b/src/mcp/capabilities.ts
index b044ff1e..72361629 100644
--- a/src/mcp/capabilities.ts
+++ b/src/mcp/capabilities.ts
@@ -1,4 +1,10 @@
+import {
+ RUNTIME_FACTS,
+ TOOL_CEILING_KIND,
+ type InstallTargetId,
+} from "../core/runtime/host-facts.ts";
import type {
+ HostCeilingReport,
ToolCapabilityEntry,
ToolCapabilityReport,
ToolDefinition,
@@ -15,6 +21,14 @@ export interface RuntimeCapabilityContext {
readonly scope: ToolScope;
readonly serverName: string;
readonly window?: RuntimeCapabilityWindow;
+ /**
+ * The runtime that launched this server, from `o2b mcp --host-target`
+ * in the registration an install adapter generated. Absent whenever
+ * the server was started by hand or by a payload written before the
+ * flag existed - which is reported as an unchecked ceiling, never as
+ * an absent one.
+ */
+ readonly hostTarget?: InstallTargetId;
}
export interface ToolCapabilityEvaluation {
@@ -55,6 +69,7 @@ export function evaluateToolCapabilities(
available.push({ name: tool.name, reason: "available" });
}
+ const advertised = tools.filter((tool) => tool.hidden !== true).length;
return {
tools,
report: {
@@ -62,12 +77,70 @@ export function evaluateToolCapabilities(
server_name: context.serverName,
static_tool_count: candidates.length,
available_tool_count: tools.length,
+ advertised_tool_count: advertised,
+ host_ceiling: hostCeiling(context.hostTarget, advertised),
available,
withheld,
},
};
}
+/**
+ * Why a server that was never told its host cannot cite a limit.
+ *
+ * It names the flag rather than shrugging, because the remedy is
+ * concrete: re-run `o2b install --target <runtime> --apply` and the
+ * generated registration will carry it.
+ */
+const UNNAMED_HOST_REASON =
+ "this server was not told which runtime launched it (no --host-target in its registration), " +
+ "so no published per-workspace tool limit can be cited; re-run " +
+ "`o2b install --target <runtime> --apply` to regenerate a registration that names the host";
+
+/** The host's published limit, or the stated absence of one. */
+function hostCeiling(target: InstallTargetId | undefined, advertised: number): HostCeilingReport {
+ if (target === undefined) {
+ return {
+ target: null,
+ kind: TOOL_CEILING_KIND.unknown,
+ max_tools: null,
+ source: null,
+ reason: UNNAMED_HOST_REASON,
+ within_ceiling: null,
+ };
+ }
+ const ceiling = RUNTIME_FACTS[target].toolCeiling;
+ switch (ceiling.kind) {
+ case TOOL_CEILING_KIND.declared:
+ return {
+ target,
+ kind: ceiling.kind,
+ max_tools: ceiling.maxTools,
+ source: ceiling.source,
+ reason: null,
+ within_ceiling: advertised <= ceiling.maxTools,
+ };
+ case TOOL_CEILING_KIND.unbounded:
+ return {
+ target,
+ kind: ceiling.kind,
+ max_tools: null,
+ source: ceiling.source,
+ reason: null,
+ within_ceiling: true,
+ };
+ case TOOL_CEILING_KIND.unknown:
+ return {
+ target,
+ kind: ceiling.kind,
+ max_tools: null,
+ source: null,
+ reason: ceiling.reason,
+ within_ceiling: null,
+ };
+ }
+}
+
function nonEmptySet(values: ReadonlyArray<string> | undefined): ReadonlySet<string> | null {
if (!values || values.length === 0) return null;
return new Set(values);
diff --git a/src/mcp/drain.ts b/src/mcp/drain.ts
new file mode 100644
index 00000000..e896dd92
--- /dev/null
+++ b/src/mcp/drain.ts
@@ -0,0 +1,204 @@
+/**
+ * In-flight request bookkeeping, shared by both MCP transports.
+ *
+ * Neither transport could shut down without cutting a request in half.
+ * The HTTP handle's `close` was `server.close()` and nothing else - it
+ * stops the listener and returns, while the promise returned by
+ * `handleHttpRequest` is floated by the `createServer` callback, so a
+ * tool call mid-flight was answered with a closed socket. The stdio loop
+ * had no shutdown path at all.
+ *
+ * What both need is the same small thing: a count of what is running, a
+ * way to say "no more", and a bounded wait. That is this module, and it
+ * is deliberately transport-shaped rather than signal-shaped:
+ *
+ * - It installs NO signal handler and knows no exit codes. Signals are
+ * process-global and the process belongs to the CLI, which already
+ * owns that vocabulary in `src/cli/interrupt.ts`; a second module
+ * reaching for `process.once("SIGTERM")` is how two conventions get
+ * shipped. `src/cli/mcp-drain.ts` is the caller that wires them.
+ * - It never abandons a request quietly. When the deadline expires the
+ * outcome CARRIES the requests that were still open, so the caller
+ * can name them. A drain that dropped them silently would be the
+ * same defect as the bare `server.close()`, one layer up.
+ */
+
+/** How long a drain waits for in-flight work before it gives up, in ms. */
+export const DEFAULT_DRAIN_DEADLINE_MS = 10_000;
+
+/** The environment variable that moves that deadline. */
+export const DRAIN_DEADLINE_ENV = "O2B_MCP_DRAIN_MS";
+
+/**
+ * The deadline this process uses.
+ *
+ * A value that is not a non-negative finite number THROWS rather than
+ * falling back to the default: an operator who set the variable did so to
+ * change the behaviour, and quietly using ten seconds because they typed
+ * `10s` is exactly the misleading quiet this release removes.
+ */
+export function resolveDrainDeadlineMs(env: NodeJS.ProcessEnv): number {
+ const raw = env[DRAIN_DEADLINE_ENV];
+ if (raw === undefined || raw.trim() === "") return DEFAULT_DRAIN_DEADLINE_MS;
+ const parsed = Number(raw.trim());
+ if (!Number.isFinite(parsed) || parsed < 0) {
+ throw new Error(
+ `${DRAIN_DEADLINE_ENV}=${raw} is not a shutdown deadline; set it to a non-negative ` +
+ `number of milliseconds (the default is ${DEFAULT_DRAIN_DEADLINE_MS}), or unset it`,
+ );
+ }
+ return parsed;
+}
+
+/** What a transport is doing about new work. */
+export const DRAIN_STATE = Object.freeze({
+ /** Accepting new requests. */
+ serving: "serving",
+ /** Refusing new requests, finishing the ones already begun. */
+ draining: "draining",
+ /** Drained (or the deadline expired) and shut. */
+ drained: "drained",
+ /** The deadline expired with requests still open. */
+ deadlineExpired: "deadline_expired",
+} as const);
+
+export type DrainState = (typeof DRAIN_STATE)[keyof typeof DRAIN_STATE];
+
+/** One request the transport has begun and not yet answered. */
+export interface InFlightRequest {
+ readonly id: number;
+ /** What it is, in the transport's own terms - `POST /`, `tools/call`. */
+ readonly label: string;
+ /** `Date.now()` when the transport began it. */
+ readonly started_at: number;
+}
+
+export interface DrainOutcome {
+ /** {@link DRAIN_STATE.drained} or {@link DRAIN_STATE.deadlineExpired}. */
+ readonly state: DrainState;
+ readonly waited_ms: number;
+ readonly deadline_ms: number;
+ /** The requests still open when the deadline expired. Empty when drained. */
+ readonly abandoned: ReadonlyArray<InFlightRequest>;
+}
+
+/**
+ * The in-flight register for one transport.
+ *
+ * `begin` returns the `finish` for that one request rather than taking an
+ * id back, so a caller cannot finish somebody else's request and cannot
+ * forget which id was theirs. `finish` is idempotent: an HTTP response
+ * that both ends normally and fires `close` must not decrement twice.
+ */
+export class RequestDrain {
+ #state: DrainState = DRAIN_STATE.serving;
+ #nextId = 1;
+ readonly #open = new Map<number, InFlightRequest>();
+ #settle: (() => void) | null = null;
+
+ get state(): DrainState {
+ return this.#state;
+ }
+
+ /** True once a drain has started; the transport must refuse new work. */
+ get draining(): boolean {
+ return this.#state !== DRAIN_STATE.serving;
+ }
+
+ get inFlight(): number {
+ return this.#open.size;
+ }
+
+ /** The requests currently open, oldest first. */
+ snapshot(): ReadonlyArray<InFlightRequest> {
+ return [...this.#open.values()];
+ }
+
+ /** Register one request. Returns the idempotent finish for it. */
+ begin(label: string): () => void {
+ const id = this.#nextId++;
+ this.#open.set(id, { id, label, started_at: Date.now() });
+ let done = false;
+ return () => {
+ if (done) return;
+ done = true;
+ this.#open.delete(id);
+ if (this.#open.size === 0 && this.#settle !== null) {
+ const settle = this.#settle;
+ this.#settle = null;
+ settle();
+ }
+ };
+ }
+
+ /**
+ * Stop accepting, then wait for the open requests up to `deadlineMs`.
+ *
+ * Resolves as soon as the last one finishes. A second call while a
+ * drain is already running waits on the same completion rather than
+ * starting a second timer - two signals in quick succession are one
+ * shutdown.
+ */
+ async drain(deadlineMs: number): Promise<DrainOutcome> {
+ const startedAt = Date.now();
+ this.#state = DRAIN_STATE.draining;
+ if (this.#open.size === 0) return this.#settled(startedAt, deadlineMs);
+
+ const emptied = new Promise<true>((resolve) => {
+ const previous = this.#settle;
+ this.#settle = () => {
+ previous?.();
+ resolve(true);
+ };
+ });
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const expired = new Promise<false>((resolve) => {
+ timer = setTimeout(() => resolve(false), deadlineMs);
+ });
+ const drained = await Promise.race([emptied, expired]);
+ if (timer !== undefined) clearTimeout(timer);
+ return drained ? this.#settled(startedAt, deadlineMs) : this.#expired(startedAt, deadlineMs);
+ }
+
+ #settled(startedAt: number, deadlineMs: number): DrainOutcome {
+ this.#state = DRAIN_STATE.drained;
+ return {
+ state: DRAIN_STATE.drained,
+ waited_ms: Date.now() - startedAt,
+ deadline_ms: deadlineMs,
+ abandoned: [],
+ };
+ }
+
+ #expired(startedAt: number, deadlineMs: number): DrainOutcome {
+ this.#state = DRAIN_STATE.deadlineExpired;
+ return {
+ state: DRAIN_STATE.deadlineExpired,
+ waited_ms: Date.now() - startedAt,
+ deadline_ms: deadlineMs,
+ abandoned: this.snapshot(),
+ };
+ }
+}
+
+/**
+ * The line an operator reads when the deadline beat the requests.
+ *
+ * Every abandoned request is named with how long it had been running,
+ * because "three requests were dropped" and "a `tools/call` that had been
+ * running for nine seconds was dropped" lead to different next steps -
+ * and the second is the one that says whether the deadline is too short.
+ */
+export function describeAbandonedRequests(outcome: DrainOutcome): string {
+ if (outcome.abandoned.length === 0) return "";
+ const now = Date.now();
+ const lines = outcome.abandoned.map(
+ (request) => ` - ${request.label} (open for ${now - request.started_at}ms)`,
+ );
+ return (
+ `[mcp] drain deadline of ${outcome.deadline_ms}ms expired with ` +
+ `${outcome.abandoned.length} request(s) still open; closing anyway:\n` +
+ `${lines.join("\n")}\n` +
+ `[mcp] raise ${DRAIN_DEADLINE_ENV} if this shutdown needs longer\n`
+ );
+}
diff --git a/src/mcp/http.ts b/src/mcp/http.ts
index 3524e437..e2566755 100644
--- a/src/mcp/http.ts
+++ b/src/mcp/http.ts
@@ -3,22 +3,42 @@
*
* This stays transport-only: every accepted JSON-RPC request is dispatched
* through MCPServer.handleRequest, the same core used by stdio.
+ *
+ * ## Shutdown
+ *
+ * `close` used to be a bare `server.close()`. That stops the listener and
+ * returns; it does not wait for anything, and the promise this module's
+ * own request callback returns is floated, so a shutdown landing during a
+ * tool call answered it with a dead socket. {@link HttpServerHandle.close}
+ * now drains: it stops accepting NEW MCP work, keeps answering `/health`
+ * so a supervisor can watch it happen, waits for the in-flight requests to
+ * a bounded deadline, and only then shuts the listener down. The listener
+ * outliving the refusal is deliberate - "stopped accepting" is about
+ * requests, and a `/health` that answers `connection refused` tells a
+ * supervisor nothing about which state it is in.
*/
import { createHash, timingSafeEqual } from "node:crypto";
import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
import { once } from "node:events";
+import type { Socket } from "node:net";
import type { Writable } from "node:stream";
import { MCPServer, type MCPServerOptions, type MCPServerRuntimeOptions } from "./server.ts";
import { errorResponse, type JsonRpcResponse } from "./server.ts";
-import { INVALID_REQUEST, PARSE_ERROR } from "./protocol.ts";
+import { INTERNAL_ERROR, INVALID_REQUEST, PARSE_ERROR } from "./protocol.ts";
+import { DRAIN_STATE, RequestDrain, resolveDrainDeadlineMs, type DrainOutcome } from "./drain.ts";
export interface ServeHttpOptions {
readonly host?: string;
readonly port?: number;
readonly apiKey?: string | null;
readonly stderr?: Writable;
+ /**
+ * How long {@link HttpServerHandle.close} waits for in-flight requests.
+ * Defaults to `O2B_MCP_DRAIN_MS`, and to ten seconds without it.
+ */
+ readonly drainDeadlineMs?: number;
}
export interface HttpServerHandle {
@@ -26,7 +46,13 @@ export interface HttpServerHandle {
readonly host: string;
readonly port: number;
readonly url: string;
- close(): Promise<void>;
+ /** The in-flight register, so a caller can report what is running. */
+ readonly drain: RequestDrain;
+ /**
+ * Stop accepting, await the in-flight requests to the deadline, close.
+ * Returns what happened, including any request the deadline abandoned.
+ */
+ close(): Promise<DrainOutcome>;
}
const MAX_BODY_BYTES = 1024 * 1024;
@@ -50,8 +76,56 @@ export async function startHttp(
}
const port = opts.port ?? 0;
const mcp = new MCPServer(ctx, runtimeOpts);
+ const drain = new RequestDrain();
+ const deadlineMs = opts.drainDeadlineMs ?? resolveDrainDeadlineMs(process.env);
const server = createServer(async (req, res) => {
- await handleHttpRequest(mcp, apiKey, host, req, res);
+ // Registered here rather than inside the handler so the whole
+ // request - header parsing, body read, dispatch, response write - is
+ // inside the window a drain waits for. `finish` runs on `close`
+ // rather than on the handler returning: a client that walks away
+ // mid-body leaves the handler parked forever, and a drain waiting on
+ // it would sit out its whole deadline for a request nobody wants.
+ // The health probe is an OBSERVATION of the drain, not work it waits
+ // for: counting it would make the number a supervisor reads include
+ // the act of reading it, and a probe arriving as the last request
+ // finishes would restart the wait it was checking on.
+ // A request that arrives once the drain has started is not work
+ // either - it is refused with a 503 below and never dispatched - and
+ // counting it let a client retrying in a tight loop keep the register
+ // non-empty, holding the shutdown open to its whole deadline over
+ // requests the server had already declined to do.
+ const untracked = isHealthProbe(req) || drain.draining;
+ const finish = untracked ? NOTHING_TO_FINISH : drain.begin(requestLabel(req));
+ // On `close` rather than on the handler returning, because that is
+ // when the response has actually left: a request counted as finished
+ // while its bytes are still queued lets the drain proceed to
+ // `closeIdleConnections` over a socket that is not idle yet, and the
+ // shutdown then waits for a client that is waiting for it.
+ res.on("close", finish);
+ try {
+ await handleHttpRequest(mcp, apiKey, host, drain, req, res);
+ } catch (exc) {
+ // This promise used to be floated. A throw from the dispatch left
+ // the socket open with no response on it and no record anywhere;
+ // the client waited until its own timeout for a request the server
+ // had already given up on.
+ if (!res.headersSent) {
+ writeJson(res, errorResponse(null, INTERNAL_ERROR, (exc as Error).message));
+ } else {
+ res.end();
+ }
+ }
+ });
+ // Every accepted socket, tracked so an expired drain can actually drop
+ // what it gave up on. `server.closeAllConnections()` is the documented
+ // way to do that and, measured on this runtime, does NOT reach a socket
+ // parked mid-body: the request stays open, `server.close` never calls
+ // back, and a shutdown that promised a bounded deadline waits forever.
+ // The set is the fallback that makes the deadline real.
+ const sockets = new Set<Socket>();
+ server.on("connection", (socket: Socket) => {
+ sockets.add(socket);
+ socket.on("close", () => sockets.delete(socket));
});
server.listen(port, host);
await once(server, "listening");
@@ -62,13 +136,61 @@ export async function startHttp(
host,
port: actualPort,
url: `http://${host}:${actualPort}`,
- close: () =>
- new Promise<void>((resolve, reject) => {
- server.close((err) => (err ? reject(err) : resolve()));
- }),
+ drain,
+ close: () => closeHttp(server, drain, deadlineMs, sockets),
};
}
+/** How one in-flight request is named in a drain report. */
+function requestLabel(req: IncomingMessage): string {
+ return `${req.method ?? "?"} ${requestPath(req)}`;
+}
+
+function requestPath(req: IncomingMessage): string {
+ return (req.url ?? "/").split("?")[0] ?? "/";
+}
+
+/** The unauthenticated liveness probe, recognised before anything is counted. */
+const HEALTH_PATH = "/health";
+
+function isHealthProbe(req: IncomingMessage): boolean {
+ return req.method === "GET" && requestPath(req) === HEALTH_PATH;
+}
+
+/** The finish for a request the drain does not track. */
+const NOTHING_TO_FINISH = (): void => {};
+
+/**
+ * Drain, then shut the listener.
+ *
+ * The order matters and the connection handling is the part that is easy
+ * to get wrong. `server.close()` refuses new CONNECTIONS but resolves
+ * only once every existing socket is gone, and HTTP keep-alive means an
+ * answered request leaves its socket open - so closing without touching
+ * the idle ones hangs until the client happens to disconnect.
+ * `closeIdleConnections` releases exactly those. Sockets still carrying
+ * an abandoned request are dropped only after the deadline has expired,
+ * and the outcome returned here still names those requests so the caller
+ * can report them rather than dropping them silently.
+ */
+async function closeHttp(
+ server: Server,
+ drain: RequestDrain,
+ deadlineMs: number,
+ sockets: ReadonlySet<Socket>,
+): Promise<DrainOutcome> {
+ const outcome = await drain.drain(deadlineMs);
+ const closed = new Promise<void>((resolve, reject) => {
+ server.close((err) => (err ? reject(err) : resolve()));
+ });
+ server.closeIdleConnections();
+ if (outcome.state === DRAIN_STATE.deadlineExpired) {
+ for (const socket of sockets) socket.destroy();
+ }
+ await closed;
+ return outcome;
+}
+
export async function serveHttp(
ctx: MCPServerOptions,
opts: ServeHttpOptions = {},
@@ -83,6 +205,7 @@ async function handleHttpRequest(
mcp: MCPServer,
apiKey: string | null,
boundHost: string,
+ drain: RequestDrain,
req: IncomingMessage,
res: ServerResponse,
): Promise<void> {
@@ -101,13 +224,38 @@ async function handleHttpRequest(
return;
}
- const path = (req.url ?? "/").split("?")[0];
-
// Health endpoint: an unauthenticated liveness probe (still behind the Host
// guard), so a supervisor can check the transport without a bearer.
- if (req.method === "GET" && path === "/health") {
+ if (isHealthProbe(req)) {
+ // Three fields rather than one, because a supervisor's next action
+ // differs per state: `ok` keep going, `draining` stop sending work
+ // and wait, and the count says how long that wait has left in it.
+ // The health probe itself is never refused during a drain - a
+ // shutdown a supervisor cannot observe is a shutdown it will report
+ // as a crash. The drain counts this request like any other; it
+ // answers within the same tick, so it never holds one open.
res.writeHead(200, { "content-type": "application/json" });
- res.end(JSON.stringify({ status: "ok", transport: "http" }) + "\n");
+ res.end(
+ JSON.stringify({
+ status: drain.draining ? DRAIN_STATE.draining : "ok",
+ transport: "http",
+ in_flight: drain.inFlight,
+ }) + "\n",
+ );
+ return;
+ }
+
+ // Stopped accepting. The listener is deliberately still up (see the
+ // module docblock), so this is where "no more work" is actually said,
+ // and it is said with a code a client retries rather than one it reads
+ // as a protocol error.
+ if (drain.draining) {
+ res.writeHead(503, {
+ "content-type": "text/plain; charset=utf-8",
+ connection: "close",
+ "retry-after": "1",
+ });
+ res.end("Service Unavailable: the MCP transport is shutting down\n");
return;
}
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index e639408b..bf62f542 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -44,6 +44,7 @@ import { assertOutputContract } from "./output-contract.ts";
import { ArtifactStore } from "./artifact-store.ts";
import { applyPreviewBudget } from "./preview-budget.ts";
import { evaluateToolCapabilities, type RuntimeCapabilityWindow } from "./capabilities.ts";
+import type { InstallTargetId } from "../core/runtime/host-facts.ts";
/** TTL after which a prior process's artifact run directory is pruned. */
const ARTIFACT_TTL_MS = 24 * 60 * 60 * 1000;
@@ -58,6 +59,13 @@ export interface MCPServerRuntimeOptions {
readonly serverName?: string;
readonly scope?: ToolScope;
readonly capabilityWindow?: RuntimeCapabilityWindow;
+ /**
+ * The runtime that launched this process, from `o2b mcp
+ * --host-target` in a generated registration. Only the capability
+ * report reads it, and only to name the host's published tool
+ * ceiling; absent means the ceiling is reported as unchecked.
+ */
+ readonly hostTarget?: InstallTargetId;
/**
* Run id grouping this process's preview artifacts under
* `Brain/.artifacts/<run-id>/`. Defaults to a per-process id;
@@ -124,6 +132,7 @@ export class MCPServer {
scope: this.scope,
serverName: this.serverName,
window: runtimeOpts.capabilityWindow,
+ hostTarget: runtimeOpts.hostTarget,
});
this.tools = evaluated.tools;
this.capabilityReport = evaluated.report;
diff --git a/src/mcp/stdio.ts b/src/mcp/stdio.ts
index d4eca8ae..a8c681e2 100644
--- a/src/mcp/stdio.ts
+++ b/src/mcp/stdio.ts
@@ -3,6 +3,16 @@
*
* Mirrors `serve_stdio` from the legacy Python implementation. The server
* only writes JSON-RPC frames to stdout; logs go to stderr.
+ *
+ * ## Shutdown
+ *
+ * The loop had no shutdown path at all: a SIGTERM took the default
+ * disposition and killed the process wherever it happened to be, which
+ * for a `tools/call` is mid-dispatch with no frame written. It now shares
+ * the HTTP transport's register (`./drain.ts`): a drain stops the loop at
+ * a request boundary, waits for the one request that can be in flight,
+ * and only then closes the reader. Nothing here handles a signal - that
+ * belongs to the CLI, which owns the process (`src/cli/mcp-drain.ts`).
*/
import { createInterface } from "node:readline";
@@ -11,6 +21,7 @@ import type { Readable, Writable } from "node:stream";
import { MCPServer, type MCPServerOptions, type MCPServerRuntimeOptions } from "./server.ts";
import { errorResponse, type JsonRpcResponse } from "./server.ts";
import { INVALID_REQUEST, PARSE_ERROR, type JsonRpcNotification } from "./protocol.ts";
+import { RequestDrain, resolveDrainDeadlineMs, type DrainOutcome } from "./drain.ts";
/**
* Any frame this transport writes: a response to a request, or a
@@ -18,10 +29,28 @@ import { INVALID_REQUEST, PARSE_ERROR, type JsonRpcNotification } from "./protoc
*/
type OutboundFrame = JsonRpcResponse | JsonRpcNotification;
+/**
+ * The shutdown handle for a running stdio loop.
+ *
+ * The same two members the HTTP handle exposes, so `src/cli/mcp-drain.ts`
+ * wires one signal handler for both transports rather than one each. It
+ * is handed to {@link ServeStdioOptions.onStart} rather than returned,
+ * because this loop does not return until it is over.
+ */
+export interface StdioTransportHandle {
+ readonly drain: RequestDrain;
+ /** Stop reading new lines, await the in-flight request, end the loop. */
+ close(): Promise<DrainOutcome>;
+}
+
export interface ServeStdioOptions {
readonly stdin?: Readable;
readonly stdout?: Writable;
readonly stderr?: Writable;
+ /** Defaults to `O2B_MCP_DRAIN_MS`, and to ten seconds without it. */
+ readonly drainDeadlineMs?: number;
+ /** Called once the loop is live, with the handle that shuts it down. */
+ readonly onStart?: (handle: StdioTransportHandle) => void;
}
/**
@@ -50,7 +79,28 @@ export async function serveStdio(
});
const rl = createInterface({ input: stdin, crlfDelay: Infinity });
+ const drain = new RequestDrain();
+ const deadlineMs = ioOpts.drainDeadlineMs ?? resolveDrainDeadlineMs(process.env);
+ ioOpts.onStart?.({
+ drain,
+ close: async () => {
+ // The wait comes first and the reader is closed after it: closing
+ // the interface while a `tools/call` is still running would end the
+ // loop before its response frame was written, which is the stdio
+ // shape of the truncated HTTP response this unit removes.
+ const outcome = await drain.drain(deadlineMs);
+ rl.close();
+ return outcome;
+ },
+ });
+
for await (const rawLine of rl) {
+ // Stopped accepting. A line that arrives after a drain has started is
+ // left unread rather than answered with an error frame: the client is
+ // being disconnected either way, and a half-served shutdown that
+ // replies to some requests and not others is harder to reason about
+ // than one that stops cleanly at a request boundary.
+ if (drain.draining) break;
const line = rawLine.trim();
if (!line) continue;
let request: unknown;
@@ -78,12 +128,27 @@ export async function serveStdio(
writeFrame(stdout, errorResponse(null, INVALID_REQUEST, "request must be an object"));
continue;
}
- const response = await server.handleRequest(request as Record<string, unknown>);
- if (response !== null) writeFrame(stdout, response);
+ // The response write is INSIDE the tracked window: a request marked
+ // finished before its frame is queued lets a drain end the loop
+ // between the dispatch and the answer.
+ const finish = drain.begin(requestLabel(request as Record<string, unknown>));
+ try {
+ const response = await server.handleRequest(request as Record<string, unknown>);
+ if (response !== null) writeFrame(stdout, response);
+ } finally {
+ finish();
+ }
}
return 0;
}
+/** How one in-flight stdio request is named in a drain report. */
+function requestLabel(request: Record<string, unknown>): string {
+ const method = typeof request["method"] === "string" ? request["method"] : "(no method)";
+ const id = request["id"];
+ return id === undefined ? method : `${method} (id ${JSON.stringify(id)})`;
+}
+
/**
* One frame as the single line this protocol delimits by.
*
diff --git a/src/mcp/tool-contract.ts b/src/mcp/tool-contract.ts
index 2412a408..c8922bf1 100644
--- a/src/mcp/tool-contract.ts
+++ b/src/mcp/tool-contract.ts
@@ -15,6 +15,7 @@
import type { OutputSchema } from "./output-contract.ts";
import type { ArtifactStore } from "./artifact-store.ts";
import type { ProgressSink } from "../core/brain/progress.ts";
+import type { ToolCeilingKind } from "../core/runtime/host-facts.ts";
/**
* The tool surfaces a server process can advertise.
@@ -54,11 +55,45 @@ export interface ToolCapabilityEntry {
readonly reason: string;
}
+/**
+ * What the running server can say about the per-workspace tool limit of
+ * the host that launched it.
+ *
+ * Present on every report, including - especially - when the answer is
+ * "nobody has established one". A host that caps a workspace at forty
+ * tools and is handed a hundred and ten drops the excess in silence, so
+ * a report that omitted the ceiling when it did not know one would be
+ * indistinguishable from a host with no limit at all. `kind` never
+ * collapses `unknown` into `unbounded`, and `reason` carries the written
+ * explanation the `RUNTIME_FACTS` row owes for saying nothing.
+ */
+export interface HostCeilingReport {
+ /** The install target that launched this server; `null` when unnamed. */
+ readonly target: string | null;
+ readonly kind: ToolCeilingKind;
+ /** The published limit; `null` unless `kind` is `declared`. */
+ readonly max_tools: number | null;
+ /** Where the limit (or its absence) is published; `null` when unknown. */
+ readonly source: string | null;
+ /** Why there is no answer; `null` unless `kind` is `unknown`. */
+ readonly reason: string | null;
+ /** Advertised tools against `max_tools`; `null` when there is no number. */
+ readonly within_ceiling: boolean | null;
+}
+
export interface ToolCapabilityReport {
readonly scope: ToolScope;
readonly server_name: string;
readonly static_tool_count: number;
readonly available_tool_count: number;
+ /**
+ * The tools a host actually LISTS: `available_tool_count` minus the
+ * ones marked `hidden`, which `tools/list` filters out. The two
+ * numbers are a hundred and three apart under the `catalog` surface,
+ * and it is this one the host's ceiling applies to.
+ */
+ readonly advertised_tool_count: number;
+ readonly host_ceiling: HostCeilingReport;
readonly available: ToolCapabilityEntry[];
readonly withheld: ToolCapabilityEntry[];
}
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index 11b93a71..47033255 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -42,6 +42,8 @@ import { vaultRelative } from "../core/path-safety.ts";
import { isOwnerVisible, normalizeAgentScope, pageOwner } from "../core/graph/agent-scope.ts";
import { listVaultPages } from "../core/vault.ts";
import { DEGRADATION_CODE, type DegradationNotice } from "../core/integrity/degradation.ts";
+import { TOOL_CEILING_KINDS } from "../core/runtime/host-facts.ts";
+import { inventoryStateSurfaces } from "../core/state/surfaces.ts";
import { INVALID_PARAMS, METHOD_NOT_FOUND, MCPError } from "./protocol.ts";
import { AGENT_SCOPE_SCHEMA, coerceAgentScope, coerceStr, coerceInt } from "./coerce.ts";
import type { OutputSchema } from "./output-contract.ts";
@@ -289,9 +291,39 @@ async function toolVaultHealth(
ok: payload.every((c) => c.ok),
checks: payload,
notices,
+ // Where this vault keeps its state, measured the same way and from
+ // the same value `o2b state status` renders. It rides `vault_health`
+ // rather than a tool of its own because the question it answers -
+ // "what is here, is it reachable, and what put it there" - is the
+ // question a caller already asked; a second tool would be a second
+ // place for the two answers to disagree. It is a sibling FIELD, not a
+ // contribution to `ok`: an absent surface is normal on a young vault
+ // and an unchecked one carries its own reason.
+ state_surfaces: inventoryStateSurfaces({
+ vault: ctx.vault,
+ env: process.env,
+ config: readConfigForStateSurfaces(ctx.configPath),
+ }),
};
}
+/**
+ * The machine config the state overrides are read from.
+ *
+ * An unreadable config resolves to the strict fallback - no overrides -
+ * rather than propagating, because this is a READER: refusing the whole
+ * health report over a config file it could not parse would remove the
+ * one surface that could have said so. The `checks` array already carries
+ * the config fault by name.
+ */
+function readConfigForStateSurfaces(configPath: string | null): Readonly<Record<string, string>> {
+ try {
+ return discoverConfig(configPath ?? undefined).data;
+ } catch {
+ return {};
+ }
+}
+
async function toolArtifactGet(
ctx: ServerContext,
args: Record<string, unknown>,
@@ -338,6 +370,8 @@ const CAPABILITIES_OUTPUT_SCHEMA: OutputSchema = {
"server_name",
"static_tool_count",
"available_tool_count",
+ "advertised_tool_count",
+ "host_ceiling",
"available",
"withheld",
],
@@ -346,6 +380,18 @@ const CAPABILITIES_OUTPUT_SCHEMA: OutputSchema = {
server_name: { type: "string" },
static_tool_count: { type: "integer" },
available_tool_count: { type: "integer" },
+ advertised_tool_count: { type: "integer" },
+ // Every field but `kind` is nullable, and the shape vocabulary
+ // types a node with one `type` rather than a union - so those
+ // nodes declare presence and leave the kind to `kind`, which is
+ // the field that says which of them carry a value.
+ host_ceiling: {
+ type: "object",
+ required: ["target", "kind", "max_tools", "source", "reason", "within_ceiling"],
+ properties: {
+ kind: { type: "string", enum: TOOL_CEILING_KINDS },
+ },
+ },
available: {
type: "array",
items: {
@@ -463,7 +509,8 @@ export function buildToolTable(scope: ToolScope = TOOL_SCOPE.full): ToolDefiniti
...SEARCH_TOOLS,
{
name: "vault_health",
- description: "Run vault, config, and plugin manifest health checks.",
+ description:
+ "Run vault, config, and plugin manifest health checks, and report every state surface in the vault with its path, reachability, and the override that placed it.",
inputSchema: {
type: "object",
properties: {
diff --git a/tests/cli/brain-dream-operator-surface.test.ts b/tests/cli/brain-dream-operator-surface.test.ts
index f47d9bf3..f712df6f 100644
--- a/tests/cli/brain-dream-operator-surface.test.ts
+++ b/tests/cli/brain-dream-operator-surface.test.ts
@@ -19,7 +19,7 @@
* - with neither flag present the verb is byte-identical to today.
*/
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -28,6 +28,7 @@ import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { writeSignal } from "../../src/core/brain/signal.ts";
import { DREAM_PHASE } from "../../src/core/brain/dream-phases.ts";
import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+import { cmdBrainDream } from "../../src/cli/brain/verbs/dream.ts";
import { runCli } from "../helpers/run-cli.ts";
let tmp: string;
@@ -468,3 +469,65 @@ describe("MCP brain_dream carries the same two capabilities", () => {
expect(Object.keys(tool.inputSchema.properties)).toContain("gates");
});
});
+
+describe("a step that runs out of budget says so on the JSON stream", () => {
+ /**
+ * `--step` is driven IN PROCESS here rather than through `runCli`,
+ * because a deadline cannot be forced from outside: the config ladder
+ * accepts only non-negative whole seconds and reads `0` as "disabled",
+ * so no value a subprocess could be given makes a scan trip. A clock
+ * whose every reading is a day past the previous one does it instead -
+ * `createSafeguard` reads `Date.now`, which is exactly the path the
+ * verb takes - and it is the same technique `long-running-tools.test.ts`
+ * uses on the MCP side of the same contract.
+ */
+ async function stepJson(step: string): Promise<Record<string, unknown>> {
+ const written: string[] = [];
+ const realWrite = process.stdout.write.bind(process.stdout);
+ process.stdout.write = ((chunk: unknown) => {
+ written.push(String(chunk));
+ return true;
+ }) as typeof process.stdout.write;
+ let tick = 0;
+ const clock = spyOn(Date, "now").mockImplementation(() => {
+ tick += 1;
+ return tick * 86_400_000;
+ });
+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
+ try {
+ const code = await cmdBrainDream(["--step", step, "--vault", vault, "--json"]);
+ expect(code).toBe(1);
+ } finally {
+ clock.mockRestore();
+ process.stdout.write = realWrite;
+ delete process.env["OPEN_SECOND_BRAIN_CONFIG"];
+ }
+ return JSON.parse(written.join("")) as Record<string, unknown>;
+ }
+
+ test("the scan step marks a tripped deadline as timed_out", async () => {
+ seedPromotion();
+ const payload = await stepJson("scan");
+ expect(payload["ok"]).toBe(false);
+ expect(payload["step"]).toBe("scan");
+ // The contract `docs/cli-reference.md` states for every long-running
+ // operation: a machine caller must be able to tell a budget it can
+ // raise from a defect it cannot. Both other dream catches emit it.
+ expect(payload["timed_out"]).toBe(true);
+ expect(String(payload["message"])).toContain("safeguard timeout");
+ });
+
+ test("the heal-enrich step marks it the same way", async () => {
+ makeLinkableNotes();
+ const payload = await stepJson("heal-enrich");
+ expect(payload["ok"]).toBe(false);
+ expect(payload["step"]).toBe("heal-enrich");
+ expect(payload["timed_out"]).toBe(true);
+ });
+
+ test("a refusal is not a timeout: no marker on a step that cannot run", async () => {
+ const r = await runCli(["brain", "dream", "--step", "log", "--vault", vault, "--json"]);
+ expect(r.returncode).toBe(2);
+ expect(JSON.parse(r.stdout)["timed_out"]).toBeUndefined();
+ });
+});
diff --git a/tests/cli/brain-export.test.ts b/tests/cli/brain-export.test.ts
index 7fa086b5..feefdda6 100644
--- a/tests/cli/brain-export.test.ts
+++ b/tests/cli/brain-export.test.ts
@@ -3,10 +3,19 @@
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
+import { EXPORT_FORMAT, EXPORT_FORMATS } from "../../src/core/brain/export.ts";
import { runCli } from "../helpers/run-cli.ts";
let tmp: string;
@@ -161,4 +170,310 @@ describe("brain export", () => {
expect(r.returncode).toBe(0);
expect(r.stdout).toContain("export");
});
+
+ test("an unknown --format names every format the vocabulary declares", async () => {
+ await bootstrap();
+ const r = await runCli(["brain", "export", "--vault", vault, "--format", "yaml"], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: config },
+ });
+ expect(r.returncode).toBe(2);
+ // Whole tokens, not substrings: `"transcripts-jsonl".includes("json")`
+ // is true, so plain containment reported `json` as offered by a
+ // message that had stopped naming it.
+ const offered = new Set(r.stderr.split(/[^A-Za-z0-9_-]+/).filter((t) => t.length > 0));
+ for (const format of EXPORT_FORMATS) {
+ expect(`${format} offered: ${offered.has(format)}`).toBe(`${format} offered: true`);
+ }
+ });
+});
+
+describe("the format vocabulary is the only dispatch", () => {
+ test("the verb inlines no format literal of its own", () => {
+ // The type existed and nothing imported it: the guard was a pair of
+ // inline string comparisons, which is a contract declared with nothing
+ // behind it. A literal reappearing here is that defect coming back.
+ const source = readFileSync(
+ join(import.meta.dir, "..", "..", "src", "cli", "brain", "verbs", "export.ts"),
+ "utf8",
+ );
+ const inlined = EXPORT_FORMATS.filter((format) => source.includes(`"${format}"`));
+ expect(inlined).toEqual([]);
+ });
+});
+
+describe("brain export --format transcripts-jsonl", () => {
+ interface TranscriptFixture {
+ /** Turn id of the first line - the `turn_id` a record carries. */
+ readonly uuid?: string;
+ /** Basename of the transcript, which becomes the record's `session_id`. */
+ readonly file?: string;
+ /** Text of the user turn, for the cases that put something in it. */
+ readonly text?: string;
+ }
+
+ /** A two-turn Claude Code transcript under a fresh directory. */
+ function transcriptDir(opts: TranscriptFixture = {}): string {
+ const uuid = opts.uuid ?? "u-1";
+ const file = opts.file ?? "session.jsonl";
+ const dir = join(tmp, `transcripts-${uuid}-${file}`);
+ mkdirSync(dir, { recursive: true });
+ const lines = [
+ {
+ parentUuid: null,
+ sessionId: "sess-1",
+ entrypoint: "cli",
+ type: "user",
+ uuid,
+ timestamp: "2026-08-01T10:00:00.000Z",
+ message: { role: "user", content: opts.text ?? "what does this verb do" },
+ },
+ {
+ parentUuid: uuid,
+ sessionId: "sess-1",
+ entrypoint: "cli",
+ type: "assistant",
+ uuid: "a-1",
+ timestamp: "2026-08-01T10:00:01.000Z",
+ message: { role: "assistant", content: "it exports the corpus" },
+ },
+ ];
+ writeFileSync(join(dir, file), lines.map((l) => JSON.stringify(l)).join("\n") + "\n", "utf8");
+ return dir;
+ }
+
+ test("emits one JSONL conversation record per transcript, with no vault involved", async () => {
+ // The corpus is on the machine, not in the vault, so this format asks
+ // for no vault - a format that never reads one must not refuse for the
+ // want of one.
+ const dir = transcriptDir();
+ const r = await runCli(
+ ["brain", "export", "--format", EXPORT_FORMAT.transcriptsJsonl, "--transcripts", dir],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(r.returncode).toBe(0);
+ const lines = r.stdout.trimEnd().split("\n");
+ expect(lines.length).toBe(1);
+ const record = JSON.parse(lines[0]!) as {
+ runtime: string;
+ session_id: string;
+ messages: ReadonlyArray<{ role: string; text: string }>;
+ };
+ expect(record.runtime).toBe("claude");
+ expect(record.session_id).toBe("session.jsonl");
+ expect(record.messages.map((m) => m.role)).toEqual(["user", "assistant"]);
+ });
+
+ test("without --transcripts the format refuses and names the flag", async () => {
+ const r = await runCli(["brain", "export", "--format", EXPORT_FORMAT.transcriptsJsonl], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: config },
+ });
+ expect(r.returncode).toBe(2);
+ expect(r.stderr).toContain("--transcripts");
+ });
+
+ test("a record with a secret-shaped identifier is refused and nothing is written", async () => {
+ // Transcripts are the highest-risk corpus in the vault's orbit: a key
+ // pasted into a prompt is recorded verbatim, and an identifier cannot
+ // be redacted without renaming what it identifies. So the export stops.
+ const dir = transcriptDir({ uuid: "sk-live-9f2ba7c1d4e8" });
+ const out = join(tmp, "corpus.jsonl");
+ const r = await runCli(
+ [
+ "brain",
+ "export",
+ "--format",
+ EXPORT_FORMAT.transcriptsJsonl,
+ "--transcripts",
+ dir,
+ "--out",
+ out,
+ ],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(r.returncode).toBe(1);
+ expect(r.stderr).toContain("refused to write");
+ expect(r.stderr).toContain("turn_id");
+ expect(existsSync(out)).toBe(false);
+ expect(r.stdout).toBe("");
+ });
+
+ test("an empty result says how much it looked at rather than writing nothing", async () => {
+ const dir = transcriptDir();
+ const r = await runCli(
+ [
+ "brain",
+ "export",
+ "--format",
+ EXPORT_FORMAT.transcriptsJsonl,
+ "--transcripts",
+ dir,
+ "--since",
+ "2027-01-01T00:00:00Z",
+ ],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(r.returncode).toBe(0);
+ expect(r.stdout).toBe("");
+ expect(r.stderr).toContain("1 transcript");
+ });
+
+ test("a secret-shaped FILENAME is refused without the refusal printing it", async () => {
+ // The one path whose entire purpose is not letting this value out was
+ // the path that wrote it to stderr - into CI logs and shell
+ // scrollback - because the refusal prefixed the guard's sentence with
+ // the record's `session_id`, which IS the transcript's basename. The
+ // guard's own message is careful about exactly this: "(Locations, not
+ // values: the identifier is the secret.)"
+ const secret = "sk-live-9f2ba7c1d4e8.jsonl";
+ const dir = transcriptDir({ file: secret });
+ const out = join(tmp, "corpus.jsonl");
+ const r = await runCli(
+ [
+ "brain",
+ "export",
+ "--format",
+ EXPORT_FORMAT.transcriptsJsonl,
+ "--transcripts",
+ dir,
+ "--out",
+ out,
+ ],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(r.returncode).toBe(1);
+ expect(r.stderr).toContain("refused to write");
+ expect(r.stderr).toContain("session_id");
+ // Neither the whole filename nor the credential inside it.
+ expect(r.stderr).not.toContain(secret);
+ expect(r.stderr).not.toContain("sk-live-9f2ba7c1d4e8");
+ // Still locatable: the runtime and the instant it started are not
+ // identifiers and are safe to name.
+ expect(r.stderr).toContain("claude");
+ expect(r.stderr).toContain("2026-08-01T10:00:00.000Z");
+ expect(existsSync(out)).toBe(false);
+ expect(r.stdout).toBe("");
+ });
+
+ test("the refusal still names the transcript when the name is not the secret", async () => {
+ // The complement: withholding the name unconditionally would make
+ // every ordinary refusal harder to act on for no gain.
+ const dir = transcriptDir({ uuid: "sk-live-9f2ba7c1d4e8", file: "ordinary.jsonl" });
+ const r = await runCli(
+ ["brain", "export", "--format", EXPORT_FORMAT.transcriptsJsonl, "--transcripts", dir],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(r.returncode).toBe(1);
+ expect(r.stderr).toContain("ordinary.jsonl");
+ });
+
+ test("a BARE high-entropy filename is refused, not exported under exit 0", async () => {
+ // Vendor-prefixed refused the whole run; an unprefixed 24-character
+ // mixed run in the same position exported verbatim. `session_id` is a
+ // foreign harness's filename, so "ids are long mixed runs by
+ // construction" - an argument about ids this vault generates - does
+ // not carry over to it.
+ const dir = transcriptDir({ file: "Xk7Qp2Rm9Wz4Tn6Yb8Vc3Ld5.jsonl" });
+ const out = join(tmp, "corpus.jsonl");
+ const r = await runCli(
+ [
+ "brain",
+ "export",
+ "--format",
+ EXPORT_FORMAT.transcriptsJsonl,
+ "--transcripts",
+ dir,
+ "--out",
+ out,
+ ],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(r.returncode).toBe(1);
+ expect(r.stderr).toContain("session_id");
+ expect(r.stderr).not.toContain("Xk7Qp2Rm9Wz4Tn6Yb8Vc3Ld5");
+ expect(existsSync(out)).toBe(false);
+ });
+
+ test("the transcript branch REDACTS a key pasted into a turn, and says so", async () => {
+ // Every existing test on this branch pinned a REFUSAL. Nothing asserted
+ // that the released corpus is redacted at all, and nothing covered the
+ // notice that tells the operator the copy no longer matches the source.
+ // The payload is the shape a key actually takes in a transcript:
+ // a prefixed environment assignment, which the key-name pass could not
+ // see at all until the `\b` at the front of it was replaced.
+ const dir = transcriptDir({ text: "run `export ANTHROPIC_API_KEY=hunter2secretvalue` first" });
+ const r = await runCli(
+ ["brain", "export", "--format", EXPORT_FORMAT.transcriptsJsonl, "--transcripts", dir],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(r.returncode).toBe(0);
+ expect(r.stdout).not.toContain("hunter2secretvalue");
+ expect(r.stdout).toContain("***REDACTED***");
+ // The variable name survives, so the line still says what was removed.
+ expect(r.stdout).toContain("ANTHROPIC_API_KEY");
+ expect(r.stderr).toContain("no longer matches the vault byte for byte");
+ });
+
+ test("an existing --out is refused before the corpus is read", async () => {
+ // The check used to sit after the handler, so `--out` naming a file
+ // that already exists read, hashed and redacted a whole machine's
+ // transcripts and then refused over a flag knowable from argv alone.
+ // A source that does not exist is what makes the ordering visible:
+ // whichever check runs first is the one that speaks.
+ const out = join(tmp, "corpus.jsonl");
+ writeFileSync(out, "existing bytes\n", "utf8");
+ const r = await runCli(
+ [
+ "brain",
+ "export",
+ "--format",
+ EXPORT_FORMAT.transcriptsJsonl,
+ "--transcripts",
+ join(tmp, "no-such-transcripts"),
+ "--out",
+ out,
+ ],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(r.returncode).toBe(1);
+ expect(r.stderr).toContain("--force");
+ expect(r.stderr).not.toContain("no-such-transcripts");
+ expect(readFileSync(out, "utf8")).toBe("existing bytes\n");
+ });
+
+ test("a zero-byte transcript does not abort the run", async () => {
+ const dir = transcriptDir();
+ writeFileSync(join(dir, "flushed-nothing.jsonl"), "", "utf8");
+ const r = await runCli(
+ ["brain", "export", "--format", EXPORT_FORMAT.transcriptsJsonl, "--transcripts", dir],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(r.returncode).toBe(0);
+ expect(r.stdout.trimEnd().split("\n").length).toBe(1);
+ });
+
+ test("--out receives the corpus and stdout stays empty", async () => {
+ const dir = transcriptDir();
+ const out = join(tmp, "corpus.jsonl");
+ const r = await runCli(
+ [
+ "brain",
+ "export",
+ "--format",
+ EXPORT_FORMAT.transcriptsJsonl,
+ "--transcripts",
+ dir,
+ "--out",
+ out,
+ ],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(r.returncode).toBe(0);
+ const written = readFileSync(out, "utf8");
+ expect(written.trimEnd().split("\n").length).toBe(1);
+ expect(JSON.parse(written.trimEnd()) as { session_id: string }).toMatchObject({
+ session_id: "session.jsonl",
+ });
+ // The spool is consumed by the rename, never left beside the target.
+ expect(readdirSync(tmp).filter((n) => n.includes("o2b-transcripts-"))).toEqual([]);
+ });
});
diff --git a/tests/cli/error-chain.test.ts b/tests/cli/error-chain.test.ts
new file mode 100644
index 00000000..c23fe0eb
--- /dev/null
+++ b/tests/cli/error-chain.test.ts
@@ -0,0 +1,84 @@
+/**
+ * `describeErrorChain` - the CLI renderer that stopped throwing away `cause`.
+ *
+ * GitHub #167 is the case this exists for. The snapshot gate's id-exhaustion
+ * error attaches the real failure as `cause`; every catch arm rendered
+ * `(exc as Error).message` and stopped, so the operator saw a summary that
+ * was not merely incomplete but WRONG - it described a full archive directory
+ * while the cause said `mkdir Brain/.snapshots` had failed. An error that
+ * builds a `cause` has already decided the detail is load-bearing.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { describeErrorChain, failWith } from "../../src/cli/output.ts";
+
+describe("describeErrorChain", () => {
+ test("renders a bare error as its own message", () => {
+ expect(describeErrorChain(new Error("plain failure"))).toBe("plain failure");
+ });
+
+ test("renders the cause behind the message", () => {
+ const cause = new Error("EEXIST: file already exists, mkdir '/v/Brain/.snapshots'");
+ expect(describeErrorChain(new Error("could not reserve a unique run id", { cause }))).toBe(
+ "could not reserve a unique run id; caused by: " +
+ "EEXIST: file already exists, mkdir '/v/Brain/.snapshots'",
+ );
+ });
+
+ test("renders a nested chain in order", () => {
+ const inner = new Error("inner");
+ const middle = new Error("middle", { cause: inner });
+ expect(describeErrorChain(new Error("outer", { cause: middle }))).toBe(
+ "outer; caused by: middle; caused by: inner",
+ );
+ });
+
+ test("skips a cause the outer message already quotes", () => {
+ // The common wrapper re-states its cause; printing it twice reads as two
+ // separate failures.
+ const cause = new Error("no space left on device");
+ expect(describeErrorChain(new Error("zstd failed: no space left on device", { cause }))).toBe(
+ "zstd failed: no space left on device",
+ );
+ });
+
+ test("terminates on a cyclic chain instead of hanging", () => {
+ const a = new Error("a") as Error & { cause?: unknown };
+ const b = new Error("b") as Error & { cause?: unknown };
+ a.cause = b;
+ b.cause = a;
+ // Bounded walk: it returns, and it returns something finite.
+ expect(describeErrorChain(a).length).toBeLessThan(200);
+ expect(describeErrorChain(a)).toContain("caused by: b");
+ });
+
+ test("renders a non-Error throw as its own text", () => {
+ expect(describeErrorChain("just a string")).toBe("just a string");
+ expect(describeErrorChain(null)).toBe("null");
+ });
+});
+
+describe("failWith", () => {
+ test("puts the cause on stderr with the action line", () => {
+ const written: string[] = [];
+ const original = process.stderr.write.bind(process.stderr);
+ (process.stderr as unknown as { write: unknown }).write = (chunk: string): boolean => {
+ written.push(chunk);
+ return true;
+ };
+ try {
+ const code = failWith(
+ "take a snapshot",
+ new Error("gate refused", { cause: new Error("Brain/.snapshots is a regular file") }),
+ );
+ expect(code).toBe(1);
+ } finally {
+ (process.stderr as unknown as { write: unknown }).write = original;
+ }
+ expect(written.join("")).toBe(
+ "error: failed to take a snapshot: gate refused; caused by: " +
+ "Brain/.snapshots is a regular file\n",
+ );
+ });
+});
diff --git a/tests/cli/export-transcripts-streaming.test.ts b/tests/cli/export-transcripts-streaming.test.ts
new file mode 100644
index 00000000..4cbc1e05
--- /dev/null
+++ b/tests/cli/export-transcripts-streaming.test.ts
@@ -0,0 +1,131 @@
+/**
+ * `o2b brain export --format transcripts-jsonl` must not hold the corpus.
+ *
+ * The producer already streams and says so. `streamTranscriptConversations`
+ * is a generator whose docblock promises "the corpus is never held whole",
+ * and `read-lines.ts` beneath it never materialises a file. The CONSUMER
+ * collected every released record into an array and `join`ed it, which put
+ * the corpus in memory twice over and made both promises worthless - on a
+ * release whose whole subject is not materialising transcripts.
+ *
+ * ## What is asserted, and why it is not a memory number
+ *
+ * Peak RSS was tried first and does not discriminate. On this workstation
+ * a 63 MB corpus grew the child process's peak resident set by ~66 MB
+ * whether the records were spooled or buffered, because what dominates is
+ * uncollected `JSON.parse` garbage rather than anything the loop retains -
+ * the same finding `sessions/streaming-memory.test.ts` records for the
+ * layer below, and the same reason it measures the reader's own window
+ * instead.
+ *
+ * So the property is asserted directly: record N is written before record
+ * N+1 is asked for. That is exact, deterministic, and it is what "the
+ * corpus is never held whole" MEANS for a consumer. A buffering consumer
+ * produces every record before it writes any of them and fails the first
+ * assertion here by construction.
+ *
+ * The second half of the pair is the guarantee a naive streaming fix would
+ * have traded away: a refusal must leave nothing written. That one is
+ * observable from outside and is asserted end-to-end in
+ * `tests/cli/brain-export.test.ts`.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { spoolTranscriptCorpus } from "../../src/cli/brain/verbs/export.ts";
+import {
+ TRANSCRIPT_EXPORT_SCHEMA_VERSION,
+ type TranscriptConversation,
+ type TranscriptExportSummary,
+} from "../../src/core/brain/export-transcripts.ts";
+
+function conversation(index: number): TranscriptConversation {
+ const at = new Date(Date.UTC(2026, 0, 1) + index * 1000).toISOString();
+ return {
+ schema: TRANSCRIPT_EXPORT_SCHEMA_VERSION,
+ runtime: "claude",
+ session_id: `s${index}.jsonl`,
+ started_at: at,
+ ended_at: at,
+ message_count: 1,
+ messages: [{ turn_id: `t-${index}`, role: "user", timestamp: at, text: `turn ${index}` }],
+ };
+}
+
+const SUMMARY: TranscriptExportSummary = {
+ scanned: 4,
+ exported: 4,
+ other_runtime: 0,
+ outside_window: 0,
+ no_messages: 0,
+ empty: 0,
+};
+
+describe("the transcript consumer writes as it reads", () => {
+ test("each record is written before the next one is produced", async () => {
+ const trace: string[] = [];
+ async function* records(): AsyncGenerator<TranscriptConversation, TranscriptExportSummary> {
+ for (let i = 0; i < 4; i++) {
+ trace.push(`produced ${i}`);
+ yield conversation(i);
+ }
+ return SUMMARY;
+ }
+
+ const outcome = await spoolTranscriptCorpus(records(), (line) => {
+ trace.push(`wrote ${(JSON.parse(line) as { session_id: string }).session_id}`);
+ });
+
+ expect(outcome).toMatchObject({ kind: "written", written: 4, redacted: false });
+ // Strictly interleaved. A consumer holding the corpus produces all
+ // four and only then writes all four.
+ expect(trace).toEqual([
+ "produced 0",
+ "wrote s0.jsonl",
+ "produced 1",
+ "wrote s1.jsonl",
+ "produced 2",
+ "wrote s2.jsonl",
+ "produced 3",
+ "wrote s3.jsonl",
+ ]);
+ });
+
+ test("nothing is written once a record is refused, and the walk stops there", async () => {
+ const trace: string[] = [];
+ async function* records(): AsyncGenerator<TranscriptConversation, TranscriptExportSummary> {
+ trace.push("produced 0");
+ yield conversation(0);
+ trace.push("produced 1");
+ yield { ...conversation(1), session_id: "sk-live-9f2ba7c1d4e8.jsonl" };
+ trace.push("produced 2");
+ yield conversation(2);
+ return SUMMARY;
+ }
+
+ const outcome = await spoolTranscriptCorpus(records(), (line) => {
+ trace.push(`wrote ${(JSON.parse(line) as { session_id: string }).session_id}`);
+ });
+
+ expect(outcome.kind).toBe("refused");
+ // The generator is abandoned at the refusal: record 2 is never asked
+ // for, so no transcript after the offending one is even opened.
+ expect(trace).toEqual(["produced 0", "wrote s0.jsonl", "produced 1"]);
+ if (outcome.kind === "refused") {
+ // And the refusal does not echo the name it refused.
+ expect(outcome.detail).not.toContain("sk-live-9f2ba7c1d4e8");
+ expect(outcome.detail).toContain("session_id");
+ }
+ });
+
+ test("the summary rides out of the generator rather than being discarded", async () => {
+ async function* records(): AsyncGenerator<TranscriptConversation, TranscriptExportSummary> {
+ return { ...SUMMARY, scanned: 7, exported: 0, empty: 7 };
+ }
+ const outcome = await spoolTranscriptCorpus(records(), () => {
+ throw new Error("nothing to write");
+ });
+ expect(outcome).toMatchObject({ kind: "written", written: 0 });
+ if (outcome.kind === "written") expect(outcome.summary.empty).toBe(7);
+ });
+});
diff --git a/tests/cli/forward-pointer-rail.test.ts b/tests/cli/forward-pointer-rail.test.ts
index cedfdbfc..55050462 100644
--- a/tests/cli/forward-pointer-rail.test.ts
+++ b/tests/cli/forward-pointer-rail.test.ts
@@ -123,6 +123,16 @@ const SANCTIONED: Readonly<Record<string, SanctionedPointer>> = Object.freeze({
"command to run next, and routing it through the rail would advise the operator to reinstall " +
"the very symlinks the paragraph is about removing.",
},
+ "src/cli/state.ts :: o2b state rollback": {
+ count: 1,
+ reason:
+ "the undo line on a completed `state migrate --apply` receipt, which must name the " +
+ "destination the operator chose seconds earlier: `o2b state rollback --from <that dir>`. " +
+ "The rail resolves ONE structural command per diagnostic code and has no parameter through " +
+ "which a runtime path can enter, by design - so a registered signal here could only name a " +
+ "command that does not run. It sits beside the manifest path in the same receipt for the " +
+ "same reason: both are facts about the move that just happened.",
+ },
});
/** A reason has to say something; a placeholder cannot reach this. */
@@ -283,9 +293,11 @@ describe("the rail is the only forward-pointer mechanism", () => {
test("the sanctioned table stays an exception", () => {
// Every measured site is sanctioned (test one), so the table's size
- // IS the number of unmigrated sites. Four is the ceiling this change
- // leaves behind; a fifth needs its own argument.
- expect(Object.keys(SANCTIONED).length).toBeLessThanOrEqual(4);
+ // IS the number of unmigrated sites. Four was the ceiling that change
+ // left behind; the fifth is `state migrate`'s undo line, which the
+ // rail structurally cannot carry because it interpolates the
+ // destination the operator just named. A sixth needs its own argument.
+ expect(Object.keys(SANCTIONED).length).toBeLessThanOrEqual(5);
});
});
diff --git a/tests/cli/install-config-scope.test.ts b/tests/cli/install-config-scope.test.ts
new file mode 100644
index 00000000..a4f4abeb
--- /dev/null
+++ b/tests/cli/install-config-scope.test.ts
@@ -0,0 +1,166 @@
+/**
+ * One run, one config file - and one refusal, printed as one line.
+ *
+ * Two operator-visible defects live at the same seam:
+ *
+ * 1. `o2b install --config <p>` used to parameterise only half the run.
+ * The agent name, timezone and vault came from `<p>`; the
+ * install-settings ladder (`install_hook_timeout_seconds`,
+ * `mcp_tool_profile`) came from the machine default, because
+ * `InstallEnv` carried no config path and the resolver fell back. On
+ * a machine with both files populated, `--apply` generated from one
+ * and `--check` verified against the other.
+ * 2. An unreadable `<vault>/Brain/_brain.yaml` escaped `main()` as a
+ * stack trace. The refusal is correct - a writer cannot infer intent
+ * from bytes it could not parse - but `main()` handled only
+ * `CliError`, `NoVaultConfiguredError` and `ConfigReadError`, so a
+ * single typo crashed plain `o2b install` before it printed the
+ * status of ANY target, including the nine that never read that file.
+ */
+
+import { describe, expect, test, beforeEach, afterEach, setDefaultTimeout } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
+import { runCli as baseRunCli, type RunCliOptions, type RunResult } from "../helpers/run-cli.ts";
+import { INSTALL_EXIT } from "../../src/cli/install/install.ts";
+
+function runCli(args: ReadonlyArray<string>, opts: RunCliOptions = {}): Promise<RunResult> {
+ return baseRunCli(args, { ...opts, subprocess: true });
+}
+
+setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
+
+let vault: string;
+let home: string;
+/** The file the MACHINE would pick if nobody passed `--config`. */
+let machineConfig: string;
+/** The file the operator names on the command line. */
+let namedConfig: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "osb-cfgscope-v-"));
+ home = mkdtempSync(join(tmpdir(), "osb-cfgscope-h-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ mkdirSync(join(home, ".config", "open-second-brain"), { recursive: true });
+ machineConfig = join(home, ".config", "open-second-brain", "config.yaml");
+ namedConfig = join(home, "named.yaml");
+ const body = `vault: "${vault}"\nagent_name: "claude-vps"\ntimezone: "UTC"\n`;
+ writeFileSync(machineConfig, `${body}mcp_tool_profile: recall\n`);
+ writeFileSync(namedConfig, `${body}mcp_tool_profile: minimal\n`);
+});
+
+afterEach(() => {
+ for (const p of [vault, home]) {
+ try {
+ rmSync(p, { recursive: true, force: true });
+ } catch {
+ // temp cleanup is best-effort
+ }
+ }
+});
+
+/**
+ * A shell that has named NEITHER `OPEN_SECOND_BRAIN_CONFIG` nor
+ * `XDG_CONFIG_HOME`, so the machine default really is `$HOME/.config/...`
+ * and `--config` is the only thing that can point elsewhere.
+ */
+function bareEnv(extra: Record<string, string> = {}): Record<string, string> {
+ return { HOME: home, ...extra };
+}
+
+function cursorArgs(): ReadonlyArray<string> {
+ const parsed = JSON.parse(readFileSync(join(home, ".cursor", "mcp.json"), "utf8")) as {
+ mcpServers: Record<string, { args: string[] }>;
+ };
+ return parsed.mcpServers["open-second-brain"]!.args;
+}
+
+describe("--config parameterises the whole run", () => {
+ test("the named file supplies the tool profile, not the machine default", async () => {
+ const applied = await runCli(
+ ["install", "--target", "cursor", "--config", namedConfig, "--apply"],
+ { env: bareEnv() },
+ );
+ expect(applied.returncode).toBe(INSTALL_EXIT.ok);
+ const args = cursorArgs();
+ expect(args).toContain("minimal");
+ expect(args).not.toContain("recall");
+ });
+
+ test("--check against the same file reports no drift", async () => {
+ await runCli(["install", "--target", "cursor", "--config", namedConfig, "--apply"], {
+ env: bareEnv(),
+ });
+ const checked = await runCli(
+ ["install", "--check", "--target", "cursor", "--config", namedConfig],
+ { env: bareEnv() },
+ );
+ expect(`${checked.returncode}: ${checked.stdout}`).toContain("ok");
+ expect(checked.returncode).toBe(INSTALL_EXIT.ok);
+ });
+
+ test("--check against the OTHER file honestly reports drift", async () => {
+ // The two files disagree, so they must produce different bytes and the
+ // check must say so. This is the control for the case above: a fix
+ // that made every config path resolve to the same answer would pass
+ // the first two cases and fail this one.
+ await runCli(["install", "--target", "cursor", "--config", namedConfig, "--apply"], {
+ env: bareEnv(),
+ });
+ const checked = await runCli(
+ ["install", "--check", "--target", "cursor", "--config", machineConfig],
+ { env: bareEnv() },
+ );
+ expect(checked.returncode).toBe(INSTALL_EXIT.drift);
+ });
+});
+
+describe("an unreadable _brain.yaml is one line, not a stack trace", () => {
+ beforeEach(() => {
+ writeFileSync(
+ join(vault, "Brain", "_brain.yaml"),
+ "schema_version: 1\ninstall:\n tool_profile: [broken\n",
+ );
+ });
+
+ test("plain `o2b install` refuses with exit 1 and names the file", async () => {
+ const result = await runCli(["install", "--config", namedConfig], { env: bareEnv() });
+ expect(result.returncode).toBe(1);
+ expect(result.stderr).toContain("error: ");
+ expect(result.stderr).toContain(join(vault, "Brain", "_brain.yaml"));
+ // A stack trace is the failure this case exists to prevent; the whole
+ // refusal is one line.
+ expect(result.stderr.trimEnd().split("\n").length).toBe(1);
+ });
+
+ test("`o2b install --check` refuses the same way", async () => {
+ const result = await runCli(["install", "--check", "--config", namedConfig], {
+ env: bareEnv(),
+ });
+ expect(result.returncode).toBe(1);
+ expect(result.stderr).toContain(join(vault, "Brain", "_brain.yaml"));
+ });
+
+ test("`o2b install --friction` stays a report and still exits 0", async () => {
+ // A report has no notion of a bad answer, only of an honest one, so
+ // the unresolvable cells name the refusal instead of taking the whole
+ // surface down with them.
+ const result = await runCli(["install", "--friction", "--json", "--config", namedConfig], {
+ env: bareEnv(),
+ });
+ expect(result.returncode).toBe(INSTALL_EXIT.ok);
+ const parsed = JSON.parse(result.stdout) as {
+ friction: {
+ targets: Array<{ target: string; cells: Array<{ value: string; detail: string | null }> }>;
+ };
+ };
+ const unresolved = parsed.friction.targets.flatMap((t) =>
+ t.cells.filter((c) => c.value === "unresolved"),
+ );
+ expect(unresolved.length).toBeGreaterThan(0);
+ for (const cell of unresolved) expect(cell.detail ?? "").toContain("_brain.yaml");
+ });
+});
diff --git a/tests/cli/install-friction.test.ts b/tests/cli/install-friction.test.ts
new file mode 100644
index 00000000..35b05794
--- /dev/null
+++ b/tests/cli/install-friction.test.ts
@@ -0,0 +1,255 @@
+/**
+ * `o2b install --friction` β€” the operator surface of the friction matrix.
+ *
+ * The verb's other modes are covered by `install-verb.test.ts`; this file
+ * covers the comparison mode and the two properties it exists for: the
+ * table is derived from the live registry, and the DIFF form names only
+ * the dimensions the two hosts answer differently. A diff that reprints
+ * the dimensions they share is a table, so the silence is asserted
+ * against the matrix itself rather than against a copied list.
+ */
+
+import { describe, expect, test, beforeEach, afterEach, setDefaultTimeout } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
+import { runCli as baseRunCli, type RunCliOptions, type RunResult } from "../helpers/run-cli.ts";
+import { INSTALL_EXIT } from "../../src/cli/install/install.ts";
+import { FRICTION_DIMENSIONS } from "../../src/core/install/friction.ts";
+import { INSTALL_TARGET_IDS } from "../../src/core/runtime/host-facts.ts";
+
+// The adapters resolve the target home at module-load time, so each call
+// needs a fresh process to honour this file's per-case temp HOME.
+function runCli(args: ReadonlyArray<string>, opts: RunCliOptions = {}): Promise<RunResult> {
+ return baseRunCli(args, { ...opts, subprocess: true });
+}
+
+setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
+
+let vault: string;
+let home: string;
+let configPath: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "osb-friction-cli-v-"));
+ home = mkdtempSync(join(tmpdir(), "osb-friction-cli-h-"));
+ configPath = join(home, "config.yaml");
+ writeFileSync(configPath, `vault: "${vault}"\nagent_name: "claude-vps"\ntimezone: "UTC"\n`);
+});
+
+afterEach(() => {
+ for (const p of [vault, home]) {
+ try {
+ rmSync(p, { recursive: true, force: true });
+ } catch {
+ // temp cleanup is best-effort
+ }
+ }
+});
+
+function envBase(extra: Record<string, string> = {}) {
+ return {
+ HOME: home,
+ OPEN_SECOND_BRAIN_CONFIG: configPath,
+ VAULT_DIR: vault,
+ VAULT_AGENT_NAME: "claude-vps",
+ VAULT_TIMEZONE: "UTC",
+ ...extra,
+ };
+}
+
+/**
+ * The identifier tokens of `text`, split on everything an id cannot hold.
+ *
+ * Plain containment let a SHORTER id ride on a longer one:
+ * `"copilot-cli".includes("pi")` is true, so "every registered target is
+ * listed" held for a table that had dropped the `pi` row entirely, and the
+ * refusal message satisfied all ten names while offering nine. A token set
+ * answers the question the assertion means to ask.
+ */
+function tokensOf(text: string): ReadonlySet<string> {
+ return new Set(text.split(/[^A-Za-z0-9_-]+/).filter((token) => token.length > 0));
+}
+
+interface FrictionCellJson {
+ readonly dimension: string;
+ readonly value: string;
+ readonly detail: string | null;
+}
+
+interface FrictionTargetJson {
+ readonly target: string;
+ readonly label: string;
+ readonly cells: ReadonlyArray<FrictionCellJson>;
+}
+
+interface FrictionJson {
+ readonly schema_version: number;
+ readonly friction: {
+ readonly dimensions: ReadonlyArray<string>;
+ readonly targets: ReadonlyArray<FrictionTargetJson>;
+ };
+}
+
+interface FrictionDiffJson {
+ readonly schema_version: number;
+ readonly friction_diff: {
+ readonly base: string;
+ readonly compare: string;
+ readonly shared: number;
+ readonly differing: ReadonlyArray<{
+ readonly dimension: string;
+ readonly base_value: string;
+ readonly compare_value: string;
+ }>;
+ };
+}
+
+async function frictionJson(extra: ReadonlyArray<string> = []): Promise<FrictionJson> {
+ const r = await runCli(["install", "--friction", "--json", ...extra], { env: envBase() });
+ expect(`exit ${r.returncode}\n${r.stderr}`).toBe("exit 0\n");
+ return JSON.parse(r.stdout) as FrictionJson;
+}
+
+describe("o2b install --friction β€” the matrix", () => {
+ test("the human table carries every registered target and every dimension", async () => {
+ const r = await runCli(["install", "--friction"], { env: envBase() });
+ expect(r.returncode).toBe(INSTALL_EXIT.ok);
+ const printed = tokensOf(r.stdout);
+ for (const target of INSTALL_TARGET_IDS) {
+ expect(`${target} listed: ${printed.has(target)}`).toBe(`${target} listed: true`);
+ }
+ for (const dimension of FRICTION_DIMENSIONS) {
+ expect(`${dimension} listed: ${printed.has(dimension)}`).toBe(`${dimension} listed: true`);
+ }
+ });
+
+ test("--json is machine-readable and versioned", async () => {
+ const payload = await frictionJson();
+ expect(payload.schema_version).toBe(1);
+ expect(payload.friction.dimensions).toEqual([...FRICTION_DIMENSIONS]);
+ expect(payload.friction.targets.map((t) => t.target).toSorted()).toEqual(
+ [...INSTALL_TARGET_IDS].toSorted(),
+ );
+ for (const target of payload.friction.targets) {
+ expect(target.cells.map((c) => c.dimension)).toEqual([...FRICTION_DIMENSIONS]);
+ }
+ });
+
+ test("--target narrows the matrix to one host", async () => {
+ const payload = await frictionJson(["--target", "cursor"]);
+ expect(payload.friction.targets.map((t) => t.target)).toEqual(["cursor"]);
+ });
+
+ test("an unknown --target is refused by name, with the known list", async () => {
+ const r = await runCli(["install", "--friction", "--target", "claude-code"], {
+ env: envBase(),
+ });
+ expect(r.returncode).toBe(INSTALL_EXIT.usage);
+ expect(r.stderr).toContain("claude-code");
+ const offered = tokensOf(r.stderr);
+ for (const target of INSTALL_TARGET_IDS) {
+ expect(`${target} offered: ${offered.has(target)}`).toBe(`${target} offered: true`);
+ }
+ });
+});
+
+describe("o2b install --friction --base <a> --compare <b> β€” the diff", () => {
+ test("it names every dimension the two answer differently and no other", async () => {
+ const matrix = await frictionJson();
+ const row = (target: string): ReadonlyArray<FrictionCellJson> =>
+ matrix.friction.targets.find((t) => t.target === target)!.cells;
+ const r = await runCli(
+ ["install", "--friction", "--base", "cursor", "--compare", "pi", "--json"],
+ { env: envBase() },
+ );
+ expect(`exit ${r.returncode}\n${r.stderr}`).toBe("exit 0\n");
+ const diff = (JSON.parse(r.stdout) as FrictionDiffJson).friction_diff;
+ const named = new Set(diff.differing.map((d) => d.dimension));
+ const wrong: string[] = [];
+ for (const dimension of FRICTION_DIMENSIONS) {
+ const base = row("cursor").find((c) => c.dimension === dimension)!;
+ const compare = row("pi").find((c) => c.dimension === dimension)!;
+ if ((base.value !== compare.value) !== named.has(dimension)) wrong.push(dimension);
+ }
+ expect(wrong.join(", ")).toBe("");
+ expect(diff.differing.length).toBeGreaterThan(0);
+ expect(diff.differing.length + diff.shared).toBe(FRICTION_DIMENSIONS.length);
+ });
+
+ test("the human diff prints the differing dimensions and says how many it withheld", async () => {
+ const r = await runCli(["install", "--friction", "--base", "cursor", "--compare", "pi"], {
+ env: envBase(),
+ });
+ expect(r.returncode).toBe(INSTALL_EXIT.ok);
+ // `pi` as a whole token: `copilot-cli` contains it as a substring, so
+ // plain containment would have accepted a diff that never named it.
+ const printed = tokensOf(r.stdout);
+ expect(`cursor: ${printed.has("cursor")}, pi: ${printed.has("pi")}`).toBe(
+ "cursor: true, pi: true",
+ );
+ expect(r.stdout).toContain("differ");
+ });
+
+ test("--base without --compare is a usage error naming the missing flag", async () => {
+ const r = await runCli(["install", "--friction", "--base", "cursor"], { env: envBase() });
+ expect(r.returncode).toBe(INSTALL_EXIT.usage);
+ expect(r.stderr).toContain("--compare");
+ });
+
+ test("an unknown --compare is refused by name", async () => {
+ const r = await runCli(
+ ["install", "--friction", "--base", "cursor", "--compare", "claude-code"],
+ { env: envBase() },
+ );
+ expect(r.returncode).toBe(INSTALL_EXIT.usage);
+ expect(r.stderr).toContain("claude-code");
+ });
+
+ test("--target alongside --base/--compare is refused rather than silently ignored", async () => {
+ const r = await runCli(
+ ["install", "--friction", "--target", "cursor", "--base", "cursor", "--compare", "pi"],
+ { env: envBase() },
+ );
+ expect(r.returncode).toBe(INSTALL_EXIT.usage);
+ expect(r.stderr).toContain("--target");
+ });
+});
+
+describe("the flags the friction mode added are advertised", () => {
+ test("help --json declares every flag o2b install parses", async () => {
+ const r = await runCli(["help", "--json"], { env: envBase() });
+ expect(r.returncode).toBe(0);
+ const manifest = JSON.parse(r.stdout) as {
+ commands: ReadonlyArray<{
+ name: string;
+ flags?: ReadonlyArray<{ name: string; inherited?: boolean }>;
+ }>;
+ };
+ const install = manifest.commands.find((c) => c.name === "install");
+ // `--json` is inherited by every verb and stated once in the help
+ // header, so parity is asserted over the flags this verb DECLARES.
+ const declared = (install?.flags ?? [])
+ .filter((f) => f.inherited !== true)
+ .map((f) => f.name)
+ .toSorted();
+ expect(declared).toEqual(
+ [
+ "apply",
+ "base",
+ "check",
+ "compare",
+ "config",
+ "dry-run",
+ "force",
+ "format",
+ "friction",
+ "out",
+ "target",
+ "vault",
+ ].toSorted(),
+ );
+ });
+});
diff --git a/tests/cli/mcp-scope-arg.test.ts b/tests/cli/mcp-scope-arg.test.ts
index 3271cdd6..267f8c95 100644
--- a/tests/cli/mcp-scope-arg.test.ts
+++ b/tests/cli/mcp-scope-arg.test.ts
@@ -3,6 +3,12 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { runCli } from "../helpers/run-cli.ts";
+import { INSTALL_TARGET_IDS, RUNTIME_FACTS } from "../../src/core/runtime/host-facts.ts";
+
+/** Whole tokens: `copilot-cli` contains `pi`, so containment over ids lies. */
+function tokensOf(text: string): ReadonlySet<string> {
+ return new Set(text.split(/[^A-Za-z0-9_-]+/).filter((token) => token.length > 0));
+}
describe("o2b mcp --scope arg validation", () => {
test("invalid scope value exits 2 with a clear error", async () => {
@@ -16,6 +22,45 @@ describe("o2b mcp --scope arg validation", () => {
const res = await runCli(["mcp", "--scope"], { stdin: "" });
expect(res.returncode).toBe(2);
});
+});
+
+describe("o2b mcp --host-target arg validation", () => {
+ test("an unrecognised runtime exits 2 and lists the known ones", async () => {
+ const res = await runCli(["mcp", "--host-target", "nope"], { stdin: "" });
+ expect(res.returncode).toBe(2);
+ expect(res.stderr).toContain("--host-target");
+ // Every known runtime, not just one of them: the refusal exists to
+ // tell the operator what they could have written instead.
+ const offered = tokensOf(res.stderr);
+ for (const target of INSTALL_TARGET_IDS) {
+ expect(`${target} offered: ${offered.has(target)}`).toBe(`${target} offered: true`);
+ }
+ });
+
+ test("a known runtime is reported back by the capability probe", async () => {
+ const tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-host-target-"));
+ try {
+ const res = await runCli(["mcp", "--probe", "--json", "--host-target", "cursor"], {
+ stdin: "",
+ env: { VAULT_DIR: tmp },
+ });
+ expect(res.returncode).toBe(0);
+ const parsed = JSON.parse(res.stdout) as {
+ capabilities: { host_ceiling: { target: string; kind: string; max_tools: number } };
+ };
+ // The number comes from the fact row the server reads, not from a
+ // literal copied out of it: the two cannot drift apart here.
+ const ceiling = RUNTIME_FACTS.cursor.toolCeiling;
+ expect(ceiling.kind).toBe("declared");
+ expect(parsed.capabilities.host_ceiling.target).toBe("cursor");
+ expect(parsed.capabilities.host_ceiling.kind).toBe(ceiling.kind);
+ expect(parsed.capabilities.host_ceiling.max_tools).toBe(
+ (ceiling as { maxTools: number }).maxTools,
+ );
+ } finally {
+ rmSync(tmp, { recursive: true, force: true });
+ }
+ });
describe("--scope writer with a vault", () => {
let tmp: string;
diff --git a/tests/cli/progress-emitter-census.test.ts b/tests/cli/progress-emitter-census.test.ts
index c4dabb32..36a0ec6c 100644
--- a/tests/cli/progress-emitter-census.test.ts
+++ b/tests/cli/progress-emitter-census.test.ts
@@ -19,9 +19,13 @@
*
* So this census is not a scan. It DRIVES each entry point for real, with
* progress on, against a fixture, and asserts that records carrying the
- * expected operation and stage actually arrived and that the stream was
- * terminated. Three properties follow, and they are why it is worth the
- * seconds it costs:
+ * expected operation and stage actually arrived, that at least one of them
+ * ADVANCED, and that the stream was terminated. The advance is the part
+ * that took a second pass to get right: a `started`/`finished` pair proves
+ * only that a counter was built, and three of the ten sites here were being
+ * vouched for by exactly that - see {@link EmitterSite.noAdvanceReason}.
+ * Three properties follow, and they are why it is worth the seconds it
+ * costs:
*
* 1. **No false positives.** A record either reached stderr or it did
* not. There is no pattern to match and therefore nothing to match
@@ -53,6 +57,10 @@
* by its enclosing top-level `function`, so a second
* `progressCounter(` in the same body would collapse onto the same
* key. Also a failure, for the same reason.
+ * - **The loop behind a site that declares `noAdvanceReason`.** Two do,
+ * and for both of them what is proven is that the stage opens and
+ * terminates - the ticking itself needs an embedding layer no test in
+ * this tree may depend on.
* - **An emitter reached only under conditions the fixture does not
* create** - a provider-backed embed batch, a lock contended by a
* second process. The fixture drives the DEFAULT path of each verb;
@@ -164,6 +172,21 @@ interface EmitterSite {
* and lends, so `lock` is what proves that counter ran.
*/
readonly stage: string;
+ /**
+ * Why this site's stream can carry `started` and `finished` but no
+ * `advanced` on the path the fixture drives.
+ *
+ * A `started`/`finished` pair proves the counter was CONSTRUCTED, and
+ * that is a weaker fact than it looks: commenting out the sole
+ * `progress.advance(...)` call in `runHealEnrichment` once left this
+ * census 3 pass / 0 fail, because the dream fixture had no user pages
+ * and the per-page loop never ran. So an `advanced` record is required
+ * by default, and a site that genuinely cannot produce one says so HERE
+ * with a reason rather than passing quietly. The exception is checked
+ * in both directions: a site declaring one that then advances is a
+ * failure too, so a stale reason cannot outlive the condition it names.
+ */
+ readonly noAdvanceReason?: string;
}
const EMITTERS: Readonly<Record<string, EmitterSite>> = Object.freeze({
@@ -182,10 +205,34 @@ const EMITTERS: Readonly<Record<string, EmitterSite>> = Object.freeze({
operation: OPERATION.dream,
stage: "scan",
},
+ // The two single-step units. Each opens its own stream because a step
+ // IS the run when it is asked for on its own - `runDreamStep`
+ // dispatches and owns no counter. Inside a full pass neither is handed
+ // a sink, so `dream()`'s own counter stays the only voice and these
+ // two stay inert; that is why the witness for each is its own entry
+ // point rather than the full-pass one.
+ "core/brain/dream-scan.ts#scanBrain": {
+ entryPoint: "o2b brain dream --step scan --progress",
+ operation: OPERATION.dream,
+ stage: "scan",
+ },
+ "core/brain/heal-run.ts#runHealEnrichment": {
+ entryPoint: "o2b brain dream --step heal-enrich --progress",
+ operation: OPERATION.dream,
+ stage: "heal-enrich",
+ },
"core/brain/link-graph/bridge-discovery.ts#discoverBridges": {
entryPoint: "o2b brain bridges discover --progress",
operation: OPERATION.bridges,
stage: "candidates",
+ // The candidate loop - the only thing that ticks - sits behind
+ // `store.vecLoaded() && store.countEmbeddings() > 0`. This fixture
+ // indexes with the lexical lane only, because an embedding layer
+ // means a provider key and a network call, which is the one thing
+ // every test in this tree refuses to depend on. The lane's own
+ // ticking is covered where an embedding store can be faked:
+ // `tests/core/brain/bridge-discovery.test.ts`.
+ noAdvanceReason: "the candidate loop needs an embedding layer this fixture cannot provide",
},
"core/brain/link-graph/communities.ts#detectCommunities": {
entryPoint: "o2b brain clusters run --progress",
@@ -206,6 +253,22 @@ const EMITTERS: Readonly<Record<string, EmitterSite>> = Object.freeze({
entryPoint: "o2b search vector-backfill --progress",
operation: OPERATION.reindex,
stage: "plan",
+ // This counter owns no loop at all: it opens the stage and LENDS
+ // itself to `runEmbeddingPhase`, which is entered only under
+ // `--apply` with a non-empty pending set - so an advance here would
+ // mean a provider call. What the default path proves is that the
+ // stage opens and terminates, which is the whole of what this site
+ // does on its own.
+ noAdvanceReason: "the counter is lent to the embedding phase, which only --apply enters",
+ },
+ // The machine-wide session sweep. One stage, because the walk is three
+ // orders of magnitude cheaper than the hashing (4 ms against 3.0 s over
+ // 596 MB) and a rail that announced the walk would be reporting on
+ // nothing.
+ "core/brain/sessions/discover.ts#discoverSessions": {
+ entryPoint: "o2b brain import-session --status --progress",
+ operation: OPERATION.sessions,
+ stage: "hash",
},
});
@@ -222,6 +285,9 @@ let dreamConfig: string;
/** A tiny project tree plus the vault its notes are written into. */
let archProject: string;
let archVault: string;
+/** A temp HOME holding a synthetic Claude Code store, plus a vault to sweep into. */
+let sessionHome: string;
+let sessionVault: string;
/**
* One run of one entry point, with `--progress` on.
@@ -245,8 +311,20 @@ const ENTRY_POINTS: Readonly<Record<string, () => Promise<RunResult>>> = Object.
runCli(["brain", "dream", "--dry-run", "--progress"], {
env: { OPEN_SECOND_BRAIN_CONFIG: dreamConfig },
}),
+ "o2b brain dream --step scan --progress": () =>
+ runCli(["brain", "dream", "--step", "scan", "--progress"], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: dreamConfig },
+ }),
+ "o2b brain dream --step heal-enrich --progress": () =>
+ runCli(["brain", "dream", "--step", "heal-enrich", "--progress"], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: dreamConfig },
+ }),
"o2b brain architect --progress": () =>
runCli(["brain", "architect", archProject, "--vault", archVault, "--progress"]),
+ "o2b brain import-session --status --progress": () =>
+ runCli(["brain", "import-session", "--status", "--vault", sessionVault, "--progress"], {
+ env: { HOME: sessionHome },
+ }),
});
beforeAll(async () => {
@@ -272,6 +350,23 @@ beforeAll(async () => {
dreamConfig = join(tmp, "dream-config.yaml");
atomicWriteFileSync(dreamConfig, `vault: ${dreamVault}\n`);
bootstrapBrain(dreamVault, { configPath: dreamConfig });
+ // User pages, because the heal-enrich pass ticks once per page and a
+ // vault with none opens its stage over a denominator of zero: the
+ // counter reports `started` and `finished` and never runs the loop the
+ // stage exists to report on. Two pages, each naming the other's title,
+ // so the pass has work as well as a denominator.
+ for (const [name, other] of [
+ ["canary-rollout", "Blast Radius"],
+ ["blast-radius", "Canary Rollout"],
+ ]) {
+ writeFileSync(
+ join(dreamVault, `${name}.md`),
+ `---\ntitle: ${name!
+ .split("-")
+ .map((w) => w[0]!.toUpperCase() + w.slice(1))
+ .join(" ")}\n---\n\nA note about ${other}.\n`,
+ );
+ }
for (const [i, date] of ["2026-05-20", "2026-05-21", "2026-05-22"].entries()) {
writeSignal(dreamVault, {
topic: "census-progress",
@@ -291,6 +386,18 @@ beforeAll(async () => {
writeFileSync(join(archProject, "src", "core", "engine.ts"), "// x\n");
archVault = join(tmp, "arch-vault");
mkdirSync(join(archVault, "Brain"), { recursive: true });
+
+ // A synthetic Claude Code store under a temp HOME. Three files, so the
+ // counter has a denominator and at least one `advanced` record to emit;
+ // the bytes are never parsed by the sweep, only hashed.
+ sessionHome = join(tmp, "session-home");
+ const projects = join(sessionHome, ".claude", "projects", "-srv-projects-demo");
+ mkdirSync(projects, { recursive: true });
+ for (const name of ["a", "b", "c"]) {
+ writeFileSync(join(projects, `${name}.jsonl`), `{"type":"user","uuid":"${name}"}\n`);
+ }
+ sessionVault = join(tmp, "session-vault");
+ mkdirSync(join(sessionVault, "Brain"), { recursive: true });
});
afterAll(() => {
@@ -366,13 +473,30 @@ describe("progress emitter census", () => {
for (const [site, decl] of Object.entries(EMITTERS)) {
const records = streams.get(decl.entryPoint) ?? [];
- const witnessed = records.some(
+ const witnessed = records.filter(
(r) => r["operation"] === decl.operation && r["stage"] === decl.stage,
);
- if (!witnessed) {
+ if (witnessed.length === 0) {
failures.push(
`${site}: no ${decl.operation}/${decl.stage} record arrived from \`${decl.entryPoint}\``,
);
+ continue;
+ }
+ // The unit of work, not just the construction of the counter. See
+ // `noAdvanceReason`.
+ const advanced = witnessed.some((r) => r["kind"] === PROGRESS_KIND.advanced);
+ if (!advanced && decl.noAdvanceReason === undefined) {
+ failures.push(
+ `${site}: \`${decl.entryPoint}\` opened and closed ${decl.operation}/${decl.stage} ` +
+ `without one advanced record - give the fixture something to advance over, ` +
+ `or declare noAdvanceReason`,
+ );
+ }
+ if (advanced && decl.noAdvanceReason !== undefined) {
+ failures.push(
+ `${site}: declared noAdvanceReason (${decl.noAdvanceReason}) but an advanced ` +
+ `record arrived - drop the exception`,
+ );
}
}
diff --git a/tests/cli/session-discovery.test.ts b/tests/cli/session-discovery.test.ts
new file mode 100644
index 00000000..9bc18120
--- /dev/null
+++ b/tests/cli/session-discovery.test.ts
@@ -0,0 +1,554 @@
+/**
+ * `o2b brain import-session --status | --discover [--all]`.
+ *
+ * The verb used to accept only an explicit path, so the operator had to
+ * already know where five harnesses keep their logs and import them one
+ * at a time. These three flags are the machine-wide half: what is here,
+ * what has never been imported, and - only when asked twice - importing
+ * exactly that gap.
+ *
+ * The privacy posture is not re-implemented and is not re-tested from
+ * first principles here. It is asserted the only way that can stay true:
+ * the discovered import and the explicit-path import must leave
+ * byte-identical vault output - every file, not only the inbox - so
+ * redaction and the tool-payload exclusion cannot be relaxed on one path
+ * without failing on the other. The one thing subtracted from that
+ * comparison is the wall clock, which two CLI runs cannot share; see
+ * {@link WALL_CLOCK_STAMP} for why that is a subtraction and not a
+ * loosening.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+ chmodSync,
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ renameSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative } from "node:path";
+
+import { brainDirs } from "../../src/core/brain/paths.ts";
+import { DEFAULT_BRAIN_CONFIG_YAML } from "../../src/core/brain/config-template.ts";
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { sessionLedgerPath } from "../../src/core/brain/sessions/discover.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+let tmp: string;
+let vault: string;
+let home: string;
+
+interface CoverageRow {
+ readonly runtime: string;
+ readonly found: number;
+ readonly imported: number;
+ readonly gap: number;
+ readonly unparsable: number;
+ readonly roots: ReadonlyArray<{ readonly path: string; readonly present: boolean }>;
+}
+
+interface DiscoveryJson {
+ readonly found: number;
+ readonly imported: number;
+ readonly gap: number;
+ readonly by_runtime: ReadonlyArray<CoverageRow>;
+ readonly would_import?: ReadonlyArray<string>;
+ readonly files?: ReadonlyArray<{ readonly file: string }>;
+}
+
+/**
+ * A credential in the shape the redactor's `key: value` pass catches, so
+ * the byte-identity claim below is about a fixture that actually carries
+ * one. The parity test asserted a structural property against a fixture
+ * with no secret and no tool call in it, which made its own docstring -
+ * "redaction and the tool-payload exclusion cannot be relaxed on one path
+ * without failing on the other" - true only by construction.
+ */
+const FIXTURE_SECRET = "sk-live-9f2ba7c1d4e8";
+
+/** A tool INPUT, which no signal may ever carry: a host path. */
+const FIXTURE_TOOL_INPUT = "/etc/shadow";
+
+function claudeLine(topic: string, uuid: string): string {
+ return (
+ [
+ JSON.stringify({
+ parentUuid: null,
+ sessionId: "s",
+ entrypoint: "sdk-cli",
+ type: "user",
+ message: {
+ role: "user",
+ content:
+ `@osb feedback positive topic=${topic} principle="Declare the roots exactly once. ` +
+ `Never paste the token: ${FIXTURE_SECRET} into a prompt."`,
+ },
+ uuid,
+ timestamp: "2026-08-16T09:00:00.000Z",
+ }),
+ JSON.stringify({
+ parentUuid: uuid,
+ sessionId: "s",
+ entrypoint: "sdk-cli",
+ type: "assistant",
+ message: {
+ role: "assistant",
+ content: [
+ { type: "text", text: "noted" },
+ {
+ type: "tool_use",
+ name: "Read",
+ id: `call-${uuid}`,
+ input: { path: FIXTURE_TOOL_INPUT },
+ },
+ ],
+ },
+ uuid: `a-${uuid}`,
+ timestamp: "2026-08-16T09:00:01.000Z",
+ }),
+ ].join("\n") + "\n"
+ );
+}
+
+function bootstrapVault(at: string): void {
+ const dirs = brainDirs(at);
+ for (const d of [
+ dirs.brain,
+ dirs.inbox,
+ dirs.processed,
+ dirs.preferences,
+ dirs.retired,
+ dirs.log,
+ dirs.snapshots,
+ ]) {
+ mkdirSync(d, { recursive: true });
+ }
+ atomicWriteFileSync(join(dirs.brain, "_brain.yaml"), DEFAULT_BRAIN_CONFIG_YAML);
+}
+
+function claudeLog(name: string, topic: string): string {
+ const dir = join(home, ".claude", "projects", "-srv-projects-example");
+ mkdirSync(dir, { recursive: true });
+ const path = join(dir, name);
+ writeFileSync(path, claudeLine(topic, `u-${topic}`));
+ return path;
+}
+
+/** Signal files in the inbox, ignoring the `processed/` subdirectory. */
+function inboxSignals(at: string): ReadonlyArray<string> {
+ return readdirSync(brainDirs(at).inbox)
+ .filter((name) => name.endsWith(".md"))
+ .toSorted();
+}
+
+/**
+ * EVERY file a run left in a vault, keyed by its path relative to the
+ * vault root.
+ *
+ * The parity claim used to be made over `Brain/inbox/` alone, which is
+ * the one place a redactor is most likely to have been applied: the log,
+ * the processed store and the ledger were all outside the comparison, and
+ * a leak on the discovered path would most plausibly land in the log,
+ * which records the transcript that was read. Walking the whole vault
+ * costs nothing here and cannot be outgrown by a surface added later.
+ */
+function vaultTree(at: string): Record<string, string> {
+ const out: Record<string, string> = {};
+ const walk = (dir: string): void => {
+ for (const entry of readdirSync(dir, { withFileTypes: true }).toSorted((a, b) =>
+ a.name < b.name ? -1 : 1,
+ )) {
+ const full = join(dir, entry.name);
+ if (entry.isDirectory()) walk(full);
+ else out[relative(at, full)] = readFileSync(full, "utf8");
+ }
+ };
+ walk(at);
+ return out;
+}
+
+/**
+ * A wall-clock stamp: `2026-08-16T11:31:51Z` in frontmatter and in the
+ * log's JSONL, `11:31:51Z` in the log's markdown heading.
+ *
+ * The two runs being compared are two CLI invocations, so a stamp taken
+ * by each can differ by a second - measured at roughly 7% of runs, which
+ * made this test flaky. The repair is NOT to loosen the byte comparison:
+ * that would trade a real assertion for a vacuous one. Only the clock is
+ * neutralised, and only where its VALUE is the whole match, so any other
+ * difference - a leaked token, a path, a field one path writes and the
+ * other does not - still survives into the comparison and still fails it.
+ *
+ * The transcript's own event times (`...T09:00:00.000Z`, with
+ * milliseconds) are deliberately NOT matched: they come from the fixture,
+ * they are identical on both paths by construction, and normalising them
+ * would hide a path that lost them.
+ */
+const WALL_CLOCK_STAMP = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z|(?<![.\d])\d{2}:\d{2}:\d{2}Z/g;
+
+function withoutWallClock(tree: Record<string, string>): Record<string, string> {
+ const out: Record<string, string> = {};
+ for (const [name, body] of Object.entries(tree)) {
+ out[name] = body.replace(WALL_CLOCK_STAMP, "<clock>");
+ }
+ return out;
+}
+
+async function run(
+ args: string[],
+ env: Record<string, string> = {},
+): Promise<{ stdout: string; stderr: string; returncode: number }> {
+ return runCli(["brain", "import-session", ...args, "--vault", vault], {
+ env: { HOME: home, ...env },
+ });
+}
+
+/**
+ * The log shard both runs must write into.
+ *
+ * `appendLogEvent` names its files `<date>.<device-id>.md`, and a device
+ * id is generated per config home - which `runCli` isolates per
+ * invocation. So two runs otherwise identical land in two DIFFERENTLY
+ * NAMED log files, and a comparison over the vault tree would report
+ * every log as missing on both sides rather than comparing them. Pinned
+ * explicitly rather than relying on the suite preload's `O2B_DEVICE_ID=""`,
+ * so what this test compares does not depend on a setting made elsewhere.
+ */
+const PARITY_DEVICE_ID = "parity-device";
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-cli-session-discovery-"));
+ vault = join(tmp, "vault");
+ home = join(tmp, "home");
+ mkdirSync(home, { recursive: true });
+ bootstrapVault(vault);
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("--status reports coverage without touching anything", () => {
+ test("per runtime it names found, imported and the gap between them", async () => {
+ claudeLog("one.jsonl", "alpha");
+ claudeLog("two.jsonl", "beta");
+ const res = await run(["--status", "--json"]);
+ expect(res.returncode).toBe(0);
+ const body = JSON.parse(res.stdout) as DiscoveryJson;
+ expect(body.found).toBe(2);
+ expect(body.imported).toBe(0);
+ expect(body.gap).toBe(2);
+ const claude = body.by_runtime.find((r) => r.runtime === "claude-code");
+ expect({ found: claude?.found, imported: claude?.imported, gap: claude?.gap }).toEqual({
+ found: 2,
+ imported: 0,
+ gap: 2,
+ });
+ // Where it looked, not only what it found: "found: 0" against an
+ // unnamed root is an answer nobody can act on.
+ expect(claude?.roots.map((r) => r.path)).toEqual([join(home, ".claude", "projects")]);
+ expect(claude?.roots[0]?.present).toBe(true);
+ });
+
+ test("it writes no signal and no ledger", async () => {
+ claudeLog("one.jsonl", "alpha");
+ expect((await run(["--status"])).returncode).toBe(0);
+ expect(inboxSignals(vault)).toEqual([]);
+ expect(existsSync(sessionLedgerPath(vault))).toBe(false);
+ });
+
+ test("the human rendering names every runtime and its three counts", async () => {
+ claudeLog("one.jsonl", "alpha");
+ const res = await run(["--status"]);
+ expect(res.returncode).toBe(0);
+ for (const id of ["claude-code", "codex", "cursor", "grok", "opencode"]) {
+ expect(`${id} named: ${res.stdout.includes(id)}`).toBe(`${id} named: true`);
+ }
+ expect(res.stdout).toContain("found: 1");
+ expect(res.stdout).toContain("gap: 1");
+ });
+});
+
+describe("--discover reports what would import and imports nothing", () => {
+ test("it lists the gap and leaves the inbox empty", async () => {
+ const path = claudeLog("one.jsonl", "alpha");
+ const res = await run(["--discover", "--json"]);
+ expect(res.returncode).toBe(0);
+ const body = JSON.parse(res.stdout) as DiscoveryJson;
+ expect(body.would_import).toEqual([path]);
+ expect(body.files).toBeUndefined();
+ expect(inboxSignals(vault)).toEqual([]);
+ });
+
+ test("--discover --all imports the gap and the next status reports it closed", async () => {
+ claudeLog("one.jsonl", "alpha");
+ const imported = await run(["--discover", "--all", "--json"]);
+ expect(imported.returncode).toBe(0);
+ const body = JSON.parse(imported.stdout) as DiscoveryJson;
+ expect(body.files?.length).toBe(1);
+ expect(inboxSignals(vault).length).toBe(1);
+
+ const after = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
+ expect(after.found).toBe(1);
+ expect(after.imported).toBe(1);
+ expect(after.gap).toBe(0);
+ });
+
+ test("a second --discover --all imports nothing, because nothing changed", async () => {
+ claudeLog("one.jsonl", "alpha");
+ expect((await run(["--discover", "--all"])).returncode).toBe(0);
+ const before = inboxSignals(vault).length;
+ const again = JSON.parse(
+ (await run(["--discover", "--all", "--json"])).stdout,
+ ) as DiscoveryJson;
+ expect(again.files).toEqual([]);
+ expect(inboxSignals(vault).length).toBe(before);
+ });
+
+ test("an explicit-path import is recorded, so discovery stops offering it", async () => {
+ const path = claudeLog("one.jsonl", "alpha");
+ expect((await run([path])).returncode).toBe(0);
+ const body = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
+ expect(body.imported).toBe(1);
+ expect(body.gap).toBe(0);
+ });
+
+ test("a dry run is not an import, and does not close the gap", async () => {
+ const path = claudeLog("one.jsonl", "alpha");
+ expect((await run([path, "--dry-run"])).returncode).toBe(0);
+ const body = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
+ expect(body.gap).toBe(1);
+ });
+});
+
+describe("the ledger records what happened, and only what happened", () => {
+ test("a directory import records the files it imported, not the files it found", async () => {
+ // `importSessionPath` collects a per-file failure into `warnings` and
+ // carries on, while the verb recorded every `*.jsonl` under the path
+ // as imported. So an unrecognised transcript left the ledger at its
+ // current bytes and vanished from `--status` and `--discover` - the
+ // "silently report everything as imported" direction this surface
+ // exists to rule out - and would stay invisible even after a later
+ // release shipped an adapter that could read it.
+ const dir = join(home, ".claude", "projects", "-srv-projects-example");
+ claudeLog("good.jsonl", "alpha");
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(join(dir, "bad.jsonl"), JSON.stringify({ not: "a transcript" }) + "\n");
+
+ const res = await run([dir]);
+ expect(res.returncode).toBe(0);
+ expect(res.stderr + res.stdout).toContain("bad.jsonl");
+
+ const status = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
+ expect(status.found).toBe(2);
+ expect(status.imported).toBe(1);
+ expect(status.gap).toBe(1);
+
+ const ledger = JSON.parse(readFileSync(sessionLedgerPath(vault), "utf8")) as {
+ entries: Record<string, unknown>;
+ };
+ expect(Object.keys(ledger.entries)).toEqual([join(dir, "good.jsonl")]);
+ });
+
+ test("a ledger failure after a successful import is reported as itself", async () => {
+ // The ledger write sat inside the verb's big `try`, ahead of the
+ // report. A corrupt ledger therefore printed `import-session failed`,
+ // exited 1 and emitted no JSON - for a run whose signal was already on
+ // disk and whose log event was already appended.
+ const path = claudeLog("one.jsonl", "alpha");
+ mkdirSync(dirname(sessionLedgerPath(vault)), { recursive: true });
+ writeFileSync(sessionLedgerPath(vault), "{ this is not json", "utf8");
+
+ const res = await run([path, "--json"]);
+ expect(res.returncode).toBe(1);
+ // The report is emitted, because the import is what it reports on.
+ const body = JSON.parse(res.stdout) as DiscoveryJson;
+ expect(body.files?.length).toBe(1);
+ // And the signal really is there.
+ expect(inboxSignals(vault).length).toBe(1);
+ // The failure names itself rather than the import.
+ expect(res.stderr).toContain("the import completed");
+ expect(res.stderr).toContain("ledger");
+ expect(res.stderr).not.toContain("import-session failed");
+ });
+
+ test("a sweep whose ledger write fails still reports what it imported", async () => {
+ // The same defect one function over, and it was not even in a `try`:
+ // `--discover --all` imported the gap and then took the whole run's
+ // report down with the ledger write. A read-only derived store is the
+ // cheapest real cause - the ledger's lock file cannot be created -
+ // and stands in for the lock timeout and the read-only vault.
+ if (process.getuid?.() === 0) return; // root writes a 0o500 directory anyway
+ claudeLog("one.jsonl", "alpha");
+ const derived = dirname(sessionLedgerPath(vault));
+ mkdirSync(derived, { recursive: true });
+ chmodSync(derived, 0o500);
+ try {
+ const res = await run(["--discover", "--all", "--json"]);
+ expect(res.returncode).toBe(1);
+ const body = JSON.parse(res.stdout) as DiscoveryJson;
+ expect(body.files?.length).toBe(1);
+ expect(inboxSignals(vault).length).toBe(1);
+ expect(res.stderr).toContain("the import completed");
+ } finally {
+ chmodSync(derived, 0o700);
+ }
+ });
+
+ test("an entry whose file has been renamed away is pruned on the next write", async () => {
+ // Entries were dropped only when the vanished path was re-submitted,
+ // which is the one moment a ledger never hears about a renamed file.
+ // So a rotated transcript left a dead key in the ledger forever.
+ const first = claudeLog("one.jsonl", "alpha");
+ expect((await run([first])).returncode).toBe(0);
+ renameSync(first, join(dirname(first), "rotated.jsonl"));
+
+ const second = claudeLog("two.jsonl", "beta");
+ expect((await run([second])).returncode).toBe(0);
+
+ const ledger = JSON.parse(readFileSync(sessionLedgerPath(vault), "utf8")) as {
+ entries: Record<string, unknown>;
+ };
+ expect(Object.keys(ledger.entries)).toEqual([second]);
+ });
+});
+
+describe("the privacy posture is the one importSession already holds", () => {
+ test("the discovered import and the explicit-path import write identical bytes everywhere but the clock", async () => {
+ const path = claudeLog("one.jsonl", "alpha");
+
+ const explicit = join(tmp, "explicit-vault");
+ bootstrapVault(explicit);
+ const direct = await runCli(["brain", "import-session", path, "--vault", explicit], {
+ env: { HOME: home, O2B_DEVICE_ID: PARITY_DEVICE_ID },
+ });
+ expect(direct.returncode).toBe(0);
+
+ expect(
+ (await run(["--discover", "--all"], { O2B_DEVICE_ID: PARITY_DEVICE_ID })).returncode,
+ ).toBe(0);
+
+ // The floor. Two imports that wrote nothing are byte-identical, and
+ // an equality with nothing on either side of it proves nothing about
+ // a redactor - so what each run produced is pinned before the two are
+ // compared.
+ expect(inboxSignals(vault)).toEqual(["sig-2026-08-16-alpha.md"]);
+ expect(inboxSignals(explicit)).toEqual(inboxSignals(vault));
+ const sweptTree = vaultTree(vault);
+ const explicitTree = vaultTree(explicit);
+ const namesOf = (tree: Record<string, string>): ReadonlyArray<string> =>
+ Object.keys(tree).toSorted();
+ expect(namesOf(sweptTree)).toEqual(namesOf(explicitTree));
+ // Named rather than counted: each of these is a surface the earlier
+ // inbox-only comparison could not see, and the log is where a leak on
+ // the discovered path would most plausibly land, because the log is
+ // what records the transcript that was read.
+ for (const required of [
+ "Brain/inbox/sig-2026-08-16-alpha.md",
+ `Brain/log/2026-08-16.${PARITY_DEVICE_ID}.md`,
+ `Brain/log/2026-08-16.${PARITY_DEVICE_ID}.jsonl`,
+ relative(vault, sessionLedgerPath(vault)),
+ ]) {
+ expect(`${required} written: ${namesOf(sweptTree).includes(required)}`).toBe(
+ `${required} written: true`,
+ );
+ }
+
+ // The whole vault, byte for byte, with the wall clock - and only the
+ // wall clock - neutralised. See WALL_CLOCK_STAMP.
+ expect(withoutWallClock(sweptTree)).toEqual(withoutWallClock(explicitTree));
+
+ // And the bytes both paths wrote are bytes the posture actually acted
+ // on. Byte-identity between two paths that both leaked would pass just
+ // as happily, so the fixture carries a credential and a tool payload
+ // and both are checked over everything either path wrote.
+ for (const tree of [sweptTree, explicitTree]) {
+ const all = Object.values(tree).join("");
+ expect(all.length).toBeGreaterThan(0);
+ expect(all).not.toContain(FIXTURE_SECRET);
+ expect(all).toContain("***REDACTED***");
+ expect(all).not.toContain(FIXTURE_TOOL_INPUT);
+ }
+ });
+});
+
+describe("the refusals name what they refuse", () => {
+ // Exit 1, not 2: `o2b brain` maps every `CliError` to 1, and the two
+ // exit codes this verb reserves for 2 are the adapter ones
+ // (`DETECT_FAIL`, `UNKNOWN_FORMAT`). A usage refusal that exited 2 here
+ // would be the only brain verb that did.
+ test("a path and --discover cannot both be given", async () => {
+ const path = claudeLog("one.jsonl", "alpha");
+ const res = await run([path, "--discover"]);
+ expect(res.returncode).toBe(1);
+ expect(res.stderr).toContain("--discover");
+ expect(res.stderr).toContain(path);
+ });
+
+ test("a path and --status cannot both be given", async () => {
+ const path = claudeLog("one.jsonl", "alpha");
+ const res = await run([path, "--status"]);
+ expect(res.returncode).toBe(1);
+ expect(res.stderr).toContain("--status");
+ });
+
+ test("--all is refused on its own, naming the flag that gives it meaning", async () => {
+ const res = await run(["--all"]);
+ expect(res.returncode).toBe(1);
+ expect(res.stderr).toContain("--discover");
+ });
+
+ test("--discover and --status together are refused rather than silently ranked", async () => {
+ const res = await run(["--discover", "--status"]);
+ expect(res.returncode).toBe(1);
+ expect(res.stderr).toContain("--status");
+ });
+
+ test("no path and no sweep flag still names the missing argument", async () => {
+ const res = await run([]);
+ expect(res.returncode).toBe(1);
+ expect(res.stderr).toContain("--discover");
+ });
+});
+
+describe("the surface is advertised where an operator looks", () => {
+ test("the manifest declares every flag the parser accepts", async () => {
+ const res = await runCli(["help", "--json"]);
+ expect(res.returncode).toBe(0);
+ const root = JSON.parse(res.stdout) as {
+ commands: Array<{
+ name: string;
+ commands?: Array<{ name: string; flags?: Array<{ name: string }> }>;
+ }>;
+ };
+ const brain = root.commands.find((c) => c.name === "brain");
+ const verb = brain?.commands?.find((c) => c.name === "import-session");
+ const declared = (verb?.flags ?? []).map((f) => f.name).toSorted();
+ expect(declared).toEqual(
+ [
+ "agent",
+ "all",
+ "discover",
+ "dry-run",
+ "filter-role",
+ "filter-text",
+ "format",
+ "ingest-scope",
+ "json",
+ "preserve-event-time",
+ "progress",
+ "recall",
+ "recall-session-id",
+ "recall-summary-group-size",
+ "since",
+ "status",
+ "vault",
+ ].toSorted(),
+ );
+ });
+});
diff --git a/tests/cli/state-migrate.test.ts b/tests/cli/state-migrate.test.ts
new file mode 100644
index 00000000..3eaefb71
--- /dev/null
+++ b/tests/cli/state-migrate.test.ts
@@ -0,0 +1,213 @@
+/**
+ * `o2b state migrate` / `o2b state rollback` - the ladder and the exit
+ * contract.
+ *
+ * The move itself is `tests/core/state/migrate.test.ts`'s subject. What
+ * this layer owns is the part an operator meets first and a supervisor
+ * reads: that a bare invocation PLANS, that `--apply` needs `--yes` when
+ * nobody can answer a prompt, and that a refusal is a distinct exit code
+ * from a mistake in the argv. The last one is the reason the refusals are
+ * a returned value rather than a warning: `1` says the command answered
+ * and the answer was no, `2` says the invocation was wrong, and a
+ * supervisor that cannot tell them apart retries the wrong one.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ renameSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { MIGRATION_MANIFEST_FILE, type MigrationPlan } from "../../src/core/state/migrate.ts";
+import { STATE_SURFACE_ID, STATE_SURFACES } from "../../src/core/state/surfaces.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+const temps: string[] = [];
+
+afterEach(() => {
+ while (temps.length > 0) rmSync(temps.pop()!, { recursive: true, force: true });
+});
+
+function tempDir(prefix: string): string {
+ const dir = mkdtempSync(join(tmpdir(), prefix));
+ temps.push(dir);
+ return dir;
+}
+
+function surfacePath(vault: string, id: string): string {
+ return STATE_SURFACES.find((s) => s.id === id)!.derive(vault, null);
+}
+
+function seedVault(): string {
+ const vault = tempDir("osb-state-migrate-cli-");
+ for (const [path, body] of [
+ [surfacePath(vault, STATE_SURFACE_ID.searchIndex), "index-bytes"],
+ [join(surfacePath(vault, STATE_SURFACE_ID.metrics), "recall.jsonl"), "{}\n"],
+ ] as ReadonlyArray<readonly [string, string]>) {
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, body);
+ }
+ return vault;
+}
+
+describe("o2b state migrate", () => {
+ test("plans by default and moves nothing", async () => {
+ const vault = seedVault();
+ const dest = join(tempDir("osb-state-dest-"), "moved");
+
+ const r = await runCli(["state", "migrate", "--vault", vault, "--to", dest, "--json"]);
+ expect(r.returncode).toBe(0);
+ const plan = JSON.parse(r.stdout) as MigrationPlan;
+ expect(plan.manifest.entries).toHaveLength(2);
+ expect(existsSync(dest)).toBe(false);
+ expect(existsSync(surfacePath(vault, STATE_SURFACE_ID.searchIndex))).toBe(true);
+ });
+
+ test("requires --to and says so in the usage stream", async () => {
+ const vault = seedVault();
+ const r = await runCli(["state", "migrate", "--vault", vault]);
+ expect(r.returncode).toBe(2);
+ expect(r.stderr).toContain("--to <dir>");
+ });
+
+ test("refuses --dry-run together with --apply", async () => {
+ const vault = seedVault();
+ const dest = join(tempDir("osb-state-dest-"), "moved");
+ const r = await runCli([
+ "state",
+ "migrate",
+ "--vault",
+ vault,
+ "--to",
+ dest,
+ "--dry-run",
+ "--apply",
+ ]);
+ expect(r.returncode).toBe(2);
+ expect(r.stderr).toContain("mutually exclusive");
+ expect(existsSync(dest)).toBe(false);
+ });
+
+ test("refuses --apply without --yes when nobody can answer a prompt", async () => {
+ const vault = seedVault();
+ const dest = join(tempDir("osb-state-dest-"), "moved");
+ const r = await runCli([
+ "state",
+ "migrate",
+ "--vault",
+ vault,
+ "--to",
+ dest,
+ "--apply",
+ "--json",
+ ]);
+ expect(r.returncode).toBe(2);
+ expect(r.stderr).toContain("--yes");
+ expect(existsSync(dest)).toBe(false);
+ });
+
+ test("a refusal is exit 1, names what it found, and moves nothing", async () => {
+ const vault = seedVault();
+ const dest = join(vault, "inside");
+
+ const r = await runCli(["state", "migrate", "--vault", vault, "--to", dest]);
+ expect(r.returncode).toBe(1);
+ expect(r.stderr).toContain("reserved_namespace");
+ expect(r.stderr).toContain("do:");
+ expect(existsSync(dest)).toBe(false);
+ });
+
+ test("--apply --yes moves the tree and leaves a manifest that rolls it back", async () => {
+ const vault = seedVault();
+ const dest = join(tempDir("osb-state-dest-"), "moved");
+
+ const applied = await runCli([
+ "state",
+ "migrate",
+ "--vault",
+ vault,
+ "--to",
+ dest,
+ "--apply",
+ "--yes",
+ ]);
+ expect(applied.returncode).toBe(0);
+ expect(applied.stdout).toContain("moved 2 file(s)");
+ expect(existsSync(join(dest, MIGRATION_MANIFEST_FILE))).toBe(true);
+ expect(existsSync(surfacePath(vault, STATE_SURFACE_ID.searchIndex))).toBe(false);
+
+ const rolled = await runCli(["state", "rollback", "--from", dest, "--apply", "--yes"]);
+ expect(rolled.returncode).toBe(0);
+ expect(readFileSync(surfacePath(vault, STATE_SURFACE_ID.searchIndex), "utf8")).toBe(
+ "index-bytes",
+ );
+ });
+});
+
+describe("o2b state rollback", () => {
+ test("requires --from and says where the manifest lives", async () => {
+ const r = await runCli(["state", "rollback"]);
+ expect(r.returncode).toBe(2);
+ expect(r.stderr).toContain("--from <dir>");
+ });
+
+ /**
+ * The command an operator runs after they have moved the vault. It used
+ * to exit 0 having recreated the dead path, copied into it, deleted the
+ * destination copies and removed the manifest - a data loss reported as
+ * a success. Now it refuses by name, and `--to` is the way through.
+ */
+ test("a vault renamed since the migration is refused, and --to puts the files back", async () => {
+ const vault = seedVault();
+ const dest = join(tempDir("osb-state-dest-"), "moved");
+ await runCli(["state", "migrate", "--vault", vault, "--to", dest, "--apply", "--yes"]);
+ const renamed = `${vault}-renamed`;
+ renameSync(vault, renamed);
+ temps.push(renamed);
+
+ const refused = await runCli(["state", "rollback", "--from", dest, "--apply", "--yes"]);
+ expect(refused.returncode).toBe(1);
+ expect(refused.stderr).toContain(vault);
+ expect(refused.stderr).toContain("--to");
+ expect(existsSync(join(dest, MIGRATION_MANIFEST_FILE))).toBe(true);
+
+ const rolled = await runCli([
+ "state",
+ "rollback",
+ "--from",
+ dest,
+ "--to",
+ renamed,
+ "--apply",
+ "--yes",
+ ]);
+ expect(rolled.returncode).toBe(0);
+ expect(readFileSync(surfacePath(renamed, STATE_SURFACE_ID.searchIndex), "utf8")).toBe(
+ "index-bytes",
+ );
+ expect(existsSync(vault)).toBe(false);
+ });
+
+ test("a refused entry is named and exits 1 even though the rest restored", async () => {
+ const vault = seedVault();
+ const dest = join(tempDir("osb-state-dest-"), "moved");
+ await runCli(["state", "migrate", "--vault", vault, "--to", dest, "--apply", "--yes"]);
+
+ const edited = join(dest, "Brain/metrics/recall.jsonl");
+ writeFileSync(edited, "{}\nedited after the migration\n");
+
+ const r = await runCli(["state", "rollback", "--from", dest, "--apply", "--yes"]);
+ expect(r.returncode).toBe(1);
+ expect(r.stdout).toContain("Brain/metrics/recall.jsonl");
+ expect(r.stdout).toContain("digest_mismatch");
+ // Refused means LEFT ALONE, never deleted.
+ expect(readFileSync(edited, "utf8")).toContain("edited after the migration");
+ });
+});
diff --git a/tests/cli/state-status.test.ts b/tests/cli/state-status.test.ts
new file mode 100644
index 00000000..2fe0a763
--- /dev/null
+++ b/tests/cli/state-status.test.ts
@@ -0,0 +1,93 @@
+/**
+ * `o2b state status` - the CLI half of the in-vault state inventory.
+ *
+ * The property worth asserting here is not the report's content, which
+ * `tests/core/state/surfaces.test.ts` owns, but that the two streams are
+ * two views of ONE value: every surface the JSON carries is named by the
+ * human text, and neither stream is assembled in this layer.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+ STATE_REACHABILITY,
+ STATE_SURFACES,
+ type StateInventory,
+} from "../../src/core/state/surfaces.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+function tempVault(): string {
+ const vault = mkdtempSync(join(tmpdir(), "osb-state-cli-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ return vault;
+}
+
+async function statusJson(vault: string, env: Record<string, string> = {}) {
+ const r = await runCli(["state", "status", "--vault", vault, "--json"], { env });
+ expect(r.stderr).toBe("");
+ expect(r.returncode).toBe(0);
+ return JSON.parse(r.stdout) as StateInventory;
+}
+
+describe("o2b state status", () => {
+ test("reports one row per declared surface, with a verdict and an origin", async () => {
+ const vault = tempVault();
+ const payload = await statusJson(vault);
+ expect(payload.vault).toBe(vault);
+ expect(payload.surfaces.length).toBe(STATE_SURFACES.length);
+ const incomplete = payload.surfaces
+ .filter((s) => s.reachability.state === undefined || s.origin === undefined)
+ .map((s) => s.id);
+ expect(incomplete.join("\n")).toBe("");
+ });
+
+ test("a surface that exists is present and one that does not is absent", async () => {
+ const vault = tempVault();
+ const lease = STATE_SURFACES.find((s) => s.id === "maintenance_lease")!.derive(vault, null);
+ mkdirSync(dirname(lease), { recursive: true });
+ writeFileSync(lease, "", "utf8");
+ const payload = await statusJson(vault);
+ const byId = new Map(payload.surfaces.map((s) => [s.id, s]));
+ expect(byId.get("maintenance_lease")!.reachability.state).toBe(STATE_REACHABILITY.present);
+ expect(byId.get("watchdog_audit")!.reachability.state).toBe(STATE_REACHABILITY.absent);
+ });
+
+ test("an environment override moves the path and is reported as its origin", async () => {
+ const vault = tempVault();
+ const payload = await statusJson(vault, {
+ OPEN_SECOND_BRAIN_SEARCH_DB: join(vault, "elsewhere", "brain.sqlite"),
+ });
+ const index = payload.surfaces.find((s) => s.id === "search_index")!;
+ expect(index.path).toBe(join(vault, "elsewhere", "brain.sqlite"));
+ expect(index.origin).toBe("env");
+ });
+
+ test("the human stream names every surface the JSON stream carries", async () => {
+ // One value, two renderings. A hand-written second copy is exactly
+ // what drifts, so the human text is checked against the machine one.
+ const vault = tempVault();
+ const payload = await statusJson(vault);
+ const human = await runCli(["state", "status", "--vault", vault]);
+ expect(human.returncode).toBe(0);
+ const unnamed = payload.surfaces
+ .filter((s) => !human.stdout.includes(s.label) || !human.stdout.includes(s.path))
+ .map((s) => s.id);
+ expect(unnamed.join("\n")).toBe("");
+ });
+
+ test("an unknown state verb is a usage error, not a silent success", async () => {
+ const r = await runCli(["state", "no-such-verb"]);
+ expect(r.returncode).toBe(2);
+ expect(r.stderr).toContain("unknown state verb");
+ expect(r.stderr).toContain("o2b state status");
+ });
+
+ test("state with no verb prints its usage and refuses", async () => {
+ const r = await runCli(["state"]);
+ expect(r.returncode).toBe(2);
+ expect(r.stdout).toContain("o2b state status");
+ });
+});
diff --git a/tests/core/architecture/egress-census.test.ts b/tests/core/architecture/egress-census.test.ts
index 9bb2508e..acaa0d2f 100644
--- a/tests/core/architecture/egress-census.test.ts
+++ b/tests/core/architecture/egress-census.test.ts
@@ -279,6 +279,42 @@ function moduleText(path: string): string {
return readFileSync(join(REPO_ROOT, path), "utf8");
}
+/**
+ * The source of one top-level function declaration, from its signature to
+ * the closing brace in column zero. Enough to ask whether that function
+ * body contains a call, and no more: this file reads source as text
+ * everywhere else too, and a parser would be a heavier dependency than
+ * the question deserves.
+ */
+function bodyOf(text: string, name: string): string {
+ const start = text.search(new RegExp(`^(?:export )?(?:async )?function ${name}\\b`, "m"));
+ if (start < 0) return "";
+ const end = text.indexOf("\n}\n", start);
+ return end < 0 ? text.slice(start) : text.slice(start, end);
+}
+
+/**
+ * True when `name`'s body calls the guard, or hands its payload to one
+ * module-local function that does.
+ *
+ * One hop, and no more. A handler is allowed to delegate its loop - the
+ * transcript one does, to the spooling function that owns the
+ * write-as-you-read contract - but a chain any longer than that stops
+ * being something this census can honestly claim to have checked, and a
+ * new handler wired through three helpers would be a reviewer's problem
+ * rather than a grep's.
+ */
+function guardsSomewhere(text: string, name: string): boolean {
+ const body = bodyOf(text, name);
+ if (EGRESS_GUARD_CALL_RE.test(body)) return true;
+ for (const call of body.matchAll(/\b([a-z][A-Za-z0-9]*)\s*\(/g)) {
+ const callee = call[1]!;
+ if (callee === name) continue;
+ if (EGRESS_GUARD_CALL_RE.test(bodyOf(text, callee))) return true;
+ }
+ return false;
+}
+
describe("egress site census", () => {
test("every module that names an output destination is declared", () => {
// Named, not counted: the failure has to say which file.
@@ -330,6 +366,25 @@ describe("egress site census", () => {
expect(uncovered).toEqual([]);
});
+ test("every format handler of `brain export` calls the guard itself", () => {
+ // `guards >= destinations` is an INEQUALITY, and it is the wrong
+ // instrument for a module that dispatches. `brain export` declares one
+ // destination and makes three guard calls, so a fourth format handler
+ // that scanned nothing would satisfy the count while writing raw bytes
+ // to the same `--out`. The registry's own sentence used to claim "the
+ // guard-call count is what proves each branch scans"; this is what
+ // makes that true, per branch, by name.
+ const module = "src/cli/brain/verbs/export.ts";
+ const text = moduleText(module);
+ const handlers = [...text.matchAll(/^\s*\[EXPORT_FORMAT\.\w+\]:\s*(\w+),$/gm)].map(
+ (m) => m[1]!,
+ );
+ // The table is the dispatch; an empty read here would pass vacuously.
+ expect(handlers.length).toBeGreaterThanOrEqual(3);
+ const unguarded = handlers.filter((name) => !guardsSomewhere(text, name));
+ expect(unguarded).toEqual([]);
+ });
+
test("no entry understates what its module does", () => {
// The complement: a module that calls the guard but is declared as
// something weaker would leave the registry describing a gap that is
diff --git a/tests/core/architecture/host-facts-census.test.ts b/tests/core/architecture/host-facts-census.test.ts
new file mode 100644
index 00000000..58ea8c12
--- /dev/null
+++ b/tests/core/architecture/host-facts-census.test.ts
@@ -0,0 +1,94 @@
+/**
+ * Census over the runtime-facts population.
+ *
+ * `RUNTIME_FACTS` answers "what does this build know about the host it is
+ * installed into". That answer is only worth reading if it covers every
+ * runtime this build can install into, and covers nothing else - a row
+ * for a target with no adapter is a fact about a host nobody can reach,
+ * and an adapter with no row is a host the ceiling, profile and session
+ * questions are silently unanswered for.
+ *
+ * So the population is DERIVED, from `registerAllAdapters().targets()` -
+ * the live registry each adapter registers itself into at import time -
+ * and compared against the declared key set in both directions. Neither
+ * half may be the source of the other: a table that vouches for its own
+ * completeness vouches for nothing.
+ *
+ * The count is pinned as an equality rather than a floor, for the reason
+ * every census here pins one: a registry that stopped being populated
+ * would sweep an empty set clean and every assertion below would pass.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { registerAllAdapters } from "../../../src/core/install/adapters/all.ts";
+import {
+ INSTALL_TARGET_IDS,
+ isInstallTargetId,
+ RUNTIME_FACTS,
+} from "../../../src/core/runtime/host-facts.ts";
+
+/**
+ * Registered adapters today. An equality, so adding an adapter is a
+ * deliberate edit here rather than a silent widening of the population.
+ */
+const REGISTERED_TARGET_COUNT = 10;
+
+const registeredTargets = (): ReadonlyArray<string> => registerAllAdapters().targets();
+
+describe("runtime facts census", () => {
+ test("every registered adapter has a row and every row has an adapter", () => {
+ // One expectation, whose value NAMES what is missing: asserting the
+ // two directions separately would stop at the first and hide the rest.
+ const declared = new Set(Object.keys(RUNTIME_FACTS));
+ const registered = new Set(registeredTargets());
+ const unaccounted = [
+ ...[...registered]
+ .filter((target) => !declared.has(target))
+ .map((target) => `adapter with no RUNTIME_FACTS row: ${target}`),
+ ...[...declared]
+ .filter((target) => !registered.has(target))
+ .map((target) => `RUNTIME_FACTS row with no adapter: ${target}`),
+ ];
+ expect(unaccounted.toSorted().join("\n")).toBe("");
+ });
+
+ test("every row's label is the adapter's own label, as the field claims", () => {
+ // `RuntimeFacts.label` is documented as "matching the adapter's own
+ // label" and nothing in `src/` read it - `--friction` prints
+ // `adapter.label`. A declared fact with no reader and no assertion is
+ // free to drift into a second, quietly wrong name for the same host,
+ // which is the defect this release exists to remove. This is the
+ // reader: not a consumer of the value, but the binding that makes the
+ // claim true or fails.
+ const mismatched = registerAllAdapters()
+ .list()
+ .filter((adapter) => RUNTIME_FACTS[adapter.target].label !== adapter.label)
+ .map(
+ (adapter) =>
+ `${adapter.target}: row says '${RUNTIME_FACTS[adapter.target].label}', ` +
+ `adapter says '${adapter.label}'`,
+ );
+ expect(mismatched.toSorted().join("\n")).toBe("");
+ });
+
+ test("the vocabulary and the row keys are the same set", () => {
+ // The third corner: a member with no row would type-check everywhere
+ // and resolve to `undefined` at the one call site that reads it.
+ const declared: ReadonlyArray<string> = INSTALL_TARGET_IDS;
+ expect(declared.toSorted()).toEqual(Object.keys(RUNTIME_FACTS).toSorted());
+ });
+
+ test("every registered target is a vocabulary member", () => {
+ const strangers = registeredTargets().filter((target) => !isInstallTargetId(target));
+ expect(strangers.toSorted().join("\n")).toBe("");
+ });
+
+ test("the census is not vacuous", () => {
+ // A registry that registered nothing, or a barrel that lost its
+ // side-effect imports, would make every comparison above trivially
+ // true. Pin the measurement, not only its verdict.
+ expect(registeredTargets().length).toBe(REGISTERED_TARGET_COUNT);
+ expect(Object.keys(RUNTIME_FACTS).length).toBe(REGISTERED_TARGET_COUNT);
+ });
+});
diff --git a/tests/core/architecture/progress-census.test.ts b/tests/core/architecture/progress-census.test.ts
index 94556780..706b6d37 100644
--- a/tests/core/architecture/progress-census.test.ts
+++ b/tests/core/architecture/progress-census.test.ts
@@ -110,6 +110,10 @@ const SKIP_DIRS: ReadonlySet<string> = new Set(["node_modules"]);
* inconvenient.
*/
const DECLARED_EXEMPTIONS: ReadonlyMap<string, string> = new Map<string, string>([
+ [
+ "DreamApplyInput",
+ "The dream pass's MUTATION STAGE, not a run: dream() owns the counter and has an `apply` stage open across this whole call. It takes the safeguard because the one sub-unit it dispatches - the opt-in heal enrichment - walks every user page in the vault and so needs a deadline inside a pass exactly as it does on its own; it takes no sink for the same reason scanBrain takes none from dream(), namely that a second stream would put two terminators on one run.",
+ ],
[
"EmbeddingPhaseOptions",
"A PHASE, not a run: called from indexInto and standalone by the vector backfill. Given a sink it would build a second counter, and a stream carrying two terminators cannot say which one ended the run - so it borrows the run owner's ProgressCounter instead, which is strictly more wiring than a sink, not less.",
diff --git a/tests/core/architecture/state-surface-census.test.ts b/tests/core/architecture/state-surface-census.test.ts
new file mode 100644
index 00000000..0a78a780
--- /dev/null
+++ b/tests/core/architecture/state-surface-census.test.ts
@@ -0,0 +1,282 @@
+/**
+ * Census over the in-vault state population.
+ *
+ * `STATE_SURFACES` claims to be the complete list of durable locations
+ * this tool keeps inside a vault. A hand-written list cannot vouch for its
+ * own completeness, and the failure mode is silent: a new module joins a
+ * path under `<vault>/.open-second-brain/`, ships, and the inventory an
+ * operator reads before migrating their vault simply does not mention it.
+ *
+ * So the derived-store half of the population is DERIVED, from the source:
+ * every module under `src/` that names {@link DERIVED_STORE_DIR} - by the
+ * constant or by its value - has to be attributed to a row through
+ * {@link StateSurface.sources} or excused in
+ * {@link STATE_SURFACE_SWEEP_EXCLUSIONS} with a written reason. That is
+ * the same instrument `OUT_OF_VAULT_SWEEP_EXCLUSIONS` already applies to
+ * the outside-the-vault half, pointed at the other root.
+ *
+ * ## What the sweep can and cannot see, stated rather than implied
+ *
+ * It lexes through the shared lexer (`tests/helpers/source-lexer.ts`) and
+ * matches on the CODE view, so a directory named in a docblock is not a
+ * path builder and a `"{"` inside a value cannot move a block. Four
+ * private copies of that lexer produced a real defect in v1.49.0; there is
+ * no fifth here.
+ *
+ * - `src/` only. `hooks/lib/session-state.ts` builds a real surface
+ * under the same root and is out of the swept tree, so its row names
+ * it explicitly and `tests/core/state/surfaces.test.ts` asserts that
+ * the file it names still exists.
+ * - The `Brain/` half of the population carries no single anchor token -
+ * `BRAIN_LOG_REL`, `brainDirs(...).log` and a bare `"Brain"` are all
+ * the same root - so it is held true by the resolver-binding block in
+ * the unit test rather than by this sweep. Saying which half is swept
+ * is the difference between a census and a claim about a census. That
+ * delegation is only worth what the block covers: it bound 26 of 40
+ * rows when this sentence first appeared, and a deliberately wrong
+ * value in one of the other fourteen changed no test. It now binds
+ * every row bar a counted, reasoned exception list, and the count is
+ * itself an assertion there.
+ * - This sweep NEVER checks that a row's declared path is the path its
+ * owner builds. `attributed()` asks only whether a module is claimed
+ * by some row's `sources`, which is a question about attribution and
+ * not about correctness.
+ * - A path whose root arrives as an argument carries no token to match
+ * on. `writer-lock.ts` and `session-focus.ts` are exactly that shape:
+ * both build under the store directory and neither names it.
+ *
+ * ## The alarm on the parser
+ *
+ * A block matcher that goes wrong reports a clean tree, so the population
+ * is cross-checked against a second, dumber search that cannot mis-parse
+ * because it does not parse - a line regex for a `join(` whose arguments
+ * name the store directory. Every file it finds must be in the population.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { DERIVED_STORE_DIR } from "../../../src/core/brain/path-constants.ts";
+import {
+ STATE_SURFACE_SWEEP_EXCLUSIONS,
+ STATE_SURFACES,
+} from "../../../src/core/state/surfaces.ts";
+import { lexSource } from "../../helpers/source-lexer.ts";
+
+const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
+
+/** The one root the sweep walks. See the docblock for what living outside costs. */
+const SWEPT_ROOT = "src";
+
+/** The identifier the constant is imported under everywhere it is used. */
+const STORE_DIR_IDENTIFIER = "DERIVED_STORE_DIR";
+
+/**
+ * Modules in the swept tree today. An equality rather than a floor: a
+ * glob that stopped matching would sweep an empty set clean and every
+ * assertion below would pass over nothing.
+ */
+const SWEPT_POPULATION_SIZE = 20;
+
+/** Declared surfaces today. Pinned for the same reason. */
+const DECLARED_SURFACE_COUNT = 40;
+
+/** An exclusion reason has to be an argument, not a label. */
+const MIN_REASON_LENGTH = 80;
+
+interface SourceFile {
+ readonly path: string;
+ readonly text: string;
+}
+
+function readSourceTree(): ReadonlyArray<SourceFile> {
+ const files: SourceFile[] = [];
+ const walk = (dir: string): void => {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const abs = join(dir, entry.name);
+ if (entry.isDirectory()) walk(abs);
+ else if (entry.name.endsWith(".ts")) {
+ files.push({
+ path: relative(REPO_ROOT, abs).split("\\").join("/"),
+ text: readFileSync(abs, "utf8"),
+ });
+ }
+ }
+ };
+ walk(join(REPO_ROOT, SWEPT_ROOT));
+ return files.toSorted((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+/**
+ * Whether `file` names the derived-store directory in CODE.
+ *
+ * Two shapes, because both ship: the imported constant, and the bare
+ * literal a dozen modules spell privately. The literal is read off the
+ * comment-stripped view - which keeps string CONTENTS, so `".open-second-
+ * brain"` is still readable - and confirmed against the code view, where a
+ * quote delimiter survives but a comment does not. Reading it off the code
+ * view alone would find nothing, because that view blanks literal
+ * contents; reading it off the raw text would enrol every docblock that
+ * mentions the directory by name.
+ */
+function namesStoreDir(file: SourceFile): boolean {
+ const { withoutComments, code } = lexSource(file.text);
+ if (new RegExp(`\\b${STORE_DIR_IDENTIFIER}\\b`).test(code)) return true;
+ for (const quote of ['"', "'"]) {
+ const needle = `${quote}${DERIVED_STORE_DIR}${quote}`;
+ for (let at = withoutComments.indexOf(needle); at !== -1; ) {
+ if (code[at] === quote) return true;
+ at = withoutComments.indexOf(needle, at + 1);
+ }
+ }
+ return false;
+}
+
+/** Every swept module that names the store directory. */
+function sweepPopulation(tree: ReadonlyArray<SourceFile> = TREE): ReadonlyArray<string> {
+ return tree.filter(namesStoreDir).map((file) => file.path);
+}
+
+/**
+ * The naive cross-check: a `join(` whose arguments name the store
+ * directory, matched on raw text one line at a time. It cannot mis-parse
+ * because it does not parse, and it is strictly narrower than the rule
+ * above, so every file it finds must be in the population.
+ */
+const NAIVE_RE = new RegExp(
+ `join\\([^)\\n]*(?:"${DERIVED_STORE_DIR.replace(/\./g, "\\.")}"|${STORE_DIR_IDENTIFIER})`,
+);
+
+function naivePathBuilders(tree: ReadonlyArray<SourceFile> = TREE): ReadonlyArray<string> {
+ return tree.filter((file) => NAIVE_RE.test(file.text)).map((file) => file.path);
+}
+
+/**
+ * Whether any declared row claims `path` through its `sources`.
+ *
+ * A trailing-slash source names the files IN that directory and not the
+ * tree beneath it. Unbounded, it was an absolution: a row declaring
+ * `sources: ["src/core/"]` would have answered for most of this
+ * repository, and the "every declared source module exists" check in
+ * `tests/core/state/surfaces.test.ts` would have waved it through
+ * because `src/core` does exist. No row spells one today, which is
+ * exactly when the bound is cheap to put on.
+ */
+function attributed(
+ path: string,
+ surfaces: ReadonlyArray<{ readonly sources: ReadonlyArray<string> }> = STATE_SURFACES,
+): boolean {
+ return surfaces.some((surface) =>
+ surface.sources.some((source) =>
+ source.endsWith("/")
+ ? path.startsWith(source) && !path.slice(source.length).includes("/")
+ : path === source,
+ ),
+ );
+}
+
+const TREE = readSourceTree();
+
+describe("state surface census", () => {
+ test("every module that names the derived store is attributed to a row or excused", () => {
+ // ONE folded expectation whose value NAMES the work: asserting per
+ // module would stop at the first and hide the rest.
+ const unaccounted = sweepPopulation().filter(
+ (path) => !attributed(path) && !STATE_SURFACE_SWEEP_EXCLUSIONS.has(path),
+ );
+ expect(unaccounted.toSorted().join("\n")).toBe("");
+ });
+
+ test("no exclusion outlives the module it excuses, and every reason says something", () => {
+ const swept = new Set(sweepPopulation());
+ const stale: string[] = [];
+ const thin: string[] = [];
+ for (const [path, reason] of STATE_SURFACE_SWEEP_EXCLUSIONS) {
+ if (!swept.has(path)) stale.push(path);
+ // A placeholder ("todo", "n/a", "") cannot satisfy this.
+ if (reason.trim().length < MIN_REASON_LENGTH) thin.push(path);
+ if (/\bTODO\b|\bfor now\b|\blater\b/i.test(reason)) thin.push(path);
+ }
+ expect(stale.toSorted().join("\n")).toBe("");
+ expect(thin.toSorted().join("\n")).toBe("");
+ });
+
+ test("no module is both attributed and excused", () => {
+ // Two answers to one question is how an exclusion survives the row
+ // that replaced it, still excusing a module nobody reads it for.
+ const both = sweepPopulation().filter(
+ (path) => attributed(path) && STATE_SURFACE_SWEEP_EXCLUSIONS.has(path),
+ );
+ expect(both.toSorted().join("\n")).toBe("");
+ });
+
+ test("the naive cross-check finds nothing the population missed", () => {
+ // The alarm on the parser itself. A lexer that blanked the wrong span
+ // would report a clean sweep over a shrunken population; this search
+ // cannot, because it never looks at structure.
+ const population = new Set(sweepPopulation());
+ const unseen = naivePathBuilders().filter((path) => !population.has(path));
+ expect(unseen.toSorted().join("\n")).toBe("");
+ // …and it has to have found something, or it is no alarm at all.
+ expect(naivePathBuilders().length).toBeGreaterThan(5);
+ });
+
+ test("the census is not vacuous", () => {
+ expect(TREE.length).toBeGreaterThan(850);
+ expect(sweepPopulation().length).toBe(SWEPT_POPULATION_SIZE);
+ expect(STATE_SURFACES.length).toBe(DECLARED_SURFACE_COUNT);
+ });
+});
+
+describe("the census can fail", () => {
+ /** The intruder joins the real tree, so the rule runs under real conditions. */
+ const intruder = (path: string, text: string): ReadonlyArray<SourceFile> => [
+ ...TREE,
+ { path, text },
+ ];
+
+ /** Only the intruder's own row, so an unrelated module cannot answer for it. */
+ const unaccountedFrom = (path: string, text: string): ReadonlyArray<string> =>
+ sweepPopulation(intruder(path, text)).filter(
+ (p) => p === path && !attributed(p) && !STATE_SURFACE_SWEEP_EXCLUSIONS.has(p),
+ );
+
+ test("a new path builder under the store directory is unaccounted for", () => {
+ const path = "src/core/synthetic-store-writer.ts";
+ const text =
+ 'import { join } from "node:path";\n' +
+ "export function spoolPath(vault: string): string {\n" +
+ ` return join(vault, "${DERIVED_STORE_DIR}", "synthetic-spool.jsonl");\n` +
+ "}\n";
+ expect(unaccountedFrom(path, text)).toEqual([path]);
+ });
+
+ test("a builder reaching the directory through the constant is caught too", () => {
+ const path = "src/core/synthetic-constant-writer.ts";
+ const text =
+ 'import { DERIVED_STORE_DIR } from "./brain/path-constants.ts";\n' +
+ 'export const dir = (vault: string): string => join(vault, DERIVED_STORE_DIR, "x");\n';
+ expect(unaccountedFrom(path, text)).toEqual([path]);
+ expect(naivePathBuilders(intruder(path, text))).toContain(path);
+ });
+
+ test("a directory source answers for its own files and not for the tree below it", () => {
+ // Driven against a synthetic row rather than a real one, because the
+ // point is what the RULE would allow: an unbounded prefix let one
+ // source line absolve every module under it, and the population is
+ // only as honest as the narrowest claim it accepts.
+ const sweeping = [{ sources: ["src/core/"] }];
+ expect(attributed("src/core/doctor.ts", sweeping)).toBe(true);
+ expect(attributed("src/core/state/migrate.ts", sweeping)).toBe(false);
+ expect(attributed("src/core/brain/anticipatory-cache.ts", sweeping)).toBe(false);
+ });
+
+ test("a docblock that merely names the directory is not a path builder", () => {
+ // The false positive the lexing exists to prevent. Seven modules in
+ // the real tree mention the directory only in prose.
+ const path = "src/core/synthetic-prose.ts";
+ const text = `/** Nothing here writes to ${DERIVED_STORE_DIR}. */\nexport const x = 1;\n`;
+ expect(sweepPopulation(intruder(path, text))).not.toContain(path);
+ });
+});
diff --git a/tests/core/architecture/verdict-vocabulary-census.test.ts b/tests/core/architecture/verdict-vocabulary-census.test.ts
index 60822866..f57325b6 100644
--- a/tests/core/architecture/verdict-vocabulary-census.test.ts
+++ b/tests/core/architecture/verdict-vocabulary-census.test.ts
@@ -367,6 +367,30 @@ import {
MIRROR_OUTCOME,
MIRROR_OUTCOMES,
} from "../../../src/core/brain/shared-namespace.ts";
+import {
+ INSTALL_TARGET_ID,
+ INSTALL_TARGET_IDS,
+ isInstallTargetId,
+ isSessionRuntimeId,
+ isToolCeilingKind,
+ SESSION_RUNTIME_ID,
+ SESSION_RUNTIME_IDS,
+ TOOL_CEILING_KIND,
+ TOOL_CEILING_KINDS,
+} from "../../../src/core/runtime/host-facts.ts";
+import { CONFIG_ORIGIN, CONFIG_ORIGINS, isConfigOrigin } from "../../../src/core/validate.ts";
+import { EXPORT_FORMAT, EXPORT_FORMATS, isExportFormat } from "../../../src/core/brain/export.ts";
+import {
+ isStateReachability,
+ isStateSurfaceId,
+ isStateTier,
+ STATE_REACHABILITIES,
+ STATE_REACHABILITY,
+ STATE_SURFACE_ID,
+ STATE_SURFACE_IDS,
+ STATE_TIER,
+ STATE_TIERS,
+} from "../../../src/core/state/surfaces.ts";
import { lexCode } from "../../helpers/source-lexer.ts";
interface VocabularyUnderCensus {
@@ -1088,6 +1112,96 @@ const CENSUS: ReadonlyArray<VocabularyUnderCensus> = Object.freeze([
members: MIRROR_OUTCOMES,
guard: isMirrorOutcome,
},
+ {
+ // U9. The runtimes `o2b install --target` can name. They were bare
+ // strings validated only by a registry-lookup miss, which is a check
+ // that runs after the value has already been carried through the
+ // adapter contract, the manifest and the ownership statement - so a
+ // typo was a value the type system had no opinion about anywhere.
+ name: "INSTALL_TARGET_ID",
+ values: INSTALL_TARGET_ID,
+ members: INSTALL_TARGET_IDS,
+ guard: isInstallTargetId,
+ },
+ {
+ // U9. The runtimes whose session logs this build can LOCATE. Neither
+ // the install-target set nor the session-adapter set: Claude Code is
+ // not installable and writes the largest transcript store on a
+ // typical machine, Cursor is locatable and unparsable, and Hermes is
+ // parsable at no path this build knows. The value round-trips through
+ // the import ledger on disk, which is what the guard is for.
+ name: "SESSION_RUNTIME_ID",
+ values: SESSION_RUNTIME_ID,
+ members: SESSION_RUNTIME_IDS,
+ guard: isSessionRuntimeId,
+ },
+ {
+ // U9. What this build can say about one host's per-workspace MCP tool
+ // limit. `unknown` and `unbounded` are separate members and that
+ // separation IS the unit: collapsing them would let a host nobody
+ // checked be read as one that publishes no limit, one layer above the
+ // fail-open profile selection that made the card true.
+ name: "TOOL_CEILING_KIND",
+ values: TOOL_CEILING_KIND,
+ members: TOOL_CEILING_KINDS,
+ guard: isToolCeilingKind,
+ },
+ {
+ // U9. Which layer produced a resolved configuration value. Four
+ // members rather than three because a vault carries a COMMITTED
+ // configuration that travels with it, next to the machine-local one
+ // that does not - and for generated install content the committed
+ // tier OUTRANKS the machine, so collapsing the two would make the
+ // only interesting provenance question unanswerable.
+ name: "CONFIG_ORIGIN",
+ values: CONFIG_ORIGIN,
+ members: CONFIG_ORIGINS,
+ guard: isConfigOrigin,
+ },
+ {
+ // U9. The durable locations this build keeps inside a vault. Closed
+ // because the inventory hands the id back to a caller that may ask
+ // for one surface by name; a bare `string` there would make a typo a
+ // silently empty answer rather than a compile error.
+ name: "STATE_SURFACE_ID",
+ values: STATE_SURFACE_ID,
+ members: STATE_SURFACE_IDS,
+ guard: isStateSurfaceId,
+ },
+ {
+ // U9. What losing one surface costs. Two members because derived
+ // machine state and vault content have genuinely different recovery
+ // stories, and an inventory that folded them into one bucket could
+ // not tell an operator which deletions are reversible.
+ name: "STATE_TIER",
+ values: STATE_TIER,
+ members: STATE_TIERS,
+ guard: isStateTier,
+ },
+ {
+ // U9. What this run established about one surface. `absent` and
+ // `unchecked` are separate members for the reason ORIGIN_REACH keeps
+ // its two apart: "it is not there" and "I could not look" are
+ // different repairs, and a permission error read as an absent file
+ // sends an operator to recreate what is already on disk.
+ name: "STATE_REACHABILITY",
+ values: STATE_REACHABILITY,
+ members: STATE_REACHABILITIES,
+ guard: isStateReachability,
+ },
+ {
+ // U11. What `o2b brain export --format` accepts. It shipped as a bare
+ // type alias that NOTHING imported, while the verb compared the raw
+ // argv string against two inline literals - a contract declared with
+ // nothing behind it, which is the defect class this release closes.
+ // The guard is now the boundary the argv value crosses, and the frozen
+ // object is the dispatch table's key set, so a format with no handler
+ // is a compile error rather than a silent fall-through.
+ name: "EXPORT_FORMAT",
+ values: EXPORT_FORMAT,
+ members: EXPORT_FORMATS,
+ guard: isExportFormat,
+ },
]);
// ---------------------------------------------------------------------------
@@ -1352,7 +1466,7 @@ const SCANNED = scanVocabularies(SOURCE_TREE);
* How many four-piece vocabularies `src/` currently holds. Measured, and
* kept as an equality rather than a floor - see the population test.
*/
-const VOCABULARY_POPULATION = 63;
+const VOCABULARY_POPULATION = 71;
const REGISTERED = new Map(CENSUS.map((entry) => [entry.name, entry] as const));
describe("verdict vocabulary census", () => {
diff --git a/tests/core/architecture/write-site-census.test.ts b/tests/core/architecture/write-site-census.test.ts
index 83f6f5b1..3aba98e9 100644
--- a/tests/core/architecture/write-site-census.test.ts
+++ b/tests/core/architecture/write-site-census.test.ts
@@ -19,14 +19,32 @@
*
* ## The population, defined structurally
*
- * A module is IN POPULATION when it can address the vault: it lives
- * under one of {@link VAULT_WRITE_ROOTS}, or it is one of
- * {@link VAULT_WRITER_FILES}, or it imports the Brain vault-path
- * vocabulary (`paths.ts`) from anywhere in the tree. The last clause is
- * what stops a new in-vault writer escaping by living somewhere new.
- * Modules that write only outside the vault β€” the install adapters, the
- * machine-config exporter, the benchmark harness β€” are out by the rule
- * rather than by twenty hand-written "not a vault" entries.
+ * A module is IN POPULATION when it can address the vault. Four clauses,
+ * and the last three exist because the first two are a list of places:
+ * it lives under one of {@link VAULT_WRITE_ROOTS}, or it is one of
+ * {@link VAULT_WRITER_FILES}, or it imports the vault-location
+ * vocabulary ({@link VAULT_VOCABULARY_IMPORT_RE}), or it NAMES a vault
+ * location itself - a `join(` rooted on a vault argument
+ * ({@link VAULT_ROOT_JOIN_RE}), or the derived-store directory as a bare
+ * literal ({@link DERIVED_STORE_LITERAL_RE}).
+ *
+ * The import clause used to carry that argument alone, and the claim
+ * above it - that it "stops a new in-vault writer escaping by living
+ * somewhere new" - was measured false on this branch. `src/core/state/
+ * migrate.ts` is 960 lines that copy, remove and prune every state
+ * surface under `<vault>/.open-second-brain/` and `<vault>/Brain/`, and
+ * it was outside the population on all three counts: not under a write
+ * root, not a named writer file, and it reaches its paths through
+ * `./surfaces.ts` rather than through `paths.ts`. `src/core/doctor.ts`,
+ * which opens and removes a probe file in the vault ROOT, and
+ * `src/core/install/manifest.ts`, which writes `<vault>/.open-second-
+ * brain/install.lock.json`, escaped the same way. A rule that names only
+ * one spelling of "vault path" is a rule about that spelling.
+ *
+ * Modules that write only outside the vault - the install adapters, the
+ * machine-config exporter - are still out by the rule rather than by
+ * twenty hand-written "not a vault" entries, because none of them roots
+ * a `join(` on a vault or names the store directory.
*
* ## What counts as a WRITE
*
@@ -89,8 +107,51 @@ const VAULT_WRITER_FILES: ReadonlyArray<string> = Object.freeze([
"src/core/fs-atomic.ts",
]);
-/** The vault path vocabulary. Importing it is addressing the vault. */
-const VAULT_PATHS_IMPORT_RE = /^[ \t]*import\b[^;]*?\bfrom\s*"\.[^"]*\bpaths\.ts"/m;
+/**
+ * The vault-location vocabulary. Importing it is addressing the vault.
+ *
+ * Three modules, because three modules spell a vault location:
+ * `paths.ts` composes them, `path-constants.ts` DECLARES the names they
+ * are composed from, and `state/surfaces.ts` enumerates the durable ones
+ * as derivations a caller can invoke. `migrate.ts` reaches every state
+ * surface through the third and named neither of the first two.
+ *
+ * The basename has to be the WHOLE last segment. `\bpaths\.ts` was too
+ * loose: `-` is a word boundary, so `./hardcoded-paths.ts`,
+ * `../claude-memory-paths.ts` and `../session-paths.ts` all matched.
+ * Measured against this branch, the segment separator drops EIGHT
+ * modules that no other clause enrols - seven install adapters reaching
+ * `../session-paths.ts` (`generic.ts`, `codex.ts`, `pi.ts`, `grok.ts`,
+ * `aider.ts`, `_json-mcp.ts`, `copilot-cli.ts`), every one of which
+ * writes, plus `src/core/hygiene/scan-repo.ts` on
+ * `./hardcoded-paths.ts`, which does not. Seven writers leaving a
+ * write-site census sounds like a loss and is not: they write into the
+ * runtimes' own config directories, never into a vault, and the
+ * docblock above says so as the rule that keeps them out. Admitting
+ * them would mean seven hand-written "not a vault" exclusions arguing
+ * against the rule beside them.
+ *
+ * Over-inclusion is the safe direction for a gate in general; here it
+ * defeats the gate's own stated boundary, so the segment separator is
+ * required.
+ */
+const VAULT_VOCABULARY_IMPORT_RE =
+ /^[ \t]*import\b[^;]*?\bfrom\s*"\.(?:[^"]*\/)?(?:paths|path-constants|surfaces)\.ts"/m;
+
+/**
+ * A path built from a vault root by hand, which is what `doctor.ts` does
+ * and no import can reveal. Matched on the CODE view, so the receiver has
+ * to be a real identifier rather than a name inside a quoted example.
+ */
+const VAULT_ROOT_JOIN_RE = /\bjoin\s*\(\s*(?:vault|vaultPath|vaultRoot|vaultDir)\b/;
+
+/**
+ * The derived-store directory spelled as a bare literal, which is how
+ * `install/manifest.ts` names `<vault>/.open-second-brain/`. Read off the
+ * comment-stripped view, which keeps string CONTENTS: on the code view a
+ * literal's body is blanked and nothing would ever match.
+ */
+const DERIVED_STORE_LITERAL_RE = /"\.open-second-brain"|'\.open-second-brain'/;
/**
* Calls that put file bytes on disk, or remove, move, or re-permission a
@@ -217,10 +278,25 @@ const WRITE_CATEGORY = Object.freeze({
archiveTransfer: "archive-transfer",
/** Permission or metadata change on an existing file; writes no bytes. */
metadataOnly: "metadata-only",
+ /** A file written only to find out whether the location accepts writes, then removed. */
+ writeProbe: "write-probe",
+ /** Bytes written into a disposable directory shaped like a vault, never an operator's. */
+ fixtureMaterialisation: "fixture-materialisation",
} as const);
type WriteCategory = (typeof WRITE_CATEGORY)[keyof typeof WRITE_CATEGORY];
+/**
+ * The bar an exclusion reason has to clear, matching the one
+ * `state-surface-census` already applies to its own exclusion map. An
+ * argument for why a write site cannot route through the shared writer
+ * does not fit in eighty characters; a label does.
+ */
+const MIN_REASON_LENGTH = 80;
+
+/** Words that mean "nobody has decided yet", which is not a reason. */
+const LAZY_REASON_RE = /\bTODO\b|\bfor now\b|\blater\b/i;
+
interface WriteExclusion {
/** Every category this file's direct calls fall in. Never empty. */
readonly categories: ReadonlyArray<WriteCategory>;
@@ -264,7 +340,11 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/brain/capture/telegram-capture.ts": {
categories: [C.appendOnlyLedger],
calls: ["appendFileSync"],
- reason: "one JSON line per capture-routing decision, appended to the decision log.",
+ reason:
+ "one JSON line per capture-routing decision, appended to the decision log. Every shared " +
+ "writer in the set rewrites a whole file, so routing an append through one would have to " +
+ "read the log back first - and this log is the only record that a rejected capture arrived " +
+ "at all, which is precisely what a read-modify-rewrite race loses.",
},
"src/core/brain/continuity/store.ts": {
categories: [C.appendOnlyLedger],
@@ -277,7 +357,11 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/brain/decisions/receipts.ts": {
categories: [C.appendOnlyLedger],
calls: ["appendFileSync"],
- reason: "one receipt JSON line per decision, appended to a per-config shard.",
+ reason:
+ "one receipt JSON line per decision, appended to a per-device shard so two machines syncing " +
+ "one vault never write the same file. The append is the commit point: the timeline emission " +
+ "after it is fail-soft precisely because the receipt is already durable, and a whole-file " +
+ "rewrite would put that ordering the other way round.",
},
"src/core/brain/diagnostics.ts": {
categories: [C.appendOnlyLedger],
@@ -308,7 +392,11 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/brain/health/edit-history.ts": {
categories: [C.appendOnlyLedger],
calls: ["appendFileSync"],
- reason: "deduplicated edit-history lines appended to the per-page history log.",
+ reason:
+ "deduplicated edit-history lines appended to the per-page history log, in one call per " +
+ "batch. The dedup runs against what is already on disk, so the file is read before every " +
+ "append - and rewriting it from that read is exactly the operation that would drop a line " +
+ "another process appended in between.",
},
"src/core/brain/idempotency-ledger.ts": {
categories: [C.appendOnlyLedger],
@@ -337,22 +425,38 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/brain/metrics.ts": {
categories: [C.appendOnlyLedger],
calls: ["appendFileSync"],
- reason: "one JSON line per surface metrics record.",
+ reason:
+ "one JSON line per surface metrics record, appended to that surface's own JSONL. These are " +
+ "observations of runs that already finished and nothing regenerates them, so the file only " +
+ "ever grows; a shared writer would turn every measurement into a full rewrite of the " +
+ "history it is being added to.",
},
"src/core/brain/pref-audit.ts": {
categories: [C.appendOnlyLedger],
calls: ["appendFileSync"],
- reason: "one rendered line per preference mutation, appended to that preference's audit.",
+ reason:
+ "one rendered line per preference mutation, appended to that preference's audit. It is the " +
+ "provenance behind a rule the agents follow and cannot be reconstructed from the preference " +
+ "file it describes, so losing an interleaved line to a rewrite would lose the only copy of " +
+ "a promotion, an edit or a retirement.",
},
"src/core/brain/query-demand.ts": {
categories: [C.appendOnlyLedger],
calls: ["appendFileSync"],
- reason: "one JSON line per query-demand record, appended under the log lock.",
+ reason:
+ "one JSON line per query-demand record, appended under the log lock, with the byte-cap " +
+ "compaction running inside that same lock immediately afterwards. The append and the " +
+ "compaction are deliberately different operations, and the second already goes through " +
+ "`atomicWriteFileSync` - a rewrite is a rewrite and an append is not.",
},
"src/core/brain/recurrence.ts": {
categories: [C.appendOnlyLedger],
calls: ["appendFileSync"],
- reason: "one JSON line per recurrence event.",
+ reason:
+ "one JSON line per recurrence event, appended behind `assertVaultIdentityForWrite` and an " +
+ "`ensureInsideVault` on the directory. The support counts a proposal is judged on ARE the " +
+ "accumulated lines, so the file is only ever extended; nothing in it is ever revised, and a " +
+ "rewrite would be a way to lose evidence rather than a way to save it.",
},
// --- Lifecycle moves: an existing artifact changes location ------------
@@ -372,7 +476,11 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/brain/dream-apply.ts": {
categories: [C.lifecycleMove],
calls: ["renameSync"],
- reason: "moves every consumed signal out of `inbox/` into its processed location.",
+ reason:
+ "moves every consumed signal out of `inbox/` into its processed location. A rename authors " +
+ "no content - the signal file's bytes are the same bytes at a new name - and it is " +
+ "deliberately best-effort per signal, because a source already moved by an earlier run is " +
+ "benign on a rerun while a real I/O failure is still surfaced.",
},
"src/core/brain/dream-stage.ts": {
categories: [C.lifecycleMove, C.retentionDelete],
@@ -434,7 +542,11 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/brain/recompile.ts": {
categories: [C.lifecycleMove],
calls: ["renameSync"],
- reason: "moves an orphaned generated page into the cleanup directory under a free name.",
+ reason:
+ "moves an orphaned generated page into the cleanup directory under a name proven free by " +
+ "the suffix loop immediately above the call, so the move can never overwrite a page already " +
+ "parked there. The bytes are the page's own and are unchanged by the move; there is no " +
+ "content for a writer to render and nothing to make atomic beyond `rename(2)` itself.",
},
"src/core/brain/signal-retire.ts": {
categories: [C.lifecycleMove],
@@ -463,12 +575,20 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/brain/exact-state.ts": {
categories: [C.retentionDelete],
calls: ["rmSync"],
- reason: "clears one aspect's exact-state file; the absence IS the cleared state.",
+ reason:
+ "clears one aspect's exact-state file behind `assertVaultIdentityForWrite`, after the " +
+ "aspect name has been validated and the file confirmed to exist. The absence IS the cleared " +
+ "state on this lane - there is no empty-file representation to write instead - so no shared " +
+ "writer has a form for this operation.",
},
"src/core/brain/gaps/gap-loop.ts": {
categories: [C.retentionDelete],
calls: ["rmSync"],
- reason: "prunes closed gap tasks past their retention window.",
+ reason:
+ "prunes closed gap tasks past their retention window, and only those whose own frontmatter " +
+ "carries a parseable `closed_at` older than the cutoff - a task with an unreadable or " +
+ "missing date is skipped rather than swept. A delete writes no bytes, so there is nothing " +
+ "for a shared writer to make atomic; the frontmatter re-check is the safety here.",
},
"src/core/brain/git/ingest.ts": {
categories: [C.retentionDelete],
@@ -480,7 +600,11 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/brain/ingest/checkpoint.ts": {
categories: [C.retentionDelete],
calls: ["rmSync"],
- reason: "clears one ingest plan's checkpoint; absence is the terminal state.",
+ reason:
+ "clears one ingest plan's checkpoint behind `assertVaultIdentityForWrite`, reporting false " +
+ "rather than throwing when there was nothing to clear. Absence is the terminal state for a " +
+ "resume point: a plan with no checkpoint starts from the beginning, which is the same thing " +
+ "a checkpoint rewritten to empty would have to mean.",
},
"src/core/brain/ingest/sources-registry.ts": {
categories: [C.retentionDelete],
@@ -526,12 +650,20 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/brain/write-session/store.ts": {
categories: [C.retentionDelete],
calls: ["rmSync"],
- reason: "deletes write-session files, individually and by sweep. Idempotent by `force`.",
+ reason:
+ "deletes write-session files, individually and by sweep, idempotent by `force` so a " +
+ "concurrent delete of the same session is not an error. A write session is a staging " +
+ "record whose whole content is its existence for the length of the session, so removal is " +
+ "the operation and there are no bytes for a shared writer to author.",
},
"src/core/search/tuning-store.ts": {
categories: [C.retentionDelete],
calls: ["rmSync"],
- reason: "deletes the persisted tuning state; absence is the reset state.",
+ reason:
+ "deletes the persisted tuning state, which returns search to the shipped defaults until the " +
+ "next tuning run. Absence is the reset state by design: the reader re-validates whatever it " +
+ "finds against the parameter grid, so writing a neutral document instead would be a claim " +
+ "that a tuning run had happened and chosen it.",
},
"src/mcp/artifact-store.ts": {
categories: [C.retentionDelete],
@@ -542,6 +674,19 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
},
// --- Machine-readable artifacts: JSON, sqlite, archives ----------------
+ "src/cli/brain/verbs/export.ts": {
+ categories: [C.machineArtifact],
+ calls: ["renameSync", "unlinkSync", "writeSync"],
+ reason:
+ "`o2b brain export --format transcripts-jsonl` spools the corpus record by " +
+ "record to a temp sibling of the operator-named `--out` and renames it into " +
+ "place, so peak memory is one conversation rather than the whole corpus and a " +
+ "guard refusal still leaves nothing written. `atomicWriteFileSync` cannot serve " +
+ "it: that helper takes the complete contents as a string, which is precisely " +
+ "the materialisation being avoided. The `unlinkSync` removes the spool on a " +
+ "refusal and after a stdout run. Never a vault note - the source is the " +
+ "runtimes' own session directories and the target is a path the operator named.",
+ },
"src/cli/brain/verbs/continuity.ts": {
categories: [C.machineArtifact],
calls: ["writeFileSync"],
@@ -565,7 +710,11 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/brain/link-graph/co-occurrence.ts": {
categories: [C.machineArtifact],
calls: ["writeFileSync"],
- reason: "regenerates the co-occurrence JSON artifact in full from the current graph.",
+ reason:
+ "regenerates the co-occurrence JSON artifact in full from the current link graph on every " +
+ "run, so there is no prior content a torn write could destroy - the next pass recomputes " +
+ "the whole document from the pages, which are the source of truth. No note is involved and " +
+ "no Markdown parser ever reads it.",
},
"src/core/brain/portability/pointer.ts": {
categories: [C.machineArtifact],
@@ -644,12 +793,20 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"src/core/search/session-focus.ts": {
categories: [C.machineArtifact, C.retentionDelete],
calls: ["rmSync", "writeFileSync"],
- reason: "the per-session focus JSON and the call that clears it.",
+ reason:
+ "the per-session focus JSON, one small document per session scope, and the call that clears " +
+ "it. Each entry expires on its own and is rewritten whole by the next `focus` call, so a " +
+ "torn file costs one session's standing query and is replaced rather than repaired; the " +
+ "clear removes the file because an empty focus and no focus are the same state.",
},
"src/core/search/tuning.ts": {
categories: [C.machineArtifact],
calls: ["writeFileSync"],
- reason: "persists the tuning result JSON, keyed by a hash of the dataset it came from.",
+ reason:
+ "persists the tuning result JSON, keyed by a hash of the dataset it came from, so a result " +
+ "is only ever read back against the same inputs that produced it. A partial file fails that " +
+ "key check and is treated as no result at all, which is the same outcome as never having " +
+ "run the tuning pass - the cost of a torn write is one re-run.",
},
// --- Bulk subtree transfer ---------------------------------------------
@@ -677,6 +834,23 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"store. The unlink removes a partial store archive whose snapshot was refused.",
},
+ "src/core/state/migrate.ts": {
+ categories: [C.archiveTransfer, C.lifecycleMove, C.retentionDelete],
+ calls: ["copyFileSync", "rmSync", "rmdirSync"],
+ reason:
+ "`o2b state migrate` moves the whole declared state tree to another filesystem, which is " +
+ "the one operation here that a shared writer would make WORSE rather than safer. Each file " +
+ "is copied byte-for-byte and re-digested at the destination against the digest the plan " +
+ "bound, so a torn copy is caught by the hash and unwound; `atomicWriteFileSync` takes a " +
+ "complete string, which for a multi-gigabyte SQLite index is the materialisation being " +
+ "avoided, and it would re-encode bytes this pass must not touch. The `rmSync` removes each " +
+ "source only after every copy landed AND verified, and removes the destination copies again " +
+ "on the unwind - the same file list, in reverse. `rmdirSync` prunes only directories " +
+ "`pruneIfEmpty` proved empty, so nothing that arrived beside the migration is ever removed. " +
+ "The manifest that binds all of it DOES go through `atomicWriteFileSync`, because that one " +
+ "is a rewrite of a small document and is the record a rollback reads.",
+ },
+
// --- Concurrency primitives --------------------------------------------
"src/core/brain/sync-lockfile.ts": {
categories: [C.lockPrimitive],
@@ -696,6 +870,32 @@ const DIRECT_WRITE_EXCLUSIONS: Readonly<Record<string, WriteExclusion>> = Object
"are written, so there is nothing for a writer to make atomic.",
},
+ // --- Write probes: bytes written to learn whether writing works --------
+ "src/core/doctor.ts": {
+ categories: [C.writeProbe],
+ calls: ["rmSync", "writeSync"],
+ reason:
+ "`checkVaultWriteable` opens `<vault>/.open-second-brain-doctor-test` and removes it again, " +
+ "and `checkConfigWriteable` does the same to the config path, creating it only if it was " +
+ "absent. The QUESTION is whether the open and the write succeed, so routing them through a " +
+ "helper that reports success or throws would answer a different question - and the answer " +
+ "the doctor gives is the raw errno, which is what the fix line it prints is derived from. " +
+ "Zero bytes are written and the probe never outlives the check.",
+ },
+
+ // --- Fixture materialisation: a vault-shaped disposable directory ------
+ "src/core/bench/fixture.ts": {
+ categories: [C.fixtureMaterialisation],
+ calls: ["writeFileSync"],
+ reason:
+ "materialises a repo-local benchmark fixture into the caller-supplied disposable directory, " +
+ "whose note paths were checked against traversal and absolute forms at parse time. It is in " +
+ "population because it joins `Brain/` onto a directory it calls a vault, which is exactly " +
+ "the shape the widened rule is meant to catch; what it writes is fixture text into a tree " +
+ "the bench harness creates and deletes, never an operator's vault, so there is no " +
+ "durability guarantee for an atomic writer to add.",
+ },
+
// --- Mixed: an accept protocol that moves, appends and rolls back ------
"src/core/brain/skill-proposals.ts": {
categories: [C.appendOnlyLedger, C.lifecycleMove, C.retentionDelete],
@@ -743,14 +943,19 @@ function readSourceTree(): CensusFile[] {
/**
* Whether this module can address the vault - see the docblock.
*
- * `withoutComments` rather than `code`, because the clause that matters
- * reads an import SPECIFIER, which is a string: the other view blanks it
- * and no module would ever be found to import `paths.ts` again.
+ * Both views, and which clause reads which is not interchangeable. The
+ * import specifier and the store-directory literal ARE strings, so they
+ * are read off `withoutComments`; the other view blanks a literal's body
+ * and no module would ever be found to import `paths.ts` again. The
+ * `join(vault` clause is read off `code`, because a name inside a quoted
+ * example builds no path.
*/
-function addressesVault(path: string, withoutComments: string): boolean {
+function addressesVault(path: string, views: LexedSource): boolean {
if (VAULT_WRITE_ROOTS.some((root) => path.startsWith(root))) return true;
if (VAULT_WRITER_FILES.includes(path)) return true;
- return VAULT_PATHS_IMPORT_RE.test(withoutComments);
+ if (VAULT_VOCABULARY_IMPORT_RE.test(views.withoutComments)) return true;
+ if (DERIVED_STORE_LITERAL_RE.test(views.withoutComments)) return true;
+ return VAULT_ROOT_JOIN_RE.test(views.code);
}
interface FsImports {
@@ -838,7 +1043,7 @@ function lexedViews(file: CensusFile): LexedSource {
*/
function classify(file: CensusFile): CensusRow | null {
const views = lexedViews(file);
- if (!addressesVault(file.path, views.withoutComments)) return null;
+ if (!addressesVault(file.path, views)) return null;
const direct = directWriteCalls(views.code, fsImports(views.withoutComments));
const shared = [...views.code.matchAll(SHARED_WRITE_RE)].length;
if (direct.size === 0 && shared === 0) return null;
@@ -858,11 +1063,31 @@ const SOURCE_TREE = readSourceTree();
const ROWS = census(SOURCE_TREE);
const DIRECT_ROWS = ROWS.filter((row) => row.directCalls.length > 0);
-/** Measured modules calling a filesystem write directly. An equality. */
-const DIRECT_WRITE_ROWS = 64;
+/**
+ * Measured modules calling a filesystem write directly. An equality.
+ *
+ * 65 -> 68, and every one of the three is a module the old population
+ * rule could not see rather than a write site that appeared: the widened
+ * rule enrolled `src/core/state/migrate.ts` (the state-tree move),
+ * `src/core/doctor.ts` (the vault and config write probes) and
+ * `src/core/bench/fixture.ts` (fixture materialisation into a
+ * vault-shaped disposable directory). Each is now carrying a written
+ * exclusion above.
+ */
+const DIRECT_WRITE_ROWS = 68;
-/** Measured modules reaching a write through a shared helper. An equality. */
-const SHARED_HELPER_ROWS = 94;
+/**
+ * Measured modules reaching a write through a shared helper. An equality.
+ *
+ * 95 -> 97, from the same widening and nothing else:
+ * `src/core/install/manifest.ts` writes `<vault>/.open-second-brain/
+ * install.lock.json` through `atomicWriteFileSync` and was out of
+ * population entirely, and `src/core/state/migrate.ts` writes the
+ * migration manifest through the same helper. The shared class is the
+ * half of this census that needs no exclusion, so a module arriving here
+ * is the outcome the record wants.
+ */
+const SHARED_HELPER_ROWS = 97;
describe("in-vault write-site census", () => {
test("every direct-fs write site carries a written exclusion", () => {
@@ -895,12 +1120,26 @@ describe("in-vault write-site census", () => {
expect(drifted).toEqual([]);
});
- test("every exclusion carries a non-empty reason", () => {
+ test("every exclusion carries a reason that is an argument, not a label", () => {
+ // `length > 0` was the whole bar here, which "x" cleared. The sibling
+ // censuses - `state-surface-census` and `forward-pointer-rail` - both
+ // require a real minimum and reject the words that mean "not yet",
+ // and there is no reading on which THIS record deserves a lower one:
+ // it is the list of write sites the shared binding cannot cover, and
+ // a one-word entry in it is an unexamined site wearing an exclusion.
+ const thin: string[] = [];
+ const lazy: string[] = [];
+ const uncategorised: string[] = [];
for (const [path, entry] of Object.entries(DIRECT_WRITE_EXCLUSIONS)) {
- expect(`${path}: ${entry.reason.trim().length > 0} ${entry.categories.length > 0}`).toBe(
- `${path}: true true`,
- );
+ if (entry.reason.trim().length < MIN_REASON_LENGTH) {
+ thin.push(`${path} (${entry.reason.trim().length})`);
+ }
+ if (LAZY_REASON_RE.test(entry.reason)) lazy.push(path);
+ if (entry.categories.length === 0) uncategorised.push(path);
}
+ expect(thin.toSorted().join("\n")).toBe("");
+ expect(lazy.toSorted().join("\n")).toBe("");
+ expect(uncategorised.toSorted().join("\n")).toBe("");
});
test("the two writers this unit routed through a shared helper are gone from the record", () => {
@@ -990,6 +1229,49 @@ describe("the census can fail", () => {
expect(classify(outsider)).toBeNull();
});
+ test("a writer in a brand-new directory that joins onto a vault is in population", () => {
+ // The hole the widened rule closes, driven as a shape rather than as
+ // the three real modules that fell through it: living somewhere no
+ // list mentions, and importing no path vocabulary, used to be enough.
+ const path = "src/core/somewhere-new/synthetic-vault-writer.ts";
+ const text =
+ 'import { writeFileSync } from "node:fs";\n' +
+ 'import { join } from "node:path";\n' +
+ "export function stamp(vault: string): void {\n" +
+ ' writeFileSync(join(vault, "marker"), "x");\n' +
+ "}\n";
+ expect(unlistedWith({ path, text })).toEqual([path]);
+ });
+
+ test("a writer naming the derived store as a bare literal is in population too", () => {
+ // The second half of the widening: `install/manifest.ts` never says
+ // `join(vault` and never imports the vocabulary - it spells the
+ // directory name itself.
+ const path = "src/core/somewhere-new/synthetic-store-writer.ts";
+ const text =
+ 'import { writeFileSync } from "node:fs";\n' +
+ 'import { join } from "node:path";\n' +
+ "export function stamp(root: string): void {\n" +
+ ' writeFileSync(join(root, ".open-second-brain", "marker.json"), "{}");\n' +
+ "}\n";
+ expect(unlistedWith({ path, text })).toEqual([path]);
+ });
+
+ test("the derived-store name in prose alone does not enrol a module", () => {
+ // The complement, and the reason the literal clause reads the
+ // comment-stripped view: a docblock that mentions the directory
+ // builds no path into it.
+ expect(
+ classify({
+ path: "src/core/somewhere-new/synthetic-prose.ts",
+ text:
+ "/** Never writes to .open-second-brain, and says so here. */\n" +
+ 'import { writeFileSync } from "node:fs";\n' +
+ 'writeFileSync("x", "y");\n',
+ }),
+ ).toBeNull();
+ });
+
test("the detectors still match the shapes they measure", () => {
// A regex that stopped matching would report a clean sweep over an
// empty set. Pin the measurement, not only its verdict - and pin it
diff --git a/tests/core/brain/dream-checkpoints.test.ts b/tests/core/brain/dream-checkpoints.test.ts
index f716acc3..2cfe17af 100644
--- a/tests/core/brain/dream-checkpoints.test.ts
+++ b/tests/core/brain/dream-checkpoints.test.ts
@@ -30,8 +30,19 @@ import { tmpdir } from "node:os";
import { join, relative } from "node:path";
import { dream } from "../../../src/core/brain/dream.ts";
+import { applyDreamPlan } from "../../../src/core/brain/dream-apply.ts";
+import { scanBrain } from "../../../src/core/brain/dream-scan.ts";
+import type { PlanState } from "../../../src/core/brain/dream-plan.ts";
+import type { RefreshResult } from "../../../src/core/brain/dream-refresh.ts";
+import { runHealEnrichment } from "../../../src/core/brain/heal-run.ts";
+import { loadBrainConfig } from "../../../src/core/brain/policy.ts";
import { brainDirs, dreamRunsDir } from "../../../src/core/brain/paths.ts";
-import { SafeguardTimeoutError, type Safeguard } from "../../../src/core/brain/safeguard.ts";
+import {
+ createSafeguard,
+ SafeguardAbortError,
+ SafeguardTimeoutError,
+ type Safeguard,
+} from "../../../src/core/brain/safeguard.ts";
import { writeSignal } from "../../../src/core/brain/signal.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
@@ -234,16 +245,37 @@ describe("dream workrun checkpoints are truthful", () => {
// ----- 2. The pre-finalize safeguard checkpoint -----------------------------
describe("dream safeguard checkpoints", () => {
- test("a changed run checkpoints five times, the last before finalize", () => {
+ /**
+ * The scan's own checkpoint count for THIS vault, measured rather than
+ * written down.
+ *
+ * The pass has five checkpoints of its own, but it CONTAINS the scan,
+ * and the scan is the pass's largest unbounded read - so the pass's
+ * total is five plus whatever the scan consults. Probing it with a real
+ * `scanBrain` call keeps the arithmetic honest as the fixture changes,
+ * and the probe is free of side effects: the scan opens no writer.
+ */
+ function scanCheckpoints(target: string = vault): number {
+ const probe = countingGuard(null);
+ scanBrain(target, { safeguard: probe.guard });
+ return probe.calls();
+ }
+
+ test("a changed run checkpoints five times of its own, plus the scan it contains", () => {
seedPromotion();
+ const scan = scanCheckpoints();
+ // Non-vacuous: a fixture whose scan crossed no boundary would make
+ // the sum below true of an unguarded scan too.
+ expect(scan).toBeGreaterThan(0);
const { guard, calls } = countingGuard(null);
dream(vault, { now: NOW, safeguard: guard });
- expect(calls()).toBe(5);
+ expect(calls()).toBe(5 + scan);
});
test("the pre-finalize checkpoint fires and leaves the workrun dangling", () => {
seedPromotion();
- const { guard } = countingGuard(5);
+ // The pass's fifth own checkpoint, counted from the scan's last one.
+ const { guard } = countingGuard(scanCheckpoints() + 5);
expect(() => dream(vault, { now: NOW, safeguard: guard })).toThrow(SafeguardTimeoutError);
const phases = workrunPhases();
// The tail is covered: every mutation landed, the journal recorded it,
@@ -253,11 +285,99 @@ describe("dream safeguard checkpoints", () => {
expect(existsSync(join(brainDirs(vault).preferences, "pref-ckpt-topic.md"))).toBe(true);
});
- test("a no-op run checkpoints once, at entry", () => {
+ test("a no-op run checkpoints once at entry, plus the scan it contains", () => {
+ const scan = scanCheckpoints();
const { guard, calls } = countingGuard(null);
const summary = dream(vault, { now: NOW, safeguard: guard });
expect(summary.changed).toBe(false);
- expect(calls()).toBe(1);
+ expect(calls()).toBe(1 + scan);
+ });
+
+ test("the heal enrichment inside a pass is guarded like the step on its own", () => {
+ // Heal is the second unit a full pass contains that walks the vault
+ // rather than the decided plan, and it was reached through
+ // `runHealEnrichment(vault)` with no options: inside a real pass the
+ // enrichment reads and rewrote every user page unguarded, however
+ // long the budget said the pass had.
+ makeNotes();
+ seedPromotion();
+ const scan = scanCheckpoints();
+
+ // Heal's own count for the same page set, measured on a vault of its
+ // own so the probe's rewrites cannot change what the pass then sees.
+ const twin = mkdtempSync(join(tmpdir(), "o2b-dream-ckpt-heal-"));
+ let heal: number;
+ try {
+ const twinConfig = join(configHome, "heal-twin.yaml");
+ atomicWriteFileSync(twinConfig, `vault: ${twin}\n`);
+ bootstrapBrain(twin, { configPath: twinConfig });
+ makeNotes(twin);
+ const probe = countingGuard(null);
+ runHealEnrichment(twin, { safeguard: probe.guard });
+ heal = probe.calls();
+ } finally {
+ rmSync(twin, { recursive: true, force: true });
+ }
+ expect(heal).toBeGreaterThan(0);
+
+ const { guard, calls } = countingGuard(null);
+ dream(vault, { now: NOW, safeguard: guard, gates: { heal_enrich: true } });
+ expect(calls()).toBe(5 + scan + heal);
+ });
+});
+
+// ----- 2b. A safeguard stop is not a heal failure ---------------------------
+
+describe("the mutation stage does not absorb a safeguard stop", () => {
+ /** The empty decided plan: this test is about the heal call, not planning. */
+ function emptyPlan(): PlanState {
+ return {
+ newUnconfirmed: [],
+ retires: [],
+ notedRedundant: [],
+ retainPinned: [],
+ signalsToMove: new Map(),
+ contradictionTopics: new Set(),
+ signalsSuppressed: [],
+ quarantined: [],
+ topicKeyContentions: [],
+ };
+ }
+
+ function emptyRefresh(): RefreshResult {
+ return { confirmed: new Set(), updated: new Map(), bandDrops: [], outcomeRegressions: [] };
+ }
+
+ function applyWith(safeguard: Safeguard): void {
+ applyDreamPlan({
+ vault,
+ cfg: loadBrainConfig(vault),
+ now: NOW,
+ plan: emptyPlan(),
+ refresh: emptyRefresh(),
+ agentName: "claude",
+ wikilinkToRun: "[[Brain/log/2026-05-23]]",
+ healEnrichEnabled: true,
+ safeguard,
+ workrun: null,
+ });
+ }
+
+ test("a tripped deadline in heal leaves the stage rather than warning and returning 0", () => {
+ makeNotes();
+ // The catch around the heal call is there for "one page would not
+ // rewrite", not for "the run is over". Absorbing a safeguard stop
+ // into a stderr warning and `heal_enriched: 0` reports a pass that
+ // enriched nothing where the truth is a pass that was stopped.
+ expect(() => applyWith(countingGuard(1).guard)).toThrow(SafeguardTimeoutError);
+ });
+
+ test("an abort is re-raised as an abort, not flattened into a warning", () => {
+ makeNotes();
+ const controller = new AbortController();
+ controller.abort();
+ const guard = createSafeguard({ operation: "dream", signal: controller.signal });
+ expect(() => applyWith(guard)).toThrow(SafeguardAbortError);
});
});
diff --git a/tests/core/brain/export-transcripts.test.ts b/tests/core/brain/export-transcripts.test.ts
new file mode 100644
index 00000000..f42d79e1
--- /dev/null
+++ b/tests/core/brain/export-transcripts.test.ts
@@ -0,0 +1,419 @@
+/**
+ * The transcript dataset builder (`o2b brain export --format
+ * transcripts-jsonl`).
+ *
+ * Two properties carry the unit. The first is that a conversation record
+ * is a CONVERSATION - ordered messages under one session, never a slice -
+ * because a harness handed an assistant reply whose prompt was filtered
+ * away learns from a prompt nobody wrote. The second is that nothing this
+ * walk cannot account for is silently dropped: a `.jsonl` no adapter
+ * recognises refuses the whole export, the same answer `collectExportRows`
+ * gives a preference file it cannot parse.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ streamTranscriptConversations,
+ TRANSCRIPT_EXPORT_SCHEMA_VERSION,
+ type TranscriptConversation,
+ type TranscriptExportOptions,
+ type TranscriptExportSummary,
+} from "../../../src/core/brain/export-transcripts.ts";
+import { redactForEgress } from "../../../src/core/egress/guard.ts";
+import { EGRESS_OUTCOME } from "../../../src/core/egress/guard.ts";
+
+function tempDir(): string {
+ return mkdtempSync(join(tmpdir(), "o2b-transcript-export-"));
+}
+
+function write(dir: string, name: string, lines: ReadonlyArray<unknown>): string {
+ const path = join(dir, name);
+ writeFileSync(path, lines.map((l) => JSON.stringify(l)).join("\n") + "\n", "utf8");
+ return path;
+}
+
+/** A two-turn Claude Code transcript: one user line, one assistant line. */
+function claudeLines(opts: { readonly at: string; readonly uuid?: string }): unknown[] {
+ return [
+ {
+ parentUuid: null,
+ sessionId: "sess-1",
+ entrypoint: "cli",
+ type: "user",
+ uuid: opts.uuid ?? "u-1",
+ timestamp: opts.at,
+ message: { role: "user", content: "how do I export a transcript" },
+ },
+ {
+ parentUuid: opts.uuid ?? "u-1",
+ sessionId: "sess-1",
+ entrypoint: "cli",
+ type: "assistant",
+ uuid: "a-1",
+ timestamp: opts.at,
+ message: {
+ role: "assistant",
+ content: [
+ { type: "text", text: "with the export verb" },
+ { type: "tool_use", name: "Read", id: "call-1", input: { path: "/etc/passwd" } },
+ ],
+ },
+ },
+ // A queue-operation line is not a turn, and a payload-less turn carries
+ // nothing a dataset can learn from; neither may become a message.
+ { type: "queue-operation", op: "enqueue" },
+ ];
+}
+
+function codexLines(at: string): unknown[] {
+ return [
+ { timestamp: at, type: "session_meta", payload: { originator: "codex_exec" } },
+ {
+ timestamp: at,
+ type: "response_item",
+ payload: { type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+ },
+ ];
+}
+
+/** Drain the stream into its records and its summary. */
+async function drain(
+ options: TranscriptExportOptions,
+): Promise<{ records: TranscriptConversation[]; summary: TranscriptExportSummary }> {
+ const records: TranscriptConversation[] = [];
+ const it = streamTranscriptConversations(options);
+ for (;;) {
+ // oxlint-disable-next-line no-await-in-loop
+ const step = await it.next();
+ if (step.done === true) return { records, summary: step.value };
+ records.push(step.value);
+ }
+}
+
+describe("transcript conversation records", () => {
+ test("one record per session file, messages in transcript order", async () => {
+ const dir = tempDir();
+ try {
+ write(dir, "one.jsonl", claudeLines({ at: "2026-08-01T10:00:00.000Z" }));
+ const { records, summary } = await drain({ source: dir });
+ expect(records.length).toBe(1);
+ const record = records[0]!;
+ expect(record.schema).toBe(TRANSCRIPT_EXPORT_SCHEMA_VERSION);
+ expect(record.runtime).toBe("claude");
+ expect(record.session_id).toBe("one.jsonl");
+ expect(record.messages.map((m) => m.role)).toEqual(["user", "assistant"]);
+ expect(record.messages.map((m) => m.text)).toEqual([
+ "how do I export a transcript",
+ "with the export verb",
+ ]);
+ expect(record.message_count).toBe(2);
+ expect(record.started_at).toBe("2026-08-01T10:00:00.000Z");
+ expect(record.ended_at).toBe("2026-08-01T10:00:00.000Z");
+ expect(summary.scanned).toBe(1);
+ expect(summary.exported).toBe(1);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a message carries tool NAMES and never tool inputs", async () => {
+ // The input of a `Read` is a host path and the input of a `Bash` is a
+ // command line; a conversation dataset is not a tool-trace dataset, and
+ // carrying the arguments would widen the corpus for nobody's benefit.
+ const dir = tempDir();
+ try {
+ write(dir, "one.jsonl", claudeLines({ at: "2026-08-01T10:00:00.000Z" }));
+ const { records } = await drain({ source: dir });
+ expect(records[0]!.messages[1]!.tools).toEqual(["Read"]);
+ expect(JSON.stringify(records[0])).not.toContain("/etc/passwd");
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a nested directory is walked and the records are path-ordered", async () => {
+ const dir = tempDir();
+ try {
+ mkdirSync(join(dir, "nested"));
+ write(dir, "a.jsonl", claudeLines({ at: "2026-08-01T10:00:00.000Z" }));
+ write(join(dir, "nested"), "b.jsonl", claudeLines({ at: "2026-08-02T10:00:00.000Z" }));
+ const { records } = await drain({ source: dir });
+ expect(records.map((r) => r.session_id)).toEqual(["a.jsonl", "b.jsonl"]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a single file is a legal source", async () => {
+ const dir = tempDir();
+ try {
+ const path = write(dir, "one.jsonl", claudeLines({ at: "2026-08-01T10:00:00.000Z" }));
+ const { records } = await drain({ source: path });
+ expect(records.map((r) => r.session_id)).toEqual(["one.jsonl"]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("the runtime filter keeps one runtime and counts what it set aside", async () => {
+ const dir = tempDir();
+ try {
+ write(dir, "a-claude.jsonl", claudeLines({ at: "2026-08-01T10:00:00.000Z" }));
+ write(dir, "b-codex.jsonl", codexLines("2026-08-01T11:00:00.000Z"));
+ const { records, summary } = await drain({ source: dir, runtime: "codex" });
+ expect(records.map((r) => r.runtime)).toEqual(["codex"]);
+ expect(summary.scanned).toBe(2);
+ expect(summary.other_runtime).toBe(1);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("an unregistered runtime is refused by name", async () => {
+ const dir = tempDir();
+ try {
+ write(dir, "one.jsonl", claudeLines({ at: "2026-08-01T10:00:00.000Z" }));
+ await expect(drain({ source: dir, runtime: "cursor" })).rejects.toThrow(/cursor/);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("the window selects whole conversations by their start", async () => {
+ const dir = tempDir();
+ try {
+ write(dir, "old.jsonl", claudeLines({ at: "2026-07-01T10:00:00.000Z" }));
+ write(dir, "new.jsonl", claudeLines({ at: "2026-08-01T10:00:00.000Z" }));
+ const { records, summary } = await drain({
+ source: dir,
+ since: new Date("2026-07-15T00:00:00.000Z"),
+ });
+ expect(records.map((r) => r.session_id)).toEqual(["new.jsonl"]);
+ // Not sliced: the kept conversation is whole.
+ expect(records[0]!.message_count).toBe(2);
+ expect(summary.outside_window).toBe(1);
+
+ const until = await drain({ source: dir, until: new Date("2026-07-15T00:00:00.000Z") });
+ expect(until.records.map((r) => r.session_id)).toEqual(["old.jsonl"]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a .jsonl no adapter recognises refuses the export by name", async () => {
+ // The same answer the preference export gives an unparseable rule: a
+ // corpus that quietly omits a transcript reads exactly like a machine
+ // that never recorded it.
+ const dir = tempDir();
+ try {
+ write(dir, "one.jsonl", claudeLines({ at: "2026-08-01T10:00:00.000Z" }));
+ write(dir, "stranger.jsonl", [{ hello: "world" }]);
+ await expect(drain({ source: dir })).rejects.toThrow(/stranger\.jsonl/);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a source that does not exist is refused, not reported as an empty corpus", async () => {
+ const dir = tempDir();
+ try {
+ await expect(drain({ source: join(dir, "absent") })).rejects.toThrow(/absent/);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a transcript with no learnable turn is reported, never emitted empty", async () => {
+ const dir = tempDir();
+ try {
+ write(dir, "empty.jsonl", [
+ { parentUuid: null, sessionId: "s", entrypoint: "cli", type: "queue-operation" },
+ ]);
+ const { records, summary } = await drain({ source: dir });
+ expect(records).toEqual([]);
+ expect(summary.scanned).toBe(1);
+ expect(summary.no_messages).toBe(1);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a zero-byte transcript is counted, not made into a refusal", async () => {
+ // Claude Code leaves these behind whenever a session opens and is
+ // killed before the first turn flushes, and "move this file out of
+ // the source directory" does not scale to a store that holds a
+ // thousand transcripts. A file with no bytes has nothing to omit.
+ const dir = tempDir();
+ try {
+ write(dir, "good.jsonl", claudeLines({ at: "2026-08-01T10:00:00.000Z" }));
+ writeFileSync(join(dir, "flushed-nothing.jsonl"), "", "utf8");
+ const { records, summary } = await drain({ source: dir });
+ expect(records.map((r) => r.session_id)).toEqual(["good.jsonl"]);
+ expect(summary.scanned).toBe(2);
+ expect(summary.empty).toBe(1);
+ // Every scanned file on exactly one counter, still.
+ expect(
+ summary.exported +
+ summary.other_runtime +
+ summary.outside_window +
+ summary.no_messages +
+ summary.empty,
+ ).toBe(summary.scanned);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a file whose first line is blank but whose second is a turn still refuses", async () => {
+ // The complement of the case above, and the reason the empty check
+ // reads the file's SIZE rather than trusting an empty first line:
+ // this file has content, so skipping it would be the silent omission
+ // the refusal exists to prevent.
+ const dir = tempDir();
+ try {
+ writeFileSync(
+ join(dir, "leading-blank.jsonl"),
+ "\n" + JSON.stringify({ hello: "world" }) + "\n",
+ "utf8",
+ );
+ await expect(drain({ source: dir })).rejects.toThrow(/leading-blank\.jsonl/);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("--since refuses a transcript whose first turn carries no timestamp", async () => {
+ // The docblock on `startInstant` forbids treating an unreadable
+ // timestamp as either inside or outside the window, "both readings
+ // are a guess, and one of them silently drops a transcript". Every
+ // adapter synthesises the epoch for a missing timestamp, which parses
+ // fine and sorts before any realistic `--since` - so the guarantee
+ // held only for a malformed string, which no adapter ever emits, and
+ // the case that does occur took the forbidden path.
+ const dir = tempDir();
+ try {
+ write(dir, "clockless.jsonl", [
+ {
+ parentUuid: null,
+ sessionId: "sess-1",
+ entrypoint: "cli",
+ type: "user",
+ uuid: "u-1",
+ message: { role: "user", content: "no timestamp on this line" },
+ },
+ ]);
+ await expect(
+ drain({ source: dir, since: new Date("2026-07-15T00:00:00.000Z") }),
+ ).rejects.toThrow(/clockless\.jsonl.*no timestamp/s);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a clockless transcript still exports when no window is asked for", async () => {
+ // Refusing over a field nobody read would be a refusal for its own
+ // sake; the window is the only thing that depends on the value.
+ const dir = tempDir();
+ try {
+ write(dir, "clockless.jsonl", [
+ {
+ parentUuid: null,
+ sessionId: "sess-1",
+ entrypoint: "cli",
+ type: "user",
+ uuid: "u-1",
+ message: { role: "user", content: "no timestamp on this line" },
+ },
+ ]);
+ const { records } = await drain({ source: dir });
+ expect(records.map((r) => r.session_id)).toEqual(["clockless.jsonl"]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a BARE high-entropy session filename is refused, not exported verbatim", async () => {
+ // The identifier branch tests identifier values for VENDOR prefixes
+ // only, on the argument that "record ids and slugs are long mixed runs
+ // by construction". That argument is about ids this vault generates.
+ // `session_id` is a foreign harness's filename, so an unexplained
+ // 24-character mixed run in it is not an id by construction - and it
+ // used to export with exit 0 while its `sk-`-prefixed sibling refused
+ // the whole run.
+ const dir = tempDir();
+ try {
+ write(dir, "Xk7Qp2Rm9Wz4Tn6Yb8Vc3Ld5.jsonl", claudeLines({ at: "2026-08-01T10:00:00.000Z" }));
+ const { records } = await drain({ source: dir });
+ const verdict = redactForEgress("brain-export", records[0]!, { foreignIdentifiers: true });
+ expect(verdict.outcome).toBe(EGRESS_OUTCOME.refusedSecretIdentifier);
+ if (verdict.outcome === EGRESS_OUTCOME.refusedSecretIdentifier) {
+ expect(verdict.secretIdentifiers).toContain("session_id");
+ // Locations, not values: the refusal must not echo the name.
+ expect(verdict.detail).not.toContain("Xk7Qp2Rm9Wz4Tn6Yb8Vc3Ld5");
+ }
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a BARE high-entropy turn id is refused too", async () => {
+ const dir = tempDir();
+ try {
+ write(
+ dir,
+ "one.jsonl",
+ claudeLines({ at: "2026-08-01T10:00:00.000Z", uuid: "Xk7Qp2Rm9Wz4Tn6Yb8Vc3Ld5" }),
+ );
+ const { records } = await drain({ source: dir });
+ const verdict = redactForEgress("brain-export", records[0]!, { foreignIdentifiers: true });
+ expect(verdict.outcome).toBe(EGRESS_OUTCOME.refusedSecretIdentifier);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a uuid-named transcript is NOT refused: it is a content address", async () => {
+ // The widening must not refuse every Claude Code session, whose files
+ // are named by uuid - hex and dashes, which the redactor already
+ // carves out as an identifier shape a bundle has to carry unchanged.
+ const dir = tempDir();
+ try {
+ write(
+ dir,
+ "f47ac10b-58cc-4372-a567-0e02b2c3d479.jsonl",
+ claudeLines({
+ at: "2026-08-01T10:00:00.000Z",
+ uuid: "a5d9e0f1-2b3c-4d5e-8f90-1a2b3c4d5e6f",
+ }),
+ );
+ const { records } = await drain({ source: dir });
+ const verdict = redactForEgress("brain-export", records[0]!, { foreignIdentifiers: true });
+ expect(verdict.outcome).toBe(EGRESS_OUTCOME.released);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a secret-shaped turn id lands where the egress guard refuses it", async () => {
+ // The record shape is what decides whether the guard can see a
+ // credential at all: an identifier is never rewritten, so it has to sit
+ // under a key the structural redactor reads as an identity.
+ const dir = tempDir();
+ try {
+ write(
+ dir,
+ "one.jsonl",
+ claudeLines({ at: "2026-08-01T10:00:00.000Z", uuid: "sk-live-9f2ba7c1d4e8" }),
+ );
+ const { records } = await drain({ source: dir });
+ const verdict = redactForEgress("brain-export", records[0]!);
+ expect(verdict.outcome).toBe(EGRESS_OUTCOME.refusedSecretIdentifier);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/tests/core/brain/heal-run.test.ts b/tests/core/brain/heal-run.test.ts
index 9a2af58a..a75ce328 100644
--- a/tests/core/brain/heal-run.test.ts
+++ b/tests/core/brain/heal-run.test.ts
@@ -11,6 +11,11 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { runHealEnrichment } from "../../../src/core/brain/heal-run.ts";
+import {
+ createSafeguard,
+ SafeguardTimeoutError,
+ type Safeguard,
+} from "../../../src/core/brain/safeguard.ts";
let vault: string;
@@ -66,3 +71,65 @@ describe("runHealEnrichment safety", () => {
expect(readFileSync(ego, "utf8")).not.toContain("[[Acme]]");
});
});
+
+describe("where the deadline is actually honoured", () => {
+ /** A guard that never trips and counts how often it was consulted. */
+ function countingGuard(): { guard: Safeguard; count: () => number } {
+ let seen = 0;
+ return {
+ guard: Object.freeze({
+ operation: "dream",
+ timeoutMs: null,
+ checkpoint: () => {
+ seen += 1;
+ },
+ }),
+ count: () => seen,
+ };
+ }
+
+ test("the phrase build is consulted before, not only after", () => {
+ // Two pages, so the arithmetic distinguishes a per-page checkpoint
+ // from a per-phase one. The run consults the guard:
+ //
+ // 1x after the listing walk (uninterruptible, so bounded on exit),
+ // Px in the index loop,
+ // 1x before prepareHealPhrases (uninterruptible, so bounded on
+ // entry - this is the one that was missing, which left the sort
+ // and regex-escape of every title and alias in the vault sitting
+ // between two checkpoints),
+ // Px in the rewrite loop.
+ //
+ // 2 * P + 2. Before the fix it was 2 * P + 1, and the phrase build
+ // ran unconditionally no matter how long the budget had been gone.
+ note("Notes/Acme.md", "---\ntitle: Acme\n---\nThe Acme page.\n");
+ note("Notes/ref.md", "---\ntitle: Ref\n---\nwe rely on Acme daily\n");
+ const { guard, count } = countingGuard();
+ const result = runHealEnrichment(vault, { safeguard: guard });
+ expect(result.scanned).toBe(2);
+ expect(count()).toBe(2 * result.scanned + 2);
+ });
+
+ test("an already-elapsed budget stops before the phrase build", () => {
+ note("Notes/Acme.md", "---\ntitle: Acme\n---\nThe Acme page.\n");
+ const ref = note("Notes/ref.md", "---\ntitle: Ref\n---\nwe rely on Acme daily\n");
+ expect(() => runHealEnrichment(vault, { safeguard: trippedGuard() })).toThrow(
+ SafeguardTimeoutError,
+ );
+ // Nothing rewritten: the stop is at a boundary, before any write.
+ expect(readFileSync(ref, "utf8")).not.toContain("[[Acme]]");
+ });
+});
+
+/** A guard whose deadline is already in the past on its first check. */
+function trippedGuard(): Safeguard {
+ let calls = 0;
+ return createSafeguard({
+ operation: "dream",
+ timeoutMs: 1,
+ now: () => {
+ calls += 1;
+ return calls === 1 ? 0 : 1_000;
+ },
+ });
+}
diff --git a/tests/core/brain/maintenance/maintenance.test.ts b/tests/core/brain/maintenance/maintenance.test.ts
index dd6d2126..09586387 100644
--- a/tests/core/brain/maintenance/maintenance.test.ts
+++ b/tests/core/brain/maintenance/maintenance.test.ts
@@ -19,7 +19,9 @@ import {
import {
dailyWindowContains,
evaluateGates,
+ LANE_TASK,
runMaintenance,
+ type MaintenanceTask,
} from "../../../../src/core/brain/maintenance/lane.ts";
import {
appendJournal,
@@ -423,10 +425,10 @@ describe("the consecutive-failure streak", () => {
}
// Named: the refused task runs, and only that one - the second task's
// own refusal is untouched by a retry that does not name it.
- const tasks = [
+ const tasks: ReadonlyArray<MaintenanceTask> = [
{ name: TASK, run: async () => void 0 },
{
- name: "dream",
+ name: LANE_TASK.dream,
run: async () => {
throw new Error("should not have been reached");
},
diff --git a/tests/core/brain/policy-safe-loaders.test.ts b/tests/core/brain/policy-safe-loaders.test.ts
index bbe94942..06badcfd 100644
--- a/tests/core/brain/policy-safe-loaders.test.ts
+++ b/tests/core/brain/policy-safe-loaders.test.ts
@@ -37,6 +37,7 @@ import {
loadActiveMostAppliedSafe,
loadFeedbackDefaultScopeSafe,
loadGuardrailsConfigSafe,
+ loadInstallBlockSafe,
loadIntegrityConfigSafe,
loadMaintenanceConfigSafe,
loadNotesConfigSafe,
@@ -94,6 +95,16 @@ const SAFE_LOADERS = [
load: loadMaintenanceConfigSafe as (vault: string) => unknown,
absentValue: BRAIN_MAINTENANCE_DEFAULTS as unknown,
},
+ {
+ // The raw block, not a resolved value: the four-tier install resolver
+ // has to tell "the vault block set this key" apart from "it did not",
+ // and a resolved value cannot express the difference. Serving defaults
+ // from a broken config would generate hooks and an MCP registration
+ // the operator never asked for, on a file nothing could parse.
+ name: "loadInstallBlockSafe",
+ load: loadInstallBlockSafe as (vault: string) => unknown,
+ absentValue: undefined as unknown,
+ },
{
// Coverage is what an operator turned ON, so answering `false` from
// the defaults on a config that merely has a typo would silently
diff --git a/tests/core/brain/policy/install-block.test.ts b/tests/core/brain/policy/install-block.test.ts
new file mode 100644
index 00000000..b2b45318
--- /dev/null
+++ b/tests/core/brain/policy/install-block.test.ts
@@ -0,0 +1,227 @@
+/**
+ * The `install:` block of `<vault>/Brain/_brain.yaml`, and the four-tier
+ * resolution that reads it.
+ *
+ * The block exists because generated install and hook content is the one
+ * output whose inputs must travel WITH the vault: two machines cloning
+ * one vault must not get different hook files because one of them has a
+ * stale key in its own `~/.config/open-second-brain/config.yaml`. That is
+ * why the committed vault tier outranks the user tier here, which is the
+ * opposite of nothing else in this tree - so it is pinned by a test that
+ * drives all four layers rather than left to a comment.
+ *
+ * The refusal is the other half. `loadBrainConfigDetailed` already
+ * distinguishes an ABSENT `_brain.yaml` (a vault nobody has initialised -
+ * the next tier answers) from an UNREADABLE one (the operator's settings
+ * exist and are not in force). Generated install content is a WRITER, and
+ * v1.49.0 established that a writer cannot infer intent from a file it
+ * could not parse: it names the parse failure and the file, and produces
+ * nothing.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
+import { brainConfigPath } from "../../../../src/core/brain/paths.ts";
+import { validateBrainConfig } from "../../../../src/core/brain/policy/validate.ts";
+import { parseBrainYaml } from "../../../../src/core/brain/yaml-parse.ts";
+import {
+ BRAIN_INSTALL_DEFAULTS,
+ INSTALL_HOOK_TIMEOUT_SECONDS_MAX,
+ INSTALL_TOOL_PROFILE_NAMES,
+} from "../../../../src/core/brain/policy/blocks/install.ts";
+import {
+ INSTALL_HOOK_TIMEOUT_CONFIG_KEY,
+ INSTALL_TOOL_PROFILE_CONFIG_KEY,
+ resolveInstallHookTimeoutSeconds,
+ resolveInstallToolProfile,
+} from "../../../../src/core/install/settings.ts";
+import { CONFIG_ORIGIN } from "../../../../src/core/validate.ts";
+import { TOOL_SURFACE_PROFILES } from "../../../../src/mcp/profiles.ts";
+
+let vault: string;
+let configHome: string;
+let configPath: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-install-block-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-install-block-cfg-"));
+ configPath = join(configHome, "config.yaml");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+/** Write a whole `_brain.yaml`; `null` leaves the vault without one. */
+function writeVaultConfig(body: string | null): void {
+ if (body === null) return;
+ atomicWriteFileSync(brainConfigPath(vault), body);
+}
+
+function writeUserConfig(body: string): void {
+ atomicWriteFileSync(configPath, body);
+}
+
+function source() {
+ return { vault, configPath };
+}
+
+function parse(body: string) {
+ return validateBrainConfig(parseBrainYaml(body), "<install-block-test>");
+}
+
+describe("install: block parsing", () => {
+ test("parses both keys", () => {
+ const config = parse(
+ 'schema_version: 1\ninstall:\n hook_timeout_seconds: 45\n tool_profile: "recall"\n',
+ );
+ expect(config.install).toEqual({ hook_timeout_seconds: 45, tool_profile: "recall" });
+ });
+
+ test("an absent block leaves install undefined", () => {
+ expect(parse("schema_version: 1\n").install).toBeUndefined();
+ });
+
+ test("rejects a non-positive hook_timeout_seconds by name", () => {
+ expect(() => parse("schema_version: 1\ninstall:\n hook_timeout_seconds: 0\n")).toThrow(
+ /install\.hook_timeout_seconds/,
+ );
+ });
+
+ test("rejects a non-integer hook_timeout_seconds by name", () => {
+ expect(() => parse("schema_version: 1\ninstall:\n hook_timeout_seconds: 2.5\n")).toThrow(
+ /install\.hook_timeout_seconds/,
+ );
+ });
+
+ test("rejects a hook_timeout_seconds past the ceiling by name", () => {
+ expect(() =>
+ parse(
+ `schema_version: 1\ninstall:\n hook_timeout_seconds: ${INSTALL_HOOK_TIMEOUT_SECONDS_MAX + 1}\n`,
+ ),
+ ).toThrow(/install\.hook_timeout_seconds/);
+ });
+
+ test("rejects an unknown tool_profile by name, listing the known ones", () => {
+ let message = "";
+ try {
+ parse('schema_version: 1\ninstall:\n tool_profile: "nope"\n');
+ } catch (err) {
+ message = (err as Error).message;
+ }
+ expect(message).toContain("install.tool_profile");
+ for (const name of INSTALL_TOOL_PROFILE_NAMES) expect(message).toContain(name);
+ });
+
+ test("the accepted names are exactly the tool-surface profile table's keys", () => {
+ expect([...INSTALL_TOOL_PROFILE_NAMES].toSorted()).toEqual(
+ Object.keys(TOOL_SURFACE_PROFILES).toSorted(),
+ );
+ });
+});
+
+describe("install setting resolution - three layers, highest first", () => {
+ test("the committed vault block beats the user-level key", () => {
+ writeVaultConfig("schema_version: 1\ninstall:\n hook_timeout_seconds: 30\n");
+ writeUserConfig(`${INSTALL_HOOK_TIMEOUT_CONFIG_KEY}: 20\n`);
+ expect(resolveInstallHookTimeoutSeconds(source())).toEqual({
+ value: 30,
+ origin: CONFIG_ORIGIN.vaultConfig,
+ });
+ });
+
+ test("the user-level key wins when the vault block does not set the key", () => {
+ writeVaultConfig('schema_version: 1\ninstall:\n tool_profile: "recall"\n');
+ writeUserConfig(`${INSTALL_HOOK_TIMEOUT_CONFIG_KEY}: 20\n`);
+ expect(resolveInstallHookTimeoutSeconds(source())).toEqual({
+ value: 20,
+ origin: CONFIG_ORIGIN.userConfig,
+ });
+ });
+
+ test("an absent vault config and an absent user key yield the compiled default", () => {
+ expect(resolveInstallHookTimeoutSeconds(source())).toEqual({
+ value: BRAIN_INSTALL_DEFAULTS.hook_timeout_seconds,
+ origin: CONFIG_ORIGIN.default,
+ });
+ });
+
+ test("the same three layers decide the tool profile", () => {
+ // The bottom tier is per HOST - the target's own `RUNTIME_FACTS`
+ // row, not one compiled name - because a profile that fits a host
+ // capping a workspace at forty tools is not the profile that fits a
+ // host with no published limit. `kiro` declares none, so the bottom
+ // tier selects no profile at all; `tests/core/install/
+ // tool-ceiling.test.ts` drives the row-bearing side.
+ expect(resolveInstallToolProfile(source(), "kiro")).toEqual({
+ value: null,
+ origin: CONFIG_ORIGIN.default,
+ });
+
+ writeUserConfig(`${INSTALL_TOOL_PROFILE_CONFIG_KEY}: minimal\n`);
+ expect(resolveInstallToolProfile(source(), "kiro")).toEqual({
+ value: "minimal",
+ origin: CONFIG_ORIGIN.userConfig,
+ });
+
+ writeVaultConfig('schema_version: 1\ninstall:\n tool_profile: "recall"\n');
+ expect(resolveInstallToolProfile(source(), "kiro")).toEqual({
+ value: "recall",
+ origin: CONFIG_ORIGIN.vaultConfig,
+ });
+ });
+
+ test("a user-config value that is not a known profile is refused by name", () => {
+ writeUserConfig(`${INSTALL_TOOL_PROFILE_CONFIG_KEY}: nope\n`);
+ expect(() => resolveInstallToolProfile(source(), "kiro")).toThrow(
+ new RegExp(INSTALL_TOOL_PROFILE_CONFIG_KEY),
+ );
+ });
+
+ test("a user-config hook timeout that is not a positive integer is refused by name", () => {
+ writeUserConfig(`${INSTALL_HOOK_TIMEOUT_CONFIG_KEY}: abc\n`);
+ expect(() => resolveInstallHookTimeoutSeconds(source())).toThrow(
+ new RegExp(INSTALL_HOOK_TIMEOUT_CONFIG_KEY),
+ );
+ });
+});
+
+describe("an unreadable vault config refuses rather than defaulting", () => {
+ const UNREADABLE = "schema_version: 1\ninstall:\n hook_timeout_seconds: [broken\n";
+
+ test("the hook-timeout resolver names the parse failure and the file", () => {
+ writeVaultConfig(UNREADABLE);
+ let message = "";
+ try {
+ resolveInstallHookTimeoutSeconds(source());
+ } catch (err) {
+ message = (err as Error).message;
+ }
+ expect(message).toContain(brainConfigPath(vault));
+ expect(message.length).toBeGreaterThan(brainConfigPath(vault).length);
+ });
+
+ test("the tool-profile resolver refuses on the same file", () => {
+ writeVaultConfig(UNREADABLE);
+ expect(() => resolveInstallToolProfile(source(), "kiro")).toThrow();
+ });
+
+ test("the refusal is not silently replaced by the default", () => {
+ writeVaultConfig(UNREADABLE);
+ writeUserConfig(`${INSTALL_HOOK_TIMEOUT_CONFIG_KEY}: 20\n`);
+ expect(() => resolveInstallHookTimeoutSeconds(source())).toThrow();
+ });
+
+ test("a block that does not validate refuses too", () => {
+ writeVaultConfig("schema_version: 1\ninstall:\n hook_timeout_seconds: 0\n");
+ expect(() => resolveInstallHookTimeoutSeconds(source())).toThrow(
+ /install\.hook_timeout_seconds/,
+ );
+ });
+});
diff --git a/tests/core/brain/sessions/discover.test.ts b/tests/core/brain/sessions/discover.test.ts
new file mode 100644
index 00000000..0fd7dd65
Binary files /dev/null and b/tests/core/brain/sessions/discover.test.ts differ
diff --git a/tests/core/brain/sessions/read-lines.test.ts b/tests/core/brain/sessions/read-lines.test.ts
new file mode 100644
index 00000000..33b9684b
--- /dev/null
+++ b/tests/core/brain/sessions/read-lines.test.ts
@@ -0,0 +1,212 @@
+/**
+ * The shared session line reader.
+ *
+ * Every adapter used to do `readFileSync(path, "utf8").split("\n")`, which
+ * handled the awkward cases by accident: a trailing newline, a missing one,
+ * a blank line in the middle, a CRLF ending, an empty file. A chunked reader
+ * has to handle each of them on purpose, and gets one more case the whole-file
+ * read could never hit - a multi-byte character straddling a chunk boundary,
+ * which a naive per-chunk decode turns into U+FFFD.
+ *
+ * These tests pin all of it, plus the reader's own retained-bytes accounting,
+ * which is what `streaming-memory.test.ts` asserts the bound on.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ lineReaderRetainedBytes,
+ readFirstLine,
+ readLines,
+ resetLineReaderRetainedBytes,
+} from "../../../../src/core/brain/sessions/read-lines.ts";
+
+function fixture(content: string | Uint8Array): string {
+ const dir = mkdtempSync(join(tmpdir(), "osb-read-lines-"));
+ const path = join(dir, "session.jsonl");
+ writeFileSync(path, content);
+ return path;
+}
+
+async function collect(path: string): Promise<string[]> {
+ const out: string[] = [];
+ for await (const line of readLines(path)) out.push(line);
+ return out;
+}
+
+/**
+ * The chunk sizes this runtime's file stream actually hands out for
+ * `path`, read the same way {@link readLines} reads it.
+ *
+ * The bounds below used to be hand-picked round numbers with about 3.8x
+ * of slack (a measured 262,144-byte window against a 1,000,000-byte
+ * bound), and a round number cannot tell a reader holding ONE chunk from
+ * one holding four - which is the module's whole invariant. Measuring the
+ * ceiling instead makes that invariant - "never more than one chunk plus
+ * the partial line carried into it" - the thing the test asserts.
+ */
+async function streamChunkBytes(path: string): Promise<ReadonlyArray<number>> {
+ const reader = Bun.file(path).stream().getReader();
+ const sizes: number[] = [];
+ try {
+ for (;;) {
+ // oxlint-disable-next-line no-await-in-loop
+ const chunk = await reader.read();
+ if (chunk.done === true || chunk.value === undefined) break;
+ sizes.push(chunk.value.byteLength);
+ }
+ } finally {
+ await reader.cancel().catch(() => undefined);
+ }
+ return sizes;
+}
+
+/** Longest line of `lines` in bytes - the largest carry the reader can hold. */
+function longestLineBytes(lines: ReadonlyArray<string>): number {
+ return lines.reduce((max, line) => Math.max(max, Buffer.byteLength(line, "utf8")), 0);
+}
+
+describe('readLines β€” the cases split("\\n") handled by accident', () => {
+ test("a trailing newline does not produce a phantom final line", async () => {
+ expect(await collect(fixture("a\nb\n"))).toEqual(["a", "b"]);
+ });
+
+ test("a missing trailing newline still yields the last line", async () => {
+ expect(await collect(fixture("a\nb"))).toEqual(["a", "b"]);
+ });
+
+ test("a blank line in the middle is yielded, not swallowed", async () => {
+ expect(await collect(fixture("a\n\nb\n"))).toEqual(["a", "", "b"]);
+ });
+
+ test("a CRLF ending does not leak its carriage return into the line", async () => {
+ expect(await collect(fixture("a\r\nb\r\n"))).toEqual(["a", "b"]);
+ // A lone CR inside the line is content, not a terminator.
+ expect(await collect(fixture("a\rb\r\n"))).toEqual(["a\rb"]);
+ });
+
+ test("an empty file yields nothing", async () => {
+ expect(await collect(fixture(""))).toEqual([]);
+ });
+
+ test("a file that is a single newline yields one empty line", async () => {
+ expect(await collect(fixture("\n"))).toEqual([""]);
+ });
+});
+
+describe("readLines β€” multi-byte characters across chunk boundaries", () => {
+ /**
+ * Irregular line lengths of mostly 3- and 4-byte characters over more than
+ * a megabyte: whatever chunk size the runtime picks, boundaries land inside
+ * a character. A per-chunk decode without `{ stream: true }` yields U+FFFD.
+ */
+ test("characters straddling a chunk boundary survive intact", async () => {
+ const expected: string[] = [];
+ for (let i = 0; i < 8000; i++) {
+ expected.push(`${"a".repeat(i % 7)}${"\u{1F9E0}\u2026".repeat(20)}${i}`);
+ }
+ const path = fixture(`${expected.join("\n")}\n`);
+ expect(Bun.file(path).size).toBeGreaterThan(1_000_000);
+
+ const got = await collect(path);
+ expect(got.length).toBe(expected.length);
+ expect(got.join("\n")).toBe(expected.join("\n"));
+ expect(got.some((l) => l.includes("\uFFFD"))).toBe(false);
+ });
+});
+
+describe("readFirstLine β€” stops at the first newline", () => {
+ test("returns the first line of a multi-line file", async () => {
+ expect(await readFirstLine(fixture("first\nsecond\nthird\n"))).toBe("first");
+ });
+
+ test("returns the whole content when there is no newline at all", async () => {
+ expect(await readFirstLine(fixture("only"))).toBe("only");
+ });
+
+ test("returns the empty string for an empty file", async () => {
+ expect(await readFirstLine(fixture(""))).toBe("");
+ });
+
+ test("strips the CR of a CRLF first line", async () => {
+ expect(await readFirstLine(fixture("first\r\nsecond\r\n"))).toBe("first");
+ });
+
+ test("reads exactly one chunk when the first line is short", async () => {
+ const path = fixture(`head\n${"x".repeat(4_000_000)}\n`);
+ const size = Bun.file(path).size;
+ const [firstChunk] = await streamChunkBytes(path);
+ resetLineReaderRetainedBytes();
+ expect(await readFirstLine(path)).toBe("head");
+ // Equality, not "less than a round number". The eager form this
+ // module exists to remove - `readFileSync` then `indexOf("\n")` -
+ // records ZERO, because it never enters the chunk loop, and a bound
+ // written only as an upper limit is satisfied by zero. A reader that
+ // buffered four chunks before yielding fails the same assertion from
+ // the other side.
+ expect(lineReaderRetainedBytes()).toBe(firstChunk!);
+ // And the chunk really is a small window on this file, rather than
+ // the runtime having handed the whole thing over in one piece.
+ expect(lineReaderRetainedBytes()).toBeLessThan(size / 8);
+ });
+});
+
+describe("the reader's retained-bytes accounting", () => {
+ test("reset drops the high-water mark to zero", async () => {
+ await collect(fixture(`${"line\n".repeat(1000)}`));
+ resetLineReaderRetainedBytes();
+ expect(lineReaderRetainedBytes()).toBe(0);
+ });
+
+ test("the window is one chunk plus the partial line, and nothing more", async () => {
+ const line = "y".repeat(200);
+ const path = fixture(`${`${line}\n`.repeat(20_000)}`);
+ const size = Bun.file(path).size;
+ expect(size).toBeGreaterThan(4_000_000);
+ const chunks = await streamChunkBytes(path);
+ const largestChunk = Math.max(...chunks);
+ expect(chunks.length).toBeGreaterThan(1);
+ resetLineReaderRetainedBytes();
+ let chars = 0;
+ let seen = 0;
+ for await (const line of readLines(path)) {
+ chars += line.length;
+ seen++;
+ }
+ expect(seen).toBe(20_000);
+ expect(chars).toBe(20_000 * 200);
+ // The module's stated invariant, asserted from both sides rather than
+ // against a round number: at least one whole chunk was held (a reader
+ // that materialised the file and split it records nothing at all),
+ // and never more than one chunk plus the longest line that can be
+ // carried across a boundary (a reader buffering two chunks doubles
+ // this and fails).
+ expect(lineReaderRetainedBytes()).toBeGreaterThanOrEqual(largestChunk);
+ expect(lineReaderRetainedBytes()).toBeLessThanOrEqual(largestChunk + longestLineBytes([line]));
+ });
+
+ test("a file with no line terminator is reported at its true cost", async () => {
+ // The carry IS the retained window when nothing terminates it, and
+ // the accounting says so rather than reporting the chunk alone. An
+ // accounting that counted only the chunk would report a 4 MB window
+ // as 256 KB, and every bound above it would be measuring nothing.
+ const path = fixture("z".repeat(4_000_000));
+ resetLineReaderRetainedBytes();
+ expect((await collect(path)).length).toBe(1);
+ expect(lineReaderRetainedBytes()).toBeGreaterThanOrEqual(4_000_000);
+ });
+
+ test("the carry does not survive the loop that made it", async () => {
+ const tail = "TAIL-WITH-NO-NEWLINE";
+ expect(await collect(fixture(`a\n${tail}`))).toEqual(["a", tail]);
+ // A carry hoisted to module scope - the obvious way to save an
+ // allocation per call - would prepend the previous file's unterminated
+ // tail to this one, and would keep those bytes retained between runs.
+ resetLineReaderRetainedBytes();
+ expect(await collect(fixture("b\n"))).toEqual(["b"]);
+ expect(lineReaderRetainedBytes()).toBe(2);
+ });
+});
diff --git a/tests/core/brain/sessions/session-files.test.ts b/tests/core/brain/sessions/session-files.test.ts
new file mode 100644
index 00000000..7429d1e0
--- /dev/null
+++ b/tests/core/brain/sessions/session-files.test.ts
@@ -0,0 +1,138 @@
+/**
+ * `sessionFilesUnder`, the one answer to "which files under this path are
+ * session transcripts".
+ *
+ * It was extracted so the directory import and the transcript dataset
+ * export could not drift about what a session log is, and it shipped with
+ * no test of its own. Two of the three things it promises were unheld: the
+ * typed `IO` refusal covered the root `statSync` and the per-entry
+ * `lstatSync` but not the recursive `readdirSync` between them, so one
+ * unreadable subdirectory escaped as a raw errno through both callers -
+ * where the sibling sweep in `discover.ts` reports the same condition and
+ * carries on; and the recursion had no depth bound at all while the sweep
+ * beside it walks a declared glob.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ isSessionFileName,
+ sessionFilesUnder,
+} from "../../../../src/core/brain/sessions/session-files.ts";
+import {
+ SESSION_FILE_EXTENSION,
+ SessionImportError,
+} from "../../../../src/core/brain/sessions/types.ts";
+
+function tempDir(): string {
+ return mkdtempSync(join(tmpdir(), "o2b-session-files-"));
+}
+
+function touch(path: string): void {
+ writeFileSync(path, "{}\n", "utf8");
+}
+
+describe("sessionFilesUnder", () => {
+ test("a directory yields its transcripts, sorted, and nothing else", () => {
+ const dir = tempDir();
+ try {
+ touch(join(dir, "b.jsonl"));
+ touch(join(dir, "a.jsonl"));
+ touch(join(dir, "README.md"));
+ mkdirSync(join(dir, "nested"));
+ touch(join(dir, "nested", "c.jsonl"));
+ expect(sessionFilesUnder(dir)).toEqual([
+ join(dir, "a.jsonl"),
+ join(dir, "b.jsonl"),
+ join(dir, "nested", "c.jsonl"),
+ ]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a named FILE is returned whatever its extension", () => {
+ const dir = tempDir();
+ try {
+ const path = join(dir, "transcript.log");
+ touch(path);
+ expect(sessionFilesUnder(path)).toEqual([path]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a path that does not exist is a typed refusal, not an empty list", () => {
+ const dir = tempDir();
+ try {
+ expect(() => sessionFilesUnder(join(dir, "absent"))).toThrow(SessionImportError);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("an unreadable SUBDIRECTORY is a typed refusal naming it, not a raw errno", () => {
+ // The hole: the top-level `statSync` and the per-entry `lstatSync`
+ // were both wrapped, and the recursion between them was not. One
+ // mode-000 directory therefore took down the whole import and the
+ // whole export with an `EACCES` nobody had translated.
+ if (process.getuid?.() === 0) return; // root reads a 000 directory anyway
+ const dir = tempDir();
+ const locked = join(dir, "locked");
+ try {
+ touch(join(dir, "readable.jsonl"));
+ mkdirSync(locked);
+ touch(join(locked, "hidden.jsonl"));
+ chmodSync(locked, 0o000);
+ let caught: unknown = null;
+ try {
+ sessionFilesUnder(dir);
+ } catch (err) {
+ caught = err;
+ }
+ expect(caught).toBeInstanceOf(SessionImportError);
+ expect((caught as SessionImportError).code).toBe("IO");
+ expect((caught as SessionImportError).message).toContain(locked);
+ } finally {
+ chmodSync(locked, 0o700);
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("a tree deeper than the bound is refused rather than recursed into", () => {
+ const dir = tempDir();
+ try {
+ let deep = dir;
+ for (let i = 0; i < 40; i++) {
+ deep = join(deep, `d${i}`);
+ mkdirSync(deep);
+ }
+ touch(join(deep, "buried.jsonl"));
+ expect(() => sessionFilesUnder(dir)).toThrow(/nests deeper than/);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+});
+
+describe("what a session log is, stated once", () => {
+ test("the walk accepts exactly the declared extension", () => {
+ expect(isSessionFileName(`x${SESSION_FILE_EXTENSION}`)).toBe(true);
+ expect(isSessionFileName("x.json")).toBe(false);
+ });
+
+ test("the Codex discovery glob is built from the same constant", async () => {
+ // Three definitions of "a session log" existed: this walk's `.jsonl`,
+ // the Codex rows' `**/*.json*`, and the adapters, which parse only
+ // line-delimited JSON. The middle one made `.json` rollouts
+ // discoverable and importable while `import-session <dir>` and
+ // `export --transcripts <dir>` skipped every one of them in silence.
+ const { resolveSessionRootsFor } = await import("../../../../src/core/runtime/host-facts.ts");
+ const roots = resolveSessionRootsFor("codex", { home: "/home/nobody", env: {} });
+ expect(roots.length).toBeGreaterThan(0);
+ for (const root of roots) expect(root.glob).toBe(`**/*${SESSION_FILE_EXTENSION}`);
+ });
+});
diff --git a/tests/core/brain/sessions/streaming-memory.test.ts b/tests/core/brain/sessions/streaming-memory.test.ts
new file mode 100644
index 00000000..15f34922
--- /dev/null
+++ b/tests/core/brain/sessions/streaming-memory.test.ts
@@ -0,0 +1,264 @@
+/**
+ * Every adapter reads its session through the shared line reader, and that
+ * reader's window stays bounded while the adapter iterates.
+ *
+ * The five adapters used to `readFileSync(path, "utf8")` and then `split("\n")`,
+ * so peak retained memory was roughly twice the file size BEFORE the first turn
+ * was yielded, and the `async *` generator bought nothing - it iterated an array
+ * that was already fully materialised. This suite drives each adapter over a
+ * synthetic session an order of magnitude larger than the largest fixture in the
+ * tree (2 KB) and asserts that the reader's window over that file stays inside
+ * the invariant `read-lines.ts` states: one chunk plus the partial line carried
+ * into it.
+ *
+ * ## What this suite does NOT claim
+ *
+ * It does not claim `iterate` holds no copy of the file ANYWHERE. The header
+ * used to say exactly that, and the accounting cannot support it: an adapter
+ * that streamed through `readLines` and ALSO did `readFileSync(path, "utf8")`,
+ * keeping the string alive for the whole iteration, was measured reporting the
+ * same 262,144-byte high-water mark and passing every assertion below while
+ * 9.84 MB stayed resident. The narrower claim - the one asserted here - is
+ * still the regression that mattered: the old path went through no reader at
+ * all, so it recorded ZERO, and a bound with a `> 0` floor rejects it.
+ *
+ * A residency assertion is what would close the gap, and the next section is
+ * the measurement record explaining why there is not one: the numbers do not
+ * discriminate. A flaky 60 MB bound would be a worse test than an exact bound
+ * with a stated blind spot, so the claim is narrowed rather than faked.
+ *
+ * ## Why the reader's own accounting and not `process.memoryUsage()`
+ *
+ * Both were measured. `rss` deltas across a full `Bun.gc(true)` baseline varied
+ * between 0 MB and 66 MB run to run for the SAME code path, and `heapUsed`
+ * failed to discriminate at all: on a 34 MB fixture the streaming path reported
+ * a ~30 MB delta, because what dominates the JSC heap mid-iteration is
+ * uncollected `JSON.parse` garbage, not the reader's window. A memory assertion
+ * that reports 30 MB for a reader retaining 256 KB is not a bound, and one that
+ * swings 60 MB between identical runs is a flaky test. So the reader keeps its
+ * own high-water mark of the bytes it holds (see `read-lines.ts`) and this suite
+ * asserts on that: an exact, deterministic number the old whole-file path could
+ * not have satisfied, since it retained the entire file by construction.
+ *
+ * For the record, on a 10.79 MB synthetic Claude session: the old
+ * `readFileSync` + `split("\n")` retained 12.06 MB of resident memory before
+ * yielding turn one; the reader's high-water mark over the same file is
+ * 263,040 bytes, and does not grow with the file.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { claudeAdapter } from "../../../../src/core/brain/sessions/claude.ts";
+import { codexAdapter } from "../../../../src/core/brain/sessions/codex.ts";
+import { grokAdapter } from "../../../../src/core/brain/sessions/grok.ts";
+import { hermesAdapter } from "../../../../src/core/brain/sessions/hermes.ts";
+import { opencodeAdapter } from "../../../../src/core/brain/sessions/opencode.ts";
+import {
+ lineReaderRetainedBytes,
+ resetLineReaderRetainedBytes,
+} from "../../../../src/core/brain/sessions/read-lines.ts";
+import type { SessionAdapter } from "../../../../src/core/brain/sessions/types.ts";
+
+/** Turn count per synthetic file. Sized so every file clears 8 MB. */
+const TURNS = 12_000;
+/** Padding that makes each line realistically large without being pathological. */
+const BODY = "the quick brown fox jumps over the lazy dog. ".repeat(16);
+
+/**
+ * A synthetic session, with the one number a bound on the reader needs
+ * besides the file itself: the longest line in it, which is the largest
+ * partial line the reader can carry across a chunk boundary.
+ */
+interface Fixture {
+ readonly path: string;
+ readonly longestLineBytes: number;
+}
+
+function write(name: string, lines: readonly string[]): Fixture {
+ const dir = mkdtempSync(join(tmpdir(), "osb-streaming-"));
+ const path = join(dir, name);
+ writeFileSync(path, `${lines.join("\n")}\n`);
+ return {
+ path,
+ longestLineBytes: lines.reduce((max, l) => Math.max(max, Buffer.byteLength(l, "utf8")), 0),
+ };
+}
+
+/**
+ * The largest chunk this runtime's file stream hands out for `path`, read
+ * exactly the way `readLines` reads it.
+ *
+ * Measured rather than assumed, because the bound below is the module's
+ * invariant and not a round number: `size / 8` on an 8 MB file leaves room
+ * for four chunks, so a reader that buffered four before yielding would
+ * have passed it.
+ */
+async function largestStreamChunkBytes(path: string): Promise<number> {
+ const reader = Bun.file(path).stream().getReader();
+ let max = 0;
+ try {
+ for (;;) {
+ // oxlint-disable-next-line no-await-in-loop
+ const chunk = await reader.read();
+ if (chunk.done === true || chunk.value === undefined) break;
+ if (chunk.value.byteLength > max) max = chunk.value.byteLength;
+ }
+ } finally {
+ await reader.cancel().catch(() => undefined);
+ }
+ return max;
+}
+
+function isoAt(i: number): string {
+ return new Date(Date.UTC(2026, 0, 1) + i * 1000).toISOString();
+}
+
+function claudeFile(): Fixture {
+ const lines: string[] = [];
+ for (let i = 0; i < TURNS; i++) {
+ lines.push(
+ JSON.stringify({
+ parentUuid: i === 0 ? null : `u-${i - 1}`,
+ sessionId: "sess-streaming",
+ entrypoint: "cli",
+ type: i % 2 === 0 ? "user" : "assistant",
+ uuid: `u-${i}`,
+ timestamp: isoAt(i),
+ message: { role: i % 2 === 0 ? "user" : "assistant", content: `${BODY}${i}` },
+ }),
+ );
+ }
+ return write("claude.jsonl", lines);
+}
+
+function codexFile(): Fixture {
+ const lines: string[] = [
+ JSON.stringify({
+ timestamp: isoAt(0),
+ type: "session_meta",
+ payload: { originator: "codex_exec", cli_version: "0.129.0" },
+ }),
+ ];
+ for (let i = 0; i < TURNS; i++) {
+ lines.push(
+ JSON.stringify({
+ timestamp: isoAt(i + 1),
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: i % 2 === 0 ? "user" : "assistant",
+ content: [{ type: "input_text", text: `${BODY}${i}` }],
+ },
+ }),
+ );
+ }
+ return write("codex.jsonl", lines);
+}
+
+function hermesFile(): Fixture {
+ const lines: string[] = [JSON.stringify({ role: "session_meta", tools: [] })];
+ for (let i = 0; i < TURNS; i++) {
+ lines.push(
+ JSON.stringify({
+ role: i % 2 === 0 ? "user" : "assistant",
+ content: `${BODY}${i}`,
+ timestamp: isoAt(i + 1),
+ }),
+ );
+ }
+ return write("hermes.jsonl", lines);
+}
+
+function opencodeFile(): Fixture {
+ const lines: string[] = [
+ JSON.stringify({
+ type: "session_meta",
+ originator: "open-second-brain-opencode-plugin",
+ format: 1,
+ session_id: "ses_streaming",
+ }),
+ ];
+ for (let i = 0; i < TURNS; i++) {
+ lines.push(
+ JSON.stringify({
+ type: "turn",
+ turnId: `t-${i}`,
+ timestamp: isoAt(i + 1),
+ role: i % 2 === 0 ? "user" : "assistant",
+ text: `${BODY}${i}`,
+ }),
+ );
+ }
+ return write("opencode.jsonl", lines);
+}
+
+function grokFile(): Fixture {
+ const lines: string[] = [];
+ for (let i = 0; i < TURNS; i++) {
+ lines.push(
+ JSON.stringify({
+ timestamp: 1_781_213_002 + i,
+ method: "session/update",
+ params: {
+ sessionId: "grok-streaming",
+ update: {
+ // Alternating roles so every chunk closes the previous buffer:
+ // coalescing must not become an accumulator over the whole file.
+ sessionUpdate: i % 2 === 0 ? "user_message_chunk" : "agent_message_chunk",
+ content: { type: "text", text: `${BODY}${i}` },
+ },
+ },
+ }),
+ );
+ }
+ return write("grok.jsonl", lines);
+}
+
+const CASES: ReadonlyArray<{
+ readonly adapter: SessionAdapter;
+ readonly build: () => Fixture;
+ readonly expectedTurns: number;
+}> = [
+ { adapter: claudeAdapter, build: claudeFile, expectedTurns: TURNS },
+ { adapter: codexAdapter, build: codexFile, expectedTurns: TURNS },
+ { adapter: hermesAdapter, build: hermesFile, expectedTurns: TURNS },
+ { adapter: opencodeAdapter, build: opencodeFile, expectedTurns: TURNS },
+ { adapter: grokAdapter, build: grokFile, expectedTurns: TURNS },
+];
+
+describe("the line reader holds a bounded window while each adapter iterates", () => {
+ for (const { adapter, build, expectedTurns } of CASES) {
+ test(`${adapter.id} streams an 8 MB+ session within one chunk plus a line`, async () => {
+ const { path, longestLineBytes } = build();
+ const size = Bun.file(path).size;
+ expect(size).toBeGreaterThan(8_000_000);
+ const largestChunk = await largestStreamChunkBytes(path);
+ // The invariant, as a number: one chunk, plus the partial line
+ // carried into it.
+ const bound = largestChunk + longestLineBytes;
+ expect(bound).toBeLessThan(size / 8);
+
+ resetLineReaderRetainedBytes();
+ let turns = 0;
+ let firstTurnRetained = -1;
+ for await (const turn of adapter.iterate(path)) {
+ if (firstTurnRetained < 0) firstTurnRetained = lineReaderRetainedBytes();
+ expect(turn.turnId.length).toBeGreaterThan(0);
+ turns++;
+ }
+
+ expect(turns).toBe(expectedTurns);
+ // The whole-file path could satisfy none of these: it went through no
+ // reader at all, so it recorded zero and fails the floor - and it had
+ // the entire file in hand before turn one, so had it been accounted
+ // for it would have failed the ceiling.
+ expect(firstTurnRetained).toBeGreaterThan(0);
+ expect(firstTurnRetained).toBeLessThanOrEqual(bound);
+ expect(lineReaderRetainedBytes()).toBeGreaterThanOrEqual(largestChunk);
+ expect(lineReaderRetainedBytes()).toBeLessThanOrEqual(bound);
+ });
+ }
+});
diff --git a/tests/core/brain/snapshot-gate.test.ts b/tests/core/brain/snapshot-gate.test.ts
index a688e488..199cb0bd 100644
--- a/tests/core/brain/snapshot-gate.test.ts
+++ b/tests/core/brain/snapshot-gate.test.ts
@@ -39,8 +39,13 @@ import {
takeSnapshot,
withDestructiveSnapshot,
} from "../../../src/core/brain/snapshot-gate.ts";
-import { BrainSnapshotStoreError, listSnapshots } from "../../../src/core/brain/snapshot.ts";
+import {
+ BrainSnapshotError,
+ BrainSnapshotStoreError,
+ listSnapshots,
+} from "../../../src/core/brain/snapshot.ts";
import { createSnapshot } from "../../../src/core/brain/snapshot.ts";
+import { dream } from "../../../src/core/brain/dream.ts";
import { isFileAlreadyExists } from "../../../src/core/fs-atomic.ts";
import { brainDirs, snapshotPath, validateRunId } from "../../../src/core/brain/paths.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
@@ -408,4 +413,72 @@ describe("createUniqueSnapshot - the retry discriminator", () => {
expect((thrown as Error).message).toMatch(/after 3 attempts/);
expect((thrown as Error).cause).toBeInstanceOf(FileAlreadyExistsError);
});
+
+ test("an EEXIST naming some other path propagates on the first attempt", () => {
+ // GitHub #167. The discriminator used to be the errno alone, so ANY
+ // EEXIST anywhere in the cause chain read as "a peer took this run id" -
+ // including the one `createSnapshot` raises before it has touched a
+ // single archive, when `mkdir Brain/.snapshots` fails. The ladder then
+ // burned all 64 candidates and reported an id exhaustion that had never
+ // happened, with the real errno buried on `cause`. A collision that does
+ // not name THIS candidate's archive is not this loop's business.
+ const calls: string[] = [];
+ const unrelated = new Error(
+ "EEXIST: file already exists, mkdir '/somewhere/entirely/else'",
+ ) as NodeJS.ErrnoException;
+ unrelated.code = "EEXIST";
+ unrelated.path = "/somewhere/entirely/else";
+
+ expect(() =>
+ createUniqueSnapshot(vault, "dream-2026-06-01-000000", (runId) => {
+ calls.push(runId);
+ throw unrelated;
+ }),
+ ).toThrow(unrelated);
+ expect(calls).toEqual(["dream-2026-06-01-000000"]);
+ });
+});
+
+describe("an unusable Brain/.snapshots is diagnosed, not laddered past", () => {
+ /**
+ * The reproduction from GitHub #167, driven end to end on the two layers
+ * that both got it wrong: `createSnapshot`, which raised a bare errno from
+ * its very first `mkdir` and named nothing an operator could act on, and
+ * the gate above it, which read that errno as a lost race.
+ */
+ const replaceSnapshotsDirWithFile = (): string => {
+ const path = brainDirs(vault).snapshots;
+ rmSync(path, { recursive: true, force: true });
+ writeFileSync(path, "not a directory\n");
+ return path;
+ };
+
+ test("createSnapshot names the archive directory and what is really there", () => {
+ const path = replaceSnapshotsDirWithFile();
+ let thrown: unknown;
+ try {
+ createSnapshot(vault, "dream-2026-06-01-000000", { reason: "dream" });
+ } catch (err) {
+ thrown = err;
+ }
+ expect(thrown).toBeInstanceOf(BrainSnapshotError);
+ expect((thrown as Error).message).toContain(path);
+ expect((thrown as Error).message).toContain("regular file");
+ // The errno is kept, not replaced: the diagnosis explains it, and a
+ // reader who wants the syscall still has it.
+ expect(((thrown as Error).cause as NodeJS.ErrnoException).code).toBe("EEXIST");
+ });
+
+ test("dream reports the archive directory, not a fictional id exhaustion", () => {
+ const path = replaceSnapshotsDirWithFile();
+ let thrown: unknown;
+ try {
+ dream(vault, { now: new Date("2026-05-27T12:00:00Z") });
+ } catch (err) {
+ thrown = err;
+ }
+ expect(thrown).toBeDefined();
+ expect((thrown as Error).message).toContain(path);
+ expect((thrown as Error).message).not.toMatch(/could not reserve a unique snapshot run id/);
+ });
});
diff --git a/tests/core/brain/sync-lockfile.test.ts b/tests/core/brain/sync-lockfile.test.ts
index e4739031..d3f4989e 100644
--- a/tests/core/brain/sync-lockfile.test.ts
+++ b/tests/core/brain/sync-lockfile.test.ts
@@ -204,6 +204,7 @@ describe("every module that takes a lock is under a scanned root", () => {
["core/brain/lineage/ledger.ts", "Brain"],
["core/brain/preference-txn.ts", "Brain"],
["core/brain/query-demand.ts", "Brain"],
+ ["core/brain/sessions/discover.ts", ".open-second-brain"],
["core/brain/skill-proposals.ts", "Brain"],
]);
diff --git a/tests/core/config-origin.test.ts b/tests/core/config-origin.test.ts
new file mode 100644
index 00000000..b2eebb5f
--- /dev/null
+++ b/tests/core/config-origin.test.ts
@@ -0,0 +1,135 @@
+/**
+ * `CONFIG_ORIGIN` and the provenance-returning sibling of `envOrConfig`.
+ *
+ * Two properties, and the second is the reason the first is safe to add.
+ *
+ * The vocabulary follows the house four-piece shape (frozen object,
+ * derived union, membership list, guard), so a layer name that survives a
+ * round trip through a string is still checkable.
+ *
+ * The delegation is asserted rather than claimed: `envOrConfig` drives
+ * roughly fifty-five keys and did not change signature, so the ONLY thing
+ * keeping it honest is that it returns `resolveWithOrigin(...).value`. A
+ * reimplementation that drifted on one branch - the empty-string branch
+ * is the one that has bitten this repository before - would be invisible
+ * at every call site. The table below drives every branch and requires
+ * the two functions to agree on all of them.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+ CONFIG_ORIGIN,
+ CONFIG_ORIGINS,
+ envOrConfig,
+ isConfigOrigin,
+ resolveWithOrigin,
+ type ConfigOrigin,
+} from "../../src/core/validate.ts";
+
+const ENV_KEY = "OPEN_SECOND_BRAIN_CONFIG_ORIGIN_PROBE";
+const CONFIG_KEY = "config_origin_probe";
+
+interface Branch {
+ readonly name: string;
+ readonly env: NodeJS.ProcessEnv;
+ readonly config: Readonly<Record<string, string>>;
+ readonly value: string | null;
+ readonly origin: ConfigOrigin;
+}
+
+/** Every combination of the three states each source can be in. */
+const BRANCHES: ReadonlyArray<Branch> = [
+ {
+ name: "env set, config absent",
+ env: { [ENV_KEY]: "from-env" },
+ config: {},
+ value: "from-env",
+ origin: CONFIG_ORIGIN.env,
+ },
+ {
+ name: "env set, config set - env wins",
+ env: { [ENV_KEY]: "from-env" },
+ config: { [CONFIG_KEY]: "from-config" },
+ value: "from-env",
+ origin: CONFIG_ORIGIN.env,
+ },
+ {
+ name: "env empty string, config set - config wins",
+ env: { [ENV_KEY]: "" },
+ config: { [CONFIG_KEY]: "from-config" },
+ value: "from-config",
+ origin: CONFIG_ORIGIN.userConfig,
+ },
+ {
+ name: "env empty string, config empty string - neither",
+ env: { [ENV_KEY]: "" },
+ config: { [CONFIG_KEY]: "" },
+ value: null,
+ origin: CONFIG_ORIGIN.default,
+ },
+ {
+ name: "env absent, config set",
+ env: {},
+ config: { [CONFIG_KEY]: "from-config" },
+ value: "from-config",
+ origin: CONFIG_ORIGIN.userConfig,
+ },
+ {
+ name: "env absent, config empty string - neither",
+ env: {},
+ config: { [CONFIG_KEY]: "" },
+ value: null,
+ origin: CONFIG_ORIGIN.default,
+ },
+ {
+ name: "neither source has the key",
+ env: {},
+ config: {},
+ value: null,
+ origin: CONFIG_ORIGIN.default,
+ },
+];
+
+describe("CONFIG_ORIGIN vocabulary", () => {
+ test("names exactly the four resolution layers", () => {
+ expect([...CONFIG_ORIGINS].toSorted()).toEqual([
+ "default",
+ "env",
+ "user-config",
+ "vault-config",
+ ]);
+ });
+
+ test("the membership list is exactly the frozen object's values", () => {
+ expect([...CONFIG_ORIGINS].toSorted()).toEqual(Object.values(CONFIG_ORIGIN).toSorted());
+ expect(Object.isFrozen(CONFIG_ORIGIN)).toBe(true);
+ });
+
+ test("the guard accepts every member and rejects everything else", () => {
+ for (const origin of CONFIG_ORIGINS) expect(isConfigOrigin(origin)).toBe(true);
+ for (const outsider of ["", "ENV", "config", "vault", null, undefined, 0, {}]) {
+ expect(isConfigOrigin(outsider)).toBe(false);
+ }
+ });
+});
+
+describe("resolveWithOrigin", () => {
+ for (const branch of BRANCHES) {
+ test(`${branch.name} - reports the layer that produced the value`, () => {
+ const resolved = resolveWithOrigin(branch.env, branch.config, ENV_KEY, CONFIG_KEY);
+ expect(resolved.value).toBe(branch.value);
+ expect(resolved.origin).toBe(branch.origin);
+ });
+ }
+});
+
+describe("envOrConfig delegates to resolveWithOrigin", () => {
+ for (const branch of BRANCHES) {
+ test(`${branch.name} - the two agree on the value`, () => {
+ const delegated = envOrConfig(branch.env, branch.config, ENV_KEY, CONFIG_KEY);
+ const sibling = resolveWithOrigin(branch.env, branch.config, ENV_KEY, CONFIG_KEY);
+ expect(delegated).toBe(sibling.value);
+ });
+ }
+});
diff --git a/tests/core/install/adapters/codex.test.ts b/tests/core/install/adapters/codex.test.ts
new file mode 100644
index 00000000..edaf3563
--- /dev/null
+++ b/tests/core/install/adapters/codex.test.ts
@@ -0,0 +1,660 @@
+/**
+ * The Codex CLI adapter, on both of the paths it can take.
+ *
+ * Codex is the second subprocess-primary target after `copilot-cli`, and
+ * it differs from that precedent in one way this file is built around:
+ * `codex mcp add` PERSISTS into the same `~/.codex/config.toml` the
+ * fallback writes. So the file is evidence in both modes - but only in
+ * the fallback mode did this build write the bytes, and the fake host
+ * below deliberately serialises its tables in a different (still valid)
+ * layout to prove `verify` does not demand our formatting from a
+ * registration the host itself made.
+ *
+ * Three properties every case here exists to hold:
+ *
+ * - **The subprocess is told which home to install into.** The runner
+ * seam takes the resolved Codex home as its first argument, because
+ * an adapter that installs into `InstallEnv.home` while its
+ * subprocess writes the ambient `~/.codex` would mutate the
+ * operator's real machine from a test.
+ * - **Unrelated TOML survives.** A `~/.codex/config.toml` carries
+ * `[plugins."..."]` and `[marketplaces....]` tables this build has no
+ * business touching; the fallback path is asserted byte-for-byte
+ * against them.
+ * - **A probe that could not run is named, never assumed.** Both skip
+ * branches (binary absent, binary refuses) are driven.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Writable } from "node:stream";
+
+import {
+ codexAdapter,
+ resetCodexRunner,
+ setCodexRunner,
+ type CodexRunner,
+} from "../../../../src/core/install/adapters/codex.ts";
+import {
+ resetHostProbeRunner,
+ setHostProbeRunner,
+} from "../../../../src/core/install/host-probe.ts";
+import { OSB_KEY_FULL, OSB_KEY_WRITER } from "../../../../src/core/install/json-merge.ts";
+import { readManifest } from "../../../../src/core/install/manifest.ts";
+import { buildPayload } from "../../../../src/core/install/payload.ts";
+import type { InstallEnv, McpPayload } from "../../../../src/core/install/types.ts";
+
+let vault: string;
+let home: string;
+let stderrBuf: string[];
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "osb-codex-v-"));
+ home = mkdtempSync(join(tmpdir(), "osb-codex-h-"));
+ stderrBuf = [];
+});
+
+afterEach(() => {
+ resetCodexRunner();
+ resetHostProbeRunner();
+ for (const dir of [vault, home]) {
+ try {
+ rmSync(dir, { recursive: true, force: true });
+ } catch {
+ // temp cleanup is best-effort
+ }
+ }
+});
+
+function env(overrides: Record<string, string> = {}): InstallEnv {
+ return {
+ vault,
+ home,
+ cwd: home,
+ env: { VAULT_AGENT_NAME: "claude-vps", VAULT_TIMEZONE: "UTC", ...overrides },
+ now: new Date("2026-08-16T12:00:00.000Z"),
+ };
+}
+
+function applyOpts() {
+ const stdout = new Writable({
+ write(_chunk, _enc, cb) {
+ cb();
+ },
+ });
+ const stderr = new Writable({
+ write(chunk, _enc, cb) {
+ stderrBuf.push(chunk.toString());
+ cb();
+ },
+ });
+ return {
+ dryRun: false,
+ force: false,
+ stdout: stdout as unknown as NodeJS.WriteStream,
+ stderr: stderr as unknown as NodeJS.WriteStream,
+ };
+}
+
+function payload(): McpPayload {
+ return buildPayload({ vault, agent_name: "claude-vps", timezone: "UTC" });
+}
+
+function configPath(base: string = join(home, ".codex")): string {
+ return join(base, "config.toml");
+}
+
+function install(installEnv: InstallEnv = env()): void {
+ const p = payload();
+ codexAdapter.apply(codexAdapter.plan(p, installEnv), p, installEnv, applyOpts());
+}
+
+/** Unrelated tables a real `~/.codex/config.toml` carries. */
+const FOREIGN_TOML = [
+ 'model = "gpt-5-codex"',
+ "",
+ '[plugins."open-second-brain@open-second-brain"]',
+ "enabled = true",
+ "",
+ "[marketplaces.builtin]",
+ 'url = "https://example.invalid/marketplace"',
+ "",
+ "[mcp_servers.some-other-tool]",
+ 'command = "other"',
+ 'args = ["serve"]',
+ "",
+].join("\n");
+
+// ---------- Fakes ----------
+
+interface FakeHost {
+ readonly runner: CodexRunner;
+ readonly calls: ReadonlyArray<ReadonlyArray<string>>;
+ readonly homes: ReadonlyArray<string>;
+ registered(): ReadonlyArray<string>;
+}
+
+/**
+ * A `codex` binary that behaves like the real one: `mcp add` appends a
+ * `[mcp_servers.<name>]` table to `$CODEX_HOME/config.toml` in ITS OWN
+ * layout (multi-line `args`), `mcp remove` deletes it.
+ */
+function fakeCodex(opts: { available?: boolean; addExitCode?: number } = {}): FakeHost {
+ const calls: string[][] = [];
+ const homes: string[] = [];
+ const names = new Set<string>();
+ const write = (codexHome: string) => {
+ const tables = [...names].map((name) =>
+ [`[mcp_servers.${name}]`, `command = "o2b"`, "args = [", ` "mcp",`, "]", ""].join("\n"),
+ );
+ mkdirSync(codexHome, { recursive: true });
+ const existing = existsSync(configPath(codexHome))
+ ? readFileSync(configPath(codexHome), "utf8")
+ : "";
+ // Drop whole `[mcp_servers.<osb>]` sections, header through body, so
+ // a re-add does not stack a second copy of the table.
+ const kept: string[] = [];
+ let skipping = false;
+ for (const line of existing.split("\n")) {
+ if (line.startsWith("[")) skipping = line.startsWith("[mcp_servers.open-second-brain");
+ if (skipping || line.trim().length === 0) continue;
+ kept.push(line);
+ }
+ const keep = kept.join("\n");
+ writeFileSync(
+ configPath(codexHome),
+ (keep.length > 0 ? keep + "\n\n" : "") + tables.join("\n"),
+ );
+ };
+ return {
+ calls,
+ homes,
+ registered: () => [...names],
+ runner: {
+ available: () => opts.available ?? true,
+ run(codexHome, args) {
+ calls.push([...args]);
+ homes.push(codexHome);
+ const [verb, action, name] = args;
+ if (verb !== "mcp" || typeof name !== "string") {
+ return { exitCode: 1, stdout: "", stderr: `unknown command: ${args.join(" ")}` };
+ }
+ if (action === "add") {
+ if (opts.addExitCode !== undefined && opts.addExitCode !== 0) {
+ return { exitCode: opts.addExitCode, stdout: "", stderr: "codex refused the add" };
+ }
+ names.add(name);
+ write(codexHome);
+ return { exitCode: 0, stdout: "", stderr: "" };
+ }
+ if (action === "remove") {
+ const had = names.delete(name);
+ write(codexHome);
+ return had
+ ? { exitCode: 0, stdout: "", stderr: "" }
+ : { exitCode: 1, stdout: "", stderr: `no such server: ${name}` };
+ }
+ return { exitCode: 1, stdout: "", stderr: `unknown action: ${String(action)}` };
+ },
+ },
+ };
+}
+
+/** A runner whose binary does not exist; running it is a test failure. */
+function absentCodex(): CodexRunner {
+ return {
+ available: () => false,
+ run: () => {
+ throw new Error("the adapter must not spawn codex when it reported the binary absent");
+ },
+ };
+}
+
+/** The host answering the declared probe with `registered`, one per line. */
+function stageProbe(registered: ReadonlyArray<string>): void {
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: `Name\n${registered.join("\n")}\n`, stderr: "" }),
+ });
+}
+
+// ---------- The subprocess path ----------
+
+describe("codex adapter β€” the CLI is present", () => {
+ test("apply registers both servers through `codex mcp add`, command after the separator", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ const adds = host.calls.filter((c) => c[1] === "add");
+ expect(adds.map((c) => c[2]).toSorted()).toEqual([OSB_KEY_FULL, OSB_KEY_WRITER].toSorted());
+ const full = adds.find((c) => c[2] === OSB_KEY_FULL)!;
+ expect(full.slice(full.indexOf("--") + 1)).toEqual([
+ "o2b",
+ "mcp",
+ "--vault",
+ vault,
+ "--host-target",
+ "codex",
+ ]);
+ expect(readManifest(vault).installs["codex"]!.operation).toBe("subprocess");
+ });
+
+ test("the subprocess is told the Codex home this env installs into", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ expect([...new Set(host.homes)]).toEqual([join(home, ".codex")]);
+ });
+
+ test("CODEX_HOME relocates both the config file and the subprocess home", () => {
+ const elsewhere = join(home, "codex-elsewhere");
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install(env({ CODEX_HOME: elsewhere }));
+ expect([...new Set(host.homes)]).toEqual([elsewhere]);
+ expect(codexAdapter.detect(env({ CODEX_HOME: elsewhere })).configPath).toBe(
+ configPath(elsewhere),
+ );
+ });
+
+ test("the registration carries codex's own host-qualified agent name", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ const add = host.calls.find((c) => c[1] === "add" && c[2] === OSB_KEY_FULL)!;
+ expect(add).toContain("VAULT_AGENT_NAME=codex-claude-vps");
+ const hostQualified = fakeCodex();
+ setCodexRunner(hostQualified.runner);
+ const p = buildPayload({ vault, agent_name: "claude-vps-agent", timezone: "UTC" });
+ const e = env({ VAULT_AGENT_NAME: "claude-vps-agent" });
+ codexAdapter.apply(codexAdapter.plan(p, e), p, e, applyOpts());
+ expect(hostQualified.calls.find((c) => c[1] === "add")!).toContain(
+ "VAULT_AGENT_NAME=codex-vps-agent",
+ );
+ });
+
+ test("apply is idempotent: a second run leaves the same two servers registered", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ const first = readFileSync(configPath(), "utf8");
+ install();
+ expect(readFileSync(configPath(), "utf8")).toBe(first);
+ expect(host.registered().toSorted()).toEqual([OSB_KEY_FULL, OSB_KEY_WRITER].toSorted());
+ });
+
+ test("a dry run registers nothing and records no manifest entry", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ const p = payload();
+ codexAdapter.apply(codexAdapter.plan(p, env()), p, env(), { ...applyOpts(), dryRun: true });
+ expect(host.calls).toEqual([]);
+ expect(readManifest(vault).installs["codex"]).toBeUndefined();
+ });
+
+ test("a failing `codex mcp add` falls back to the TOML merge and names the failure", () => {
+ const host = fakeCodex({ addExitCode: 7 });
+ setCodexRunner(host.runner);
+ install();
+ expect(stderrBuf.join("")).toContain("codex mcp add failed");
+ expect(readFileSync(configPath(), "utf8")).toContain(`[mcp_servers.${OSB_KEY_FULL}]`);
+ expect(readManifest(vault).installs["codex"]!.operation).toBe("managed-block");
+ });
+});
+
+// ---------- The TOML fallback path ----------
+
+describe("codex adapter β€” the CLI is absent", () => {
+ test("the fallback writes both server tables into config.toml", () => {
+ setCodexRunner(absentCodex());
+ install();
+ const toml = readFileSync(configPath(), "utf8");
+ expect(toml).toContain(`[mcp_servers.${OSB_KEY_FULL}]`);
+ expect(toml).toContain(`[mcp_servers.${OSB_KEY_WRITER}]`);
+ expect(toml).toContain(`"--host-target", "codex"`);
+ expect(toml).toContain('VAULT_AGENT_NAME = "codex-claude-vps"');
+ expect(readManifest(vault).installs["codex"]!.operation).toBe("managed-block");
+ expect(stderrBuf.join("")).toContain("file-fallback");
+ });
+
+ test("every unrelated table survives byte-for-byte", () => {
+ mkdirSync(join(home, ".codex"), { recursive: true });
+ writeFileSync(configPath(), FOREIGN_TOML);
+ setCodexRunner(absentCodex());
+ install();
+ const toml = readFileSync(configPath(), "utf8");
+ for (const line of FOREIGN_TOML.split("\n").filter((l) => l.trim().length > 0)) {
+ expect(toml).toContain(line);
+ }
+ expect(toml.indexOf('[plugins."open-second-brain@open-second-brain"]')).toBeLessThan(
+ toml.indexOf(`[mcp_servers.${OSB_KEY_FULL}]`),
+ );
+ });
+
+ test("a second apply leaves the file byte-identical", () => {
+ mkdirSync(join(home, ".codex"), { recursive: true });
+ writeFileSync(configPath(), FOREIGN_TOML);
+ setCodexRunner(absentCodex());
+ install();
+ const first = readFileSync(configPath(), "utf8");
+ install();
+ expect(readFileSync(configPath(), "utf8")).toBe(first);
+ });
+
+ test("a dry run on the fallback path writes nothing", () => {
+ setCodexRunner(absentCodex());
+ const p = payload();
+ codexAdapter.apply(codexAdapter.plan(p, env()), p, env(), { ...applyOpts(), dryRun: true });
+ expect(existsSync(configPath())).toBe(false);
+ });
+});
+
+// ---------- detect and plan ----------
+
+describe("codex adapter β€” detect and plan", () => {
+ test("detect reports not-installed on a clean home and names the file it would write", () => {
+ setCodexRunner(absentCodex());
+ const result = codexAdapter.detect(env());
+ expect(result.status).toBe("not-installed");
+ expect(result.configPath).toBe(configPath());
+ });
+
+ test("detect reports drift when only one of the two tables is declared", () => {
+ mkdirSync(join(home, ".codex"), { recursive: true });
+ writeFileSync(configPath(), `[mcp_servers.${OSB_KEY_FULL}]\ncommand = "o2b"\nargs = []\n`);
+ setCodexRunner(absentCodex());
+ expect(codexAdapter.detect(env()).status).toBe("drift");
+ });
+
+ test("detect reports installed once both tables are declared", () => {
+ setCodexRunner(absentCodex());
+ install();
+ expect(codexAdapter.detect(env()).status).toBe("installed");
+ });
+
+ test("plan names the subprocess when the binary is present and the merge when it is not", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ expect(codexAdapter.plan(payload(), env()).steps.map((s) => s.kind)).toEqual(["subprocess"]);
+ setCodexRunner(absentCodex());
+ const fallback = codexAdapter.plan(payload(), env());
+ expect(fallback.steps.map((s) => s.kind)).toEqual(["managed-block"]);
+ expect(fallback.steps[0]!.path).toBe(configPath());
+ expect(fallback.postNotes.join("\n")).toContain("codex");
+ });
+});
+
+// ---------- verify ----------
+
+describe("codex adapter β€” verify", () => {
+ test("no manifest entry is not-installed, with the remedy", () => {
+ const result = codexAdapter.verify(env());
+ expect(result.status).toBe("not-installed");
+ expect(result.fix_hint).toBe("o2b install --target codex --apply");
+ });
+
+ test("the host reports both servers: ok, naming the probe it ran", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ stageProbe([OSB_KEY_FULL, OSB_KEY_WRITER]);
+ const result = codexAdapter.verify(env());
+ expect(result.status).toBe("ok");
+ expect(result.details.join("; ")).toContain("`codex mcp list` reports both OSB servers");
+ });
+
+ test("the fallback file matching the canonical payload verifies ok", () => {
+ setCodexRunner(absentCodex());
+ install();
+ stageProbe([OSB_KEY_FULL, OSB_KEY_WRITER]);
+ const result = codexAdapter.verify(env());
+ expect(result.status).toBe("ok");
+ expect(result.details.join("; ")).toContain(configPath());
+ });
+
+ test("an edited table on the fallback path is drift, and re-applying is the remedy", () => {
+ setCodexRunner(absentCodex());
+ install();
+ stageProbe([OSB_KEY_FULL, OSB_KEY_WRITER]);
+ writeFileSync(
+ configPath(),
+ readFileSync(configPath(), "utf8").replace('command = "o2b"', 'command = "TAMPERED"'),
+ );
+ const result = codexAdapter.verify(env());
+ expect(result.status).toBe("drift");
+ expect(result.fix_hint).toBe("o2b install --target codex --apply");
+ });
+
+ test("the host's own formatting is not drift: a subprocess install verifies on presence", () => {
+ // `codex mcp add` writes the table in codex's layout, not ours. A
+ // byte comparison against our serializer would report drift on a
+ // registration the host itself made and is serving correctly.
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ expect(readFileSync(configPath(), "utf8")).not.toContain("--host-target");
+ stageProbe([OSB_KEY_FULL, OSB_KEY_WRITER]);
+ expect(codexAdapter.verify(env()).status).toBe("ok");
+ });
+
+ test("the config declares both but the host reports neither: unreachable, not ok", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ stageProbe([]);
+ const result = codexAdapter.verify(env());
+ expect(result.status).toBe("mcp-unreachable");
+ expect(result.details.join("; ")).toContain(OSB_KEY_FULL);
+ expect(result.fix_hint ?? "").toContain("restart");
+ });
+
+ test("the host reports nothing and the config lost the tables: drift", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ writeFileSync(configPath(), FOREIGN_TOML);
+ stageProbe([]);
+ expect(codexAdapter.verify(env()).status).toBe("drift");
+ });
+
+ test("the binary is absent: the skip is named and the file still answers", () => {
+ setCodexRunner(absentCodex());
+ install();
+ setHostProbeRunner({
+ available: () => false,
+ run: () => {
+ throw new Error("the probe must not spawn a binary it reported absent");
+ },
+ });
+ const result = codexAdapter.verify(env());
+ expect(result.status).toBe("ok");
+ expect(result.details.join("; ")).toContain("`codex` is not on PATH");
+ });
+
+ test("the binary refuses: the exit code and its first stderr line are named", () => {
+ setCodexRunner(absentCodex());
+ install();
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 4, stdout: "", stderr: "failed to load configuration\n" }),
+ });
+ const result = codexAdapter.verify(env());
+ expect(result.details.join("; ")).toContain("exited 4: failed to load configuration");
+ });
+});
+
+// ---------- uninstall ----------
+
+describe("codex adapter β€” uninstall", () => {
+ test("the CLI path removes both names and drops the manifest entry", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ codexAdapter.uninstall(env(), applyOpts());
+ expect(host.registered()).toEqual([]);
+ expect(
+ host.calls.filter((c) => c[1] === "remove" && c[2] === OSB_KEY_WRITER).length,
+ ).toBeGreaterThan(0);
+ expect(readManifest(vault).installs["codex"]).toBeUndefined();
+ });
+
+ test("the fallback path removes only our tables", () => {
+ mkdirSync(join(home, ".codex"), { recursive: true });
+ writeFileSync(configPath(), FOREIGN_TOML);
+ setCodexRunner(absentCodex());
+ install();
+ codexAdapter.uninstall(env(), applyOpts());
+ const toml = readFileSync(configPath(), "utf8");
+ expect(toml).not.toContain(`[mcp_servers.${OSB_KEY_FULL}]`);
+ expect(toml).not.toContain(`[mcp_servers.${OSB_KEY_WRITER}]`);
+ expect(toml).toContain("[mcp_servers.some-other-tool]");
+ expect(toml).toContain('[plugins."open-second-brain@open-second-brain"]');
+ });
+
+ test("a subprocess install whose CLI is gone is still removed from the file", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ setCodexRunner(absentCodex());
+ codexAdapter.uninstall(env(), applyOpts());
+ expect(readFileSync(configPath(), "utf8")).not.toContain(`[mcp_servers.${OSB_KEY_FULL}]`);
+ });
+
+ test("a dry run removes nothing", () => {
+ setCodexRunner(absentCodex());
+ install();
+ codexAdapter.uninstall(env(), { ...applyOpts(), dryRun: true });
+ expect(readFileSync(configPath(), "utf8")).toContain(`[mcp_servers.${OSB_KEY_FULL}]`);
+ expect(readManifest(vault).installs["codex"]).toBeDefined();
+ });
+
+ test("uninstalling what was never installed is refused by name, with the remedy", () => {
+ setCodexRunner(absentCodex());
+ let message = "";
+ let hint = "";
+ try {
+ codexAdapter.uninstall(env(), applyOpts());
+ } catch (e) {
+ message = (e as Error).message;
+ hint = (e as { hint?: string }).hint ?? "";
+ }
+ expect(message).toContain("codex");
+ expect(hint).toContain("--force-from-snippet");
+ });
+});
+
+// ---------- A commented-out table is the operator saying no ----------
+
+describe("a commented-out table is not a declaration", () => {
+ /** The file an operator produces by commenting both tables out. */
+ function commentOutOurTables(): void {
+ const path = configPath();
+ const current = readFileSync(path, "utf8");
+ writeFileSync(
+ path,
+ current
+ .split("\n")
+ .map((line) => (line.trim().length === 0 ? line : `# ${line}`))
+ .join("\n"),
+ );
+ }
+
+ test("detect reports not-installed, not installed", () => {
+ // `toml.includes("[mcp_servers.open-second-brain]")` matches
+ // `# [mcp_servers.open-second-brain]` just as readily, so commenting
+ // both tables out - the ordinary way to turn a server off - left
+ // `detect` reporting a registration Codex would never load.
+ setCodexRunner(absentCodex());
+ install();
+ commentOutOurTables();
+ expect(codexAdapter.detect(env()).status).toBe("not-installed");
+ });
+
+ test("verify reports drift and names both missing tables", () => {
+ setCodexRunner(absentCodex());
+ install();
+ commentOutOurTables();
+ setHostProbeRunner({
+ available: () => false,
+ run: () => ({ exitCode: 127, stdout: "", stderr: "" }),
+ });
+ const result = codexAdapter.verify(env());
+ expect(result.status).toBe("drift");
+ expect(result.details.join("; ")).toContain(OSB_KEY_FULL);
+ expect(result.details.join("; ")).toContain(OSB_KEY_WRITER);
+ });
+
+ test("an indented but uncommented header still counts as declared", () => {
+ // The anchor is a whole-line match with leading whitespace tolerated:
+ // TOML permits an indented table header, and refusing one would be
+ // the same misreading pointed the other way.
+ setCodexRunner(absentCodex());
+ install();
+ const path = configPath();
+ writeFileSync(path, readFileSync(path, "utf8").replaceAll("[mcp_servers.", " [mcp_servers."));
+ expect(codexAdapter.detect(env()).status).toBe("installed");
+ });
+});
+
+// ---------- A failed removal keeps the manifest entry ----------
+
+describe("uninstall does not forget an install it failed to remove", () => {
+ test("a `codex mcp remove` that fails leaves the entry, so the retry works", () => {
+ // Dropping the manifest entry after a failed removal makes the retry
+ // impossible: the next `o2b uninstall` finds no entry, throws
+ // `manifest-missing` and demands `--force-from-snippet` for a server
+ // the host still has. grok already guarded this; codex did not.
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ expect(readManifest(vault).installs["codex"]).toBeDefined();
+
+ setCodexRunner({
+ available: () => true,
+ run: () => ({ exitCode: 3, stdout: "", stderr: "codex refused the remove" }),
+ });
+ const result = codexAdapter.uninstall(env(), { ...applyOpts(), fromSnippet: false });
+ expect(result.removed_keys).toEqual([]);
+ expect(result.skipped.map(([name]) => name).toSorted()).toEqual(
+ [OSB_KEY_FULL, OSB_KEY_WRITER].toSorted(),
+ );
+ expect(readManifest(vault).installs["codex"]).toBeDefined();
+
+ // The retry, once the host is willing again.
+ setCodexRunner(host.runner);
+ const retry = codexAdapter.uninstall(env(), { ...applyOpts(), fromSnippet: false });
+ expect(retry.removed_keys.toSorted()).toEqual([OSB_KEY_FULL, OSB_KEY_WRITER].toSorted());
+ expect(readManifest(vault).installs["codex"]).toBeUndefined();
+ });
+
+ test("a clean removal still drops the entry", () => {
+ const host = fakeCodex();
+ setCodexRunner(host.runner);
+ install();
+ codexAdapter.uninstall(env(), { ...applyOpts(), fromSnippet: false });
+ expect(readManifest(vault).installs["codex"]).toBeUndefined();
+ });
+
+ test("nothing left to remove is a completed uninstall, not a failure", () => {
+ // A skip is not a failure. `no OSB tables declared` means the file
+ // path found nothing to strip, and keeping the entry alive for that
+ // would make the manifest unclearable.
+ setCodexRunner(absentCodex());
+ install();
+ writeFileSync(configPath(), "");
+ const result = codexAdapter.uninstall(env(), { ...applyOpts(), fromSnippet: false });
+ expect(result.skipped.length).toBe(1);
+ expect(readManifest(vault).installs["codex"]).toBeUndefined();
+ });
+
+ test("the file path reports the config it changed", () => {
+ // grok names its hooks file; codex named nothing, so an uninstall that
+ // rewrote `config.toml` left the operator no path to check.
+ setCodexRunner(absentCodex());
+ install();
+ const result = codexAdapter.uninstall(env(), { ...applyOpts(), fromSnippet: false });
+ expect(result.removed_paths).toEqual([configPath()]);
+ });
+});
diff --git a/tests/core/install/adapters/copilot-cli.test.ts b/tests/core/install/adapters/copilot-cli.test.ts
index f1812ff4..70f007b8 100644
--- a/tests/core/install/adapters/copilot-cli.test.ts
+++ b/tests/core/install/adapters/copilot-cli.test.ts
@@ -10,7 +10,12 @@ import {
resetCopilotRunner,
type CopilotRunner,
} from "../../../../src/core/install/adapters/copilot-cli.ts";
+import {
+ resetHostProbeRunner,
+ setHostProbeRunner,
+} from "../../../../src/core/install/host-probe.ts";
import { buildPayload } from "../../../../src/core/install/payload.ts";
+import { OSB_KEY_FULL, OSB_KEY_WRITER } from "../../../../src/core/install/json-merge.ts";
import { readManifest } from "../../../../src/core/install/manifest.ts";
let vault: string;
@@ -24,6 +29,7 @@ beforeEach(() => {
});
afterEach(() => {
resetCopilotRunner();
+ resetHostProbeRunner();
for (const p of [vault, home]) {
try {
rmSync(p, { recursive: true, force: true });
@@ -69,23 +75,70 @@ function fallbackFile() {
return join(home, ".config", "github-copilot", "mcp.json");
}
+/**
+ * A `copilot` binary that REMEMBERS what it was told.
+ *
+ * `mcp add` and `mcp remove` move a name in and out of a registry, and
+ * `list` answers from that registry rather than from a fixture. It matters
+ * because the subprocess mode leaves nothing on disk: the host's own
+ * registry IS the record, so a stub that reports both names whatever it
+ * was asked to do makes `verify` an assertion about the stub. Reducing
+ * `applyViaCli` to the full server alone left this whole suite green
+ * before the host remembered.
+ *
+ * The third field, `calls`, keeps the raw argv so the WHICH-name
+ * assertions can read `mcp add <name>` directly.
+ */
+function fakeCopilotHost(): {
+ runner: CopilotRunner;
+ calls: string[][];
+ registered: () => ReadonlyArray<string>;
+} {
+ const calls: string[][] = [];
+ const registry = new Set<string>();
+ const runner: CopilotRunner = {
+ available: () => true,
+ run: (args) => {
+ calls.push([...args]);
+ const [verb, action, name] = args;
+ if (verb === "mcp" && name !== undefined) {
+ if (action === "add") registry.add(name);
+ if (action === "remove") registry.delete(name);
+ }
+ return { exitCode: 0, stdout: "", stderr: "" };
+ },
+ list: () => ({ ok: true, names: [...registry] }),
+ };
+ return { runner, calls, registered: () => [...registry] };
+}
+
+/** The names one `copilot mcp <action>` verb was invoked with, sorted. */
+function namesOf(calls: ReadonlyArray<ReadonlyArray<string>>, action: string): string[] {
+ return calls
+ .filter((c) => c[0] === "mcp" && c[1] === action)
+ .map((c) => c[2] ?? "(no name)")
+ .toSorted();
+}
+
+/** Both server names, sorted: the assertions below compare name SETS. */
+const BOTH_KEYS = [OSB_KEY_FULL, OSB_KEY_WRITER].toSorted();
+
describe("copilot-cli adapter β€” happy path via CLI subprocess", () => {
test("apply calls `copilot mcp remove` + `copilot mcp add` for both names", () => {
- const calls: string[][] = [];
- const runner: CopilotRunner = {
- available: () => true,
- run: (args) => {
- calls.push([...args]);
- return { exitCode: 0, stdout: "", stderr: "" };
- },
- list: () => ({ ok: true, names: ["open-second-brain", "open-second-brain-writer"] }),
- };
- setCopilotRunner(runner);
+ const host = fakeCopilotHost();
+ setCopilotRunner(host.runner);
const p = payload();
copilotCliAdapter.apply(copilotCliAdapter.plan(p, env()), p, env(), applyOpts());
- const ops = calls.map((c) => `${c[0]} ${c[1]}`);
- expect(ops).toContain("mcp remove");
- expect(ops).toContain("mcp add");
+ // WHICH names, not how many operations: `toContain("mcp add")` held for
+ // an apply that registered the full server and forgot the writer.
+ expect(namesOf(host.calls, "add")).toEqual(BOTH_KEYS);
+ expect(namesOf(host.calls, "remove")).toEqual(BOTH_KEYS);
+ // …and the two adds carry the two DIFFERENT entries, so registering the
+ // full payload under both names is not a way to satisfy the line above.
+ const writerAdd = host.calls.find((c) => c[1] === "add" && c[2] === OSB_KEY_WRITER)!;
+ const fullAdd = host.calls.find((c) => c[1] === "add" && c[2] === OSB_KEY_FULL)!;
+ expect(writerAdd).toContain("--writer-only");
+ expect(fullAdd).not.toContain("--writer-only");
const manifest = readManifest(vault).installs["copilot-cli"];
expect(manifest).toBeDefined();
expect(manifest!.operation).toBe("subprocess");
@@ -134,16 +187,41 @@ describe("copilot-cli adapter β€” fallback to JSON file", () => {
});
});
+/**
+ * A host whose `copilot` binary is present and reports `registered`.
+ *
+ * `verify` reads the host through the DECLARED probe
+ * (`RUNTIME_FACTS[copilot-cli].hostProbe`) rather than through
+ * `CopilotRunner`, so a case that wants the host to answer stages it
+ * here; `CopilotRunner` still stages `mcp add` / `mcp remove` / the
+ * presence check that decides which path apply takes.
+ */
+function stageProbe(registered: ReadonlyArray<string>): void {
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: registered.join("\n") + "\n", stderr: "" }),
+ });
+}
+
+/** The probe answering from what `host` was actually told to register. */
+function stageProbeFrom(host: { registered: () => ReadonlyArray<string> }): void {
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: host.registered().join("\n") + "\n", stderr: "" }),
+ });
+}
+
describe("copilot-cli adapter β€” verify", () => {
test("verify ok when CLI lists both names", () => {
- const runner: CopilotRunner = {
- available: () => true,
- run: () => ({ exitCode: 0, stdout: "", stderr: "" }),
- list: () => ({ ok: true, names: ["open-second-brain", "open-second-brain-writer"] }),
- };
- setCopilotRunner(runner);
+ // The host answers with the registrations THIS apply made, so an apply
+ // that skipped one reaches `verify` as the drift it is. Handing the
+ // probe a fixed pair of names instead verified the fixture.
+ const host = fakeCopilotHost();
+ setCopilotRunner(host.runner);
const p = payload();
copilotCliAdapter.apply(copilotCliAdapter.plan(p, env()), p, env(), applyOpts());
+ stageProbeFrom(host);
+ expect([...host.registered()].toSorted()).toEqual(BOTH_KEYS);
expect(copilotCliAdapter.verify(env()).status).toBe("ok");
});
@@ -181,6 +259,7 @@ describe("copilot-cli adapter β€” verify", () => {
});
test("verify drift when CLI lists only one name", () => {
+ stageProbe(["open-second-brain"]);
const runner: CopilotRunner = {
available: () => true,
run: () => ({ exitCode: 0, stdout: "", stderr: "" }),
@@ -191,26 +270,62 @@ describe("copilot-cli adapter β€” verify", () => {
copilotCliAdapter.apply(copilotCliAdapter.plan(p, env()), p, env(), applyOpts());
expect(copilotCliAdapter.verify(env()).status).toBe("drift");
});
-});
-describe("copilot-cli adapter β€” uninstall", () => {
- test("uninstall via CLI removes both names", () => {
- const calls: string[][] = [];
+ test("a subprocess install whose host binary is gone reports the named skip, not ok", () => {
+ // The subprocess mode leaves no file behind, so the host CLI is the
+ // only record of the registration. Losing it means nothing is
+ // verified - and the operator is told WHICH obstacle was hit.
const runner: CopilotRunner = {
available: () => true,
- run: (args) => {
- calls.push([...args]);
- return { exitCode: 0, stdout: "", stderr: "" };
+ run: () => ({ exitCode: 0, stdout: "", stderr: "" }),
+ list: () => ({ ok: true, names: ["open-second-brain", "open-second-brain-writer"] }),
+ };
+ setCopilotRunner(runner);
+ const p = payload();
+ copilotCliAdapter.apply(copilotCliAdapter.plan(p, env()), p, env(), applyOpts());
+ setHostProbeRunner({
+ available: () => false,
+ run: () => {
+ throw new Error("the probe must not spawn a binary it just reported absent");
},
+ });
+ const v = copilotCliAdapter.verify(env());
+ expect(v.status).toBe("mcp-unreachable");
+ expect(v.details.join("\n")).toContain("not on PATH");
+ expect(v.fix_hint ?? "").toContain("PATH");
+ });
+
+ test("a host that refuses the probe names the exit code, not a bare failure", () => {
+ const runner: CopilotRunner = {
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: "", stderr: "" }),
list: () => ({ ok: true, names: ["open-second-brain", "open-second-brain-writer"] }),
};
setCopilotRunner(runner);
const p = payload();
copilotCliAdapter.apply(copilotCliAdapter.plan(p, env()), p, env(), applyOpts());
- calls.length = 0;
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 4, stdout: "", stderr: "not authenticated\n" }),
+ });
+ const v = copilotCliAdapter.verify(env());
+ expect(v.status).toBe("mcp-unreachable");
+ expect(v.details.join("\n")).toContain("exited 4: not authenticated");
+ });
+});
+
+describe("copilot-cli adapter β€” uninstall", () => {
+ test("uninstall via CLI removes both names", () => {
+ const host = fakeCopilotHost();
+ setCopilotRunner(host.runner);
+ const p = payload();
+ copilotCliAdapter.apply(copilotCliAdapter.plan(p, env()), p, env(), applyOpts());
+ host.calls.length = 0;
copilotCliAdapter.uninstall(env(), applyOpts());
- const removeCalls = calls.filter((c) => c[0] === "mcp" && c[1] === "remove");
- expect(removeCalls.length).toBe(2);
+ // Two removals of the FULL server is also "two remove calls", and it
+ // leaves the writer registered on the host forever.
+ expect(namesOf(host.calls, "remove")).toEqual(BOTH_KEYS);
+ expect([...host.registered()]).toEqual([]);
expect(readManifest(vault).installs["copilot-cli"]).toBeUndefined();
});
@@ -231,3 +346,109 @@ describe("copilot-cli adapter β€” uninstall", () => {
expect(parsed.mcpServers["open-second-brain-writer"]).toBeUndefined();
});
});
+
+/**
+ * The other half of the shared refuting-probe rule.
+ *
+ * `probeRefutedVerdict` splits one probe answer into two verdicts, and
+ * this adapter's subprocess mode is the only place in the tree where the
+ * `artifactMatches: false` half is reachable: `copilot mcp add` leaves no
+ * file, so the host's own registry IS the record and a host that answers
+ * without our servers has lost the registration rather than failed to
+ * reload it. The `artifactMatches: true` half - config right, host stale -
+ * is driven for every probe-bearing target in
+ * `tests/core/install/friction.test.ts`.
+ */
+describe("a refuting probe means different things in the two modes", () => {
+ function subprocessCapable(): CopilotRunner {
+ return {
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: "", stderr: "" }),
+ list: () => ({ ok: true, names: ["open-second-brain", "open-second-brain-writer"] }),
+ };
+ }
+
+ test("subprocess mode: the host is the record, so an empty answer is drift", () => {
+ setCopilotRunner(subprocessCapable());
+ const p = payload();
+ copilotCliAdapter.apply(copilotCliAdapter.plan(p, env()), p, env(), applyOpts());
+ stageProbe([]);
+ const v = copilotCliAdapter.verify(env());
+ expect(v.status).toBe("drift");
+ // Re-applying is the repair, because there is nothing on disk that is
+ // already correct for a restart to pick up.
+ expect(v.fix_hint ?? "").toContain("--apply");
+ expect(v.fix_hint ?? "").not.toContain("restart");
+ });
+
+ test("file mode: the file is the record and it matches, so it is unreachable", () => {
+ const absent: CopilotRunner = {
+ available: () => false,
+ run: () => ({ exitCode: 1, stdout: "", stderr: "" }),
+ list: () => ({ ok: false, names: [] }),
+ };
+ setCopilotRunner(absent);
+ const p = payload();
+ copilotCliAdapter.apply(copilotCliAdapter.plan(p, env()), p, env(), applyOpts());
+ stageProbe([]);
+ const v = copilotCliAdapter.verify(env());
+ expect(v.status).toBe("mcp-unreachable");
+ expect(v.fix_hint ?? "").toContain("restart");
+ });
+});
+
+describe("uninstall does not forget an install it failed to remove", () => {
+ test("a `copilot mcp remove` that fails leaves the entry, so the retry works", () => {
+ setCopilotRunner({
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: "", stderr: "" }),
+ list: () => ({ ok: true, names: ["open-second-brain", "open-second-brain-writer"] }),
+ });
+ const p = payload();
+ copilotCliAdapter.apply(copilotCliAdapter.plan(p, env()), p, env(), applyOpts());
+ expect(readManifest(vault).installs["copilot-cli"]).toBeDefined();
+
+ setCopilotRunner({
+ available: () => true,
+ run: () => ({ exitCode: 5, stdout: "", stderr: "copilot refused the remove" }),
+ list: () => ({ ok: true, names: ["open-second-brain", "open-second-brain-writer"] }),
+ });
+ const failed = copilotCliAdapter.uninstall(env(), { ...applyOpts(), fromSnippet: false });
+ expect(failed.removed_keys).toEqual([]);
+ expect(failed.skipped.length).toBe(2);
+ // Kept, so the retry below is not `manifest-missing`.
+ expect(readManifest(vault).installs["copilot-cli"]).toBeDefined();
+
+ setCopilotRunner({
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: "", stderr: "" }),
+ list: () => ({ ok: true, names: [] }),
+ });
+ const retry = copilotCliAdapter.uninstall(env(), { ...applyOpts(), fromSnippet: false });
+ expect(retry.removed_keys.length).toBe(2);
+ expect(readManifest(vault).installs["copilot-cli"]).toBeUndefined();
+ });
+
+ test("an unchanged fallback file is a completed uninstall, not a failure", () => {
+ // A skip is not a failure: there was nothing left to remove. Guarding
+ // the manifest drop on `skipped.length === 0` - the shape grok uses,
+ // where every skip IS a failure - would make this manifest entry
+ // unclearable.
+ const absent: CopilotRunner = {
+ available: () => false,
+ run: () => ({ exitCode: 1, stdout: "", stderr: "" }),
+ list: () => ({ ok: false, names: [] }),
+ };
+ setCopilotRunner(absent);
+ const p = payload();
+ copilotCliAdapter.apply(copilotCliAdapter.plan(p, env()), p, env(), applyOpts());
+ copilotCliAdapter.uninstall(env(), { ...applyOpts(), fromSnippet: false });
+ expect(readManifest(vault).installs["copilot-cli"]).toBeUndefined();
+
+ // Second pass: the file no longer carries the keys.
+ setCopilotRunner(absent);
+ const again = copilotCliAdapter.uninstall(env(), { ...applyOpts(), fromSnippet: true });
+ expect(again.skipped.length).toBe(1);
+ expect(readManifest(vault).installs["copilot-cli"]).toBeUndefined();
+ });
+});
diff --git a/tests/core/install/adapters/grok-hook-parity.test.ts b/tests/core/install/adapters/grok-hook-parity.test.ts
index e8803b1c..cd9657c5 100644
--- a/tests/core/install/adapters/grok-hook-parity.test.ts
+++ b/tests/core/install/adapters/grok-hook-parity.test.ts
@@ -21,6 +21,7 @@ import { describe, expect, test } from "bun:test";
import { readFileSync } from "node:fs";
import { join } from "node:path";
+import { INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT } from "../../../../src/core/brain/policy/blocks/install.ts";
import { grokHooksJson } from "../../../../src/core/install/grok-asset.ts";
import { buildPayload } from "../../../../src/core/install/payload.ts";
import type { McpPayload } from "../../../../src/core/install/types.ts";
@@ -79,7 +80,7 @@ function payload(): McpPayload {
describe("grok registers the plugin's hooks", () => {
const plugin = registeredHooks(readFileSync(PLUGIN_HOOKS_JSON, "utf8"));
- const grok = registeredHooks(grokHooksJson(payload()));
+ const grok = registeredHooks(grokHooksJson(payload(), INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT));
test("the derivation reads a real hook set, not an empty one", () => {
// Both floors sit just under the live measurement. Without them a
diff --git a/tests/core/install/adapters/grok.test.ts b/tests/core/install/adapters/grok.test.ts
index 498394f4..d6480350 100644
--- a/tests/core/install/adapters/grok.test.ts
+++ b/tests/core/install/adapters/grok.test.ts
@@ -16,9 +16,11 @@ import { join } from "node:path";
import { Writable } from "node:stream";
import { grokAdapter } from "../../../../src/core/install/adapters/grok.ts";
+import { INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT } from "../../../../src/core/brain/policy/blocks/install.ts";
import { grokMcpServers, grokHooksJson } from "../../../../src/core/install/grok-asset.ts";
import { hasMcpServers } from "../../../../src/core/install/grok-config.ts";
import { buildPayload } from "../../../../src/core/install/payload.ts";
+import { payloadForHost } from "../../../../src/core/install/payload-host.ts";
import { readManifest } from "../../../../src/core/install/manifest.ts";
let vault: string;
@@ -95,7 +97,11 @@ describe("grok adapter - apply", () => {
test("writes both MCP servers into config.toml with an absolute bun command", () => {
apply();
const toml = readFileSync(configPath(), "utf8");
- expect(hasMcpServers(toml, grokMcpServers(payload()))).toBe(true);
+ // The written tables carry this host's dimensions, so the comparison
+ // has to be against the same transform the adapter applies.
+ expect(hasMcpServers(toml, grokMcpServers(payloadForHost("grok", payload(), env())))).toBe(
+ true,
+ );
expect(toml).toContain("[mcp_servers.open-second-brain]");
expect(toml).toContain("[mcp_servers.open-second-brain-writer]");
// absolute command (the running bun), the repo entry point, and the vault.
@@ -117,7 +123,9 @@ describe("grok adapter - apply", () => {
test("writes the lifecycle hooks file verbatim", () => {
apply();
- expect(readFileSync(hooksPath(), "utf8")).toBe(grokHooksJson(payload()));
+ expect(readFileSync(hooksPath(), "utf8")).toBe(
+ grokHooksJson(payload(), INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT),
+ );
});
test("manifest records the mcp keys and the hooks path", () => {
@@ -155,7 +163,9 @@ describe("grok adapter - apply", () => {
apply();
writeFileSync(hooksPath(), "{}\n");
apply();
- expect(readFileSync(hooksPath(), "utf8")).toBe(grokHooksJson(payload()));
+ expect(readFileSync(hooksPath(), "utf8")).toBe(
+ grokHooksJson(payload(), INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT),
+ );
});
});
diff --git a/tests/core/install/adapters/json-mcp-custom-shape.test.ts b/tests/core/install/adapters/json-mcp-custom-shape.test.ts
index 0c7ecbe3..d9600100 100644
--- a/tests/core/install/adapters/json-mcp-custom-shape.test.ts
+++ b/tests/core/install/adapters/json-mcp-custom-shape.test.ts
@@ -46,8 +46,12 @@ function customShape(e: McpServerEntry): Record<string, unknown> {
};
}
+// A real vocabulary member rather than a synthetic id: `target` is a
+// closed `InstallTargetId` and its only job here is to key the manifest
+// entry. The SHAPE under test is still entirely inline, which is what
+// this file pins - `kiro`'s own adapter is not imported.
const adapter = createJsonMcpAdapter({
- target: "custom-shape-test",
+ target: "kiro",
label: "custom shape (test only)",
topLevelKey: "mcp",
resolveConfigPath: (env: InstallEnv) => join(env.home, ".customrt", "config.json"),
@@ -90,7 +94,7 @@ describe("createJsonMcpAdapter with custom entry shape", () => {
const parsed = JSON.parse(readFileSync(path, "utf8"));
const full = parsed.mcp["open-second-brain"];
expect(full.type).toBe("local");
- expect(full.command).toEqual(["o2b", "mcp", "--vault", vault]);
+ expect(full.command).toEqual(["o2b", "mcp", "--vault", vault, "--host-target", "kiro"]);
expect(full.environment).toEqual({ VAULT_AGENT_NAME: "a", VAULT_TIMEZONE: "UTC" });
expect(full.enabled).toBe(true);
expect(full.args).toBeUndefined();
@@ -129,7 +133,7 @@ describe("createJsonMcpAdapter with custom entry shape", () => {
writeFileSync(path, JSON.stringify(parsed, null, 2) + "\n");
adapter.uninstall(env(), applyOpts());
- expect(readManifest(vault).installs["custom-shape-test"]).toBeUndefined();
+ expect(readManifest(vault).installs["kiro"]).toBeUndefined();
const after = JSON.parse(readFileSync(path, "utf8"));
expect(after.mcp["open-second-brain"]).toBeUndefined();
expect(after.mcp["open-second-brain-writer"]).toBeUndefined();
diff --git a/tests/core/install/adapters/opencode.test.ts b/tests/core/install/adapters/opencode.test.ts
index b4b110dd..b6cd7833 100644
--- a/tests/core/install/adapters/opencode.test.ts
+++ b/tests/core/install/adapters/opencode.test.ts
@@ -100,14 +100,22 @@ describe("opencode adapter - apply", () => {
const full = parsed.mcp["open-second-brain"];
expect(full).toEqual({
type: "local",
- command: ["o2b", "mcp", "--vault", vault],
+ command: ["o2b", "mcp", "--vault", vault, "--host-target", "opencode"],
// opencode keeps the operator host ("dev") but swaps the vendor to its
// own, rather than inheriting the operator name "claude-dev-agent".
environment: { VAULT_AGENT_NAME: "opencode-dev-agent", VAULT_TIMEZONE: "UTC" },
enabled: true,
});
const writer = parsed.mcp["open-second-brain-writer"];
- expect(writer.command).toEqual(["o2b", "mcp", "--writer-only", "--vault", vault]);
+ expect(writer.command).toEqual([
+ "o2b",
+ "mcp",
+ "--writer-only",
+ "--vault",
+ vault,
+ "--host-target",
+ "opencode",
+ ]);
expect(writer.type).toBe("local");
expect(readManifest(vault).installs["opencode"]).toBeDefined();
});
diff --git a/tests/core/install/friction.test.ts b/tests/core/install/friction.test.ts
new file mode 100644
index 00000000..07319fbc
--- /dev/null
+++ b/tests/core/install/friction.test.ts
@@ -0,0 +1,519 @@
+/**
+ * The per-host friction matrix, and the end of the blanket no-handshake
+ * claim.
+ *
+ * Two properties this file exists to hold:
+ *
+ * 1. The matrix is DERIVED. Its rows come from the live adapter
+ * registry and its cells from `RUNTIME_FACTS`, so a runtime added to
+ * the fact table and the registry appears here without a line of
+ * this file changing. Every cell assertion below reads its expected
+ * value out of the same fact row the implementation reads, never out
+ * of a literal copied from it - a test that pins "cursor: 40" passes
+ * for a matrix that ignores the table entirely.
+ * 2. A target whose fact row declares a host probe no longer prints the
+ * blanket "no MCP handshake attempted" note. Both probe branches -
+ * the binary answering and the binary being absent - are driven
+ * through a real plan+apply into a temp home, because a probe that
+ * reports `ok` when it could not run is the misleading default this
+ * whole release removes.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Writable } from "node:stream";
+
+import { registerAllAdapters } from "../../../src/core/install/adapters/all.ts";
+import {
+ resetCodexRunner,
+ setCodexRunner,
+ type CodexRunner,
+} from "../../../src/core/install/adapters/codex.ts";
+import {
+ resetCopilotRunner,
+ setCopilotRunner,
+ type CopilotRunner,
+} from "../../../src/core/install/adapters/copilot-cli.ts";
+import {
+ buildFrictionMatrix,
+ diffFrictionRows,
+ FRICTION_DIMENSION,
+ FRICTION_DIMENSIONS,
+ frictionRowFor,
+ type FrictionInput,
+ type FrictionRow,
+} from "../../../src/core/install/friction.ts";
+import {
+ hostProbeCommand,
+ NO_HANDSHAKE_NOTE,
+ resetHostProbeRunner,
+ setHostProbeRunner,
+ type HostProbeRunner,
+} from "../../../src/core/install/host-probe.ts";
+import { OSB_KEY_FULL, OSB_KEY_WRITER } from "../../../src/core/install/json-merge.ts";
+import {
+ carriesHostDimensions,
+ payloadForHost,
+ TOOL_PROFILE_FLAG,
+} from "../../../src/core/install/payload-host.ts";
+import { buildPayload } from "../../../src/core/install/payload.ts";
+import {
+ INSTALL_TARGET_IDS,
+ RUNTIME_FACTS,
+ TOOL_CEILING_KIND,
+ type InstallTargetId,
+} from "../../../src/core/runtime/host-facts.ts";
+import type {
+ ApplyOpts,
+ InstallAdapter,
+ InstallEnv,
+ SessionPathsResult,
+} from "../../../src/core/install/types.ts";
+
+let vault: string;
+let home: string;
+
+/**
+ * The apply below is REAL, and every mutation seam an adapter owns must be
+ * injected before it runs. The rule, not the instance: the host probe is a
+ * read-only seam this suite stages per case, but each subprocess-driven
+ * adapter carries a SEPARATE seam for the commands that CHANGE the
+ * machine, and any of those left on its default runner will spawn the
+ * operator's real host binary against the operator's real registration.
+ *
+ * That is not hypothetical. `codex` was pinned here and `copilot` was not,
+ * so on a machine with the Copilot CLI installed this file ran four rounds
+ * of `copilot mcp remove` + `copilot mcp add` against the developer's own
+ * registration, pointing it at a `/tmp/osb-friction-v-*` vault that
+ * `afterEach` then deleted - and CI, where no `copilot` exists, reported
+ * a clean pass.
+ *
+ * Pinning them absent also makes the suite deterministic: a runner that
+ * exists on some developer machines and on no CI runner would exercise the
+ * subprocess branch here and the file-fallback branch there and report
+ * both as the same pass. Both branches have their own coverage in the
+ * adapters' own suites; this one pins the fallback so the friction matrix
+ * is the only variable.
+ */
+const ABSENT_CODEX: CodexRunner = {
+ available: () => false,
+ run: () => ({ exitCode: 1, stdout: "", stderr: "codex is not on PATH" }),
+};
+
+const ABSENT_COPILOT: CopilotRunner = {
+ available: () => false,
+ run: () => ({ exitCode: 1, stdout: "", stderr: "copilot is not on PATH" }),
+ list: () => ({ ok: false, names: [] }),
+};
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "osb-friction-v-"));
+ home = mkdtempSync(join(tmpdir(), "osb-friction-h-"));
+ setCodexRunner(ABSENT_CODEX);
+ setCopilotRunner(ABSENT_COPILOT);
+});
+
+afterEach(() => {
+ resetHostProbeRunner();
+ resetCodexRunner();
+ resetCopilotRunner();
+ for (const dir of [vault, home]) {
+ try {
+ rmSync(dir, { recursive: true, force: true });
+ } catch {
+ // temp cleanup is best-effort
+ }
+ }
+});
+
+function sink(): NodeJS.WriteStream {
+ return new Writable({
+ write(_chunk, _enc, cb) {
+ cb();
+ },
+ }) as unknown as NodeJS.WriteStream;
+}
+
+function installEnv(): InstallEnv {
+ return {
+ vault,
+ home,
+ cwd: home,
+ env: { VAULT_AGENT_NAME: "claude-vps", VAULT_TIMEZONE: "UTC" },
+ now: new Date("2026-05-20T12:00:00.000Z"),
+ };
+}
+
+function applyOpts(): ApplyOpts {
+ return { dryRun: false, force: false, stdout: sink(), stderr: sink() };
+}
+
+function input(): FrictionInput {
+ const env = installEnv();
+ return {
+ env,
+ payload: buildPayload({ vault, agent_name: "claude-vps", timezone: "UTC" }),
+ adapters: registerAllAdapters().list(),
+ };
+}
+
+/** The one cell of `row` for `dimension`; the row is total over the set. */
+function cell(row: FrictionRow, dimension: string) {
+ const found = row.cells.find((c) => c.dimension === dimension);
+ expect(`${row.target} answers ${dimension}: ${found !== undefined}`).toBe(
+ `${row.target} answers ${dimension}: true`,
+ );
+ return found!;
+}
+
+describe("the friction matrix is derived, not written", () => {
+ test("the row population is the fact table's, in both directions", () => {
+ const rows = buildFrictionMatrix(input()).rows;
+ expect(rows.map((r) => r.target).toSorted()).toEqual(
+ Object.keys(RUNTIME_FACTS).toSorted() as InstallTargetId[],
+ );
+ // A matrix over an empty registry would satisfy the equality above if
+ // the fact table were ever emptied too.
+ expect(rows.length).toBeGreaterThan(5);
+ });
+
+ test("every row answers every dimension exactly once, in the declared order", () => {
+ for (const row of buildFrictionMatrix(input()).rows) {
+ expect(`${row.target}: ${row.cells.map((c) => c.dimension).join(",")}`).toBe(
+ `${row.target}: ${FRICTION_DIMENSIONS.join(",")}`,
+ );
+ const empty = row.cells.filter((c) => c.value.trim().length === 0);
+ expect(`${row.target} cells with no answer: ${empty.length}`).toBe(
+ `${row.target} cells with no answer: 0`,
+ );
+ }
+ });
+
+ test("the ceiling cell carries the fact row's own number and its citation", () => {
+ for (const row of buildFrictionMatrix(input()).rows) {
+ const ceiling = RUNTIME_FACTS[row.target].toolCeiling;
+ const answer = cell(row, FRICTION_DIMENSION.toolCeiling);
+ expect(answer.value).toContain(ceiling.kind);
+ if (ceiling.kind === TOOL_CEILING_KIND.declared) {
+ expect(answer.value).toContain(String(ceiling.maxTools));
+ expect(answer.detail).toBe(ceiling.source);
+ } else if (ceiling.kind === TOOL_CEILING_KIND.unknown) {
+ expect(answer.detail).toBe(ceiling.reason);
+ }
+ }
+ });
+
+ test("the verify-evidence cell names the declared probe, and the blanket note survives only without one", () => {
+ for (const row of buildFrictionMatrix(input()).rows) {
+ const probe = RUNTIME_FACTS[row.target].hostProbe;
+ const answer = cell(row, FRICTION_DIMENSION.verifyEvidence);
+ if (probe === null) {
+ expect(`${row.target}: ${answer.detail}`).toBe(`${row.target}: ${NO_HANDSHAKE_NOTE}`);
+ } else {
+ expect(answer.value).toContain(hostProbeCommand(probe));
+ expect(answer.detail).toBe(probe.answers);
+ }
+ }
+ });
+
+ test("the session cells report what the fact row declares, not what is on this machine", () => {
+ for (const row of buildFrictionMatrix(input()).rows) {
+ const facts = RUNTIME_FACTS[row.target];
+ const roots = cell(row, FRICTION_DIMENSION.sessionTranscripts);
+ if (facts.sessionRoots.length === 0) {
+ expect(roots.detail).toBeNull();
+ } else {
+ expect(roots.value).toContain(String(facts.sessionRoots.length));
+ for (const root of facts.sessionRoots) {
+ expect(roots.detail ?? "").toContain(root.resolve({ home, env: {} }));
+ }
+ }
+ // The parser cell, on EVERY row. Guarding it behind
+ // `sessionAdapter !== null` ran it for three of the ten and left
+ // nothing pinning what the other seven say - the rows where the
+ // answer is "none ships", which is the answer an operator reads to
+ // decide whether importing this host's transcripts is possible at
+ // all. The expected value is derived from the row's own roots, the
+ // same input the cell is built from.
+ const parser = cell(row, FRICTION_DIMENSION.sessionParser);
+ const parsers = [
+ ...new Set(facts.sessionRoots.map((root) => root.adapter).filter((a) => a !== null)),
+ ].toSorted();
+ expect(`${row.target}: ${parser.value}`).toBe(
+ `${row.target}: ${parsers.length > 0 ? parsers.join(", ") : "none ships"}`,
+ );
+ if (parsers.length === 0) {
+ // Roots in a format nothing reads are named, so "none ships" is a
+ // measured answer rather than a shrug; no roots at all is silence.
+ for (const format of new Set(facts.sessionRoots.map((root) => root.format))) {
+ expect(`${row.target}: ${parser.detail ?? ""}`).toContain(format);
+ }
+ if (facts.sessionRoots.length === 0) expect(parser.detail).toBeNull();
+ }
+ }
+ });
+
+ test("the mechanism cell is the live adapter's own plan", () => {
+ const shared = input();
+ for (const adapter of shared.adapters) {
+ const kinds = new Set(adapter.plan(shared.payload, shared.env).steps.map((s) => s.kind));
+ const answer = cell(frictionRowFor(adapter.target, shared), FRICTION_DIMENSION.mechanism);
+ expect(`${adapter.target}: ${answer.value}`).toBe(
+ `${adapter.target}: ${[...kinds].toSorted().join(", ")}`,
+ );
+ }
+ });
+
+ test("an unknown target is refused by name, with the known list", () => {
+ let message = "";
+ try {
+ frictionRowFor("claude-code" as InstallTargetId, input());
+ } catch (e) {
+ message = (e as Error).message;
+ }
+ expect(message).toContain("claude-code");
+ for (const known of INSTALL_TARGET_IDS) expect(message).toContain(known);
+ });
+});
+
+describe("a diff names the dimensions that differ and stays silent about the rest", () => {
+ test("the differing set is exactly the set of unequal cells, over every pair", () => {
+ const rows = buildFrictionMatrix(input()).rows;
+ const wrong: string[] = [];
+ for (const base of rows) {
+ for (const compare of rows) {
+ const named = new Set(diffFrictionRows(base, compare).differing.map((d) => d.dimension));
+ for (const dimension of FRICTION_DIMENSIONS) {
+ const differs = cell(base, dimension).value !== cell(compare, dimension).value;
+ if (differs !== named.has(dimension)) {
+ wrong.push(`${base.target} vs ${compare.target}: ${dimension}`);
+ }
+ }
+ }
+ }
+ expect(wrong.join("\n")).toBe("");
+ });
+
+ test("a row against itself names nothing, and two unlike hosts name something", () => {
+ const rows = buildFrictionMatrix(input()).rows;
+ const cursor = rows.find((r) => r.target === "cursor")!;
+ const pi = rows.find((r) => r.target === "pi")!;
+ expect(diffFrictionRows(cursor, cursor).differing).toEqual([]);
+ expect(diffFrictionRows(cursor, cursor).shared).toBe(FRICTION_DIMENSIONS.length);
+ expect(diffFrictionRows(cursor, pi).differing.length).toBeGreaterThan(0);
+ expect(
+ diffFrictionRows(cursor, pi).differing.length + diffFrictionRows(cursor, pi).shared,
+ ).toBe(FRICTION_DIMENSIONS.length);
+ });
+});
+
+// ---------- The probe, on both branches ----------
+
+/** Every target whose fact row declares a host probe. Derived. */
+const PROBE_BEARING: ReadonlyArray<InstallTargetId> = INSTALL_TARGET_IDS.filter(
+ (target) => RUNTIME_FACTS[target].hostProbe !== null,
+);
+
+/** A runner whose binary is present and prints `registered`, one per line. */
+function answeringRunner(registered: ReadonlyArray<string>): HostProbeRunner {
+ return {
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: registered.join("\n") + "\n", stderr: "" }),
+ };
+}
+
+/** Install `target` for real, then verify it, and return the printed details. */
+function detailsAfterInstall(target: InstallTargetId): {
+ readonly status: string;
+ readonly details: string;
+} {
+ const adapter = registerAllAdapters().get(target)!;
+ const env = installEnv();
+ const payload = buildPayload({ vault, agent_name: "claude-vps", timezone: "UTC" });
+ adapter.apply(adapter.plan(payload, env), payload, env, applyOpts());
+ const result = adapter.verify(env);
+ return { status: result.status, details: result.details.join("; ") };
+}
+
+describe("a target that declares a host probe stops claiming a handshake it never attempts", () => {
+ test("the probe-bearing population is not empty", () => {
+ // Every case below iterates it; an empty list would pass them all.
+ expect(PROBE_BEARING.length).toBeGreaterThan(0);
+ });
+
+ test("the binary answers: verify names the probe and never the blanket note", () => {
+ for (const target of PROBE_BEARING) {
+ setHostProbeRunner(answeringRunner([OSB_KEY_FULL, OSB_KEY_WRITER]));
+ const { status, details } = detailsAfterInstall(target);
+ expect(`${target}: ${status}`).toBe(`${target}: ok`);
+ expect(details).toContain(hostProbeCommand(RUNTIME_FACTS[target].hostProbe!));
+ expect(details).not.toContain(NO_HANDSHAKE_NOTE);
+ }
+ });
+
+ test("the binary is absent: verify names the skip reason and never the blanket note", () => {
+ for (const target of PROBE_BEARING) {
+ const bin = RUNTIME_FACTS[target].hostProbe!.bin;
+ setHostProbeRunner({
+ available: () => false,
+ run: () => {
+ throw new Error(`the runner must not spawn ${bin} when it is not on PATH`);
+ },
+ });
+ const { details } = detailsAfterInstall(target);
+ expect(details).toContain(bin);
+ expect(details).toContain("not on PATH");
+ expect(details).not.toContain(NO_HANDSHAKE_NOTE);
+ }
+ });
+
+ test("the binary refuses: the non-zero exit is named, not swallowed", () => {
+ for (const target of PROBE_BEARING) {
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 3, stdout: "", stderr: "not authenticated\n" }),
+ });
+ const { details } = detailsAfterInstall(target);
+ expect(details).toContain("3");
+ expect(details).toContain("not authenticated");
+ expect(details).not.toContain(NO_HANDSHAKE_NOTE);
+ }
+ });
+
+ test("the binary answers but the host has nothing registered: that is not ok", () => {
+ // Every mutation runner is pinned absent above, so each of these
+ // installs landed in its adapter's FILE fallback and that file was
+ // just compared and found correct. The shared rule
+ // (`probeRefutedVerdict`) reads a refuting probe over a matching
+ // artifact as a host that has not reloaded it, so the verdict is
+ // `mcp-unreachable` and the repair is a restart - never `drift`,
+ // which would tell the operator to rewrite bytes that are already
+ // right. The host-is-the-only-record half of that rule is driven in
+ // `tests/core/install/adapters/copilot-cli.test.ts`, where the
+ // subprocess branch has an artifact-free registration to refute.
+ for (const target of PROBE_BEARING) {
+ setHostProbeRunner(answeringRunner([]));
+ const { status, details } = detailsAfterInstall(target);
+ expect(`${target}: ${status}`).toBe(`${target}: mcp-unreachable`);
+ expect(details).toContain(OSB_KEY_FULL);
+ }
+ });
+
+ test("a target with no probe keeps the blanket note, because it is the true answer", () => {
+ setHostProbeRunner(answeringRunner([OSB_KEY_FULL, OSB_KEY_WRITER]));
+ const { details } = detailsAfterInstall("cursor");
+ expect(details).toContain(NO_HANDSHAKE_NOTE);
+ });
+});
+
+// ---------- The cells that must describe the real artifact ----------
+
+describe("the tool-profile cell describes the registration this target writes", () => {
+ /** Targets whose generated registration carries no MCP command line. */
+ const NOT_CARRIED: ReadonlyArray<InstallTargetId> = INSTALL_TARGET_IDS.filter(
+ (target) => !carriesHostDimensions(target),
+ );
+
+ test("the population is not empty, and it is the declared one", () => {
+ // Derived from the declaration the write path uses, so a target that
+ // starts routing through `payloadForHost` moves between the two cases
+ // below rather than escaping both.
+ expect(NOT_CARRIED.toSorted()).toEqual(["aider", "generic", "pi"]);
+ });
+
+ test("a target that writes no command line says so instead of naming a profile", () => {
+ // It used to resolve the ladder anyway and print, for example,
+ // `generic tool-profile minimal / resolved from user-config` beside a
+ // `--target generic --apply` whose args carry no `--tool-profile` at
+ // all - a cell contradicting the artifact it claims to describe.
+ for (const target of NOT_CARRIED) {
+ const answer = cell(frictionRowFor(target, input()), FRICTION_DIMENSION.toolProfile);
+ expect(`${target}: ${answer.value}`).toBe(`${target}: not carried`);
+ expect(answer.detail ?? "").toContain("no MCP command line");
+ }
+ });
+
+ test("a target that does write one names the profile its payload carries", () => {
+ const shared = input();
+ for (const target of INSTALL_TARGET_IDS.filter(carriesHostDimensions)) {
+ const answer = cell(frictionRowFor(target, shared), FRICTION_DIMENSION.toolProfile);
+ const written = payloadForHost(target, shared.payload, shared.env);
+ const index = written.full.args.indexOf(TOOL_PROFILE_FLAG);
+ const carried = index === -1 ? "none" : written.full.args[index + 1];
+ expect(`${target}: ${answer.value}`).toBe(`${target}: ${carried}`);
+ }
+ });
+});
+
+describe("the session cells ask the adapter, not the fact table", () => {
+ /** An adapter that answers a DIFFERENT session store than its row. */
+ function withSessionPaths(
+ adapter: InstallAdapter,
+ answer: SessionPathsResult | null,
+ ): InstallAdapter {
+ return { ...adapter, sessionPaths: () => answer };
+ }
+
+ test("an adapter that answers null is reported as declaring nothing", () => {
+ // `codex` declares four roots in `RUNTIME_FACTS`. A matrix reading the
+ // table directly would print them however the adapter answered, which
+ // is what made `InstallAdapter.sessionPaths` a required member with
+ // ten implementations and no caller anywhere in `src/`.
+ const shared = input();
+ const codex = shared.adapters.find((a) => a.target === "codex")!;
+ const silent = withSessionPaths(codex, null);
+ const row = frictionRowFor("codex", { ...shared, adapters: [silent] });
+ expect(cell(row, FRICTION_DIMENSION.sessionTranscripts).value).toBe("none declared");
+ expect(cell(row, FRICTION_DIMENSION.sessionParser).value).toBe("none ships");
+ });
+
+ test("the roots printed are the ones the adapter resolved", () => {
+ const shared = input();
+ for (const adapter of shared.adapters) {
+ const answered = adapter.sessionPaths(shared.env);
+ const roots = cell(
+ frictionRowFor(adapter.target, shared),
+ FRICTION_DIMENSION.sessionTranscripts,
+ );
+ if (answered === null) {
+ expect(`${adapter.target}: ${roots.value}`).toBe(`${adapter.target}: none declared`);
+ continue;
+ }
+ for (const root of answered.roots) expect(roots.detail ?? "").toContain(root.path);
+ }
+ });
+});
+
+describe("an unreadable _brain.yaml is reported, not thrown", () => {
+ beforeEach(() => {
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ writeFileSync(
+ join(vault, "Brain", "_brain.yaml"),
+ "schema_version: 1\ninstall:\n tool_profile: [broken\n",
+ );
+ });
+
+ test("the matrix still answers every row, and names the refusal in the cells", () => {
+ // `--friction` is documented as a report that never exits non-zero.
+ // Once `plan()` began resolving the tool profile, a vault whose config
+ // will not parse turned it into an uncaught `BrainConfigError` stack
+ // trace - `runFriction` catches only usage and payload errors.
+ const rows = buildFrictionMatrix(input()).rows;
+ expect(rows.length).toBe(INSTALL_TARGET_IDS.length);
+ const unresolved = rows.filter((row) => row.cells.some((c) => c.value === "unresolved"));
+ expect(unresolved.length).toBeGreaterThan(0);
+ for (const row of unresolved) {
+ const named = row.cells.filter((c) => c.value === "unresolved");
+ for (const c of named) expect(c.detail ?? "").toContain("_brain.yaml");
+ }
+ });
+
+ test("the refusal is stated, never replaced by a default profile", () => {
+ const row = frictionRowFor("cursor", input());
+ const profile = cell(row, FRICTION_DIMENSION.toolProfile);
+ expect(profile.value).toBe("unresolved");
+ expect(profile.value).not.toBe("catalog");
+ });
+});
diff --git a/tests/core/install/grok-asset.test.ts b/tests/core/install/grok-asset.test.ts
index 03ae5602..9ec18ba6 100644
--- a/tests/core/install/grok-asset.test.ts
+++ b/tests/core/install/grok-asset.test.ts
@@ -7,6 +7,7 @@
import { describe, expect, test } from "bun:test";
+import { INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT } from "../../../src/core/brain/policy/blocks/install.ts";
import { grokHooksJson, grokMcpServers } from "../../../src/core/install/grok-asset.ts";
import type { McpPayload } from "../../../src/core/install/types.ts";
@@ -51,7 +52,7 @@ describe("grokMcpServers", () => {
describe("grokHooksJson", () => {
test("stamps grok's host-qualified id on every hook command's env", () => {
- const parsed = JSON.parse(grokHooksJson(PAYLOAD));
+ const parsed = JSON.parse(grokHooksJson(PAYLOAD, INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT));
const commands = Object.values(
parsed.hooks as Record<string, Array<{ hooks: Array<{ env: Record<string, string> }> }>>,
)
diff --git a/tests/core/install/grok-hook-timeout.test.ts b/tests/core/install/grok-hook-timeout.test.ts
new file mode 100644
index 00000000..b2c4804b
--- /dev/null
+++ b/tests/core/install/grok-hook-timeout.test.ts
@@ -0,0 +1,283 @@
+/**
+ * The generated grok hook entries read their timeout from the committed
+ * vault tier instead of a literal.
+ *
+ * Two obligations pull against each other here and both are pinned below.
+ *
+ * A vault that declares no `install:` block must still generate the file
+ * it generated before this knob existed - install verification works by
+ * RE-CONSTRUCTION, never a stored hash, so a single changed byte reads as
+ * drift on every machine that already applied. The baseline is DERIVED
+ * rather than restated: `hooks/hooks.json` is the shipped plugin hook set
+ * and carries the same timeout on every entry, which is the number the
+ * generator used to hardcode. The parity suite next door already reads
+ * that file for the event -> hook-name map; this reads it for the one
+ * scalar the generator now resolves.
+ *
+ * A vault that DOES declare one must have it reach every entry, and an
+ * unreadable `_brain.yaml` must stop the write rather than quietly
+ * regenerate the default - the file is a writer's input, and a writer
+ * cannot infer intent from bytes it could not parse.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Writable } from "node:stream";
+
+import { grokAdapter } from "../../../src/core/install/adapters/grok.ts";
+import { grokHooksJson } from "../../../src/core/install/grok-asset.ts";
+import { buildPayload } from "../../../src/core/install/payload.ts";
+import { resolveInstallHookTimeoutSeconds } from "../../../src/core/install/settings.ts";
+import { INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT } from "../../../src/core/brain/policy/blocks/install.ts";
+import { brainConfigPath } from "../../../src/core/brain/paths.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+import { CONFIG_ORIGIN } from "../../../src/core/validate.ts";
+import type { InstallEnv } from "../../../src/core/install/types.ts";
+
+const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
+
+interface HookEntry {
+ readonly type: string;
+ readonly command: string;
+ readonly env: Record<string, string>;
+ readonly timeout: number;
+}
+
+/**
+ * The one timeout the shipped plugin hook set uses, read off
+ * `hooks/hooks.json`. Derived, not restated: this is the literal the grok
+ * generator carried before the `install:` block existed, so a vault with
+ * no block must still produce it.
+ */
+function shippedHookTimeoutSeconds(): number {
+ const raw = readFileSync(join(REPO_ROOT, "hooks", "hooks.json"), "utf8");
+ const timeouts = new Set([...raw.matchAll(/"timeout"\s*:\s*(\d+)/g)].map((m) => Number(m[1])));
+ expect(timeouts.size).toBe(1);
+ return [...timeouts][0]!;
+}
+
+/** The committed rendering, with the two per-machine paths left as tokens. */
+function golden(): string {
+ return readFileSync(
+ join(REPO_ROOT, "tests", "fixtures", "install", "grok-hooks.golden.json"),
+ "utf8",
+ );
+}
+
+/**
+ * A generated hooks file reduced to the form the golden is stored in.
+ *
+ * Only the bun binary and the repository root are tokenised, because only
+ * those two are machine-specific by design (grok's restricted
+ * session-spawn PATH forces absolute commands). Tokenising anything else
+ * would be the golden agreeing not to look at it.
+ */
+function normalize(json: string): string {
+ return json.split(process.execPath).join("<BUN>").split(REPO_ROOT).join("<REPO>");
+}
+
+function hookEntries(json: string): ReadonlyArray<HookEntry> {
+ const parsed = JSON.parse(json) as {
+ hooks: Record<string, Array<{ hooks: HookEntry[] }>>;
+ };
+ return Object.values(parsed.hooks)
+ .flat()
+ .flatMap((group) => group.hooks);
+}
+
+let vault: string;
+let home: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "osb-grok-timeout-v-"));
+ home = mkdtempSync(join(tmpdir(), "osb-grok-timeout-h-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+});
+
+afterEach(() => {
+ for (const dir of [vault, home]) rmSync(dir, { recursive: true, force: true });
+});
+
+function installEnv(): InstallEnv {
+ return {
+ vault,
+ home,
+ cwd: home,
+ env: { VAULT_AGENT_NAME: "claude-dev-agent", VAULT_TIMEZONE: "UTC" },
+ now: new Date("2026-06-12T12:00:00.000Z"),
+ };
+}
+
+function payload() {
+ return buildPayload({ vault, agent_name: "claude-dev-agent", timezone: "UTC" });
+}
+
+function apply(): void {
+ const sink = new Writable({
+ write(_chunk, _encoding, done) {
+ done();
+ },
+ });
+ const opts = {
+ dryRun: false,
+ force: false,
+ stdout: sink as unknown as NodeJS.WriteStream,
+ stderr: sink as unknown as NodeJS.WriteStream,
+ };
+ const env = installEnv();
+ grokAdapter.apply(grokAdapter.plan(payload(), env), payload(), env, opts);
+}
+
+function hooksPath(): string {
+ return join(home, ".grok", "hooks", "open-second-brain.json");
+}
+
+describe("a vault with no install: block regenerates the committed output", () => {
+ test("the compiled default is the timeout the shipped hook set carries", () => {
+ expect(INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT).toBe(shippedHookTimeoutSeconds());
+ });
+
+ test("resolution reports the default layer and the shipped value", () => {
+ expect(
+ resolveInstallHookTimeoutSeconds({
+ vault,
+ configPath: join(home, "absent-config.yaml"),
+ }),
+ ).toEqual({ value: shippedHookTimeoutSeconds(), origin: CONFIG_ORIGIN.default });
+ });
+
+ test("the generation matches the committed golden rendering, byte for byte", () => {
+ // The anchor. Every other "byte-identical" assertion here and in the
+ // adapter suite compared the generator against ITSELF - the same call
+ // with the argument the default supplied - so it could only fail if
+ // the generator were non-deterministic, and a change to the hook
+ // command paths, the `env` map, the entry ordering or the JSON
+ // indentation left every one of them green. This compares against
+ // bytes committed to the tree.
+ //
+ // Two substitutions, and only two: the bun binary and the repository
+ // root are absolute paths that differ per machine, and the whole
+ // reason `grok-asset.ts` emits them is that grok's session-spawn PATH
+ // will not resolve a bare command. Everything else - including the
+ // derived agent name and the timeout on every entry - is compared
+ // literally.
+ expect(normalize(grokHooksJson(payload(), shippedHookTimeoutSeconds()))).toBe(golden());
+ });
+
+ test("the applied file is the same golden rendering", () => {
+ apply();
+ expect(normalize(readFileSync(hooksPath(), "utf8"))).toBe(golden());
+ });
+
+ test("every generated entry carries the shipped timeout", () => {
+ const entries = hookEntries(grokHooksJson(payload(), shippedHookTimeoutSeconds()));
+ expect(entries.length).toBeGreaterThan(0);
+ for (const entry of entries) expect(entry.timeout).toBe(shippedHookTimeoutSeconds());
+ });
+});
+
+describe("a configured hook_timeout_seconds reaches every entry", () => {
+ const CONFIGURED = 45;
+
+ beforeEach(() => {
+ atomicWriteFileSync(
+ brainConfigPath(vault),
+ `schema_version: 1\ninstall:\n hook_timeout_seconds: ${CONFIGURED}\n`,
+ );
+ });
+
+ test("the resolver reports the vault-config layer", () => {
+ expect(
+ resolveInstallHookTimeoutSeconds({
+ vault,
+ configPath: join(home, "absent-config.yaml"),
+ }),
+ ).toEqual({ value: CONFIGURED, origin: CONFIG_ORIGIN.vaultConfig });
+ });
+
+ test("the applied hooks file carries it on every entry", () => {
+ apply();
+ const entries = hookEntries(readFileSync(hooksPath(), "utf8"));
+ expect(entries.length).toBeGreaterThan(0);
+ for (const entry of entries) expect(entry.timeout).toBe(CONFIGURED);
+ });
+
+ test("the applied file equals the generation for that timeout", () => {
+ apply();
+ expect(readFileSync(hooksPath(), "utf8")).toBe(grokHooksJson(payload(), CONFIGURED));
+ });
+
+ test("it is the golden rendering with only the timeout changed", () => {
+ // Pins the SCOPE of the setting as well as its arrival: a knob that
+ // also moved a command path or reordered the entries would pass the
+ // assertion above and fail this one.
+ apply();
+ expect(normalize(readFileSync(hooksPath(), "utf8"))).toBe(
+ golden().replaceAll(`"timeout": ${shippedHookTimeoutSeconds()}`, `"timeout": ${CONFIGURED}`),
+ );
+ });
+
+ test("a freshly applied install reports no drift", () => {
+ apply();
+ expect(grokAdapter.verify(installEnv()).status).toBe("ok");
+ });
+});
+
+describe("an unreadable _brain.yaml refuses the generation", () => {
+ beforeEach(() => {
+ atomicWriteFileSync(
+ brainConfigPath(vault),
+ "schema_version: 1\ninstall:\n hook_timeout_seconds: [broken\n",
+ );
+ });
+
+ test("apply refuses and names the file", () => {
+ let message = "";
+ try {
+ apply();
+ } catch (err) {
+ message = (err as Error).message;
+ }
+ expect(message).toContain(brainConfigPath(vault));
+ });
+
+ test("nothing is written", () => {
+ try {
+ apply();
+ } catch {
+ // The refusal is the assertion below: no hooks file exists.
+ }
+ expect(() => readFileSync(hooksPath(), "utf8")).toThrow();
+ });
+
+ /**
+ * The READ paths refuse too, and they are the ones with a blast radius:
+ * `o2b install` with no `--target` walks every adapter's `detect`, and
+ * `--check` walks every `verify`, so one unparsable file used to take
+ * down the status of nine targets that never read it. The refusal is
+ * still correct - `syncState` compares against a generation it cannot
+ * produce - and `src/cli/main.ts` now renders it as one line rather than
+ * a stack trace.
+ */
+ test("verify refuses and names the file", () => {
+ let message = "";
+ try {
+ grokAdapter.verify(installEnv());
+ } catch (err) {
+ message = (err as Error).message;
+ }
+ expect(message).toContain(brainConfigPath(vault));
+ });
+
+ test("detect refuses and names the file", () => {
+ let message = "";
+ try {
+ grokAdapter.detect(installEnv());
+ } catch (err) {
+ message = (err as Error).message;
+ }
+ expect(message).toContain(brainConfigPath(vault));
+ });
+});
diff --git a/tests/core/install/host-probe.test.ts b/tests/core/install/host-probe.test.ts
new file mode 100644
index 00000000..8600d46b
--- /dev/null
+++ b/tests/core/install/host-probe.test.ts
@@ -0,0 +1,207 @@
+/**
+ * The host probe: what it parses, which machine it asks, and what it does
+ * when the host does not answer.
+ *
+ * Three properties, each of which was previously either untested or tested
+ * only against strings the tests themselves authored:
+ *
+ * 1. The parser is driven by a REAL capture. Every case for
+ * `registeredNames` used to invent its own `mcp list` output, so the
+ * parser was only ever held against the format the test author
+ * believed in. Real `codex mcp list` prints a padded table WITH a
+ * header row, which no authored fixture had.
+ * 2. The probe asks the host named by the `InstallEnv`, not the ambient
+ * one. `codex.ts` declares "the Codex home is injected, never
+ * ambient" for its mutation runner; the probe seam took no
+ * environment at all, so `verify` on a relocated `CODEX_HOME`
+ * described one machine in its file half and another in its
+ * handshake half.
+ * 3. The wait is bounded. An unauthenticated host that blocks on a
+ * network call or a prompt used to hang `o2b install --check` with no
+ * message and no way out.
+ */
+
+import { describe, expect, test, afterEach } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+ createHostProbeRunner,
+ hostProbeEnvironment,
+ HOST_PROBE_RESULT,
+ HOST_PROBE_TIMEOUT_MS,
+ probeHost,
+ resetHostProbeRunner,
+ setHostProbeRunner,
+ type HostProbeEnvironment,
+ type HostProbeRunResult,
+} from "../../../src/core/install/host-probe.ts";
+import { OSB_KEY_FULL, OSB_KEY_WRITER } from "../../../src/core/install/json-merge.ts";
+import type { InstallEnv } from "../../../src/core/install/types.ts";
+
+const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
+
+/** The capture committed at `tests/fixtures/install/codex-mcp-list.txt`. */
+function realCodexListing(): string {
+ return readFileSync(
+ join(REPO_ROOT, "tests", "fixtures", "install", "codex-mcp-list.txt"),
+ "utf8",
+ );
+}
+
+function envFor(extra: Readonly<Record<string, string>> = {}): InstallEnv {
+ return {
+ vault: "/srv/vaults/example",
+ home: "/home/operator",
+ cwd: "/srv/projects/example",
+ env: { PATH: "/usr/bin", ...extra },
+ now: new Date("2026-08-16T09:00:00.000Z"),
+ };
+}
+
+afterEach(() => {
+ resetHostProbeRunner();
+});
+
+describe("the parser is held against real host output", () => {
+ test("the committed capture is the real shape: a padded table with a header", () => {
+ // A fixture that had been reduced to one bare name would make every
+ // assertion below pass for a parser that cannot read a table at all.
+ const lines = realCodexListing().trimEnd().split("\n");
+ expect(lines.length).toBe(2);
+ expect(lines[0]!.split(/\s+/)[0]).toBe("Name");
+ expect(lines[0]).toContain("Status");
+ expect(lines[1]).toContain("enabled");
+ });
+
+ test("it reports the one OSB server this machine had registered", () => {
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: realCodexListing(), stderr: "" }),
+ });
+ const outcome = probeHost("codex", envFor());
+ expect(outcome.kind).toBe(HOST_PROBE_RESULT.answered);
+ if (outcome.kind !== HOST_PROBE_RESULT.answered) throw new Error("unreachable");
+ expect(outcome.registered).toEqual([OSB_KEY_FULL]);
+ expect(outcome.missing).toEqual([OSB_KEY_WRITER]);
+ });
+
+ test("the header row cannot become a registered server", () => {
+ // `registeredNames` deliberately does NOT skip the header: recognising
+ // each host's header would be a per-host grammar to keep up with. It
+ // is safe by construction instead - the answer is an intersection with
+ // two fixed names, and no host prints a column called
+ // `open-second-brain`. This is the assertion that says so out loud.
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: realCodexListing(), stderr: "" }),
+ });
+ const outcome = probeHost("codex", envFor());
+ if (outcome.kind !== HOST_PROBE_RESULT.answered) throw new Error("unreachable");
+ for (const name of [...outcome.registered, ...outcome.missing]) {
+ expect([OSB_KEY_FULL, OSB_KEY_WRITER]).toContain(name);
+ }
+ });
+
+ test("a host with both registered under the same table shape answers clean", () => {
+ const both =
+ realCodexListing().trimEnd() +
+ "\nopen-second-brain-writer o2b mcp - - enabled Unsupported\n";
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: both, stderr: "" }),
+ });
+ const outcome = probeHost("codex", envFor());
+ if (outcome.kind !== HOST_PROBE_RESULT.answered) throw new Error("unreachable");
+ expect(outcome.missing).toEqual([]);
+ });
+});
+
+describe("the probe asks the host being verified", () => {
+ /** A runner that records the environment it was handed. */
+ function recordingRunner(seen: { env: HostProbeEnvironment | null; bin: string | null }) {
+ return {
+ available(bin: string, env: HostProbeEnvironment): boolean {
+ seen.bin = bin;
+ seen.env = env;
+ return true;
+ },
+ run(
+ _bin: string,
+ _argv: ReadonlyArray<string>,
+ env: HostProbeEnvironment,
+ ): HostProbeRunResult {
+ seen.env = env;
+ return { exitCode: 0, stdout: "", stderr: "" };
+ },
+ };
+ }
+
+ test("HOME is the injected home, not the ambient one", () => {
+ const seen: { env: HostProbeEnvironment | null; bin: string | null } = { env: null, bin: null };
+ setHostProbeRunner(recordingRunner(seen));
+ probeHost("codex", envFor());
+ expect(seen.bin).toBe("codex");
+ expect(seen.env?.["HOME"]).toBe("/home/operator");
+ });
+
+ test("a relocated CODEX_HOME reaches the subprocess", () => {
+ // The measured defect: applying codex into an isolated `CODEX_HOME`
+ // and calling `verify` ran `codex mcp list` with `CODEX_HOME` unset,
+ // so the handshake described the operator's real `~/.codex` while the
+ // file comparison described the temporary one.
+ const seen: { env: HostProbeEnvironment | null; bin: string | null } = { env: null, bin: null };
+ setHostProbeRunner(recordingRunner(seen));
+ probeHost("codex", envFor({ CODEX_HOME: "/mnt/elsewhere/codex" }));
+ expect(seen.env?.["CODEX_HOME"]).toBe("/mnt/elsewhere/codex");
+ });
+
+ test("the environment is derived from the InstallEnv alone", () => {
+ const env = envFor({ XDG_CONFIG_HOME: "/mnt/cfg" });
+ expect(hostProbeEnvironment(env)).toEqual({
+ PATH: "/usr/bin",
+ XDG_CONFIG_HOME: "/mnt/cfg",
+ HOME: "/home/operator",
+ });
+ });
+});
+
+describe("the wait is bounded", () => {
+ test("the shipped cap is a positive number of milliseconds", () => {
+ expect(Number.isSafeInteger(HOST_PROBE_TIMEOUT_MS)).toBe(true);
+ expect(HOST_PROBE_TIMEOUT_MS).toBeGreaterThan(0);
+ });
+
+ test("a host that never answers is killed and reported, not waited on", () => {
+ // Driven against `sleep`, which stands in for the real obstacle: a
+ // host CLI blocking on a network call or an interactive
+ // authentication prompt. Without the cap this call never returns.
+ const sleep = Bun.which("sleep");
+ expect(sleep === null ? "sleep is on PATH: false" : "sleep is on PATH: true").toBe(
+ "sleep is on PATH: true",
+ );
+ const runner = createHostProbeRunner(200);
+ const started = Date.now();
+ const result = runner.run("sleep", ["30"], { PATH: process.env["PATH"] ?? "/usr/bin" });
+ const elapsed = Date.now() - started;
+ expect(elapsed).toBeLessThan(10_000);
+ expect(result.exitCode).not.toBe(0);
+ expect(result.stdout).toBe("");
+ expect(result.stderr).toContain("200 ms");
+ });
+
+ test("a killed probe becomes a named skip, never an assumed answer", () => {
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({
+ exitCode: 1,
+ stdout: "",
+ stderr: `killed by SIGTERM; the probe is capped at ${HOST_PROBE_TIMEOUT_MS} ms`,
+ }),
+ });
+ const outcome = probeHost("codex", envFor());
+ expect(outcome.kind).toBe(HOST_PROBE_RESULT.probeFailed);
+ if (outcome.kind !== HOST_PROBE_RESULT.probeFailed) throw new Error("unreachable");
+ expect(outcome.reason).toContain("SIGTERM");
+ });
+});
diff --git a/tests/core/install/payload-host.test.ts b/tests/core/install/payload-host.test.ts
new file mode 100644
index 00000000..27567e91
--- /dev/null
+++ b/tests/core/install/payload-host.test.ts
@@ -0,0 +1,218 @@
+/**
+ * `HOST_PAYLOAD_TARGETS` against the artifacts the ten adapters write.
+ *
+ * The set answers one question - "does this target's generated
+ * registration carry the host dimensions" - and three surfaces read it:
+ * `payloadForHost` (which refuses a non-member), `o2b update`'s payload
+ * hash, and `--friction`'s tool-profile cell. A declaration read by three
+ * surfaces and checked by none would be a fourth place for the routing to
+ * drift from what is claimed about it, which is the shape of defect this
+ * release exists to remove.
+ *
+ * So the check is BEHAVIOURAL, not a re-listing: every adapter is applied
+ * for real into a temporary home, every file it leaves is read back, and
+ * the set of targets whose artifact mentions `--host-target` is required
+ * to equal the declared set. A target that stopped routing through
+ * `payloadForHost`, or started, moves in the measurement rather than in a
+ * literal somebody has to remember to edit.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Writable } from "node:stream";
+
+import { registerAllAdapters } from "../../../src/core/install/adapters/all.ts";
+import {
+ resetCodexRunner,
+ setCodexRunner,
+ type CodexRunner,
+} from "../../../src/core/install/adapters/codex.ts";
+import {
+ resetCopilotRunner,
+ setCopilotRunner,
+ type CopilotRunner,
+} from "../../../src/core/install/adapters/copilot-cli.ts";
+import {
+ carriesHostDimensions,
+ HOST_PAYLOAD_TARGETS,
+ HOST_TARGET_FLAG,
+ payloadAsWritten,
+ payloadForHost,
+ writtenToolProfile,
+} from "../../../src/core/install/payload-host.ts";
+import { buildPayload } from "../../../src/core/install/payload.ts";
+import { INSTALL_TARGET_IDS, type InstallTargetId } from "../../../src/core/runtime/host-facts.ts";
+import type { ApplyOpts, InstallEnv } from "../../../src/core/install/types.ts";
+
+let vault: string;
+let home: string;
+
+/**
+ * Both subprocess seams are pinned absent, so every adapter takes its FILE
+ * path and leaves something on disk to read. Left on their defaults they
+ * would spawn the operator's real host binaries against the operator's
+ * real registrations - and the subprocess branches would then leave
+ * nothing under `home` for the sweep below to find.
+ */
+const ABSENT_CODEX: CodexRunner = {
+ available: () => false,
+ run: () => ({ exitCode: 1, stdout: "", stderr: "codex is not on PATH" }),
+};
+
+const ABSENT_COPILOT: CopilotRunner = {
+ available: () => false,
+ run: () => ({ exitCode: 1, stdout: "", stderr: "copilot is not on PATH" }),
+ list: () => ({ ok: false, names: [] }),
+};
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "osb-payload-host-v-"));
+ home = mkdtempSync(join(tmpdir(), "osb-payload-host-h-"));
+ setCodexRunner(ABSENT_CODEX);
+ setCopilotRunner(ABSENT_COPILOT);
+});
+
+afterEach(() => {
+ resetCodexRunner();
+ resetCopilotRunner();
+ for (const dir of [vault, home]) {
+ try {
+ rmSync(dir, { recursive: true, force: true });
+ } catch {
+ // temp cleanup is best-effort
+ }
+ }
+});
+
+function sink(): NodeJS.WriteStream {
+ return new Writable({
+ write(_chunk, _enc, cb) {
+ cb();
+ },
+ }) as unknown as NodeJS.WriteStream;
+}
+
+function installEnv(): InstallEnv {
+ return {
+ vault,
+ home,
+ cwd: home,
+ env: { VAULT_AGENT_NAME: "claude-vps", VAULT_TIMEZONE: "UTC" },
+ now: new Date("2026-08-16T12:00:00.000Z"),
+ };
+}
+
+/** Every regular file under `dir`, following no symlink. */
+function filesUnder(dir: string): ReadonlyArray<string> {
+ const out: string[] = [];
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const path = join(dir, entry.name);
+ if (entry.isSymbolicLink()) continue;
+ if (entry.isDirectory()) {
+ out.push(...filesUnder(path));
+ continue;
+ }
+ if (statSync(path).isFile()) out.push(path);
+ }
+ return out;
+}
+
+/**
+ * Apply `target` into the temporary home and return everything it wrote.
+ *
+ * `generic` prints rather than installing, so it is given an explicit
+ * `--out` inside the same home; without one it writes to stdout and the
+ * sweep would report it as carrying nothing for the wrong reason.
+ */
+function artifactsAfterApply(target: InstallTargetId): string {
+ const adapter = registerAllAdapters().get(target)!;
+ const env = installEnv();
+ const payload = buildPayload({ vault, agent_name: "claude-vps", timezone: "UTC" });
+ const opts: ApplyOpts = {
+ dryRun: false,
+ force: false,
+ stdout: sink(),
+ stderr: sink(),
+ outPath: join(home, "generic-payload.json"),
+ piSkillDir: join(home, "pi-skills"),
+ };
+ adapter.apply(adapter.plan(payload, env), payload, env, opts);
+ return filesUnder(home)
+ .map((file) => {
+ try {
+ return readFileSync(file, "utf8");
+ } catch {
+ return "";
+ }
+ })
+ .join("\n");
+}
+
+describe("the declared set is the set that actually writes host dimensions", () => {
+ test("the population is the whole registry, so neither direction can be empty", () => {
+ expect(INSTALL_TARGET_IDS.length).toBe(registerAllAdapters().list().length);
+ expect(HOST_PAYLOAD_TARGETS.size).toBeGreaterThan(0);
+ expect(HOST_PAYLOAD_TARGETS.size).toBeLessThan(INSTALL_TARGET_IDS.length);
+ });
+
+ test("an applied artifact carries --host-target exactly when the set says so", () => {
+ const measured: string[] = [];
+ for (const target of INSTALL_TARGET_IDS) {
+ if (artifactsAfterApply(target).includes(HOST_TARGET_FLAG)) measured.push(target);
+ // Each target gets a clean home, so one adapter's artifact cannot be
+ // credited to the next.
+ rmSync(home, { recursive: true, force: true });
+ home = mkdtempSync(join(tmpdir(), "osb-payload-host-h-"));
+ }
+ expect(measured.toSorted()).toEqual([...HOST_PAYLOAD_TARGETS].toSorted());
+ });
+
+ test("a target outside the set is refused by name rather than silently transformed", () => {
+ // The other direction of the same claim: an adapter that started
+ // routing an undeclared target through here would fail loudly instead
+ // of leaving the declaration quietly wrong.
+ let message = "";
+ try {
+ payloadForHost(
+ "generic",
+ buildPayload({ vault, agent_name: "claude-vps", timezone: "UTC" }),
+ installEnv(),
+ );
+ } catch (exc) {
+ message = (exc as Error).message;
+ }
+ expect(message).toContain("generic");
+ expect(message).toContain("HOST_PAYLOAD_TARGETS");
+ });
+});
+
+describe("what update hashes is what gets written", () => {
+ test("a member's hashed payload carries the dimensions", () => {
+ const payload = buildPayload({ vault, agent_name: "claude-vps", timezone: "UTC" });
+ const written = payloadAsWritten("cursor", payload, installEnv());
+ expect(written.full.args).toContain(HOST_TARGET_FLAG);
+ expect(written).toEqual(payloadForHost("cursor", payload, installEnv()));
+ });
+
+ test("a non-member's hashed payload is the canonical one, unchanged", () => {
+ const payload = buildPayload({ vault, agent_name: "claude-vps", timezone: "UTC" });
+ expect(payloadAsWritten("generic", payload, installEnv())).toEqual(payload);
+ });
+});
+
+describe("the profile question distinguishes its two nulls", () => {
+ test("a target that writes no command line answers null for the whole question", () => {
+ for (const target of INSTALL_TARGET_IDS.filter((t) => !carriesHostDimensions(t))) {
+ expect(`${target}: ${writtenToolProfile(target, installEnv())}`).toBe(`${target}: null`);
+ }
+ });
+
+ test("a target with no declared profile answers a resolution whose value is null", () => {
+ const resolved = writtenToolProfile("kiro", installEnv());
+ expect(resolved).not.toBeNull();
+ expect(resolved!.value).toBeNull();
+ expect(resolved!.origin).toBe("default");
+ });
+});
diff --git a/tests/core/install/registry.test.ts b/tests/core/install/registry.test.ts
index 86ed4a5c..08a0b572 100644
--- a/tests/core/install/registry.test.ts
+++ b/tests/core/install/registry.test.ts
@@ -9,11 +9,17 @@ import type {
UninstallResult,
VerifyResult,
} from "../../../src/core/install/types.ts";
+import type { InstallTargetId } from "../../../src/core/runtime/host-facts.ts";
-function makeFakeAdapter(target: string): InstallAdapter {
+function makeFakeAdapter(target: InstallTargetId): InstallAdapter {
return {
target,
label: target,
+ // The seam is required on every adapter; a double that answers
+ // `null` is a runtime with no session store, which is what a double is.
+ sessionPaths(): null {
+ return null;
+ },
detect(env: InstallEnv): DetectResult {
void env;
return { target, status: "not-installed", configPath: null, notes: [] };
@@ -61,10 +67,10 @@ describe("install registry", () => {
test("register + get round-trip", () => {
const reg = createRegistry();
- const a = makeFakeAdapter("test");
+ const a = makeFakeAdapter("generic");
reg.register(a);
- expect(reg.get("test")).toBe(a);
- expect(reg.list().map((x) => x.target)).toEqual(["test"]);
+ expect(reg.get("generic")).toBe(a);
+ expect(reg.list().map((x) => x.target)).toEqual(["generic"]);
});
test("register rejects duplicate target", () => {
@@ -75,24 +81,24 @@ describe("install registry", () => {
test("detectAll returns one entry per registered adapter", () => {
const reg = createRegistry();
- reg.register(makeFakeAdapter("a"));
- reg.register(makeFakeAdapter("b"));
+ reg.register(makeFakeAdapter("aider"));
+ reg.register(makeFakeAdapter("kiro"));
const out = reg.detectAll(makeEnv());
- expect(out.map((d) => d.target).toSorted()).toEqual(["a", "b"]);
+ expect(out.map((d) => d.target).toSorted()).toEqual(["aider", "kiro"]);
});
test("list returns adapters in registration order", () => {
const reg = createRegistry();
- reg.register(makeFakeAdapter("b"));
- reg.register(makeFakeAdapter("a"));
- reg.register(makeFakeAdapter("c"));
- expect(reg.list().map((x) => x.target)).toEqual(["b", "a", "c"]);
+ reg.register(makeFakeAdapter("kiro"));
+ reg.register(makeFakeAdapter("aider"));
+ reg.register(makeFakeAdapter("grok"));
+ expect(reg.list().map((x) => x.target)).toEqual(["kiro", "aider", "grok"]);
});
test("targets() returns target names only", () => {
const reg = createRegistry();
- reg.register(makeFakeAdapter("a"));
- reg.register(makeFakeAdapter("b"));
- expect(reg.targets()).toEqual(["a", "b"]);
+ reg.register(makeFakeAdapter("aider"));
+ reg.register(makeFakeAdapter("kiro"));
+ expect(reg.targets()).toEqual(["aider", "kiro"]);
});
});
diff --git a/tests/core/install/session-paths.test.ts b/tests/core/install/session-paths.test.ts
new file mode 100644
index 00000000..1190b9b6
--- /dev/null
+++ b/tests/core/install/session-paths.test.ts
@@ -0,0 +1,179 @@
+/**
+ * `InstallAdapter.sessionPaths` over the whole registered population.
+ *
+ * The member shipped as an optional one with zero implementations and
+ * zero call sites, carrying a `format` union
+ * (`"claude-jsonl" | "codex-json" | "cursor-sqlite" | "unknown"`) that no
+ * other module in the tree used and that named none of the adapters
+ * `src/core/brain/sessions/` actually ships. An optional member nobody
+ * implements is indistinguishable from one nobody needs, and that is what
+ * this file changes: the answer is REQUIRED, so a runtime storing no
+ * session logs has to say `null` rather than say nothing.
+ *
+ * The population is derived from `registerAllAdapters()` for the same
+ * reason `host-facts-census.test.ts` derives its own: a hand-listed set of
+ * adapters vouches only for the adapters somebody remembered.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { registerAllAdapters } from "../../../src/core/install/adapters/all.ts";
+import { sessionPathsFor } from "../../../src/core/install/session-paths.ts";
+import type { InstallEnv } from "../../../src/core/install/types.ts";
+import {
+ isInstallTargetId,
+ isSessionRuntimeId,
+ resolveSessionRootsFor,
+ RUNTIME_FACTS,
+ SESSION_ROOTS,
+ SESSION_RUNTIME_ID,
+ type InstallTargetId,
+} from "../../../src/core/runtime/host-facts.ts";
+import { isSessionAdapterId } from "../../../src/core/brain/sessions/types.ts";
+
+const HOME = "/home/operator";
+
+function envFor(extra: Readonly<Record<string, string>> = {}): InstallEnv {
+ return {
+ vault: "/srv/vaults/example",
+ home: HOME,
+ cwd: "/srv/projects/example",
+ env: extra,
+ now: new Date("2026-08-16T09:00:00.000Z"),
+ };
+}
+
+const ADAPTERS = registerAllAdapters().list();
+
+describe("every adapter answers where its sessions live", () => {
+ test("the population is the registered one, and every target is a vocabulary member", () => {
+ // A registry that stopped registering would make every assertion
+ // below pass over nothing.
+ expect(ADAPTERS.length).toBe(10);
+ const strangers = ADAPTERS.map((a) => a.target).filter((t) => !isInstallTargetId(t));
+ expect(strangers.join("\n")).toBe("");
+ });
+
+ test("no adapter leaves the member absent", () => {
+ const silent = ADAPTERS.filter((a) => typeof a.sessionPaths !== "function").map(
+ (a) => a.target,
+ );
+ expect(silent.toSorted().join("\n")).toBe("");
+ });
+
+ test("a runtime that stores no session logs answers null, and says so on purpose", () => {
+ const quiet: ReadonlyArray<string> = ADAPTERS.filter(
+ (a) => a.sessionPaths(envFor()) === null,
+ ).map((a) => a.target);
+ expect(quiet.toSorted()).toEqual(
+ ["aider", "copilot-cli", "gemini-cli", "generic", "kiro", "pi"].toSorted(),
+ );
+ });
+
+ test("a runtime that stores session logs answers the fact table's roots, resolved", () => {
+ // The declaration is reached through the RUNTIME-keyed lookup
+ // (`resolveSessionRootsFor` over `SESSION_ROOTS`), not the
+ // target-keyed one. Comparing `adapter.sessionPaths()` against
+ // `resolveSessionRoots(target)` was a tautology: both read
+ // `RUNTIME_FACTS[target].sessionRoots`, so the assertion held for any
+ // value that field could contain. Going through the other lookup is
+ // what makes a row naming one runtime while carrying another's roots
+ // fail here.
+ const drifted: string[] = [];
+ for (const adapter of ADAPTERS) {
+ const target = adapter.target as InstallTargetId;
+ const runtime = RUNTIME_FACTS[target].sessionRuntime;
+ const declared =
+ runtime === null ? [] : resolveSessionRootsFor(runtime, { home: HOME, env: {} });
+ const answered = adapter.sessionPaths(envFor());
+ if (declared.length === 0) {
+ if (answered !== null) drifted.push(`${target}: roots with no declaration`);
+ continue;
+ }
+ if (answered === null) {
+ drifted.push(`${target}: declared roots but answered null`);
+ continue;
+ }
+ if (JSON.stringify(answered.roots) !== JSON.stringify(declared)) {
+ drifted.push(`${target}: answered roots differ from the declaration`);
+ }
+ if (answered.target !== target) drifted.push(`${target}: answered for ${answered.target}`);
+ if (!isSessionRuntimeId(answered.runtime)) {
+ drifted.push(`${target}: runtime ${String(answered.runtime)} is not a session runtime`);
+ }
+ }
+ expect(drifted.toSorted().join("\n")).toBe("");
+ });
+
+ test("each root names a session adapter, or names the format no adapter reads", () => {
+ const defects: string[] = [];
+ for (const adapter of ADAPTERS) {
+ const answered = adapter.sessionPaths(envFor());
+ if (answered === null) continue;
+ for (const root of answered.roots) {
+ if (root.adapter === null) {
+ // The stated non-session format. `format` is what makes the
+ // null a fact rather than a shrug.
+ if (root.format.trim() === "") defects.push(`${answered.target}/${root.id}: no format`);
+ continue;
+ }
+ if (!isSessionAdapterId(root.adapter)) {
+ defects.push(`${answered.target}/${root.id}: adapter ${root.adapter}`);
+ }
+ }
+ }
+ expect(defects.toSorted().join("\n")).toBe("");
+ });
+
+ test("the answer follows the injected environment, not this machine", () => {
+ const relocated = sessionPathsFor("codex", envFor({ CODEX_HOME: "/mnt/elsewhere/codex" }));
+ expect(relocated).not.toBeNull();
+ expect(relocated!.roots.map((r) => r.path)).toEqual([
+ "/mnt/elsewhere/codex/sessions",
+ "/mnt/elsewhere/codex/session",
+ "/mnt/elsewhere/codex/history",
+ "/mnt/elsewhere/codex/.tmp",
+ ]);
+ });
+
+ test("cursor answers the runtime whose logs no adapter in this build reads", () => {
+ const cursor = sessionPathsFor("cursor", envFor());
+ expect(cursor).not.toBeNull();
+ expect(cursor!.runtime).toBe(SESSION_RUNTIME_ID.cursor);
+ expect(cursor!.roots.every((r) => r.adapter === null)).toBe(true);
+ expect([...new Set(cursor!.roots.map((r) => r.format))]).toEqual(["cursor-state-vscdb"]);
+ });
+
+ test("the row's declared session runtime and its declared roots agree", () => {
+ // Two fields could disagree, and the comparison has to be BETWEEN
+ // them: a row naming `grok` while carrying Cursor's roots would make
+ // the discovery join silently wrong - a sweep keyed on the runtime id
+ // would attribute Cursor's `state.vscdb` files to grok - and the
+ // shapes match, so nothing about the types objects to it. Counting
+ // roots against runtime-is-not-null could not see it: both sides stay
+ // true. The row's roots must BE the entry its declared runtime names,
+ // by identity, because `SESSION_ROOTS` is the one declaration and a
+ // row that copied the array instead of pointing at it is a second one.
+ const drifted: string[] = [];
+ for (const row of Object.values(RUNTIME_FACTS)) {
+ if (row.sessionRuntime === null) {
+ if (row.sessionRoots.length > 0) {
+ drifted.push(`${row.target}: ${row.sessionRoots.length} roots but no session runtime`);
+ }
+ continue;
+ }
+ const declared = SESSION_ROOTS[row.sessionRuntime];
+ if (row.sessionRoots !== declared) {
+ drifted.push(
+ `${row.target}: sessionRoots are not SESSION_ROOTS[${row.sessionRuntime}] ` +
+ `(ids ${row.sessionRoots.map((r) => r.id).join(",")} vs ` +
+ `${declared.map((r) => r.id).join(",")})`,
+ );
+ }
+ if (row.sessionRoots.length === 0) {
+ drifted.push(`${row.target}: names runtime ${row.sessionRuntime} and declares no roots`);
+ }
+ }
+ expect(drifted.toSorted().join("\n")).toBe("");
+ });
+});
diff --git a/tests/core/install/tool-ceiling.test.ts b/tests/core/install/tool-ceiling.test.ts
new file mode 100644
index 00000000..79b0e501
--- /dev/null
+++ b/tests/core/install/tool-ceiling.test.ts
@@ -0,0 +1,407 @@
+/**
+ * A capped host selects a bounded profile.
+ *
+ * Cursor publishes a per-workspace ceiling of forty tools across all
+ * enabled MCP servers; the full surface advertises a hundred and ten.
+ * Before this unit the adapter wrote the full surface anyway and the
+ * host silently dropped the excess - no error, no note, and no row in
+ * `second_brain_capabilities` naming which tools went missing or why.
+ *
+ * Three things are pinned here, and each one is pinned in the way that
+ * makes it hard to pass by accident:
+ *
+ * - The census over `RUNTIME_FACTS` is DERIVED, not hand-listed, and
+ * its pinned counts are an EQUALITY. A future row that declares a
+ * ceiling has no way to skip the check, and a tool added to a
+ * bounded profile moves the advertised count off its pin rather
+ * than quietly creeping back over the host's limit.
+ * - The advertised count is computed the way the SERVER computes it -
+ * `buildToolTable` under the resolved surface, then
+ * `evaluateToolCapabilities`, then the `hidden` filter `tools/list`
+ * applies - so it is what a host actually sees, not what is
+ * registered. Those two numbers differ by a hundred and three under
+ * `catalog`, which is the whole reason the profile fits.
+ * - `unknown` is visible. A host whose limit nobody has published gets
+ * no profile - that is today's behaviour and it is correct - but the
+ * capability report says the ceiling is unchecked and repeats the
+ * written reason, because silence is what let the original defect
+ * survive.
+ * - The flag the payload bakes in is the flag the CLI PARSES. Every
+ * expectation here spells it with the constant, so the constant alone
+ * is no evidence: the last block runs `o2b` on the argv the adapter
+ * writes and reads the surface back off the probe.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Writable } from "node:stream";
+
+import { runCli } from "../../helpers/run-cli.ts";
+import { brainConfigPath } from "../../../src/core/brain/paths.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+import { cursorAdapter } from "../../../src/core/install/adapters/cursor.ts";
+import { buildPayload } from "../../../src/core/install/payload.ts";
+import {
+ carriesHostDimensions,
+ HOST_TARGET_FLAG,
+ TOOL_PROFILE_FLAG,
+ payloadForHost,
+} from "../../../src/core/install/payload-host.ts";
+import {
+ INSTALL_TOOL_PROFILE_CONFIG_KEY,
+ resolveInstallToolProfile,
+} from "../../../src/core/install/settings.ts";
+import type { InstallEnv } from "../../../src/core/install/types.ts";
+import {
+ INSTALL_TARGET_IDS,
+ RUNTIME_FACTS,
+ TOOL_CEILING_KIND,
+ type InstallTargetId,
+} from "../../../src/core/runtime/host-facts.ts";
+import { CONFIG_ORIGIN } from "../../../src/core/validate.ts";
+import { evaluateToolCapabilities } from "../../../src/mcp/capabilities.ts";
+import { resolveToolSurface } from "../../../src/mcp/profiles.ts";
+import { buildToolTable } from "../../../src/mcp/tools.ts";
+
+let vault: string;
+let home: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "osb-ceiling-v-"));
+ home = mkdtempSync(join(tmpdir(), "osb-ceiling-h-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(home, { recursive: true, force: true });
+});
+
+function makeEnv(overrides: Record<string, string> = {}): InstallEnv {
+ return {
+ vault,
+ home,
+ cwd: home,
+ env: { VAULT_AGENT_NAME: "claude-vps", VAULT_TIMEZONE: "UTC", ...overrides },
+ now: new Date("2026-08-16T12:00:00.000Z"),
+ };
+}
+
+function makePayload() {
+ return buildPayload({ vault, agent_name: "claude-vps", timezone: "UTC" });
+}
+
+/**
+ * What a host LISTS under one profile: the server's own surface build
+ * (`src/mcp/server.ts`) followed by the `hidden` filter its
+ * `tools/list` handler applies.
+ */
+function advertisedToolCount(profileName: string): number {
+ const surface = resolveToolSurface({ profileName });
+ const evaluated = evaluateToolCapabilities(buildToolTable(surface.scope), {
+ scope: surface.scope,
+ serverName: "open-second-brain",
+ ...(surface.window ? { window: surface.window } : {}),
+ });
+ return evaluated.tools.filter((tool) => tool.hidden !== true).length;
+}
+
+/**
+ * The advertised count each ceiling-bearing host's resolved profile
+ * produces today, as an EQUALITY per target.
+ *
+ * A floor would let a tool added to `catalog` walk the surface back
+ * toward the ceiling without failing anything until it crossed. The key
+ * set is required to equal the derived declared-ceiling population
+ * below, so a new row cannot be added without pinning its number.
+ */
+const PINNED_ADVERTISED_TOOLS: Readonly<Record<string, number>> = Object.freeze({
+ cursor: 7,
+});
+
+/** The targets whose row publishes a number, derived from the table. */
+const DECLARED_CEILING_TARGETS: ReadonlyArray<InstallTargetId> = INSTALL_TARGET_IDS.filter(
+ (target) => RUNTIME_FACTS[target].toolCeiling.kind === TOOL_CEILING_KIND.declared,
+);
+
+/** The targets whose row publishes nothing, derived the same way. */
+const UNKNOWN_CEILING_TARGETS: ReadonlyArray<InstallTargetId> = INSTALL_TARGET_IDS.filter(
+ (target) => RUNTIME_FACTS[target].toolCeiling.kind === TOOL_CEILING_KIND.unknown,
+);
+
+describe("the declared-ceiling census", () => {
+ test("is not vacuous: at least one runtime publishes a limit", () => {
+ expect(DECLARED_CEILING_TARGETS.length).toBeGreaterThan(0);
+ });
+
+ test("every declared ceiling has a pinned advertised count", () => {
+ expect(Object.keys(PINNED_ADVERTISED_TOOLS).toSorted()).toEqual(
+ [...DECLARED_CEILING_TARGETS].toSorted(),
+ );
+ });
+
+ for (const target of DECLARED_CEILING_TARGETS) {
+ test(`${target}: the resolved profile advertises at or under the published limit`, () => {
+ const ceiling = RUNTIME_FACTS[target].toolCeiling;
+ if (ceiling.kind !== TOOL_CEILING_KIND.declared) throw new Error("derivation drifted");
+ const resolved = resolveInstallToolProfile(
+ { vault, configPath: join(home, "config.yaml") },
+ target,
+ );
+ expect(resolved.value).not.toBeNull();
+ const advertised = advertisedToolCount(resolved.value!);
+ expect(advertised).toBe(PINNED_ADVERTISED_TOOLS[target]!);
+ expect(advertised).toBeLessThanOrEqual(ceiling.maxTools);
+ });
+ }
+});
+
+describe("the profile baked into the generated payload", () => {
+ test("a capped host carries its profile on the full entry", () => {
+ const payload = payloadForHost("cursor", makePayload(), makeEnv());
+ expect(payload.full.args).toEqual([
+ "mcp",
+ "--vault",
+ vault,
+ TOOL_PROFILE_FLAG,
+ "catalog",
+ HOST_TARGET_FLAG,
+ "cursor",
+ ]);
+ });
+
+ test("the writer entry keeps its five-tool surface and takes no profile", () => {
+ const payload = payloadForHost("cursor", makePayload(), makeEnv());
+ expect(payload.writer.args).not.toContain(TOOL_PROFILE_FLAG);
+ expect(payload.writer.args).toEqual([
+ "mcp",
+ "--writer-only",
+ "--vault",
+ vault,
+ HOST_TARGET_FLAG,
+ "cursor",
+ ]);
+ });
+
+ // The three targets that write no MCP command line at all are excluded:
+ // `payloadForHost` refuses them by name rather than pretending to bake a
+ // dimension into a registration they never generate.
+ for (const target of UNKNOWN_CEILING_TARGETS.filter(carriesHostDimensions)) {
+ test(`${target}: an unchecked ceiling bakes in no profile`, () => {
+ const payload = payloadForHost(target, makePayload(), makeEnv());
+ expect(payload.full.args).not.toContain(TOOL_PROFILE_FLAG);
+ expect(payload.writer.args).not.toContain(TOOL_PROFILE_FLAG);
+ });
+ }
+
+ test("a fresh apply reports no drift: verify reconstructs the same args", () => {
+ const payload = makePayload();
+ const env = makeEnv();
+ const opts = {
+ dryRun: false,
+ force: false,
+ stdout: sink(),
+ stderr: sink(),
+ };
+ const plan = cursorAdapter.plan(payload, env);
+ cursorAdapter.apply(plan, payload, env, opts);
+
+ const written = JSON.parse(readFileSync(join(home, ".cursor", "mcp.json"), "utf8")) as {
+ mcpServers: Record<string, { args: string[] }>;
+ };
+ expect(written.mcpServers["open-second-brain"]!.args).toContain("catalog");
+ expect(cursorAdapter.verify(env).status).toBe("ok");
+ });
+});
+
+/**
+ * The generated argv, handed to the program that has to read it.
+ *
+ * `payload-host.ts` names the flags and `src/cli/main.ts` parses them, and
+ * until this block nothing held the two together: every expectation above
+ * spells the flag with {@link TOOL_PROFILE_FLAG}, so renaming the constant
+ * renamed the expectation with it and left the suite green while every
+ * Cursor install reverted from the seven-tool surface to the hundred-and-
+ * ten-tool one - the exact defect the file exists to prevent.
+ *
+ * Running the CLI closes it from both sides. An argument the parser does
+ * not know is a usage error, so a renamed flag fails on the exit code; a
+ * flag accepted and then ignored would still start the full surface, so it
+ * fails on the advertised count. The probe is the same code path the
+ * server's `tools/list` runs, which is why the number is comparable to the
+ * pin above.
+ */
+describe("the generated registration is an argv this CLI accepts", () => {
+ interface ProbeJson {
+ readonly server_name: string;
+ readonly capabilities: {
+ readonly advertised_tool_count: number;
+ readonly host_ceiling: { readonly target: string | null };
+ };
+ }
+
+ async function probe(args: ReadonlyArray<string>): Promise<ProbeJson> {
+ const res = await runCli([...args, "--probe", "--json"], { env: { VAULT_DIR: vault } });
+ expect(`exit ${res.returncode}\n${res.stderr}`).toBe("exit 0\n");
+ return JSON.parse(res.stdout) as ProbeJson;
+ }
+
+ test("the full entry's args select the bounded surface the pin names", async () => {
+ const args = payloadForHost("cursor", makePayload(), makeEnv()).full.args;
+ const answered = await probe(args);
+ expect(answered.server_name).toBe("open-second-brain");
+ expect(answered.capabilities.advertised_tool_count).toBe(PINNED_ADVERTISED_TOOLS["cursor"]!);
+ expect(answered.capabilities.host_ceiling.target).toBe("cursor");
+ });
+
+ test("the writer entry's args are accepted too, and name the same host", async () => {
+ const args = payloadForHost("cursor", makePayload(), makeEnv()).writer.args;
+ const answered = await probe(args);
+ expect(answered.server_name).toBe("open-second-brain-writer");
+ expect(answered.capabilities.host_ceiling.target).toBe("cursor");
+ });
+});
+
+describe("tool-profile precedence, three layers, highest first", () => {
+ function source() {
+ return { vault, configPath: join(home, "config.yaml") };
+ }
+
+ test("the committed vault block beats the host row", () => {
+ atomicWriteFileSync(
+ brainConfigPath(vault),
+ 'schema_version: 1\ninstall:\n tool_profile: "recall"\n',
+ );
+ expect(resolveInstallToolProfile(source(), "cursor")).toEqual({
+ value: "recall",
+ origin: CONFIG_ORIGIN.vaultConfig,
+ });
+ });
+
+ test("the machine-local key beats the host row when the vault says nothing", () => {
+ atomicWriteFileSync(join(home, "config.yaml"), `${INSTALL_TOOL_PROFILE_CONFIG_KEY}: minimal\n`);
+ expect(resolveInstallToolProfile(source(), "cursor")).toEqual({
+ value: "minimal",
+ origin: CONFIG_ORIGIN.userConfig,
+ });
+ });
+
+ test("the host row answers when nothing else does", () => {
+ expect(resolveInstallToolProfile(source(), "cursor")).toEqual({
+ value: "catalog",
+ origin: CONFIG_ORIGIN.default,
+ });
+ });
+
+ test("a host with no declared profile resolves to no profile at all", () => {
+ expect(resolveInstallToolProfile(source(), "kiro")).toEqual({
+ value: null,
+ origin: CONFIG_ORIGIN.default,
+ });
+ });
+});
+
+describe("the capability report states the ceiling it runs under", () => {
+ function report(hostTarget: InstallTargetId | undefined) {
+ const surface = resolveToolSurface({ profileName: "catalog" });
+ return evaluateToolCapabilities(buildToolTable(surface.scope), {
+ scope: surface.scope,
+ serverName: "open-second-brain",
+ ...(hostTarget !== undefined ? { hostTarget } : {}),
+ }).report;
+ }
+
+ test("a declared ceiling is reported with its number and its citation", () => {
+ const ceiling = report("cursor").host_ceiling;
+ expect(ceiling.target).toBe("cursor");
+ expect(ceiling.kind).toBe(TOOL_CEILING_KIND.declared);
+ expect(ceiling.max_tools).toBe(40);
+ expect(ceiling.source).toBe((RUNTIME_FACTS.cursor.toolCeiling as { source: string }).source);
+ expect(ceiling.reason).toBeNull();
+ expect(ceiling.within_ceiling).toBe(true);
+ });
+
+ test("an unchecked ceiling is stated, with the written reason, not left silent", () => {
+ const ceiling = report("kiro").host_ceiling;
+ expect(ceiling.kind).toBe(TOOL_CEILING_KIND.unknown);
+ expect(ceiling.max_tools).toBeNull();
+ expect(ceiling.within_ceiling).toBeNull();
+ expect(ceiling.reason).toBe((RUNTIME_FACTS.kiro.toolCeiling as { reason: string }).reason);
+ });
+
+ test("a server nobody named a host for says so instead of inventing one", () => {
+ const ceiling = report(undefined).host_ceiling;
+ expect(ceiling.target).toBeNull();
+ expect(ceiling.kind).toBe(TOOL_CEILING_KIND.unknown);
+ expect(ceiling.reason).toContain(HOST_TARGET_FLAG);
+ });
+
+ test("the advertised count is the one a host lists, not the registered one", () => {
+ const evaluated = report("cursor");
+ expect(evaluated.available_tool_count).toBe(110);
+ expect(evaluated.advertised_tool_count).toBe(7);
+ });
+});
+
+function sink(): NodeJS.WriteStream {
+ return new Writable({
+ write(_chunk, _enc, cb) {
+ cb();
+ },
+ }) as unknown as NodeJS.WriteStream;
+}
+
+/**
+ * The environment does not parameterise a GENERATED registration.
+ *
+ * `OPEN_SECOND_BRAIN_MCP_TOOL_PROFILE` used to outrank every other tier
+ * here, and the ladder is walked twice: once by `payloadForHost` on the
+ * apply path and once by `expectedPayloadFromEnv` on the verify path. A
+ * variable set for the first invocation and absent from the next therefore
+ * made a CORRECT install report drift, and the fix hint it offered would
+ * have rewritten the file to the host row - silently downgrading the
+ * profile the operator had asked for. Every surviving tier is a file, and a
+ * file is still there on the next invocation.
+ */
+describe("an environment variable cannot reach the written payload", () => {
+ const ENV_KEY = "OPEN_SECOND_BRAIN_MCP_TOOL_PROFILE";
+
+ test("apply writes the host row's profile, not the environment's", () => {
+ const env = makeEnv({ [ENV_KEY]: "minimal" });
+ const payload = makePayload();
+ cursorAdapter.apply(cursorAdapter.plan(payload, env), payload, env, {
+ dryRun: false,
+ force: false,
+ stdout: sink(),
+ stderr: sink(),
+ });
+ const written = JSON.parse(readFileSync(join(home, ".cursor", "mcp.json"), "utf8")) as {
+ mcpServers: Record<string, { args: string[] }>;
+ };
+ const args = written.mcpServers["open-second-brain"]!.args;
+ expect(args).toContain("catalog");
+ expect(args).not.toContain("minimal");
+ });
+
+ test("a plain --check after an environment-set apply reports no drift", () => {
+ const withEnv = makeEnv({ [ENV_KEY]: "minimal" });
+ const payload = makePayload();
+ cursorAdapter.apply(cursorAdapter.plan(payload, withEnv), payload, withEnv, {
+ dryRun: false,
+ force: false,
+ stdout: sink(),
+ stderr: sink(),
+ });
+ // The second invocation is the operator running `o2b install --check`
+ // in a shell that never exported the variable.
+ expect(cursorAdapter.verify(makeEnv()).status).toBe("ok");
+ });
+
+ test("the resolver itself ignores the variable", () => {
+ expect(
+ resolveInstallToolProfile({ vault, configPath: join(home, "config.yaml") }, "cursor"),
+ ).toEqual({ value: "catalog", origin: CONFIG_ORIGIN.default });
+ });
+});
diff --git a/tests/core/install/update.test.ts b/tests/core/install/update.test.ts
index 83991ac2..b2d501d4 100644
--- a/tests/core/install/update.test.ts
+++ b/tests/core/install/update.test.ts
@@ -3,6 +3,8 @@ import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
+import { brainConfigPath } from "../../../src/core/brain/paths.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { runUpdate } from "../../../src/core/install/update.ts";
import { createRegistry } from "../../../src/core/install/registry.ts";
import { readManifest } from "../../../src/core/install/manifest.ts";
@@ -14,6 +16,7 @@ import type {
ApplyResult,
VerifyResult,
} from "../../../src/core/install/types.ts";
+import type { InstallTargetId } from "../../../src/core/runtime/host-facts.ts";
let vault: string;
let home: string;
@@ -39,12 +42,17 @@ function makeEnv(): InstallEnv {
}
function fakeAdapter(
- target: string,
+ target: InstallTargetId,
status: "installed" | "not-installed" = "installed",
): InstallAdapter {
return {
target,
label: target,
+ // The seam is required on every adapter; a double that answers
+ // `null` is a runtime with no session store, which is what a double is.
+ sessionPaths(): null {
+ return null;
+ },
detect(): DetectResult {
return { target, status, configPath: `/tmp/${target}-config`, notes: [] };
},
@@ -87,21 +95,21 @@ describe("runUpdate", () => {
test("applies when no previous manifest exists", () => {
const reg = createRegistry();
- reg.register(fakeAdapter("claudecode"));
+ reg.register(fakeAdapter("cursor"));
const result = runUpdate(reg, makeEnv(), { dryRun: false, force: false, target: null });
expect(result.targets[0]!.status).toBe("applied");
});
test("dry-run reports would-apply without applying", () => {
const reg = createRegistry();
- reg.register(fakeAdapter("claudecode"));
+ reg.register(fakeAdapter("cursor"));
const result = runUpdate(reg, makeEnv(), { dryRun: true, force: false, target: null });
expect(result.targets[0]!.status).toBe("would-apply");
});
test("skips when payload hash is unchanged", () => {
const reg = createRegistry();
- reg.register(fakeAdapter("claudecode"));
+ reg.register(fakeAdapter("cursor"));
const env = makeEnv();
const first = runUpdate(reg, env, { dryRun: false, force: false, target: null });
@@ -114,7 +122,7 @@ describe("runUpdate", () => {
test("--force bypasses hash-skip", () => {
const reg = createRegistry();
- reg.register(fakeAdapter("claudecode"));
+ reg.register(fakeAdapter("cursor"));
const env = makeEnv();
const first = runUpdate(reg, env, { dryRun: false, force: false, target: null });
@@ -124,15 +132,58 @@ describe("runUpdate", () => {
expect(forced.targets[0]!.status).toBe("applied");
});
+ test("a changed tool profile is not 'payload unchanged'", () => {
+ // The hash used to be taken over the CANONICAL payload - vault, agent
+ // name, timezone - and the host dimensions (`--tool-profile`,
+ // `--host-target`) are added afterwards, by `payloadForHost`, which
+ // `runUpdate` never called. So an operator who changed
+ // `install.tool_profile` in the committed `_brain.yaml` got
+ // "up-to-date, payload unchanged" from `o2b update` while
+ // `o2b install --check` reported drift on the same target, and a
+ // 110-tool registration stayed under Cursor's 40-tool ceiling.
+ const reg = createRegistry();
+ reg.register(fakeAdapter("cursor"));
+ const env = makeEnv();
+
+ expect(
+ runUpdate(reg, env, { dryRun: false, force: false, target: null }).targets[0]!.status,
+ ).toBe("applied");
+ expect(
+ runUpdate(reg, env, { dryRun: false, force: false, target: null }).targets[0]!.status,
+ ).toBe("up-to-date");
+
+ atomicWriteFileSync(
+ brainConfigPath(vault),
+ 'schema_version: 1\ninstall:\n tool_profile: "minimal"\n',
+ );
+ const after = runUpdate(reg, env, { dryRun: false, force: false, target: null });
+ expect(`${after.targets[0]!.status}: ${after.targets[0]!.reason ?? ""}`).toBe("applied: ");
+ });
+
+ test("an unreadable _brain.yaml is an error on that target, not a crash", () => {
+ // The settings ladder REFUSES an unparsable vault config rather than
+ // regenerating a default. `runUpdate` reports it per target, so the
+ // other targets in the same run still get their status.
+ const reg = createRegistry();
+ reg.register(fakeAdapter("cursor"));
+ atomicWriteFileSync(
+ brainConfigPath(vault),
+ "schema_version: 1\ninstall:\n tool_profile: [x\n",
+ );
+ const result = runUpdate(reg, makeEnv(), { dryRun: false, force: false, target: null });
+ expect(result.targets[0]!.status).toBe("error");
+ expect(result.targets[0]!.error ?? "").toContain(brainConfigPath(vault));
+ });
+
test("payload_hash stored in install.lock.json after apply", () => {
const reg = createRegistry();
- reg.register(fakeAdapter("claudecode"));
+ reg.register(fakeAdapter("cursor"));
const env = makeEnv();
runUpdate(reg, env, { dryRun: false, force: false, target: null });
const manifest = readManifest(env.vault);
- const entry = manifest.installs["claudecode"];
+ const entry = manifest.installs["cursor"];
expect(entry).toBeDefined();
expect(entry!.payload_hash).toBeDefined();
expect(entry!.payload_hash).toMatch(/^[0-9a-f]{64}$/);
diff --git a/tests/core/redactor.test.ts b/tests/core/redactor.test.ts
index 8a91bccc..1b50f44a 100644
--- a/tests/core/redactor.test.ts
+++ b/tests/core/redactor.test.ts
@@ -58,6 +58,50 @@ describe("redactRawOutput (cross-module backward compat)", () => {
});
});
+describe("redactRawOutput env-style assignment under a PREFIXED key name", () => {
+ // `\b` used to stand at the front of this pattern, and `_` is a word
+ // character, so the boundary never fired after one: the two most common
+ // spellings a credential takes in a shell line or an agent transcript
+ // went through untouched while the unprefixed one was caught. What did
+ // come out redacted in the common cases came out through the
+ // vendor-prefix rule on the VALUE, not through this key-name pass.
+ test("a vendor-neutral value under a prefixed key name is redacted", () => {
+ expect(redactRawOutput("export ANTHROPIC_API_KEY=hunter2secretvalue")).toBe(
+ "export ANTHROPIC_API_KEY=***REDACTED***",
+ );
+ expect(redactRawOutput("MY_DB_PASSWORD=letmein12345")).toBe("MY_DB_PASSWORD=***REDACTED***");
+ expect(redactRawOutput("SERVICE-ACCESS-TOKEN=plainish9value")).toBe(
+ "SERVICE-ACCESS-TOKEN=***REDACTED***",
+ );
+ });
+
+ test("the unprefixed spelling is still redacted", () => {
+ expect(redactRawOutput("export API_KEY=hunter2secretvalue")).toBe(
+ "export API_KEY=***REDACTED***",
+ );
+ });
+
+ test("the prefix is kept, so the line still says which variable it was", () => {
+ expect(redactRawOutput("export ANTHROPIC_API_KEY=hunter2secretvalue")).toContain("ANTHROPIC_");
+ });
+
+ test("a near miss keeps its value: the key must END at the assignment", () => {
+ // `token` here is followed by `s`, not by `=`. A widened boundary that
+ // fired anyway would eat the value of an ordinary CLI flag - and the
+ // point of the boundary is that it separates a credential's NAME from
+ // a word that merely contains one.
+ expect(redactRawOutput("claude --max-tokens=4096")).toBe("claude --max-tokens=4096");
+ expect(redactRawOutput("TOKENS_PER_MINUTE=90000")).toBe("TOKENS_PER_MINUTE=90000");
+ });
+
+ test("a near miss keeps its value: the key must START at a separator", () => {
+ // Mid-identifier with no `_` or `-` in front of it is the same
+ // under-match `\b` already had, left in place deliberately rather than
+ // widened into every word ending in a secret name.
+ expect(redactRawOutput("MYTOKEN=plainish9value")).toBe("MYTOKEN=plainish9value");
+ });
+});
+
describe("redactRawOutput fail-closed truncation", () => {
test("appends the scan-truncated marker when input exceeds maxInput", () => {
const out = redactRawOutput("x".repeat(100), { maxInput: 10 });
diff --git a/tests/core/runtime/host-facts.test.ts b/tests/core/runtime/host-facts.test.ts
new file mode 100644
index 00000000..1d5d1d16
--- /dev/null
+++ b/tests/core/runtime/host-facts.test.ts
@@ -0,0 +1,459 @@
+/**
+ * What the machine already has, asserted rather than assumed.
+ *
+ * `RUNTIME_FACTS` is a declaration file: nine rows of things this build
+ * claims to know about the runtimes it installs into. A declaration that
+ * nothing checks is a comment, so this file checks the three properties
+ * the rows are read for.
+ *
+ * 1. `unknown` is not `unbounded`. A row whose ceiling was never checked
+ * carries a reason and can never be read as "no limit" - that collapse
+ * is the fail-open profile selection the whole unit exists to prevent.
+ * 2. Every cross-reference resolves: a declared tool profile is a real
+ * `TOOL_SURFACE_PROFILES` key, a declared session adapter is a real
+ * `SESSION_ADAPTER_ID` member. Both are held by a test rather than by
+ * the type system on purpose - the module is a LEAF, and importing the
+ * MCP profile table into it would close the cycle the architecture
+ * ratchet gates.
+ * 3. Root derivation is pure. The roots are functions of an injected home
+ * and an injected environment map, exactly as `InstallEnv` already is,
+ * so a caller can ask where opencode's spool would be on a machine
+ * that is not this one. A `homedir()` call inside the module would
+ * make that unanswerable, so the last block reads the source and
+ * refuses it by name.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { isSessionAdapterId, SESSION_ADAPTER_ID } from "../../../src/core/brain/sessions/types.ts";
+import {
+ INSTALL_TARGET_ID,
+ INSTALL_TARGET_IDS,
+ isInstallTargetId,
+ isToolCeilingKind,
+ resolveSessionRoots,
+ runtimeFactsFor,
+ RUNTIME_FACTS,
+ TOOL_CEILING_KIND,
+ TOOL_CEILING_KINDS,
+ type HostContext,
+ type RuntimeFacts,
+} from "../../../src/core/runtime/host-facts.ts";
+import { TOOL_SURFACE_PROFILES } from "../../../src/mcp/profiles.ts";
+
+const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
+const MODULE_PATH = join(REPO_ROOT, "src", "core", "runtime", "host-facts.ts");
+
+/** Strings shaped like plausible drift, not like obvious garbage. */
+const NON_MEMBERS: ReadonlyArray<unknown> = Object.freeze([
+ "",
+ " ",
+ "Cursor",
+ "copilot",
+ "Codex",
+ null,
+ undefined,
+ 42,
+ {},
+]);
+
+/** Two unrelated hosts, so a derivation that ignores its input is visible. */
+const ONE: HostContext = Object.freeze({
+ home: "/home/one",
+ env: Object.freeze({}),
+});
+const TWO: HostContext = Object.freeze({
+ home: "/home/two",
+ env: Object.freeze({
+ GROK_HOME: "/home/two/grok-elsewhere",
+ XDG_DATA_HOME: "/home/two/xdg-data",
+ }),
+});
+
+const ROWS = Object.values(RUNTIME_FACTS);
+
+/**
+ * The bar a citation clears, taken from the sibling census in
+ * `tests/core/architecture/state-surface-census.test.ts`.
+ *
+ * Every check below used to be `.trim() !== ""`, which `reason: "TODO"`
+ * and `source: "for now"` both pass. That is not a pedantic gap here: the
+ * `unknown` reason is the field the fail-open prevention rests on - it is
+ * what `second_brain_capabilities` repeats to say WHY no profile was
+ * selected - and a placeholder in it reaches the operator as the silence
+ * this whole file exists to end.
+ */
+const MIN_CITATION_LENGTH = 80;
+const LAZY_CITATION = /\bTODO\b|\bTBD\b|\bfor now\b|\blater\b|\bn\/a\b/i;
+
+/** Why `text` is not a citation, or `null` when it is one. */
+function citationDefect(text: string): string | null {
+ const trimmed = text.trim();
+ if (trimmed.length < MIN_CITATION_LENGTH) {
+ return `${trimmed.length} chars, under the ${MIN_CITATION_LENGTH} a citation needs`;
+ }
+ if (LAZY_CITATION.test(trimmed)) return "a placeholder, not an argument";
+ return null;
+}
+
+describe("the install-target vocabulary", () => {
+ test("the guard accepts every declared member", () => {
+ const rejected = INSTALL_TARGET_IDS.filter((id) => !isInstallTargetId(id));
+ expect(rejected.join(",")).toBe("");
+ });
+
+ test("the guard rejects non-members and non-strings", () => {
+ const accepted = NON_MEMBERS.filter((value) => isInstallTargetId(value)).map((value) =>
+ JSON.stringify(value),
+ );
+ expect(accepted.join(",")).toBe("");
+ });
+
+ test("the members list and the values object agree", () => {
+ expect([...INSTALL_TARGET_IDS].toSorted()).toEqual(Object.values(INSTALL_TARGET_ID).toSorted());
+ });
+
+ test("codex is a member now that its adapter ships", () => {
+ // The vocabulary is what `--target` is validated against, so a member
+ // is only allowed to exist once the registry can find an adapter for
+ // it - `tests/core/architecture/host-facts-census.test.ts` holds the
+ // two populations equal. Codex was the standing example of the rule
+ // while it had no adapter; it is now the example of the rule met.
+ expect(isInstallTargetId("codex")).toBe(true);
+ expect(runtimeFactsFor(INSTALL_TARGET_ID.codex).sessionAdapter).toBe(SESSION_ADAPTER_ID.codex);
+ });
+});
+
+describe("the tool-ceiling vocabulary", () => {
+ test("it has exactly three members", () => {
+ expect([...TOOL_CEILING_KINDS].toSorted()).toEqual(["declared", "unbounded", "unknown"]);
+ });
+
+ test("the guard accepts every member and rejects everything else", () => {
+ const wrong = [
+ ...TOOL_CEILING_KINDS.filter((kind) => !isToolCeilingKind(kind)),
+ ...NON_MEMBERS.filter((value) => isToolCeilingKind(value)).map((value) =>
+ JSON.stringify(value),
+ ),
+ ];
+ expect(wrong.join(",")).toBe("");
+ });
+
+ test("an unknown ceiling carries a reason and nothing that reads as a limit", () => {
+ const silent: string[] = [];
+ for (const row of ROWS) {
+ if (row.toolCeiling.kind !== TOOL_CEILING_KIND.unknown) continue;
+ const defect = citationDefect(row.toolCeiling.reason);
+ if (defect !== null) silent.push(`${row.target}: ${defect}`);
+ if ("maxTools" in row.toolCeiling) silent.push(`${row.target} carries maxTools`);
+ }
+ expect(silent.join("\n")).toBe("");
+ });
+
+ test("a declared ceiling carries a positive integer and cites where it is published", () => {
+ const defects: string[] = [];
+ for (const row of ROWS) {
+ if (row.toolCeiling.kind !== TOOL_CEILING_KIND.declared) continue;
+ const { maxTools, source } = row.toolCeiling;
+ if (!Number.isSafeInteger(maxTools) || maxTools <= 0) {
+ defects.push(`${row.target}: maxTools ${maxTools}`);
+ }
+ const defect = citationDefect(source);
+ if (defect !== null) defects.push(`${row.target}: source is ${defect}`);
+ }
+ expect(defects.join("\n")).toBe("");
+ });
+
+ test("no row ships an unbounded ceiling today, and that is on purpose", () => {
+ // Stated as an equality rather than left implicit. The filter in the
+ // case below is empty over the live population, so without this line
+ // that case reads as coverage when it is really a guard held in
+ // reserve. The day a host publishes "no limit", this assertion is what
+ // fails first and sends the author to the one below.
+ const unbounded = ROWS.filter(
+ (row) => row.toolCeiling.kind === TOOL_CEILING_KIND.unbounded,
+ ).map((row) => row.target);
+ expect(unbounded.join(",")).toBe("");
+ });
+
+ test("an unbounded ceiling cites where the absence of a limit is published", () => {
+ // Run against a SYNTHETIC row, because no live row uses the member.
+ // The predicate is the same one applied to the live population, so
+ // the guard is proven to bite before it has anything to bite on -
+ // otherwise the first host to declare `unbounded` would be checked by
+ // an assertion nobody had ever seen fail.
+ const sourceless = (rows: ReadonlyArray<RuntimeFacts>): ReadonlyArray<string> =>
+ rows
+ .filter(
+ (row) =>
+ row.toolCeiling.kind === TOOL_CEILING_KIND.unbounded &&
+ citationDefect(row.toolCeiling.source) !== null,
+ )
+ .map((row) => row.target);
+
+ const base = runtimeFactsFor(INSTALL_TARGET_ID.kiro);
+ const silent: RuntimeFacts = {
+ ...base,
+ toolCeiling: { kind: TOOL_CEILING_KIND.unbounded, source: " " },
+ };
+ // Long enough to be a citation but still a placeholder: the length
+ // floor alone would let this one through.
+ const lazy: RuntimeFacts = {
+ ...base,
+ toolCeiling: {
+ kind: TOOL_CEILING_KIND.unbounded,
+ source:
+ "no limit is documented anywhere this build could find, so treat the surface as " +
+ "unbounded for now",
+ },
+ };
+ const sourced: RuntimeFacts = {
+ ...base,
+ toolCeiling: {
+ kind: TOOL_CEILING_KIND.unbounded,
+ source:
+ "the host's own MCP documentation states that it applies no per-workspace tool limit " +
+ "and forwards every registered server's whole surface to the model",
+ },
+ };
+ expect(sourceless([silent]).join(",")).toBe(base.target);
+ expect(sourceless([lazy]).join(",")).toBe(base.target);
+ expect(sourceless([sourced]).join(",")).toBe("");
+ expect(sourceless(ROWS).join(",")).toBe("");
+ });
+
+ test("cursor carries the published 40-tool workspace limit", () => {
+ const ceiling = runtimeFactsFor(INSTALL_TARGET_ID.cursor).toolCeiling;
+ expect(ceiling.kind).toBe(TOOL_CEILING_KIND.declared);
+ expect(ceiling.kind === TOOL_CEILING_KIND.declared ? ceiling.maxTools : 0).toBe(40);
+ });
+});
+
+describe("every row's cross-references resolve", () => {
+ test("a declared tool profile is a real TOOL_SURFACE_PROFILES key", () => {
+ const dangling = ROWS.filter(
+ (row) => row.toolProfile !== null && TOOL_SURFACE_PROFILES[row.toolProfile] === undefined,
+ ).map((row) => `${row.target}: ${row.toolProfile}`);
+ expect(dangling.join("\n")).toBe("");
+ });
+
+ test("a declared session adapter is a real SESSION_ADAPTER_ID member", () => {
+ const dangling = ROWS.filter(
+ (row) => row.sessionAdapter !== null && !isSessionAdapterId(row.sessionAdapter),
+ ).map((row) => `${row.target}: ${row.sessionAdapter}`);
+ expect(dangling.join("\n")).toBe("");
+ });
+
+ test("every row is keyed by its own target id", () => {
+ const mismatched = Object.entries(RUNTIME_FACTS)
+ .filter(([key, row]) => key !== row.target)
+ .map(([key, row]) => `${key} -> ${row.target}`);
+ expect(mismatched.join("\n")).toBe("");
+ });
+
+ test("every row carries a label", () => {
+ expect(ROWS.filter((row) => row.label.trim() === "").map((row) => row.target)).toEqual([]);
+ });
+
+ test("cursor declares the catalog profile and no session adapter", () => {
+ // Cursor's transcripts live in a `state.vscdb` SQLite file and no
+ // session adapter reads that format, so the row says `null` rather
+ // than naming an adapter that would fail on the first file.
+ const cursor = runtimeFactsFor(INSTALL_TARGET_ID.cursor);
+ expect(`${cursor.toolProfile} ${cursor.sessionAdapter}`).toBe("catalog null");
+ });
+
+ test("grok and opencode name the adapters that actually parse their logs", () => {
+ expect(runtimeFactsFor(INSTALL_TARGET_ID.grok).sessionAdapter).toBe(SESSION_ADAPTER_ID.grok);
+ expect(runtimeFactsFor(INSTALL_TARGET_ID.opencode).sessionAdapter).toBe(
+ SESSION_ADAPTER_ID.opencode,
+ );
+ });
+});
+
+describe("session roots", () => {
+ test("every root names a glob and the format its files are in", () => {
+ const defects: string[] = [];
+ for (const row of ROWS) {
+ for (const root of row.sessionRoots) {
+ if (root.id.trim() === "") defects.push(`${row.target}: a root with no id`);
+ if (root.glob.trim() === "") defects.push(`${row.target}/${root.id}: no glob`);
+ if (root.format.trim() === "") defects.push(`${row.target}/${root.id}: no format`);
+ if (root.adapter !== null && !isSessionAdapterId(root.adapter)) {
+ defects.push(`${row.target}/${root.id}: adapter ${root.adapter}`);
+ }
+ }
+ }
+ expect(defects.join("\n")).toBe("");
+ });
+
+ test("root ids are unique within a row", () => {
+ const duplicated: string[] = [];
+ for (const row of ROWS) {
+ const seen = new Set<string>();
+ for (const root of row.sessionRoots) {
+ if (seen.has(root.id)) duplicated.push(`${row.target}: ${root.id}`);
+ seen.add(root.id);
+ }
+ }
+ expect(duplicated.join("\n")).toBe("");
+ });
+
+ test("a row with no session adapter and no non-adapter format declares no roots", () => {
+ // aider, pi, copilot-cli, gemini-cli, kiro and generic store no
+ // transcripts this build can name. An empty list is the stated answer;
+ // a root pointing at a directory that never exists would make
+ // discovery report a miss instead of an absence.
+ //
+ // DERIVED from the predicate the title states, not hand-listed. The
+ // list was `[aider, pi, generic]` while the predicate held for twice
+ // that many rows, so inventing a root for `kiro` changed nothing here
+ // - the very drift this case is the guard against.
+ const quiet = INSTALL_TARGET_IDS.filter(
+ (target) =>
+ runtimeFactsFor(target).sessionAdapter === null &&
+ runtimeFactsFor(target).sessionRuntime === null,
+ );
+ // Both sides non-empty, or the filter is doing the asserting.
+ expect(`quiet ${quiet.length > 0}, loud ${quiet.length < INSTALL_TARGET_IDS.length}`).toBe(
+ "quiet true, loud true",
+ );
+ const noisy = quiet.filter(
+ (target) =>
+ runtimeFactsFor(target).sessionRoots.length > 0 ||
+ resolveSessionRoots(target, ONE).length > 0,
+ );
+ expect(noisy.join(",")).toBe("");
+ });
+
+ test("derivation is a pure function of the injected home and environment", () => {
+ const first = ROWS.map((row) => resolveSessionRoots(row.target, ONE));
+ const again = ROWS.map((row) => resolveSessionRoots(row.target, ONE));
+ expect(JSON.stringify(again)).toBe(JSON.stringify(first));
+ });
+
+ test("derivation does not read the real process environment", () => {
+ const key = "GROK_HOME";
+ const saved = process.env[key];
+ process.env[key] = "/tmp/host-facts-must-not-read-this";
+ try {
+ const roots = resolveSessionRoots(INSTALL_TARGET_ID.grok, ONE);
+ expect(roots.map((root) => root.path).join("\n")).not.toContain(
+ "host-facts-must-not-read-this",
+ );
+ } finally {
+ if (saved === undefined) delete process.env[key];
+ else process.env[key] = saved;
+ }
+ });
+
+ test("a different home and environment give different roots", () => {
+ const one = resolveSessionRoots(INSTALL_TARGET_ID.grok, ONE);
+ const two = resolveSessionRoots(INSTALL_TARGET_ID.grok, TWO);
+ expect(one.map((root) => root.path)).toEqual([join("/home/one", ".grok", "sessions")]);
+ expect(two.map((root) => root.path)).toEqual([join("/home/two/grok-elsewhere", "sessions")]);
+ });
+
+ test("the opencode spool honours XDG_DATA_HOME and falls back to ~/.local/share", () => {
+ expect(resolveSessionRoots(INSTALL_TARGET_ID.opencode, ONE).map((r) => r.path)).toEqual([
+ join("/home/one", ".local", "share", "open-second-brain", "opencode"),
+ ]);
+ expect(resolveSessionRoots(INSTALL_TARGET_ID.opencode, TWO).map((r) => r.path)).toEqual([
+ join("/home/two/xdg-data", "open-second-brain", "opencode"),
+ ]);
+ });
+
+ test("the cursor roots are the three layouts the transcript scanner already probes", () => {
+ expect(resolveSessionRoots(INSTALL_TARGET_ID.cursor, ONE).map((r) => r.path)).toEqual([
+ join("/home/one", ".config", "Cursor", "User", "workspaceStorage"),
+ join("/home/one", "Library", "Application Support", "Cursor", "User", "workspaceStorage"),
+ join("/home/one", ".cursor", "workspaceStorage"),
+ ]);
+ });
+
+ test("the codex roots are the four subdirectories the scanner walks, under CODEX_HOME", () => {
+ // `src/core/discipline/transcripts/codex.ts` probes exactly these
+ // four because the CLI has moved its transcripts between releases.
+ expect(resolveSessionRoots(INSTALL_TARGET_ID.codex, ONE).map((r) => r.path)).toEqual([
+ join("/home/one", ".codex", "sessions"),
+ join("/home/one", ".codex", "session"),
+ join("/home/one", ".codex", "history"),
+ join("/home/one", ".codex", ".tmp"),
+ ]);
+ const relocated: HostContext = {
+ home: "/home/two",
+ env: { CODEX_HOME: "/home/two/codex-elsewhere" },
+ };
+ expect(resolveSessionRoots(INSTALL_TARGET_ID.codex, relocated).map((r) => r.path)).toEqual([
+ join("/home/two/codex-elsewhere", "sessions"),
+ join("/home/two/codex-elsewhere", "session"),
+ join("/home/two/codex-elsewhere", "history"),
+ join("/home/two/codex-elsewhere", ".tmp"),
+ ]);
+ });
+
+ test("a resolved cursor root reports the SQLite format and no adapter", () => {
+ const [first] = resolveSessionRoots(INSTALL_TARGET_ID.cursor, ONE);
+ expect(`${first?.adapter} ${first?.format}`).toBe("null cursor-state-vscdb");
+ });
+});
+
+describe("host probes", () => {
+ test("a declared probe names a binary and an argv", () => {
+ const defects: string[] = [];
+ for (const row of ROWS) {
+ const probe = row.hostProbe;
+ if (probe === null) continue;
+ if (probe.bin.trim() === "") defects.push(`${row.target}: no binary`);
+ if (probe.argv.length === 0) defects.push(`${row.target}: empty argv`);
+ // `answers` is what `--friction` prints as the probe's evidence
+ // cell, so a placeholder there is a blank column on the operator's
+ // screen rather than a missing string in a table.
+ const defect = citationDefect(probe.answers);
+ if (defect !== null) defects.push(`${row.target}: answers is ${defect}`);
+ }
+ expect(defects.join("\n")).toBe("");
+ });
+
+ test("copilot-cli declares the registration probe it already runs", () => {
+ const probe = runtimeFactsFor(INSTALL_TARGET_ID.copilotCli).hostProbe;
+ expect(`${probe?.bin} ${probe?.argv.join(" ")}`).toBe("copilot mcp list");
+ });
+
+ test("codex declares the plain-text registration probe, not the JSON one", () => {
+ // The shared probe reads the first whitespace-delimited token of each
+ // output line, which is the name column of `codex mcp list`. Under
+ // `--json` that token is `"name":` on every host, so a JSON probe
+ // would answer "nothing registered" everywhere.
+ const probe = runtimeFactsFor(INSTALL_TARGET_ID.codex).hostProbe;
+ expect(`${probe?.bin} ${probe?.argv.join(" ")}`).toBe("codex mcp list");
+ });
+
+ test("a target with no probe declares null rather than an empty command", () => {
+ expect(runtimeFactsFor(INSTALL_TARGET_ID.cursor).hostProbe).toBeNull();
+ });
+});
+
+describe("the module stays a leaf that reads nothing", () => {
+ const source = readFileSync(MODULE_PATH, "utf8");
+
+ test("it never resolves a home directory or an environment of its own", () => {
+ // The whole point of taking `{home, env}`: the caller supplies them,
+ // exactly as `InstallEnv` does, so the same row answers for a machine
+ // that is not this one.
+ const forbidden = ["homedir(", "process.env"].filter((token) => source.includes(token));
+ expect(forbidden.join(",")).toBe("");
+ });
+
+ test("it imports nothing from the install subsystem", () => {
+ // Importing it back from the install aggregator would close a cycle
+ // `tests/core/architecture/import-cycles.test.ts` gates. Relative
+ // specifiers only - that is the edge set that ratchet builds its
+ // graph from.
+ expect([...source.matchAll(/from\s+"(\.[^"]+)"/g)].map((m) => m[1]!)).toEqual([
+ "../brain/sessions/types.ts",
+ ]);
+ });
+});
diff --git a/tests/core/state/migrate.test.ts b/tests/core/state/migrate.test.ts
new file mode 100644
index 00000000..2518c1da
--- /dev/null
+++ b/tests/core/state/migrate.test.ts
@@ -0,0 +1,762 @@
+/**
+ * Moving a vault's state, and putting it back.
+ *
+ * The unit under test is the one operation in this project where a
+ * half-completed run is worse than no run at all: bytes that exist in
+ * neither the old place nor the new one are gone, and the surfaces the
+ * inventory calls `vault-content` do not rebuild. So the tests below are
+ * organised around the two guarantees that follow from that, rather than
+ * around the functions:
+ *
+ * - FAIL BEFORE COMMIT. Every refusal is driven with the source tree
+ * otherwise perfectly movable, and each one drives `applyStateMigration`
+ * and asserts that NOTHING moved - not that the call threw. A plan
+ * that reported a refusal and still copied half a tree would pass a
+ * throw-shaped assertion. Three of the seven used to stop at the
+ * plan: `reserved_namespace`, the unreadable-lock case and
+ * `unreadable_surface` never called apply at all, so their
+ * `expect(existsSync(dest)).toBe(false)` was true of a destination
+ * nothing had ever been asked to write.
+ * - PUT BACK ONLY WHAT IS STILL THE SAME. The rollback tests change a
+ * migrated file behind the tool's back and assert it is named,
+ * refused, and STILL THERE afterwards. Deleting a file the operator
+ * edited after the migration is the failure this half exists to
+ * prevent, and it is invisible to a test that only checks the exit
+ * code.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+ chmodSync,
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ readdirSync,
+ renameSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { canonicalJson, sha256Hex } from "../../../src/core/integrity/digest.ts";
+import {
+ applyStateMigration,
+ applyStateRollback,
+ MIGRATION_MANIFEST_FILE,
+ MIGRATION_REFUSAL,
+ MIGRATION_SOURCE_TYPE,
+ planStateMigration,
+ planStateRollback,
+ renderRollbackPlan,
+ ROLLBACK_REFUSAL,
+ StateMigrationError,
+ type MigrationPlan,
+} from "../../../src/core/state/migrate.ts";
+import { STATE_SURFACE_ID, STATE_SURFACES } from "../../../src/core/state/surfaces.ts";
+
+const temps: string[] = [];
+
+afterEach(() => {
+ while (temps.length > 0) rmSync(temps.pop()!, { recursive: true, force: true });
+});
+
+function tempDir(): string {
+ const dir = mkdtempSync(join(tmpdir(), "osb-state-migrate-"));
+ temps.push(dir);
+ return dir;
+}
+
+function write(path: string, body: string): void {
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, body);
+}
+
+/** The resolved location of one declared surface in `vault`, no overrides. */
+function surfacePath(vault: string, id: string): string {
+ const surface = STATE_SURFACES.find((s) => s.id === id);
+ if (surface === undefined) throw new Error(`no such surface: ${id}`);
+ return surface.derive(vault, null);
+}
+
+/**
+ * A vault with real bytes under both roots, including one surface nested
+ * inside another so the canonical-root collapse is exercised by default
+ * rather than by a test that has to remember to arrange it.
+ */
+function seedVault(): string {
+ const vault = tempDir();
+ write(surfacePath(vault, STATE_SURFACE_ID.searchIndex), "index-bytes");
+ write(surfacePath(vault, STATE_SURFACE_ID.ingestContentManifest), "{}\n");
+ write(join(surfacePath(vault, STATE_SURFACE_ID.brainLog), "2026-08-16.md"), "# today\n");
+ write(join(surfacePath(vault, STATE_SURFACE_ID.dreamRuns), "run-1.jsonl"), "{}\n");
+ write(join(surfacePath(vault, STATE_SURFACE_ID.metrics), "recall.jsonl"), "{}\n");
+ return vault;
+}
+
+function plan(
+ vault: string,
+ destination: string,
+ extra: Record<string, unknown> = {},
+): MigrationPlan {
+ return planStateMigration({
+ vault,
+ destination,
+ env: {},
+ config: {},
+ now: new Date("2026-08-16T10:00:00.000Z"),
+ ...extra,
+ });
+}
+
+/** Every file under `root`, as vault-relative paths. */
+function tree(root: string): string[] {
+ const out: string[] = [];
+ const walk = (dir: string, prefix: string): void => {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+ if (entry.isDirectory()) walk(join(dir, entry.name), rel);
+ else out.push(rel);
+ }
+ };
+ if (existsSync(root)) walk(root, "");
+ return out.toSorted();
+}
+
+function refusalCodes(p: MigrationPlan): string[] {
+ return p.refusals.map((r) => r.code).toSorted();
+}
+
+/**
+ * The bar a remedy has to clear.
+ *
+ * It was `remedy.length > 20`, applied to one of the seven refusal codes,
+ * and `"TODO: fix this later!!"` is twenty-two characters. A remedy is
+ * the sentence that turns a refusal into something the operator can act
+ * on; the shortest real one in this module - "name an empty directory, or
+ * a path that does not exist yet" - is fifty-seven.
+ */
+const MIN_REMEDY_LENGTH = 50;
+
+/** Words that mean nobody has decided yet, which is not a remedy. */
+const LAZY_REMEDY_RE = /\bTODO\b|\bfor now\b|\blater\b/i;
+
+/** Every refusal in `refusals` says what to DO, named when one does not. */
+function expectActionableRemedies(
+ refusals: ReadonlyArray<{ readonly code: string; readonly remedy: string }>,
+): void {
+ // Folded into one expectation whose value NAMES the offender: asserting
+ // per refusal would stop at the first and hide the rest.
+ const thin = refusals
+ .filter((r) => r.remedy.trim().length < MIN_REMEDY_LENGTH || LAZY_REMEDY_RE.test(r.remedy))
+ .map((r) => `${r.code}: ${r.remedy.trim()}`);
+ expect(thin.toSorted().join("\n")).toBe("");
+}
+
+describe("state migration plan", () => {
+ test("inventories every file under both roots with its byte count and digest", () => {
+ const vault = seedVault();
+ const p = plan(vault, join(tempDir(), "moved"));
+
+ expect(p.refusals).toEqual([]);
+ expect(p.manifest.source_type).toBe(MIGRATION_SOURCE_TYPE.vault);
+ expect(p.manifest.entries.map((e) => e.relative_path)).toEqual([
+ ".open-second-brain/brain.sqlite",
+ ".open-second-brain/ingest-manifest.json",
+ "Brain/log/2026-08-16.md",
+ "Brain/log/dream-runs/run-1.jsonl",
+ "Brain/metrics/recall.jsonl",
+ ]);
+ const index = p.manifest.entries.find(
+ (e) => e.relative_path === ".open-second-brain/brain.sqlite",
+ );
+ expect(index?.bytes).toBe("index-bytes".length);
+ expect(index?.digest).toBe(sha256Hex("index-bytes"));
+ expect(p.manifest.total_bytes).toBe(p.manifest.entries.reduce((sum, e) => sum + e.bytes, 0));
+ });
+
+ test("collapses a nested surface into the canonical root that contains it", () => {
+ const vault = seedVault();
+ const p = plan(vault, join(tempDir(), "moved"));
+ // A root is a DECLARED surface, never its parent directory: the two
+ // files under the derived store are two surfaces and stay two roots,
+ // so nothing undeclared beside them is swept along. `Brain/log/dream-
+ // runs` IS declared and IS under `Brain/log`, so it is absorbed;
+ // without the collapse its files would be bound twice.
+ expect(p.manifest.canonical_roots).toEqual([
+ ".open-second-brain/brain.sqlite",
+ ".open-second-brain/ingest-manifest.json",
+ "Brain/log",
+ "Brain/metrics",
+ ]);
+ });
+
+ test("binds the manifest through canonicalJson so a byte edit invalidates it", () => {
+ const vault = seedVault();
+ const p = plan(vault, join(tempDir(), "moved"));
+ const { digest, ...bound } = p.manifest;
+ expect(digest).toBe(sha256Hex(canonicalJson(bound)));
+ });
+});
+
+describe("state migration refuses before it commits", () => {
+ test("a symlink in the source tree, by name", () => {
+ const vault = seedVault();
+ const link = join(surfacePath(vault, STATE_SURFACE_ID.metrics), "elsewhere.jsonl");
+ symlinkSync("/etc/hostname", link);
+ const dest = join(tempDir(), "moved");
+
+ const p = plan(vault, dest);
+ expect(refusalCodes(p)).toContain(MIGRATION_REFUSAL.symlink);
+ const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.symlink)!;
+ expect(refusal.path).toBe(link);
+ expect(refusal.found).toContain("/etc/hostname");
+ expectActionableRemedies(p.refusals);
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ expect(existsSync(dest)).toBe(false);
+ });
+
+ test("a special file in the source tree, by name", () => {
+ const vault = seedVault();
+ const fifo = join(surfacePath(vault, STATE_SURFACE_ID.metrics), "pipe");
+ const made = Bun.spawnSync(["mkfifo", fifo]);
+ expect(made.exitCode).toBe(0);
+ const dest = join(tempDir(), "moved");
+
+ const p = plan(vault, dest);
+ const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.specialFile);
+ expect(refusal?.path).toBe(fifo);
+ expect(refusal?.found).toContain("FIFO");
+ expectActionableRemedies(p.refusals);
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ expect(existsSync(dest)).toBe(false);
+ });
+
+ test("a destination that already holds content", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+ write(join(dest, "notes", "keep.md"), "mine\n");
+
+ const p = plan(vault, dest);
+ const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.destinationOccupied);
+ expect(refusal?.path).toBe(dest);
+ expect(refusal?.found).toContain("notes");
+ expectActionableRemedies(p.refusals);
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ expect(tree(dest)).toEqual(["notes/keep.md"]);
+ });
+
+ test("a destination inside the source vault, as a reserved namespace", () => {
+ const vault = seedVault();
+ const dest = join(vault, "inside");
+
+ const p = plan(vault, dest);
+ const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.reservedNamespace);
+ expect(refusal?.path).toBe(dest);
+ expect(refusal?.found).toContain(vault);
+ expectActionableRemedies(p.refusals);
+ // The apply is the assertion. Without it `existsSync(dest)` was true
+ // of a path nothing had been asked to create, which is a fact about
+ // this test rather than about the module.
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ expect(existsSync(dest)).toBe(false);
+ for (const entry of p.manifest.entries) {
+ expect(existsSync(join(vault, entry.relative_path))).toBe(true);
+ }
+ });
+
+ test("insufficient free space at the destination", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+
+ const p = plan(vault, dest, { freeBytesAt: () => 1 });
+ const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.insufficientSpace);
+ expect(refusal?.found).toContain("1 byte");
+ expectActionableRemedies(p.refusals);
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ expect(existsSync(dest)).toBe(false);
+ });
+
+ test("a held search writer lock, which is the one loss a digest cannot undo", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+
+ const p = plan(vault, dest, { writerLockHeldAt: () => true });
+ const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.writerLockHeld);
+ expect(refusal?.path).toBe(surfacePath(vault, STATE_SURFACE_ID.searchIndex));
+ expect(refusal?.remedy).toContain("reindex");
+ expectActionableRemedies(p.refusals);
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ expect(existsSync(dest)).toBe(false);
+ });
+
+ test("a lock whose state could not be determined is refused, not assumed free", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+ const p = plan(vault, dest, {
+ writerLockHeldAt: () => {
+ throw Object.assign(new Error("permission denied"), { code: "EACCES" });
+ },
+ });
+ const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.writerLockHeld);
+ expect(refusal?.found).toContain("EACCES");
+ expectActionableRemedies(p.refusals);
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ expect(existsSync(dest)).toBe(false);
+ });
+
+ test("a surface that could not be probed, rather than silently leaving it behind", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+ const p = plan(vault, dest, {
+ statAt: (path: string) => {
+ if (path.endsWith("metrics")) throw Object.assign(new Error("nope"), { code: "EACCES" });
+ return undefined;
+ },
+ });
+ const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.unreadableSurface);
+ expect(refusal?.path).toBe(surfacePath(vault, STATE_SURFACE_ID.metrics));
+ expect(refusal?.found).toContain("EACCES");
+ expectActionableRemedies(p.refusals);
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ expect(existsSync(dest)).toBe(false);
+ // Named rather than looped over `p.manifest.entries`: the stub
+ // reports every OTHER surface absent, so that list is empty here and
+ // a loop over it would assert nothing at all.
+ expect(existsSync(join(surfacePath(vault, STATE_SURFACE_ID.metrics), "recall.jsonl"))).toBe(
+ true,
+ );
+ expect(existsSync(surfacePath(vault, STATE_SURFACE_ID.searchIndex))).toBe(true);
+ });
+
+ test("a destination that reaches the vault through a symlink, which resolve() cannot see", () => {
+ // `resolve` is a string operation: it collapses `..` and knows
+ // nothing about links, so a destination whose parent is a link INTO
+ // the vault passed every prefix test while landing the whole state
+ // tree inside the vault being migrated.
+ const vault = seedVault();
+ const link = join(tempDir(), "link");
+ symlinkSync(join(vault, "Brain"), link);
+ const dest = join(link, "state");
+
+ const p = plan(vault, dest);
+ const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.reservedNamespace);
+ expect(refusal?.path).toBe(dest);
+ expect(refusal?.found).toContain(vault);
+ expectActionableRemedies(p.refusals);
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ expect(existsSync(dest)).toBe(false);
+ });
+
+ test("a directory in the state tree that cannot be listed, as a refusal not a stack", () => {
+ const vault = seedVault();
+ const locked = surfacePath(vault, STATE_SURFACE_ID.metrics);
+ chmodSync(locked, 0o000);
+ try {
+ const p = plan(vault, join(tempDir(), "moved"), { writerLockHeldAt: () => true });
+ const refusal = p.refusals.find(
+ (r) => r.code === MIGRATION_REFUSAL.unreadableSurface && r.path === locked,
+ );
+ expect(refusal?.found).toContain("EACCES");
+ // The headline contract: an unreadable directory is one refusal
+ // among all of them, not a throw that leaves the rest uncomputed.
+ expectActionableRemedies(p.refusals);
+ expect(refusalCodes(p)).toContain(MIGRATION_REFUSAL.writerLockHeld);
+ expect(p.manifest.entries.map((e) => e.relative_path)).toContain(
+ ".open-second-brain/brain.sqlite",
+ );
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ } finally {
+ chmodSync(locked, 0o755);
+ }
+ });
+
+ test("a surface root that is a DANGLING symlink reaches the symlink refusal", () => {
+ // `statSync` follows the link and reports the missing target as
+ // ENOENT, so the surface read as `absent` and the migration skipped
+ // it in silence - the one outcome a refusal-shaped module must not
+ // have. Deeper in the tree the same link is caught by name.
+ const vault = seedVault();
+ const metrics = surfacePath(vault, STATE_SURFACE_ID.metrics);
+ rmSync(metrics, { recursive: true, force: true });
+ symlinkSync(join(vault, "nowhere"), metrics);
+
+ const p = plan(vault, join(tempDir(), "moved"));
+ const refusal = p.refusals.find(
+ (r) => r.code === MIGRATION_REFUSAL.symlink && r.path === metrics,
+ );
+ expect(refusal?.found).toContain("nowhere");
+ expectActionableRemedies(p.refusals);
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ });
+
+ test("every refusal is collected, so one run tells the operator all of it", () => {
+ const vault = seedVault();
+ symlinkSync("/etc/hostname", join(surfacePath(vault, STATE_SURFACE_ID.metrics), "link"));
+ const dest = join(vault, "inside");
+ write(join(dest, "already.md"), "here first\n");
+
+ const p = plan(vault, dest, { freeBytesAt: () => 0, writerLockHeldAt: () => true });
+ expect(refusalCodes(p)).toEqual(
+ [
+ MIGRATION_REFUSAL.destinationOccupied,
+ MIGRATION_REFUSAL.insufficientSpace,
+ MIGRATION_REFUSAL.reservedNamespace,
+ MIGRATION_REFUSAL.symlink,
+ MIGRATION_REFUSAL.writerLockHeld,
+ ].toSorted(),
+ );
+ });
+});
+
+describe("state migration apply", () => {
+ test("lands every bound file, writes the manifest, and empties the source", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+
+ const p = plan(vault, dest);
+ const result = applyStateMigration(p);
+
+ expect(result.manifest_path).toBe(join(dest, MIGRATION_MANIFEST_FILE));
+ expect(tree(dest).filter((f) => f !== MIGRATION_MANIFEST_FILE)).toEqual(
+ p.manifest.entries.map((e) => e.relative_path),
+ );
+ expect(readFileSync(join(dest, ".open-second-brain/brain.sqlite"), "utf8")).toBe("index-bytes");
+ for (const entry of p.manifest.entries) {
+ expect(existsSync(join(vault, entry.relative_path))).toBe(false);
+ }
+ expect(result.moved).toEqual(p.manifest.entries.map((e) => e.relative_path));
+ });
+
+ test("a manifest written by apply is the plan's manifest, digest and all", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+ const p = plan(vault, dest);
+ applyStateMigration(p);
+
+ const onDisk = JSON.parse(readFileSync(join(dest, MIGRATION_MANIFEST_FILE), "utf8"));
+ expect(onDisk.digest).toBe(p.manifest.digest);
+ const { digest, ...bound } = onDisk;
+ expect(digest).toBe(sha256Hex(canonicalJson(bound)));
+ });
+
+ /**
+ * The module's stated core guarantee, driven by a REAL mid-copy failure
+ * rather than a mocked one: the bytes of the third bound file change
+ * after the plan measured them, so its copy lands, fails the digest
+ * check, and aborts the pass with two files already at the destination.
+ */
+ test("a copy that fails half way unwinds the destination and leaves the source as it was", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+ const p = plan(vault, dest);
+ const before = p.manifest.entries.map((e) =>
+ readFileSync(join(vault, e.relative_path), "utf8"),
+ );
+ writeFileSync(join(vault, "Brain/log/2026-08-16.md"), "# today, rewritten after the plan\n");
+
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+
+ // Nothing of ours is left at the destination, not even the directory
+ // skeleton `mkdirSync` created on the way down: the identical command
+ // is retried, not refused with `destination_occupied`.
+ expect(existsSync(dest)).toBe(false);
+ expect(plan(vault, dest).refusals).toEqual([]);
+ // And the source is exactly as the run found it - the one file this
+ // test rewrote aside, which is the failure it drove.
+ p.manifest.entries.forEach((entry, at) => {
+ expect(existsSync(join(vault, entry.relative_path))).toBe(true);
+ if (entry.relative_path === "Brain/log/2026-08-16.md") return;
+ expect(readFileSync(join(vault, entry.relative_path), "utf8")).toBe(before[at]!);
+ });
+ });
+
+ test("a file that appeared at the destination after the plan is never overwritten", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+ const p = plan(vault, dest);
+ // `destination_occupied` was measured before the operator read the
+ // plan. What arrives afterwards used to be copied over AND then
+ // deleted by the unwind, which cannot tell a file it created from one
+ // it clobbered.
+ const theirs = join(dest, "Brain/metrics/recall.jsonl");
+ write(theirs, "SOMEONE-ELSES-FILE\n");
+
+ expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
+ expect(readFileSync(theirs, "utf8")).toBe("SOMEONE-ELSES-FILE\n");
+ expect(tree(dest)).toEqual(["Brain/metrics/recall.jsonl"]);
+ for (const entry of p.manifest.entries) {
+ expect(existsSync(join(vault, entry.relative_path))).toBe(true);
+ }
+ });
+
+ test("a source it cannot remove says the bytes are safe and names the manifest", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+ const p = plan(vault, dest);
+ // Readable and traversable, but not writable: every file lands and
+ // verifies, and the unlink pass is the thing that fails.
+ const metrics = surfacePath(vault, STATE_SURFACE_ID.metrics);
+ chmodSync(metrics, 0o500);
+ try {
+ let caught: unknown;
+ try {
+ applyStateMigration(p);
+ } catch (error) {
+ caught = error;
+ }
+ expect(caught).toBeInstanceOf(StateMigrationError);
+ expect((caught as Error).message).toContain(join(dest, MIGRATION_MANIFEST_FILE));
+ expect((caught as Error).message).toContain("rollback");
+ expect(readFileSync(join(dest, "Brain/metrics/recall.jsonl"), "utf8")).toBe("{}\n");
+ } finally {
+ chmodSync(metrics, 0o755);
+ }
+ });
+});
+
+describe("state rollback", () => {
+ function migrated(): { vault: string; dest: string } {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+ applyStateMigration(plan(vault, dest));
+ return { vault, dest };
+ }
+
+ test("restores every entry whose digest still matches", () => {
+ const { vault, dest } = migrated();
+
+ const p = planStateRollback({ destination: dest });
+ expect(p.refusals).toEqual([]);
+ const result = applyStateRollback(p);
+
+ expect(result.restored).toEqual(p.restore.map((e) => e.relative_path));
+ expect(readFileSync(join(vault, ".open-second-brain/brain.sqlite"), "utf8")).toBe(
+ "index-bytes",
+ );
+ expect(existsSync(join(dest, ".open-second-brain/brain.sqlite"))).toBe(false);
+ expect(existsSync(join(dest, MIGRATION_MANIFEST_FILE))).toBe(false);
+ });
+
+ test("refuses a file changed after the migration BY NAME and leaves it alone", () => {
+ const { vault, dest } = migrated();
+ const edited = join(dest, "Brain/log/2026-08-16.md");
+ writeFileSync(edited, "# today\nplus a line the operator added\n");
+
+ const p = planStateRollback({ destination: dest });
+ const refusal = p.refusals.find((r) => r.code === ROLLBACK_REFUSAL.digestMismatch);
+ expect(refusal?.relative_path).toBe("Brain/log/2026-08-16.md");
+ expect(refusal?.remedy).toContain("copy");
+ expectActionableRemedies(p.refusals);
+
+ const result = applyStateRollback(p);
+ expect(result.refused.map((r) => r.relative_path)).toEqual(["Brain/log/2026-08-16.md"]);
+ expect(readFileSync(edited, "utf8")).toContain("the operator added");
+ expect(existsSync(join(vault, "Brain/log/2026-08-16.md"))).toBe(false);
+ // The manifest survives an incomplete rollback: the refused entry is
+ // still bound by it, and deleting it would strand the only record of
+ // where that file came from.
+ expect(existsSync(join(dest, MIGRATION_MANIFEST_FILE))).toBe(true);
+ });
+
+ test("refuses an entry missing from the destination rather than inventing one", () => {
+ const { dest } = migrated();
+ rmSync(join(dest, "Brain/metrics/recall.jsonl"));
+
+ const p = planStateRollback({ destination: dest });
+ const refusal = p.refusals.find((r) => r.code === ROLLBACK_REFUSAL.missingAtDestination);
+ expect(refusal?.relative_path).toBe("Brain/metrics/recall.jsonl");
+ expectActionableRemedies(p.refusals);
+ });
+
+ test("refuses to clobber a source path that diverged since the migration", () => {
+ const { vault, dest } = migrated();
+ write(join(vault, "Brain/metrics/recall.jsonl"), "written again since\n");
+
+ const p = planStateRollback({ destination: dest });
+ const refusal = p.refusals.find((r) => r.code === ROLLBACK_REFUSAL.sourceDiverged);
+ expect(refusal?.relative_path).toBe("Brain/metrics/recall.jsonl");
+ expectActionableRemedies(p.refusals);
+
+ applyStateRollback(p);
+ expect(readFileSync(join(vault, "Brain/metrics/recall.jsonl"), "utf8")).toBe(
+ "written again since\n",
+ );
+ expect(existsSync(join(dest, "Brain/metrics/recall.jsonl"))).toBe(true);
+ });
+
+ test("a source path already back in place with the same bytes counts as restored", () => {
+ const { vault, dest } = migrated();
+ // The shape a crash between the copy and the removal leaves behind.
+ write(join(vault, "Brain/metrics/recall.jsonl"), "{}\n");
+
+ const p = planStateRollback({ destination: dest });
+ expect(p.refusals).toEqual([]);
+ const result = applyStateRollback(p);
+ expect(result.restored).toContain("Brain/metrics/recall.jsonl");
+ });
+
+ test("a source path that appeared between the plan and the apply is never overwritten", () => {
+ const { vault, dest } = migrated();
+ const p = planStateRollback({ destination: dest });
+ expect(p.refusals).toEqual([]);
+ // The plan cleared this entry against an empty source path. The
+ // operator wrote there while reading it, and the apply used to copy
+ // straight over them.
+ const target = join(vault, "Brain/metrics/recall.jsonl");
+ write(target, "OPERATOR-WROTE-THIS-AFTER-PLANNING\n");
+
+ const result = applyStateRollback(p);
+ expect(readFileSync(target, "utf8")).toBe("OPERATOR-WROTE-THIS-AFTER-PLANNING\n");
+ expect(result.restored).not.toContain("Brain/metrics/recall.jsonl");
+ expect(result.refused.map((r) => r.code)).toContain(ROLLBACK_REFUSAL.sourceDiverged);
+ expect(existsSync(join(dest, "Brain/metrics/recall.jsonl"))).toBe(true);
+ expect(result.manifest_removed).toBe(false);
+ expect(existsSync(join(dest, MIGRATION_MANIFEST_FILE))).toBe(true);
+ });
+
+ test("one entry it cannot read is refused by name and the rest still go back", () => {
+ const { vault, dest } = migrated();
+ // The source path recreated as a DIRECTORY: reading it for a digest
+ // fails with EISDIR, which used to abort the whole plan and take
+ // every other restorable entry with it.
+ mkdirSync(join(vault, "Brain/metrics/recall.jsonl"), { recursive: true });
+
+ const p = planStateRollback({ destination: dest });
+ const refusal = p.refusals.find((r) => r.code === ROLLBACK_REFUSAL.unreadable);
+ expect(refusal?.relative_path).toBe("Brain/metrics/recall.jsonl");
+ expect(refusal?.found).toContain("EISDIR");
+ expectActionableRemedies(p.refusals);
+ expect(p.restore.map((e) => e.relative_path)).toContain("Brain/log/2026-08-16.md");
+
+ const result = applyStateRollback(p);
+ expect(result.restored).toContain("Brain/log/2026-08-16.md");
+ expect(existsSync(join(dest, "Brain/metrics/recall.jsonl"))).toBe(true);
+ expect(result.manifest_removed).toBe(false);
+ });
+
+ test("a directory the prune cannot look inside is left alone, not judged empty", () => {
+ const { dest } = migrated();
+ // Listable, but its children cannot be stat'ed. Reading that as
+ // "empty" made the `rmdir` below throw ENOTEMPTY out of a rollback
+ // that had in fact succeeded.
+ const opaque = join(dest, "Brain/metrics/extra");
+ write(join(opaque, "keep.jsonl"), "not ours\n");
+ chmodSync(opaque, 0o444);
+ try {
+ const result = applyStateRollback(planStateRollback({ destination: dest }));
+ expect(result.restored).toContain("Brain/metrics/recall.jsonl");
+ expect(existsSync(opaque)).toBe(true);
+ } finally {
+ chmodSync(opaque, 0o755);
+ }
+ });
+
+ test("refuses a source root that is no longer there rather than recreating it", () => {
+ const { vault, dest } = migrated();
+ const renamed = `${vault}-renamed`;
+ renameSync(vault, renamed);
+ temps.push(renamed);
+
+ let caught: unknown;
+ try {
+ planStateRollback({ destination: dest });
+ } catch (error) {
+ caught = error;
+ }
+ expect(caught).toBeInstanceOf(StateMigrationError);
+ expect((caught as Error).message).toContain(vault);
+ expect((caught as Error).message).toContain("--to");
+ // The dead path stays dead, and the only copies stay where they are.
+ expect(existsSync(vault)).toBe(false);
+ expect(existsSync(join(dest, ".open-second-brain/brain.sqlite"))).toBe(true);
+ expect(existsSync(join(dest, MIGRATION_MANIFEST_FILE))).toBe(true);
+ });
+
+ test("--to restores into the vault's new location and still reports the recorded root", () => {
+ const { vault, dest } = migrated();
+ const renamed = `${vault}-renamed`;
+ renameSync(vault, renamed);
+ temps.push(renamed);
+
+ const p = planStateRollback({ destination: dest, vault: renamed });
+ expect(p.source).toBe(renamed);
+ expect(p.manifest.source_root).toBe(vault);
+ expect(renderRollbackPlan(p)).toContain(vault);
+
+ const result = applyStateRollback(p);
+ expect(result.restored).toContain(".open-second-brain/brain.sqlite");
+ expect(readFileSync(join(renamed, ".open-second-brain/brain.sqlite"), "utf8")).toBe(
+ "index-bytes",
+ );
+ expect(existsSync(vault)).toBe(false);
+ });
+
+ test("refuses a manifest whose own digest does not verify", () => {
+ const { dest } = migrated();
+ const manifestPath = join(dest, MIGRATION_MANIFEST_FILE);
+ const doc = JSON.parse(readFileSync(manifestPath, "utf8"));
+ doc.entries[0].bytes = 0;
+ writeFileSync(manifestPath, JSON.stringify(doc));
+
+ expect(() => planStateRollback({ destination: dest })).toThrow(StateMigrationError);
+ });
+});
+
+/**
+ * Every declared refusal code is REACHED by something here.
+ *
+ * A code nobody drives is a branch nobody has read: `ROLLBACK_REFUSAL.
+ * unreadable` was declared and produced nowhere for a release, and the
+ * suite was as green then as it is now. This block builds the conditions
+ * itself rather than accumulating codes seen by the tests above, so it
+ * says the same thing when one test is run in isolation as it does when
+ * the file is run whole.
+ */
+describe("every declared refusal code is reachable", () => {
+ test("the migration codes, all seven, with a remedy each", () => {
+ // Six from one plan, because they are independent conditions and a
+ // plan collects all of them; the seventh needs a probe that throws,
+ // which would hide the surfaces the other six are read from.
+ const vault = seedVault();
+ const metrics = surfacePath(vault, STATE_SURFACE_ID.metrics);
+ symlinkSync("/etc/hostname", join(metrics, "link"));
+ expect(Bun.spawnSync(["mkfifo", join(metrics, "pipe")]).exitCode).toBe(0);
+ const occupied = join(vault, "inside");
+ write(join(occupied, "already.md"), "here first\n");
+
+ const many = plan(vault, occupied, { freeBytesAt: () => 0, writerLockHeldAt: () => true });
+ const unreadable = plan(vault, join(tempDir(), "moved"), {
+ statAt: (path: string) => {
+ if (path.endsWith("metrics")) throw Object.assign(new Error("nope"), { code: "EACCES" });
+ return undefined;
+ },
+ });
+
+ const seen = new Set([...refusalCodes(many), ...refusalCodes(unreadable)]);
+ const unreached = Object.values(MIGRATION_REFUSAL).filter((code) => !seen.has(code));
+ expect(unreached.toSorted().join("\n")).toBe("");
+ expectActionableRemedies([...many.refusals, ...unreadable.refusals]);
+ });
+
+ test("the rollback codes, all four, with a remedy each", () => {
+ const vault = seedVault();
+ const dest = join(tempDir(), "moved");
+ applyStateMigration(plan(vault, dest));
+
+ // One condition per bound entry, so no two of them compete for the
+ // same file and the plan has to report all four.
+ writeFileSync(join(dest, ".open-second-brain/brain.sqlite"), "edited at the destination");
+ rmSync(join(dest, ".open-second-brain/ingest-manifest.json"));
+ write(join(vault, "Brain/log/2026-08-16.md"), "# written again since\n");
+ mkdirSync(join(vault, "Brain/log/dream-runs/run-1.jsonl"), { recursive: true });
+
+ const p = planStateRollback({ destination: dest });
+ const seen = new Set(p.refusals.map((r) => r.code));
+ const unreached = Object.values(ROLLBACK_REFUSAL).filter((code) => !seen.has(code));
+ expect(unreached.toSorted().join("\n")).toBe("");
+ expectActionableRemedies(p.refusals);
+ });
+});
diff --git a/tests/core/state/surfaces.test.ts b/tests/core/state/surfaces.test.ts
new file mode 100644
index 00000000..d7b3a60c
--- /dev/null
+++ b/tests/core/state/surfaces.test.ts
@@ -0,0 +1,621 @@
+/**
+ * The in-vault state inventory: declaration, measurement, rendering.
+ *
+ * `STATE_SURFACES` is a declaration, so most of what can go wrong with it
+ * is a row that no longer describes the resolver it claims to describe.
+ * The binding block below is the guard against exactly that: a row whose
+ * owning resolver is EXPORTED is compared against it, so a rename inside
+ * `brain/paths.ts` or `search/paths.ts` fails here rather than printing a
+ * path nothing writes, and a row whose resolver is PRIVATE is bound by
+ * driving the module's own exported writer against a temporary vault and
+ * asking whether the artifact landed where the row says it does.
+ *
+ * Both halves exist because half a guard reads exactly like a whole one.
+ * This block bound 26 of the 40 rows and the state-surface census
+ * delegated row-path correctness to it in prose, so the other fourteen -
+ * the writer lock, the session focus, the protect manifest, the
+ * maintenance journal, the watchdog audit fallback, the inject cache, the
+ * Aider sidecar, the Brain log, the continuity and lineage ledgers, the
+ * anticipatory cache, the metrics tree, the skill accept journal and the
+ * Claude memory manifest - were checked by nothing at all: renaming
+ * `WATCHDOG_AUDIT_DIR` to a deliberately wrong value left the suite
+ * green. Every row is bound now, and the count of deliberate exceptions
+ * is itself asserted.
+ *
+ * The measured half has one rule the whole design turns on: "it is not
+ * there" and "I could not look" are different repairs. Both directions
+ * are driven below, because a probe that swallows an `EACCES` into
+ * `absent` reads exactly like a healthy vault that has not been used yet.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, mkdirSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+ brainArtifactsDir,
+ brainDirs,
+ claimGraphPath,
+ dreamRunsDir,
+ hookAuditDir,
+ prefAuditDir,
+ proceduralRecurrencePath,
+ proposalWatermarkPath,
+ queryDemandLogPath,
+ rollupLedgerPath,
+ skillAcceptJournalPath,
+ snapshotsDir,
+ brainStateDir,
+ captureDecisionLogPath,
+ captureWatermarkPath,
+} from "../../../src/core/brain/paths.ts";
+import { checkpointPath } from "../../../src/core/brain/ingest/checkpoint.ts";
+import { manifestPath as ingestManifestPath } from "../../../src/core/brain/ingest/content-manifest.ts";
+import { sessionLedgerPath } from "../../../src/core/brain/sessions/discover.ts";
+import { secretsDir } from "../../../src/core/brain/secrets/store.ts";
+import { manifestPath as installManifestPath } from "../../../src/core/install/manifest.ts";
+import { receiptsDir } from "../../../src/core/brain/decisions/receipts.ts";
+import { anticipatoryCachePath } from "../../../src/core/brain/anticipatory-cache.ts";
+import { continuityLogPath } from "../../../src/core/brain/continuity/store.ts";
+import { sessionLineageLedgerPath } from "../../../src/core/brain/lineage/ledger.ts";
+import { appendJournal, MAINTENANCE_VERDICT } from "../../../src/core/brain/maintenance/journal.ts";
+import { acquireLease, MAINTENANCE_LEASE_NAME } from "../../../src/core/brain/maintenance/lease.ts";
+import { appendMetric } from "../../../src/core/brain/metrics.ts";
+import { saveManifest as saveClaudeMemoryManifest } from "../../../src/core/brain/claude-memory-manifest.ts";
+import { writeInjectCache } from "../../../src/core/brain/inject-failopen.ts";
+import { writeManifest as writeProtectManifest } from "../../../src/core/brain/protect.ts";
+import { runBrainWatchdog } from "../../../src/core/brain/watchdog.ts";
+import { resolveAiderSidecarPath } from "../../../src/core/install/adapters/aider-wrapper.ts";
+import type { InstallEnv } from "../../../src/core/install/types.ts";
+import { feedbackDir, learnedWeightsPath } from "../../../src/core/search/feedback.ts";
+import { reinforceDir } from "../../../src/core/search/reinforce.ts";
+import { tuningPath } from "../../../src/core/search/tuning-store.ts";
+import { resolveIndexPath } from "../../../src/core/search/paths.ts";
+import { sessionFocusPath } from "../../../src/core/search/session-focus.ts";
+import { acquireWriterLockSync } from "../../../src/core/search/store/writer-lock.ts";
+import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";
+import { hookStateFilePath } from "../../../hooks/lib/session-state.ts";
+import { CONFIG_ORIGIN } from "../../../src/core/validate.ts";
+import {
+ inventoryStateSurfaces,
+ isStateSurfaceId,
+ isStateReachability,
+ isStateTier,
+ renderStateInventory,
+ STATE_REACHABILITIES,
+ STATE_REACHABILITY,
+ STATE_SURFACE_ID,
+ STATE_SURFACE_IDS,
+ STATE_SURFACES,
+ STATE_TIER,
+ STATE_TIERS,
+ type StateSurfaceId,
+} from "../../../src/core/state/surfaces.ts";
+
+const EMPTY_ENV: NodeJS.ProcessEnv = Object.freeze({});
+const EMPTY_CONFIG: Readonly<Record<string, string>> = Object.freeze({});
+
+function tempVault(): string {
+ return mkdtempSync(join(tmpdir(), "osb-state-surfaces-"));
+}
+
+function row(id: StateSurfaceId) {
+ const found = STATE_SURFACES.find((surface) => surface.id === id);
+ expect(`${id} is declared: ${found !== undefined}`).toBe(`${id} is declared: true`);
+ return found!;
+}
+
+function reportFor(vault: string, id: StateSurfaceId) {
+ const inventory = inventoryStateSurfaces({ vault, env: EMPTY_ENV, config: EMPTY_CONFIG });
+ const found = inventory.surfaces.find((surface) => surface.id === id);
+ expect(`${id} is reported: ${found !== undefined}`).toBe(`${id} is reported: true`);
+ return found!;
+}
+
+describe("the state-surface vocabulary", () => {
+ test("the members list and the object agree, and the guard accepts exactly them", () => {
+ // `Object.values(STATE_SURFACE_IDS)` compared the array with itself:
+ // the array IS `Object.values(STATE_SURFACE_ID)`, so the assertion
+ // read `X.toSorted()` against `X.toSorted()` and could not fail. The
+ // intended operand is the frozen OBJECT, which is the declaration the
+ // list is derived from and the only thing worth comparing it to.
+ const values = Object.values(STATE_SURFACE_ID);
+ expect([...STATE_SURFACE_IDS].toSorted()).toEqual(values.toSorted());
+ for (const id of STATE_SURFACE_IDS) expect(isStateSurfaceId(id)).toBe(true);
+ expect(isStateSurfaceId("no_such_surface")).toBe(false);
+ expect(isStateSurfaceId(7)).toBe(false);
+ });
+
+ test("the tier vocabulary separates rebuildable state from vault content", () => {
+ // Two members, and the census below leans on the separation: a
+ // derived surface is one an operator may delete, and a vault-content
+ // surface is one whose loss is permanent. One bucket would make the
+ // inventory unable to say which is which.
+ expect([...STATE_TIERS].toSorted()).toEqual([STATE_TIER.derived, STATE_TIER.vaultContent]);
+ for (const tier of STATE_TIERS) expect(isStateTier(tier)).toBe(true);
+ expect(isStateTier("cache")).toBe(false);
+ });
+
+ test("reachability has three members, and unchecked is one of them", () => {
+ expect([...STATE_REACHABILITIES].toSorted()).toEqual(
+ [
+ STATE_REACHABILITY.present,
+ STATE_REACHABILITY.absent,
+ STATE_REACHABILITY.unchecked,
+ ].toSorted(),
+ );
+ for (const state of STATE_REACHABILITIES) expect(isStateReachability(state)).toBe(true);
+ expect(isStateReachability("missing")).toBe(false);
+ });
+
+ test("every row is declared once, with a reason a reader can act on", () => {
+ const ids = STATE_SURFACES.map((surface) => surface.id);
+ expect(ids.length).toBe(new Set(ids).size);
+ expect(ids.toSorted()).toEqual([...STATE_SURFACE_IDS].toSorted());
+ const thin = STATE_SURFACES.filter((surface) => surface.reason.trim().length < 40).map(
+ (surface) => surface.id,
+ );
+ expect(thin.join("\n")).toBe("");
+ });
+
+ test("every declared source exists AND is the kind of thing its spelling claims", () => {
+ // An anchor that rots orphans a surface silently; the census attributes
+ // swept path builders through this field.
+ //
+ // The kind check is the second half and it is not decoration: a
+ // trailing slash means "the modules in this directory" and a bare
+ // name means "this module". `existsSync` alone accepted either
+ // spelling for either thing, so `src/core/` and `src/core` were
+ // interchangeable to it - and the looser of the two is the one that
+ // answers for a whole tree.
+ const repoRoot = join(import.meta.dir, "..", "..", "..");
+ const wrong: string[] = [];
+ for (const surface of STATE_SURFACES) {
+ expect(`${surface.id} names a source: ${surface.sources.length > 0}`).toBe(
+ `${surface.id} names a source: true`,
+ );
+ for (const source of surface.sources) {
+ const directory = source.endsWith("/");
+ const abs = join(repoRoot, directory ? source.slice(0, -1) : source);
+ if (!existsSync(abs)) {
+ wrong.push(`${surface.id}: ${source} does not exist`);
+ continue;
+ }
+ const stat = statSync(abs);
+ if (directory && !stat.isDirectory()) {
+ wrong.push(`${surface.id}: ${source} ends in a slash but is not a directory`);
+ }
+ if (!directory && !stat.isFile()) {
+ wrong.push(`${surface.id}: ${source} names a module but is not a file`);
+ }
+ }
+ }
+ expect(wrong.join("\n")).toBe("");
+ });
+
+ test("every derivation stays inside the vault it was handed", () => {
+ const vault = "/srv/vaults/example";
+ const escaping = STATE_SURFACES.filter(
+ (surface) => !surface.derive(vault, null).startsWith(`${vault}/`),
+ ).map((surface) => surface.id);
+ expect(escaping.join("\n")).toBe("");
+ });
+});
+
+/**
+ * Row id -> the path its owning resolver computes, for every row whose
+ * resolver is EXPORTED.
+ *
+ * A table rather than a list of statements, because the point is no
+ * longer only "these rows are right": it is that the set of rows bound
+ * here, plus {@link DRIVEN_BINDINGS}, plus {@link UNBOUND_ROWS}, is
+ * every row there is. Twenty-six of forty rows were bound when this
+ * block was three tests of hand-written expectations, and nothing
+ * noticed the other fourteen - renaming `WATCHDOG_AUDIT_DIR` to a
+ * deliberately wrong value left the whole suite green, because the
+ * census that delegates row-path correctness here only ever checked
+ * that a module PATH appeared in some row's `sources`.
+ */
+const RESOLVER_BINDINGS: ReadonlyArray<readonly [StateSurfaceId, (vault: string) => string]> =
+ Object.freeze([
+ // --- Under `<vault>/.open-second-brain/` -------------------------------
+ ["search_index", (v) => resolveIndexPath(v, null)],
+ [
+ "search_session_focus",
+ // `sessionFocusPath` reads two fields of the resolved search config
+ // and nothing else, so the cast supplies exactly those. Building a
+ // whole `ResolvedSearchConfig` here would bind this row to the
+ // config loader rather than to the resolver that owns its path.
+ (v) => dirname(sessionFocusPath({ vault: v, dbPath: "" } as ResolvedSearchConfig, "scope")),
+ ],
+ ["secret_custody", (v) => secretsDir(v)],
+ ["ingest_content_manifest", (v) => ingestManifestPath(v)],
+ ["ingest_checkpoints", (v) => dirname(checkpointPath(v, "0f1e2d3c"))],
+ ["session_import_ledger", (v) => sessionLedgerPath(v)],
+ ["install_manifest", (v) => installManifestPath(v)],
+ ["hook_audit", (v) => hookAuditDir(v)],
+ ["hook_session_state", (v) => dirname(hookStateFilePath(v, null))],
+ ["aider_context_artifact", (v) => resolveAiderSidecarPath({ vault: v } as InstallEnv, {})],
+ // --- Under `<vault>/Brain/` --------------------------------------------
+ ["brain_log", (v) => brainDirs(v).log],
+ ["continuity_ledger", (v) => dirname(continuityLogPath(v, "2026-08"))],
+ ["dream_runs", (v) => dreamRunsDir(v)],
+ ["pref_audit", (v) => prefAuditDir(v)],
+ ["recurrence_ledger", (v) => proceduralRecurrencePath(v)],
+ ["query_demand_ledger", (v) => queryDemandLogPath(v)],
+ ["capture_decision_log", (v) => captureDecisionLogPath(v)],
+ ["capture_watermark", (v) => captureWatermarkPath(v)],
+ ["proposal_watermark", (v) => proposalWatermarkPath(v)],
+ ["decision_receipts", (v) => receiptsDir(v)],
+ ["lineage_ledger", (v) => sessionLineageLedgerPath(v)],
+ ["anticipatory_cache", (v) => dirname(anticipatoryCachePath(v, "root-session"))],
+ ["exact_state", (v) => brainStateDir(v)],
+ ["search_feedback", (v) => feedbackDir(v)],
+ ["search_learned_weights", (v) => learnedWeightsPath(v)],
+ ["search_reinforce", (v) => reinforceDir(v)],
+ ["search_tuning", (v) => tuningPath(v)],
+ ["snapshots", (v) => snapshotsDir(v)],
+ ["mcp_artifacts", (v) => brainArtifactsDir(v)],
+ ["skill_accept_journal", (v) => dirname(skillAcceptJournalPath(v, "probe"))],
+ ["claim_graph", (v) => claimGraphPath(v)],
+ ["rollup_ledger", (v) => rollupLedgerPath(v)],
+ ]);
+
+/**
+ * A row whose resolver is module-private, bound by DRIVING the module's
+ * own exported writer against a real temporary vault.
+ *
+ * The comparison is not "something appeared under the vault": that would
+ * pass for a row naming any ancestor of the real location. Each entry
+ * names the concrete artifact the write produces AS A FUNCTION OF THE
+ * ROW'S OWN PATH, so a row pointing one directory up, or at a sibling,
+ * has nowhere for that artifact to be.
+ */
+interface DrivenBinding {
+ readonly id: StateSurfaceId;
+ /**
+ * Make the owning module write, through its exported surface only.
+ * Return the path the writer REPORTS having written when it reports
+ * one - a report is a stronger binding than "something appeared" -
+ * and `null` when it reports nothing.
+ */
+ readonly drive: (vault: string) => string | null;
+ /** The artifact the drive creates, expressed from the row's own path. */
+ readonly artifact: (derived: string) => string;
+}
+
+const DRIVEN_BINDINGS: ReadonlyArray<DrivenBinding> = Object.freeze([
+ {
+ // `leaseDbPath` is private; `acquireLease` creates the database.
+ id: STATE_SURFACE_ID.maintenanceLease,
+ drive: (vault) => {
+ acquireLease(vault, {
+ name: MAINTENANCE_LEASE_NAME,
+ holder: "state-surface-binding",
+ ttlMs: 60_000,
+ now: new Date("2026-08-16T10:00:00.000Z"),
+ });
+ return null;
+ },
+ artifact: (derived) => derived,
+ },
+ {
+ // `journalPath` is private; `appendJournal` writes the JSONL.
+ id: STATE_SURFACE_ID.maintenanceJournal,
+ drive: (vault) => {
+ appendJournal(vault, {
+ ts: "2026-08-16T10:00:00.000Z",
+ holder: "state-surface-binding",
+ verdict: MAINTENANCE_VERDICT.run,
+ });
+ return null;
+ },
+ artifact: (derived) => derived,
+ },
+ {
+ // The protect manifest path is private; `writeManifest` is not.
+ id: STATE_SURFACE_ID.protectManifest,
+ drive: (vault) => {
+ writeProtectManifest(vault, {
+ schema_version: 1,
+ target: "claudecode",
+ vault,
+ owned_deny: [],
+ owned_allow: [],
+ });
+ return null;
+ },
+ artifact: (derived) => derived,
+ },
+ {
+ // `cachePath` is private; the row is the DIRECTORY, so the artifact
+ // is the cache file the write puts inside it.
+ id: STATE_SURFACE_ID.injectFailopenCache,
+ drive: (vault) => {
+ writeInjectCache(vault, "state-surface-binding", "cached body");
+ return null;
+ },
+ artifact: (derived) => join(derived, "state-surface-binding.txt"),
+ },
+ {
+ // `metricsDir` is private; same directory-plus-artifact shape.
+ id: STATE_SURFACE_ID.metrics,
+ drive: (vault) => {
+ appendMetric(vault, {
+ surface: "state_surface_binding",
+ runAt: "2026-08-16T10:00:00Z",
+ payload: {},
+ });
+ return null;
+ },
+ artifact: (derived) => join(derived, "state_surface_binding.jsonl"),
+ },
+ {
+ // `manifestPath` is private; `saveManifest` writes the row's file.
+ id: STATE_SURFACE_ID.claudeMemoryManifest,
+ drive: (vault) => {
+ saveClaudeMemoryManifest(vault, { version: 1, imports: {} });
+ return null;
+ },
+ artifact: (derived) => derived,
+ },
+ {
+ // The FALLBACK the watchdog uses when its configured audit directory
+ // refuses the write, so the drive has to make that directory refuse:
+ // `Brain/log/watchdog` is pre-created as a FILE, and `mkdirSync` on
+ // it throws. `runBrainWatchdog` reports the path it landed on, which
+ // is what makes this a comparison and not a sighting.
+ id: STATE_SURFACE_ID.watchdogAudit,
+ drive: (vault) => {
+ const log = brainDirs(vault).log;
+ mkdirSync(log, { recursive: true });
+ writeFileSync(join(log, "watchdog"), "not a directory", "utf8");
+ return runBrainWatchdog(vault).audit_path;
+ },
+ artifact: (derived) => derived,
+ },
+ {
+ // No resolver at all: the `.lock` suffix is `proper-lockfile`'s, and
+ // the only honest way to bind it is to take the lock and look.
+ id: STATE_SURFACE_ID.searchWriterLock,
+ drive: (vault) => {
+ const index = row(STATE_SURFACE_ID.searchIndex).derive(vault, null);
+ mkdirSync(dirname(index), { recursive: true });
+ acquireWriterLockSync(index);
+ return null;
+ },
+ artifact: (derived) => derived,
+ },
+]);
+
+/**
+ * Rows deliberately left unbound, each with the reason no binding is
+ * reachable. An entry here is a decision; the absence of one is not.
+ *
+ * EMPTY today, and that is the finding: of the fourteen rows nothing
+ * bound, every one turned out to have either an exported resolver or an
+ * exported writer that reports where it wrote. The map and its count
+ * stay because the next row added to the catalogue is the one that will
+ * want an excuse, and an excuse should have to be typed.
+ */
+const UNBOUND_ROWS: ReadonlyMap<StateSurfaceId, string> = new Map();
+
+/** How many rows are deliberately unbound. An equality, so a new one is a decision. */
+const UNBOUND_ROW_COUNT = 0;
+
+/** An unbound reason has to be an argument, at the bar the censuses use. */
+const MIN_UNBOUND_REASON_LENGTH = 80;
+
+describe("each row is bound to the resolver that owns it", () => {
+ const vault = "/srv/vaults/example";
+
+ for (const [id, resolver] of RESOLVER_BINDINGS) {
+ test(`${id} derives what its resolver returns`, () => {
+ expect(row(id).derive(vault, null)).toBe(resolver(vault));
+ });
+ }
+
+ test("the search index follows its override, and so does everything derived from it", () => {
+ const elsewhere = "/elsewhere/brain.sqlite";
+ expect(row("search_index").derive(vault, elsewhere)).toBe(resolveIndexPath(vault, elsewhere));
+ expect(row("search_writer_lock").derive(vault, elsewhere)).toBe(`${elsewhere}.lock`);
+ expect(row("search_session_focus").derive(vault, elsewhere)).toBe(
+ dirname(sessionFocusPath({ vault, dbPath: elsewhere } as ResolvedSearchConfig, "scope")),
+ );
+ });
+
+ for (const binding of DRIVEN_BINDINGS) {
+ test(`${binding.id} is where its own writer puts bytes`, () => {
+ const temp = tempVault();
+ const derived = row(binding.id).derive(temp, null);
+ const artifact = binding.artifact(derived);
+ expect(existsSync(artifact)).toBe(false);
+ const reported = binding.drive(temp);
+ expect(existsSync(artifact)).toBe(true);
+ // A writer that names the path it wrote is held to it exactly:
+ // either it IS the artifact, or it sits directly in the directory
+ // the row declares. Anything else means the row and the writer
+ // disagree about where this surface lives.
+ if (reported !== null) {
+ expect(reported === artifact || dirname(reported) === artifact).toBe(true);
+ }
+ });
+ }
+
+ test("every declared row is bound, or is one of the counted exceptions", () => {
+ // The assertion the fourteen unbound rows needed. Without it a new
+ // row joins the catalogue bound to nothing, and the census that
+ // delegates path correctness to this block keeps saying it is
+ // covered here.
+ const bound = new Set<string>([
+ ...RESOLVER_BINDINGS.map(([id]) => id),
+ ...DRIVEN_BINDINGS.map((binding) => binding.id),
+ ]);
+ const overlap = [...UNBOUND_ROWS.keys()].filter((id) => bound.has(id));
+ expect(overlap.join("\n")).toBe("");
+ const unaccounted = STATE_SURFACE_IDS.filter((id) => !bound.has(id) && !UNBOUND_ROWS.has(id));
+ expect(unaccounted.toSorted().join("\n")).toBe("");
+ const stale = [...UNBOUND_ROWS.keys()].filter((id) => !isStateSurfaceId(id));
+ expect(stale.join("\n")).toBe("");
+ expect(UNBOUND_ROWS.size).toBe(UNBOUND_ROW_COUNT);
+ });
+
+ test("every deliberately unbound row says why, at the bar the censuses use", () => {
+ const thin = [...UNBOUND_ROWS.entries()]
+ .filter(
+ ([, reason]) =>
+ reason.trim().length < MIN_UNBOUND_REASON_LENGTH ||
+ /\bTODO\b|\bfor now\b|\blater\b/i.test(reason),
+ )
+ .map(([id]) => id);
+ expect(thin.join("\n")).toBe("");
+ });
+});
+
+describe("the measured half", () => {
+ test("a surface nothing has written reports absent, with the reason it is absent", () => {
+ const report = reportFor(tempVault(), "maintenance_lease");
+ expect(report.reachability.state).toBe(STATE_REACHABILITY.absent);
+ expect(report.reachability.reason).not.toBeNull();
+ expect(report.reachability.path).toBe(report.path);
+ });
+
+ test("a surface that exists reports present, with no reason to give", () => {
+ const vault = tempVault();
+ const path = row("maintenance_lease").derive(vault, null);
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, "", "utf8");
+ const report = reportFor(vault, "maintenance_lease");
+ expect(report.reachability.state).toBe(STATE_REACHABILITY.present);
+ expect(report.reachability.reason).toBeNull();
+ });
+
+ test("a dangling symlink is present: something IS there, and it needs a decision", () => {
+ // `statSync` follows the link and reports the missing TARGET as
+ // ENOENT, so a surface whose root is a broken link read as `absent`
+ // and `state migrate` skipped it in silence. Reporting it present is
+ // what carries it to the `symlink` refusal, which is the one place
+ // that knows what to tell the operator about a link.
+ const vault = tempVault();
+ const path = row("maintenance_lease").derive(vault, null);
+ mkdirSync(dirname(path), { recursive: true });
+ symlinkSync(join(vault, "nowhere"), path);
+
+ const report = reportFor(vault, "maintenance_lease");
+ expect(report.reachability.state).toBe(STATE_REACHABILITY.present);
+ expect(report.reachability.reason).toBeNull();
+ });
+
+ test("a probe that cannot look reports unchecked, never absent", () => {
+ // The whole point of the tri-state. A permission error folded into
+ // `absent` tells the operator to create a file that is already there.
+ const denied = new Error("EACCES: permission denied") as NodeJS.ErrnoException;
+ denied.code = "EACCES";
+ const inventory = inventoryStateSurfaces({
+ vault: tempVault(),
+ env: EMPTY_ENV,
+ config: EMPTY_CONFIG,
+ statAt: () => {
+ throw denied;
+ },
+ });
+ const states = new Set(inventory.surfaces.map((s) => s.reachability.state));
+ expect([...states]).toEqual([STATE_REACHABILITY.unchecked]);
+ const sample = inventory.surfaces[0]!;
+ expect(sample.reachability.reason).toContain("EACCES");
+ });
+
+ test("the inventory reports one row per declared surface, in declaration order", () => {
+ const inventory = inventoryStateSurfaces({
+ vault: tempVault(),
+ env: EMPTY_ENV,
+ config: EMPTY_CONFIG,
+ });
+ expect(inventory.surfaces.map((s) => s.id)).toEqual(STATE_SURFACES.map((s) => s.id));
+ });
+});
+
+describe("the origin names the layer that placed the path", () => {
+ test("an environment override moves the path and is reported as env", () => {
+ const vault = tempVault();
+ const inventory = inventoryStateSurfaces({
+ vault,
+ env: { OPEN_SECOND_BRAIN_SEARCH_DB: "/elsewhere/brain.sqlite" },
+ config: EMPTY_CONFIG,
+ });
+ const index = inventory.surfaces.find((s) => s.id === "search_index")!;
+ expect(index.path).toBe("/elsewhere/brain.sqlite");
+ expect(index.origin).toBe(CONFIG_ORIGIN.env);
+ // Everything derived from the index follows it, or the inventory
+ // would print a lock file beside a database nobody opens.
+ const lock = inventory.surfaces.find((s) => s.id === "search_writer_lock")!;
+ expect(lock.path).toBe("/elsewhere/brain.sqlite.lock");
+ expect(lock.origin).toBe(CONFIG_ORIGIN.env);
+ });
+
+ test("a machine-config key moves the path and is reported as user-config", () => {
+ const vault = tempVault();
+ const inventory = inventoryStateSurfaces({
+ vault,
+ env: EMPTY_ENV,
+ config: { search_db_path: "/elsewhere/brain.sqlite" },
+ });
+ const index = inventory.surfaces.find((s) => s.id === "search_index")!;
+ expect(index.path).toBe("/elsewhere/brain.sqlite");
+ expect(index.origin).toBe(CONFIG_ORIGIN.userConfig);
+ });
+
+ test("a row nothing can move reports default, whatever the environment holds", () => {
+ const vault = tempVault();
+ const inventory = inventoryStateSurfaces({
+ vault,
+ env: { OPEN_SECOND_BRAIN_SEARCH_DB: "/elsewhere/brain.sqlite" },
+ config: { search_db_path: "/elsewhere/brain.sqlite" },
+ });
+ const drifted = inventory.surfaces
+ .filter((s) => s.override_env === null && s.override_config_key === null)
+ .filter((s) => s.origin !== CONFIG_ORIGIN.default)
+ .map((s) => s.id);
+ expect(drifted.join("\n")).toBe("");
+ });
+});
+
+describe("one value, two renderings", () => {
+ test("the rendered statement names every surface it was built from", () => {
+ const inventory = inventoryStateSurfaces({
+ vault: tempVault(),
+ env: EMPTY_ENV,
+ config: EMPTY_CONFIG,
+ });
+ const text = renderStateInventory(inventory);
+ const unnamed = inventory.surfaces
+ .filter((s) => !text.includes(s.label) || !text.includes(s.path))
+ .map((s) => s.id);
+ expect(unnamed.join("\n")).toBe("");
+ });
+
+ test("the rendering states the vault and the count it measured", () => {
+ const vault = tempVault();
+ const inventory = inventoryStateSurfaces({ vault, env: EMPTY_ENV, config: EMPTY_CONFIG });
+ const text = renderStateInventory(inventory);
+ expect(text).toContain(vault);
+ expect(text).toContain(String(inventory.surfaces.length));
+ });
+
+ test("an unchecked surface is never rendered as an absent one", () => {
+ const denied = new Error("EACCES: permission denied") as NodeJS.ErrnoException;
+ denied.code = "EACCES";
+ const inventory = inventoryStateSurfaces({
+ vault: tempVault(),
+ env: EMPTY_ENV,
+ config: EMPTY_CONFIG,
+ statAt: () => {
+ throw denied;
+ },
+ });
+ const text = renderStateInventory(inventory);
+ expect(text).toContain("EACCES");
+ expect(text).not.toContain("nothing has created it");
+ });
+});
diff --git a/tests/docs/install-verify-conformance.test.ts b/tests/docs/install-verify-conformance.test.ts
index 3052897a..591f9ae9 100644
--- a/tests/docs/install-verify-conformance.test.ts
+++ b/tests/docs/install-verify-conformance.test.ts
@@ -19,17 +19,23 @@
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { Writable } from "node:stream";
import { registerAllAdapters } from "../../src/core/install/adapters/all.ts";
+import {
+ resetCodexRunner,
+ setCodexRunner,
+ type CodexRunner,
+} from "../../src/core/install/adapters/codex.ts";
import {
resetCopilotRunner,
setCopilotRunner,
type CopilotRunner,
} from "../../src/core/install/adapters/copilot-cli.ts";
+import { resetHostProbeRunner, setHostProbeRunner } from "../../src/core/install/host-probe.ts";
import { buildPayload } from "../../src/core/install/payload.ts";
import { renderVerifyTable } from "../../src/cli/install/render.ts";
import type {
@@ -62,7 +68,6 @@ const TIMEZONE = "UTC";
*/
const PIPELINE_HOSTED_DOCS: Readonly<Record<string, string>> = Object.freeze({
"claudecode.md": "plugin-hosted; verified with `claude mcp list`, not an OSB adapter",
- "codex.md": "plugin-hosted; verified with `codex mcp list`, not an OSB adapter",
"hermes.md": "provider-hosted; verified with `hermes memory status`, not an OSB adapter",
"openclaw.md": "plugin-hosted; verified with `openclaw plugins inspect`, not an OSB adapter",
"prerequisites.md": "shared setup, not a runtime document",
@@ -85,7 +90,9 @@ beforeEach(() => {
});
afterEach(() => {
+ resetCodexRunner();
resetCopilotRunner();
+ resetHostProbeRunner();
for (const dir of [vault, home]) {
try {
rmSync(dir, { recursive: true, force: true });
@@ -136,6 +143,36 @@ const INSTALLERS: Readonly<Record<string, (adapter: InstallAdapter) => Harness>>
const h = harness({ piSkillSource: join(REPO_ROOT, "skills", "brain-memory") });
return applyInto(adapter, h);
},
+ codex: (adapter) => {
+ // The codex CLI may or may not be on the machine running this suite,
+ // and the document has to show ONE thing: what an operator who has
+ // it installed sees. So the mutation seam is a fake that behaves
+ // like the real binary - `mcp add` persists a `[mcp_servers.<name>]`
+ // table into `$CODEX_HOME/config.toml`, in codex's own layout rather
+ // than the adapter's - and the read-only probe is staged separately,
+ // exactly as the copilot case below stages its two seams.
+ const registered: string[] = [];
+ const runner: CodexRunner = {
+ available: () => true,
+ run: (codexHome: string, args: ReadonlyArray<string>) => {
+ if (args[0] === "mcp" && args[1] === "add" && typeof args[2] === "string") {
+ registered.push(args[2]);
+ mkdirSync(codexHome, { recursive: true });
+ const tables = registered
+ .map((name) => `[mcp_servers.${name}]\ncommand = "o2b"\nargs = [\n "mcp",\n]\n`)
+ .join("\n");
+ writeFileSync(join(codexHome, "config.toml"), tables);
+ }
+ return { exitCode: 0, stdout: "", stderr: "" };
+ },
+ };
+ setCodexRunner(runner);
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: registered.join("\n") + "\n", stderr: "" }),
+ });
+ return applyInto(adapter, harness());
+ },
"copilot-cli": (adapter) => {
// The copilot CLI is not present in a test environment; inject a
// runner that behaves like a working one so the document shows the
@@ -152,6 +189,15 @@ const INSTALLERS: Readonly<Record<string, (adapter: InstallAdapter) => Harness>>
},
};
setCopilotRunner(runner);
+ // `verify` reads the host through the DECLARED probe rather than
+ // through `CopilotRunner`, so the same fiction has to be staged on
+ // that seam too - otherwise the document would show the verdict of a
+ // machine with no `copilot` on PATH, which is not what a successful
+ // check looks like.
+ setHostProbeRunner({
+ available: () => true,
+ run: () => ({ exitCode: 0, stdout: registered.join("\n") + "\n", stderr: "" }),
+ });
return applyInto(adapter, harness());
},
});
diff --git a/tests/fixtures/install/codex-mcp-list.txt b/tests/fixtures/install/codex-mcp-list.txt
new file mode 100644
index 00000000..5032b4f6
--- /dev/null
+++ b/tests/fixtures/install/codex-mcp-list.txt
@@ -0,0 +1,2 @@
+Name Command Args Env Cwd Status Auth
+open-second-brain o2b mcp - - enabled Unsupported
diff --git a/tests/fixtures/install/grok-hooks.golden.json b/tests/fixtures/install/grok-hooks.golden.json
new file mode 100644
index 00000000..00725508
--- /dev/null
+++ b/tests/fixtures/install/grok-hooks.golden.json
@@ -0,0 +1,186 @@
+{
+ "hooks": {
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/active-inject.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ },
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/gap-agenda.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ },
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/session-capture.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ }
+ ]
+ }
+ ],
+ "UserPromptSubmit": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/session-capture.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ },
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/recall-inject.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ },
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/nav-inject.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ }
+ ]
+ }
+ ],
+ "PreToolUse": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/pretool-orient.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ }
+ ]
+ }
+ ],
+ "PostToolUse": [
+ {
+ "matcher": "brain_feedback",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/session-capture.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ }
+ ]
+ },
+ {
+ "matcher": "Write|Edit|MultiEdit|apply_patch|search_replace",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/post-write-reminder.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/session-capture.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ },
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/stop-log-guardrail.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ }
+ ]
+ }
+ ],
+ "SubagentStop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/session-capture.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ }
+ ]
+ }
+ ],
+ "SessionEnd": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/session-capture.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ },
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/gap-promote.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ }
+ ]
+ }
+ ],
+ "PostCompact": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/active-inject.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ },
+ {
+ "type": "command",
+ "command": "<BUN> run <REPO>/hooks/session-capture.ts",
+ "env": {
+ "VAULT_AGENT_NAME": "grok-dev-agent"
+ },
+ "timeout": 10
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/tests/mcp/http-drain.test.ts b/tests/mcp/http-drain.test.ts
new file mode 100644
index 00000000..5293dd05
--- /dev/null
+++ b/tests/mcp/http-drain.test.ts
@@ -0,0 +1,259 @@
+/**
+ * Shutting the MCP transports down without cutting a request in half.
+ *
+ * Before this unit `HttpServerHandle.close` was a bare `server.close()`:
+ * it stopped the listener and returned, while the promise returned by
+ * `handleHttpRequest` was floated. A supervisor sending SIGTERM during a
+ * tool call got a truncated response and no record of it, and neither
+ * transport handled a signal at all.
+ *
+ * The tests below therefore hold a REAL request open across the drain
+ * rather than asserting on a counter. The hold is produced by a client
+ * that announces a `Content-Length` and then sends only part of the body,
+ * so the server is genuinely parked inside `readBody` - a mock would
+ * prove the bookkeeping and nothing about the server.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { connect, type Socket } from "node:net";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { installMcpSignalDrain } from "../../src/cli/mcp-drain.ts";
+import { EXIT_TERMINATED } from "../../src/cli/interrupt.ts";
+import {
+ DEFAULT_DRAIN_DEADLINE_MS,
+ DRAIN_DEADLINE_ENV,
+ DRAIN_STATE,
+ describeAbandonedRequests,
+ resolveDrainDeadlineMs,
+} from "../../src/mcp/drain.ts";
+import { startHttp, type HttpServerHandle } from "../../src/mcp/http.ts";
+
+const temps: string[] = [];
+
+afterEach(() => {
+ while (temps.length > 0) rmSync(temps.pop()!, { recursive: true, force: true });
+});
+
+function tempVault(): string {
+ const dir = mkdtempSync(join(tmpdir(), "osb-mcp-drain-"));
+ temps.push(dir);
+ return dir;
+}
+
+/**
+ * A request the server has begun and cannot finish until the caller says
+ * so: the headers promise more body than has been sent, so the server is
+ * parked awaiting the rest.
+ */
+interface HeldRequest {
+ readonly socket: Socket;
+ /** Send the rest of the body, letting the server complete the request. */
+ readonly complete: () => void;
+ /** The full HTTP response, once the server writes one. */
+ readonly response: Promise<string>;
+}
+
+async function holdRequestOpen(handle: HttpServerHandle): Promise<HeldRequest> {
+ const held = await openHeldSocket(handle);
+ // The socket write returning says nothing about the server having read
+ // it. Without this wait the drain below can start before the request
+ // has been registered at all, and every assertion about waiting for it
+ // would pass over an empty register.
+ await until(() => handle.drain.inFlight === 1, "the held request to reach the server");
+ return held;
+}
+
+/** Poll a condition the server reaches on its own schedule, or say what failed. */
+async function until(condition: () => boolean, what: string): Promise<void> {
+ for (let attempt = 0; attempt < 200; attempt++) {
+ if (condition()) return;
+ await Bun.sleep(5);
+ }
+ throw new Error(`timed out waiting for ${what}`);
+}
+
+function openHeldSocket(handle: HttpServerHandle): Promise<HeldRequest> {
+ const body = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" });
+ const head = body.slice(0, 5);
+ const tail = body.slice(5);
+ return new Promise((ready, failed) => {
+ const socket = connect(handle.port, handle.host, () => {
+ socket.write(
+ `POST / HTTP/1.1\r\nHost: ${handle.host}:${handle.port}\r\n` +
+ `content-type: application/json\r\ncontent-length: ${Buffer.byteLength(body)}\r\n\r\n` +
+ head,
+ );
+ let seen = "";
+ const response = new Promise<string>((resolve) => {
+ socket.on("data", (chunk) => {
+ seen += String(chunk);
+ if (seen.includes("\r\n\r\n")) resolve(seen);
+ });
+ socket.on("close", () => resolve(seen));
+ });
+ ready({ socket, complete: () => socket.write(tail), response });
+ });
+ socket.on("error", failed);
+ });
+}
+
+async function health(handle: HttpServerHandle): Promise<Record<string, unknown>> {
+ const res = await fetch(`${handle.url}/health`);
+ return (await res.json()) as Record<string, unknown>;
+}
+
+describe("the drain deadline", () => {
+ test("defaults to ten seconds", () => {
+ expect(DEFAULT_DRAIN_DEADLINE_MS).toBe(10_000);
+ expect(resolveDrainDeadlineMs({})).toBe(DEFAULT_DRAIN_DEADLINE_MS);
+ });
+
+ test("is overridable by the environment", () => {
+ expect(resolveDrainDeadlineMs({ [DRAIN_DEADLINE_ENV]: "250" })).toBe(250);
+ });
+
+ test("refuses a value that is not a deadline rather than silently defaulting", () => {
+ expect(() => resolveDrainDeadlineMs({ [DRAIN_DEADLINE_ENV]: "soon" })).toThrow(
+ new RegExp(DRAIN_DEADLINE_ENV),
+ );
+ expect(() => resolveDrainDeadlineMs({ [DRAIN_DEADLINE_ENV]: "-1" })).toThrow(
+ new RegExp(DRAIN_DEADLINE_ENV),
+ );
+ });
+});
+
+describe("the HTTP transport drains before it closes", () => {
+ test("reports draining on the unauthenticated /health while a request is in flight", async () => {
+ const handle = await startHttp({ vault: tempVault() }, { host: "127.0.0.1", port: 0 });
+ const held = await holdRequestOpen(handle);
+ try {
+ expect((await health(handle)).status).toBe("ok");
+
+ const closing = handle.close();
+ await until(() => handle.drain.draining, "the drain to start");
+ // The listener stays up so a supervisor can still be told what is
+ // happening; what stops is the acceptance of new MCP work.
+ const probe = await health(handle);
+ expect(probe.status).toBe(DRAIN_STATE.draining);
+ expect(probe.in_flight).toBe(1);
+
+ const refused = await fetch(handle.url, {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "ping" }),
+ });
+ expect(refused.status).toBe(503);
+
+ held.complete();
+ const outcome = await closing;
+ expect(outcome.state).toBe(DRAIN_STATE.drained);
+ expect(outcome.abandoned).toEqual([]);
+ expect(await held.response).toContain("200 OK");
+ } finally {
+ held.socket.destroy();
+ }
+ });
+
+ test("a request refused with 503 is not counted as work the drain waits for", async () => {
+ const handle = await startHttp({ vault: tempVault() }, { host: "127.0.0.1", port: 0 });
+ const held = await holdRequestOpen(handle);
+ try {
+ const closing = handle.close();
+ await until(() => handle.drain.draining, "the drain to start");
+
+ const retries = await Promise.all(
+ [1, 2, 3].map((id) =>
+ fetch(handle.url, {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ jsonrpc: "2.0", id, method: "ping" }),
+ }),
+ ),
+ );
+ expect(retries.map((r) => r.status)).toEqual([503, 503, 503]);
+
+ // The register hands out ids in registration order, so the id of
+ // the next request IS the count of everything registered before
+ // it: 1 is the held request, and 2 means the three refusals above
+ // never entered the register. Counting them let a client retrying
+ // in a tight loop hold the drain open to its own deadline.
+ const finish = handle.drain.begin("probe");
+ expect(handle.drain.snapshot().find((r) => r.label === "probe")?.id).toBe(2);
+ finish();
+
+ held.complete();
+ expect((await closing).state).toBe(DRAIN_STATE.drained);
+ } finally {
+ held.socket.destroy();
+ }
+ });
+
+ test("names the still-open requests on stderr when the deadline expires", async () => {
+ const handle = await startHttp(
+ { vault: tempVault() },
+ { host: "127.0.0.1", port: 0, drainDeadlineMs: 120 },
+ );
+ const held = await holdRequestOpen(handle);
+ try {
+ const outcome = await handle.close();
+ expect(outcome.state).toBe(DRAIN_STATE.deadlineExpired);
+ expect(outcome.abandoned).toHaveLength(1);
+ expect(outcome.abandoned[0]!.label).toBe("POST /");
+
+ const report = describeAbandonedRequests(outcome);
+ expect(report).toContain("POST /");
+ expect(report).toContain("120");
+ } finally {
+ held.socket.destroy();
+ }
+ });
+
+ test("a close with nothing in flight resolves at once and shuts the listener", async () => {
+ const handle = await startHttp({ vault: tempVault() }, { host: "127.0.0.1", port: 0 });
+ const outcome = await handle.close();
+ expect(outcome.state).toBe(DRAIN_STATE.drained);
+ await expect(fetch(`${handle.url}/health`)).rejects.toThrow();
+ });
+});
+
+describe("a signal drains the transport", () => {
+ test("SIGTERM drains, then exits with the signal's code so the exit hooks run", async () => {
+ const handle = await startHttp({ vault: tempVault() }, { host: "127.0.0.1", port: 0 });
+ const held = await holdRequestOpen(handle);
+ const stderr: string[] = [];
+ const exits: number[] = [];
+ let settled: () => void = () => {};
+ const finished = new Promise<void>((resolve) => {
+ settled = resolve;
+ });
+
+ const installed = installMcpSignalDrain({
+ close: () => handle.close(),
+ stderr: { write: (chunk: string) => void stderr.push(chunk) },
+ exit: (code) => {
+ exits.push(code);
+ settled();
+ },
+ });
+ try {
+ process.kill(process.pid, "SIGTERM");
+ // A signal handler is a callback dispatched from the event loop, so
+ // it runs a turn or more after delivery (`src/cli/interrupt.ts`
+ // measures exactly this). The request is still open when it does,
+ // which is the point of the test.
+ await until(() => handle.drain.draining, "the signal handler to start a drain");
+ expect((await health(handle)).status).toBe(DRAIN_STATE.draining);
+ held.complete();
+ await finished;
+
+ expect(exits).toEqual([EXIT_TERMINATED]);
+ expect(stderr.join("")).toContain("SIGTERM");
+ } finally {
+ installed.release();
+ held.socket.destroy();
+ }
+ });
+});
diff --git a/tests/mcp/long-running-tools.test.ts b/tests/mcp/long-running-tools.test.ts
index 7287040b..54b422de 100644
--- a/tests/mcp/long-running-tools.test.ts
+++ b/tests/mcp/long-running-tools.test.ts
@@ -31,11 +31,12 @@
*/
import { afterEach, beforeEach, expect, spyOn, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { DREAM_STEP } from "../../src/core/brain/dream-step.ts";
import { indexVault } from "../../src/core/search/indexer.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { makeConfig } from "../helpers/search-fixtures.ts";
@@ -197,6 +198,59 @@ test("brain_dream stage aborts once its deadline has passed", async () => {
}
});
+test("brain_dream step aborts once its deadline has passed", async () => {
+ // The step branch was the one row `docs/mcp.md` marked **none**: it
+ // returned `runDreamStep(vault, step)` with no guard, so a single step
+ // over a large tree held the server's event loop for its whole
+ // duration. It is bounded on the same `dream` budget as every other
+ // branch now, and the abort names the operation rather than the step.
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ const restore = jumpingClock();
+ try {
+ const result = await callRaw(server, "brain_dream", { action: "run", step: "scan" });
+ expect(result.isError).toBe(true);
+ expect(result.content![0]!.text).toContain("safeguard timeout");
+ expect(result.content![0]!.text).toContain("dream");
+ } finally {
+ restore();
+ }
+});
+
+test("brain_dream step reports the step it runs under a progress token", async () => {
+ const frames: JsonRpcNotification[] = [];
+ const server = observedServer(frames);
+ await initialize(server);
+
+ expect(
+ (await callWithToken(server, "brain_dream", { action: "run", step: DREAM_STEP.scan })).isError,
+ ).toBe(false);
+ // The step branch dropped the sink as silently as it dropped the guard.
+ expect(operationsIn(frames)).toEqual(new Set(["dream"]));
+ // ...and the STAGE is the claim this test's name, its docblock and the
+ // `docs/mcp.md` row all make: a step reports under its own name rather
+ // than the five stages of a full pass. Asserting only the operation
+ // left that claim untested - `dream` is the operation on every branch,
+ // so renaming the scan's stage to `plan` kept this green.
+ expect(stagesIn(frames)).toEqual(new Set([DREAM_STEP.scan]));
+});
+
+test("brain_dream step heal-enrich reports under its own stage too", async () => {
+ const frames: JsonRpcNotification[] = [];
+ const server = observedServer(frames);
+ await initialize(server);
+
+ expect(
+ (await callWithToken(server, "brain_dream", { action: "run", step: DREAM_STEP.healEnrich }))
+ .isError,
+ ).toBe(false);
+ // The second of the two runnable steps, so the row's parenthetical
+ // (`scan` / `heal-enrich`) is covered rather than half-covered.
+ expect(operationsIn(frames)).toEqual(new Set(["dream"]));
+ expect(stagesIn(frames)).toEqual(new Set([DREAM_STEP.healEnrich]));
+});
+
test("brain_maintenance names the task whose deadline tripped", async () => {
const server = new MCPServer({ vault, configPath });
await initialize(server);
@@ -282,22 +336,39 @@ test("a live clock leaves all four tools running to completion", async () => {
// The same four tools, observed
// ---------------------------------------------------------------------------
-/** The operations named by the progress events a call emitted. */
-function operationsIn(frames: JsonRpcNotification[]): Set<string> {
+/** One field of the progress events a call emitted, deduplicated. */
+function fieldIn(frames: JsonRpcNotification[], field: "operation" | "stage"): Set<string> {
const seen = new Set<string>();
for (const frame of frames) {
if (frame.method !== PROGRESS_NOTIFICATION_METHOD) continue;
const params = frame.params as Record<
string,
- Record<string, { operation: string; schema: string }>
+ Record<string, { operation: string; stage: string; schema: string }>
>;
const event = params["_meta"]![PROGRESS_META_KEY]!;
expect(event.schema).toBe(PROGRESS_SCHEMA);
- seen.add(event.operation);
+ seen.add(event[field]);
}
return seen;
}
+/** The operations named by the progress events a call emitted. */
+function operationsIn(frames: JsonRpcNotification[]): Set<string> {
+ return fieldIn(frames, "operation");
+}
+
+/**
+ * The stages named by those events.
+ *
+ * A second reader rather than a wider `operationsIn`, because the two
+ * answer different questions: the operation says WHOSE run this is (the
+ * lane's dispatch test turns on it), and the stage says WHERE in that run
+ * it currently is. The step tests are the ones that need the second.
+ */
+function stagesIn(frames: JsonRpcNotification[]): Set<string> {
+ return fieldIn(frames, "stage");
+}
+
/** A server whose notification frames this test can read back. */
function observedServer(frames: JsonRpcNotification[]): MCPServer {
return new MCPServer(
@@ -413,3 +484,81 @@ test("no token leaves every one of them silent", async () => {
await callRaw(server, "brain_clusters", { operation: "run" });
expect(frames).toEqual([]);
});
+
+// ---------------------------------------------------------------------------
+// The prose is derived from the two populations, not asserted beside them
+// ---------------------------------------------------------------------------
+
+/**
+ * `docs/mcp.md` claims "bounded and observed are now the same population
+ * with no exception", and the table under it is the population. That
+ * sentence replaced a `**none**` row - a row that had been wrong for a
+ * release because nothing checked it - so leaving the replacement as
+ * unchecked prose would repeat the failure with better wording.
+ *
+ * Both sides are read rather than written down: the rows come out of the
+ * document and the covered tools come out of THIS file's own calls. A row
+ * for a tool nobody drives here fails, and a row that reads `none` in
+ * either column fails.
+ */
+const BOUNDED_TABLE_HEADER = "| tool | long operation it reaches | deadline | reports |";
+
+interface DocRow {
+ readonly tool: string;
+ readonly subject: string;
+ readonly deadline: string;
+ readonly reports: string;
+}
+
+function boundedTableRows(): ReadonlyArray<DocRow> {
+ const doc = readFileSync(join(import.meta.dir, "..", "..", "docs", "mcp.md"), "utf8");
+ const start = doc.indexOf(BOUNDED_TABLE_HEADER);
+ expect(`the bounded table is present: ${start >= 0}`).toBe("the bounded table is present: true");
+ const body = doc.slice(start).split("\n\n")[0]!;
+ return body
+ .split("\n")
+ .slice(2) // header and separator
+ .filter((line) => line.startsWith("|"))
+ .map((line) => {
+ const cells = line
+ .split("|")
+ .slice(1, -1)
+ .map((c) => c.trim());
+ return {
+ subject: cells[0] ?? "",
+ tool: /`(brain_[a-z_]+)`/.exec(cells[0] ?? "")?.[1] ?? "",
+ deadline: cells[2] ?? "",
+ reports: cells[3] ?? "",
+ };
+ });
+}
+
+/** The tools this file actually drives, read from its own call sites. */
+function toolsCoveredHere(): Set<string> {
+ const self = readFileSync(import.meta.path, "utf8");
+ return new Set(
+ [...self.matchAll(/call(?:Raw|WithToken)\(\s*server,\s*"([a-z_]+)"/g)].map((m) => m[1]!),
+ );
+}
+
+test("every row of the bounded table is bounded, observed, and covered here", () => {
+ const rows = boundedTableRows();
+ // Non-vacuous: a parse that silently stopped matching would sweep an
+ // empty table clean.
+ expect(rows.length).toBeGreaterThan(6);
+
+ const unnamed = rows.filter((r) => r.tool === "").map((r) => r.subject);
+ expect(unnamed.join("\n")).toBe("");
+
+ // "No exception" is exactly this: no row may say a call is unbounded or
+ // unobserved. `**none**` was the spelling the step row used.
+ const exceptions = rows
+ .filter((r) => /none/i.test(r.deadline) || !/^yes/i.test(r.reports))
+ .map((r) => `${r.subject} | ${r.deadline} | ${r.reports}`);
+ expect(exceptions.join("\n")).toBe("");
+
+ // And the table may not name a tool this file leaves untested.
+ const covered = toolsCoveredHere();
+ const untested = [...new Set(rows.map((r) => r.tool))].filter((t) => !covered.has(t));
+ expect(untested.toSorted().join("\n")).toBe("");
+});
diff --git a/tests/mcp/maintenance-parity-census.test.ts b/tests/mcp/maintenance-parity-census.test.ts
new file mode 100644
index 00000000..74113c50
--- /dev/null
+++ b/tests/mcp/maintenance-parity-census.test.ts
@@ -0,0 +1,524 @@
+/**
+ * Surface-parity census over the maintenance lane (what-the-machine-
+ * already-has, unit 5).
+ *
+ * The lane has two front doors - `o2b brain maintenance` and
+ * `brain_maintenance` - and they have drifted apart twice in two
+ * releases. The second drift is the one that made this file: the lane's
+ * own streak refusal tells the caller to re-run with `--retry <task>`,
+ * a CLI flag an MCP caller has no way to reach, so half the callers were
+ * handed a remedy that did not exist on their surface.
+ *
+ * Neither population is written down here. The CLI flags are read out of
+ * the verb's own `parse()` table and the MCP properties out of the
+ * registered tool definition's `inputSchema`, because a census whose
+ * population is a hand-kept list is a list that drifts beside the thing
+ * it was supposed to watch - which is precisely what happened to the two
+ * lane-task lists this unit also collapsed.
+ *
+ * A flag or a property may sit outside the mapping only through
+ * {@link CLI_ONLY} / {@link MCP_ONLY}, each entry carrying a written
+ * reason. Both directions are asserted: a missing counterpart fails, and
+ * so does an exclusion that outlives the flag it excuses, so the map
+ * cannot quietly become a graveyard. {@link CLI_TO_MCP} is checked on
+ * BOTH sides for the same reason - its values were validated against the
+ * declared properties and its keys against nothing, so renaming `--retry`
+ * would have left a dead entry silently excusing a flag that no longer
+ * exists.
+ *
+ * ## Three things a name-only census cannot see
+ *
+ * Names matching is necessary and not sufficient, so three further rules
+ * sit beside it:
+ *
+ * - **Same name, different contract.** `--busy-minutes`, `--busy-
+ * threshold` and `--limit` each took any positive integer on the CLI
+ * while the tool bounded them, so one lane accepted through one door
+ * what it refused at the other. Both surfaces now read the same
+ * ceilings, and "the two refuse the same out-of-range value" is
+ * asserted by DRIVING both rather than by comparing two numbers.
+ * - **Declared and never read.** The populations come from the flag
+ * table and the `inputSchema`, both of which are declarations. A
+ * property nobody consumes would pass a name census cleanly, so each
+ * name must also appear where its surface actually reads it.
+ * - **The root cause, not the symptom:** neither module may spell a
+ * lane task name by hand any more. Both build their task list from
+ * `LANE_TASK`, so a fifth task is added in one place or not at all.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ isLaneTask,
+ LANE_TASK,
+ LANE_TASKS,
+ MAINTENANCE_BUSY_MINUTES_MAX,
+ MAINTENANCE_BUSY_THRESHOLD_MAX,
+} from "../../src/core/brain/maintenance/lane.ts";
+import { MAINTENANCE_JOURNAL_CAP } from "../../src/core/brain/maintenance/journal.ts";
+import { isOperation } from "../../src/core/brain/safeguard.ts";
+import { ADMIN_TOOLS } from "../../src/mcp/brain/admin-tools.ts";
+import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+import { INVALID_PARAMS } from "../../src/mcp/protocol.ts";
+import { runCli } from "../helpers/run-cli.ts";
+import { lexSource } from "../helpers/source-lexer.ts";
+
+const ROOT = join(import.meta.dir, "..", "..");
+const CLI_VERB = join(ROOT, "src", "cli", "brain", "verbs", "maintenance.ts");
+const MCP_MODULE = join(ROOT, "src", "mcp", "brain", "admin-tools.ts");
+
+/** The tool whose schema is the MCP half of the population. */
+const TOOL_NAME = "brain_maintenance";
+
+/** An exclusion reason has to be an argument; forty characters is the floor. */
+const MIN_REASON_LENGTH = 40;
+
+/**
+ * CLI flags whose MCP counterpart is not simply the same name.
+ *
+ * One flag may answer to more than one property: `--window H-H` is two
+ * integers on a surface that has no dashes to parse.
+ */
+const CLI_TO_MCP: Readonly<Record<string, ReadonlyArray<string>>> = Object.freeze({
+ retry: ["retry_tasks"],
+ window: ["window_start_hour", "window_end_hour"],
+});
+
+/** CLI flags with no MCP property, and why. */
+const CLI_ONLY: Readonly<Record<string, string>> = Object.freeze({
+ vault:
+ "the vault is a property of the MCP SESSION, not of a call: the server resolves it once at " +
+ "construction and brain_switch_vault is the surface that changes it.",
+ json:
+ "every MCP answer is structured by construction - the tool returns an object and the " +
+ "transport serializes it - so there is no rendering for a flag to switch.",
+ progress:
+ "a client asks for progress with a _meta progressToken on the request, which the transport " +
+ "turns into the handler's onProgress sink; a boolean argument would be a second way to ask.",
+});
+
+/**
+ * CLI flags the verb reads through a shared helper rather than by name,
+ * mapped to the helper that reads them.
+ *
+ * `flags["<name>"]` is how every other flag is consumed, so the absence
+ * of that spelling normally means nobody reads it. These are the
+ * exceptions, and each names the reader so the waiver dies with it.
+ */
+const CLI_INDIRECT: Readonly<Record<string, string>> = Object.freeze({
+ vault: "brainVerbContext(flags)",
+});
+
+/** MCP properties with no CLI flag, and why. */
+const MCP_ONLY: Readonly<Record<string, string>> = Object.freeze({
+ operation:
+ "run|status arrives as a POSITIONAL on the CLI, which has no flag table entry to enumerate; " +
+ "the verb reads it out of positional[0] and refuses anything else with its usage line.",
+});
+
+/**
+ * One module with its comments blanked and every offset preserved.
+ *
+ * `withoutComments` rather than `code`, because the rule below is about
+ * string LITERALS and the `code` view blanks exactly those contents. A
+ * task name discussed in a docblock is prose, not a hand-written list.
+ */
+function sourceWithoutComments(file: string): string {
+ return lexSource(readFileSync(file, "utf8")).withoutComments;
+}
+
+/**
+ * Every flag the verb declares, read between its `parse()` call and the
+ * `});` that terminates the table. Bounded on both ends so an unrelated
+ * object literal elsewhere in the module cannot leak into the census.
+ */
+function cliFlagNames(): ReadonlyArray<string> {
+ const text = sourceWithoutComments(CLI_VERB);
+ const marker = "parse(argv, {";
+ const start = text.indexOf(marker);
+ expect(`the verb declares a flag table: ${start >= 0}`).toBe(
+ "the verb declares a flag table: true",
+ );
+ const end = text.indexOf("});", start);
+ expect(`the flag table is terminated: ${end > start}`).toBe("the flag table is terminated: true");
+ return [...text.slice(start, end).matchAll(/^ {4}"?([a-z][a-z0-9-]*)"?:\s*\{\s*type:/gm)].map(
+ (m) => m[1]!,
+ );
+}
+
+/** Every property the registered tool definition declares. */
+function mcpPropertyNames(): ReadonlyArray<string> {
+ const tool = ADMIN_TOOLS.find((t) => t.name === TOOL_NAME);
+ expect(`${TOOL_NAME} is registered: ${tool !== undefined}`).toBe(
+ `${TOOL_NAME} is registered: true`,
+ );
+ const schema = tool!.inputSchema as { properties?: Record<string, unknown> };
+ return Object.keys(schema.properties ?? {});
+}
+
+/**
+ * The tool's handler, as source: everything between its declaration and
+ * the tool table that declares the schema.
+ *
+ * Bounded that way on purpose. Every property name appears in the schema
+ * literal by construction, so a census that searched the whole module
+ * would find each one and prove nothing; the handler region is where a
+ * name has to appear for the argument to actually do something.
+ */
+function mcpHandlerSource(): string {
+ const text = sourceWithoutComments(MCP_MODULE);
+ const start = text.indexOf("function toolBrainMaintenance(");
+ expect(`the handler is present: ${start >= 0}`).toBe("the handler is present: true");
+ const end = text.indexOf("export const ADMIN_TOOLS", start);
+ expect(`the handler precedes the tool table: ${end > start}`).toBe(
+ "the handler precedes the tool table: true",
+ );
+ return text.slice(start, end);
+}
+
+/** The properties a CLI flag maps to: its declared aliases, else its snake form. */
+function propertiesFor(flag: string): ReadonlyArray<string> {
+ return CLI_TO_MCP[flag] ?? [flag.replaceAll("-", "_")];
+}
+
+/** The flag a property maps back to: the inverse of {@link propertiesFor}. */
+function flagFor(property: string, flags: ReadonlyArray<string>): string | undefined {
+ return flags.find((flag) => propertiesFor(flag).includes(property));
+}
+
+/**
+ * Lane-task names spelled as a bare string literal, with their module.
+ *
+ * Known imprecision, left in deliberately: this matches a quoted task
+ * name ANYWHERE outside a comment, so a user-facing message that happens
+ * to quote one - `"dream is already running"` - would be reported as a
+ * hand-written list. That is a false positive, not a bug to work around
+ * silently: if you hit it, the fix is to build the sentence from
+ * `LANE_TASK.dream` rather than to loosen this pattern, because the whole
+ * point is that the name has exactly one source. A pattern that tried to
+ * tell a list from a sentence would need a parser and would still guess.
+ */
+function bareLaneTaskLiterals(file: string): ReadonlyArray<string> {
+ const literal = new RegExp(`(["'\`])(${LANE_TASKS.join("|")})\\1`, "g");
+ const label = file.slice(ROOT.length + 1);
+ return [...sourceWithoutComments(file).matchAll(literal)].map((m) => `${label}: ${m[0]}`);
+}
+
+describe("the lane task vocabulary", () => {
+ // `verdict-vocabulary-census.test.ts` scans `src/` for the four-piece
+ // shape and audits every vocabulary it finds, but it reads the VALUES
+ // out of the object literal, and this one's values are `OPERATION`
+ // members rather than fresh strings - deliberately, so a lane task is
+ // by construction an operation with a budget. That keeps LANE_TASK out
+ // of that scan's population, so the same audit is run here instead of
+ // left undone.
+ test("object, membership list and guard agree, and every value is an operation", () => {
+ expect(Object.isFrozen(LANE_TASK)).toBe(true);
+ const values = Object.values(LANE_TASK);
+ expect(values.toSorted()).toEqual([...LANE_TASKS].toSorted());
+ expect(new Set(values).size).toBe(values.length);
+ for (const task of LANE_TASKS) {
+ expect(`${task} is a lane task: ${isLaneTask(task)}`).toBe(`${task} is a lane task: true`);
+ // The linkage the values encode: each surface resolves a safeguard
+ // budget from the task name, and a name that is not an operation
+ // would resolve a key nothing reads.
+ expect(`${task} is an operation: ${isOperation(task)}`).toBe(`${task} is an operation: true`);
+ }
+ for (const outsider of ["", "dreams", "maintenance", "scan"]) {
+ expect(`${outsider} is a lane task: ${isLaneTask(outsider)}`).toBe(
+ `${outsider} is a lane task: false`,
+ );
+ }
+ });
+});
+
+describe("maintenance surface parity", () => {
+ test("every CLI flag reaches the MCP tool or is excluded with a written reason", () => {
+ // One folded comparison so the failure names every flag to act on;
+ // asserting per flag would stop at the first and hide the rest.
+ const properties = new Set(mcpPropertyNames());
+ const unreachable = cliFlagNames()
+ .filter((flag) => CLI_ONLY[flag] === undefined)
+ .filter((flag) => !propertiesFor(flag).every((property) => properties.has(property)))
+ .map((flag) => `--${flag} -> ${propertiesFor(flag).join(" + ")}`);
+ expect(unreachable.toSorted().join("\n")).toBe("");
+ });
+
+ test("every MCP property reaches the CLI verb or is excluded with a written reason", () => {
+ const flags = cliFlagNames();
+ const unreachable = mcpPropertyNames()
+ .filter((property) => MCP_ONLY[property] === undefined)
+ .filter((property) => flagFor(property, flags) === undefined)
+ .map((property) => `${TOOL_NAME}.${property}`);
+ expect(unreachable.toSorted().join("\n")).toBe("");
+ });
+
+ test("no exclusion outlives what it excuses, and every reason says something", () => {
+ const flags = new Set(cliFlagNames());
+ const properties = new Set(mcpPropertyNames());
+ for (const [flag, reason] of Object.entries(CLI_ONLY)) {
+ expect(`--${flag} is still declared: ${flags.has(flag)}`).toBe(
+ `--${flag} is still declared: true`,
+ );
+ expect(`--${flag} has a reason: ${reason.trim().length >= MIN_REASON_LENGTH}`).toBe(
+ `--${flag} has a reason: true`,
+ );
+ }
+ for (const [property, reason] of Object.entries(MCP_ONLY)) {
+ expect(`${property} is still declared: ${properties.has(property)}`).toBe(
+ `${property} is still declared: true`,
+ );
+ expect(`${property} has a reason: ${reason.trim().length >= MIN_REASON_LENGTH}`).toBe(
+ `${property} has a reason: true`,
+ );
+ }
+ // An alias that names a property nobody declares is a mapping that
+ // silently excuses the flag it points at.
+ const dangling = Object.entries(CLI_TO_MCP)
+ .flatMap(([flag, names]) => names.map((name) => `${flag} -> ${name}`))
+ .filter((pair) => !properties.has(pair.split(" -> ")[1]!));
+ expect(dangling.toSorted().join("\n")).toBe("");
+ // ...and the other side of the same arrow. A key naming a flag the
+ // verb no longer declares excuses nothing and hides that it excuses
+ // nothing: rename `--retry` and the two name-parity tests above stay
+ // green while this entry rots.
+ const orphanedKeys = Object.keys(CLI_TO_MCP).filter((flag) => !flags.has(flag));
+ expect(orphanedKeys.toSorted().join("\n")).toBe("");
+ });
+
+ test("every declared name is read by the surface that declares it", () => {
+ // Both populations are DECLARATIONS. A flag in the table that the
+ // verb never reads, or a schema property the handler never consumes,
+ // is a promise on the surface with nothing behind it - and it passes
+ // a name census cleanly, because the name is right there.
+ const cli = sourceWithoutComments(CLI_VERB);
+ const unreadFlags = cliFlagNames()
+ .filter((flag) => CLI_INDIRECT[flag] === undefined)
+ .filter((flag) => !cli.includes(`flags["${flag}"]`))
+ .map((flag) => `--${flag}`);
+ expect(unreadFlags.toSorted().join("\n")).toBe("");
+
+ // The indirect readers are named rather than waived: the helper that
+ // consumes the flag has to still be called here.
+ for (const [flag, helper] of Object.entries(CLI_INDIRECT)) {
+ expect(`--${flag} is read via ${helper}: ${cli.includes(helper)}`).toBe(
+ `--${flag} is read via ${helper}: true`,
+ );
+ }
+
+ const handler = mcpHandlerSource();
+ const unreadProperties = mcpPropertyNames()
+ .filter((property) => !handler.includes(`"${property}"`))
+ .map((property) => `${TOOL_NAME}.${property}`);
+ expect(unreadProperties.toSorted().join("\n")).toBe("");
+ });
+
+ test("the census is not vacuous", () => {
+ // A extraction that silently stopped matching would report a clean
+ // sweep over an empty set. Pin the measurement, not only its verdict.
+ expect(cliFlagNames().length).toBeGreaterThan(8);
+ expect(mcpPropertyNames().length).toBeGreaterThan(8);
+ expect(LANE_TASKS.length).toBeGreaterThan(3);
+ });
+
+ test("neither surface spells a lane task by hand any more", () => {
+ // The root cause, not the symptom: two hand-written task lists are
+ // what let the surfaces disagree in the first place.
+ expect(
+ [...bareLaneTaskLiterals(CLI_VERB), ...bareLaneTaskLiterals(MCP_MODULE)].join("\n"),
+ ).toBe("");
+ });
+});
+
+/**
+ * One out-of-range value per bounded knob, in both spellings.
+ *
+ * The ceilings are imported, never retyped, and each case sits one past
+ * its own ceiling - so raising a bound moves these cases with it and a
+ * bound that disappears from one surface fails here rather than in a
+ * user's vault.
+ */
+interface OutOfRangeCase {
+ readonly label: string;
+ readonly operation: "run" | "status";
+ readonly cli: ReadonlyArray<string>;
+ readonly mcp: Record<string, number>;
+}
+
+// Annotated before freezing rather than inside it: `Object.freeze` is
+// generic, so its argument gets no contextual type, and TypeScript then
+// widens these three literals into a union in which each one carries the
+// other two's keys as `?: undefined` - which no `Record<string, number>`
+// accepts.
+const OUT_OF_RANGE_CASES: ReadonlyArray<OutOfRangeCase> = [
+ {
+ label: "busy-minutes past a day",
+ operation: "run",
+ cli: ["--busy-minutes", String(MAINTENANCE_BUSY_MINUTES_MAX + 1)],
+ mcp: { busy_minutes: MAINTENANCE_BUSY_MINUTES_MAX + 1 },
+ },
+ {
+ label: "busy-threshold past any real traffic",
+ operation: "run",
+ cli: ["--busy-threshold", String(MAINTENANCE_BUSY_THRESHOLD_MAX + 1)],
+ mcp: { busy_threshold: MAINTENANCE_BUSY_THRESHOLD_MAX + 1 },
+ },
+ {
+ label: "limit past the journal's ring size",
+ operation: "status",
+ cli: ["--limit", String(MAINTENANCE_JOURNAL_CAP + 1)],
+ mcp: { limit: MAINTENANCE_JOURNAL_CAP + 1 },
+ },
+];
+
+const OUT_OF_RANGE = Object.freeze(OUT_OF_RANGE_CASES);
+
+describe("the two surfaces refuse the same values, not only the same names", () => {
+ let tmp: string;
+ let vault: string;
+ let configPath: string;
+
+ beforeEach(async () => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-maint-bounds-"));
+ vault = join(tmp, "vault");
+ mkdirSync(vault, { recursive: true });
+ configPath = join(tmp, "config.yaml");
+ writeFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
+ const init = await runCli(["brain", "init", "--vault", vault], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
+ });
+ expect(init.returncode).toBe(0);
+ });
+
+ afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+ });
+
+ for (const casing of OUT_OF_RANGE) {
+ test(`${casing.label}: refused by the verb and by the tool`, async () => {
+ const cli = await runCli(
+ ["brain", "maintenance", casing.operation, ...casing.cli, "--vault", vault],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: configPath } },
+ );
+ // Understood and declined: a usage exit, nothing attempted. The
+ // lane must never START on a number the other door refuses.
+ expect(cli.returncode).toBe(2);
+
+ const server = new MCPServer({ vault, configPath });
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: { protocolVersion: PROTOCOL_VERSION },
+ });
+ const res = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 2,
+ method: "tools/call",
+ params: {
+ name: TOOL_NAME,
+ arguments: { operation: casing.operation, ...casing.mcp },
+ },
+ })) as { error?: { code: number } };
+ expect(res.error?.code).toBe(INVALID_PARAMS);
+ });
+ }
+
+ test("retry_tasks longer than the lane has tasks is refused, not merely advertised", async () => {
+ // `maxItems` on the schema is advertisement: no JSON-Schema validator
+ // runs on the request path, and the unknown-argument guard checks
+ // names rather than shapes. So the handler owes the check itself -
+ // without it a thousand-entry array was accepted while the schema
+ // said it could not be.
+ const server = new MCPServer({ vault, configPath });
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: { protocolVersion: PROTOCOL_VERSION },
+ });
+ const tool = ADMIN_TOOLS.find((t) => t.name === TOOL_NAME)!;
+ const schema = tool.inputSchema as {
+ properties: { retry_tasks: { maxItems?: number } };
+ };
+ const advertised = schema.properties.retry_tasks.maxItems;
+ expect(advertised).toBe(LANE_TASKS.length);
+ const res = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 2,
+ method: "tools/call",
+ params: {
+ name: TOOL_NAME,
+ arguments: {
+ operation: "run",
+ // Every entry a REAL lane task, so the only thing wrong with
+ // the request is its length.
+ retry_tasks: Array.from({ length: advertised! + 1 }, () => LANE_TASK.dream),
+ },
+ },
+ })) as { error?: { code: number; message: string } };
+ expect(res.error?.code).toBe(INVALID_PARAMS);
+ expect(res.error?.message).toContain(String(advertised));
+ });
+});
+
+describe("an unknown retry name is refused by name on both surfaces", () => {
+ let tmp: string;
+ let vault: string;
+ let configPath: string;
+
+ beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-maint-parity-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ configPath = join(tmp, "config.yaml");
+ writeFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
+ });
+
+ afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+ });
+
+ test("the CLI and the tool both name the typo and list the known tasks", async () => {
+ const init = await runCli(["brain", "init", "--vault", vault], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
+ });
+ expect(init.returncode).toBe(0);
+
+ const cli = await runCli(
+ ["brain", "maintenance", "run", "--retry", "dreams", "--vault", vault],
+ {
+ env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
+ },
+ );
+ expect(cli.stderr).toContain("dreams");
+ for (const task of LANE_TASKS) expect(cli.stderr).toContain(task);
+
+ const server = new MCPServer({ vault, configPath });
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: { protocolVersion: PROTOCOL_VERSION },
+ });
+ const res = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 2,
+ method: "tools/call",
+ params: {
+ name: TOOL_NAME,
+ arguments: { operation: "run", retry_tasks: ["dreams"] },
+ },
+ })) as { error?: { code: number; message: string } };
+ // A bad argument, so it comes back as INVALID_PARAMS rather than as a
+ // tool result carrying isError - the same shape the CLI's usage exit
+ // has: the request was understood and refused, nothing was attempted.
+ const message = res.error?.message ?? "";
+ expect(res.error?.code).toBe(INVALID_PARAMS);
+ expect(message).toContain("dreams");
+ for (const task of LANE_TASKS) expect(message).toContain(task);
+ });
+});
diff --git a/tests/mcp/vault-health-state-surfaces.test.ts b/tests/mcp/vault-health-state-surfaces.test.ts
new file mode 100644
index 00000000..661dc50e
--- /dev/null
+++ b/tests/mcp/vault-health-state-surfaces.test.ts
@@ -0,0 +1,92 @@
+/**
+ * `vault_health` carries the in-vault state inventory.
+ *
+ * The doctor answers "is this vault healthy". It could not answer "and
+ * where does it keep its state", which is the question an agent has to
+ * settle before it proposes moving or deleting anything. The field is the
+ * SAME value `o2b state status` prints - one record, two renderings - so
+ * this file asserts the identity rather than the content: a second
+ * hand-assembled copy would pass a "both are present" check and drift on
+ * the next row added.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { MCPServer } from "../../src/mcp/index.ts";
+import {
+ inventoryStateSurfaces,
+ STATE_SURFACES,
+ type StateInventory,
+} from "../../src/core/state/surfaces.ts";
+import { createSandboxVault } from "../helpers/fixtures.ts";
+import { PARTNER_CODEGRAPH_DISABLED_ENV } from "../../src/core/config.ts";
+
+async function health(vault: string): Promise<Record<string, unknown>> {
+ const server = new MCPServer({ vault });
+ const r = (await server.handleRequest({
+ jsonrpc: "2.0",
+ id: 1,
+ method: "tools/call",
+ params: { name: "vault_health", arguments: {} },
+ })) as { result: { structuredContent: Record<string, unknown> } };
+ return r.result.structuredContent;
+}
+
+describe("vault_health state surfaces", () => {
+ // The doctor consults the codegraph partner whenever that binary is on
+ // PATH, which costs seconds per call and tells this file nothing.
+ let saved: string | undefined;
+ beforeAll(() => {
+ saved = process.env[PARTNER_CODEGRAPH_DISABLED_ENV];
+ process.env[PARTNER_CODEGRAPH_DISABLED_ENV] = "true";
+ });
+ afterAll(() => {
+ if (saved === undefined) delete process.env[PARTNER_CODEGRAPH_DISABLED_ENV];
+ else process.env[PARTNER_CODEGRAPH_DISABLED_ENV] = saved;
+ });
+
+ test("the tool reports one row per declared surface", async () => {
+ const tmp = mkdtempSync(join(tmpdir(), "o2b-vault-health-state-"));
+ try {
+ const vault = createSandboxVault(tmp);
+ const payload = await health(vault);
+ const inventory = payload["state_surfaces"] as StateInventory;
+ expect(inventory.vault).toBe(vault);
+ expect(inventory.surfaces.length).toBe(STATE_SURFACES.length);
+ } finally {
+ rmSync(tmp, { recursive: true, force: true });
+ }
+ });
+
+ test("the field is the inventory value itself, not a second copy of it", async () => {
+ const tmp = mkdtempSync(join(tmpdir(), "o2b-vault-health-state-"));
+ try {
+ const vault = createSandboxVault(tmp);
+ const payload = await health(vault);
+ const direct = inventoryStateSurfaces({
+ vault,
+ env: process.env,
+ config: {},
+ });
+ expect(payload["state_surfaces"]).toEqual(direct);
+ } finally {
+ rmSync(tmp, { recursive: true, force: true });
+ }
+ });
+
+ test("the existing health fields are untouched", async () => {
+ const tmp = mkdtempSync(join(tmpdir(), "o2b-vault-health-state-"));
+ try {
+ const vault = createSandboxVault(tmp);
+ const payload = await health(vault);
+ expect(Array.isArray(payload["checks"])).toBe(true);
+ expect(Array.isArray(payload["notices"])).toBe(true);
+ expect(payload["vault_path"]).toBeDefined();
+ } finally {
+ rmSync(tmp, { recursive: true, force: true });
+ }
+ });
+});