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(brain): integrity & safety hardening suite (1.21.0) (#115)

Sol Aitken4281605860e7
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index fce56703..567c145e 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.20.0",
+ "version": "1.21.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 5997b451..f2783853 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.20.0",
+ "version": "1.21.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/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 15dda1c5..d43adac7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -43,6 +43,9 @@ jobs:
- name: Verify manifest version sync
run: bun run sync-version:check
+ - name: Hardcoded path hygiene (report-only)
+ run: bun run check:paths
+
- name: Formatting check
run: bun run fmt:check
diff --git a/.gitignore b/.gitignore
index 3bdbf047..dc3ffd1b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,3 +26,6 @@ sandbox-vault/
.orphaned_at
.claude/scheduled_tasks.lock
.open-second-brain/bench-runs/
+
+# Local Kanban/git worktrees (never committed; exclude from lint/fmt)
+.worktrees/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b7a0c131..71f494bd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,49 @@ 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.21.0] - 2026-07-04
+
+A safety-hardening pass around the surfaces that write to or trust the
+vault and the codegraph. Each change tightens a boundary or closes a
+silent-loss gap; none changes default behaviour when the new path is
+unused, and the kernel still calls no LLM.
+
+### Added
+
+- **Fail-closed redactor scan window and opt-in infra-topology
+ detectors.** The secret redactor now enforces a hard 1 MiB input
+ window and fails closed instead of silently truncating oversized
+ input, so a too-large document can no longer slip past redaction. Two
+ opt-in detector families (hostnames that resolve to a private range,
+ and well-known infrastructure tokens) extend coverage beyond secrets
+ when enabled; off by default, the shipped redaction set is unchanged.
+- **Read-only codegraph health gate before labeling and import.** Before
+ the partner surface mutates the codegraph (labeling, edge import), it
+ runs a read-only `codegraph health` check and refuses the write when
+ the index reports stale, partial, or inconsistent state, instead of
+ importing into a graph it cannot trust.
+- **Report-only hardcoded-path check for shipped surfaces.** A new
+ `check-hardcoded-paths` script scans the shipped source for absolute
+ or machine-local paths and reports them, without failing a build on
+ pre-existing hits, so path leakage stays visible without blocking
+ history it did not create.
+- **Memory cost meter: write-volume versus read accounting.** The
+ recall-telemetry surface now separates memory write volume from read
+ volume, so a runaway writer (a provider looping on store) is
+ distinguishable from a busy reader in the same numbers.
+
+### Changed
+
+- **Stable `unnamed-<hash>` slug fallback for punctuation-only titles.**
+ A note whose title collapses to empty after slugification now gets a
+ deterministic `unnamed-<hash>` slug instead of colliding into a single
+ shared `unnamed` note, so distinct punctuation-only titles no longer
+ overwrite one another.
+- **Portable session-provenance key.** Session import records its
+ provenance as a stable logical key rather than the absolute
+ session-file path, so a vault moved between machines no longer breaks
+ session provenance lookups.
+
## [1.20.0] - 2026-06-28
Two optional, opt-in config keys widen the agent skill surface without
@@ -6075,6 +6118,8 @@ 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.21.0]: https://github.com/itechmeat/open-second-brain/compare/v1.20.0...v1.21.0
+[1.20.0]: https://github.com/itechmeat/open-second-brain/compare/v1.19.1...v1.20.0
[1.19.1]: https://github.com/itechmeat/open-second-brain/compare/v1.19.0...v1.19.1
[1.19.0]: https://github.com/itechmeat/open-second-brain/compare/v1.18.1...v1.19.0
[1.18.1]: https://github.com/itechmeat/open-second-brain/compare/v1.18.0...v1.18.1
diff --git a/README.md b/README.md
index 22fe99e9..4dd89985 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ Open Second Brain plugs into [Hermes Agent](https://github.com/NousResearch/herm
## What is new
-Open Second Brain 1.19.0 closes two session-boundary durability gaps that silently lost or distorted memory, and it adds a deterministic post-compaction survival audit for pinned context. When the host runtime reports an interrupted shutdown, the agent now honours the flag, consumes the persisted pre-restart transcript, and runs its turns through the same extraction as a live prompt, so a SIGHUP or force-quit no longer leaves the conversation without a memory trace. A new LLM-free post-compaction audit detects when a pinned anchor has drifted into a context summary and selectively re-asserts only the drifted anchors, keeping the long-conversation memory the pinned store was built to protect. Both behaviours are off by default and byte-identical when unused, and the kernel still calls no LLM.
+Open Second Brain 1.21.0 is a safety-hardening pass around the surfaces that write to or trust the vault and the codegraph. The secret redactor now enforces a fail-closed 1 MiB scan window instead of silently truncating oversized input (always on), with opt-in infrastructure-topology detectors that extend coverage beyond secrets when enabled. Before the partner surface mutates the codegraph, a read-only health check refuses the write when the index is stale or inconsistent rather than importing into a graph it cannot trust (always on). A report-only hardcoded-path check surfaces path leakage in shipped source without failing on pre-existing hits (always on), and the recall-telemetry cost meter now separates memory write volume from read volume (always on). Two quiet loss and collision gaps close as well: punctuation-only note titles get a deterministic `unnamed-<hash>` slug instead of collapsing into one shared note (always on), and session provenance is recorded as a stable logical key so a vault moved between machines keeps its lookups (always on). The opt-in pieces (the extra infra-topology detectors) are off by default and byte-identical when the new path is unused, and the kernel still calls no LLM.
## Why
diff --git a/docs/brainstorm/brain-integrity-safety-hardening/cli-output/claude.md b/docs/brainstorm/brain-integrity-safety-hardening/cli-output/claude.md
new file mode 100644
index 00000000..1f1dcc7f
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-safety-hardening/cli-output/claude.md
@@ -0,0 +1,49 @@
+## 1. Three architectural variants
+
+### Variant 1 β€” Primitive-first (extract the shared substrate, then wire consumers)
+
+**Approach:** Land three cross-cutting primitives before any feature task, then build the nine tasks as thin consumers of them: (1) a **write-boundary chokepoint** built on the existing `proper-lockfile` writer-lock/lease pattern (`store.ts:228`, `maintenance/lease.ts`) that both serializes all Brain writes (A) and exposes a single instrumentation seam for write-volume accounting (I); (2) a **linear-bounded corpus-scan detector harness** hosted in the maintenance lane's quiet window that `context-guard`'s `TEXT_PATTERNS` (C), the redactor's new infra-topology detectors (D), and the path-hygiene check (G) all register into; (3) a **unified findings/health-gate reporter** feeding `doctor`/`vault_health` that the graph-health gate (E) and hygiene checks surface through. B, F, and H then land as independent leaves.
+
+**Trade-offs:**
+- Pro: maximal DRY β€” the ReDoS-linearity contract, the lease acquisition, and the findings shape are each written and tested once.
+- Pro: coherent operator surfaces (one findings vocabulary across injection/graph/path).
+- Con: front-loads abstraction risk β€” primitives must be designed for consumers not yet built; wrong guess forces rework.
+- Con: primitive PRs are byte-identical-when-off *and* feature-invisible, which fights the "one atomic commit ships one unit" grain and complicates CHANGELOG framing.
+- Con: sequences the concurrency-invariant change (A) earliest, before any safety net exists.
+
+**Complexity:** large. **Risk:** medium-high.
+
+---
+
+### Variant 2 β€” Thematic vertical slices (the release's own three sub-themes)
+
+**Approach:** Ship three cohesive, individually-demoable verticals matching the stated theme. **Write-time integrity discipline:** A (single-writer lane), E (graph-health gate), H (safe fallback names). **Cross-machine portability:** B (scan-root-relative keys), G (hardcoded-path hygiene), I (write cost meter). **Corpus-level safety:** C (injection sweep), D (redactor fail-closed + topology detectors), F (signed grounding score). Extract a shared primitive only *within* a slice where two members genuinely share one β€” e.g. C and D share the linear-regex detector contract inside the safety slice.
+
+**Trade-offs:**
+- Pro: each slice maps to a release-narrative section and a self-contained CHANGELOG story.
+- Pro: moderate, low-risk reuse that stays inside a slice boundary.
+- Con: misses the strongest cross-slice couplings β€” A's write chokepoint (integrity slice) and I's write meter (portability slice) instrument the *same* boundary but never meet; C's corpus scan (safety) and G's hygiene detector (portability) want the same registry harness across slices.
+- Con: some duplicated scan/reporting scaffolding across slices.
+
+**Complexity:** medium. **Risk:** medium.
+
+---
+
+### Variant 3 β€” Risk-ordered incremental, minimal abstraction (refactor-on-second-use)
+
+**Approach:** Ignore grouping; sequence all nine strictly by blast radius, landing byte-identical-when-off, report-only leaves first and the concurrency-invariant change last. Order: **G, H, I, E** (additive/report-only) β†’ **B, F** (read-time derivations / append-only projections, no history mutation) β†’ **C, D** (deterministic scanners behind flags) β†’ **A** (single-writer lane, which touches the write path every other task depends on). Each task ships self-contained via TDD as one atomic commit; shared primitives are extracted opportunistically only when a second real consumer appears β€” the ordering *engineers* those second-use points (I meters at A's chokepoint because A lands after it is anticipated; D shares C's linear-regex detector because D follows C).
+
+**Trade-offs:**
+- Pro: lowest per-step risk; the tree is always shippable and every step is independently revertible.
+- Pro: cleanly honors "one unit, one branch, one atomic commit" and the repo's read-time-derive precedent (F, E, I compute at read time, nothing new persisted).
+- Pro: the invariant-touching write-lane (A) lands *after* the health gate, cost meter, and safety scanners exist β€” the safety net precedes the risky change.
+- Con: least upfront DRY; reuse emerges via ordering rather than design, risking minor rework if a late task reveals a primitive an early task could have shared.
+- Con: no single unifying architecture diagram; A's cross-cutting benefit arrives latest.
+
+**Complexity:** medium. **Risk:** low.
+
+---
+
+## Recommended: Variant 3
+
+The repo's stated grain β€” "each suite unit ships one-by-one via TDD on a single feature branch, one atomic conventional commit per task" β€” plus byte-identical-when-off makes Variant 1's speculative primitives a poor fit: a primitive PR changes no observable behavior and can't be validated by its own acceptance test, and the codebase's *only* principled persisted-derivation exception (memoized side-indexes) signals a strong refactor-on-second-use culture rather than design-for-reuse-upfront. Risk ordering also respects the standing invariants directly: the concurrency-touching single-writer lane (A) is the one task that can destabilize every other write path, so landing it last β€” after E's non-aborting health gate, I's write meter, and the C/D safety scanners are already in place β€” means the "safety hardening" net exists before the riskiest change, and A's `proper-lockfile` chokepoint becomes the natural, already-anticipated second-use seam where I's write accounting attaches. F, E, and I stay pure read-time projections over the append-only ledger and telemetry (no history mutation, nothing new on disk), and B/G/H remain independent leaves, so the sequence keeps every step revertible and honestly opt-in without forcing a big-bang abstraction the conventions would struggle to justify.
diff --git a/docs/brainstorm/brain-integrity-safety-hardening/cli-output/prompt.md b/docs/brainstorm/brain-integrity-safety-hardening/cli-output/prompt.md
new file mode 100644
index 00000000..3ba401c5
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-safety-hardening/cli-output/prompt.md
@@ -0,0 +1,104 @@
+# Brainstorm: Open Second Brain β€” "Brain Integrity & Safety Hardening" suite
+
+You are a senior backend architect. The project owner needs exactly **3 distinct architectural variants** for how to structure a 9-task release, then a single recommendation. Be concrete and grounded in the real codebase facts below. **No code.** Only the sections listed at the bottom.
+
+## Project facts (grounding β€” do not contradict)
+
+**Open Second Brain (o2b)** is an Obsidian-native memory layer for AI agents. Plain Markdown the user owns, in a vault synced across VPS/Mac/Android via Syncthing. No daemon, no vector black box, no hidden state outside the vault. The plugin NEVER calls an LLM itself β€” the agent owns generation, the vault owns the durable record. Every behaviour is opt-in and byte-identical-when-off.
+
+- **Runtime/language**: TypeScript + Bun (`"type": "module"`). Node `node:fs` / `node:path` only. No new runtime dependency is ever added casually.
+- **Testing**: `bash scripts/test`. Tooling: `tsc --noEmit`, `oxlint`, `oxfmt`. `bun run validate` = typecheck + lint + test.
+- **Only runtime dependency**: `proper-lockfile` (already used by the search store writer lock and maintenance lease).
+- **MCP-first**: the writer/reader tools are exposed as MCP tools (`src/mcp/tools.ts`, `src/mcp/brain/`). The CLI (`src/cli/`) is a thin layer over the same core. OpenClaw reads/writes the vault directly with `node:fs`.
+- **Current version**: 1.20.0. Each release bumps README + CHANGELOG + package.json (`scripts/sync-version.ts`).
+- **Architecture layers**: Agent runtime β†’ runtime adapter/plugin β†’ skills and commands β†’ CLI/core library β†’ vault files and local config. Core (`src/core/`) is runtime-agnostic and deterministic.
+
+## Standing project conventions (every variant MUST honor these)
+
+1. **No hidden daemon.** OSB is filesystem-first and can be called by many runtimes concurrently. No mandatory long-running process. Any coordination must use an explicit write session, file lock, or cooperative queue compatible with Syncthing and process exit.
+2. **Deterministic, no LLM inside the kernel.** Counters, atomic file moves, regex. The plugin never runs a model. Memory "learns" via a nightly `dream` pass.
+3. **Byte-identical-when-off.** Every new capability is opt-in behind a flag/verb. The default path changes nothing.
+4. **No misleading fallbacks.** A verb that silently no-ops when its backend is absent is forbidden. Fail loudly or report honestly.
+5. **Read-time-derive precedent.** The repo prefers computing derived views at read time over persisting them (`recall-hint.ts`, `enrich.ts`). The single principled exception in the codebase is in-memory side-indexes memoized + invalidated on store version (never SQLite-persisted for derived data).
+6. **Path-safety chokepoint.** Every write funnels through `ensureInsideVault(target, vault)` (`src/core/path-safety.ts`), which resolves `..`, follows symlinks for the deepest existing ancestor, and re-runs a lexical prefix check. The write-session commit chokepoint re-resolves every target through it.
+7. **Atomic writes.** `atomicWriteFileSync` / `atomicCreateFileSyncExclusive` for all vault mutations; verified snapshots before mutations.
+8. **English-only strings, abstract multi-language.** No natural-language word lists in any algorithm; tokenizers emit CJK bigrams structurally.
+9. **SOLID / KISS / DRY.** No hardcoding. Each suite unit ships one-by-one via TDD on a single feature branch, one atomic conventional commit per task.
+
+## Recent git log (for style/conventions; current branch is `feat/brain-integrity-safety-hardening`)
+
+```
+313d061 feat: configurable skills_dir + trigger-keyword auto-attach scoring (#114)
+a3ea315 fix: v1.19.1 - cross-vault cards, event-trace exit codes, registry-guard hygiene (#113)
+bb5f320 feat(brain): session-boundary capture durability and post-compaction pinned-anchor survival audit (v1.19.0) (#112)
+c5e30b8 fix: cross-vault chain-stop reads the max normalized score (v1.18.1) (#111)
+33b4fba feat: recall precision, coverage, and provenance hardening (v1.18.0) (#110)
+254b580 feat: codegraph link-graph depth and MCP exposure (v1.17.0) (#108)
+da2e3cc feat: memory subsystem alignment - honest pinned budgets, atomic batch writes, on_memory_write host bridge (v1.16.0) (#107)
+9295e28 feat: Brain Portability & Interop Suite - bank export/import, page contract, brain_create_note, in-process SDK (v1.9.0) (#98)
+6e59a42 feat: Vault Integrity & Trust Suite - untrusted-source containment, NFC identity, watch-sync, O(1) graph, agent-scope (v1.6.0) (#95)
+```
+
+## The 9 in-scope tasks (verbatim bodies + verified code anchors)
+
+This release's theme: **write-time integrity discipline, cross-machine portability, and corpus-level safety** β€” the architectural strip that the project's own triage ranks as priority-4 (core) plus three thematically aligned p3 tasks.
+
+### Task A β€” `t_559fbe1f` (p4): Single-writer queue for concurrent Brain writes
+Introduce a single-writer queue or lease-backed write lane for concurrent OSB writes from MCP tools, hooks, imports, and scheduled jobs, WITHOUT violating the no-hidden-daemon invariant. Concurrent writes to the same Brain artifacts risk races, lost updates, or noisy Syncthing conflict files; serializing write operations gives deterministic ordering and clearer failure/retry.
+- **Anchors**: search store already has `acquireWriterLockSync` (`proper-lockfile.lockSync`, `realpath:false`, stale-ms guard) at `src/core/search/store.ts:228`. Maintenance lane has an expiring SQLite lease (`src/core/brain/maintenance/lease.ts` `acquireLease/releaseLease`, `MAINTENANCE_LEASE_TTL_MS`, never bypassable) and `runMaintenance` is sequential-by-design. Write-session commit chokepoint at `src/core/brain/write-session/engine.ts:347`. No general single-writer queue across ALL Brain writes exists yet.
+- **Constraint**: prefer an explicit write session / file lock / cooperative queue. Never a mandatory daemon.
+
+### Task B β€” `t_e032ff18` (p4): Portable graph/index artifact keys (scan-root-relative, not absolute)
+Store OSB-generated graph/index artifacts (codegraph manifest, node/edge/hyperedge source references, search/embedding index keys, generation reports) using keys relative to the vault scan root instead of absolute machine-local paths. Syncthing syncs the vault across 3 devices, so any `/root/vault/...` key is stale/unmatched on every other device, forcing full re-extraction/re-index instead of incremental reuse.
+- **Anchors**: search store already stores document paths as **vault-relative POSIX** (`readonly path: string; // vault-relative POSIX`, `store.ts:46,537,553,566,579`); content_hash + mtime drive the unchanged-file fastpath. The open question is whether the CODEGRAPH artifacts (manifest.json keys, graph.json `source_file`, generation reports) and any embedding-index keys carry absolute paths β€” `src/core/partner/codegraph-report.ts` resolves `manifestPath`/project dir but the emitted on-disk graph artifact key format is NOT yet verified from hints. `path-safety.ts` `vaultRelative` is about sandboxing writes (different concern from manifest-key portability).
+- **Note**: must confirm the actual on-disk key format first; if some readers already store relative paths, scope down to only the absolute-leaking readers.
+
+### Task C β€” `t_aec23bd0` (p4): Scheduled corpus-wide prompt-injection sweep
+A scheduled, corpus-wide prompt-injection sweep as a phase of the memory health check (fsck): regex-scan EVERY stored memory for injection payloads (instruction-override, role impersonation, delimiter/boundary spoofing), NO LLM, with findings surfaced for auto-fix or quarantine. Closes the gap where a poisoned memory that got persisted (via an untrusted ingested source / hostile pasted log) sits in the vault and is only caught at read time.
+- **Anchors**: the injection-pattern detector ALREADY EXISTS β€” `src/core/brain/safety/context-guard.ts` exports `TEXT_PATTERNS` (frozen ReadonlyArray of `DetectionPattern`) covering `prompt_injection.instruction_override` / `delimiter_spoof` / `secret_exfiltration`, plus `contextSafetyReport`, `guardBrainContextSnippet`, `detectText`. Today it fires only at read-time context assembly. Grep confirms context-guard is NOT wired into hygiene/doctor/maintenance as a corpus scan. Host: the maintenance lane (`runMaintenance`, leased, quiet-window, sequential) and the hygiene scan registry (`src/core/brain/hygiene/scan.ts` + detectors dir: conflicts/dedup/freshness/id/usefulness).
+- **Constraint**: deterministic regex, no LLM. Land in the existing lane so it runs in the quiet window with the lease. Findings flow to the operator (quarantine/auto-fix), NEVER silent deletion.
+
+### Task D β€” `t_de2ccadd` (p4): Redactor fail-closed past scan ceiling + infra-topology detectors
+OSB's `redactRawOutput` (`src/core/redactor.ts`) truncates input to `MAX_REDACTOR_INPUT = 256 * 1024` and SILENTLY drops the tail past the cut (`out.slice(0, maxInput) + TRUNCATION_MARKER`), so secrets/infra beyond 256KB are neither scanned nor flagged. Two independent fixes: (1) make oversized input FAIL-CLOSED β€” a `scan_truncated` marker that demotes/excludes rather than treating the unscanned tail as clean; (2) add an infra-topology detector family (bare `public_ipv4`/`public_ipv6`, `basic_auth_url`, `fqdn_port`, `ipv4_port`, `internal_host`) β€” today only `key=value`/Bearer-shaped secrets are caught, so a bare public IP or internal hostname is never redacted. MCP artifact-store already scans the full payload (`maxInput: Number.POSITIVE_INFINITY`), so window size is moot there but the topology detectors still apply.
+- **Anchors**: `SECRET_KEYS` list (key=value/Bearer family only) lines 53–69; known-literal pre-scrub lines 161–168; silent truncate at 171; MCP caller at 141–145.
+- **Constraint**: upstream bounds the detector regexes to stay LINEAR β€” port that property to avoid ReDoS on large inputs. Fail-closed marker on the 256KB receipts path; infra-topology detectors benefit the artifact-store path most.
+
+### Task E β€” `t_301db77e` (p4): Read-only graph health gate before labeling/import
+Run a read-only graph-health gate after graph/index construction and before labels, imports, or downstream recall surfaces trust the graph. Surface dangling references, self-loops, collapsed-edge warnings, and cache-root mismatches WITHOUT aborting the run. Prevents subtly-wrong-but-syntactically-present graph structure from being promoted into agent context or vault artifacts.
+- **Anchors**: `vault_health` MCP tool at `src/mcp/tools.ts:381`; brain diagnostics at `src/mcp/brain/health-tools.ts`. No `diagnose_extraction` equivalent, no graph-health gate tied to codegraph labeling/import found.
+- **Constraint**: report warnings in existing health/doctor surfaces; stay non-destructive.
+
+### Task F β€” `t_4678a91a` (p4): Signed source-diversity grounding score for contested truth-ledger slots
+Replace the binary CONTESTED flag with a signed grounding score on a βˆ’1.0..+1.0 scale, computed from the balance of confirming vs contradicting evidence across INDEPENDENT sources (not raw mention count), weighted by relationship strength, plus a separate confidence/sufficiency dimension. Kappa weights N mentions in one document far below N mentions across N independent sources.
+- **Anchors**: contested-slot detection (binary, to extend) β€” `src/core/brain/truth/conflicts.ts` `withinWindow`/CONTESTED, `CONFLICT_WINDOW_DAYS=30`, `computeTruthStateWithConflicts`. Claim ledger w/ independent source+agent provenance (the INPUT signal) β€” `src/core/brain/truth/types.ts` `ClaimEvent` (entity/aspect/value/source/agent/valueKind), `ClaimVersion` (carries `count` = how many events asserted this value). Derived truth projection (where a score would compute) β€” `src/core/brain/truth/fold.ts` `computeTruthState`, `slotKey`, `normalizeClaimValue`. Unsigned confidence bands (to generalize) β€” `src/core/brain/page-meta/confidence.ts` `PageConfidence`/`BRAIN_CONFIDENCE` (high/medium/low).
+- **Constraint**: deterministic (counting + weighting, no LLM). Score is a PROJECTION over the append-only claim ledger β€” do NOT mutate history; compute alongside the existing fold. Source-diversity weighting (independent sources > repeated mentions) is the part o2b lacks entirely.
+
+### Task G β€” `t_44f91e9b` (p3): Hardcoded absolute path hygiene check
+Add a deterministic hygiene check that flags hardcoded home/absolute paths in OSB source, docs, generated examples, and plugin config templates. OSB installs across different machines and vault roots; hardcoded paths leak private host assumptions and cause broken installs or unsafe copy-paste.
+- **Anchors**: `docs/brainstorm/hermes-memory-provider/design.md:40` distinguishes vault path from `hermes_home`; text search finds hardcoded-path concerns in brainstorm docs but no shipped lint/hygiene command scanning source+docs. Host: the doctor surface (`src/core/brain/doctor.ts` `runDoctor` β†’ `DoctorIssue` w/ `code`/severity; config schema check is check #1).
+- **Constraint**: start report-only in `o2b brain doctor` or CI; allow annotated fixtures to avoid false positives for intentional examples.
+
+### Task H β€” `t_5c364387` (p3): Safe fallback names for punctuation-only generated notes
+Ensure any OSB-generated note/canvas/artifact filename that slugifies to punctuation-only or empty falls back to a stable safe name like `unnamed` plus a short hash. Punctuation-only filenames break downstream re-sluggers, collide across devices, or become hard to address from agents and shell.
+- **Anchors**: `src/mcp/brain/feedback-tools.ts:48-55` `deriveSlug` β†’ `slugify(topic)` (from `src/core/vault.ts`); `src/mcp/resources.ts:24-25` validates slug/id args. No explicit punctuation-only generated filename fallback found.
+- **Constraint**: acceptance must cover `@`, `!!!`, whitespace, emoji-only, combining marks; do NOT weaken traversal protection (`ensureInsideVault`).
+
+### Task I β€” `t_0c7bed77` (p3): Memory cost meter β€” write-volume accounting alongside read telemetry
+A memory-operation cost meter that accounts for WRITE volume (preference/note/fact saves) alongside the existing read/recall telemetry, surfacing a write-vs-read ratio and a rough cost signal per period. Today recall-telemetry tracks only reads (`RecallTelemetryMode = search|context_pack|pre_compress|query`); there is no write-side accounting, so "is my agent write-heavy?" is unanswerable.
+- **Anchors**: `src/core/brain/recall-telemetry.ts` β€” `emitRecallTelemetry` (records reads only), `summarizeRecallTelemetry` (no write dimension), `listRecallTelemetry`. Write events already pass through the log (brain_feedback / apply_evidence / note / create_note). Relates to active-memory budget-pressure watermark (informs eviction).
+- **Constraint**: write events already flow through known boundaries; a meter can fold those counts against recall-telemetry reads. Keep deterministic.
+
+## What I need from you
+
+Produce exactly these sections and nothing else:
+
+1. **3 distinct architectural variants** for how to structure this 9-task release (how tasks group, what shared primitives to extract, ordering/dependencies, where the derive-vs-persist and opt-in lines fall). Each variant:
+ - **Approach** (2–3 sentences)
+ - **Trade-offs** (bullets: pro / con)
+ - **Complexity** (small | medium | large)
+ - **Risk** (low | medium | high)
+ - The three variants must be genuinely different strategies, not the same plan reworded.
+
+2. Then exactly one line: **Recommended: Variant N** followed by a 3–5 sentence rationale grounded in the project facts/conventions above (byte-identical-when-off, no-daemon, read-time-derive, path-safety chokepoint, proper-lockfile reuse, etc.).
+
+Do NOT write code. Do NOT add sections beyond those two. Do NOT propose anything that violates the standing conventions (no daemon, no LLM-in-kernel, no misleading fallbacks, no new runtime dependency unless justified).
diff --git a/docs/brainstorm/brain-integrity-safety-hardening/design.md b/docs/brainstorm/brain-integrity-safety-hardening/design.md
new file mode 100644
index 00000000..4641e44c
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-safety-hardening/design.md
@@ -0,0 +1,100 @@
+# Brain Integrity & Safety Hardening β€” a nine-task suite hardening write-time discipline, cross-machine portability, and corpus-level safety
+
+**Status:** draft
+**Author:** product-tech-lead (via hermes-workflows Phase 0)
+**Audience:** implementation (driven card workers, one card at a time on the shared branch)
+**Branch:** `feat/brain-integrity-safety-hardening`
+**Consultant:** Claude Code (`claude -p`, model `claude-opus-4-8`), exit 0, 3 parseable variants β†’ no fallback invoked.
+
+## Problem statement
+
+Open Second Brain syncs a plain-Markdown vault across VPS/Mac/Android via Syncthing and is called concurrently by many runtimes (Hermes, Claude Code, Codex, OpenClaw, …) through MCP. Three architectural strips are soft today:
+
+1. **Write-time integrity.** There is no single-writer discipline across *all* Brain writes, so concurrent MCP tools/hooks/imports/jobs can race on the same artifact and produce lost updates or noisy Syncthing conflict files. Codegraph-derived artifacts can be subtly wrong while syntactically present, and a generated note whose title slugifies to punctuation-only or empty produces a fragile/colliding filename.
+2. **Cross-machine portability.** Graph/index artifacts and generated examples that carry absolute, machine-local paths (`/root/vault/...` vs a Mac/Android home) are stale on every other device, forcing full re-extraction/re-index instead of incremental reuse, and hardcodes in docs/templates leak private host assumptions.
+3. **Corpus-level safety.** The injection-pattern detector fires only at *read-time* context assembly, so a poisoned memory that got persisted sits in the vault until it happens to be read; the secret redactor silently drops the tail past a 256 KB ceiling and recognises only `key=value`/Bearer shapes, so secrets beyond the ceiling and bare infra-topology (public IPs, internal hostnames) leak; and a contested truth-ledger slot is a binary flag that cannot say *which side* carries more independent support.
+
+This suite hardens each strip as opt-in (or byte-identical-when-off / projection-only) capabilities without changing any existing default, and without introducing a hidden daemon or an LLM call inside the kernel.
+
+## Scope
+
+Nine atomic tasks, one feature branch, one release (1.20.0 β†’ 1.21.0). Implemented one-by-one via TDD. Each task is one conventional commit. Cards are driven **one at a time** on the shared branch β€” each worker builds on the commits the previously-driven cards already landed.
+
+**Task letter β†’ card id β†’ one-line title:**
+
+- **A** `t_559fbe1f` (p4) β€” Single-writer queue / lease-backed write lane for concurrent Brain writes (no daemon).
+- **B** `t_e032ff18` (p4) β€” Portable graph/index artifact keys: scan-root-relative, not absolute.
+- **C** `t_aec23bd0` (p4) β€” Scheduled corpus-wide prompt-injection sweep (reuse `context-guard` patterns; no LLM).
+- **D** `t_de2ccadd` (p4) β€” Redactor fail-closed past the 256 KB scan ceiling + infra-topology detectors.
+- **E** `t_301db77e` (p4) β€” Read-only graph health gate before labeling/import.
+- **F** `t_4678a91a` (p4) β€” Signed source-diversity grounding score for contested truth-ledger slots.
+- **G** `t_44f91e9b` (p3) β€” Hardcoded absolute-path hygiene check (report-only).
+- **H** `t_5c364387` (p3) β€” Safe fallback names for punctuation-only generated notes.
+- **I** `t_0c7bed77` (p3) β€” Memory cost meter: write-volume accounting alongside read telemetry.
+
+## Out of scope
+
+- **`t_9935bd26`** (the umbrella card for this cluster) β€” purely meta; its leaf children are the work.
+- **Hermes-core conformance tasks** `t_2c8448bb`, `t_3190e771` (upstream children) β€” a different axis (Hermes-core alignment), not the integrity/safety/portability axis; left out of this triage.
+- **Raising OSB's 256 KB redactor window** as a value β€” the *fail-closed* marker is in scope; the window size itself stays a tunable, decided separately.
+- **Migrating existing on-disk graph/index artifacts** to relative keys β€” portability converges on the next extraction/index pass; no one-shot migration (matches the NFC-identity precedent from the Vault Integrity suite).
+- **Persisting any derived view into note frontmatter** β€” the read-time-derive precedent holds (F, E, I compute at read time; nothing new on disk for them).
+- **Any new runtime dependency.** Only `proper-lockfile` (already a dependency) is reused.
+- **Auto-deleting** any corpus-scan / hygiene / graph-health finding β€” findings are surfaced for operator decision (quarantine / fix / ignore), never silently deleted.
+
+## Chosen approach
+
+**Variant 3 β€” Risk-ordered incremental, minimal abstraction (refactor-on-second-use).** Ignore thematic grouping; sequence all nine strictly by blast radius. Byte-identical-when-off, report-only / projection-only leaves land first; the concurrency-invariant change (A, the single-writer lane) lands **last**, after the safety net (E's non-aborting health gate, I's write meter, C/D's scanners) is already in place. Shared primitives are extracted **opportunistically, on the second real consumer** β€” the ordering itself engineers those second-use points:
+
+- **I's write meter attaches at A's write-boundary chokepoint**, because A lands after I is anticipated; A's `proper-lockfile` lane becomes the already-known seam where write-volume accounting plugs in.
+- **D shares C's linear-bounded detector contract**, because D follows C; both need a regex family that stays linear on large inputs, so the contract is named once when the second consumer (D) appears.
+- **E's graph-health findings and C's injection findings share the existing `DoctorIssue`/hygiene-scan finding shape** rather than a new unified reporter β€” E follows C and reuses the shape, not a new abstraction.
+
+The derive-vs-persist tension is resolved by one rule, inherited from the prior suite: **read-time-derive everywhere** (F's signed score is a projection over the append-only claim ledger; E's gate is a read-only post-construction pass; I's meter folds write events already flowing through known boundaries against existing read telemetry) β€” **no new persisted derived state**, and **no history mutation** (F computes alongside the existing fold, never mutates the append-only ledger).
+
+## Design decisions
+
+- **Ordering is the architecture.** The release ships in risk order β€” G, H, I, E β†’ B, F β†’ C, D β†’ A (see `plan.md`). The tree stays shippable and every step is independently revertible. This is the lowest-risk path against the byte-identical-when-off and no-silent-fallback hard gates.
+- **No speculative shared module.** Unlike the prior Vault Integrity suite (which had one provably-shared identity primitive, NFC path+hash), this suite's tasks share only *contract shapes* (linear-regex detector; lockfile lease; findings record), which are extracted on second use, not pre-built. There is no "brain-integrity kernel".
+- **A (single-writer lane) reuses the existing `proper-lockfile` writer-lock pattern** from `src/core/search/store.ts:228` (`lockfile.lockSync`, `realpath:false`, stale-ms guard) and the maintenance lease shape from `src/core/brain/maintenance/lease.ts`. The lane is an **explicit, cooperative, process-exit-safe discipline**: acquire-on-write, release-on-completion, stale-guarded. It is **not** a daemon and **not** mandatory for read paths. It serializes write operations on the same artifact to give deterministic ordering and clearer failure/retry. (Whether it is opt-in per call-site or enforced at the write-session chokepoint is a per-task TDD decision recorded in `plan.md` Task A, but the chokepoint at `src/core/brain/write-session/engine.ts:347` is the natural home.)
+- **B (portable keys) is confirmed-scoped, not blind.** The search store already stores document paths as **vault-relative POSIX** (`store.ts:46,537,553,566,579`), so the search index is *not* the leaker. The task's first step is to confirm the actual on-disk key format of the **codegraph** artifacts (`manifest.json` keys, `graph.json` `source_file`, generation reports) and any embedding-index keys; if a reader already stores relative paths, scope down to only the absolute-leaking readers. This is the "no misleading fallback / report honestly" discipline β€” do not relativize what is already relative.
+- **C (injection sweep) reuses `context-guard.ts` `TEXT_PATTERNS` verbatim** β€” no new pattern list. It is wired as a corpus scan in the **existing maintenance lane** (`runMaintenance`, leased, quiet-window, sequential) and/or as a hygiene detector in the existing `src/core/brain/hygiene/scan.ts` registry, so it runs in the quiet window with the lease. Findings flow to the operator (quarantine/auto-fix via the existing hygiene `apply` plan), **never silent deletion**. Deterministic regex, no LLM.
+- **D (redactor) is two independent, separately-shippable fixes.** (1) Fail-closed: oversized input past `MAX_REDACTOR_INPUT` gets a `scan_truncated` marker that **demotes/excludes** the artifact instead of the current silent drop treating the unscanned tail as clean. (2) Infra-topology detector family (`public_ipv4`, `public_ipv6`, `basic_auth_url`, `fqdn_port`, `ipv4_port`, `internal_host`). Both detector families (the existing SECRET_KEYS key=value/Bearer family and the new topology family) must stay **linear** (bounded regexes, no catastrophic backtracking) to avoid ReDoS on large inputs β€” port upstream's linearity property. The fail-closed marker benefits the 256 KB receipts path; the topology detectors benefit the MCP artifact-store path (which already scans the full payload via `maxInput: Infinity`) most.
+- **E (graph health gate) is read-only and non-aborting.** A post-construction pass over the codegraph/index that surfaces dangling references, self-loops, collapsed-edge warnings, and cache-root mismatches as **warnings in the existing `doctor`/`vault_health` surfaces** (`DoctorIssue` with a stable `code`), before labels/import/recall trust the graph. It never aborts the run and never mutates state.
+- **F (signed grounding score) is a pure projection.** `groundingScore(slot): { signed: number; sufficiency: number; band: string }` computed from `ClaimVersion` provenance (independent `source` + `agent`) already in the ledger, weighting N mentions across N independent sources far above N mentions in one source. Computed **alongside** `computeTruthState` (in `truth/fold.ts`) and `computeTruthStateWithConflicts` (in `truth/conflicts.ts`) β€” **never mutates** the append-only ledger. The binary CONTESTED flag remains (backward compatible); the signed score is an *additional* dimension. Deterministic counting + weighting, no LLM. Confidence stays unsigned bands in `page-meta/confidence.ts`; the signed score is a separate, signed dimension, not a replacement of the unsigned confidence.
+- **G (hardcoded-path hygiene) is report-only, with an allowlist escape hatch.** A deterministic check (regex for absolute/home paths) registered in `o2b brain doctor` and/or CI, scanning OSB **source, docs, generated examples, and plugin config templates**. Annotated fixtures (a marker comment or a documented allowlist) suppress intentional-example false positives. Never auto-edits files.
+- **H (safe fallback names) strengthens the slug boundary, never weakens traversal protection.** `slugify` (in `src/core/vault.ts:204`, consumed by `deriveSlug` at `src/mcp/brain/feedback-tools.ts:54`) **already** falls back to a constant `"note"` when the input is punctuation-only/empty; the task strengthens that collision-prone constant into a hash-distinct name (`unnamed-<short-hash>`) so many bad inputs no longer collide on `note`. `ensureInsideVault` is untouched and remains the traversal gate.
+- **I (write cost meter) reuses the recall-telemetry shape with a write dimension.** A `writeTelemetry` sibling to `emitRecallTelemetry` that records write events (preference/note/fact saves) already flowing through `brain_feedback` / `apply_evidence` / `create_note`, and a `summarizeWriteTelemetry` that folds write counts against `summarizeRecallTelemetry` reads into a write-vs-read ratio per period. Deterministic counting. The meter attaches at A's write-boundary chokepoint once A lands (A is sequenced after I in `plan.md`; I anticipates the seam, A provides it).
+- **Every task opt-in or byte-identical-when-off.** No existing caller changes behaviour unless it opts in; the projection tasks (E, F, I) are additive outputs (new fields/findings), not behaviour changes.
+
+## File changes (indicative β€” finalized per task in `plan.md`)
+
+New:
+- `src/core/brain/write-lane.ts` (or `write-session/lane.ts`) β€” single-writer/lease-backed write discipline (Task A).
+- Corpus-injection scan: a new maintenance task and/or hygiene detector registering `context-guard` `TEXT_PATTERNS` (Task C); tests.
+- Infra-topology detector family + `scan_truncated` fail-closed marker in/near `src/core/redactor.ts` (Task D); tests.
+- `src/core/partner/graph-health.ts` (or sibling) β€” read-only graph-health gate (Task E); tests.
+- `groundingScore` projection in `src/core/brain/truth/` (Task F); tests.
+- Hardcoded-path hygiene check in `src/core/brain/doctor.ts` or a new CI lint (Task G); tests.
+- `slugify` punctuation-only/empty fallback in `src/core/vault.ts` (Task H); tests.
+- `write-telemetry.ts` sibling to `recall-telemetry.ts` (Task I); tests.
+
+Modified:
+- `src/core/redactor.ts` β€” fail-closed marker + topology detectors (Task D).
+- `src/core/brain/truth/fold.ts`, `truth/conflicts.ts` β€” surface the signed grounding score alongside CONTESTED (Task F).
+- `src/core/brain/doctor.ts` and/or `src/core/brain/hygiene/*` β€” register the injection sweep + hardcoded-path check (Tasks C, G).
+- `src/core/brain/maintenance/lane.ts` β€” register the corpus injection-sweep task (Task C).
+- `src/core/partner/codegraph-report.ts` (+ codegraph artifact readers) β€” relativize any absolute-leaking keys (Task B, after on-disk-format confirmation).
+- `src/core/vault.ts` (`slugify`) β€” safe fallback name (Task H).
+- `src/core/brain/write-session/engine.ts` β€” attach the single-writer lane at the commit chokepoint (Task A); attach write-telemetry at the same seam (Task I).
+- `src/mcp/brain/health-tools.ts` / `src/mcp/tools.ts` β€” surface graph-health + meter findings (Tasks E, I, as applicable).
+- `README.md`, `CHANGELOG.md` (`## [1.21.0]`), `package.json` (+ `scripts/sync-version.ts`).
+
+## Risks and open questions
+
+- **A (single-writer lane) is the one concurrency-invariant change.** Sequencing it **last** (after E/I/C/D) means the health gate, meter, and scanners exist before the write path is touched β€” the safety net precedes the risk. Open question for Task A: enforce the lane at the write-session commit chokepoint (broadest coverage, highest blast radius) vs. an opt-in per-call `acquireWriteLane()` (narrower, lower risk). Resolved in Task A's TDD: prefer the chokepoint for deterministic coverage, but only if every existing write path already funnels through it (verify via grep before locking the design); otherwise start opt-in and expand.
+- **B (portable keys) hinges on confirming the codegraph on-disk format.** If the codegraph artifacts already store relative keys, the task shrinks to a no-op-with-test (pin the invariant) β€” do **not** invent work. The search index is already relative; do not touch it.
+- **D ReDoS.** The new topology detector regexes must be provably linear on large inputs. The acceptance test includes a pathological-large-input case asserting bounded time; port upstream's bounded pattern property.
+- **C corpus-sweep performance.** Scanning every stored memory on a schedule must stay bounded; the maintenance lane's quiet-window + lease + sequential discipline is the host, and the scan reuses the already-linear `context-guard` patterns. A large-vault acceptance test asserts bounded time.
+- **F source-diversity definition.** "Independent source" must be crisply defined (distinct `source` values, optionally weighted by `agent`) so the score is deterministic; the acceptance test pins the N-docs-vs-N-sources weighting explicitly. The score must not change any existing recall ranking unless opted in (it is an *additional* surfaced dimension, not a ranking input by default).
+- **H false friends.** The hash-strengthened fallback must not change the slug of any currently-valid input (byte-identical for all non-punctuation-only inputs); only the existing `"note"` fallback value is replaced by a hash-distinct name for the punctuation-only/empty branch.
diff --git a/docs/brainstorm/brain-integrity-safety-hardening/plan.md b/docs/brainstorm/brain-integrity-safety-hardening/plan.md
new file mode 100644
index 00000000..06d60d76
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-safety-hardening/plan.md
@@ -0,0 +1,63 @@
+# Brain Integrity & Safety Hardening β€” implementation plan
+
+Implemented **one-by-one** via TDD on branch `feat/brain-integrity-safety-hardening`. Each task is one atomic conventional commit. Cards are driven **one at a time** on the shared branch β€” each worker MUST build on the commits previously-driven in-scope cards already landed, and must not duplicate or conflict with sibling tasks.
+
+**Sequence (risk-ordered, lowest blast radius first; the concurrency-invariant change lands last):**
+
+```
+G β†’ H β†’ I β†’ E β†’ B β†’ F β†’ C β†’ D β†’ A
+```
+
+The combined design is at `docs/brainstorm/brain-integrity-safety-hardening/design.md` (same branch).
+
+## Tasks
+
+### Task G β€” Hardcoded absolute-path hygiene check (`t_44f91e9b`, p3)
+- **Files**: new check in `src/core/brain/doctor.ts` (registered after the existing config-schema check) and/or a new CI lint script under `scripts/`; allowlist fixture support; tests `tests/doctor-absolute-path.test.ts` (and/or lint test).
+- **Acceptance**: a vault/docs scan flags hardcoded home/absolute paths (`/root/...`, `/Users/...`, `/home/...`, `C:\\...`) in OSB source, docs, generated examples, and plugin config templates; annotated fixtures (documented allowlist or marker comment) suppress intentional-example false positives; the finding is a report-only `DoctorIssue` (severity `warning`, stable `code`) and never auto-edits files; absent flagged paths β‡’ doctor exit clean / lint passes.
+- **Depends on**: none.
+
+### Task H β€” Safe fallback names for punctuation-only generated notes (`t_5c364387`, p3)
+- **Files**: `src/core/vault.ts` (`slugify`); tests `tests/vault-slugify.test.ts`. Verify `deriveSlug` (`src/mcp/brain/feedback-tools.ts:48-55`) and `src/mcp/resources.ts` slug/id validators still pass.
+- **Acceptance**: `slugify` of `@`, `!!!`, whitespace, emoji-only, and combining-marks inputs falls back to a stable safe name (`unnamed` + short hash of the original); every currently-valid (non-punctuation-only) input is **byte-identical** to today (regression snapshot test against the current output); `ensureInsideVault` traversal protection is untouched and still rejects `..`/symlink escapes.
+- **Depends on**: none.
+
+### Task I β€” Memory cost meter: write-volume accounting (`t_0c7bed77`, p3)
+- **Files**: new `src/core/brain/write-telemetry.ts` (sibling to `recall-telemetry.ts`: `emitWriteTelemetry`, `summarizeWriteTelemetry`, write-vs-read ratio); wire `brain_feedback` / `apply_evidence` / `create_note` (and note-create paths) to emit; tests `tests/write-telemetry.test.ts`. Anticipate β€” but do NOT yet wire β€” the write-lane seam (Task A provides it).
+- **Acceptance**: write events (preference/note/fact saves) are counted per period and folded against `summarizeRecallTelemetry` reads into a write-vs-read ratio; reads-only behaviour is **byte-identical** to today when no write events occur; deterministic counting; summary shape documented and frozen.
+- **Depends on**: none (anticipates Task A's chokepoint; final wiring to the lane lands with Task A).
+
+### Task E β€” Read-only graph health gate before labeling/import (`t_301db77e`, p4)
+- **Files**: new `src/core/partner/graph-health.ts` (read-only post-construction pass: dangling refs, self-loops, collapsed-edge warnings, cache-root mismatches); surface findings as `DoctorIssue`-shaped warnings in the existing `vault_health` / `doctor` surfaces (`src/mcp/tools.ts:381`, `src/mcp/brain/health-tools.ts`); tests `tests/graph-health.test.ts`.
+- **Acceptance**: after graph/index construction, the gate surfaces the four warning classes as non-aborting warnings (never aborts the run, never mutates state); a clean graph β‡’ no warnings; findings carry a stable `code` and severity `warning`; the gate runs read-only (no writes).
+- **Depends on**: none.
+
+### Task B β€” Portable graph/index artifact keys (`t_e032ff18`, p4)
+- **Files**: **first** a read-only confirmation of the on-disk key format of codegraph artifacts (`manifest.json` keys, `graph.json` `source_file`, generation reports) and any embedding-index keys; then relativize any absolute-leaking readers in `src/core/partner/codegraph-report.ts` (+ sibling codegraph artifact readers). The search index already stores vault-relative POSIX (`store.ts:46,537,553`) β€” do **not** touch it. Tests `tests/codegraph-portable-keys.test.ts`.
+- **Acceptance**: codegraph manifest keys + graph `source_file` + report references are stored relative to the vault scan root; an incremental update after a simulated clone/move (different absolute vault root) matches cached files instead of forcing full re-extraction; if a reader already stores relative paths, the task shrinks to a pin-the-invariant test (no invented work); no absolute host path leaks into a synced/committed graph artifact.
+- **Depends on**: none.
+
+### Task F β€” Signed source-diversity grounding score (`t_4678a91a`, p4)
+- **Files**: new `groundingScore(slot)` projection in `src/core/brain/truth/` (e.g. `grounding.ts`), computed alongside `computeTruthState`/`computeTruthStateWithConflicts` in `truth/fold.ts`; surface the signed score + sufficiency as an additional dimension next to CONTESTED in `truth/conflicts.ts`; tests `tests/truth-grounding.test.ts`. Do **not** mutate the append-only ledger; do **not** change `page-meta/confidence.ts` unsigned bands.
+- **Acceptance**: a contested slot with N mentions across N independent `source`s scores higher support than N mentions in one source (pinned weighting test); the signed score ∈ [βˆ’1.0, +1.0] with a labelled band (Strongly supported β†’ Mixed β†’ Contested β†’ Contradicted); the existing binary CONTESTED flag is unchanged (backward-compat test); no recall ranking changes unless a caller opts into the new dimension; deterministic, no LLM; history (claim ledger) is byte-identical before/after.
+- **Depends on**: none.
+
+### Task C β€” Scheduled corpus-wide prompt-injection sweep (`t_aec23bd0`, p4)
+- **Files**: new corpus scan reusing `src/core/brain/safety/context-guard.ts` `TEXT_PATTERNS`/`contextSafetyReport` verbatim (no new pattern list); register as a maintenance task in `src/core/brain/maintenance/` (leased, quiet-window, sequential via `runMaintenance`) and/or a hygiene detector in `src/core/brain/hygiene/scan.ts` registry; findings flow to operator via the existing hygiene `apply` plan (quarantine/auto-fix); tests `tests/corpus-injection-sweep.test.ts`.
+- **Acceptance**: scanning every stored memory surfaces injection payloads (instruction_override / delimiter_spoof / secret_exfiltration) with zero LLM; a poisoned memory persisted via an untrusted source is flagged on the next scheduled sweep, not only at read time; findings are surfaced for operator decision (quarantine/auto-fix) and **never silently deleted**; sweep runs inside the maintenance lease and is bounded on a large-vault fixture; default-off until the operator schedules/enables the lane task.
+- **Depends on**: none. (If D lands first and defines a shared linear-detector contract, C may reuse it; otherwise C defines the contract D later shares.)
+
+### Task D β€” Redactor fail-closed past ceiling + infra-topology detectors (`t_de2ccadd`, p4)
+- **Files**: `src/core/redactor.ts` β€” (1) replace the silent truncate-and-drop (`out.slice(0, maxInput) + TRUNCATION_MARKER`, line 171) with a fail-closed `scan_truncated` marker that demotes/excludes the artifact; (2) add infra-topology detector family (`public_ipv4`, `public_ipv6`, `basic_auth_url`, `fqdn_port`, `ipv4_port`, `internal_host`). All detector regexes (existing SECRET_KEYS family + new topology family) must stay **linear** (bounded, no catastrophic backtracking). Tests `tests/redactor-failclosed.test.ts`, `tests/redactor-topology.test.ts`.
+- **Acceptance**: input > `MAX_REDACTOR_INPUT` (256 KB) on the receipts path produces a `scan_truncated` marker that demotes/excludes (no unscanned tail treated as clean); a secret placed after byte 256 KB is flagged, not passed through; bare public IPv4/IPv6, `basic_auth_url`, `fqdn:port`, `ipv4:port`, and internal hostnames are redacted (artifact-store path benefits most); a pathological-large-input test asserts bounded (linear) time β€” no ReDoS; existing key=value/Bearer redaction is **byte-identical** for inputs under the ceiling (regression snapshot test).
+- **Depends on**: none (shares C's linear-detector contract on second use, if C landed first).
+
+### Task A β€” Single-writer queue / lease-backed write lane for concurrent Brain writes (`t_559fbe1f`, p4)
+- **Files**: new `src/core/brain/write-lane.ts` (or `write-session/lane.ts`) reusing the `proper-lockfile` writer-lock pattern (`src/core/search/store.ts:228`, `lockfile.lockSync`, `realpath:false`, stale-ms guard) and the maintenance-lease shape (`src/core/brain/maintenance/lease.ts`); attach at the write-session commit chokepoint `src/core/brain/write-session/engine.ts:347` (verify every write path funnels through it via grep before locking); **complete I's write-telemetry wiring at the same seam** (I anticipated this chokepoint). Tests `tests/write-lane.test.ts`.
+- **Acceptance**: concurrent writes to the same Brain artifact from two callers serialize with deterministic ordering (no lost update, no Syncthing conflict file); a held lane makes the second writer wait-or-fail-clearly (no silent corruption); the lane is process-exit-safe (stale-guarded, releases on completion, no daemon, no mandatory long-running process); read paths are unaffected (byte-identical); the lane never bypasses `ensureInsideVault` or the atomic-write discipline. Design note (resolve in TDD): prefer enforcing at the chokepoint if grep confirms all write paths pass through it; otherwise ship an opt-in `acquireWriteLane()` and document the expansion path.
+- **Depends on**: Tasks G–F landed (the safety net β€” E health gate, I meter, C/D scanners β€” precedes the concurrency-invariant change). I's chokepoint seam is finalized here.
+
+### Task (final) β€” Docs + version bump (same release)
+- **Files**: `README.md`, `CHANGELOG.md` (new `## [1.21.0]` heading + link-ref, grouped by the three sub-themes: write-time integrity / cross-machine portability / corpus-level safety), `package.json` (1.20.0 β†’ 1.21.0), then `bun run scripts/sync-version.ts`.
+- **Acceptance**: `bun run sync-version:check` passes; CHANGELOG version matches package.json; README documents the nine opt-in/projection capabilities; `bun run validate` (typecheck + lint + test) is green.
+- **Depends on**: Tasks G, H, I, E, B, F, C, D, A.
diff --git a/docs/brainstorm/brain-integrity-safety-hardening/variants.md b/docs/brainstorm/brain-integrity-safety-hardening/variants.md
new file mode 100644
index 00000000..cad2ee8f
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-safety-hardening/variants.md
@@ -0,0 +1,54 @@
+# Brain Integrity & Safety Hardening β€” brainstorm variants (audit trail)
+
+Consultant: Claude Code (`claude -p`), model `claude-opus-4-8`, primary. Exit 0, three parseable variants returned, so the fallback was not invoked (anti-pattern: sequential, fallback only on primary failure). Prompt: `cli-output/prompt.md`. Raw output: `cli-output/claude.md`.
+
+## Variant 1: Primitive-first (extract the shared substrate, then wire consumers)
+
+- **Approach**: Land three cross-cutting primitives before any feature task, then build the nine tasks as thin consumers of them: (1) a **write-boundary chokepoint** built on the existing `proper-lockfile` writer-lock/lease pattern (`store.ts:228`, `maintenance/lease.ts`) that both serializes all Brain writes (A) and exposes a single instrumentation seam for write-volume accounting (I); (2) a **linear-bounded corpus-scan detector harness** hosted in the maintenance lane's quiet window that `context-guard`'s `TEXT_PATTERNS` (C), the redactor's new infra-topology detectors (D), and the path-hygiene check (G) all register into; (3) a **unified findings/health-gate reporter** feeding `doctor`/`vault_health` that the graph-health gate (E) and hygiene checks surface through. B, F, and H then land as independent leaves.
+- **Trade-offs**:
+ - Pro: maximal DRY β€” the ReDoS-linearity contract, the lease acquisition, and the findings shape are each written and tested once.
+ - Pro: coherent operator surfaces (one findings vocabulary across injection/graph/path).
+ - Con: front-loads abstraction risk β€” primitives must be designed for consumers not yet built; wrong guess forces rework.
+ - Con: primitive PRs are byte-identical-when-off *and* feature-invisible, which fights the "one atomic commit ships one unit" grain and complicates CHANGELOG framing.
+ - Con: sequences the concurrency-invariant change (A) earliest, before any safety net exists.
+- **Complexity**: large
+- **Risk**: medium-high
+
+## Variant 2: Thematic vertical slices (the release's own three sub-themes)
+
+- **Approach**: Ship three cohesive, individually-demoable verticals matching the stated theme. **Write-time integrity discipline:** A (single-writer lane), E (graph-health gate), H (safe fallback names). **Cross-machine portability:** B (scan-root-relative keys), G (hardcoded-path hygiene), I (write cost meter). **Corpus-level safety:** C (injection sweep), D (redactor fail-closed + topology detectors), F (signed grounding score). Extract a shared primitive only *within* a slice where two members genuinely share one β€” e.g. C and D share the linear-regex detector contract inside the safety slice.
+- **Trade-offs**:
+ - Pro: each slice maps to a release-narrative section and a self-contained CHANGELOG story.
+ - Pro: moderate, low-risk reuse that stays inside a slice boundary.
+ - Con: misses the strongest cross-slice couplings β€” A's write chokepoint (integrity slice) and I's write meter (portability slice) instrument the *same* boundary but never meet; C's corpus scan (safety) and G's hygiene detector (portability) want the same registry harness across slices.
+ - Con: some duplicated scan/reporting scaffolding across slices.
+- **Complexity**: medium
+- **Risk**: medium
+
+## Variant 3: Risk-ordered incremental, minimal abstraction (refactor-on-second-use) (CHOSEN)
+
+- **Approach**: Ignore grouping; sequence all nine strictly by blast radius, landing byte-identical-when-off, report-only leaves first and the concurrency-invariant change last. Order: **G, H, I, E** (additive/report-only) β†’ **B, F** (read-time derivations / append-only projections, no history mutation) β†’ **C, D** (deterministic scanners behind flags) β†’ **A** (single-writer lane, which touches the write path every other task depends on). Each task ships self-contained via TDD as one atomic commit; shared primitives are extracted opportunistically only when a second real consumer appears β€” the ordering *engineers* those second-use points (I meters at A's chokepoint because A lands after it is anticipated; D shares C's linear-regex detector because D follows C).
+- **Trade-offs**:
+ - Pro: lowest per-step risk; the tree is always shippable and every step is independently revertible.
+ - Pro: cleanly honors "one unit, one branch, one atomic commit" and the repo's read-time-derive precedent (F, E, I compute at read time, nothing new persisted).
+ - Pro: the invariant-touching write-lane (A) lands *after* the health gate, cost meter, and safety scanners exist β€” the safety net precedes the risky change.
+ - Con: least upfront DRY; reuse emerges via ordering rather than design, risking minor rework if a late task reveals a primitive an early task could have shared.
+ - Con: no single unifying architecture diagram; A's cross-cutting benefit arrives latest.
+- **Complexity**: medium
+- **Risk**: low
+
+## Consultant recommendation: Variant 3
+
+> The repo's stated grain β€” "each suite unit ships one-by-one via TDD on a single feature branch, one atomic conventional commit per task" β€” plus byte-identical-when-off makes Variant 1's speculative primitives a poor fit: a primitive PR changes no observable behavior and can't be validated by its own acceptance test, and the codebase's *only* principled persisted-derivation exception (memoized side-indexes) signals a strong refactor-on-second-use culture rather than design-for-reuse-upfront. Risk ordering also respects the standing invariants directly: the concurrency-touching single-writer lane (A) is the one task that can destabilize every other write path, so landing it last β€” after E's non-aborting health gate, I's write meter, and the C/D safety scanners are already in place β€” means the "safety hardening" net exists before the riskiest change, and A's `proper-lockfile` chokepoint becomes the natural, already-anticipated second-use seam where I's write accounting attaches. F, E, and I stay pure read-time projections over the append-only ledger and telemetry (no history mutation, nothing new on disk), and B/G/H remain independent leaves, so the sequence keeps every step revertible and honestly opt-in without forcing a big-bang abstraction the conventions would struggle to justify.
+
+## Orchestrator decision: accept Variant 3
+
+No override. Variant 3 matches three standing project facts the consultant independently weighed:
+
+1. **The repo's grain is "one unit, one atomic commit, byte-identical-when-off."** Variant 1's speculative primitives cannot be validated by their own acceptance test (they change no observable behaviour) and front-load abstraction over consumers not yet built β€” directly against the codebase's refactor-on-second-use culture (the *only* persisted-derivation exception in the whole project is the memoized side-indexes from the prior Vault Integrity suite).
+2. **The single concurrency-invariant change (A) is the highest-risk task** because it touches the write path every other task depends on. Risk-ordering lands it **last**, after E's non-aborting graph-health gate, I's write meter, and the C/D scanners already exist β€” the safety net precedes the riskiest change, which is precisely what a "safety hardening" release should do.
+3. **The cross-cutting couplings are real but narrow.** I's meter and A's lane share one boundary; C and D share one linear-detector contract; E's and C's findings share the existing `DoctorIssue`/hygiene shape. Variant 3 extracts each of these on the second real consumer (engineered by the ordering), rather than paying Variant 1's upfront cost or missing the coupling entirely as Variant 2 does (it puts A and I in different slices that never meet).
+
+This is the direct sibling of the prior suite's "Thin Identity Core, Independent Edges" choice: share only what is provably shared, nothing speculative. The one difference here is there is no single provably-shared *primitive* (no analog to the NFC identity function); there are only shared *contract shapes*, which is exactly why refactor-on-second-use (not upfront extraction) is the right call.
+
+De-scope noted in `design.md`: the umbrella card `t_9935bd26` and the Hermes-core-conformance children `t_2c8448bb`/`t_3190e771` are out of this release (meta / different axis). Raising the 256 KB redactor window value is out of scope (fail-closed marker is in; window size stays a tunable). No on-disk artifact migration (portability converges on the next pass). No silent deletion of any finding.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 2432de07..d5e0d5e0 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -275,7 +275,7 @@ See [`hermes-cron.md`](hermes-cron.md) for the cron envelope and Telegram delive
Reports on external code-project partners. Strictly read-only: never installs, initializes, extracts, or mutates a partner index or the vault.
```text
-o2b partner codegraph report Resolve the in-scope code project and report the codegraph index state (no_project | absent | not_indexed | indexed with node/file/edge counts | error) plus a structural Cargo.toml workspace-member list. Non-Rust projects report cargo_workspace: null with a reason. --vault sharpens the scan scope; --json emits the schema-versioned report
+o2b partner codegraph report Resolve the in-scope code project and report the codegraph index state (no_project | absent | not_indexed | indexed with node/file/edge counts | error) plus a structural Cargo.toml workspace-member list. When indexed, runs a read-only, non-blocking graph-health gate (index.health) that flags empty-graph, collapsed-edges, dangling-references, self-loops, and cache-root-mismatch before labeling/import/recall trust the graph. Non-Rust projects report cargo_workspace: null with a reason. --vault sharpens the scan scope; --json emits the schema-versioned report
```
## Search
diff --git a/docs/mcp.md b/docs/mcp.md
index 44a18bea..1eaca976 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -38,7 +38,7 @@ flags for a narrower per-process full server.
| `vault_health` | Run vault, config, and plugin manifest health checks. | β€” |
| `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. Never installs, extracts, or mutates; non-Rust projects report `cargo_workspace: null` with a reason. | β€” |
+| `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. | β€” |
| `brain_agent_query` | Read-only source-agent retrieval over Brain provenance. Filters by agents, topic, free-text query, contribution kind, and limit. | β€” |
| `brain_agent_diff` | Read-only comparison between source agents using browse/search/diff/map modes over the same provenance foundation. | β€” |
| `brain_audit` | Read-only per-preference mutation trail (create / promote / update / retire / merge) with agent, reason, revision + content-hash before/after. | `pref_id` |
@@ -109,7 +109,10 @@ weights (applied to ranking only when `search_learned_weights_enabled` is on).
`brain_context_pack` accepts opt-in `receipt`, `telemetry`, `cache_stable`, and
`dedup_repeated` diagnostics; `brain_pre_compress_pack` accepts opt-in `receipt`
and `telemetry`. `brain_context_receipts` supports `operation: "list"|"show"`;
-`brain_recall_telemetry` supports `operation: "list"|"summary"`;
+`brain_recall_telemetry` supports `operation: "list"|"summary"|"cost"` (`cost`
+folds write volume - feedback/apply-evidence/note plus host-bridge writes -
+against reads into a write-vs-read ratio, a `write_heavy` flag, and a rough
+weighted cost signal per period; tune with `write_cost`/`read_cost`/`write_heavy_ratio`);
`brain_context_presets` supports `operation: "show"|"suggest"|"diff"`; and
`brain_generation_reports` supports `action: "record"|"list"|"summary"` -
`record` is gated (default off) by a per-call `enable` flag or the
diff --git a/docs/observability.md b/docs/observability.md
index b7b5f5bd..20e73466 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -88,6 +88,7 @@ No-consumer regression tests cover each gated surface, so a future call site can
## Reading the surfaces
- `brain_recall_telemetry` (MCP) and `o2b brain recall-telemetry list|summary|gate-list|gate-summary` aggregate recall and gate records.
+- `brain_recall_telemetry` `operation: "cost"` (MCP) and `o2b brain recall-telemetry cost` fold WRITE volume against the read telemetry above: memory-write ops (Brain-log `feedback`/`apply-evidence`/`note` verbs plus `host_memory_write` continuity records) are counted per period and reported alongside reads as a write-vs-read ratio, a `write_heavy` flag, and a rough weighted cost signal. Weights (`--write-cost`/`--read-cost`, default 1 each) model "some tools charge on write, some on read"; `--write-heavy-ratio` (default 1) sets the write-heavy threshold. Read-only; period-scoped by `--since`/`--until`. `brain_create_note` file creation emits no telemetry event today and is not counted.
- `brain_context_receipts` and `o2b brain context-receipts` inspect served-context receipts.
- `brain_event_trace` (MCP) and `o2b brain event-trace` join the Brain log to the continuity store: given a logged event (by day, `--at` stamp, kind, or `--session-id`), they resolve the continuity records attached to it via the stable correlation ids above (`session_id`, `turn_id`, and artifact `sourceRefs`), so an operator can answer "which context was supplied to this action?" from one surface. Each attached record reports `joinedBy` (`session` / `turn` / `artifact`); open the full record through the per-kind readers (`context-receipts show`, `recall-telemetry`, `generation-reports show`). Read-only; `private` records are dropped unless explicitly kept.
- `brain_generation_reports` (MCP, actions `record`/`list`/`summary`) and `o2b brain generation-reports record|list|summary|show` post and read inbound LLM generation traces. `summary` rolls up call counts, the always-present local token estimate, agent-reported usage where present, and a per-path linkage map so a memory path resolves back to the generation reports that produced or consumed it.
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index ce14dc9c..67d20cbe 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.20.0",
+ "version": "1.21.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/oxlint.json b/oxlint.json
index 08aad051..9ae940ce 100644
--- a/oxlint.json
+++ b/oxlint.json
@@ -15,5 +15,5 @@
"unicorn/no-useless-fallback-in-spread": "warn",
"unicorn/no-useless-spread": "warn"
},
- "ignorePatterns": [".codegraph", "node_modules", "openclaw/**", "dist", "coverage"]
+ "ignorePatterns": [".codegraph", "node_modules", "openclaw/**", "dist", "coverage", ".worktrees"]
}
diff --git a/package.json b/package.json
index faf50a8b..92c8623a 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.20.0",
+ "version": "1.21.0",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
@@ -46,6 +46,8 @@
"validate:fix": "bun run lint:fix && bun run fmt",
"sync-version": "bun run scripts/sync-version.ts",
"sync-version:check": "bun run scripts/sync-version.ts --check",
+ "check:paths": "bun run scripts/check-hardcoded-paths.ts",
+ "check:paths:strict": "bun run scripts/check-hardcoded-paths.ts --strict",
"hooks:install": "git config core.hooksPath .githooks && echo 'git hooks enabled (core.hooksPath=.githooks)'",
"prepare": "git rev-parse --git-dir >/dev/null 2>&1 && git config core.hooksPath .githooks || true"
},
diff --git a/plugin.yaml b/plugin.yaml
index 4cb668d1..821e81fb 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.20.0"
+version: "1.21.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 6e71b73c..75b37097 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.20.0",
+ "version": "1.21.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/_base.py b/plugins/hermes/_base.py
index 5699834a..72d361e1 100644
--- a/plugins/hermes/_base.py
+++ b/plugins/hermes/_base.py
@@ -9,67 +9,77 @@ mirroring the defensive pattern the rest of the Hermes shim already uses.
The stand-in deliberately does not enforce the abstract surface: the concrete
provider overrides every required method, and a faithful no-op base keeps the
provider importable and unit-testable without Hermes.
+
+The stand-in class is defined unconditionally (as ``_FallbackMemoryProviderBase``)
+and exposed via ``MemoryProvider`` regardless of whether the Hermes ABC is
+available: when Hermes is present, ``MemoryProvider`` aliases the real ABC; when
+it is not, ``MemoryProvider`` aliases the stand-in. Tests that pin the stand-in's
+no-op contract import ``_FallbackMemoryProviderBase`` directly so they hold in
+both environments (CI without Hermes, and a real install with Hermes).
"""
from __future__ import annotations
from typing import Any
-try: # pragma: no cover - exercised only inside a Hermes install
- from agent.memory_provider import MemoryProvider as _HermesMemoryProvider
- MemoryProvider: type = _HermesMemoryProvider
- HAS_HERMES_ABC = True
-except Exception: # noqa: BLE001 - any import failure means "not in Hermes"
- HAS_HERMES_ABC = False
+class _FallbackMemoryProviderBase:
+ """Minimal stand-in for the Hermes ``MemoryProvider`` ABC.
+
+ Optional lifecycle hooks default to no-ops so a subclass that does not
+ override one can still be driven by a Hermes-shaped harness without
+ raising. Required methods are intentionally absent here; the concrete
+ provider supplies them.
+ """
- class MemoryProvider: # type: ignore[no-redef]
- """Minimal fallback base used when the Hermes ABC is unavailable.
+ def system_prompt_block(self) -> str:
+ return ""
- Optional lifecycle hooks default to no-ops so a subclass that does not
- override one can still be driven by a Hermes-shaped harness without
- raising. Required methods are intentionally absent here; the concrete
- provider supplies them.
- """
+ def prefetch(self, query: str, *, session_id: str = "", **_kwargs: Any) -> str:
+ return ""
- def system_prompt_block(self) -> str:
- return ""
+ def queue_prefetch(self, query: str, **_kwargs: Any) -> None:
+ return None
- def prefetch(self, query: str, *, session_id: str = "", **_kwargs: Any) -> str:
- return ""
+ def sync_turn(
+ self,
+ user: str,
+ assistant: str,
+ *,
+ session_id: str = "",
+ messages: list | None = None,
+ **_kwargs: Any,
+ ) -> None:
+ return None
- def queue_prefetch(self, query: str, **_kwargs: Any) -> None:
- return None
+ def on_session_end(self, messages: list, **_kwargs: Any) -> None:
+ return None
- def sync_turn(
- self,
- user: str,
- assistant: str,
- *,
- session_id: str = "",
- messages: list | None = None,
- **_kwargs: Any,
- ) -> None:
- return None
+ def on_pre_compress(self, messages: list, **_kwargs: Any) -> None:
+ return None
- def on_session_end(self, messages: list, **_kwargs: Any) -> None:
- return None
+ def on_memory_write(
+ self,
+ action: str,
+ target: str,
+ content: str,
+ metadata: dict[str, Any] | None = None,
+ **_kwargs: Any,
+ ) -> None:
+ return None
- def on_pre_compress(self, messages: list, **_kwargs: Any) -> None:
- return None
+ def shutdown(self) -> None:
+ return None
- def on_memory_write(
- self,
- action: str,
- target: str,
- content: str,
- metadata: dict[str, Any] | None = None,
- **_kwargs: Any,
- ) -> None:
- return None
- def shutdown(self) -> None:
- return None
+try: # pragma: no cover - exercised only inside a Hermes install
+ from agent.memory_provider import MemoryProvider as _HermesMemoryProvider
+
+ MemoryProvider: type = _HermesMemoryProvider
+ HAS_HERMES_ABC = True
+except Exception: # noqa: BLE001 - any import failure means "not in Hermes"
+ MemoryProvider = _FallbackMemoryProviderBase
+ HAS_HERMES_ABC = False
-__all__ = ["MemoryProvider", "HAS_HERMES_ABC"]
+__all__ = ["HAS_HERMES_ABC", "MemoryProvider", "_FallbackMemoryProviderBase"]
diff --git a/plugins/hermes/_schemas.py b/plugins/hermes/_schemas.py
index db468a70..8536eb5b 100644
--- a/plugins/hermes/_schemas.py
+++ b/plugins/hermes/_schemas.py
@@ -312,7 +312,14 @@ STATIC_TOOL_SCHEMAS: tuple[dict[str, Any], ...] = (
'pages always match, '
'owner-tagged pages only their '
'owner. Absent = no ownership '
- 'filtering.'}},
+ 'filtering.'},
+ 'disclosure': {'type': 'string',
+ 'enum': ['full', 'cards'],
+ 'description': "Result depth: 'full' "
+ '(default) returns full chunk '
+ "content; 'cards' returns token-"
+ 'cheap layer-1 cards β€” drill a '
+ 'hit with brain_search_expand.'}},
'required': ['query'],
'additionalProperties': False}},
{'name': 'brain_recall_gate',
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 4cb668d1..821e81fb 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.20.0"
+version: "1.21.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 b4839dab..d193117f 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.20.0"
+version = "1.21.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/scripts/check-hardcoded-paths.ts b/scripts/check-hardcoded-paths.ts
new file mode 100644
index 00000000..1c140243
--- /dev/null
+++ b/scripts/check-hardcoded-paths.ts
@@ -0,0 +1,51 @@
+#!/usr/bin/env bun
+/**
+ * Hardcoded home / absolute path hygiene report.
+ *
+ * Scans OSB's shipped source, docs, generated examples, and plugin
+ * config templates for concrete home paths (`/home/<user>`,
+ * `/Users/<user>`, `X:\Users\<user>`) that would leak a private host
+ * layout or hand a reader a copy-paste command that only works on the
+ * author's machine. Placeholder segments (`user`, `you`, single-letter
+ * stand-ins, …) pass; a line carrying `hygiene:allow-path` is skipped.
+ *
+ * Report-only by default: prints findings and always exits 0, so it can
+ * ride in CI as an informational step without gating a merge. The
+ * `hardcoded-paths.test.ts` suite is the enforcing gate.
+ *
+ * Usage:
+ * bun run scripts/check-hardcoded-paths.ts # report, exit 0
+ * bun run scripts/check-hardcoded-paths.ts --strict # exit 1 on findings
+ * bun run scripts/check-hardcoded-paths.ts --json # machine-readable
+ */
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { formatFinding } from "../src/core/hygiene/hardcoded-paths.ts";
+import { scanRepo } from "../src/core/hygiene/scan-repo.ts";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const argv = process.argv.slice(2);
+const strict = argv.includes("--strict");
+const json = argv.includes("--json");
+
+const findings = scanRepo(ROOT);
+
+if (json) {
+ process.stdout.write(JSON.stringify({ findings }, null, 2) + "\n");
+} else if (findings.length === 0) {
+ process.stdout.write(
+ "check-hardcoded-paths: clean β€” no hardcoded home paths in shipped surfaces\n",
+ );
+} else {
+ for (const f of findings) process.stdout.write(`[hardcoded-path] ${formatFinding(f)}\n`);
+ process.stdout.write(
+ `check-hardcoded-paths: ${findings.length} finding(s). ` +
+ "Use a placeholder (e.g. ~/vault, $HOME, /home/user) or annotate an " +
+ "intentional path with a 'hygiene:allow-path' comment on the same line.\n",
+ );
+}
+
+process.exit(strict && findings.length > 0 ? 1 : 0);
diff --git a/src/cli/brain/help-text.ts b/src/cli/brain/help-text.ts
index 31283354..d38c09d6 100644
--- a/src/cli/brain/help-text.ts
+++ b/src/cli/brain/help-text.ts
@@ -587,7 +587,8 @@ export const VERB_HELP: Record<string, string> = {
"recall-telemetry":
"usage: o2b brain recall-telemetry list [--mode search|context_pack|pre_compress] [--status ok|empty|error|timeout] [--host <name>] [--since <iso>] [--until <iso>] [--limit <n>] [--vault <path>] [--json]\n" +
" o2b brain recall-telemetry summary [same filters] [--vault <path>] [--json]\n" +
- "Read opt-in recall telemetry continuity records and aggregate coverage gaps.\n",
+ " o2b brain recall-telemetry cost [--since <iso>] [--until <iso>] [--write-cost <n>] [--read-cost <n>] [--write-heavy-ratio <n>] [--vault <path>] [--json]\n" +
+ "Read opt-in recall telemetry continuity records and aggregate coverage gaps. cost folds write volume (feedback/apply-evidence/note/host writes) against reads into a write-vs-read ratio, a write-heavy flag, and a rough weighted cost signal per period.\n",
"generation-reports":
"usage: o2b brain generation-reports record <write_session|context_pack|dream_stage> --ref <id> --agent <name> --prompt <text> [--enable] [--provider <p>] [--model <m>] [--finish-reason <r>] [--latency-ms <n>] [--input-tokens <n>] [--output-tokens <n>] [--cached-tokens <n>] [--total-tokens <n>] [--scope <s>] [--source <id[=path]>...] [--created-at <iso>] [--vault <path>] [--json]\n" +
" o2b brain generation-reports list [--handoff <kind>] [--agent <name>] [--since <iso>] [--until <iso>] [--limit <n>] [--vault <path>] [--json]\n" +
diff --git a/src/cli/brain/verbs/recall-telemetry.ts b/src/cli/brain/verbs/recall-telemetry.ts
index 4fcc04c1..964e6e21 100644
--- a/src/cli/brain/verbs/recall-telemetry.ts
+++ b/src/cli/brain/verbs/recall-telemetry.ts
@@ -5,6 +5,7 @@ import {
summarizeRecallTelemetry,
} from "../../../core/brain/recall-telemetry.ts";
import { listGateTelemetry, summarizeGateTelemetry } from "../../../core/brain/gate-telemetry.ts";
+import { computeMemoryCostMeter } from "../../../core/brain/memory-cost-meter.ts";
import { CliError, brainVerbContext, parse } from "../helpers.ts";
export async function cmdBrainRecallTelemetry(argv: string[]): Promise<number> {
@@ -15,7 +16,11 @@ export async function cmdBrainRecallTelemetry(argv: string[]): Promise<number> {
// Gate-decision telemetry (Workspace Insight Suite, t_65036e02).
if (subcommand === "gate-list") return listGate(rest);
if (subcommand === "gate-summary") return summarizeGate(rest);
- throw new CliError("brain recall-telemetry: expected list, summary, gate-list, or gate-summary");
+ // Write-vs-read cost meter (memory cost meter).
+ if (subcommand === "cost") return costMeter(rest);
+ throw new CliError(
+ "brain recall-telemetry: expected list, summary, gate-list, gate-summary, or cost",
+ );
}
function listTelemetry(argv: string[]): number {
@@ -119,6 +124,64 @@ function summarizeGate(argv: string[]): number {
return 0;
}
+function costMeter(argv: string[]): number {
+ const { flags } = parseTelemetryFlags(argv);
+ // The cost meter is period-based; mode/status/host/limit filter recall
+ // records only and have no write-side analogue, so reject them rather
+ // than silently ignore.
+ for (const name of ["mode", "status", "host", "limit"]) {
+ if (flags[name] !== undefined) {
+ throw new CliError(
+ `brain recall-telemetry cost: --${name} is not supported for the cost meter`,
+ );
+ }
+ }
+ const vault = brainVerbContext(flags).vault;
+ const since = trimOrUndefined(flags["since"]);
+ const until = trimOrUndefined(flags["until"]);
+ // Parse each numeric weight once; the cost meter omits undefined weights
+ // so the module applies its own defaults.
+ const writeCost = parseNonNegativeNumber(
+ trimOrUndefined(flags["write-cost"]),
+ "brain recall-telemetry cost",
+ "--write-cost",
+ );
+ const readCost = parseNonNegativeNumber(
+ trimOrUndefined(flags["read-cost"]),
+ "brain recall-telemetry cost",
+ "--read-cost",
+ );
+ const writeHeavyRatio = parseNonNegativeNumber(
+ trimOrUndefined(flags["write-heavy-ratio"]),
+ "brain recall-telemetry cost",
+ "--write-heavy-ratio",
+ );
+ const meter = computeMemoryCostMeter(vault, {
+ ...(since !== undefined ? { since } : {}),
+ ...(until !== undefined ? { until } : {}),
+ weights: { write: writeCost, read: readCost },
+ ...(writeHeavyRatio !== undefined ? { writeHeavyRatio } : {}),
+ });
+
+ if (flags["json"]) {
+ process.stdout.write(JSON.stringify(meter, null, 2) + "\n");
+ return 0;
+ }
+
+ const ratio = meter.write_read_ratio === null ? "n/a (no reads)" : meter.write_read_ratio;
+ process.stdout.write(`writes: ${meter.writes.total}\n`);
+ process.stdout.write(`reads: ${meter.reads.total}\n`);
+ process.stdout.write(`write/read ratio: ${ratio}\n`);
+ process.stdout.write(`write-heavy: ${meter.write_heavy ? "yes" : "no"}\n`);
+ process.stdout.write(`by write kind: ${JSON.stringify(meter.writes.by_kind)}\n`);
+ process.stdout.write(`by read mode: ${JSON.stringify(meter.reads.by_mode)}\n`);
+ process.stdout.write(
+ `cost (write=${meter.weights.write}, read=${meter.weights.read}): ` +
+ `write=${meter.cost.write} read=${meter.cost.read} total=${meter.cost.total}\n`,
+ );
+ return 0;
+}
+
function parseTelemetryFlags(argv: string[]): {
readonly flags: Record<string, string | boolean | string[] | undefined>;
} {
@@ -131,9 +194,25 @@ function parseTelemetryFlags(argv: string[]): {
since: { type: "string" },
until: { type: "string" },
limit: { type: "string" },
+ "write-cost": { type: "string" },
+ "read-cost": { type: "string" },
+ "write-heavy-ratio": { type: "string" },
});
}
+function parseNonNegativeNumber(
+ value: string | undefined,
+ label: string,
+ flag: string,
+): number | undefined {
+ if (value === undefined) return undefined;
+ const parsed = Number(value);
+ if (!Number.isFinite(parsed) || parsed < 0) {
+ throw new CliError(`${label}: ${flag} must be a non-negative number`);
+ }
+ return parsed;
+}
+
function telemetryFilter(
flags: Record<string, string | boolean | string[] | undefined>,
label: string,
diff --git a/src/cli/partner.ts b/src/cli/partner.ts
index bc4bbf3e..c91aa17d 100644
--- a/src/cli/partner.ts
+++ b/src/cli/partner.ts
@@ -30,6 +30,16 @@ function renderCodegraphReport(report: CodegraphReport): string {
`index: indexed (${idx.node_count ?? 0} nodes, ${idx.file_count ?? 0} files, ` +
`${idx.edge_count ?? 0} edges)`,
);
+ // Read-only graph-health gate: surface non-blocking findings before any
+ // labeling/import/recall surface trusts the graph.
+ if (idx.health) {
+ if (idx.health.ok) {
+ lines.push("graph health: ok");
+ } else {
+ lines.push(`graph health: ${idx.health.warnings.length} warning(s)`);
+ for (const w of idx.health.warnings) lines.push(` - ${w.code}: ${w.message}`);
+ }
+ }
} else {
lines.push(`index: ${idx.state}${detail}`);
}
diff --git a/src/core/brain/memory-cost-meter.ts b/src/core/brain/memory-cost-meter.ts
new file mode 100644
index 00000000..582fb7af
--- /dev/null
+++ b/src/core/brain/memory-cost-meter.ts
@@ -0,0 +1,224 @@
+/**
+ * Memory-operation cost meter (article: "Memory cost meter").
+ *
+ * The recall-telemetry surface (`recall-telemetry.ts`) accounts only for
+ * READS - the `search | context_pack | pre_compress | query` modes. There
+ * was no write-side accounting, so "is my agent write-heavy?" - the
+ * question the source article argues is the real one ("how often does your
+ * agent write memory, how often does it read memory, and what does the
+ * tool charge for?") - could not be answered from the vault.
+ *
+ * This module folds WRITE volume against the existing read telemetry and
+ * surfaces a write-vs-read ratio plus a rough cost signal per period, so
+ * an operator can spot "write-heavy chaos" before the bill does.
+ *
+ * WRITE sources (what the meter counts):
+ * - Brain daily-log write verbs (`Brain/log/<date>`): `feedback`
+ * (brain_feedback), `apply-evidence` (brain_apply_evidence), and
+ * `note` (brain_note).
+ * - Native host-memory bridge writes: `host_memory_write` continuity
+ * records (the create-note-style writes Hermes bridges into the vault).
+ *
+ * NOT counted (documented honestly rather than silently): `brain_create_note`
+ * file creation, which writes a note file but emits no log/continuity event
+ * today - there is nothing to fold. When it grows a telemetry event this
+ * meter should pick it up via a new {@link MemoryWriteKind}.
+ *
+ * The meter is READ-ONLY and deterministic: it aggregates events already on
+ * disk, never emits its own record and never calls a model.
+ */
+
+import { listContinuityRecords } from "./continuity/store.ts";
+import { HOST_MEMORY_WRITE_KIND } from "./host-memory-write.ts";
+import { listLogDates, readLogDay } from "./log-jsonl.ts";
+import { summarizeRecallTelemetry, type RecallTelemetryMode } from "./recall-telemetry.ts";
+
+/** Countable memory-write categories the meter folds against reads. */
+export type MemoryWriteKind = "feedback" | "apply_evidence" | "note" | "host_memory_write";
+
+/**
+ * Brain daily-log event kinds that represent an agent-driven memory
+ * SAVE, mapped to the meter's stable snake_case write-kind labels. Log
+ * kinds absent from this map (dream, promote, retire, ...) are lifecycle
+ * transitions, not writes, and are ignored.
+ */
+const LOG_EVENT_TO_WRITE_KIND: Readonly<Record<string, MemoryWriteKind>> = Object.freeze({
+ feedback: "feedback",
+ "apply-evidence": "apply_evidence",
+ note: "note",
+});
+
+export interface MemoryWriteFilter {
+ /** Inclusive lower ISO-8601 timestamp bound. */
+ readonly since?: string;
+ /** Inclusive upper ISO-8601 timestamp bound. */
+ readonly until?: string;
+}
+
+export interface MemoryWriteSummary {
+ readonly total: number;
+ readonly by_kind: Partial<Record<MemoryWriteKind, number>>;
+}
+
+/**
+ * Count memory-write operations over a period. Reads the Brain daily log
+ * for the agent write verbs and the continuity log for host-bridge writes,
+ * bounded by the same inclusive `[since, until]` window the recall summary
+ * uses so the two sides stay comparable.
+ */
+export function summarizeMemoryWrites(
+ vault: string,
+ filter: MemoryWriteFilter = {},
+): MemoryWriteSummary {
+ const byKind: Partial<Record<MemoryWriteKind, number>> = {};
+ let total = 0;
+ const bump = (kind: MemoryWriteKind): void => {
+ byKind[kind] = (byKind[kind] ?? 0) + 1;
+ total += 1;
+ };
+
+ // Brain daily-log write verbs. Skip whole day files outside the window
+ // before reading them, then bound each entry by its exact timestamp.
+ const sinceDay = filter.since?.slice(0, 10);
+ const untilDay = filter.until?.slice(0, 10);
+ for (const date of listLogDates(vault)) {
+ if (sinceDay !== undefined && date < sinceDay) continue;
+ if (untilDay !== undefined && date > untilDay) continue;
+ for (const entry of readLogDay(vault, date).entries) {
+ const kind = LOG_EVENT_TO_WRITE_KIND[entry.eventType];
+ if (kind === undefined) continue;
+ if (!withinBounds(entry.timestamp, filter)) continue;
+ bump(kind);
+ }
+ }
+
+ // Native host-memory bridge writes (continuity records). The store's
+ // since/until filter already applies the same inclusive bounds.
+ const hostWrites = listContinuityRecords(vault, {
+ kind: HOST_MEMORY_WRITE_KIND,
+ ...(filter.since !== undefined ? { since: filter.since } : {}),
+ ...(filter.until !== undefined ? { until: filter.until } : {}),
+ });
+ for (let i = 0; i < hostWrites.length; i += 1) bump("host_memory_write");
+
+ return Object.freeze({ total, by_kind: Object.freeze(byKind) });
+}
+
+/** Per-operation cost weights ("what the tool charges" per write / read). */
+export interface MemoryCostWeights {
+ readonly write: number;
+ readonly read: number;
+}
+
+/** Unit weights: one cost unit per operation regardless of direction. */
+export const DEFAULT_MEMORY_COST_WEIGHTS: MemoryCostWeights = Object.freeze({ write: 1, read: 1 });
+
+/**
+ * Default write-heavy threshold on the write/read ratio. `1` means "more
+ * writes than reads is write-heavy" - the article's "write-heavy chaos"
+ * baseline. Operators tune it per their tool's pricing.
+ */
+export const DEFAULT_WRITE_HEAVY_RATIO = 1;
+
+export interface MemoryCostMeterOptions {
+ readonly since?: string;
+ readonly until?: string;
+ /** Override per-operation weights; missing fields fall back to unit weights. */
+ readonly weights?: Partial<MemoryCostWeights>;
+ /** Ratio above which the period is flagged write-heavy. Default 1. */
+ readonly writeHeavyRatio?: number;
+}
+
+export interface MemoryCostMeter {
+ readonly period: { readonly since: string | null; readonly until: string | null };
+ readonly writes: MemoryWriteSummary;
+ readonly reads: {
+ readonly total: number;
+ readonly by_mode: Partial<Record<RecallTelemetryMode, number>>;
+ };
+ /**
+ * writes / reads, rounded to 2 decimals. `null` when there are no reads
+ * in the period (division undefined) - inspect `write_heavy` instead.
+ */
+ readonly write_read_ratio: number | null;
+ /**
+ * `true` when the ratio exceeds `writeHeavyRatio`, or when there are
+ * writes but zero reads (the extreme write-heavy case).
+ */
+ readonly write_heavy: boolean;
+ readonly weights: MemoryCostWeights;
+ readonly cost: { readonly write: number; readonly read: number; readonly total: number };
+}
+
+/**
+ * Fold write volume against read telemetry into a single cost meter for a
+ * period. Reads come from {@link summarizeRecallTelemetry}; writes from
+ * {@link summarizeMemoryWrites}. The cost signal is a weighted op count -
+ * deliberately rough: it models "some tools charge on write, some on
+ * read" without pretending to be a billing integration.
+ */
+export function computeMemoryCostMeter(
+ vault: string,
+ options: MemoryCostMeterOptions = {},
+): MemoryCostMeter {
+ const filter: MemoryWriteFilter = {
+ ...(options.since !== undefined ? { since: options.since } : {}),
+ ...(options.until !== undefined ? { until: options.until } : {}),
+ };
+ const writes = summarizeMemoryWrites(vault, filter);
+ const readSummary = summarizeRecallTelemetry(vault, filter);
+ const reads = { total: readSummary.total, by_mode: readSummary.by_mode };
+
+ const weights = resolveWeights(options.weights);
+ const threshold = resolveWriteHeavyRatio(options.writeHeavyRatio);
+
+ const ratio = reads.total === 0 ? null : round2(writes.total / reads.total);
+ const writeHeavy = reads.total === 0 ? writes.total > 0 : (ratio as number) > threshold;
+
+ const writeCost = round2(writes.total * weights.write);
+ const readCost = round2(reads.total * weights.read);
+
+ return Object.freeze({
+ period: Object.freeze({
+ since: options.since ?? null,
+ until: options.until ?? null,
+ }),
+ writes,
+ reads: Object.freeze({ total: reads.total, by_mode: reads.by_mode }),
+ write_read_ratio: ratio,
+ write_heavy: writeHeavy,
+ weights,
+ cost: Object.freeze({
+ write: writeCost,
+ read: readCost,
+ total: round2(writeCost + readCost),
+ }),
+ });
+}
+
+function withinBounds(ts: string, filter: MemoryWriteFilter): boolean {
+ if (filter.since !== undefined && ts < filter.since) return false;
+ if (filter.until !== undefined && ts > filter.until) return false;
+ return true;
+}
+
+function resolveWeights(weights: Partial<MemoryCostWeights> | undefined): MemoryCostWeights {
+ return Object.freeze({
+ write: finiteOrDefault(weights?.write, DEFAULT_MEMORY_COST_WEIGHTS.write),
+ read: finiteOrDefault(weights?.read, DEFAULT_MEMORY_COST_WEIGHTS.read),
+ });
+}
+
+function resolveWriteHeavyRatio(ratio: number | undefined): number {
+ return typeof ratio === "number" && Number.isFinite(ratio) && ratio >= 0
+ ? ratio
+ : DEFAULT_WRITE_HEAVY_RATIO;
+}
+
+function finiteOrDefault(value: number | undefined, fallback: number): number {
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+function round2(value: number): number {
+ return Math.round(value * 100) / 100;
+}
diff --git a/src/core/brain/sessions/import.ts b/src/core/brain/sessions/import.ts
index e0075feb..7a7d2544 100644
--- a/src/core/brain/sessions/import.ts
+++ b/src/core/brain/sessions/import.ts
@@ -125,6 +125,22 @@ function firstLineOfFile(path: string): string {
return nl < 0 ? text : text.slice(0, nl);
}
+/**
+ * Portable session identity for provenance refs (Vault portability suite).
+ *
+ * A session file's absolute path is machine-local, so persisting it into a
+ * synced signal's `source` / `session_ref` bakes in a host path (e.g.
+ * `/root/vault/...` vs a Mac/Android home) that no Syncthing peer can
+ * resolve. We key provenance by the session file's basename instead β€” the
+ * same identity the recall DAG uses β€” so signal provenance and recall
+ * records join on one portable id. An explicit `recallSessionId` wins so a
+ * caller can pin a stable logical id.
+ */
+export function sessionRefIdentity(absPath: string, recallSessionId?: string): string {
+ const explicit = recallSessionId?.trim();
+ return explicit && explicit.length > 0 ? explicit : basename(absPath);
+}
+
/** Pick an adapter β€” by explicit format, or autodetect. */
function chooseAdapter(path: string, format?: SessionAdapterId): SessionAdapter {
if (format !== undefined) {
@@ -157,6 +173,9 @@ export async function importSession(
const now = opts.now ?? new Date();
const sinceMs = opts.since ? opts.since.getTime() : undefined;
const absPath = resolve(path);
+ // Portable provenance key for signal/fact `source` + `session_ref` and the
+ // recall DAG id β€” never the machine-local `absPath`. See sessionRefIdentity.
+ const sessionKey = sessionRefIdentity(absPath, opts.recallSessionId);
const errors: { path: string; message: string }[] = [];
let turnsScanned = 0;
@@ -195,7 +214,7 @@ export async function importSession(
// actually written.
return;
}
- const sessionRef = `${absPath}#${input.turnId}`;
+ const sessionRef = `${sessionKey}#${input.turnId}`;
try {
const res = writeSignal(vault, {
topic: input.topic,
@@ -287,7 +306,7 @@ export async function importSession(
facts: extractFacts(turn.text),
agent: agentLabelForTurn(turn, adapter.id, opts.agent),
now,
- sessionRef: `${absPath}#${turn.turnId}`,
+ sessionRef: `${sessionKey}#${turn.turnId}`,
dedup,
...(opts.dryRun === true ? { dryRun: true } : {}),
});
@@ -354,7 +373,9 @@ export async function importSession(
let recallSummaryNodes = 0;
if (opts.recall === true && opts.dryRun !== true && recallTurns.length > 0) {
try {
- const recallSessionId = opts.recallSessionId ?? basename(absPath);
+ // Same portable identity used for signal/fact provenance above, so
+ // the recall DAG and the emitted signals key this session identically.
+ const recallSessionId = sessionKey;
// Persisted-link resolution only: without a clock the crutch
// never infers a new link, so an unknown session imports flat.
const lineage =
diff --git a/src/core/hygiene/hardcoded-paths.ts b/src/core/hygiene/hardcoded-paths.ts
new file mode 100644
index 00000000..911ebd23
--- /dev/null
+++ b/src/core/hygiene/hardcoded-paths.ts
@@ -0,0 +1,168 @@
+/**
+ * Hardcoded home / absolute path hygiene scanner.
+ *
+ * OSB is installed across many machines and vault roots. A concrete
+ * home path baked into shipped source, docs, generated examples, or a
+ * plugin config template leaks the author's host layout and hands the
+ * reader a copy-paste command that only works on the author's machine.
+ * This module flags those paths deterministically so a CI report (and
+ * the `hardcoded-paths.test.ts` gate) can keep them out of the tree.
+ *
+ * What it flags: a POSIX `/home/<user>/…` or `/Users/<user>/…` prefix,
+ * or a Windows `X:\Users\<user>\…` prefix, whose `<user>` segment names
+ * a *specific* account rather than a placeholder. Placeholder segments
+ * (`user`, `you`, `me`, single/double-letter stand-ins, …) are intended
+ * examples and pass. `~`, `$HOME`, `/path/to/…`, and non-home absolute
+ * paths (`/usr`, `/etc`, `/tmp`, `#!/usr/bin/env …`) are never flagged.
+ *
+ * Escape hatch: a line carrying the marker `hygiene:allow-path` (in a
+ * comment) suppresses findings on that line, so a genuinely intentional
+ * concrete path can be annotated instead of triggering a false positive.
+ *
+ * Pure and text-based: {@link scanText} takes a string and returns
+ * findings; {@link scanFiles} walks a file list. Neither mutates state.
+ */
+
+// ----- Public types ---------------------------------------------------------
+
+/** Stable detector identifiers so callers can filter without parsing. */
+export type HardcodedPathDetector = "unix-home" | "windows-home";
+
+export interface HardcodedPathFinding {
+ /** File the match came from, exactly as the caller passed it. */
+ readonly file: string;
+ /** 1-based line number of the match. */
+ readonly line: number;
+ /** 1-based column (UTF-16 code unit) of the match start. */
+ readonly column: number;
+ /** The matched path prefix, e.g. `/home/sergey`. */ // hygiene:allow-path
+ readonly match: string;
+ /** The offending user segment, e.g. `sergey`. */
+ readonly segment: string;
+ /** Which detector fired. */
+ readonly detector: HardcodedPathDetector;
+}
+
+// ----- Detectors ------------------------------------------------------------
+
+/**
+ * POSIX home prefix: `/home/<seg>` or `/Users/<seg>`. The segment must
+ * start with an alphanumeric so a literal `/Users/...` placeholder does
+ * not capture a segment and therefore never fires.
+ */
+const UNIX_HOME_RE = /\/(?:home|Users)\/([A-Za-z0-9][A-Za-z0-9._-]*)/g;
+
+/**
+ * Windows home prefix: `X:\Users\<seg>`. Tolerates both a raw backslash
+ * (Markdown / shell text) and an escaped `\\` (inside a source string
+ * literal) between the components.
+ */
+const WINDOWS_HOME_RE = /[A-Za-z]:\\{1,2}Users\\{1,2}([A-Za-z0-9][A-Za-z0-9._-]*)/g;
+
+/**
+ * Marker that suppresses findings on the line that carries it. Keep the
+ * literal out of any scanned example by placing it in a comment.
+ */
+export const HYGIENE_ALLOW_MARKER = "hygiene:allow-path";
+
+/**
+ * Segments treated as intentional placeholders rather than real
+ * accounts. Case-insensitive. Anything one or two characters long
+ * (`u`, `x`, `me`, …) is also treated as a placeholder β€” real leaks are
+ * full usernames, and short stand-ins are ubiquitous in examples.
+ */
+const PLACEHOLDER_SEGMENTS: ReadonlySet<string> = new Set([
+ "user",
+ "users",
+ "username",
+ "youruser",
+ "you",
+ "your",
+ "yourname",
+ "yourusername",
+ "name",
+ "someone",
+ "somebody",
+ "example",
+ "changeme",
+ "home",
+ "alice",
+ "bob",
+ "carol",
+ "dave",
+ "foo",
+ "bar",
+ "baz",
+ "qux",
+]);
+
+function isPlaceholderSegment(segment: string): boolean {
+ if (segment.length <= 2) return true;
+ return PLACEHOLDER_SEGMENTS.has(segment.toLowerCase());
+}
+
+// ----- Scanning -------------------------------------------------------------
+
+/**
+ * Scan a single text blob. `file` is echoed verbatim into every finding
+ * so the caller controls whether paths are absolute or repo-relative.
+ * Lines carrying {@link HYGIENE_ALLOW_MARKER} contribute no findings.
+ */
+export function scanText(content: string, file: string): HardcodedPathFinding[] {
+ const findings: HardcodedPathFinding[] = [];
+ const lines = content.split("\n");
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i]!;
+ if (line.includes(HYGIENE_ALLOW_MARKER)) continue;
+ collect(line, i + 1, file, UNIX_HOME_RE, "unix-home", findings);
+ collect(line, i + 1, file, WINDOWS_HOME_RE, "windows-home", findings);
+ }
+ return findings;
+}
+
+function collect(
+ line: string,
+ lineNumber: number,
+ file: string,
+ re: RegExp,
+ detector: HardcodedPathDetector,
+ out: HardcodedPathFinding[],
+): void {
+ // `re` is a module-level global regex; reset lastIndex per line so the
+ // stateful `.exec` loop starts clean and never skips a line's first hit.
+ re.lastIndex = 0;
+ let m: RegExpExecArray | null;
+ while ((m = re.exec(line)) !== null) {
+ const segment = m[1]!;
+ if (isPlaceholderSegment(segment)) continue;
+ out.push({
+ file,
+ line: lineNumber,
+ column: m.index + 1,
+ match: m[0],
+ segment,
+ detector,
+ });
+ }
+}
+
+/**
+ * Scan a list of `{ file, content }` pairs. The caller is responsible
+ * for reading files and deciding which ones are in scope; this keeps the
+ * core pure and trivially testable. Findings preserve input order, then
+ * line, then column.
+ */
+export function scanFiles(
+ files: ReadonlyArray<{ readonly file: string; readonly content: string }>,
+): HardcodedPathFinding[] {
+ const out: HardcodedPathFinding[] = [];
+ for (const { file, content } of files) {
+ out.push(...scanText(content, file));
+ }
+ return out;
+}
+
+/** One-line human summary of a finding, suitable for a CI report. */
+export function formatFinding(f: HardcodedPathFinding): string {
+ return `${f.file}:${f.line}:${f.column}: hardcoded home path '${f.match}' (segment '${f.segment}', ${f.detector})`;
+}
diff --git a/src/core/hygiene/scan-repo.ts b/src/core/hygiene/scan-repo.ts
new file mode 100644
index 00000000..5354e6e9
--- /dev/null
+++ b/src/core/hygiene/scan-repo.ts
@@ -0,0 +1,160 @@
+/**
+ * Repo-scoped driver for the hardcoded-path scanner.
+ *
+ * Decides *which* files of the OSB tree the hygiene check looks at β€”
+ * shipped source, docs, generated examples, and plugin config templates
+ * β€” and reads them off disk. The matching logic itself lives in the
+ * pure {@link scanFiles} core; this module is the only part that touches
+ * the filesystem, so tests can drive the core without walking a tree.
+ *
+ * Fixtures and the test tree are deliberately out of scope: they are
+ * full of intentional example paths (`/home/u/vault`, `/Users/x/…`) and
+ * are never installed on an operator's machine.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+import { scanFiles, type HardcodedPathFinding } from "./hardcoded-paths.ts";
+
+/**
+ * Top-level directories walked recursively. Every entry is a surface
+ * that ships to, or is read by, an operator installing OSB.
+ */
+export const SCAN_DIRS: ReadonlyArray<string> = [
+ "src",
+ "docs",
+ "templates",
+ "skills",
+ "plugins",
+ "scripts",
+ "hooks",
+ "install",
+ "schemas",
+ "bin",
+];
+
+/** Individually-scanned root files (docs / manifests, not whole dirs). */
+export const SCAN_ROOT_FILES: ReadonlyArray<string> = [
+ "README.md",
+ "install.md",
+ "after-install.md",
+ "plugin.yaml",
+ "openclaw.plugin.json",
+];
+
+/** Text extensions worth scanning. Binary/asset files are skipped. */
+const SCAN_EXTENSIONS: ReadonlySet<string> = new Set([
+ ".ts",
+ ".js",
+ ".mjs",
+ ".cjs",
+ ".md",
+ ".mdx",
+ ".json",
+ ".jsonc",
+ ".yaml",
+ ".yml",
+ ".toml",
+ ".txt",
+ ".html",
+ ".sh",
+ ".py",
+]);
+
+/**
+ * Path segments that exclude a file from the scan. `tests` and
+ * `fixtures` hold intentional example paths; the rest are VCS / build
+ * noise. `openclaw/index.js` is a generated bundle and is dropped by the
+ * extension-less-of-interest check plus this list's `node_modules` guard
+ * β€” but we also name it explicitly below.
+ */
+const EXCLUDED_SEGMENTS: ReadonlySet<string> = new Set([
+ "node_modules",
+ ".git",
+ ".worktrees",
+ "dist",
+ "build",
+ "tests",
+ "test",
+ "fixtures",
+ "__pycache__",
+ ".venv",
+]);
+
+/** Generated artifacts scanned nowhere, matched by repo-relative path. */
+const EXCLUDED_RELPATHS: ReadonlySet<string> = new Set([join("openclaw", "index.js")]);
+
+function hasScanExtension(name: string): boolean {
+ const dot = name.lastIndexOf(".");
+ if (dot < 0) return false;
+ return SCAN_EXTENSIONS.has(name.slice(dot).toLowerCase());
+}
+
+function isExcludedDir(name: string): boolean {
+ return EXCLUDED_SEGMENTS.has(name);
+}
+
+/** Recursively collect scannable files under `dir`, fail-soft on I/O. */
+function collectFiles(dir: string, root: string, out: string[]): void {
+ let entries;
+ try {
+ entries = readdirSync(dir, { withFileTypes: true });
+ } catch {
+ return; // missing / unreadable dir is not a scan failure
+ }
+ for (const entry of entries) {
+ const abs = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ if (isExcludedDir(entry.name)) continue;
+ collectFiles(abs, root, out);
+ } else if (entry.isFile() && hasScanExtension(entry.name)) {
+ const rel = relative(root, abs);
+ if (EXCLUDED_RELPATHS.has(rel)) continue;
+ out.push(abs);
+ }
+ }
+}
+
+/**
+ * Enumerate every in-scope file under `root`, as repo-relative paths.
+ * Deterministic order (sorted after the walk) so reports diff cleanly
+ * regardless of the readdir ordering the platform returns.
+ */
+export function listScanTargets(root: string): string[] {
+ const abs: string[] = [];
+ for (const dir of SCAN_DIRS) {
+ collectFiles(join(root, dir), root, abs);
+ }
+ for (const name of SCAN_ROOT_FILES) {
+ const p = join(root, name);
+ try {
+ if (statSync(p).isFile()) abs.push(p);
+ } catch {
+ // absent root file is fine
+ }
+ }
+ // Sort to guarantee stable cross-platform output: readdirSync is
+ // alphabetical on POSIX (libuv alphasort) but not guaranteed on Windows.
+ abs.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+ return abs.map((p) => relative(root, p)).map((p) => p.split(sep).join("/"));
+}
+
+/**
+ * Walk the OSB tree under `root`, read every in-scope file, and return
+ * the hardcoded-path findings. Findings carry repo-relative POSIX paths
+ * so they are stable across machines and cheap to assert on in tests.
+ */
+export function scanRepo(root: string): HardcodedPathFinding[] {
+ const targets = listScanTargets(root);
+ const files = targets.map((rel) => {
+ let content = "";
+ try {
+ content = readFileSync(join(root, rel), "utf8");
+ } catch {
+ content = "";
+ }
+ return { file: rel, content };
+ });
+ return scanFiles(files);
+}
diff --git a/src/core/partner/codegraph-health.ts b/src/core/partner/codegraph-health.ts
new file mode 100644
index 00000000..8853c925
--- /dev/null
+++ b/src/core/partner/codegraph-health.ts
@@ -0,0 +1,154 @@
+/**
+ * Read-only graph-health gate for the codegraph partner
+ * (https://github.com/colbymchenry/codegraph, upstream feature parity with
+ * safishamsi/graphify v0.8.46).
+ *
+ * A code graph can be syntactically present - `codegraph status` reports it
+ * `initialized` with node and edge counts - while being subtly wrong: the
+ * index was built for a different root, relationship extraction collapsed to
+ * zero edges, or the partner's own diagnostics found dangling references and
+ * self-loops. Any of those makes the graph an untrustworthy input for
+ * labeling, import, or downstream recall.
+ *
+ * This gate runs AFTER the partner has constructed/indexed the graph and
+ * BEFORE any OSB surface (the partner report, `o2b doctor`, and any future
+ * codegraph-derived edge import) trusts it. It is strictly read-only and
+ * non-destructive: it never runs extraction, never mutates the index or the
+ * vault, and NEVER aborts. Every problem is surfaced as a warning; the caller
+ * decides how loudly to report it. `ok` is a convenience derived from
+ * `warnings.length === 0`.
+ *
+ * Detection is grounded in the fields the real `codegraph status -j` emits
+ * (node/edge counts, `worktreeMismatch`), plus optional partner-provided
+ * diagnostic counts (`danglingRefs`, `selfLoops`) consumed when present so the
+ * gate stays forward-compatible with a richer status surface.
+ */
+
+/** Stable code per health finding so callers can filter without parsing text. */
+export type GraphHealthCode =
+ | "empty-graph"
+ | "collapsed-edges"
+ | "dangling-references"
+ | "self-loops"
+ | "cache-root-mismatch";
+
+/** One non-blocking graph-health finding. */
+export interface GraphHealthWarning {
+ readonly code: GraphHealthCode;
+ readonly message: string;
+}
+
+/** Outcome of the gate. `ok` is true exactly when there are no warnings. */
+export interface GraphHealthReport {
+ readonly ok: boolean;
+ readonly warnings: ReadonlyArray<GraphHealthWarning>;
+}
+
+export interface GraphHealthInput {
+ /** Node count reported by `codegraph status` (defaults to 0 when absent). */
+ readonly nodeCount: number;
+ /** Edge count reported by `codegraph status` (defaults to 0 when absent). */
+ readonly edgeCount: number;
+ /**
+ * Dangling-reference count from the partner's own diagnostics. Optional:
+ * base `codegraph status` does not emit it, so the finding only fires when
+ * a status surface provides it. `undefined` means "not measured", not zero.
+ */
+ readonly danglingRefs?: number;
+ /**
+ * Self-loop edge count from the partner's diagnostics. Same optional
+ * semantics as {@link GraphHealthInput.danglingRefs}.
+ */
+ readonly selfLoops?: number;
+ /**
+ * Absolute root the index was built for (`status.projectPath` or
+ * `worktreeMismatch.indexRoot`). Compared against {@link
+ * GraphHealthInput.worktreeRoot} for the cache-root-mismatch finding.
+ */
+ readonly indexRoot?: string | null;
+ /**
+ * Absolute root the graph is being read from (the in-scope project or
+ * `worktreeMismatch.worktreeRoot`). A mismatch means file/line references in
+ * the graph are rooted elsewhere and may be stale for this tree.
+ */
+ readonly worktreeRoot?: string | null;
+}
+
+/** Strip trailing slashes so `/repo` and `/repo/` compare equal. */
+function stripTrailingSlash(p: string): string {
+ return p.replace(/\/+$/, "");
+}
+
+/** Trailing-slash-insensitive path comparison. */
+function samePath(a: string, b: string): boolean {
+ return stripTrailingSlash(a) === stripTrailingSlash(b);
+}
+
+/**
+ * Assess graph health from the partner status projection. Pure, total, and
+ * never-throwing: unknown or missing inputs simply produce no warning rather
+ * than a false positive. Findings are returned in a stable, severity-ordered
+ * sequence (structural emptiness first, then reference integrity, then
+ * root provenance) so callers can render them deterministically.
+ */
+export function assessGraphHealth(input: GraphHealthInput): GraphHealthReport {
+ const warnings: GraphHealthWarning[] = [];
+ const nodes = Number.isFinite(input.nodeCount) ? input.nodeCount : 0;
+ const edges = Number.isFinite(input.edgeCount) ? input.edgeCount : 0;
+
+ if (nodes <= 0) {
+ warnings.push({
+ code: "empty-graph",
+ message:
+ "index is initialized but holds 0 nodes; extraction produced an empty graph - " +
+ "labeling and recall will find nothing until it is re-indexed",
+ });
+ } else if (edges <= 0) {
+ // Nodes without edges: symbols were extracted but no relationships. Only
+ // meaningful when there is at least one node (an empty graph is reported
+ // above and should not double-warn).
+ warnings.push({
+ code: "collapsed-edges",
+ message:
+ `graph has ${nodes} node(s) but 0 edges; relationship extraction collapsed - ` +
+ "callers/callees/impact traversal will be empty",
+ });
+ }
+
+ if (input.danglingRefs !== undefined && input.danglingRefs > 0) {
+ warnings.push({
+ code: "dangling-references",
+ message:
+ `${input.danglingRefs} dangling reference(s): edges point at nodes absent from the ` +
+ "index; derived labels/imports built from them would reference missing symbols",
+ });
+ }
+
+ if (input.selfLoops !== undefined && input.selfLoops > 0) {
+ warnings.push({
+ code: "self-loops",
+ message:
+ `${input.selfLoops} self-loop edge(s): a node references itself; ` +
+ "impact and traversal surfaces may double-count or cycle",
+ });
+ }
+
+ if (input.indexRoot && input.worktreeRoot && !samePath(input.indexRoot, input.worktreeRoot)) {
+ warnings.push({
+ code: "cache-root-mismatch",
+ message:
+ `index was built for '${input.indexRoot}' but is being read from ` +
+ `'${input.worktreeRoot}'; file and line references may be stale for this tree - ` +
+ "re-index the current root before trusting graph-derived artifacts",
+ });
+ }
+
+ return { ok: warnings.length === 0, warnings };
+}
+
+/** Compact one-line summary of a report, e.g. `2 warning(s) [collapsed-edges, self-loops]`. */
+export function summarizeGraphHealth(report: GraphHealthReport): string {
+ if (report.warnings.length === 0) return "ok";
+ const codes = report.warnings.map((w) => w.code).join(", ");
+ return `${report.warnings.length} warning(s) [${codes}]`;
+}
diff --git a/src/core/partner/codegraph-report.ts b/src/core/partner/codegraph-report.ts
index a1c1aafb..ec4074e1 100644
--- a/src/core/partner/codegraph-report.ts
+++ b/src/core/partner/codegraph-report.ts
@@ -23,6 +23,7 @@ import {
findCodeProjects,
type CodegraphStatusResult,
} from "./codegraph.ts";
+import { assessGraphHealth, type GraphHealthReport } from "./codegraph-health.ts";
export interface CargoWorkspace {
readonly manifestPath: string;
@@ -178,6 +179,14 @@ export interface CodegraphReport {
readonly file_count?: number;
readonly edge_count?: number;
readonly reason?: string;
+ /**
+ * Read-only graph-health gate result. Present only when the index is
+ * `indexed` (there is a graph to assess). Findings are non-blocking
+ * warnings - a syntactically present graph that is nonetheless an
+ * untrustworthy input for labeling/import/recall (empty, edge-collapsed,
+ * dangling references, self-loops, or built for a different root).
+ */
+ readonly health?: GraphHealthReport;
};
readonly cargo_workspace: CargoWorkspace | null;
readonly cargo_workspace_reason: string;
@@ -256,10 +265,21 @@ function resolveIndexState(
if (!status.data.initialized) {
return { state: "not_indexed", reason: `run: codegraph init ${project}` };
}
+ const nodeCount = status.data.nodeCount ?? 0;
+ const edgeCount = status.data.edgeCount ?? 0;
+ const health = assessGraphHealth({
+ nodeCount,
+ edgeCount,
+ ...(status.data.danglingRefs !== undefined ? { danglingRefs: status.data.danglingRefs } : {}),
+ ...(status.data.selfLoops !== undefined ? { selfLoops: status.data.selfLoops } : {}),
+ indexRoot: status.data.worktreeMismatch?.indexRoot ?? status.data.projectPath ?? null,
+ worktreeRoot: status.data.worktreeMismatch?.worktreeRoot ?? project,
+ });
return {
state: "indexed",
- node_count: status.data.nodeCount ?? 0,
+ node_count: nodeCount,
file_count: status.data.fileCount ?? 0,
- edge_count: status.data.edgeCount ?? 0,
+ edge_count: edgeCount,
+ health,
};
}
diff --git a/src/core/partner/codegraph.ts b/src/core/partner/codegraph.ts
index 4634a6ab..02619581 100644
--- a/src/core/partner/codegraph.ts
+++ b/src/core/partner/codegraph.ts
@@ -12,10 +12,11 @@
* from config. No deep filesystem walk.
*/
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import type { CheckResult } from "../types.ts";
+import { assessGraphHealth, summarizeGraphHealth } from "./codegraph-health.ts";
const CODE_MANIFESTS: ReadonlyArray<string> = [
"package.json",
@@ -109,11 +110,35 @@ export function findCodeProjects(opts: FindCodeProjectsOptions): string[] {
return found;
}
+/**
+ * The root the index was built for vs. the root it is being read from.
+ * `codegraph status -j` emits this block only when they differ (e.g. the
+ * index lives at the repo root but is queried from a git worktree). Its
+ * presence is the raw signal behind the graph-health `cache-root-mismatch`
+ * finding.
+ */
+export interface CodegraphWorktreeMismatch {
+ readonly worktreeRoot: string;
+ readonly indexRoot: string;
+}
+
export interface CodegraphStatusData {
readonly initialized: boolean;
readonly nodeCount?: number;
readonly fileCount?: number;
readonly edgeCount?: number;
+ /** Absolute root the index was built for (`status.projectPath`). */
+ readonly projectPath?: string;
+ /** Present only when the index root differs from the queried root. */
+ readonly worktreeMismatch?: CodegraphWorktreeMismatch;
+ /**
+ * Optional partner-provided graph diagnostics. Base `codegraph status`
+ * does not emit these today; the graph-health gate consumes them when a
+ * richer status surface provides them, and treats their absence as
+ * "not measured" (no finding), never as zero.
+ */
+ readonly danglingRefs?: number;
+ readonly selfLoops?: number;
}
export type CodegraphStatusResult =
@@ -228,9 +253,45 @@ export function checkCodegraph(
const nodes = status.data.nodeCount ?? 0;
const files = status.data.fileCount ?? 0;
+ const base = `code project at ${project}: indexed (${nodes} nodes, ${files} files)`;
+
+ // Read-only graph-health gate. Runs after the partner has indexed the graph
+ // and before OSB surfaces trust it. Findings are non-blocking: the graph is
+ // present and usable, so `ok` stays true (a cache-root mismatch, common in
+ // worktree checkouts, must not fail `o2b doctor`) - but the summary is
+ // appended so an operator sees the warning and can drill in via
+ // `o2b partner codegraph report`.
+ const health = assessGraphHealth({
+ nodeCount: nodes,
+ edgeCount: status.data.edgeCount ?? 0,
+ ...(status.data.danglingRefs !== undefined ? { danglingRefs: status.data.danglingRefs } : {}),
+ ...(status.data.selfLoops !== undefined ? { selfLoops: status.data.selfLoops } : {}),
+ indexRoot: resolveRealpath(
+ status.data.worktreeMismatch?.indexRoot ?? status.data.projectPath ?? null,
+ ),
+ worktreeRoot: resolveRealpath(status.data.worktreeMismatch?.worktreeRoot ?? project),
+ });
+
return {
name: "code_graph",
ok: true,
- message: `code project at ${project}: indexed (${nodes} nodes, ${files} files)`,
+ message: health.ok
+ ? base
+ : `${base}; graph-health: ${summarizeGraphHealth(health)} - run: o2b partner codegraph report`,
};
}
+
+/**
+ * Resolve a path through symlinks so the cache-root-mismatch comparison treats
+ * a real checkout and its symlinked worktree as the same root. Falls back to
+ * the raw value when the path is missing or unreadable (a missing path is not
+ * a topology mismatch worth warning about here).
+ */
+function resolveRealpath(value: string | null | undefined): string | null {
+ if (!value) return null;
+ try {
+ return realpathSync(value);
+ } catch {
+ return value;
+ }
+}
diff --git a/src/core/redactor.ts b/src/core/redactor.ts
index 84d0866b..a9f41303 100644
--- a/src/core/redactor.ts
+++ b/src/core/redactor.ts
@@ -15,6 +15,21 @@
* intentionally narrow β€” receipts and signals carry a disclaimer that
* the agent must visually inspect output before posting externally.
*
+ * An optional infra-topology pass (`redactInfra`) additionally scrubs
+ * bare network coordinates that carry no `key=value` shape β€” public
+ * IPv4/IPv6 literals, `user:pass@host` URL credentials, `host:port`
+ * endpoints, and internal hostnames. It is off by default (the key/value
+ * passes suffice for receipts) and enabled on the artifact store, which
+ * persists full tool payloads where a bare IP or internal FQDN is the
+ * most common topology leak. Every infra regex is bounded (no nested
+ * unbounded quantifiers), so the pass stays linear on large inputs.
+ *
+ * Oversized input FAILS CLOSED: rather than silently dropping the tail
+ * past the scan window as if it were clean, {@link redactRawOutput}
+ * appends {@link SCAN_TRUNCATED_MARKER}. {@link wasScanTruncated} lets a
+ * downstream consumer detect that marker and demote/exclude the artifact
+ * instead of trusting a partially-scanned payload.
+ *
* `normaliseTextField` is the shared input sanitiser for fields that
* land in YAML frontmatter or single-line Markdown bullets. It strips
* C0 control characters (except `\n` and `\t`), folds the unicode line
@@ -30,15 +45,41 @@ const PLACEHOLDER = "***REDACTED***";
export const PRIVATE_REGION_PLACEHOLDER = "***PRIVATE***";
/**
- * Maximum input size accepted by `redactRawOutput`. Receipts have no
+ * Maximum input size scanned by `redactRawOutput`. Receipts have no
* legitimate reason to embed multi-megabyte payloads β€” a runaway pipe
- * of server logs is the realistic cause of an oversize input. Capping
- * at 256 KB keeps the four-pass regex pipeline bounded and avoids a
- * DoS vector for whoever's caller is feeding the redactor.
+ * of server logs is the realistic cause of an oversize input. The
+ * regex pipeline is linear, so the window is a DoS bound rather than a
+ * correctness limit; 1 MiB is wide enough that a secret rarely lands
+ * past it, and anything that does trips the fail-closed marker below
+ * rather than being dropped as if it were clean.
*/
-export const MAX_REDACTOR_INPUT = 256 * 1024;
-const TRUNCATION_MARKER =
- "\n\n[…truncated for size; original exceeded 256 KB. Inspect raw output before sharing.]\n";
+export const MAX_REDACTOR_INPUT = 1024 * 1024;
+
+/**
+ * Stable, machine-detectable token embedded in {@link SCAN_TRUNCATED_MARKER}.
+ * {@link wasScanTruncated} matches on this so downstream consumers can
+ * demote/exclude a partially-scanned artifact without parsing prose.
+ */
+const SCAN_TRUNCATED_TOKEN = "***SCAN_TRUNCATED***";
+
+/**
+ * Appended when input exceeds the scan window. The tail past the window
+ * is dropped *and* flagged: because it was never scanned, the whole
+ * payload must be treated as unverified rather than clean.
+ */
+export const SCAN_TRUNCATED_MARKER =
+ `\n\n${SCAN_TRUNCATED_TOKEN} [redactor scan window exceeded (> 1 MiB); the unscanned tail was dropped. ` +
+ `This payload was only partially scanned β€” treat it as unverified and inspect the raw source before sharing.]\n`;
+
+/**
+ * True when `text` carries the fail-closed marker appended by
+ * {@link redactRawOutput} on oversized input. Consumers use this to
+ * demote or exclude an artifact that could not be fully scanned instead
+ * of trusting the redactor's output as complete.
+ */
+export function wasScanTruncated(text: string): boolean {
+ return typeof text === "string" && text.includes(SCAN_TRUNCATED_TOKEN);
+}
const PRIVATE_OPEN_TAG_RE = /<private\b[^>]*>/gi;
const PRIVATE_CLOSE_TAG_RE = /<\/private>/gi;
@@ -92,6 +133,111 @@ const JSON_ENTRY_RE = new RegExp(
// and only replace the token portion.
const BEARER_RE = /\b(Bearer\s+)([A-Za-z0-9._\-+/=]+)/gi;
+// ----- Infra-topology detectors (opt-in via `redactInfra`) ------------------
+//
+// These scrub network coordinates that carry no key=value shape, so the
+// assignment passes above never see them. Every regex uses only bounded
+// repetition ({m,n}) β€” no nested unbounded quantifiers β€” so the pass is
+// linear and cannot be driven into catastrophic backtracking (ReDoS) by
+// a large adversarial input.
+
+/** A single dotted-quad octet (0-255), used to compose IPv4 patterns. */
+const IPV4_OCTET = "(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)";
+/** A syntactically-valid IPv4 literal (four octets). */
+const IPV4 = `${IPV4_OCTET}(?:\\.${IPV4_OCTET}){3}`;
+
+// `scheme://user:pass@host` β€” strip the embedded credentials but keep the
+// scheme and `@host` for readability. Run first so the host that follows
+// is still available to the host/port passes below.
+const BASIC_AUTH_URL_RE = /\b([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^\s/:@]+):([^\s/@]+)@/g;
+
+// `ipv4:port` β€” a reachable service endpoint. Redacted whole regardless of
+// whether the address is public or private (the port is what leaks the
+// service). Runs before the bare-IPv4 pass so the port form is caught first.
+const IPV4_PORT_RE = new RegExp(`\\b${IPV4}:\\d{1,5}\\b`, "g");
+
+// `fqdn:port` β€” a named service endpoint (`db.example.com:5432`). The final
+// label is alphabetic, so this never collides with `ipv4:port`. A negative
+// lookahead skips source-file extensions (`index.js:42`, `app.ts:128`) so
+// diagnostics and stack frames are not mistaken for service endpoints when
+// `redactInfra` runs over tool output (e.g. ArtifactStore.put).
+const FQDN_PORT_SOURCE_EXTS =
+ "js|ts|tsx|jsx|py|json|rs|go|java|rb|php|c|cc|cpp|cxx|h|hpp|css|scss|sass|less|" +
+ "html|htm|xml|yaml|yml|toml|ini|cfg|md|markdown|sh|bash|sql|vue|svelte|gradle|" +
+ "kt|swift|scala|clj|ex|exs|erl|elm|dart|lua|pl|pm|r|jl|tf|lock|map|txt|csv|log";
+const FQDN_PORT_RE = new RegExp(
+ "\\b(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+(?!(" +
+ FQDN_PORT_SOURCE_EXTS +
+ "):\\d)[a-zA-Z]{2,63}:\\d{1,5}\\b",
+ "g",
+);
+
+// Internal hostnames β€” FQDNs under a private/self-hosted suffix
+// (`db.internal`, `svc.cluster.local`, `host.corp`, …). These reveal
+// internal topology even without a port.
+const INTERNAL_HOST_RE =
+ /\b(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+(?:internal|intranet|localdomain|local|lan|corp|home)\b/gi;
+
+// Bare IPv6 literals: either a full 8-group address or any `::`-compressed
+// form. Requiring `::` or 8 groups keeps `HH:MM:SS`-style timestamps (only
+// two colons, no `::`) from being mistaken for an address. Every quantifier
+// is bounded.
+const IPV6_RE = new RegExp(
+ "(?<![\\w:.])(?:" +
+ // full 8 groups
+ "(?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}" +
+ "|" +
+ // `::`-compressed with leading groups (e.g. 2001:db8::1, fe80::)
+ "(?:[0-9A-Fa-f]{1,4}:){0,6}[0-9A-Fa-f]{1,4}::(?:[0-9A-Fa-f]{1,4}:){0,6}[0-9A-Fa-f]{0,4}" +
+ "|" +
+ // leading `::` (e.g. ::1, ::ffff:1.2.3.4-style prefix)
+ "::(?:[0-9A-Fa-f]{1,4}:){0,6}[0-9A-Fa-f]{1,4}" +
+ ")(?![\\w:.])",
+ "g",
+);
+
+// Bare IPv4 literal not part of a longer dotted run (excludes version
+// strings like `1.2.3.4.5` and `v1.2.3`). Public-only: the callback skips
+// private/reserved ranges.
+const IPV4_BARE_RE = new RegExp(`(?<![\\w.])${IPV4}(?![\\w.])`, "g");
+
+/** RFC 1918 / loopback / link-local / CGNAT / multicast+reserved IPv4. */
+function isPrivateOrReservedIPv4(ip: string): boolean {
+ const octets = ip.split(".");
+ const a = Number.parseInt(octets[0] ?? "", 10);
+ const b = Number.parseInt(octets[1] ?? "", 10);
+ if (a === 0 || a === 10 || a === 127) return true; // this-network, private, loopback
+ if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
+ if (a === 192 && b === 168) return true; // 192.168.0.0/16
+ if (a === 169 && b === 254) return true; // link-local
+ if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT 100.64.0.0/10
+ if (a >= 224) return true; // multicast + reserved (224+)
+ return false;
+}
+
+/** Loopback / unspecified / link-local (fe80::/10) / unique-local (fc00::/7). */
+function isPrivateOrReservedIPv6(ip: string): boolean {
+ const lower = ip.toLowerCase();
+ if (lower === "::" || lower === "::1") return true;
+ if (/^fe[89ab]/.test(lower)) return true; // link-local
+ if (/^f[cd]/.test(lower)) return true; // unique-local
+ return false;
+}
+
+function redactInfraTopology(text: string): string {
+ let out = text.replace(BASIC_AUTH_URL_RE, (_m, scheme: string) => `${scheme}${PLACEHOLDER}@`);
+ out = out.replace(IPV4_PORT_RE, PLACEHOLDER);
+ out = out.replace(FQDN_PORT_RE, PLACEHOLDER);
+ out = out.replace(INTERNAL_HOST_RE, PLACEHOLDER);
+ out = out.replace(IPV6_RE, (match: string) =>
+ isPrivateOrReservedIPv6(match) ? match : PLACEHOLDER,
+ );
+ out = out.replace(IPV4_BARE_RE, (match: string) =>
+ isPrivateOrReservedIPv4(match) ? match : PLACEHOLDER,
+ );
+ return out;
+}
+
export function stripPrivateRegions(text: string): string {
if (!text) return text;
@@ -137,7 +283,7 @@ export function stripPrivateRegions(text: string): string {
export interface RedactRawOutputOptions {
/**
* Maximum input length before the truncation guard fires. Defaults to
- * {@link MAX_REDACTOR_INPUT} (256 KiB) - the right cap for receipts,
+ * {@link MAX_REDACTOR_INPUT} (1 MiB) - the right cap for receipts,
* where a multi-megabyte payload is a runaway log pipe. Callers that
* must redact-without-losing-data (the MCP artifact store, whose whole
* job is to preserve the full payload for later fetch) pass
@@ -153,6 +299,15 @@ export interface RedactRawOutputOptions {
* when no key=value shape surrounds it.
*/
readonly literals?: ReadonlyArray<string>;
+ /**
+ * When `true`, also run the infra-topology pass (public IPv4/IPv6,
+ * `user:pass@host` URL credentials, `host:port` endpoints, internal
+ * hostnames). Off by default β€” the key/value passes suffice for
+ * receipts, and blanket IP/host redaction would mangle legitimate
+ * prose. Enabled on the artifact store, whose full tool payloads are
+ * where a bare coordinate is the likeliest topology leak.
+ */
+ readonly redactInfra?: boolean;
}
export function redactRawOutput(text: string, opts: RedactRawOutputOptions = {}): string {
@@ -167,8 +322,11 @@ export function redactRawOutput(text: string, opts: RedactRawOutputOptions = {})
out = out.split(literal).join(PLACEHOLDER);
}
+ // Fail closed on oversized input: scan the prefix that fits the window,
+ // drop the unscanned tail, and flag the result so a downstream consumer
+ // treats it as unverified rather than trusting it as fully scanned.
const maxInput = opts.maxInput ?? MAX_REDACTOR_INPUT;
- if (out.length > maxInput) out = out.slice(0, maxInput) + TRUNCATION_MARKER;
+ if (out.length > maxInput) out = out.slice(0, maxInput) + SCAN_TRUNCATED_MARKER;
out = stripPrivateRegions(out);
@@ -200,6 +358,11 @@ export function redactRawOutput(text: string, opts: RedactRawOutputOptions = {})
return `${key}${sep}${PLACEHOLDER}`;
});
+ // Infra-topology pass last: it runs on values the key/value passes
+ // already left untouched (bare coordinates), and any value they redacted
+ // is now a placeholder with no IP/host shape left to match.
+ if (opts.redactInfra) out = redactInfraTopology(out);
+
return out;
}
diff --git a/src/core/vault.ts b/src/core/vault.ts
index 82214ef9..8db475b0 100644
--- a/src/core/vault.ts
+++ b/src/core/vault.ts
@@ -7,6 +7,7 @@
* through Obsidian and the simple parser.
*/
+import { createHash } from "node:crypto";
import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import { dirname, join, relative } from "node:path";
@@ -196,17 +197,48 @@ export function writeFrontmatterAtomic(
}
}
+const SLUG_FALLBACK_PREFIX = "unnamed";
+const SLUG_FALLBACK_HASH_LEN = 8;
+
+/**
+ * Stable safe basename for a title that slugifies to nothing β€” empty,
+ * whitespace-only, or punctuation / emoji / combining-mark-only input.
+ *
+ * A bare shared constant (the old `"note"`) is stable but collides: every
+ * punctuation-only title lands on the same basename, so `@`, `!!!`, and an
+ * emoji all fight for one filename in a synced vault. Instead we suffix a
+ * short sha256 digest of the normalized input, which is
+ * - deterministic β€” the same empty-slug title yields the same basename on
+ * every device and under a re-slug, and
+ * - distinct β€” different empty-slug titles get different basenames.
+ *
+ * The suffix is hex (`[a-f0-9]`), so the result stays traversal-safe and is
+ * idempotent under a second `slugify` pass.
+ */
+function unnamedFallbackSlug(normalized: string): string {
+ const digest = createHash("sha256")
+ .update(normalized, "utf8")
+ .digest("hex")
+ .slice(0, SLUG_FALLBACK_HASH_LEN);
+ return `${SLUG_FALLBACK_PREFIX}-${digest}`;
+}
+
/**
* Convert a free-form title to a URL-safe slug. Lowercase, alphanumeric
- * runs joined by `-`, trimmed to 64 chars. Empty / non-ASCII inputs fall
- * back to "note".
+ * runs joined by `-`, trimmed to 64 chars. Inputs that slugify to nothing
+ * (empty, whitespace-only, punctuation / emoji / combining-mark-only) fall
+ * back to a stable `unnamed-<hash>` basename β€” see `unnamedFallbackSlug`.
*/
export function slugify(value: string): string {
const lowered = value.trim().toLowerCase();
let slug = lowered.replace(SLUG_INVALID_RE, "-").replace(/^-+|-+$/g, "");
- if (!slug) slug = "note";
+ if (!slug) return unnamedFallbackSlug(lowered);
slug = slug.slice(0, SLUG_MAX_LEN).replace(/-+$/, "");
- return slug || "note";
+ // Defensive only: SLUG_MAX_LEN (64) > 0 and the leading-trim above
+ // guarantees a non-empty alnum-started slug here, so slicing cannot
+ // produce "". Kept so a future SLUG_MAX_LEN or generation change cannot
+ // silently produce an empty slug.
+ return slug || unnamedFallbackSlug(lowered);
}
/**
diff --git a/src/mcp/artifact-store.ts b/src/mcp/artifact-store.ts
index a19371d5..5b687c44 100644
--- a/src/mcp/artifact-store.ts
+++ b/src/mcp/artifact-store.ts
@@ -69,9 +69,15 @@ export class ArtifactStore {
*/
put(fullText: string): StoredArtifact {
// Scrub secrets but never truncate: the artifact IS the recoverable
- // full payload, so the receipt-oriented 256 KiB context cap must not
- // apply here, or large results would be silently clipped on disk.
- const text = redactRawOutput(fullText, { maxInput: Number.POSITIVE_INFINITY });
+ // full payload, so the receipt-oriented scan-window cap must not apply
+ // here, or large results would be silently clipped on disk. The whole
+ // payload is scanned, so also run the infra-topology pass β€” a bare
+ // public IP or internal hostname in a stored tool result is the
+ // likeliest topology leak and carries no key=value shape to catch it.
+ const text = redactRawOutput(fullText, {
+ maxInput: Number.POSITIVE_INFINITY,
+ redactInfra: true,
+ });
const artifactId = createHash("sha256")
.update(text, "utf8")
.digest("hex")
diff --git a/src/mcp/brain/knowledge-tools.ts b/src/mcp/brain/knowledge-tools.ts
index 88ef124a..e1c6c94e 100644
--- a/src/mcp/brain/knowledge-tools.ts
+++ b/src/mcp/brain/knowledge-tools.ts
@@ -562,7 +562,7 @@ export const KNOWLEDGE_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: "brain_codegraph_report",
description:
- "Read-only codegraph partner report: resolves the in-scope code project, reports index state (no_project|absent|not_indexed|indexed|error, with counts), and structurally parses Cargo.toml for workspace members. Non-Rust projects report cargo_workspace: null. Never installs or mutates.",
+ "Read-only codegraph partner report: in-scope project, index state + counts, and Cargo.toml workspace members. When indexed, adds a non-blocking graph-health gate (index.health: dangling refs, self-loops, collapsed edges, cache-root mismatch) before labeling/import trust the graph. Never mutates.",
inputSchema: {
type: "object",
properties: {},
diff --git a/src/mcp/brain/recall-tools.ts b/src/mcp/brain/recall-tools.ts
index 9bb5f285..5424ed3c 100644
--- a/src/mcp/brain/recall-tools.ts
+++ b/src/mcp/brain/recall-tools.ts
@@ -11,6 +11,7 @@ import { appendMetric } from "../../core/brain/metrics.ts";
import { parseRecallBenchmarkDataset, runRecallBenchmark } from "../../core/search/benchmark.ts";
import { loadTunedParameters, resetTuning, tuneRecall } from "../../core/search/tuning.ts";
import { listGateTelemetry, summarizeGateTelemetry } from "../../core/brain/gate-telemetry.ts";
+import { computeMemoryCostMeter } from "../../core/brain/memory-cost-meter.ts";
import {
isRecallTelemetryMode,
isRecallTelemetryStatus,
@@ -181,12 +182,55 @@ async function toolBrainRecallTelemetry(
});
return { ...summary };
}
+ // Write-vs-read cost meter (memory cost meter): folds write volume
+ // against the read telemetry above. Period-based; mode/status/host/limit
+ // do not apply to the write side, so reject them to mirror the CLI's
+ // fail-closed behavior (recall-telemetry.ts costMeter) rather than
+ // silently ignoring and looking like a valid filtered result.
+ if (operation === "cost") {
+ for (const name of ["mode", "status", "host", "limit"] as const) {
+ if (args[name] !== undefined) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ `brain_recall_telemetry: ${name} is not supported for the cost meter`,
+ );
+ }
+ }
+ const writeCost = coerceNonNegativeNumber("write_cost", args["write_cost"]);
+ const readCost = coerceNonNegativeNumber("read_cost", args["read_cost"]);
+ const writeHeavyRatio = coerceNonNegativeNumber("write_heavy_ratio", args["write_heavy_ratio"]);
+ const meter = computeMemoryCostMeter(ctx.vault, {
+ ...(filter.since !== undefined ? { since: filter.since } : {}),
+ ...(filter.until !== undefined ? { until: filter.until } : {}),
+ ...(writeCost !== undefined || readCost !== undefined
+ ? {
+ weights: {
+ ...(writeCost !== undefined ? { write: writeCost } : {}),
+ ...(readCost !== undefined ? { read: readCost } : {}),
+ },
+ }
+ : {}),
+ ...(writeHeavyRatio !== undefined ? { writeHeavyRatio } : {}),
+ });
+ return { vault_path: ctx.vault, ...meter };
+ }
throw new MCPError(
INVALID_PARAMS,
- "brain_recall_telemetry: operation must be list, summary, gate_list, or gate_summary",
+ "brain_recall_telemetry: operation must be list, summary, gate_list, gate_summary, or cost",
);
}
+function coerceNonNegativeNumber(name: string, raw: unknown): number | undefined {
+ if (raw === undefined || raw === null) return undefined;
+ if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ `brain_recall_telemetry: ${name} must be a non-negative number`,
+ );
+ }
+ return raw;
+}
+
function recallTelemetryFilter(args: Record<string, unknown>): RecallTelemetryFilter {
const mode = coerceRecallTelemetryMode(args["mode"]);
const status = coerceRecallTelemetryStatus(args["status"]);
@@ -330,15 +374,15 @@ export const RECALL_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
name: "brain_recall_telemetry",
previewBudget: MCP_PREVIEW_BUDGET,
description:
- "List recall telemetry records or summarize recall coverage and knowledge gaps. Records are emitted only by opt-in callers. Read-only.",
+ "List recall telemetry records or summarize recall coverage and gaps; cost folds write volume (feedback/apply-evidence/note/host writes) against reads into a write-vs-read ratio, a write-heavy flag, and a rough cost signal per period. Emitted only by opt-in callers. Read-only.",
inputSchema: {
type: "object",
properties: {
operation: {
type: "string",
- enum: ["list", "summary", "gate_list", "gate_summary"],
+ enum: ["list", "summary", "gate_list", "gate_summary", "cost"],
description:
- "list/summary for recall telemetry; gate_list/gate_summary for recall-gate decisions.",
+ "list/summary for recall telemetry; gate_list/gate_summary for recall-gate decisions; cost for the write-vs-read cost meter.",
},
mode: {
type: "string",
@@ -367,6 +411,22 @@ export const RECALL_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
minimum: 1,
description: "Optional maximum record count for list.",
},
+ write_cost: {
+ type: "number",
+ minimum: 0,
+ description: "cost: weight charged per write op (default 1).",
+ },
+ read_cost: {
+ type: "number",
+ minimum: 0,
+ description: "cost: weight charged per read op (default 1).",
+ },
+ write_heavy_ratio: {
+ type: "number",
+ minimum: 0,
+ description:
+ "cost: write/read ratio above which the period is flagged write-heavy (default 1).",
+ },
},
required: ["operation"],
additionalProperties: false,
diff --git a/tests/core/brain.sessions.import.test.ts b/tests/core/brain.sessions.import.test.ts
index e1162adb..e9cefbfa 100644
--- a/tests/core/brain.sessions.import.test.ts
+++ b/tests/core/brain.sessions.import.test.ts
@@ -7,9 +7,9 @@
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } 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 { basename, dirname, join, resolve } from "node:path";
import { brainDirs } from "../../src/core/brain/paths.ts";
import { DEFAULT_BRAIN_CONFIG_YAML } from "../../src/core/brain/policy.ts";
@@ -87,6 +87,31 @@ describe("importSession", () => {
expect(second.signals_deduped).toBe(first.signals_created);
});
+ test("persists a portable session_ref, not the absolute session-file path", async () => {
+ // The session fixture lives OUTSIDE the vault at an absolute path.
+ // A synced signal must not carry that machine-local path in its
+ // provenance (Syncthing peers on Mac/Android cannot resolve it):
+ // the ref keys the session by basename, matching the recall DAG id.
+ const res = await importSession(tmp, CLAUDE, { agent: "test" });
+ expect(res.signals_created).toBeGreaterThan(0);
+
+ const inbox = brainDirs(tmp).inbox;
+ const files = readdirSync(inbox).filter((n) => n.startsWith("sig-"));
+ expect(files.length).toBeGreaterThan(0);
+
+ const absDir = dirname(CLAUDE);
+ for (const name of files) {
+ const text = readFileSync(join(inbox, name), "utf8");
+ // No absolute host directory of the session file leaked in.
+ expect(text).not.toContain(absDir);
+ expect(text).not.toContain(CLAUDE);
+ // The portable identity (basename#turn) is present instead, in both
+ // the `source` wikilink and the `session_ref` field.
+ expect(text).toContain(`[[${basename(CLAUDE)}#`);
+ expect(text).toContain(`session_ref: "${basename(CLAUDE)}#`);
+ }
+ });
+
test("dry-run does not write signals", async () => {
const res = await importSession(tmp, CLAUDE, {
agent: "test",
diff --git a/tests/core/brain/memory-cost-meter.test.ts b/tests/core/brain/memory-cost-meter.test.ts
new file mode 100644
index 00000000..a63cf2e3
--- /dev/null
+++ b/tests/core/brain/memory-cost-meter.test.ts
@@ -0,0 +1,158 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { appendLogEvent } from "../../../src/core/brain/log.ts";
+import { recordHostMemoryWrite } from "../../../src/core/brain/host-memory-write.ts";
+import { emitRecallTelemetry } from "../../../src/core/brain/recall-telemetry.ts";
+import {
+ computeMemoryCostMeter,
+ summarizeMemoryWrites,
+} from "../../../src/core/brain/memory-cost-meter.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-memory-cost-meter-"));
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function writeEvent(kind: string, timestamp: string): void {
+ appendLogEvent(
+ vault,
+ {
+ timestamp,
+ eventType: kind as never,
+ agent: "claude",
+ body: { agent: "claude" },
+ },
+ { deviceId: "" },
+ );
+}
+
+function read(createdAt: string, mode: "search" | "context_pack" | "query"): void {
+ emitRecallTelemetry(vault, {
+ createdAt,
+ host: "unit-test",
+ mode,
+ status: "ok",
+ durationMs: 1,
+ resultCount: 1,
+ });
+}
+
+describe("summarizeMemoryWrites", () => {
+ test("counts brain-log write verbs and host-bridge writes; ignores lifecycle events", () => {
+ writeEvent("feedback", "2026-07-01T10:00:00Z");
+ writeEvent("apply-evidence", "2026-07-01T10:01:00Z");
+ writeEvent("note", "2026-07-01T10:02:00Z");
+ // Lifecycle transitions are not writes and must be ignored.
+ writeEvent("promote", "2026-07-01T10:03:00Z");
+ writeEvent("retire", "2026-07-01T10:04:00Z");
+ recordHostMemoryWrite(vault, {
+ action: "add",
+ target: "memory",
+ content: "remember this",
+ createdAt: "2026-07-01T10:05:00Z",
+ });
+
+ const summary = summarizeMemoryWrites(vault);
+ expect(summary.total).toBe(4);
+ expect(summary.by_kind).toEqual({
+ feedback: 1,
+ apply_evidence: 1,
+ note: 1,
+ host_memory_write: 1,
+ });
+ });
+
+ test("bounds writes by inclusive since/until across both sources", () => {
+ writeEvent("feedback", "2026-06-30T23:59:59Z"); // before window
+ writeEvent("note", "2026-07-01T12:00:00Z"); // in window
+ recordHostMemoryWrite(vault, {
+ action: "add",
+ target: "user",
+ content: "in window",
+ createdAt: "2026-07-02T00:00:00Z",
+ });
+ recordHostMemoryWrite(vault, {
+ action: "add",
+ target: "user",
+ content: "after window",
+ createdAt: "2026-07-03T00:00:01Z",
+ });
+
+ const summary = summarizeMemoryWrites(vault, {
+ since: "2026-07-01T00:00:00Z",
+ until: "2026-07-03T00:00:00Z",
+ });
+ expect(summary.total).toBe(2);
+ expect(summary.by_kind).toEqual({ note: 1, host_memory_write: 1 });
+ });
+});
+
+describe("computeMemoryCostMeter", () => {
+ test("folds writes against reads into ratio, cost, and write-heavy flag", () => {
+ // 3 writes, 2 reads β†’ ratio 1.5, write-heavy under the default ratio of 1.
+ writeEvent("feedback", "2026-07-01T10:00:00Z");
+ writeEvent("feedback", "2026-07-01T10:01:00Z");
+ writeEvent("note", "2026-07-01T10:02:00Z");
+ read("2026-07-01T11:00:00.000Z", "search");
+ read("2026-07-01T11:01:00.000Z", "context_pack");
+
+ const meter = computeMemoryCostMeter(vault);
+ expect(meter.writes.total).toBe(3);
+ expect(meter.reads.total).toBe(2);
+ expect(meter.write_read_ratio).toBe(1.5);
+ expect(meter.write_heavy).toBe(true);
+ expect(meter.reads.by_mode).toEqual({ search: 1, context_pack: 1 });
+ // Default unit weights: cost equals op counts.
+ expect(meter.cost).toEqual({ write: 3, read: 2, total: 5 });
+ });
+
+ test("applies custom weights and a custom write-heavy threshold", () => {
+ writeEvent("feedback", "2026-07-01T10:00:00Z");
+ writeEvent("note", "2026-07-01T10:01:00Z");
+ read("2026-07-01T11:00:00.000Z", "search");
+ read("2026-07-01T11:01:00.000Z", "search");
+
+ const meter = computeMemoryCostMeter(vault, {
+ weights: { write: 5, read: 0.5 },
+ writeHeavyRatio: 2,
+ });
+ expect(meter.write_read_ratio).toBe(1); // 2 writes / 2 reads
+ expect(meter.write_heavy).toBe(false); // 1 <= threshold 2
+ expect(meter.cost).toEqual({ write: 10, read: 1, total: 11 });
+ expect(meter.weights).toEqual({ write: 5, read: 0.5 });
+ });
+
+ test("no reads β†’ null ratio, write-heavy when any writes exist", () => {
+ writeEvent("feedback", "2026-07-01T10:00:00Z");
+ const meter = computeMemoryCostMeter(vault);
+ expect(meter.reads.total).toBe(0);
+ expect(meter.write_read_ratio).toBeNull();
+ expect(meter.write_heavy).toBe(true);
+ });
+
+ test("empty vault β†’ zeroed meter, not write-heavy", () => {
+ const meter = computeMemoryCostMeter(vault);
+ expect(meter.writes.total).toBe(0);
+ expect(meter.reads.total).toBe(0);
+ expect(meter.write_read_ratio).toBeNull();
+ expect(meter.write_heavy).toBe(false);
+ expect(meter.cost.total).toBe(0);
+ });
+
+ test("negative or non-finite weights fall back to unit defaults", () => {
+ writeEvent("feedback", "2026-07-01T10:00:00Z");
+ read("2026-07-01T11:00:00.000Z", "search");
+ const meter = computeMemoryCostMeter(vault, {
+ weights: { write: -3, read: Number.NaN },
+ });
+ expect(meter.weights).toEqual({ write: 1, read: 1 });
+ });
+});
diff --git a/tests/core/hygiene/hardcoded-paths.test.ts b/tests/core/hygiene/hardcoded-paths.test.ts
new file mode 100644
index 00000000..9f5a5147
--- /dev/null
+++ b/tests/core/hygiene/hardcoded-paths.test.ts
@@ -0,0 +1,133 @@
+/**
+ * Tests for the hardcoded home / absolute path hygiene scanner.
+ *
+ * Two layers:
+ * 1. Unit coverage of the pure {@link scanText} core β€” detectors,
+ * placeholder allowlist, the `hygiene:allow-path` escape hatch.
+ * 2. A repo gate: the shipped surfaces this check owns must be clean
+ * today, and stay clean. This is the enforcing counterpart to the
+ * report-only `scripts/check-hardcoded-paths.ts`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { formatFinding, scanText } from "../../../src/core/hygiene/hardcoded-paths.ts";
+import { listScanTargets, scanRepo } from "../../../src/core/hygiene/scan-repo.ts";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+// The scanner is oblivious to string literals β€” build path fragments by
+// concatenation so this very test file is not itself flagged when the
+// repo gate scans the tree (tests are excluded, but belt and braces).
+const HOME = "/home/";
+const USERS = "/Users/";
+
+describe("scanText β€” detectors", () => {
+ test("flags a concrete POSIX /home/<user> path", () => {
+ const found = scanText(`export const p = "${HOME}sergey/vault";`, "x.ts");
+ expect(found).toHaveLength(1);
+ expect(found[0]!.detector).toBe("unix-home");
+ expect(found[0]!.segment).toBe("sergey");
+ expect(found[0]!.match).toBe(`${HOME}sergey`);
+ expect(found[0]!.line).toBe(1);
+ });
+
+ test("flags a concrete /Users/<user> path", () => {
+ const found = scanText(`vault: ${USERS}alexander/notes`, "doc.md");
+ expect(found).toHaveLength(1);
+ expect(found[0]!.detector).toBe("unix-home");
+ expect(found[0]!.segment).toBe("alexander");
+ });
+
+ test("flags a Windows X:\\Users\\<user> path (raw and escaped backslash)", () => {
+ const raw = scanText("path = C:\\Users\\Vladimir\\vault", "doc.md");
+ expect(raw).toHaveLength(1);
+ expect(raw[0]!.detector).toBe("windows-home");
+ expect(raw[0]!.segment).toBe("Vladimir");
+
+ const escaped = scanText('const p = "D:\\\\Users\\\\Natalia\\\\v";', "x.ts");
+ expect(escaped).toHaveLength(1);
+ expect(escaped[0]!.segment).toBe("Natalia");
+ });
+
+ test("reports 1-based line and column", () => {
+ const found = scanText(`a\nb\n x = ${HOME}dmitry/v`, "x.ts");
+ expect(found).toHaveLength(1);
+ expect(found[0]!.line).toBe(3);
+ expect(found[0]!.column).toBe(` x = `.length + 1);
+ });
+
+ test("finds multiple hits on one line", () => {
+ const found = scanText(`${HOME}petr/a and ${HOME}igor/b`, "x.ts");
+ expect(found.map((f) => f.segment)).toEqual(["petr", "igor"]);
+ });
+});
+
+describe("scanText β€” placeholders and non-home paths pass", () => {
+ const cleanCases: ReadonlyArray<readonly [string, string]> = [
+ ["placeholder 'user'", `${HOME}user/vault`],
+ ["placeholder 'you'", `${HOME}you/vault`],
+ ["placeholder 'youruser'", `${HOME}youruser/vault`],
+ ["single-letter stand-in", `${USERS}x/vault`],
+ ["two-letter stand-in", `${HOME}me/vault`],
+ ["literal ellipsis segment", `${USERS}...`],
+ ["tilde home", "~/vaults/brain"],
+ ["$HOME env", "$HOME/vaults/brain"],
+ ["generic /path/to", "/path/to/vault"],
+ ["system path /usr/bin", "#!/usr/bin/env bun"],
+ ["system path /etc", "/etc/hosts"],
+ ["temp path /tmp", "/tmp/o2b-test"],
+ ["repo path /srv", "/srv/projects/open-second-brain"],
+ ];
+ for (const [label, line] of cleanCases) {
+ test(`no finding: ${label}`, () => {
+ expect(scanText(line, "x.ts")).toHaveLength(0);
+ });
+ }
+});
+
+describe("scanText β€” hygiene:allow-path escape hatch", () => {
+ test("suppresses findings on an annotated line", () => {
+ const line = `const p = "${HOME}sergey/vault"; // hygiene:allow-path intentional demo`;
+ expect(scanText(line, "x.ts")).toHaveLength(0);
+ });
+
+ test("only suppresses the annotated line, not its neighbours", () => {
+ const content = [`${HOME}sergey/a // hygiene:allow-path`, `${HOME}sergey/b`].join("\n");
+ const found = scanText(content, "x.ts");
+ expect(found).toHaveLength(1);
+ expect(found[0]!.line).toBe(2);
+ });
+});
+
+describe("formatFinding", () => {
+ test("renders file:line:column with segment and detector", () => {
+ const [f] = scanText(`${HOME}sergey/vault`, "src/x.ts");
+ expect(formatFinding(f!)).toBe(
+ `src/x.ts:1:1: hardcoded home path '${HOME}sergey' (segment 'sergey', unix-home)`,
+ );
+ });
+});
+
+describe("repo gate", () => {
+ test("shipped surfaces contain no hardcoded home paths", () => {
+ const findings = scanRepo(ROOT);
+ // Surface the offenders in the failure message so a regression is
+ // actionable without re-running the scanner by hand.
+ expect(findings.map(formatFinding)).toEqual([]);
+ });
+
+ test("scan reaches the surfaces the task names", () => {
+ const targets = listScanTargets(ROOT);
+ expect(targets).toContain("README.md");
+ expect(targets.some((t) => t.startsWith("src/"))).toBe(true);
+ expect(targets.some((t) => t.startsWith("docs/"))).toBe(true);
+ expect(targets.some((t) => t.startsWith("templates/"))).toBe(true);
+ expect(targets.some((t) => t.startsWith("plugins/"))).toBe(true);
+ // Fixtures and the test tree are intentionally out of scope.
+ expect(targets.some((t) => t.startsWith("tests/"))).toBe(false);
+ expect(targets.some((t) => t.includes("/fixtures/"))).toBe(false);
+ });
+});
diff --git a/tests/core/partner/codegraph-health.test.ts b/tests/core/partner/codegraph-health.test.ts
new file mode 100644
index 00000000..30f020b2
--- /dev/null
+++ b/tests/core/partner/codegraph-health.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+ assessGraphHealth,
+ summarizeGraphHealth,
+ type GraphHealthCode,
+} from "../../../src/core/partner/codegraph-health.ts";
+
+function codes(input: Parameters<typeof assessGraphHealth>[0]): GraphHealthCode[] {
+ return assessGraphHealth(input).warnings.map((w) => w.code);
+}
+
+describe("assessGraphHealth", () => {
+ test("healthy indexed graph -> ok, no warnings", () => {
+ const r = assessGraphHealth({ nodeCount: 12, edgeCount: 40 });
+ expect(r.ok).toBe(true);
+ expect(r.warnings).toEqual([]);
+ });
+
+ test("zero nodes -> empty-graph (and no collapsed-edges double-warn)", () => {
+ const c = codes({ nodeCount: 0, edgeCount: 0 });
+ expect(c).toContain("empty-graph");
+ expect(c).not.toContain("collapsed-edges");
+ });
+
+ test("nodes but zero edges -> collapsed-edges", () => {
+ const r = assessGraphHealth({ nodeCount: 100, edgeCount: 0 });
+ expect(r.ok).toBe(false);
+ expect(r.warnings.map((w) => w.code)).toEqual(["collapsed-edges"]);
+ expect(r.warnings[0]!.message).toContain("100");
+ });
+
+ test("dangling references surfaced only when the count is provided and > 0", () => {
+ expect(codes({ nodeCount: 5, edgeCount: 5 })).not.toContain("dangling-references");
+ expect(codes({ nodeCount: 5, edgeCount: 5, danglingRefs: 0 })).not.toContain(
+ "dangling-references",
+ );
+ expect(codes({ nodeCount: 5, edgeCount: 5, danglingRefs: 3 })).toContain("dangling-references");
+ });
+
+ test("self-loops surfaced only when the count is provided and > 0", () => {
+ expect(codes({ nodeCount: 5, edgeCount: 5 })).not.toContain("self-loops");
+ expect(codes({ nodeCount: 5, edgeCount: 5, selfLoops: 0 })).not.toContain("self-loops");
+ expect(codes({ nodeCount: 5, edgeCount: 5, selfLoops: 2 })).toContain("self-loops");
+ });
+
+ test("cache-root mismatch when index root differs from worktree root", () => {
+ const r = assessGraphHealth({
+ nodeCount: 5,
+ edgeCount: 5,
+ indexRoot: "/repo",
+ worktreeRoot: "/repo/.worktrees/x",
+ });
+ expect(r.warnings.map((w) => w.code)).toContain("cache-root-mismatch");
+ expect(r.warnings.find((w) => w.code === "cache-root-mismatch")!.message).toContain("/repo");
+ });
+
+ test("matching roots (trailing-slash insensitive) -> no mismatch", () => {
+ expect(
+ codes({ nodeCount: 5, edgeCount: 5, indexRoot: "/repo", worktreeRoot: "/repo/" }),
+ ).not.toContain("cache-root-mismatch");
+ });
+
+ test("missing roots never fabricate a mismatch", () => {
+ expect(
+ codes({ nodeCount: 5, edgeCount: 5, indexRoot: null, worktreeRoot: "/repo" }),
+ ).not.toContain("cache-root-mismatch");
+ expect(codes({ nodeCount: 5, edgeCount: 5 })).not.toContain("cache-root-mismatch");
+ });
+
+ test("multiple findings are ordered deterministically", () => {
+ const r = assessGraphHealth({
+ nodeCount: 0,
+ edgeCount: 0,
+ danglingRefs: 1,
+ selfLoops: 1,
+ indexRoot: "/a",
+ worktreeRoot: "/b",
+ });
+ expect(r.warnings.map((w) => w.code)).toEqual([
+ "empty-graph",
+ "dangling-references",
+ "self-loops",
+ "cache-root-mismatch",
+ ]);
+ });
+
+ test("non-finite counts are treated as zero, not NaN comparisons", () => {
+ const r = assessGraphHealth({ nodeCount: Number.NaN, edgeCount: Number.NaN });
+ expect(r.warnings.map((w) => w.code)).toEqual(["empty-graph"]);
+ });
+});
+
+describe("summarizeGraphHealth", () => {
+ test("clean report -> ok", () => {
+ expect(summarizeGraphHealth({ ok: true, warnings: [] })).toBe("ok");
+ });
+
+ test("warnings -> count and codes", () => {
+ const report = assessGraphHealth({ nodeCount: 10, edgeCount: 0, selfLoops: 1 });
+ expect(summarizeGraphHealth(report)).toBe("2 warning(s) [collapsed-edges, self-loops]");
+ });
+});
diff --git a/tests/core/partner/codegraph-report.test.ts b/tests/core/partner/codegraph-report.test.ts
index 20df46d9..5f5760e5 100644
--- a/tests/core/partner/codegraph-report.test.ts
+++ b/tests/core/partner/codegraph-report.test.ts
@@ -159,6 +159,50 @@ describe("buildCodegraphReport", () => {
expect(r.index.node_count).toBe(12);
expect(r.index.file_count).toBe(3);
expect(r.index.edge_count).toBe(40);
+ // Read-only graph-health gate attaches a clean report for a healthy graph.
+ expect(r.index.health).toBeDefined();
+ expect(r.index.health!.ok).toBe(true);
+ expect(r.index.health!.warnings).toEqual([]);
+ });
+
+ test("indexed but edge-collapsed graph -> non-blocking collapsed-edges warning", () => {
+ const repo = makeRepo(join(tmp, "repo"), "Cargo.toml", WORKSPACE_TOML);
+ makeIndexed(repo);
+ const r = buildCodegraphReport(
+ { cwd: repo, vault: join(tmp, "vault") },
+ {
+ whichCodegraph: () => "/usr/bin/codegraph",
+ runStatusJson: () => ({
+ ok: true,
+ data: { initialized: true, nodeCount: 500, fileCount: 30, edgeCount: 0 },
+ }),
+ },
+ );
+ expect(r.index.state).toBe("indexed");
+ expect(r.index.health!.ok).toBe(false);
+ expect(r.index.health!.warnings.map((w) => w.code)).toEqual(["collapsed-edges"]);
+ });
+
+ test("worktreeMismatch from status surfaces as cache-root-mismatch", () => {
+ const repo = makeRepo(join(tmp, "repo"), "Cargo.toml", WORKSPACE_TOML);
+ makeIndexed(repo);
+ const r = buildCodegraphReport(
+ { cwd: repo, vault: join(tmp, "vault") },
+ {
+ whichCodegraph: () => "/usr/bin/codegraph",
+ runStatusJson: () => ({
+ ok: true,
+ data: {
+ initialized: true,
+ nodeCount: 10,
+ fileCount: 3,
+ edgeCount: 20,
+ worktreeMismatch: { worktreeRoot: "/repo/.worktrees/x", indexRoot: "/repo" },
+ },
+ }),
+ },
+ );
+ expect(r.index.health!.warnings.map((w) => w.code)).toContain("cache-root-mismatch");
});
test("status error surfaces as error state with reason", () => {
diff --git a/tests/core/partner/codegraph.test.ts b/tests/core/partner/codegraph.test.ts
index 820b7a7d..d574f88b 100644
--- a/tests/core/partner/codegraph.test.ts
+++ b/tests/core/partner/codegraph.test.ts
@@ -198,6 +198,50 @@ describe("checkCodegraph", () => {
expect(r!.message).toContain("392");
});
+ test("indexed but unhealthy graph -> ok stays true, health summary in message", () => {
+ // A cache-root mismatch (common in worktree checkouts) and collapsed edges
+ // are non-blocking: doctor must not fail, but must surface the warning.
+ const repo = makeRepo(join(tmp, "repo"));
+ makeIndexed(repo);
+ const r = checkCodegraph(
+ { cwd: repo, vault: join(tmp, "vault") },
+ {
+ whichCodegraph: () => "/usr/bin/codegraph",
+ runStatusJson: () => ({
+ ok: true,
+ data: {
+ initialized: true,
+ nodeCount: 800,
+ fileCount: 50,
+ edgeCount: 0,
+ worktreeMismatch: { worktreeRoot: "/other/root", indexRoot: "/repo" },
+ },
+ }),
+ },
+ );
+ expect(r!.ok).toBe(true);
+ expect(r!.message).toContain("graph-health");
+ expect(r!.message).toContain("collapsed-edges");
+ expect(r!.message).toContain("cache-root-mismatch");
+ });
+
+ test("indexed healthy graph -> no graph-health suffix", () => {
+ const repo = makeRepo(join(tmp, "repo"));
+ makeIndexed(repo);
+ const r = checkCodegraph(
+ { cwd: repo, vault: join(tmp, "vault") },
+ {
+ whichCodegraph: () => "/usr/bin/codegraph",
+ runStatusJson: () => ({
+ ok: true,
+ data: { initialized: true, nodeCount: 100, fileCount: 10, edgeCount: 250 },
+ }),
+ },
+ );
+ expect(r!.ok).toBe(true);
+ expect(r!.message).not.toContain("graph-health");
+ });
+
test("status reports initialized:false -> not_indexed", () => {
const repo = makeRepo(join(tmp, "repo"));
makeIndexed(repo);
diff --git a/tests/core/redactor.test.ts b/tests/core/redactor.test.ts
index f6b4e2ed..85e6633d 100644
--- a/tests/core/redactor.test.ts
+++ b/tests/core/redactor.test.ts
@@ -2,10 +2,12 @@ import { describe, expect, test } from "bun:test";
import {
PRIVATE_REGION_PLACEHOLDER,
+ SCAN_TRUNCATED_MARKER,
normaliseTextField,
redactRawOutput,
sanitiseTextField,
stripPrivateRegions,
+ wasScanTruncated,
} from "../../src/core/redactor.ts";
describe("stripPrivateRegions", () => {
@@ -53,6 +55,124 @@ describe("redactRawOutput (cross-module backward compat)", () => {
});
});
+describe("redactRawOutput fail-closed truncation", () => {
+ test("appends the scan-truncated marker when input exceeds maxInput", () => {
+ const out = redactRawOutput("x".repeat(100), { maxInput: 10 });
+ expect(out).toContain(SCAN_TRUNCATED_MARKER.trim());
+ expect(wasScanTruncated(out)).toBe(true);
+ });
+
+ test("does not flag input that fits within the window", () => {
+ const out = redactRawOutput("small payload", { maxInput: 1024 });
+ expect(wasScanTruncated(out)).toBe(false);
+ expect(out).toBe("small payload");
+ });
+
+ test("still scrubs secrets within the kept prefix on truncated input", () => {
+ const head = "api_key=topsecret\n";
+ const out = redactRawOutput(head + "y".repeat(100), { maxInput: head.length + 5 });
+ expect(out).toContain("api_key=***REDACTED***");
+ expect(out).not.toContain("topsecret");
+ expect(wasScanTruncated(out)).toBe(true);
+ });
+
+ test("wasScanTruncated tolerates non-string input", () => {
+ expect(wasScanTruncated(undefined as unknown as string)).toBe(false);
+ });
+
+ test("Infinity maxInput never truncates (artifact-store contract)", () => {
+ const big = "z".repeat(2 * 1024 * 1024);
+ const out = redactRawOutput(big, { maxInput: Number.POSITIVE_INFINITY });
+ expect(wasScanTruncated(out)).toBe(false);
+ expect(out.length).toBe(big.length);
+ });
+});
+
+describe("redactRawOutput infra-topology pass (redactInfra)", () => {
+ test("is off by default β€” bare coordinates pass through", () => {
+ const input = "reach 8.8.8.8 and db.example.com:5432";
+ expect(redactRawOutput(input)).toBe(input);
+ });
+
+ test("redacts public IPv4 but leaves private/reserved ranges", () => {
+ const out = redactRawOutput("pub 8.8.8.8 priv 10.0.0.5 lo 127.0.0.1 lan 192.168.1.1", {
+ redactInfra: true,
+ });
+ expect(out).toContain("pub ***REDACTED***");
+ expect(out).toContain("priv 10.0.0.5");
+ expect(out).toContain("lo 127.0.0.1");
+ expect(out).toContain("lan 192.168.1.1");
+ });
+
+ test("does not mistake a version string for an IPv4", () => {
+ const out = redactRawOutput("v1.2.3.4 and 1.2.3.4.5", { redactInfra: true });
+ expect(out).toBe("v1.2.3.4 and 1.2.3.4.5");
+ });
+
+ test("redacts ipv4:port endpoints regardless of range", () => {
+ const out = redactRawOutput("db at 10.0.0.5:5432 cache 8.8.8.8:6379", { redactInfra: true });
+ expect(out).toContain("db at ***REDACTED***");
+ expect(out).toContain("cache ***REDACTED***");
+ expect(out).not.toContain("5432");
+ expect(out).not.toContain("6379");
+ });
+
+ test("redacts fqdn:port endpoints", () => {
+ const out = redactRawOutput("connect db.example.com:5432", { redactInfra: true });
+ expect(out).toContain("connect ***REDACTED***");
+ expect(out).not.toContain("db.example.com");
+ });
+
+ test("leaves file:line references untouched (no false-positive fqdn:port)", () => {
+ // Diagnostics and stack frames (`index.js:42`, `app.ts:128`) must not be
+ // mistaken for service endpoints when redactInfra runs over tool output.
+ const input = "error at src/app.ts:128 see lib/index.js:42 and tests/main.py:10";
+ const out = redactRawOutput(input, { redactInfra: true });
+ expect(out).toContain("src/app.ts:128");
+ expect(out).toContain("lib/index.js:42");
+ expect(out).toContain("tests/main.py:10");
+ expect(out).not.toContain("REDACTED");
+ });
+
+ test("strips basic-auth credentials from URLs but keeps scheme and host", () => {
+ const out = redactRawOutput("git clone https://alice:[email protected]/x.git", {
+ redactInfra: true,
+ });
+ expect(out).toContain("https://***REDACTED***@github.com/x.git");
+ expect(out).not.toContain("hunter2");
+ expect(out).not.toContain("alice");
+ });
+
+ test("redacts internal hostnames", () => {
+ const out = redactRawOutput("ping db.internal and app.svc.cluster.local", {
+ redactInfra: true,
+ });
+ expect(out).not.toContain("db.internal");
+ expect(out).not.toContain("svc.cluster.local");
+ });
+
+ test("redacts public IPv6 but leaves loopback and link-local", () => {
+ const out = redactRawOutput("pub 2001:db8:0:0:0:0:0:1 lo ::1 ll fe80::1", {
+ redactInfra: true,
+ });
+ expect(out).toContain("pub ***REDACTED***");
+ expect(out).toContain("lo ::1");
+ expect(out).toContain("ll fe80::1");
+ });
+
+ test("does not mistake HH:MM:SS timestamps for IPv6", () => {
+ const input = "event at 12:34:56 done";
+ expect(redactRawOutput(input, { redactInfra: true })).toBe(input);
+ });
+
+ test("stays linear on a large adversarial infra-shaped input (no ReDoS)", () => {
+ const evil = `${"1234:".repeat(5000)}z`;
+ // Should return promptly; a catastrophic-backtracking regex would hang.
+ const out = redactRawOutput(evil, { redactInfra: true });
+ expect(typeof out).toBe("string");
+ });
+});
+
describe("normaliseTextField", () => {
test("returns empty string for non-string input", () => {
expect(normaliseTextField(123 as unknown, { maxLen: 10 })).toBe("");
diff --git a/tests/core/vault.test.ts b/tests/core/vault.test.ts
index f80e048f..b9e1c6e9 100644
--- a/tests/core/vault.test.ts
+++ b/tests/core/vault.test.ts
@@ -136,12 +136,36 @@ describe("slugify", () => {
expect(slugify("Hello, World!")).toBe("hello-world");
});
- test("handles non-ASCII and empty inputs", () => {
- expect(slugify(" ")).toBe("note");
- expect(slugify("---")).toBe("note");
- // Geometric / dingbat symbols β€” purely non-ASCII, stripped down to nothing
- // by the alphanumeric regex. Falls back to the "note" sentinel.
- expect(slugify("β˜… β˜† β˜ƒ")).toBe("note");
+ test("empty / punctuation-only inputs fall back to a stable unnamed-<hash>", () => {
+ // Every input that slugifies to nothing must land on `unnamed-<hex>` β€”
+ // never a bare `-`, empty string, or traversal-capable name.
+ const fallback = /^unnamed-[0-9a-f]{8}$/;
+ for (const input of [
+ "", // empty
+ " ", // whitespace-only
+ "---", // punctuation-only
+ "@", // single symbol
+ "!!!", // repeated punctuation
+ "β˜… β˜† β˜ƒ", // dingbat / geometric symbols
+ "πŸ™‚πŸ™‚", // emoji-only
+ "́̈", // bare combining marks (acute + diaeresis)
+ ]) {
+ expect(slugify(input)).toMatch(fallback);
+ }
+ });
+
+ test("fallback is stable per-input and distinct across inputs", () => {
+ // Same title β†’ same basename (stable across devices / re-slug)...
+ expect(slugify("@")).toBe(slugify("@"));
+ // ...normalized: leading/trailing whitespace and case do not fork it.
+ expect(slugify(" @ ")).toBe(slugify("@"));
+ // ...but different punctuation-only titles must not collide on one name.
+ expect(slugify("@")).not.toBe(slugify("!!!"));
+ });
+
+ test("fallback is idempotent under a second slugify pass", () => {
+ const once = slugify("@");
+ expect(slugify(once)).toBe(once);
});
test("truncates long input to 64 chars", () => {
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index b429cda2..cf4c66fe 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -70,10 +70,11 @@ describe("slugify (re-exported via MCP barrel)", () => {
expect(slugify("Hello, World!")).toBe("hello-world");
});
- test("handles empty/non-ASCII inputs", () => {
- expect(slugify(" ")).toBe("note");
- expect(slugify("---")).toBe("note");
- expect(slugify("β˜… β˜† β˜ƒ")).toBe("note");
+ test("empty/non-ASCII inputs fall back to a stable unnamed-<hash>", () => {
+ const fallback = /^unnamed-[0-9a-f]{8}$/;
+ expect(slugify(" ")).toMatch(fallback);
+ expect(slugify("---")).toMatch(fallback);
+ expect(slugify("β˜… β˜† β˜ƒ")).toMatch(fallback);
});
test("truncates to 64 chars", () => {
diff --git a/tests/mcp/recall-telemetry-tool.test.ts b/tests/mcp/recall-telemetry-tool.test.ts
index d8e6e281..ee9cbcc2 100644
--- a/tests/mcp/recall-telemetry-tool.test.ts
+++ b/tests/mcp/recall-telemetry-tool.test.ts
@@ -4,10 +4,12 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { emitRecallTelemetry } from "../../src/core/brain/recall-telemetry.ts";
+import { recordHostMemoryWrite } from "../../src/core/brain/host-memory-write.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { BRAIN_CONFIDENCE, BRAIN_PREFERENCE_STATUS } from "../../src/core/brain/types.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+import { INVALID_PARAMS } from "../../src/mcp/protocol.ts";
import { buildToolTable } from "../../src/mcp/tools.ts";
let tmp: string;
@@ -200,4 +202,81 @@ describe("brain_recall_telemetry tool", () => {
by_status: { ok: 2 },
});
});
+
+ test("cost meter folds write volume against reads", async () => {
+ recordHostMemoryWrite(vault, {
+ action: "add",
+ target: "memory",
+ content: "one",
+ createdAt: "2026-05-20T09:00:00.000Z",
+ });
+ recordHostMemoryWrite(vault, {
+ action: "add",
+ target: "memory",
+ content: "two",
+ createdAt: "2026-05-20T09:01:00.000Z",
+ });
+ emitRecallTelemetry(vault, {
+ createdAt: "2026-05-20T09:02:00.000Z",
+ host: "mcp-test",
+ mode: "search",
+ status: "ok",
+ durationMs: 3,
+ resultCount: 1,
+ });
+
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ const meter = await callTelemetry(server, {
+ operation: "cost",
+ write_cost: 2,
+ read_cost: 1,
+ });
+ expect(meter).toMatchObject({
+ write_read_ratio: 2, // 2 host writes / 1 read
+ write_heavy: true,
+ cost: { write: 4, read: 1, total: 5 },
+ });
+ expect((meter["writes"] as Record<string, unknown>)["by_kind"]).toEqual({
+ host_memory_write: 2,
+ });
+ });
+
+ test("cost meter rejects a negative weight", async () => {
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: {
+ name: "brain_recall_telemetry",
+ arguments: { operation: "cost", write_cost: -1 },
+ },
+ })) as { result?: { isError?: boolean }; error?: unknown };
+ // Invalid params surface as a tool error rather than a valid meter.
+ expect(response.error ?? response.result?.isError).toBeTruthy();
+ });
+
+ test("cost meter rejects read-side-only filters (mode/status/host/limit)", async () => {
+ // Parity with the CLI: mode/status/host/limit filter recall records only
+ // and have no write-side analogue. They must be rejected for the cost
+ // meter, not silently ignored as a valid filtered result.
+ for (const field of ["mode", "status", "host", "limit"]) {
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: {
+ name: "brain_recall_telemetry",
+ arguments: { operation: "cost", [field]: "search" },
+ },
+ })) as { error?: { code: number; message: string } };
+ expect(response.error?.code).toBe(INVALID_PARAMS);
+ expect(response.error?.message).toContain(field);
+ }
+ });
});
diff --git a/tests/python/test_memory_provider.py b/tests/python/test_memory_provider.py
index 9bf171d1..33abc694 100644
--- a/tests/python/test_memory_provider.py
+++ b/tests/python/test_memory_provider.py
@@ -20,7 +20,11 @@ if str(ROOT) not in sys.path:
sys.path.insert(0, str(ROOT))
from plugins.hermes import config as cfg # noqa: E402
-from plugins.hermes._base import MemoryProvider # noqa: E402
+from plugins.hermes._base import ( # noqa: E402
+ HAS_HERMES_ABC,
+ MemoryProvider,
+ _FallbackMemoryProviderBase,
+)
from plugins.hermes.bridge import ( # noqa: E402
BridgeError,
BridgeTransportError,
@@ -104,8 +108,17 @@ class ConfigHelperTests(unittest.TestCase):
class FallbackBaseTests(unittest.TestCase):
- def test_memory_provider_is_subclassable(self):
- class Demo(MemoryProvider):
+ """Pin the no-op stand-in contract.
+
+ These tests target ``_FallbackMemoryProviderBase`` directly so they hold in
+ both environments: CI without the Hermes ABC, and a real install where
+ ``MemoryProvider`` aliases the Hermes ABC (which enforces its abstract
+ surface). The stand-in is the unit under test, not whichever base
+ ``MemoryProvider`` resolves to at import time.
+ """
+
+ def test_fallback_base_is_subclassable_without_abstract_methods(self):
+ class Demo(_FallbackMemoryProviderBase):
@property
def name(self):
return "demo"
@@ -113,8 +126,8 @@ class FallbackBaseTests(unittest.TestCase):
demo = Demo()
self.assertEqual(demo.name, "demo")
- def test_optional_hooks_are_noop_on_base(self):
- class Demo(MemoryProvider):
+ def test_optional_hooks_are_noop_on_fallback_base(self):
+ class Demo(_FallbackMemoryProviderBase):
@property
def name(self):
return "demo"
@@ -125,6 +138,16 @@ class FallbackBaseTests(unittest.TestCase):
self.assertIsNone(demo.on_session_end([]))
self.assertIsNone(demo.shutdown())
+ def test_memory_provider_aliases_fallback_base_without_hermes(self):
+ # When the Hermes ABC is unavailable, MemoryProvider must BE the
+ # fallback stand-in (not a separate class), so the provider subclass
+ # inherits the no-op hooks. With Hermes present, MemoryProvider is the
+ # real ABC and the stand-in stays independently testable above.
+ if not HAS_HERMES_ABC:
+ self.assertIs(MemoryProvider, _FallbackMemoryProviderBase)
+ else:
+ self.assertIsNot(MemoryProvider, _FallbackMemoryProviderBase)
+
class ProviderRequiredSurfaceTests(unittest.TestCase):
_ENV_KEYS = ("VAULT_AGENT_NAME", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG")