brainiac-cli 0.20.47__tar.gz → 0.20.49__tar.gz

{brainiac_cli-0.20.47/src/brainiac_cli.egg-info → brainiac_cli-0.20.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainiac-cli
-Version: 0.20.47
+Version: 0.20.49
 Summary: Brainiac — local any-LLM second-brain core engine + brain CLI (Markdown truth, derived SQLite index).
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/Autopsias/brainiac
@@ -19,7 +19,7 @@ Requires-Dist: cryptography>=49
 Requires-Dist: PyYAML>=6
 Requires-Dist: regex>=2023.0.0
 Requires-Dist: keyring>=24; sys_platform == "win32"
-Requires-Dist: pypdf>=6.21.2
+Requires-Dist: pypdf>=6.21.4
 Requires-Dist: python-docx>=1.1
 Requires-Dist: python-pptx>=0.6.23
 Requires-Dist: openpyxl>=3.1
@@ -44,7 +44,7 @@ Requires-Dist: PyYAML>=6; extra == "corporate"
 Provides-Extra: yaml
 Requires-Dist: PyYAML>=6; extra == "yaml"
 Provides-Extra: ingest
-Requires-Dist: pypdf>=6.21.2; extra == "ingest"
+Requires-Dist: pypdf>=6.21.4; extra == "ingest"
 Requires-Dist: python-docx>=1.1; extra == "ingest"
 Requires-Dist: python-pptx>=0.6.23; extra == "ingest"
 Requires-Dist: openpyxl>=3.1; extra == "ingest"
@@ -63,6 +63,7 @@ Provides-Extra: quant-tools
 Requires-Dist: onnx>=1.14; extra == "quant-tools"
 Provides-Extra: mcp
 Requires-Dist: mcp<2,>=1.30.0; extra == "mcp"
+Requires-Dist: PyJWT>=2.15.0; extra == "mcp"
 Provides-Extra: index
 Requires-Dist: regex>=2023.0.0; extra == "index"
 Dynamic: license-file

{brainiac_cli-0.20.47 → brainiac_cli-0.20.49}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 # check. The IMPORT package stays `brain` and the console script stays
 # `brain` — only the distribution/project name changes.
 name = "brainiac-cli"
-version = "0.20.47"
+version = "0.20.49"
 description = "Brainiac — local any-LLM second-brain core engine + brain CLI (Markdown truth, derived SQLite index)."
 readme = "README.md"
 license = "Apache-2.0"
@@ -42,7 +42,7 @@ dependencies = [
     # because requirements.lock is CI/audit-only -- a plain
     # `pip install brainiac-cli` reads THIS constraint, and >=4.0 let the
     # vulnerable 6.14.2 survive an upgrade to 0.20.5 on a real host.
-    "pypdf>=6.21.2",
+    "pypdf>=6.21.4",
     "python-docx>=1.1",
     "python-pptx>=0.6.23",
     "openpyxl>=3.1",
@@ -97,7 +97,7 @@ yaml = ["PyYAML>=6"]
 # message hints valid even though a default install already has these. Absent,
 # `brain ingest` degrades per-handler (reports which extensions are
 # unavailable) rather than crashing.
-ingest = ["pypdf>=6.21.2", "python-docx>=1.1", "python-pptx>=0.6.23", "openpyxl>=3.1", "Pillow>=13.0.0; python_version >= '3.11'", "Pillow>=12.3.0; python_version < '3.11'"]
+ingest = ["pypdf>=6.21.4", "python-docx>=1.1", "python-pptx>=0.6.23", "openpyxl>=3.1", "Pillow>=13.0.0; python_version >= '3.11'", "Pillow>=12.3.0; python_version < '3.11'"]
 # pytest-xdist/-timeout back the documented parallel suite run (AGENTS.md §8,
 # "Running the test suite"): ~15 min sequential -> ~6 min at `-n 8`. Both are
 # pytest-dev org, actively maintained. Declared here so a fresh checkout can
@@ -128,7 +128,9 @@ quant-tools = ["onnx>=1.14"]
 # >=1.30.0: CVE-2026-59951 (Streamable HTTP stateful sessions never reclaimed,
 # unbounded memory) is fixed there. The FLOOR, not just the lock, for the same
 # reason as pypdf above: a plain `pip install` reads this, not requirements.lock.
-mcp = ["mcp>=1.30.0,<2"]
+# PyJWT>=2.15.0: the floor mcp pulls in, stated here so a plain install
+# cannot resolve an older PyJWT (public PR #36).
+mcp = ["mcp>=1.30.0,<2", "PyJWT>=2.15.0"]
 # Timeout-bounded regex engine (mrab-regex) used by BrainIndex.grep's --regex
 # path (RET-04 hardening) as a ReDoS guard: regex.search(text, timeout=...)
 # genuinely bounds catastrophic backtracking, unlike stdlib `re`. Absent ->
@@ -183,7 +185,7 @@ known_first_party = ["brain", "workspace_registry", "framework_sync", "qwen3_emb
 # package_module_name_map: the 4 real import-name mismatches (distribution
 # name vs. the name actually imported).
 package_module_name_map = { PyYAML = "yaml", "python-docx" = "docx", "python-pptx" = "pptx", Pillow = "PIL" }
-per_rule_ignores = { DEP001 = ["llama_cpp", "lxml"], DEP002 = ["pytest", "pytest-xdist", "pytest-timeout", "ruff", "build", "onnx", "ranx"] }
+per_rule_ignores = { DEP001 = ["llama_cpp", "lxml"], DEP002 = ["pytest", "pytest-xdist", "pytest-timeout", "ruff", "build", "onnx", "ranx", "PyJWT"] }
 # DEP001 llama_cpp/lxml: both are optional accelerants guarded by
 # try/except ImportError (src/brain/context.py, src/brain/ingest/handlers/html.py)
 # — the code degrades gracefully absent either, same pattern as the existing
@@ -195,12 +197,15 @@ per_rule_ignores = { DEP001 = ["llama_cpp", "lxml"], DEP002 = ["pytest", "pytest
 # src/brain package. ranx is a real [eval] runtime import, but its only
 # import site is eval/, which extend_exclude drops above for the DEP001
 # noise reason — excluding it flips ranx to a false DEP002.
+# DEP002 PyJWT: a deliberate floor pin for mcp (see the mcp extra above,
+# public PR #36); never imported by our own code.
 
 [tool.claude-quality]
 # Trees the size gates skip: frozen plan/archive/evidence dirs and the
 # generated _assets mirror of tools/ + scripts/ (re-synced by
 # tools/package_clients.py). Not authored source.
-exclude = ["_plans", "_archive", "_evidence", "_assets"]
+# eval/ holds frozen, one-off experiment scripts, not shipped source (owner choice 2026-11-03).
+exclude = ["_plans", "_archive", "_evidence", "_assets", "eval"]
 
 [tool.ruff]
 # CORRECTNESS ONLY — this is not a style gate. The repo already has three
@@ -257,6 +262,9 @@ select = ["F", "E9", "E722"]
 # exists to express that.
 ignore = ["F403", "F405"]
 
+[tool.ruff.lint.mccabe]
+max-complexity = 12  # matches the complexity ratchet limit (tools/check_complexity.py, limit=12)
+
 [tool.ruff.lint.per-file-ignores]
 # F811 cannot see pytest. A module-level `@pytest.fixture def text()` and a test
 # that takes `text` as a parameter is the framework's core idiom, and this rule
@@ -264,6 +272,10 @@ ignore = ["F403", "F405"]
 # real F811s all live outside tests/.
 "tests/**" = ["F811"]
 
+# eval/ is out of the size and complexity gates (see [tool.claude-quality]); the
+# correctness lint still runs on it.
+"eval/**" = ["C901"]
+
 
 [tool.pytest.ini_options]
 # Scope collection to tests/ so pytest never descends into a local model venv
@@ -302,9 +314,9 @@ exclude = ["**/_plans", "**/_archive", "**/_evidence", "**/_assets"]
 
 [tool.uv]
 # Wait 7 days before resolving a newly published version (a new release can be
-# malicious or broken). shortcut: pypdf 6.21.2, filelock 4.2.4 and certifi
+# malicious or broken). shortcut: pypdf 6.21.4 (fixes 7 DoS advisories, 2026-10-31), filelock 4.2.4 and certifi
 # 2026.10.23 are security fixes under 7 days old on 2026-10-24, so they are
-# exempt; remove the exemptions after 2026-10-31.
+# exempt; re-check the exemptions after 2026-11-08.
 exclude-newer = "7 days"
 exclude-newer-package = { pypdf = false, filelock = false, certifi = false }
 # fastembed (the optional `embed` extra, not installed by default) caps

{brainiac_cli-0.20.47 → brainiac_cli-0.20.49}/src/brain/_assets/AGENTS.md

@@ -449,7 +449,7 @@ gates.
    signal (`emitter_output`, 2026-08-20).** The paragraph above is right and
    is not weakened: `proposal`, `report`, `analysis` and `review` stay OUT of
    `OPERATIONAL_SOURCE_TYPES` because a human writes those about the
-   business. The gap it leaves is narrower — when `_log_rotation.py` emits
+   business. The gap it leaves is narrower — when a log-rotation script (not tracked here) emits
    `type: proposal` once a day, type says "keep" and nothing else disagrees.
    The reference vault carried **22** daily `Log rotation proposal` files
    from one script, each counted as a source awaiting a note. So the second
@@ -1028,6 +1028,12 @@ rules, in order:
    env-exported `$BRAIN_VM_MAX_EGRESS_TIER` is IGNORED (the session's own
    shell can set it; VULN-3386). Raising a VM's ceiling is a host-operator
    action (`brain vm-egress-tier <TIER>`, signed), never the model's own.
+   That clamp binds the VM's own `brain --role vm` CLI only. A Cowork session
+   that reads through the host broker (`brain-mcp`, the Desktop MCP entry)
+   gets the BROKER's ceiling — the full vault unless `$BRAIN_MAX_EGRESS_TIER`
+   narrows that entry — because the broker receives no caller role (owner
+   ruling, `docs/security-acceptances.md` A-01; pentest VULN-3419). When
+   asked for your cap, report the broker's, never the VM file's.
 
 3. **Ask it in every language the vault holds — the VARIANT CONTRACT
    (CON-01) — and paraphrase within your own.** The cross-language half is a
@@ -1850,8 +1856,9 @@ entry formats in `docs/session-memory.md`. Rules an agent needs at a glance:
   count match the host's; there is nothing enforcing that a session actually
   does it. When `N > 0`, do not tell the owner to go run `/brain-inbox` —
   open the exceptions page yourself and walk them through what is open using
-  `AskUserQuestion`, one at a time. The two host-home sources
-  (`~/.brainiac/update-state.json`, `~/.brain/synthesis-state.json`) stay out
+  `AskUserQuestion`, one at a time. The three host-home sources
+  (`~/.brainiac/update-state.json`, `~/.brain/synthesis-state.json`,
+  `~/.brain/retrieval-watch-state.json`) stay out
   of the VM's reach and are listed under `unreachable` rather than skipped.
   Claude Code and Codex both fire this from a SessionStart hook; run it first
   regardless of harness.
@@ -1928,8 +1935,8 @@ summary is the one authority for open owner questions on the VM leg now.
 That is the whole point of the first bullet above — until 2026-08-14 this
 logic lived only in a Claude Code hook, so a Cowork session worked for days
 against a vault whose invariants had regressed with no surface that could
-tell it. Only the two HOST-HOME sources (`~/.brainiac/update-state.json`,
-`~/.brain/synthesis-state.json`) are out of the VM's reach, and `alerts`
+tell it. Only the three HOST-HOME sources (`~/.brainiac/update-state.json`,
+`~/.brain/synthesis-state.json`, `~/.brain/retrieval-watch-state.json`) are out of the VM's reach, and `alerts`
 reports those under `unreachable` rather than skipping them. The reads are
 file-reads of counts and two findings files; the VM still never WRITES
 anything here,

{brainiac_cli-0.20.47 → brainiac_cli-0.20.49}/src/brain/_assets/scripts/brain-synthesis.sh

@@ -82,7 +82,9 @@ note and will be rejected; cite the source in the BODY as [[<bare-id>]], never
 edge, so it inflates the metric while linking nothing); put the [[raw/<id>]]
 form in the note's `source:` frontmatter as usual; set the note's
 classification to at least the HIGHEST classification among the sources it
-cites, read live off each source; and NEVER append these links into an
+cites, read live off each source; give each new note a SHORT kebab-case
+id of at most 80 characters, the same as its file name (a sentence-long id
+is refused at signing and the note stays unsigned); and NEVER append these links into an
 existing hand-curated note — always a new note. Work the list in order; in
 your final summary state HOW MANY of the file's candidates you covered (the
 file's own "consumed_today" field is the fold's count — quote yours beside
@@ -335,6 +337,16 @@ doctor: $DOCTOR_DIAG"
     find "$VAULT/brain" -type f -name '*.md' \
          ! -name 'backlinks.md' ! -name 'catalog.md' \
          -newer "$SIGN_MARKER" > "$SIGN_LIST" 2>/dev/null || true
+    # A sentence-long note name is refused by the drain's safe-id check
+    # (2026-10-25: 20 of 45 notes unsigned, rc=75). Give those a short id
+    # first; anything it cannot shorten safely is left for the drain to refuse.
+    SHORT_LIST="$(mktemp -t brain-synthesis-shortlist)"
+    if python3 "$(dirname "$0")/shorten_long_note_ids.py" "$SIGN_LIST" \
+         > "$SHORT_LIST" 2>>"$LOG"; then
+      mv -f -- "$SHORT_LIST" "$SIGN_LIST"
+    else
+      rm -f -- "$SHORT_LIST"
+    fi
     SIGNED=0; SIGN_FAIL=0
     # fd 3, not stdin: `brain write` reads the note body FROM STDIN, so a
     # plain `while read` loop would feed it the file list instead.

{brainiac_cli-0.20.47 → brainiac_cli-0.20.49}/src/brain/_assets/scripts/brain_synthesis_codex.py

@@ -58,7 +58,11 @@ existing-note link suggestions, or missing watchdogs in action_required rather
 than changing existing notes. This runner never edits or retires existing notes.
 Do not create a duplicate of a supplied existing note. If there is no honest
 new synthesis, return notes=[] and explain why in summary/action_required.
+Maintenance status="ok" with a recent last_run is success; last_success and rc
+are optional fields on many folds. Missing optional fields are not failures.
 Note bodies must be 120–8000 characters; titles 1–200 characters.
+Use each distinct set of source_ids for at most one note. Combine related
+claims from the same source set rather than repeating that set in several notes.
 
 UNTRUSTED DATA PACKET:
 {packet}
@@ -113,8 +117,10 @@ def make_packet(args, core):
     lane = link_lane_candidates(core.index.conn, args.vault, limit=100000)
     gate = classification.ClassificationFilter(args.max_tier)
     eligible = [x for x in lane["candidates"] if gate.allows(x.get("classification"))]
+    offset = getattr(args, "source_offset", 0) % max(len(eligible), 1)
+    ordered = eligible[offset:] + eligible[:offset]
     sources, remaining = [], args.packet_chars
-    for row in eligible:
+    for row in ordered:
         if len(sources) >= args.source_budget or remaining < 120:
             break
         note = get_gated(args, row["id"])
@@ -145,7 +151,7 @@ def make_packet(args, core):
     except (OSError, ValueError):
         state = {}
     # Diagnostics expose cadence/status, not arbitrary strings from host stores.
-    diagnostics = {key: {k: value.get(k) for k in ("last_run", "last_success", "date", "rc")}
+    diagnostics = {key: {k: value.get(k) for k in ("last_run", "last_success", "date", "rc", "status", "failed", "consecutive_failures")}
                    for key, value in state.items() if isinstance(value, dict)}
     return {"sources": sources, "knowledge_context": knowledge,
             "diagnostics": diagnostics,
@@ -322,6 +328,8 @@ def parser():
     p.add_argument("--model", default=None)
     p.add_argument("--max-tier", choices=classification.TIERS, default="Internal")
     p.add_argument("--source-budget", type=int, default=40)
+    p.add_argument("--source-offset", type=int, default=0,
+                   help="Rotate the canonical eligible lane for an operator-run backfill; no exclusions")
     p.add_argument("--note-budget", type=int, default=8)
     p.add_argument("--packet-chars", type=int, default=120000)
     p.add_argument("--timeout", type=int, default=1200)
@@ -337,7 +345,7 @@ def parser():
 
 
 def validate_args(args):
-    if not (1 <= args.source_budget <= 40 and 1 <= args.note_budget <= 8
+    if not (0 <= args.source_offset <= 100000 and 1 <= args.source_budget <= 40 and 1 <= args.note_budget <= 8
             and 1000 <= args.packet_chars <= 120000 and 30 <= args.timeout <= 1800):
         raise SystemExit("Bounds refused")
     for binary in (args.brain_bin, args.codex_bin):
@@ -441,6 +449,11 @@ def main():
     # A dry-run/smoke test must never earn the production watchdog heartbeat.
     if not args.smoke_test and not args.dry_run:
         update_state(args, outcome)
+    # Numbers only: summary/action_required/error carry vault-derived text and
+    # stay in the owner-only run_dir, never in the launchd log this lands in.
+    print(json.dumps({"rc": outcome["rc"], "run_dir": outcome["run_dir"],
+                      "created": len(outcome.get("created") or []),
+                      **{k: outcome.get(k) for k in ("tokens", "duration_s", "est_cost_usd")}}))
     return outcome["rc"]
 
 

brainiac_cli-0.20.49/src/brain/_assets/scripts/shorten_long_note_ids.py

@@ -0,0 +1,100 @@
+"""Give a too-long note a short id before the synthesis sign-drain signs it.
+
+2026-10-25: the confined session named 20 of its 45 notes after a whole
+sentence (up to 208 characters). `notes.safe_slug` refuses an id over
+MAX_SLUG_BYTES, so all 20 stayed unsigned and the run failed rc=75.
+
+Reads the drain's file list (one path per line), and for each note whose
+file stem is over the limit AND equals its frontmatter `id:`, moves it to
+`<first words>-<8 hex of the old id>.md` and rewrites that one `id:` line.
+Anything else is left exactly as it was, so the drain still refuses it.
+Then rewrites `[[old-id]]` links to `[[new-id]]` in every listed note: the
+same session wrote the notes that link to these, and on 2026-10-26 a rename
+without this left 18 links pointing at files that no longer existed.
+Prints the list back with the new paths. Stdlib only: the script runs it
+with the host's `python3`, outside the engine's venv.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+#: Same number as `brain.notes.MAX_SLUG_BYTES` (a test holds them equal).
+MAX_SLUG_BYTES = 180
+#: Short enough to read, long enough to keep the subject.
+KEEP_BYTES = 80
+
+
+def short_id(old: str) -> str:
+    head = old.encode("utf-8")[:KEEP_BYTES].decode("utf-8", "ignore")
+    if "-" in head:
+        head = head.rsplit("-", 1)[0]
+    return f"{head.rstrip('-.')}-{hashlib.sha256(old.encode('utf-8')).hexdigest()[:8]}"
+
+
+def shorten(path: Path) -> Path:
+    old = path.stem
+    if len(old.encode("utf-8")) <= MAX_SLUG_BYTES:
+        return path
+    lines = path.read_text(encoding="utf-8").split("\n")
+    if not lines or lines[0].strip() != "---":
+        return path
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            return path                      # no `id:` line: leave it to the drain
+        if line.startswith("id:"):
+            if line[3:].strip().strip("\"'") != old:
+                return path                  # the id is not the file name: leave it
+            new = short_id(old)
+            target = path.with_name(f"{new}.md")
+            if target.exists():
+                return path
+            lines[i] = f"id: {new}"
+            target.write_text("\n".join(lines), encoding="utf-8")
+            path.unlink()
+            return target
+    return path
+
+
+def relink(paths: list[str], renames: dict[str, str]) -> None:
+    """Point `[[old]]`, `[[old|..]]` and `[[old#..]]` at the new id."""
+    if not renames:
+        return
+    pattern = re.compile(r"\[\[(" + "|".join(map(re.escape, renames)) + r")(?=[\]|#])")
+    for raw in paths:
+        path = Path(raw)
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        new = pattern.sub(lambda m: "[[" + renames[m.group(1)], text)
+        if new != text:
+            path.write_text(new, encoding="utf-8")
+
+
+def main(argv: list[str]) -> int:
+    # "\n" only, as the shell's `read` splits: splitlines() also breaks on
+    # \r, \x1c, \u2028 ..., so a crafted file name could add a list entry.
+    with open(argv[1], encoding="utf-8", newline="") as fh:  # no \r translation
+        entries = fh.read().split("\n")
+    out: list[str] = []
+    renames: dict[str, str] = {}
+    for raw in entries:
+        if raw:
+            try:
+                new = shorten(Path(raw))
+            except (OSError, UnicodeDecodeError):
+                new = Path(raw)
+            if str(new) != raw:
+                renames[Path(raw).stem] = new.stem
+            out.append(str(new))
+    relink(out, renames)
+    for line in out:
+        print(line)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

{brainiac_cli-0.20.47 → brainiac_cli-0.20.49}/src/brain/_version.py

@@ -9,4 +9,4 @@ pip-installed host, importlib.metadata stays primary; brain/__init__.py reads
 this file only as the fallback before 0.0.0+unknown.
 """
 
-__version__ = "0.20.47"
+__version__ = "0.20.49"

{brainiac_cli-0.20.47 → brainiac_cli-0.20.49}/src/brain/alerts.py

@@ -12,7 +12,7 @@ identical list.
 
 Two design rules, both learned from earlier failures in this repo:
 
-* **Silence must never be able to mean "could not look."** Two of the five
+* **Silence must never be able to mean "could not look."** Some of the
   inputs live in the HOST home (``~/.brainiac``, ``~/.brain``) and the Cowork
   VM cannot reach them. On ``role=vm`` they are reported in ``unreachable``
   rather than quietly contributing nothing — the same posture ``doctor`` takes
@@ -42,7 +42,7 @@ from .alerts_staging import (  # noqa: F401 — re-exported for callers/tests
     _untriaged,
     _untriaged_key,
     _unwrap_untriaged,
-    host_vaults,
+    host_vaults, retrieval_watch_alerts, RETRIEVAL_WATCH_UNREACHABLE,
     staging_alerts,
 )
 
@@ -79,7 +79,7 @@ SYNTHESIS_STALE_DAYS = 8
 STUCK_DRAFT_HOURS = 48
 
 # The feed's `findings[].key` vocabulary is closed (see maintenance_notify.py:
-# "blocked", "synthesis-watchdog", "trend:<metric>", "invariant:<metric>",
+# "blocked", "synthesis-watchdog", "trend:<metric>", "invariant:<metric>",  # noqa: ERA001
 # "branch-escalate:<branch>", "ingest_quarantine*", ...). The dir is on the
 # VirtioFS mount the Cowork VM can write, so a key failing this shape must
 # never reach the rendered alert text — it is the one thing standing between
@@ -91,7 +91,7 @@ def _read_json(path: Path) -> Any:
     try:
         with open(path, encoding="utf-8") as fh:
             return json.load(fh)
-    except Exception:
+    except Exception:  # fail-open: missing or corrupt feed file reads as no data
         return None
 
 
@@ -443,7 +443,7 @@ def collect(
     """Every alert this role can see, plus what it could not look at.
 
     ``host`` sweeps the workspace registry; ``vm`` reads only its own vault and
-    reports the two host-home sources as unreachable."""
+    reports the host-home sources as unreachable."""
     home = home or Path.home()
     today = today or datetime.date.today()
     alerts: list[dict[str, str]] = []
@@ -454,7 +454,7 @@ def collect(
             "auto-update state (~/.brainiac/update-state.json) — host-only, "
             "run `brain alerts` on the host Mac",
             "weekly synthesis task health (~/.brain/synthesis-state.json) — "
-            "host-only, run `brain alerts` on the host Mac",
+            "host-only, run `brain alerts` on the host Mac", RETRIEVAL_WATCH_UNREACHABLE,
         ]
         vaults = [Path(vault)] if vault else []
         if not vaults:
@@ -467,7 +467,7 @@ def collect(
     else:
         alerts += update_alerts(home, today)
         alerts += staging_alerts(home)
-        alerts += synthesis_alerts(home, today)
+        alerts += synthesis_alerts(home, today) + retrieval_watch_alerts(home, today)
         alerts += wiring_alerts()
         vaults = host_vaults(home)
         if not vaults and vault:

{brainiac_cli-0.20.47 → brainiac_cli-0.20.49}/src/brain/alerts_staging.py

@@ -186,3 +186,39 @@ def host_vaults(home: Path) -> list[Path]:
         if path not in seen:
             seen.append(path)
     return seen
+
+
+#: The monthly retrieval watch fires on day 1; past this its silence is the news.
+RETRIEVAL_WATCH_STALE_DAYS = 35
+
+
+def retrieval_watch_alerts(home: Path, today: Any) -> list[dict[str, str]]:
+    """The monthly retrieval-quality watch (``~/.brain/retrieval-watch-state.json``,
+    written by ``scripts/brain-retrieval-watch.sh``). Until 2026-10-27 a FAIL
+    went only to ``hot.md``, a log nobody has to read, and it failed unread on
+    three months running against a baseline from a retired embedder."""
+    from .alerts import _alert, _date, _read_json
+
+    state = _read_json(home / ".brain" / "retrieval-watch-state.json")
+    if not isinstance(state, dict):
+        return []  # never installed on this host — nothing to watch
+    day = _date(state.get("at"))
+    if state.get("verdict") == "FAIL":
+        return [_alert(
+            "retrieval-watch:fail",
+            f"monthly retrieval check FAILED on {state.get('at')} — run /autoresearch, "
+            "or re-baseline if the engine or embedder changed")]
+    if state.get("verdict") == "ERROR":
+        return [_alert(
+            "retrieval-watch:error",
+            f"monthly retrieval check could not run on {state.get('at')} — "
+            "read ~/.brain/logs/launchd-retrievalwatch-stderr.log")]
+    if day is None or (today - day).days > RETRIEVAL_WATCH_STALE_DAYS:
+        return [_alert(
+            "retrieval-watch:stale",
+            f"monthly retrieval check has not run since {state.get('at') or 'never'}")]
+    return []
+
+RETRIEVAL_WATCH_UNREACHABLE = (
+    "monthly retrieval check (~/.brain/retrieval-watch-state.json) — host-only, "
+    "run `brain alerts` on the host Mac")

brainiac_cli-0.20.49/src/brain/atomic_temp.py

@@ -0,0 +1,49 @@
+"""Durable-write temp-name helper and the one write-then-replace helper."""
+from __future__ import annotations
+
+import errno
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from .lock import _atomic_temp_path
+
+atomic_temp_path = _atomic_temp_path
+
+
+def _fsync_dir(d: Path) -> None:
+    """fsync a directory so a rename in it survives a crash; unsupported is fine."""
+    if os.name == "nt":
+        return  # no directory descriptors on Windows
+    fd = os.open(d, os.O_RDONLY)
+    try:
+        os.fsync(fd)
+    except OSError as exc:
+        if exc.errno not in (errno.EINVAL, errno.ENOTSUP, errno.EBADF):
+            raise
+    finally:
+        os.close(fd)
+
+
+def write_text_atomic(path: Path, text: str) -> None:
+    """Write ``text`` to a sibling temp file, fsync, then ``os.replace`` it in.
+
+    The temp file is removed on any error, so the target keeps its old content.
+    """
+    tmp = atomic_temp_path(path)
+    try:
+        with open(tmp, "w", encoding="utf-8") as fh:
+            fh.write(text)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+    _fsync_dir(path.parent)  # after the replace: the target must not be unlinked on failure
+
+
+def write_json_atomic(path: Path, obj: Any) -> None:
+    """``write_text_atomic`` of ``json.dumps(obj, indent=2)`` plus a newline."""
+    write_text_atomic(path, json.dumps(obj, indent=2) + "\n")

{brainiac_cli-0.20.47 → brainiac_cli-0.20.49}/src/brain/audit.py

@@ -18,6 +18,7 @@ Resolution precedence (first hit wins, all yield identical PEM bytes):
 """
 from __future__ import annotations
 
+import logging
 import base64 as base64
 import contextlib
 import hashlib
@@ -31,6 +32,8 @@ from datetime import datetime as datetime, timezone as timezone
 from pathlib import Path
 from typing import Iterator, Optional
 
+logger = logging.getLogger(__name__)
+
 JSONL_FORMAT = "brain-audit-chain-jsonl-v1"
 NULL_PREV_HASH = "0" * 64
 _REQUIRED_KEYS = frozenset({"format", "ts", "verb", "path", "reason", "prev_hash", "sig"})
@@ -137,7 +140,7 @@ def _pem_from_credential_manager(service: str, account: str) -> Optional[bytes]:
 
         secret = keyring.get_password(service, account)
         return secret.encode("utf-8") if secret else None
-    except Exception:
+    except Exception:  # fail-open: keyring is optional; None means no key from this source
         return None
 
 
@@ -334,7 +337,8 @@ def _exclusive_lock(log_path: Path) -> Iterator[None]:
 
                 msvcrt.locking(fd, msvcrt.LK_LOCK, 1)
                 locked_with = "msvcrt"
-            except Exception:
+            except Exception:  # fail-open: best-effort lock; locked_with=None records that none was taken
+                logger.warning("audit lock not taken (msvcrt locking failed); writing unlocked", exc_info=True)
                 locked_with = None  # best-effort fallback
         yield
     finally:
@@ -348,7 +352,7 @@ def _exclusive_lock(log_path: Path) -> Iterator[None]:
 
                 os.lseek(fd, 0, os.SEEK_SET)
                 msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
-            except Exception:
+            except Exception:  # fail-open: unlock failure is harmless, the fd is closed next
                 pass
         os.close(fd)
 

{brainiac_cli-0.20.47 → brainiac_cli-0.20.49}/src/brain/audit_drift.py

@@ -1,12 +1,11 @@
 """Host-private audit drift-disposition triage (INT-02)."""
 from __future__ import annotations
+from .atomic_temp import write_text_atomic
 
 import json
-import os
 from datetime import date
 from pathlib import Path
 from typing import TYPE_CHECKING
-from .atomic_temp import atomic_temp_path
 
 if TYPE_CHECKING:  # annotation-only; a runtime import here would be a cycle
     from .audit_chain import AuditChain
@@ -33,9 +32,7 @@ def _write_dispositions(path: Path, payload: dict) -> None:
     turn every explained finding back into an unexplained one. `os.replace` is
     atomic within a filesystem, so a reader sees the old file or the new one.
     """
-    tmp = atomic_temp_path(path)
-    tmp.write_text(json.dumps(payload, indent=2), encoding="utf-8")
-    os.replace(tmp, path)
+    write_text_atomic(path, json.dumps(payload, indent=2))
 
 
 def drift_dispositions_path(vault: Path) -> Path:

{brainiac_cli-0.20.47 → brainiac_cli-0.20.49}/src/brain/autolink.py

@@ -45,16 +45,18 @@ def _fold(text: str) -> str:
     return re.sub(r"[^a-z0-9]+", "-", folded).strip("-")
 
 
-def _typed_notes(vault: Path, types: tuple[str, ...]) -> list[tuple[str, str]]:
-    """[(note_id, folded-title-slug)] for every brain/ note of one of ``types``."""
+def _typed_notes(vault: Path, types: tuple[str, ...], notes=None) -> list[tuple[str, str]]:
+    """[(note_id, folded-title-slug)] for every brain/ note of one of ``types``.
+
+    ``notes`` is an already-scanned vault (one scan shared by both finders)."""
     out: list[tuple[str, str]] = []
-    for note in scan_vault(vault):
+    for note in (scan_vault(vault) if notes is None else notes):
         if note.zone == "brain" and note.type in types:
             out.append((note.id, _fold(note.title)))
     return out
 
 
-def find_person_links(text: str, vault: Path) -> list[str]:
+def find_person_links(text: str, vault: Path, notes=None) -> list[str]:
     """Full-name matches of existing ``type: person`` notes in ``text``.
 
     A person note's title must fold to at least two hyphen-separated parts
@@ -63,7 +65,7 @@ def find_person_links(text: str, vault: Path) -> list[str]:
     ``text`` never links on its own."""
     folded_text = _fold(text)
     hits: list[str] = []
-    for note_id, name_slug in _typed_notes(vault, ("person",)):
+    for note_id, name_slug in _typed_notes(vault, ("person",), notes):
         parts = [p for p in name_slug.split("-") if p]
         if len(parts) < 2:
             continue
@@ -72,7 +74,7 @@ def find_person_links(text: str, vault: Path) -> list[str]:
     return hits
 
 
-def find_project_link(text: str, vault: Path) -> list[str]:
+def find_project_link(text: str, vault: Path, notes=None) -> list[str]:
     """Origin-context match against ``type: project``/``type: moc`` notes.
 
     Returns a match only when exactly one candidate's folded title is a
@@ -80,7 +82,7 @@ def find_project_link(text: str, vault: Path) -> list[str]:
     nothing."""
     folded_text = _fold(text)
     candidates = [
-        note_id for note_id, title_slug in _typed_notes(vault, ("project", "moc"))
+        note_id for note_id, title_slug in _typed_notes(vault, ("project", "moc"), notes)
         if title_slug and title_slug in folded_text
     ]
     return candidates if len(candidates) == 1 else []
@@ -109,8 +111,9 @@ def apply_autolinks(
         return body, []
     try:
         search_text = "\n".join(t for t in (title, body) if t)
-        candidates = list(find_person_links(search_text, vault))
-        candidates.extend(find_project_link("\n".join(t for t in (title, origin) if t), vault))
+        notes = list(scan_vault(vault))  # one scan per record; no cross-record cache
+        candidates = list(find_person_links(search_text, vault, notes))
+        candidates.extend(find_project_link("\n".join(t for t in (title, origin) if t), vault, notes))
         existing = set(parse_wikilinks(body))
         new_ids = [nid for nid in dict.fromkeys(candidates) if nid not in existing]
         if not new_ids: