@junghanacs/entwurf 0.15.0 → 0.16.0

package/scripts/omp-mcp-config.py

@@ -0,0 +1,392 @@
+#!/usr/bin/env python3
+"""Stateful OMP-native MCP-config adapter; stdlib only (#87 step 5).
+
+Owns ONE server key inside the omp-native user MCP file (``<agent dir>/mcp.json``).
+The file wrapper is always ``mcpServers`` and the stdio entry follows omp's OWN writer
+layer — ``{command, args?, env?}`` with ``type`` omitted (stdio is the default) —
+measured at ``mcp/config-writer.ts:111-143`` + ``config/mcp-schema.json`` on v18.0.0.
+
+THE SERVER KEY IS A PINNED LITERAL, AND THAT IS THE WHOLE MECHANISM. omp already
+translates Claude Code's ``~/.claude.json`` as an IMPORT provider, so on a host that ever
+used Claude Code there is already an ``entwurf-bridge`` server — carrying Claude Code's
+external agent id. This writer does not remove it, hide it, or ask the operator to: it
+shadows it, and same-key first-wins is how. Provider priorities are native=100 >
+omp-plugins=90 > claude=80 (``capability/index.ts:84-91``), dedupe is first-wins on
+``key: server => server.name`` (``:183``), and on a key hit ``equivalent()`` is NEVER
+consulted (``:203-207``) — so an entry whose env deliberately differs still suppresses the
+import completely. A DIFFERENT key would load BOTH: two bridge tool families, one of them
+still introducing this session as Claude Code.
+
+``disabledServers`` IS NOT THE HIDE-IMPORT TOOL. Suppression is by NAME
+(``mcp/config.ts:123-127``) and a suppressed item still claims the dedupe key
+(``capability/index.ts:191-196``), so denylisting ``entwurf-bridge`` kills the native entry
+and the import together. This adapter never writes that key, and the doctor goes red when
+somebody else has.
+"""
+
+import datetime
+import json
+import os
+import sys
+import tempfile
+
+STATE_SCHEMA_VERSION = 1
+
+# PINNED. The literal `mcpServers` map key the Claude import also uses — measured LIVE on
+# oracle 2026-08-27 (`/mcp list` → "Claude Code (~/.claude.json): entwurf-bridge") and in
+# source (`discovery/claude.ts:88-92` assigns the plain object key with no prefix). Changing
+# this string does not rename our entry; it un-shadows the import.
+SERVER_KEY = "entwurf-bridge"
+
+# The provenance label this whole surface exists to fix: an omp session riding the import
+# introduces itself to the bridge as Claude Code.
+EXTERNAL_AGENT_ID = "external-mcp/omp"
+ENV_KEY = "ENTWURF_BRIDGE_EXTERNAL_AGENT_ID"
+
+SCHEMA_URL = "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json"
+
+
+def die(code: int, message: str) -> "None":
+    sys.stderr.write(message.rstrip("\n") + "\n")
+    raise SystemExit(code)
+
+
+def load_object(path: str, label: str) -> dict:
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            raw = handle.read()
+    except OSError as error:
+        die(4, f"omp-mcp: cannot read {label} {path}: {error}")
+    if not raw.strip():
+        return {}
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as error:
+        die(4, f"omp-mcp: {label} {path} is not valid JSON: {error}")
+    if not isinstance(value, dict):
+        die(4, f"omp-mcp: {label} {path} top-level must be a JSON object")
+    return value
+
+
+def atomic_write(path: str, value: dict) -> None:
+    directory = os.path.dirname(os.path.abspath(path))
+    os.makedirs(directory, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(dir=directory, prefix=".omp-mcp-", suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(value, handle, indent=2)
+            handle.write("\n")
+        os.replace(temporary, path)
+    except BaseException:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def now() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def our_entry(command: str, args: list) -> dict:
+    # `type` is omitted on purpose: stdio is the default in omp's own schema, and the
+    # vendor's writer omits it too. `env` carries the one fact that makes this entry worth
+    # writing at all — the omp provenance label.
+    return {"command": command, "args": args, "env": {ENV_KEY: EXTERNAL_AGENT_ID}}
+
+
+def checked_state(state_path: str) -> dict:
+    state = load_object(state_path, "install-state")
+    required = (
+        "managedConfigPath",
+        "serverKey",
+        "command",
+        "args",
+        "detectMode",
+        "configExistedBefore",
+        "preimage",
+    )
+    if state.get("schemaVersion") != STATE_SCHEMA_VERSION or any(key not in state for key in required):
+        die(4, f"omp-mcp: install-state {state_path} has an unsupported shape")
+    if state.get("serverKey") != SERVER_KEY:
+        die(4, f"omp-mcp: install-state {state_path} serverKey is not {SERVER_KEY}")
+    return state
+
+
+def prior_state(state_path: str, config_path: str) -> dict | None:
+    """The ownership state for THIS target, or a refusal.
+
+    A state that names a DIFFERENT config is not "no state" (#87 D1). Treating it as
+    absent captured a fresh preimage and overwrote the single state file, stranding the
+    previous profile's managed entry with no inverse left to remove it. There is one
+    state and one target: changing the target is uninstall-then-install, in that order.
+    """
+    if not os.path.exists(state_path):
+        return None
+    state = checked_state(state_path)
+    if state["managedConfigPath"] != os.path.abspath(config_path):
+        die(
+            3,
+            f"omp-mcp: install-state {state_path} already manages {state['managedConfigPath']}, "
+            f"but this host now reads {os.path.abspath(config_path)}. One state owns one target: "
+            "overwriting it would strand the first entry with no inverse. Run uninstall-omp-mcp with "
+            "the ORIGINAL omp agent dir / profile selected, then install here.",
+        )
+    return state
+
+
+def disabled_names(data: dict) -> list:
+    value = data.get("disabledServers")
+    return [name for name in value if isinstance(name, str)] if isinstance(value, list) else []
+
+
+def install(config_path: str, command: str, args_json: str, state_path: str) -> None:
+    if os.path.islink(config_path):
+        die(3, f"omp-mcp: refusing to adopt {config_path} — symlink to {os.readlink(config_path)} (someone else's SSOT)")
+    try:
+        args = json.loads(args_json)
+    except json.JSONDecodeError as error:
+        die(5, f"omp-mcp: args must be a JSON array: {error}")
+    if not isinstance(args, list) or not all(isinstance(a, str) for a in args):
+        die(5, "omp-mcp: args must be a JSON array of strings")
+
+    existed = os.path.exists(config_path)
+    data = load_object(config_path, "config") if existed else {"$schema": SCHEMA_URL}
+    servers = data.get("mcpServers")
+    if servers is None:
+        servers = {}
+        data["mcpServers"] = servers
+    if not isinstance(servers, dict):
+        die(4, f"omp-mcp: {config_path} mcpServers must be a JSON object")
+
+    # A pre-existing denylist on OUR key would suppress the entry we are about to write —
+    # and the import with it. Refuse rather than write a server nothing will ever load.
+    if SERVER_KEY in disabled_names(data):
+        die(
+            3,
+            f"omp-mcp: {config_path} lists {SERVER_KEY!r} in disabledServers. Suppression is by NAME "
+            "(mcp/config.ts:123-127) and a suppressed item still claims the dedupe key "
+            "(capability/index.ts:191-196), so this would kill BOTH the native entry and the Claude "
+            "import. Remove that denylist entry first — it is never the way to hide an import.",
+        )
+
+    prior = prior_state(state_path, config_path)
+    if prior is None:
+        state = {
+            "schemaVersion": STATE_SCHEMA_VERSION,
+            "managedConfigPath": os.path.abspath(config_path),
+            "serverKey": SERVER_KEY,
+            "command": command,
+            "args": args,
+            "detectMode": "adopt-regular-file" if existed else "created-new",
+            "configExistedBefore": existed,
+            # THE PREIMAGE IS THE CURRENT VALUE ON DISK, even when it is byte-identical to
+            # what we are about to write. Inventing a "there was nothing here before" case
+            # for one backend is the special-casing the rail exists to prevent.
+            "preimage": servers.get(SERVER_KEY),
+            "installedAt": now(),
+        }
+    else:
+        state = prior
+
+    servers[SERVER_KEY] = our_entry(command, args)
+    atomic_write(config_path, data)
+    atomic_write(state_path, state)
+    sys.stdout.write(f"{state['detectMode']} {os.path.abspath(config_path)}\n")
+
+
+def uninstall(state_path: str) -> None:
+    if not os.path.exists(state_path):
+        die(2, f"omp-mcp: no install-state at {state_path} — nothing to undo")
+    state = checked_state(state_path)
+    config_path = state.get("managedConfigPath")
+    if not isinstance(config_path, str) or not os.path.isabs(config_path):
+        die(4, f"omp-mcp: install-state {state_path} has no absolute managedConfigPath")
+    if os.path.islink(config_path):
+        die(3, f"omp-mcp: refusing to uninstall — {config_path} became a symlink (someone else's SSOT)")
+
+    if os.path.exists(config_path):
+        data = load_object(config_path, "config")
+        servers = data.get("mcpServers")
+        if isinstance(servers, dict):
+            preimage = state.get("preimage")
+            if preimage is None:
+                servers.pop(SERVER_KEY, None)
+            else:
+                servers[SERVER_KEY] = preimage
+            created = state.get("detectMode") == "created-new" and state.get("configExistedBefore") is False
+            # We created this file, and nothing but our own two keys is left in it. The
+            # honest inverse of "created-new" is an absent file — a stub carrying only a
+            # $schema line would be an artifact of ours surviving our own removal.
+            only_ours = created and len(servers) == 0 and set(data.keys()) <= {"mcpServers", "$schema"}
+            if only_ours:
+                os.remove(config_path)
+            else:
+                atomic_write(config_path, data)
+
+    os.remove(state_path)
+    sys.stdout.write(f"uninstalled {config_path}\n")
+
+
+def native_entry_state(servers: dict) -> str:
+    """`absent` | `invalid` | `present` — STRUCTURAL validity of the entry under our key.
+
+    Deliberately says nothing about ownership, about which command it names, or about
+    provenance: those are other axes with other verdicts. This one answers only "would omp
+    be able to load this at all", which is what makes an invalid entry red without an
+    install-state (#87 B4).
+    """
+    if not isinstance(servers, dict) or SERVER_KEY not in servers:
+        return "absent"
+    server = servers.get(SERVER_KEY)
+    if not isinstance(server, dict):
+        return "invalid"
+    if server.get("type") not in (None, "stdio"):
+        return "invalid"
+    command = server.get("command")
+    if not isinstance(command, str) or not command:
+        return "invalid"
+    args = server.get("args", [])
+    if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args):
+        return "invalid"
+    env = server.get("env", {})
+    if not isinstance(env, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in env.items()):
+        return "invalid"
+    return "present"
+
+
+def _doctor_invocation(config_path: str, command: str):
+    if os.path.islink(config_path):
+        return "symlink", None
+    if not os.path.exists(config_path):
+        return "file-absent", None
+    try:
+        data = load_object(config_path, "config")
+    except SystemExit:
+        return "invalid-json", None
+    if SERVER_KEY in disabled_names(data):
+        return "self-disabled", None
+    servers = data.get("mcpServers") if isinstance(data.get("mcpServers"), dict) else {}
+    # STRUCTURE first, through the one shared predicate — so "is this loadable at all" has
+    # a single answer here and in doctor-shadow, and cannot drift into two.
+    state = native_entry_state(servers)
+    if state == "absent":
+        return "not-ours", None
+    if state == "invalid":
+        return "invalid-entry", None
+    server = servers[SERVER_KEY]
+    found = server["command"]
+    args = server.get("args", [])
+    env = server.get("env", {})
+    if found != command:
+        return "not-ours", None
+    # The provenance label is the reason this entry exists. An entry that boots but
+    # introduces the session as some other harness is not our entry.
+    if env.get(ENV_KEY) != EXTERNAL_AGENT_ID:
+        return "foreign-provenance", None
+    return "configured", {"command": found, "args": args, "env": env}
+
+
+def doctor_static(config_path: str, command: str) -> None:
+    status, invocation = _doctor_invocation(config_path, command)
+    if status != "configured":
+        sys.stdout.write(f"{status}\n")
+        return
+    sys.stdout.write(f"configured {invocation['command']}\n")
+
+
+def doctor_invocation(config_path: str, command: str) -> None:
+    status, invocation = _doctor_invocation(config_path, command)
+    if status != "configured":
+        die(4, f"omp-mcp: cannot read configured invocation from {config_path}: {status}")
+    sys.stdout.write(json.dumps(invocation, separators=(",", ":")) + "\n")
+
+
+def doctor_shadow(config_path: str, *import_paths: str) -> None:
+    """Is the EFFECTIVE `entwurf-bridge` this host's omp will load the native entry?
+
+    This is a CONFIGURATION read, never a runtime receipt: it reports what omp's own
+    precedence rules decide about the files on disk. The vendor's own `/mcp list` pane is
+    the live oracle, and it is taken once as a LIVE receipt rather than re-derived here.
+
+    Prints one line per fact, then a verdict line:
+      native <present|invalid|absent>
+      import <path> <key-present|key-absent|unreadable>
+      disabled <yes|no>
+      verdict <native-wins|native-invalid|import-wins|both-suppressed|no-entry>
+
+    RUNTIME VALIDITY AND OWNERSHIP ARE SEPARATE AXES (Hard Rule 13, #87 B4). "The key is
+    present" is not "the entry works": a null / non-object / malformed value under our key
+    still claims the dedupe slot, so the import is suppressed AND nothing loads. Reporting
+    that as `native-wins` turned a broken effective source into a PASS whenever no
+    ownership state happened to exist. An invalid entry gets its own verdict, and it is red
+    on the runtime axis whether or not entwurf owns anything here.
+    """
+    data = {}
+    if os.path.exists(config_path) and not os.path.islink(config_path):
+        try:
+            data = load_object(config_path, "config")
+        except SystemExit:
+            data = {}
+    servers = data.get("mcpServers") if isinstance(data.get("mcpServers"), dict) else {}
+    native_state = native_entry_state(servers)
+    sys.stdout.write(f"native {native_state}\n")
+
+    import_hit = False
+    for path in import_paths:
+        expanded = os.path.expanduser(path)
+        if not os.path.exists(expanded):
+            continue
+        try:
+            imported = load_object(expanded, "imported config")
+        except SystemExit:
+            sys.stdout.write(f"import {expanded} unreadable\n")
+            continue
+        keys = imported.get("mcpServers")
+        present = isinstance(keys, dict) and SERVER_KEY in keys
+        import_hit = import_hit or present
+        sys.stdout.write(f"import {expanded} {'key-present' if present else 'key-absent'}\n")
+
+    disabled = SERVER_KEY in disabled_names(data)
+    sys.stdout.write(f"disabled {'yes' if disabled else 'no'}\n")
+
+    if disabled:
+        verdict = "both-suppressed"
+    elif native_state == "invalid":
+        # It still claims the dedupe key, so the import is suppressed too — but nothing
+        # loads. Never `native-wins`.
+        verdict = "native-invalid"
+    elif native_state == "present":
+        verdict = "native-wins"
+    elif import_hit:
+        verdict = "import-wins"
+    else:
+        verdict = "no-entry"
+    sys.stdout.write(f"verdict {verdict}\n")
+
+
+def main(argv: list[str]) -> None:
+    if len(argv) < 2:
+        die(5, "usage: omp-mcp-config.py <install|uninstall|doctor-static|doctor-invocation|doctor-shadow> ...")
+    match argv[1]:
+        case "install" if len(argv) == 6:
+            install(argv[2], argv[3], argv[4], argv[5])
+        case "uninstall" if len(argv) == 3:
+            uninstall(argv[2])
+        case "doctor-static" if len(argv) == 4:
+            doctor_static(argv[2], argv[3])
+        case "doctor-invocation" if len(argv) == 4:
+            doctor_invocation(argv[2], argv[3])
+        case "doctor-shadow" if len(argv) >= 3:
+            doctor_shadow(argv[2], *argv[3:])
+        case _:
+            die(
+                5,
+                "usage: omp-mcp-config.py <install config command args-json state|uninstall state|"
+                "doctor-static config command|doctor-invocation config command|doctor-shadow config [import...]>",
+            )
+
+
+if __name__ == "__main__":
+    main(sys.argv)

package/scripts/omp-receive-doctor.sh

@@ -0,0 +1,246 @@
+#!/usr/bin/env bash
+# omp-receive-doctor.sh — the fail-loud surface for the OMP RECEIVER extension
+# (#87 bundle B).
+#
+# TWO AXES, REPORTED SEPARATELY, EITHER RED IS RED (AGENTS.md Hard Rule 13):
+#   runtime   — is there a receiver unit omp will import, does it carry the CURRENT
+#               writer, what did it do the last time it ran, and is a doorbell actually
+#               held right now?
+#   ownership — does entwurf own that unit, by a state whose shape and bindings hold?
+#
+# WHAT "ARMED" IS ALLOWED TO MEAN HERE, AND WHAT IT IS NOT. A receiver marker records
+# that a LIVE owner reached the watch-arm emit. It is NOT proof that the vendor's file
+# watch is still registered — the Claude unit says the same about its own marker in the
+# same words (`meta-bridge-hook.ts:279-280`), and on this rail the owner is the operator's
+# TUI process itself, so a wedged event loop looks identical to a healthy one from out
+# here. This doctor therefore reports what it can prove (a marker, its owner's liveness,
+# the mailbox behind it) and never upgrades that into "a wake will happen".
+#
+# THE MARKER READ GOES THROUGH THE PRODUCTION READER, never a filename or a grep:
+# `./run.sh omp-receive-facts` projects `readMetaReceiverMarker` for both readings — the
+# live one dispatch gets, and the file as written — so "nothing armed" stays
+# distinguishable from "armed, then the session died".
+#
+# ZERO ARMED RECEIVERS IS NOT-YET, NEVER RED. A host with the unit installed and no omp
+# TUI open has nothing to arm; that is the designed resting state.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(cd "$HERE/.." && pwd)"
+UNIT="entwurf-receive-omp"
+SRC="$REPO/pi/omp-receive"
+ASM="${ENTWURF_OMP_RECEIVE_ASM:-${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/omp-receive/.assembled}"
+STATE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/omp-receive"
+STATE_FILE="$STATE_DIR/install-state.json"
+BIRTH_STATE="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/omp-bridge/install-state.json"
+
+fail=0
+own_fail=0
+ok()   { echo "  ok    $*"; }
+note() { echo "  note  $*"; }
+bad()  { echo "  FAIL  $*"; fail=1; }
+own_bad() { echo "  FAIL  $*"; own_fail=1; }
+
+# shellcheck source=scripts/omp-bridge-oracle.sh
+. "$HERE/omp-bridge-oracle.sh"
+
+echo "[omp-receive-doctor] unit: $UNIT"
+
+# ── root-grammar preflight, BEFORE anything is read ──────────────────────────
+# Same rule and same reason as the birth doctor (#87 A2): the four overrides are absolute
+# or `~`-rooted only. A relative value resolves against each process's own cwd, and this
+# doctor does not share one with the extension, so asking anything first would answer
+# about a different directory. A refused environment is RUNTIME RED, never laundered into
+# a NOT-YET about some other store.
+ROOT_POLICY_REFUSAL=""
+for var in ENTWURF_META_SESSIONS_DIR ENTWURF_META_MAILBOX_DIR ENTWURF_META_SENDERS_DIR ENTWURF_META_RECEIVERS_DIR; do
+  val="${!var:-}"
+  [ -n "$val" ] || continue
+  case "$val" in
+    /*|"~"|"~/"*) ;;
+    *) ROOT_POLICY_REFUSAL="${ROOT_POLICY_REFUSAL:+$ROOT_POLICY_REFUSAL, }$var=$val" ;;
+  esac
+done
+
+echo
+echo "[omp-receive-doctor] runtime axis"
+
+AGENT_DIR=""
+UNIT_DIR=""
+if AGENT_DIR="$(omp_agent_dir 2>/dev/null)"; then
+  UNIT_DIR="$AGENT_DIR/extensions/$UNIT"
+  ok "omp agent directory: $AGENT_DIR"
+else
+  bad "the omp agent directory this host reads is AMBIGUOUS (inherited PI_CODING_AGENT_DIR / PI_CONFIG_DIR / PI_PROFILE) — no honest statement about the installed unit can be made; pass ENTWURF_OMP_AGENT_DIR if you mean a non-default one"
+fi
+
+# ── the artifact omp would import ────────────────────────────────────────────
+INSTALLED_ENTRY=""
+if [ -n "$UNIT_DIR" ]; then
+  if [ -L "$UNIT_DIR" ]; then
+    bad "$UNIT_DIR is a SYMLINK — this installer never creates one, so what omp would import is not ours"
+  elif [ -d "$UNIT_DIR" ]; then
+    if omp_assembly_valid "$(dirname "$UNIT_DIR")" "$UNIT" 2>/dev/null; then
+      [ -f "$UNIT_DIR/index.ts" ] && INSTALLED_ENTRY="index.ts"
+      [ -z "$INSTALLED_ENTRY" ] && [ -f "$UNIT_DIR/index.js" ] && INSTALLED_ENTRY="index.js"
+      ok "installed unit is structurally complete: $UNIT_DIR (entry $INSTALLED_ENTRY)"
+    else
+      bad "installed unit at $UNIT_DIR fails the structural oracle — omp may import a half-unit"
+    fi
+  else
+    note "NOT-INSTALLED: no receiver unit at $UNIT_DIR. omp citizens on this host are outbound-only; dispatch to them answers mailbox-undeliverable. Install with ./run.sh install-omp-receive"
+  fi
+fi
+
+# ── writer parity: source vs assembled vs installed ──────────────────────────
+# The same stale-writer axis the birth and Claude doctors carry. A deployed unit that
+# predates the source is the failure that looks like success: everything is green and the
+# behaviour is last week's.
+digest() { [ -f "$1" ] && python3 -c "import hashlib,sys;print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest()[:12])" "$1" || echo "-"; }
+SRC_ENTRY="$REPO/pi-extensions/meta-bridge-receive-omp.ts"
+case "$REPO" in
+  */node_modules/@junghanacs/entwurf) SRC_ENTRY="$REPO/mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-receive-omp.js" ;;
+esac
+# TWO artifacts, not one. The ENTRY is this unit's own logic; `lib/meta-session` is the
+# SHARED writer every native unit carries a copy of, and it is the one that goes stale
+# silently — a backend id, a marker field or a root-policy fix lands in the source while
+# three deployed bundles keep last week's copy. Checking only the entry would call such a
+# host green (measured: it did, in this very smoke).
+if [ -n "$INSTALLED_ENTRY" ]; then
+  LIB_EXT="ts"; [ "$INSTALLED_ENTRY" = "index.js" ] && LIB_EXT="js"
+  SRC_LIB="$REPO/pi-extensions/lib/meta-session.ts"
+  [ "$LIB_EXT" = "js" ] && SRC_LIB="$REPO/mcp/entwurf-bridge/dist/pi-extensions/lib/meta-session.js"
+  for pair in "entry:$SRC_ENTRY:$UNIT_DIR/$INSTALLED_ENTRY" "writer:$SRC_LIB:$UNIT_DIR/lib/meta-session.$LIB_EXT"; do
+    what="${pair%%:*}"; rest="${pair#*:}"; src="${rest%%:*}"; ins="${rest#*:}"
+    SRC_D="$(digest "$src")"; INS_D="$(digest "$ins")"
+    if [ "$SRC_D" = "$INS_D" ]; then
+      ok "$what parity: source == installed ($SRC_D)"
+    else
+      bad "STALE $what: source=$SRC_D installed=$INS_D ($ins) — the deployed receiver is not this checkout's. Re-run ./run.sh install-omp-receive (and 'pnpm run build-bridge' first in a dev clone if you changed the source)"
+    fi
+  done
+fi
+
+# ── what the unit DID, off its own log ───────────────────────────────────────
+# Arm failures and doorbell failures are judged on SEPARATE axes: a citizen can be armed
+# and still fail to ring, and folding the two would print "nothing is armed" about a
+# session whose marker is right there.
+RECEIVE_LOG=""
+if [ -n "$ROOT_POLICY_REFUSAL" ]; then
+  bad "the omp meta-root policy REFUSES this environment: $ROOT_POLICY_REFUSAL — a garden root must be absolute or ~-rooted. The extension receives the same refusal, so no store can be named here"
+else
+  RECEIVE_LOG="${ENTWURF_META_SESSIONS_DIR:+$(dirname "$ENTWURF_META_SESSIONS_DIR")}"
+  [ -n "$RECEIVE_LOG" ] || RECEIVE_LOG="$HOME/.pi/agent"
+  RECEIVE_LOG="$RECEIVE_LOG/meta-bridge-receive-omp.log"
+fi
+if [ -n "$RECEIVE_LOG" ] && [ -f "$RECEIVE_LOG" ]; then
+  # `grep -c` PRINTS 0 and EXITS 1 on no-match, so the idiomatic `|| echo 0` appends a
+  # SECOND zero and every later `[ "$N" -gt 0 ]` dies with "integer expected" — caught
+  # here on a real host, where a stale-marker read went through a doctor that had already
+  # printed two shell errors. Count without the fallback and normalise once.
+  count_in_log() { grep -c -- "$1" "$RECEIVE_LOG" 2>/dev/null | head -1 | tr -cd '0-9'; }
+  ARMED_N="$(count_in_log " armed garden=")"; ARMED_N="${ARMED_N:-0}"
+  RANG_N="$(count_in_log " rang garden=")"; RANG_N="${RANG_N:-0}"
+  GAVEUP_N="$(count_in_log "arm-gave-up")"; GAVEUP_N="${GAVEUP_N:-0}"
+  ARMFAIL_N="$(grep -cE "arm-failed|arm-refused" "$RECEIVE_LOG" 2>/dev/null | head -1 | tr -cd '0-9')"; ARMFAIL_N="${ARMFAIL_N:-0}"
+  RINGFAIL_N="$(grep -cE "doorbell-failed|watch-error|signal-vanished" "$RECEIVE_LOG" 2>/dev/null | head -1 | tr -cd '0-9')"; RINGFAIL_N="${RINGFAIL_N:-0}"
+  ok "receive log: $RECEIVE_LOG (armed=$ARMED_N rang=$RANG_N)"
+  [ "$GAVEUP_N" -gt 0 ] && bad "$GAVEUP_N session(s) GAVE UP arming — birth never wrote a sender marker in that process. Those citizens were never addressable; check ./run.sh doctor-omp-bridge"
+  [ "$ARMFAIL_N" -gt 0 ] && bad "$ARMFAIL_N arm failure/refusal line(s) — a citizen exists but no doorbell was published for it:" && grep "arm-failed\|arm-refused" "$RECEIVE_LOG" | tail -3 | sed 's/^/        /'
+  [ "$RINGFAIL_N" -gt 0 ] && bad "$RINGFAIL_N doorbell/watch failure line(s) — the wake half broke on a live citizen:" && grep "doorbell-failed\|watch-error\|signal-vanished" "$RECEIVE_LOG" | tail -3 | sed 's/^/        /'
+elif [ -n "$RECEIVE_LOG" ]; then
+  note "NOT-YET: no receive log at $RECEIVE_LOG — this unit has not run. Open an omp TUI and re-run"
+fi
+
+# ── who is armed RIGHT NOW, through the production reader ────────────────────
+if [ -z "$ROOT_POLICY_REFUSAL" ]; then
+  FACTS_RC=0
+  FACTS="$(env -u PI_CODING_AGENT_DIR "$REPO/run.sh" omp-receive-facts 2>&1)" || FACTS_RC=$?
+  if [ "$FACTS_RC" -ne 0 ]; then
+    bad "omp-receive-facts could not read the receiver markers (rc=$FACTS_RC):"
+    printf '%s\n' "$FACTS" | tail -3 | sed 's/^/        /'
+  else
+    SUMMARY="$(printf '%s' "$FACTS" | python3 -c '
+import json, sys
+d = json.load(sys.stdin)
+rs = d.get("receivers") or []
+live = [r for r in rs if r.get("ownerLive")]
+dead = [r for r in rs if not r.get("ownerLive")]
+print(len(rs), len(live), len(dead), len(d.get("unreadableMarkers") or []))
+for r in live:
+    print("LIVE", r["gardenId"], r["ownerPid"], r["ownerKind"], r["unreadDelivered"], r["freshUnannounced"])
+for r in dead:
+    print("DEAD", r["gardenId"], r["ownerPid"], r["ownerKind"], r["unreadDelivered"], r["freshUnannounced"])
+' 2>/dev/null)" || SUMMARY=""
+    if [ -z "$SUMMARY" ]; then
+      bad "omp-receive-facts returned output this doctor could not parse — refusing to guess"
+    else
+      COUNTS="$(printf '%s' "$SUMMARY" | head -1)"
+      TOTAL="$(echo "$COUNTS" | cut -d' ' -f1)"; LIVE="$(echo "$COUNTS" | cut -d' ' -f2)"
+      DEAD="$(echo "$COUNTS" | cut -d' ' -f3)"; BADM="$(echo "$COUNTS" | cut -d' ' -f4)"
+      if [ "$TOTAL" -eq 0 ]; then
+        note "NOT-YET: no omp receiver markers. Nothing is armed, so dispatch to an omp citizen is the honest mailbox-undeliverable refusal. Open an omp TUI with this unit installed and re-run"
+      else
+        # A stale marker is not a fault: the reader already refuses it and dispatch is
+        # fail-closed. It is reported so an operator can tell "nothing armed" from
+        # "something armed and then the session died" — two states one count would hide.
+        if [ "$LIVE" -gt 0 ]; then
+          ok "$LIVE live / $DEAD stale omp receiver marker(s)"
+        else
+          note "0 live / $DEAD stale omp receiver marker(s) — nothing is armed right now, so dispatch to an omp citizen is the honest mailbox-undeliverable refusal"
+        fi
+        printf '%s\n' "$SUMMARY" | tail -n +2 | while read -r state gid pid kind unread fresh; do
+          if [ "$state" = "LIVE" ]; then
+            echo "        armed  $gid owner=$pid ($kind) unread=$unread not-yet-announced=$fresh"
+            [ "${fresh:-0}" -gt 0 ] && echo "        note   $fresh body/ies are enqueued but no doorbell has announced them — the watch may not be firing"
+          else
+            echo "        stale  $gid owner=$pid ($kind) — owner is gone; the reader already refuses this, dispatch is fail-closed"
+          fi
+        done
+      fi
+      [ "${BADM:-0}" -gt 0 ] && bad "$BADM receiver marker file(s) the production reader could not parse — inspect them by hand"
+    fi
+  fi
+fi
+
+# ── the two units this one is useless without ────────────────────────────────
+# Not a duplicate of their own doctors — a NOTE, on the one axis this doctor owns:
+# a doorbell with no birth has no citizen to join, and a doorbell with no tool hand rings
+# for a model that has no entwurf_inbox_read to drain with.
+if [ -f "$BIRTH_STATE" ]; then
+  ok "birth unit is installed (ownership state present) — this receiver has a citizen to join"
+else
+  note "the BIRTH unit is not installed here (no $BIRTH_STATE). Without it nothing mints a citizen, so this receiver will log arm-deferred and then give up. Install with ./run.sh install-omp-bridge"
+fi
+if [ -n "$AGENT_DIR" ] && [ -f "$AGENT_DIR/mcp.json" ] && grep -q "entwurf-bridge" "$AGENT_DIR/mcp.json" 2>/dev/null; then
+  ok "an entwurf-bridge MCP entry exists in $AGENT_DIR/mcp.json — the model has a way to reach entwurf_inbox_read (doctor-omp-mcp owns that axis)"
+else
+  note "no entwurf-bridge entry found in the omp MCP config. The doorbell announces a tool the model would not have; install with ./run.sh install-omp-mcp and verify with ./run.sh doctor-omp-mcp"
+fi
+
+# ── ownership axis ───────────────────────────────────────────────────────────
+echo
+echo "[omp-receive-doctor] ownership axis"
+if [ -L "$STATE_FILE" ]; then
+  own_bad "ownership state $STATE_FILE is a SYMLINK — refusing to trust it"
+elif [ -f "$STATE_FILE" ]; then
+  if [ -n "$UNIT_DIR" ] && omp_state_read "$STATE_FILE" "$UNIT_DIR" "$ASM" >/dev/null 2>&1; then
+    ok "ownership state binds this installation: $STATE_FILE"
+    if [ -n "$UNIT_DIR" ] && [ ! -e "$UNIT_DIR" ]; then
+      own_bad "ownership state claims $UNIT_DIR but nothing is there — the inverse (./run.sh uninstall-omp-receive) will refuse until this is resolved"
+    fi
+  else
+    own_bad "ownership state $STATE_FILE is corrupt or names a DIFFERENT installation than $UNIT_DIR"
+  fi
+elif [ -n "$UNIT_DIR" ] && [ -e "$UNIT_DIR" ]; then
+  own_bad "$UNIT_DIR exists with NO ownership state. A directory that looks like our unit is not proof it is ours — the installer refuses to adopt it and the inverse refuses to remove it. Resolve by hand"
+else
+  note "no ownership state and no unit — this host has no omp receiver installed (a clean absence, not a fault)"
+fi
+
+echo
+if [ "$fail" -eq 0 ]; then echo "[omp-receive-doctor] runtime axis: PASS"; else echo "[omp-receive-doctor] runtime axis: FAIL"; fi
+if [ "$own_fail" -eq 0 ]; then echo "[omp-receive-doctor] ownership axis: PASS"; else echo "[omp-receive-doctor] ownership axis: FAIL"; fi
+if [ "$fail" -eq 0 ] && [ "$own_fail" -eq 0 ]; then echo "[omp-receive-doctor] PASS"; exit 0; fi
+echo "[omp-receive-doctor] FAIL"
+exit 1