release(v0.2.1): user-visible SessionStart banner + doctor drift signal

Two follow-up gaps from v0.2.0 that turned out to matter once the banner
shipped:

(1) The v0.2.0 banner reached Claude Code's `additionalContext` (model
    context) but was INVISIBLE to the human user. Per Claude Code hooks
    docs, the `systemMessage` field is the documented dual-channel
    rendering — Claude Code displays it as the
    `SessionStart:startup says: <line>` row in the terminal alongside
    other hook output. v0.2.1 adds `systemMessage` to the JSON payload
    plus `user_message` for Cursor forward-compat (Cursor docs note the
    field is "accepted but not enforced" today).

(2) `supamem doctor`'s install-drift detection (per-client managed-block
    version vs running CLI version) now flips the banner health flag to
    ⚠ in real time. Surfaces the "you upgraded supamem but your
    CLAUDE.md / .cursor rules still reference the old version" failure
    mode at session-open instead of waiting for the user to run doctor
    manually. Cheap to compute (small text reads, never raises);
    failures fall back to ✓ rather than blocking session-start.

Suppress only the user-visible row with `SUPAMEM_BANNER_QUIET=1` (keeps
context injection alive for the model). `SUPAMEM_BANNER_DISABLE=1`
still kills both channels.

302 tests pass, ruff clean, twine PEP 639 license check passes.

Refs: research-agent a5c666821a386ce71 — Claude Code hooks docs at
code.claude.com/docs/en/hooks confirm `systemMessage` is the canonical
dual-channel rendering for hook events. Cursor `user_message` is
included for forward-compat per cursor.com/docs/hooks.

Author: dzmitrys-dev

AGENTS.md

@@ -154,3 +154,7 @@ CI guard candidate: a script that fails when `README.md` changes without bumping
 - New config field: extend `config.py` Pydantic schema + bump default in `share/default.toml`
 - New hook target: add module under `src/supamem/hooks/<client>.py`, register in `cli.py hook` dispatcher
 - Failure in network code: blanket `except Exception: pass` is correct for non-essential probes (update_check); for indexing/retrieval, surface error to user via `err_console`
+
+# BEGIN SUPAMEM v0.2.0 MANAGED BLOCK — DO NOT EDIT
+@~/.supamem/share/rules/dual-memory.md
+# END SUPAMEM v0.2.0 MANAGED BLOCK

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to `supamem` will be documented in this file.
 
+## v0.2.1 — unreleased
+
+Patch fixing two v0.2.0 banner gaps that turned out to matter:
+
+### Added
+
+- **User-visible SessionStart banner** — the v0.2.0 banner reached the
+  model via `additionalContext` but was invisible to the user. Adds a
+  `systemMessage` field to the SessionStart hook payload, which Claude
+  Code renders as the `SessionStart:startup says: <line>` row in the
+  terminal (officially documented dual-channel pattern). Cursor
+  `user_message` is included for forward-compat (per Cursor docs the
+  field is "accepted but not enforced" today; will surface once Cursor
+  ships UI for it). Suppress only the user-visible row with
+  `SUPAMEM_BANNER_QUIET=1` (keeps context injection alive for the
+  model). `SUPAMEM_BANNER_DISABLE=1` still kills both channels.
+- **`supamem doctor` install-drift surfaced in the banner** — the
+  health flag now flips to `⚠` when any installed client's managed-
+  block version differs from the running CLI (i.e. you upgraded
+  supamem but a client's CLAUDE.md/.cursor rules still reference the
+  old version). Prompts running `supamem repair` to resync. The drift
+  probe is cheap (small text reads, never raises); banner failures
+  fall back to `✓` rather than blocking session-start.
+
 ## v0.2.0 — 2026-05-01
 
 First milestone of the v0.2.0 token-economy line. Ships server-side hard

README.md

@@ -295,7 +295,8 @@ You should see a colorful banner and the credit line. 🎨
 | `SUPAMEM_GATE_DISABLE=1` | Bypass the opt-in claude-code edit-gate for the current session (`--enforce-search` users only). |
 | `SUPAMEM_ADVISORY_DISABLE=1` | Suppress the Cursor `beforeSubmitPrompt` advisory hook. |
 | `SUPAMEM_NO_UPDATE_CHECK=1`, `NO_UPDATE_NOTIFIER=1`, `CI=1` | Suppress the GitHub Releases probe. |
-| `SUPAMEM_BANNER_DISABLE=1` | Suppress the SessionStart one-line banner. |
+| `SUPAMEM_BANNER_DISABLE=1` | Suppress the SessionStart one-line banner entirely (no context injection, no user-visible status). |
+| `SUPAMEM_BANNER_QUIET=1` | Suppress only the **user-visible** terminal status line; keep injecting the banner into Claude Code's `additionalContext` for the model. Use this when you want supamem context loaded but no per-session `SessionStart:supamem says: …` row in your terminal. |
 
 ### SessionStart banner format
 

