brainiac-cli 0.20.2__tar.gz → 0.20.4__tar.gz

{brainiac_cli-0.20.2/src/brainiac_cli.egg-info → brainiac_cli-0.20.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainiac-cli
-Version: 0.20.2
+Version: 0.20.4
 Summary: Brainiac — local any-LLM second-brain core engine + brain CLI (Markdown truth, derived SQLite index).
 License-Expression: Apache-2.0
 Requires-Python: >=3.9

{brainiac_cli-0.20.2 → brainiac_cli-0.20.4}/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.2"
+version = "0.20.4"
 description = "Brainiac — local any-LLM second-brain core engine + brain CLI (Markdown truth, derived SQLite index)."
 readme = "README.md"
 license = "Apache-2.0"

{brainiac_cli-0.20.2 → brainiac_cli-0.20.4}/src/brain/_assets/AGENTS.md

@@ -547,6 +547,33 @@ round-trip). Both temporal flags stay **VM_ALLOWED** — they are read-only
 filters over already-gated rows, no different in trust from any other
 `bases-query`.
 
+**Breadth-intent routing (RTE-01).** A heuristic adapted from NapMem's
+observed navigator behavior (arXiv 2607.05794) — the paper never classifies
+query breadth itself, but its top-down-vs-bottom-up entry choice transfers as
+a rule of thumb for frontier-model navigators over this vault. This governs
+*entry point* only, never a mandated step sequence: probing lexically first
+and escalating only when needed (§5's agentic tool surface) still applies
+once you're in. When a question is BROAD — "state of play", "overview", "how
+do we usually…" asked about VAULT knowledge — enter TOP-DOWN instead of
+grepping cold:
+
+```
+brain get index --json          # the map note (id: index) — start here
+```
+
+then drill down via wikilinks with `get`/`graph-expand`, confirming each
+candidate on its cited note (`graph-expand` stays DISCOVERY-ONLY — never
+treat its derived graph as authoritative). If no state-MOC or `index.md`
+entry fits, fall back to `search`. **Owner persona/voice/preference
+questions are NOT this route:** voice/brand/keywords/people live in
+`vault/overlay/`, which is excluded from retrieval indexing entirely, so the
+vault map can never contain those answers — keep the existing overlay-loading
+path for those. When a question is NARROW factual recall — a specific
+entity, exact term, date — keep the existing lexical-first entry
+(`grep`/`search`). This rule is additive only: decision-state questions still
+route to `brain dossier` and temporal questions still route to TMP-03 above,
+regardless of breadth.
+
 **`brain supersede <old-id> <new-id> [--reason R]`** retires `old-id` in favour
 of `new-id` — both sides of the version chain, written through the audited
 `write_note` path in one call. **HOST-broker only** (refused on `role=vm`
@@ -724,10 +751,18 @@ Obsidian "five-step retrieval cascade" rule for any harness reading this file.
   (`--check-content` adds the per-note list), `brain doctor` carries the same
   count as a gating row, and any UNEXPLAINED drift makes the health verdict
   DEGRADED. A vault carrying historical drift (notes edited outside the audited
-  write path before this was visible) triages it once into
-  `<vault>/.brain/audit-drift-dispositions.json`; each disposition is **pinned
-  to the bytes it was ruled on**, so the same note changing again returns as
-  unexplained. Never re-sign or delete drifted notes to clear the count.
+  write path before this was visible) triages it once into a **host-private**
+  disposition file (`brain doctor --json` prints its path); each disposition is
+  **pinned to the bytes it was ruled on**, so the same note changing again
+  returns as unexplained. Never re-sign or delete drifted notes to clear the
+  count. That file moved OFF `<vault>/.brain/` on 2026-08-07: it decides
+  whether tampering counts as EXPLAINED, and a match needs only path + issue +
+  observed hash — every one of which is known to whoever edited the note — so
+  on the shared mount the untrusted VM leg could forge one and drive
+  `unexplained` to 0 while `verify-audit` still reported `ok`. Same treatment
+  and same reason as the approved queue (INT-01), the attachment anchors
+  (INT-04) and the writer lock (INT-05). An existing file is carried forward
+  once, stamped `migrated_from_mount`.
 
 ---
 

{brainiac_cli-0.20.2 → brainiac_cli-0.20.4}/src/brain/_assets/tools/cos_reconcile_metrics.py

@@ -54,6 +54,7 @@ import json
 import os
 import re
 import sys
+import tempfile
 from collections import defaultdict
 from pathlib import Path
 
@@ -455,13 +456,29 @@ def append_metric(ops_dir: Path, row: dict) -> str:
             f"conflicting metrics row for {(row['date'], row['run'])!r}")
 
     prior = path.read_text(encoding="utf-8") if path.exists() else ""
