@junghanacs/entwurf 0.15.1 → 0.16.1

package/scripts/omp-bridge-oracle.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# omp-bridge-oracle.sh — the ONE structural oracle for the OMP birth unit (#87).
+# Sourced by the installer, the inverse and the doctor so "valid assembly", "valid
+# ownership state" and "which agent dir does omp actually read" cannot mean three
+# different things in three files.
+#
+# omp_agent_dir
+#   Resolve the agent directory omp itself would read, or REFUSE. Prints the absolute
+#   path on rc 0; prints the reason on stderr and returns rc 1 when the environment is
+#   ambiguous. See the function header for why an inherited `PI_*` knob is a refusal
+#   rather than a guess.
+#
+# omp_assembly_valid <asm-root> <unit-name>
+#   rc 0 = the assembly is a complete unit (entry + lib + registry + package.json with
+#   `type: module`); rc 1 with the first failing reason on stderr.
+#
+# omp_state_read <state_file> <unit_dir> <asm>
+#   Fail-closed EXACT-schema reader for the ownership state — one validator for all
+#   three surfaces. rc 0 prints `<unitVersion> <entryName>`; any missing/unknown key,
+#   wrong type, empty string, relative path or constant drift is rc 1.
+#
+# Deliberately BOUNDED: environment, structure, one state schema. Records, markers and
+# hook-log truth stay on the doctor's own axes.
+
+# The vendor's own agent-dir resolution, reproduced only as far as this lane needs.
+#
+# `[source]` omp reads `PI_CONFIG_DIR` (default `.omp`) and `PI_CODING_AGENT_DIR`
+# (`packages/utils/src/dirs.ts:23`, `:210`, `:358`), and selects a profile from
+# `OMP_PROFILE` first, `PI_PROFILE` second (`dirs.ts:57`, `:85-91`), which moves the
+# agent dir to `~/.omp/profiles/<name>/agent`.
+#
+# WHY A `PI_*` KNOB IS A REFUSAL AND NOT A LOOKUP (ledger M6). omp is a pi fork and kept
+# pi's env vocabulary, so those three variables now steer TWO harnesses: entwurf's own pi
+# rail sandboxes `PI_CODING_AGENT_DIR` (AGENTS.md Hard Rule 12) and omp reads the same
+# name. A value in the installing shell therefore does not say WHICH harness it is
+# addressing. Installing into a directory chosen by that guess is how an operator ends up
+# with a unit no live omp reads, or a unit written into the pi rail's sandbox. `OMP_PROFILE`
+# is omp's own name and is honoured; the pi-shaped names refuse, and `ENTWURF_OMP_AGENT_DIR`
+# is the explicit override every gate and smoke passes.
+omp_agent_dir() {
+	if [ -n "${ENTWURF_OMP_AGENT_DIR:-}" ]; then
+		python3 -c 'import os,sys;print(os.path.abspath(os.path.expanduser(sys.argv[1])))' "$ENTWURF_OMP_AGENT_DIR"
+		return 0
+	fi
+	if [ -n "${PI_CODING_AGENT_DIR:-}" ]; then
+		echo "PI_CODING_AGENT_DIR is set ($PI_CODING_AGENT_DIR). omp reads it too (utils/src/dirs.ts:358), so it does not say whether it is addressing omp or entwurf's pi rail — refusing to guess. Unset it, or pass ENTWURF_OMP_AGENT_DIR explicitly." >&2
+		return 1
+	fi
+	if [ -n "${PI_CONFIG_DIR:-}" ]; then
+		echo "PI_CONFIG_DIR is set ($PI_CONFIG_DIR). It renames omp's whole config root (utils/src/dirs.ts:23, :210) and is a pi-shaped name — refusing to guess. Unset it, or pass ENTWURF_OMP_AGENT_DIR explicitly." >&2
+		return 1
+	fi
+	if [ -n "${PI_PROFILE:-}" ] && [ -z "${OMP_PROFILE:-}" ]; then
+		echo "PI_PROFILE is set ($PI_PROFILE) with no OMP_PROFILE. omp falls back to it (utils/src/dirs.ts:85-91) but so does pi — refusing to guess which harness this profile addresses. Set OMP_PROFILE explicitly, or pass ENTWURF_OMP_AGENT_DIR." >&2
+		return 1
+	fi
+	local root="$HOME/.omp"
+	if [ -n "${OMP_PROFILE:-}" ]; then
+		case "$OMP_PROFILE" in
+			[a-z0-9]*)
+				case "$OMP_PROFILE" in
+					*[!a-z0-9._-]*)
+						echo "OMP_PROFILE '$OMP_PROFILE' is not a valid omp profile name (utils/src/dirs.ts PROFILE_NAME_RE)." >&2
+						return 1 ;;
+				esac
+				root="$HOME/.omp/profiles/$OMP_PROFILE" ;;
+			*)
+				echo "OMP_PROFILE '$OMP_PROFILE' is not a valid omp profile name (utils/src/dirs.ts PROFILE_NAME_RE)." >&2
+				return 1 ;;
+		esac
+	fi
+	printf '%s\n' "$root/agent"
+}
+
+omp_assembly_valid() {
+	local asm="$1" unit="$2"
+	local dir="$asm/$unit"
+	if [ ! -d "$dir" ]; then
+		echo "assembly has no unit directory: $dir" >&2
+		return 1
+	fi
+	local entry=""
+	if [ -f "$dir/index.ts" ]; then entry="index.ts"; elif [ -f "$dir/index.js" ]; then entry="index.js"; fi
+	if [ -z "$entry" ]; then
+		echo "assembly has no index.ts/index.js entry: $dir (omp discovers a subdirectory extension by that name, discovery/helpers.ts:700-710)" >&2
+		return 1
+	fi
+	local libext="ts"
+	[ "$entry" = "index.js" ] && libext="js"
+	for required in "package.json" "entwurf-capabilities.json" "lib/meta-session.$libext" "lib/session-id.js"; do
+		if [ ! -f "$dir/$required" ]; then
+			echo "assembly is missing $required: $dir/$required" >&2
+			return 1
+		fi
+	done
+	# `type: module` is not cosmetic on the installed-package shape: an ESM `index.js`
+	# under a directory with no nearest package.json type field is read as CommonJS.
+	if ! DIR_ENV="$dir" python3 - <<'PY'
+import json, os, sys
+pkg = json.load(open(os.path.join(os.environ["DIR_ENV"], "package.json")))
+if pkg.get("type") != "module":
+    print(f"assembly package.json type is {pkg.get('type')!r}, want the literal \"module\"", file=sys.stderr)
+    sys.exit(1)
+if not isinstance(pkg.get("version"), str) or not pkg["version"]:
+    print("assembly package.json has no non-empty version", file=sys.stderr)
+    sys.exit(1)
+PY
+	then
+		return 1
+	fi
+	return 0
+}
+
+omp_state_read() {
+	local state_file="$1" unit_dir="$2" asm="$3"
+	STATE_FILE_ENV="$state_file" UNIT_DIR_ENV="$unit_dir" ASM_ENV="$asm" python3 - <<'PY'
+import json, os, sys
+try:
+    state = json.load(open(os.environ["STATE_FILE_ENV"]))
+except (OSError, json.JSONDecodeError) as err:
+    print(f"state parse failed: {err}", file=sys.stderr)
+    sys.exit(1)
+EXACT_KEYS = {"schemaVersion", "unitDir", "assemblyPath", "unitVersion", "entryName", "ownedUnitDir", "installedAt"}
+if not isinstance(state, dict) or set(state) != EXACT_KEYS:
+    got = sorted(state) if isinstance(state, dict) else type(state).__name__
+    print(f"state keyset drifted: {got} != {sorted(EXACT_KEYS)}", file=sys.stderr)
+    sys.exit(1)
+if state["schemaVersion"] != 1:
+    print(f"state schemaVersion is {state['schemaVersion']!r}, want the literal 1", file=sys.stderr)
+    sys.exit(1)
+for key in ("unitDir", "assemblyPath", "unitVersion", "entryName", "installedAt"):
+    if not isinstance(state[key], str) or not state[key]:
+        print(f"state {key} must be a nonempty string, got {state[key]!r}", file=sys.stderr)
+        sys.exit(1)
+if any(ord(c) < 0x21 or ord(c) == 0x7f for c in state["unitVersion"]):
+    print(f"state unitVersion contains whitespace/control characters: {state['unitVersion']!r} — "
+          "the space-separated fact transport would truncate it into a fabricated version", file=sys.stderr)
+    sys.exit(1)
+if state["entryName"] not in ("index.ts", "index.js"):
+    print(f"state entryName is {state['entryName']!r}, want index.ts or index.js", file=sys.stderr)
+    sys.exit(1)
+if not isinstance(state["ownedUnitDir"], bool):
+    print(f"state ownedUnitDir must be a boolean, got {state['ownedUnitDir']!r} — flags are never coerced", file=sys.stderr)
+    sys.exit(1)
+for key, want in (("unitDir", os.environ["UNIT_DIR_ENV"]), ("assemblyPath", os.environ["ASM_ENV"])):
+    if not os.path.isabs(state[key]):
+        print(f"state {key} is not absolute: {state[key]!r}", file=sys.stderr)
+        sys.exit(1)
+    if os.path.abspath(state[key]) != os.path.abspath(want):
+        print(f"state {key} names {state[key]!r}, not this installation's {want!r}", file=sys.stderr)
+        sys.exit(1)
+print(f"{state['unitVersion']} {state['entryName']}")
+PY
+}