llms.txt

@@ -87,6 +87,7 @@ Format: `🧠 supamem ✓ v0.2.0 · <collection> · <N> chunks · audit <path>`
 - Health flag — single character right after `supamem`: `✓` healthy / `⚠` qdrant unreachable OR resolved collection is still the shipped default (legacy global-install / wrong-cwd failure mode)
 - Update hint — cache-only read of `update_check.json`; never blocks session-open on network. Healing is NEVER automatic — the banner only signals; run `supamem repair` to act
 - Suppress entirely with `SUPAMEM_BANNER_DISABLE=1`
+- Suppress ONLY the user-visible terminal line (keep injecting context for the model) with `SUPAMEM_BANNER_QUIET=1`. v0.2.1+ emits `systemMessage` (Claude Code) and `user_message` (Cursor forward-compat) alongside `additionalContext` — Claude Code renders `systemMessage` as the `SessionStart:startup says: <line>` row in the terminal. Health flag `⚠` now also fires on per-client install drift detected by `supamem doctor` (managed-block version != running CLI version).
 
 ## Update-check (v0.1.1+)
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "supamem"
-version = "0.2.0"
+version = "0.2.1"
 description = "Project-agnostic dual-memory tooling for Claude Code, Cursor, and opencode"
 readme = "README.md"
 license = "MIT"

src/supamem/__init__.py

@@ -1,2 +1,2 @@
 """supamem — project-agnostic dual-memory tooling."""
-__version__ = "0.2.0"
+__version__ = "0.2.1"

src/supamem/hooks/session_start.py

@@ -76,7 +76,8 @@ def _probe_health_flag(cfg: ResolvedConfig, points: int | None) -> str:
     * ``"⚠"`` when supamem looks misconfigured for THIS project:
       qdrant unreachable, OR the resolved collection is still the shipped
       default (``dev_memory_tuned_hybrid``) AND no project config was loaded