-    tmp = path.with_suffix(".jsonl.tmp")
-    tmp.write_text(
-        prior.rstrip("\n") + ("\n" if prior else "")
-        + json.dumps(row, separators=(",", ":"), ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-    os.replace(tmp, path)
+    payload = (prior.rstrip("\n") + ("\n" if prior else "")
+               + json.dumps(row, separators=(",", ":"), ensure_ascii=False) + "\n")
+    # The temp file used to be the fixed name `_cos_metrics.jsonl.tmp`, written
+    # with `Path.write_text` (Codex cloud review, 2026-08-07). A symlink planted
+    # at that predictable path is FOLLOWED by the open, so the write truncates
+    # and overwrites whatever it points at -- outside the vault included -- and
+    # the later `os.replace` only swaps the link, long after the damage. A COS
+    # run writes here as a documented step, so nothing unusual has to happen.
+    #
+    # `mkstemp` is the stdlib answer to exactly this: a random name created
+    # with O_CREAT|O_EXCL|O_NOFOLLOW-equivalent semantics (it refuses to open an
+    # existing path at all), 0600, in the same directory so `os.replace` stays
+    # atomic on one filesystem.
+    fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix="._cos_metrics-",
+                                    suffix=".jsonl.tmp")
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(payload)
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
     return "appended"
 
 

{brainiac_cli-0.20.2 → brainiac_cli-0.20.4}/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.2"
+__version__ = "0.20.4"

{brainiac_cli-0.20.2 → brainiac_cli-0.20.4}/src/brain/audit.py

@@ -507,21 +507,92 @@ class AuditChain:
 # drifting AGAIN produces a different `actual_sha256`, no longer matches, and
 # comes back as unexplained. Absorbing a whole path forever is exactly the
 # failure mode this instrument exists to prevent.
+#
+# WHERE IT LIVES (changed 2026-08-07): the host-private app-data dir, NOT
+# `<vault>/.brain/`. This file decides whether tampering counts as explained,
+# and a match needs only path + issue + observed hash -- all of which whoever
+# edited the note already knows. On the old path, the Cowork VM could write it,
+# so the untrusted leg could silence the host's own tamper alarm. Pinning to
+# bytes is what stops a disposition absorbing a path forever; being off the
+# mount is what stops it being forged. Both are needed.
 DRIFT_DISPOSITIONS_FILENAME = "audit-drift-dispositions.json"
 
 
 def drift_dispositions_path(vault: Path) -> Path:
-    """Host-only triage file. Lives under ``.brain/`` (gitignored, never
-    indexed, never published to the VM snapshot)."""
+    """Host-private triage file, OFF the VM-visible mount (2026-08-07).
+
+    Raises ``config.HostPathUnsafe`` when it cannot resolve somewhere the
+    Cowork VM is unable to reach — see ``config.audit_drift_dispositions_path``
+    for why this file in particular must be out of reach."""
+    from . import config
+
+    return config.audit_drift_dispositions_path(vault)
+
+
+def legacy_drift_dispositions_path(vault: Path) -> Path:
+    """Where this file lived until 2026-08-07: on the shared mount. Read ONLY
+    by the one-time carry-forward below; nothing else may consult it again."""
     return Path(vault) / ".brain" / DRIFT_DISPOSITIONS_FILENAME
 
 
+def migrate_drift_dispositions(vault: Path) -> str | None:
+    """Carry a pre-2026-08-07 triage file forward to the host-private location.
+
+    Copy, never move: the destination is the only thing read from now on, and
+    deleting the operator's historical record on their behalf is not this
+    function's call. Returns a one-line note when it acted, else ``None``.
+
+    The carried-forward records came from a VM-writable path, so the copy is
+    STAMPED (``migrated_from_mount``) rather than laundered into looking
+    host-authored. Without this, a vault with triaged historical drift would
+    report every previously-explained record as unexplained on first run after
+    the upgrade — a false tamper alarm, which is the fastest way to teach an
+    operator to ignore a real one."""
+    legacy = legacy_drift_dispositions_path(vault)
+    if not legacy.is_file():
+        return None
+    try:
+        dest = drift_dispositions_path(vault)
+    except Exception:  # noqa: BLE001 — unsafe destination: stay fail-closed
+        return None
+    if dest.exists():
+        return None
+    try:
+        raw = json.loads(legacy.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    records = raw.get("dispositions") if isinstance(raw, dict) else raw
+    if not isinstance(records, list):
+        return None
+    try:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            dest.parent.chmod(0o700)
+        except OSError:
+            pass
+        dest.write_text(json.dumps(
+            {"dispositions": records,
+             "migrated_from_mount": legacy.as_posix()},
+            indent=2), encoding="utf-8")
+    except OSError:
+        return None
+    return (f"carried {len(records)} drift disposition(s) forward from the shared "
+            f"mount to {dest} — they were recorded where a Cowork VM could write, "
+            f"so re-check them if you have any reason to doubt that host")
+
+
 def load_drift_dispositions(vault: Path) -> dict[str, dict]:
-    """``{path: record}`` from the triage file; ``{}`` when absent or
-    unreadable. Fails OPEN into "nothing is explained" — an unreadable
-    disposition file must never silently clear a drift count."""
+    """``{path: record}`` from the triage file; ``{}`` when absent, unreadable,
+    or resolvable only to a VM-visible path. Fails CLOSED into "nothing is
+    explained" — an unreadable or untrustworthy disposition file must never
+    silently clear a drift count."""
+    migrate_drift_dispositions(vault)
+    try:
+        path = drift_dispositions_path(vault)
+    except Exception:  # noqa: BLE001 — HostPathUnsafe and anything else
+        return {}
     try:
-        raw = json.loads(drift_dispositions_path(vault).read_text(encoding="utf-8"))
+        raw = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, ValueError):
         return {}
     records = raw.get("dispositions") if isinstance(raw, dict) else raw

{brainiac_cli-0.20.2 → brainiac_cli-0.20.4}/src/brain/config.py

@@ -633,6 +633,37 @@ def writer_lock_path(vault: str | os.PathLike[str] | None = None) -> Path:
     return host_lock_dir(vault) / f"writer-{vault_slug8(vault)}.lock"
 
 
+def audit_drift_dispositions_dir(vault: str | os.PathLike[str] | None = None) -> Path:
+    """Directory holding the INT-02 drift-triage files. Resolution only — the
+    writing path creates it, same convention as ``host_lock_dir``."""
+    return proven_off_mount(host_private_base() / "audit-drift", vault,
+                            what="audit drift disposition store")
+
+
+def audit_drift_dispositions_path(vault: str | os.PathLike[str] | None = None) -> Path:
+    """The file that decides whether post-signing content drift is EXPLAINED.
+
+    OFF THE MOUNT (2026-08-07, Codex cloud security review). It used to be
+    ``<vault>/.brain/audit-drift-dispositions.json``, on the VirtioFS mount a
+    Cowork VM session can write. That made it a tamper-suppression authority
+    sitting in reach of the untrusted leg: a disposition matches on path, issue
+    and OBSERVED hash — every one of which is known to whoever just edited the
+    note — so adding one record drives ``drift_summary()['unexplained']`` to 0,
+    and ``verify_audit`` keeps reporting ``ok`` while a signed note's bytes have
+    changed. The signature check cannot catch it; the whole point of the content
+    pass was to catch what signatures cannot.
+
+    Same treatment, same reason, and now the same helper as the COS approved
+    queue (INT-01), the attachment acceptance anchors (INT-04) and the
+    single-writer lock (INT-05): being unreachable is the control, not a
+    permission bit on a mount that "may only partially honour POSIX bits".
+
+    Raises :class:`HostPathUnsafe` when the resolved location is VM-visible.
+    Callers must treat that as "nothing is explained" — never as a clean bill.
+    Keyed by vault identity so two vaults never share one triage file."""
+    return audit_drift_dispositions_dir(vault) / f"dispositions-{vault_slug8(vault)}.json"
+
+
 def graph_dir(vault: str | os.PathLike[str] | None = None) -> Path:
     """GRF-01 discovery-graph runtime artifacts (ADR-0003 Ruling 6/(a)) —
     gitignored, host-only, never published into the VM snapshot. Holds the

{brainiac_cli-0.20.2 → brainiac_cli-0.20.4}/src/brain/core.py

@@ -3202,6 +3202,19 @@ class BrainCore:
         # `brain maintain`, an interactive session, and the test suite must NEVER
         # trigger an unattended pip upgrade / plugin reinstall of the machine —
         # so default OFF and require the explicit opt-in the scheduler provides.
+        # KILL SWITCH, checked first (2026-08-07). Unattended auto-apply is an
+        # ACCEPTED RISK, not an oversight -- see docs/adr/0005-update-versioning-ux.md
+        # "Risk acceptance" for what is being accepted and why. But an acceptance
+        # you cannot revoke is not an acceptance: `scripts/brain-brief.sh` sets
+        # BRAIN_AUTO_UPDATE=1 INLINE, so an inherited 0 cannot switch it off, and
+        # that runner is a shipped file the next update overwrites. This is the
+        # one way to turn auto-apply off without editing shipped files or
+        # enabling full BRAIN_MANAGED lockdown -- set it in the environment the
+        # scheduled task runs in (launchd plist / cron). Default off: setting
+        # nothing changes nothing.
+        if _os.environ.get("BRAIN_NO_AUTO_UPDATE", "").strip().lower() in (
+                "1", "true", "yes", "on"):
+            return {"auto_update": "disabled", "reason": "BRAIN_NO_AUTO_UPDATE set"}
         if _os.environ.get("BRAIN_AUTO_UPDATE") != "1":
             return {"auto_update": "disabled", "reason": "BRAIN_AUTO_UPDATE!=1 (scheduled-task only)"}
 

{brainiac_cli-0.20.2 → brainiac_cli-0.20.4}/src/brain/doctor.py

@@ -601,10 +601,25 @@ def check_desktop_plugin_store(
         # slash-command skill); in a Cowork session /skill-creator is what
         # repackages + presents the skill for Save-and-Replace. /brainiac-update
         # is host-only (refuses --role vm) so it is NOT the Cowork fix.
-        if _compare(str(version), ssot) < 0:
+        #
+        # ANY mismatch needs action, not just `installed < ssot` (Codex cloud
+        # review, 2026-08-07). `installed > ssot` was reported as "looks current
+        # — no action needed", but ADR-0004 Ruling 5 / the CLI-plugin path
+        # explicitly handle RECONCILIATION DOWNGRADES, where an old installed
+        # plugin legitimately carries a numerically higher version than the
+        # current SSOT. The surface left stale by a false green here is the
+        # LLM-facing Cowork/Desktop skill instructions, so "newer" is not a
+        # reason to leave it alone after a security-relevant release.
+        skew = _compare(str(version), ssot)
+        if skew < 0:
             remediation = ("in a Cowork session use /skill-creator to repackage + "
                            "Save-and-Replace the stale skill(s); re-run brain doctor on "
                            "the host to confirm it took")
+        elif skew > 0:
+            remediation = (f"installed {version} is AHEAD of SSOT {ssot} — a "
+                           "reconciliation downgrade, not a current install; in a "
+                           "Cowork session use /skill-creator to repackage + "
+                           "Save-and-Replace so the shipped skill matches SSOT")
         else:
             remediation = "looks current — no action needed"
         rows.append(_row(surface, MANUAL_REQUIRED, detail, remediation=remediation,
@@ -1209,10 +1224,12 @@ def check_audit_content_drift(vault: Path) -> dict:
     files against hashes already in the log, so this row costs one vault read
     and never resolves the signing key (``verify-audit`` does that separately).
 
-    Only UNEXPLAINED drift gates. Drift a human triaged into
-    ``.brain/audit-drift-dispositions.json`` is reported in the detail and
-    subtracted from the verdict — pinned to the bytes it was ruled on, so the
-    same file changing again comes straight back as unexplained."""
+    Only UNEXPLAINED drift gates. Drift a human triaged into the disposition
+    file is reported in the detail and subtracted from the verdict — pinned to
+    the bytes it was ruled on, so the same file changing again comes straight
+    back as unexplained. That file lives in the HOST-PRIVATE app-data dir since
+    2026-08-07 (``config.audit_drift_dispositions_path``); on the old
+    ``.brain/`` path a Cowork VM could write it and zero out this very row."""
     from . import audit as _audit
     from . import config
 
@@ -1233,7 +1250,8 @@ def check_audit_content_drift(vault: Path) -> dict:
             f"{unexplained} signed note(s) changed after signing with no recorded "
             f"disposition ({explained} triaged, {total} total)",
             remediation="brain verify-audit --check-content --json  # then triage into "
-                        ".brain/audit-drift-dispositions.json or restore the note",
+                        "the host-private disposition file (brain doctor --json shows "
+                        "its path) or restore the note",
             raw={"total": total, "unexplained": unexplained})
     detail = ("no drift — every signed note matches its signed bytes" if not total
               else f"0 unexplained ({explained} triaged historical drift record(s))")

{brainiac_cli-0.20.2 → brainiac_cli-0.20.4}/src/brain/index.py

@@ -2868,7 +2868,23 @@ class BrainIndex:
         row = self.conn.execute(
             "SELECT rowid, classification FROM notes WHERE id=?", (target_id,)
         ).fetchone()
+        # EXISTENCE ORACLE (Codex cloud review, 2026-08-07). A missing id used
+        # to answer `candidate-miss` and echo the id back, while an id that
+        # exists above the caller's cap answered `withheld` — two distinguishable
+        # replies, on a verb the VM is allowed to call. That let an untrusted leg
+        # probe guessed slugs and learn WHICH Restricted/MNPI notes exist, which
+        # is precisely what the egress gate is there to prevent. Note ids are
+        # readable slugs, so guessing is cheap.
+        #
+        # Whenever a cap can hide something, both cases now return the identical
+        # `withheld` payload, so the two are indistinguishable. On an UNCAPPED
+        # caller (the host default is the full vault) nothing can be hidden, so
+        # there is no oracle to close and `candidate-miss` stays the useful
+        # answer for a typo'd id.
+        capped = max_tier != cls_mod.TIERS[-1]
         if not row:
+            if capped:
+                return {"target": "withheld", "verdict": "withheld"}
             return {
                 "target": target_id,
                 "verdict": "candidate-miss",

{brainiac_cli-0.20.2 → brainiac_cli-0.20.4/src/brainiac_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainiac-cli
-Version: 0.20.2
+Version: 0.20.4
 Summary: Brainiac — local any-LLM second-brain core engine + brain CLI (Markdown truth, derived SQLite index).
 License-Expression: Apache-2.0
 Requires-Python: >=3.9