package/scripts/omp-bridge-uninstall.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# omp-bridge-uninstall.sh — the honest inverse of install-omp-bridge (#87).
+#
+# HONEST means: remove exactly what the ownership state says this repo installed, and
+# nothing else. No `--force`, no "clean up anything that looks like ours", no removal of
+# a unit directory we cannot prove we placed. A no-state host is NOT an empty host: it is
+# a host whose ownership we cannot establish, so the answer is a named refusal.
+#
+# The state is deleted LAST, so an interrupted inverse leaves the authority to retry.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+UNIT="entwurf-meta-omp"
+ASM="${ENTWURF_OMP_ASM:-${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/meta-bridge-omp/.assembled}"
+STATE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/omp-bridge"
+STATE_FILE="$STATE_DIR/install-state.json"
+
+die() { echo "[omp-bridge-uninstall] $*" >&2; exit 1; }
+
+# shellcheck source=scripts/omp-bridge-oracle.sh
+. "$HERE/omp-bridge-oracle.sh"
+
+AGENT_DIR="$(omp_agent_dir)" || die "refusing: the omp agent directory this host reads is ambiguous (see above)."
+UNIT_DIR="$AGENT_DIR/extensions/$UNIT"
+
+[ -L "$STATE_FILE" ] && die "ownership state $STATE_FILE is a symlink — refusing to trust it."
+if [ ! -f "$STATE_FILE" ]; then
+  die "no ownership state at $STATE_FILE, so nothing here is provably ours. Refusing with zero writes — if $UNIT_DIR is a stale hand-copied unit, remove it by hand."
+fi
+STATE_FACTS="$(omp_state_read "$STATE_FILE" "$UNIT_DIR" "$ASM")" \
+  || die "ownership state $STATE_FILE is corrupt or names a different installation (see above) — refusing with zero writes."
+STATE_ENTRY="${STATE_FACTS#* }"
+
+if [ -e "$UNIT_DIR" ]; then
+  if [ -L "$UNIT_DIR" ]; then
+    die "$UNIT_DIR is a SYMLINK — this installer never creates one, so it is not ours. Refusing; remove it by hand."
+  fi
+  if [ ! -f "$UNIT_DIR/$STATE_ENTRY" ]; then
+    die "$UNIT_DIR exists but does not carry the entry this install recorded ($STATE_ENTRY) — it is not provably the unit we placed. Refusing with zero writes."
+  fi
+  rm -rf "$UNIT_DIR"
+  echo "[omp-bridge-uninstall] removed the installed unit: $UNIT_DIR"
+else
+  echo "[omp-bridge-uninstall] the installed unit was already absent: $UNIT_DIR"
+fi
+
+if [ -d "$ASM" ]; then
+  rm -rf "$ASM"
+  echo "[omp-bridge-uninstall] removed the assembly: $ASM"
+fi
+
+rm -f "$STATE_FILE"
+rmdir "$STATE_DIR" 2>/dev/null || true
+echo "[omp-bridge-uninstall] ownership state removed: $STATE_FILE"
+echo "[omp-bridge-uninstall] DONE. Existing omp sessions keep the record they already"
+echo "minted — records are preserved, never deleted (AGENTS.md Hard Rule 8); what stops"
+echo "is any FUTURE birth. The MCP hand is a separate inverse: ./run.sh uninstall-omp-mcp"