-      (the legacy global-install failure mode).
+      (the legacy global-install failure mode), OR per-client install drift
+      (a client's managed-block version differs from the running CLI).
     * ``"✓"`` otherwise.
     """
     if points is None:
@@ -86,9 +87,26 @@ def _probe_health_flag(cfg: ResolvedConfig, points: int | None) -> str:
     default_collection = ResolvedConfig().collection
     if cfg.collection == default_collection:
         return "⚠"
+    if _has_install_drift():
+        return "⚠"
     return "✓"
 
 
+def _has_install_drift() -> bool:
+    """True if any installed client's managed-block version differs from the
+    running CLI version (``supamem doctor`` drift signal).
+
+    Cheap: reads small text files; never raises.
+    """
+    try:
+        from supamem.doctor import version_drift_report
+
+        return any(row.get("drift") for row in version_drift_report())
+    except Exception as exc:  # noqa: BLE001 — banner must never fail
+        log.debug("session_start: drift probe failed: %s", exc)
+        return False
+
+
 def _probe_update_hint() -> str | None:
     """Return ``"update v0.X.Y available"`` if a newer release is cached, else None.
 
@@ -161,16 +179,40 @@ def _detect_client() -> str:
 
 
 def _emit_payload(banner: str) -> dict[str, Any]:
-    """Dual-format JSON payload that works across Claude Code / Cursor / OpenCode."""
-    return {
+    """Cross-host JSON payload — silent context injection + user-visible status.
+
+    Three keys, three audiences:
+
+    * ``hookSpecificOutput.additionalContext`` (Claude Code) — silent
+      context injection into the model's window. Carries the full banner
+      so the model knows version, collection, chunk count, audit path.
+    * ``additional_context`` (Cursor / OpenCode forks) — snake-case
+      duplicate; harmless on Claude Code (key ignored).
+    * ``systemMessage`` (Claude Code) — the **user-visible** status line.
+      Per Claude Code hooks docs, this field renders as the
+      ``SessionStart:startup says: <line>`` row the user sees in the
+      terminal. Suppressed when ``SUPAMEM_BANNER_QUIET=1``.
+    * ``user_message`` (Cursor) — Cursor docs note this field is
+      "accepted but not enforced" today; we include it for forward-
+      compat once Cursor ships UI for it. No-op on Claude Code.
+
+    The reason ``additionalContext`` and ``systemMessage`` carry the same
+    payload is that both audiences benefit from the same one-liner: the
+    user gets visible confirmation; the model gets context it can cite
+    when answering "what version of supamem am I on?" without a tool call.
+    """
+    payload: dict[str, Any] = {
         "hookSpecificOutput": {
             "hookEventName": "SessionStart",
             "additionalContext": banner,
         },
-        # Snake-case duplicate for Cursor / OpenCode forks that adopted the
-        # older shape. Harmless on Claude Code (key ignored).
         "additional_context": banner,
     }
+    if os.environ.get("SUPAMEM_BANNER_QUIET", "").strip() != "1":
+        payload["systemMessage"] = banner
+        # Cursor future-compat (currently a no-op in Cursor's UI per its docs).
+        payload["user_message"] = banner
+    return payload
 
 
 def run(client: str | None = None, *, config: ResolvedConfig | None = None) -> int:

tests/test_session_start.py

@@ -36,13 +36,20 @@ def test_build_banner_starts_with_emoji_and_version() -> None:
 
 
 def test_build_banner_health_flag_ok_when_project_collection() -> None:
-    """Custom collection name + reachable qdrant → ✓."""
+    """Custom collection + reachable qdrant + no drift → ✓.
+
+    `_has_install_drift` is mocked so the test's verdict doesn't depend on
+    the developer's real CLAUDE.md / .cursor managed-block versions on the
+    machine running the suite.
+    """
     cfg = ResolvedConfig(collection="proj-coll")
     with patch(
         "supamem.hooks.session_start._probe_collection",
         return_value=("proj-coll", 5),
     ), patch(
         "supamem.hooks.session_start._probe_update_hint", return_value=None
+    ), patch(
+        "supamem.hooks.session_start._has_install_drift", return_value=False
     ):
         banner = build_banner(cfg)
     assert "🧠 supamem ✓ v" in banner
@@ -61,6 +68,22 @@ def test_build_banner_health_flag_warn_on_default_collection() -> None:
     assert "🧠 supamem ⚠ v" in banner
 
 
+def test_build_banner_health_flag_warn_on_install_drift() -> None:
+    """A client whose managed-block version differs from the running CLI
+    flips the health flag to ⚠ — surfaces ``supamem doctor`` drift in-band."""
+    cfg = ResolvedConfig(collection="proj-coll")
+    with patch(
+        "supamem.hooks.session_start._probe_collection",
+        return_value=("proj-coll", 5),
+    ), patch(
+        "supamem.hooks.session_start._probe_update_hint", return_value=None
+    ), patch(
+        "supamem.hooks.session_start._has_install_drift", return_value=True
+    ):
+        banner = build_banner(cfg)
+    assert "🧠 supamem ⚠ v" in banner
+
+
 def test_build_banner_health_flag_warn_on_qdrant_unreachable() -> None:
     cfg = ResolvedConfig(collection="proj-coll")
     with patch(
@@ -169,13 +192,35 @@ def test_detect_client_default_when_no_env(monkeypatch: pytest.MonkeyPatch) -> N
 # ── _emit_payload (dual-format JSON) ────────────────────────────────────────
 
 
-def test_emit_payload_has_both_camelcase_and_snakecase_keys() -> None:
+def test_emit_payload_has_both_camelcase_and_snakecase_keys(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("SUPAMEM_BANNER_QUIET", raising=False)
     payload = _emit_payload("hello banner")
-    # Camel for Claude Code
+    # Camel for Claude Code (silent context injection)
     assert payload["hookSpecificOutput"]["hookEventName"] == "SessionStart"
     assert payload["hookSpecificOutput"]["additionalContext"] == "hello banner"
-    # Snake for Cursor / OpenCode forks
+    # Snake for Cursor / OpenCode forks (silent context injection)
+    assert payload["additional_context"] == "hello banner"
+    # User-visible status (Claude Code renders systemMessage as the
+    # `SessionStart:startup says: <line>` row in the terminal).
+    assert payload["systemMessage"] == "hello banner"
+    # Cursor forward-compat (Cursor docs note user_message is "accepted but
+    # not enforced" today; harmless on Claude Code).
+    assert payload["user_message"] == "hello banner"
+
+
+def test_emit_payload_quiet_env_suppresses_user_visible_keys(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """SUPAMEM_BANNER_QUIET=1 → payload still injects context silently but
+    does NOT emit the user-visible systemMessage / user_message keys."""
+    monkeypatch.setenv("SUPAMEM_BANNER_QUIET", "1")
+    payload = _emit_payload("hello banner")
+    assert payload["hookSpecificOutput"]["additionalContext"] == "hello banner"
     assert payload["additional_context"] == "hello banner"
+    assert "systemMessage" not in payload
+    assert "user_message" not in payload
 
 
 # ── run (end-to-end) ────────────────────────────────────────────────────────