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.jsonindex 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.jsonindex 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.ymlindex 15dda1c5..d43adac7 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -43,6 +43,9 @@ jobs:- name: Verify manifest version syncrun: bun run sync-version:check+ - name: Hardcoded path hygiene (report-only)+ run: bun run check:paths+- name: Formatting checkrun: bun run fmt:checkdiff --git a/.gitignore b/.gitignoreindex 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.mdindex 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-28Two 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.1diff --git a/README.md b/README.mdindex 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.## Whydiff --git a/docs/brainstorm/brain-integrity-safety-hardening/cli-output/claude.md b/docs/brainstorm/brain-integrity-safety-hardening/cli-output/claude.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 deliveReports 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```## Searchdiff --git a/docs/mcp.md b/docs/mcp.mdindex 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 thediff --git a/docs/observability.md b/docs/observability.mdindex 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.jsonindex 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.jsonindex 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.jsonindex 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.yamlindex 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: truediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 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.pyindex 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 concreteprovider overrides every required method, and a faithful no-op base keeps theprovider 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 annotationsfrom 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.pyindex 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.yamlindex 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: truediff --git a/pyproject.toml b/pyproject.tomlindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.pyindex 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: E402BridgeError,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):@propertydef 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):@propertydef 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")