package/scripts/omp-config-xdev.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""Write the ONE operator setting omp's tool hand requires: ``tools.xdev: false``.
+
+stdlib only. This is the WRITER half of the runtime cell ``omp-tool-surface.py``
+already reads and ``doctor-omp-mcp`` already judges. Until it existed the setting
+was documentation — `docs/setup-clean-host.md` §4b told the operator to hand-edit
+`config.yml`, and a host that skipped it looked green everywhere except the one
+place it mattered: the doorbell announced ``mcp__entwurf_bridge_entwurf_v`` while
+the vendor had wrapped every MCP tool behind ``xd://`` and the model could not
+call it (measured, omp 18.0.0).
+
+Ownership, in the same shape as every other entwurf writer:
+
+* The config file is the VENDOR's. We add exactly one key and we record exactly
+  what we added, so the inverse can take back our bytes and nothing else.
+* ``xdev: true`` written EXPLICITLY by the operator is a decision, not drift. We
+  refuse it by name instead of overwriting — setup reports a FAIL the operator
+  resolves, which is the honest branch when two authorities disagree.
+* A config we cannot parse is refused, never rewritten. A writer that edits a
+  file it cannot read is how a config gets corrupted.
+
+Exit codes: 0 ok · 2 nothing to do (uninstall, no state) · 3 refused (symlink) ·
+4 unreadable/invalid · 5 refused (operator's explicit xdev: true) · 6 refused
+(the file changed under us since install).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+import time
+
+STATE_SCHEMA = 1
+TRUE_WORDS = {"true", "yes", "on", "y"}
+FALSE_WORDS = {"false", "no", "off", "n"}
+
+
+def die(code: int, message: str) -> None:
+    sys.stderr.write(message.rstrip("\n") + "\n")
+    raise SystemExit(code)
+
+
+def sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def strip_comment(raw: str) -> str:
+    """Drop a trailing `#` comment outside quotes — the reader's rule, kept in sync."""
+    in_single = in_double = escaped = False
+    for index, char in enumerate(raw):
+        if escaped:
+            escaped = False
+            continue
+        if char == "\\" and in_double:
+            escaped = True
+            continue
+        if char == "'" and not in_double:
+            in_single = not in_single
+            continue
+        if char == '"' and not in_single:
+            in_double = not in_double
+            continue
+        if char == "#" and not in_single and not in_double:
+            return raw[:index].rstrip()
+    return raw.rstrip()
+
+
+def indent_of(line: str) -> int:
+    body = strip_comment(line)
+    return len(body) - len(body.lstrip(" "))
+
+
+def split_key(line: str) -> str | None:
+    """The key of a `key: value` line, or None when the line is not a mapping entry."""
+    body = strip_comment(line).strip()
+    if not body or body.startswith("- ") or body.startswith("#"):
+        return None
+    in_single = in_double = False
+    for index, char in enumerate(body):
+        if char == "'" and not in_double:
+            in_single = not in_single
+            continue
+        if char == '"' and not in_single:
+            in_double = not in_double
+            continue
+        if char == ":" and not in_single and not in_double:
+            key = body[:index].strip()
+            if (len(key) >= 2) and (key[0] == key[-1] == '"' or key[0] == key[-1] == "'"):
+                key = key[1:-1]
+            return key or None
+    return None
+
+
+def value_of(line: str) -> str:
+    body = strip_comment(line).strip()
+    _, _, rest = body.partition(":")
+    return rest.strip()
+
+
+def scalar_bool(raw: str) -> bool | None:
+    text = raw.strip()
+    if (len(text) >= 2) and (text[0] == text[-1] == '"' or text[0] == text[-1] == "'"):
+        text = text[1:-1]
+    folded = text.casefold()
+    if folded in TRUE_WORDS:
+        return True
+    if folded in FALSE_WORDS:
+        return False
+    return None
+
+
+def find_tools_block(lines: list[str]) -> tuple[int, int, int] | None:
+    """(header index, first child index, child indent) for the TOP-LEVEL `tools:` key."""
+    for index, line in enumerate(lines):
+        if not strip_comment(line).strip():
+            continue
+        if indent_of(line) != 0:
+            continue
+        if split_key(line) != "tools":
+            continue
+        end = index + 1
+        child_indent = -1
+        while end < len(lines):
+            if not strip_comment(lines[end]).strip():
+                end += 1
+                continue
+            if indent_of(lines[end]) == 0:
+                break
+            if child_indent < 0:
+                child_indent = indent_of(lines[end])
+            end += 1
+        return index, end, (child_indent if child_indent > 0 else 2)
+    return None
+
+
+def read_config(path: str) -> list[str]:
+    with open(path, "r", encoding="utf-8") as handle:
+        return handle.read().splitlines()
+
+
+def write_config(path: str, lines: list[str]) -> str:
+    text = "\n".join(lines) + "\n"
+    parent = os.path.dirname(path) or "."
+    os.makedirs(parent, exist_ok=True)
+    tmp = f"{path}.entwurf-tmp"
+    with open(tmp, "w", encoding="utf-8") as handle:
+        handle.write(text)
+    os.replace(tmp, path)
+    return text
+
+
+def write_state(state_file: str, payload: dict[str, object]) -> None:
+    os.makedirs(os.path.dirname(state_file) or ".", exist_ok=True)
+    tmp = f"{state_file}.tmp"
+    with open(tmp, "w", encoding="utf-8") as handle:
+        json.dump(payload, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+    os.replace(tmp, state_file)
+
+
+def do_install(config_path: str, state_file: str) -> None:
+    if os.path.islink(config_path):
+        die(3, f"refusing: {config_path} is a symlink — entwurf never writes through a link")
+    existed = os.path.exists(config_path)
+    if existed and not os.path.isfile(config_path):
+        die(4, f"refusing: {config_path} exists and is not a regular file")
+
+    lines = read_config(config_path) if existed else []
+    block = find_tools_block(lines)
+    inserted: list[str] = []
+    action: str
+
+    if block is None:
+        # No `tools:` at all — append the whole two-line section. The vendor's own
+        # writer emits `key: ` with a trailing space, so the file stays uniform.
+        if lines and strip_comment(lines[-1]).strip() == "":
+            lines = lines[:-1]
+        inserted = ["tools: ", "  xdev: false"]
+        lines.extend(inserted)
+        action = "created-file" if not existed else "appended-tools-block"
+    else:
+        header, end, child_indent = block
+        existing = None
+        for index in range(header + 1, end):
+            if indent_of(lines[index]) == child_indent and split_key(lines[index]) == "xdev":
+                existing = index
+                break
+        if existing is not None:
+            current = scalar_bool(value_of(lines[existing]))
+            if current is False:
+                write_state(
+                    state_file,
+                    {
+                        "schemaVersion": STATE_SCHEMA,
+                        "configPath": os.path.abspath(config_path),
+                        "fileExistedBefore": True,
+                        "action": "already-false",
+                        "insertedLines": [],
+                        "postimageSha256": sha256("\n".join(lines) + "\n"),
+                        "installedAt": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+                    },
+                )
+                print(f"already-set {config_path} (tools.xdev is false — nothing written)")
+                return
+            if current is True:
+                die(
+                    5,
+                    f"refusing: {config_path} sets tools.xdev: true EXPLICITLY (line {existing + 1}). "
+                    "That is the operator's decision, not drift, so entwurf will not overwrite it. "
+                    "Entwurf's MCP tools are unreachable from omp while xdev is on and no "
+                    "xdevInlineDevices glob covers them — set it to false yourself, or accept that "
+                    "the omp citizen cannot call entwurf tools.",
+                )
+            die(4, f"refusing: {config_path} line {existing + 1} sets tools.xdev to a value this reader cannot classify")
+        inserted = [" " * child_indent + "xdev: false"]
+        lines[end:end] = inserted
+        action = "inserted-xdev-key"
+
+    text = write_config(config_path, lines)
+    write_state(
+        state_file,
+        {
+            "schemaVersion": STATE_SCHEMA,
+            "configPath": os.path.abspath(config_path),
+            "fileExistedBefore": existed,
+            "action": action,
+            "insertedLines": inserted,
+            "postimageSha256": sha256(text),
+            "installedAt": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        },
+    )
+    print(f"{action} {config_path} (tools.xdev: false)")
+
+
+def do_uninstall(state_file: str) -> None:
+    if not os.path.exists(state_file):
+        die(2, f"no install-state at {state_file} — entwurf never wrote this setting on this host")
+    try:
+        with open(state_file, "r", encoding="utf-8") as handle:
+            state = json.load(handle)
+    except (OSError, ValueError):
+        die(4, f"install-state at {state_file} is unreadable — refusing to guess what to take back")
+    if not isinstance(state, dict) or state.get("schemaVersion") != STATE_SCHEMA:
+        die(4, f"install-state at {state_file} is not schemaVersion {STATE_SCHEMA} — refusing")
+
+    config_path = state.get("configPath")
+    action = state.get("action")
+    inserted = state.get("insertedLines")
+    if not isinstance(config_path, str) or not isinstance(inserted, list):
+        die(4, f"install-state at {state_file} is malformed — refusing")
+
+    if action == "already-false":
+        os.remove(state_file)
+        print(f"nothing to take back ({config_path} already had tools.xdev: false); state cleared")
+        return
+
+    if os.path.islink(config_path):
+        die(3, f"refusing: {config_path} is now a symlink — entwurf never writes through a link")
+    if not os.path.exists(config_path):
+        os.remove(state_file)
+        print(f"{config_path} is already gone; state cleared")
+        return
+
+    with open(config_path, "r", encoding="utf-8") as handle:
+        current = handle.read()
+    if sha256(current) != state.get("postimageSha256"):
+        die(
+            6,
+            f"refusing: {config_path} changed since entwurf wrote it. Remove the tools.xdev line "
+            "yourself if you want it gone — a blind edit here would take back somebody else's bytes.",
+        )
+
+    if action == "created-file":
+        os.remove(config_path)
+        os.remove(state_file)
+        print(f"removed {config_path} (entwurf created it); state cleared")
+        return
+
+    lines = current.splitlines()
+    for line in reversed(inserted):
+        if line in lines:
+            lines.remove(line)
+        else:
+            die(6, f"refusing: the line {line!r} entwurf added is no longer in {config_path}")
+    write_config(config_path, lines)
+    os.remove(state_file)
+    print(f"took back {len(inserted)} line(s) from {config_path}; state cleared")
+
+
+def main(argv: list[str]) -> None:
+    if len(argv) < 2:
+        die(5, "usage: omp-config-xdev.py install <config-path> <state-file> | uninstall <state-file>")
+    verb = argv[1]
+    if verb == "install":
+        if len(argv) != 4:
+            die(5, "usage: omp-config-xdev.py install <config-path> <state-file>")
+        do_install(argv[2], argv[3])
+        return
+    if verb == "uninstall":
+        if len(argv) != 3:
+            die(5, "usage: omp-config-xdev.py uninstall <state-file>")
+        do_uninstall(argv[2])
+        return
+    die(5, f"unknown verb {verb!r} — install | uninstall")
+
+
+if __name__ == "__main__":
+    main(sys.argv)

package/scripts/omp-config-xdev.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# OMP operator-setting adapter (`tools.xdev: false`) — the WRITER for the runtime cell
+# `doctor-omp-mcp` already judges and `omp-tool-surface.py` already reads.
+#
+# Separate surface from the MCP hand on purpose: registering the server is TOOLS, and
+# `tools.xdev` decides whether those registered tools are REACHABLE at all. omp's default
+# (`xdev: true`, no inline allowlist) wraps every MCP tool behind `xd://`, so a host with a
+# perfect mcp.json still announces a doorbell tool the model cannot call. Until this adapter
+# existed the fix was a documented hand-edit, which is exactly the kind of step a one-command
+# setup is supposed to end.
+#
+# Target confinement follows the MCP hand's rule (#87 D1): the file is exactly
+# `<resolved omp agent dir>/config.yml`, never a configurable path. `ENTWURF_OMP_AGENT_DIR`
+# moves the agent dir and the target follows by construction.
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CONFIG_PY="$HERE/omp-config-xdev.py"
+STATE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/omp-config"
+STATE_FILE="$STATE_DIR/install-state.json"
+
+log() { printf '%s\n' "$*"; }
+fail() { printf 'FAIL: %s\n' "$*" >&2; exit 1; }
+
+# shellcheck source=scripts/omp-bridge-oracle.sh
+. "$HERE/omp-bridge-oracle.sh"
+
+AGENT_DIR="$(omp_agent_dir)" || fail "the omp agent directory this host reads is ambiguous (see above) — refusing to write a config file omp may never read."
+CONFIG="$AGENT_DIR/config.yml"
+
+do_install() {
+	log "[omp-config install]"
+	log "  target:  $CONFIG"
+	log "  setting: tools.xdev: false"
+	log "  state:   $STATE_FILE"
+	local out rc
+	set +e
+	out="$(python3 "$CONFIG_PY" install "$CONFIG" "$STATE_FILE" 2>&1)"
+	rc=$?
+	set -e
+	case "$rc" in
+		0) log "  ok: $out" ;;
+		3) fail "refused (symlink) — $out" ;;
+		4) fail "unreadable config — $out" ;;
+		5) fail "refused (the operator set tools.xdev: true explicitly) — $out" ;;
+		*) fail "install error (rc=$rc) — $out" ;;
+	esac
+	log "  installed. The runtime axis is verified by: ./run.sh doctor-omp-mcp"
+	log "  NOTE: an omp session that is ALREADY OPEN keeps the tool surface it started with;"
+	log "  restart it for the top-level tools to appear."
+}
+
+do_uninstall() {
+	log "[omp-config uninstall]"
+	local out rc
+	set +e
+	out="$(python3 "$CONFIG_PY" uninstall "$STATE_FILE" 2>&1)"
+	rc=$?
+	set -e
+	case "$rc" in
+		0) log "  ok: $out" ;;
+		2) log "  note: $out" ;;
+		3) fail "refused (symlink) — $out" ;;
+		4) fail "invalid state — $out" ;;
+		6) fail "refused (the config changed since install) — $out" ;;
+		*) fail "uninstall error (rc=$rc) — $out" ;;
+	esac
+}
+
+case "${1:-}" in
+	install) do_install ;;
+	uninstall) do_uninstall ;;
+	*)
+		echo "usage: omp-config-xdev.sh install | uninstall" >&2
+		exit 2
+		;;
+esac