@junghanacs/entwurf 0.14.2 → 0.15.1

package/scripts/copilot-bridge-uninstall.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# copilot-bridge-uninstall.sh — the package-owned INVERSE of copilot-bridge-install.sh
+# (#86 C3a). Removes exactly what the ownership state records this package installed —
+# the qualified plugin, the local marketplace registration, the assembly — and nothing
+# else. The stale Claude unit is INSTALL-ONLY territory; this inverse never touches it.
+#
+# ORDER AND AUTHORITY (amendment: the ownership preflight is COMPLETE before any vendor
+# mutation). The state is required and validated fail-closed against this package's
+# constants and the effective assembly path; both vendor lists are read next and a
+# failing list is UNKNOWN (an unknown host is not an empty one — refuse); then EVERY
+# ownership and safety fact — marketplace name/path/recorded ownership, assembly path
+# safety, exact plugin row presence — is decided read-only. Only after all of it passes
+# may the first vendor write run. So a refusal, any refusal, is zero vendor/filesystem
+# writes with the state retained. Vendor steps run before filesystem steps, the state
+# is deleted LAST, and any failure stops with the state retained so a rerun can finish
+# the job. `--force` is forbidden: `marketplace remove --force` uninstalls that
+# marketplace's plugins as a side effect (measured 2026-08-27).
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MKT_NAME="meta-bridge-copilot-local"
+PLUGIN="entwurf-meta-receive-copilot"
+QUALIFIED="$PLUGIN@$MKT_NAME"
+ASM="${ENTWURF_COPILOT_ASM:-${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/meta-bridge-copilot/.assembled}"
+STATE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/copilot-bridge"
+STATE_FILE="$STATE_DIR/install-state.json"
+
+die() { echo "[copilot-bridge-uninstall] $*" >&2; exit 1; }
+
+[ $# -eq 0 ] || die "unknown argument: $1 (this inverse takes no arguments; --force does not exist here)"
+command -v copilot >/dev/null 2>&1 || die "the 'copilot' CLI is not on PATH."
+command -v python3 >/dev/null 2>&1 || die "python3 is required and is not on PATH."
+
+# shellcheck source=copilot-bridge-oracle.sh
+. "$HERE/copilot-bridge-oracle.sh"
+
+# --- 1. the ownership state is the sole removal authority --------------------
+[ -L "$STATE_FILE" ] && die "ownership state $STATE_FILE is a symlink — refusing to trust it."
+[ -f "$STATE_FILE" ] || die "no ownership state at $STATE_FILE — nothing this package provably owns to remove. A legacy no-state installation is adopted by './run.sh install-copilot-bridge' first, then removed."
+STATE_FACTS="$(copilot_state_read "$STATE_FILE" "$QUALIFIED" "$MKT_NAME" "$ASM")" \
+  || die "ownership state $STATE_FILE is corrupt or names a different installation (see above) — refusing with zero vendor/filesystem writes."
+OWNED_MKT="$(printf '%s' "$STATE_FACTS" | cut -d' ' -f1)"
+OWNED_ASM="$(printf '%s' "$STATE_FACTS" | cut -d' ' -f2)"
+STATE_PLUGIN_VERSION="$(printf '%s' "$STATE_FACTS" | cut -d' ' -f3)"
+
+# --- 2. read-only vendor facts (a failing list is UNKNOWN, never absence) ----
+if ! INSTALLED_LIST="$(copilot plugin list 2>/dev/null)"; then
+  die "'copilot plugin list' failed, so this host's installed plugins are UNKNOWN — refusing with zero writes. Fix the Copilot CLI error and re-run."
+fi
+if ! MKT_LIST="$(copilot plugin marketplace list 2>/dev/null)"; then
+  die "'copilot plugin marketplace list' failed, so this host's marketplaces are UNKNOWN — refusing with zero writes. Fix the Copilot CLI error and re-run."
+fi
+
+# --- 3. COMPLETE ownership/safety preflight, read-only, before ANY mutation --
+# 3a. the marketplace half: exact name must sit at the recorded path AND be recorded
+#     as ours. Refusing HERE — before the plugin uninstall — is the amendment's point:
+#     the same qualified id could have been installed from a same-named marketplace at
+#     another path, and an inverse that had already uninstalled the plugin would have
+#     removed someone else's unit before discovering that.
+MKT_PRESENT=0
+# ONE marketplace-row grammar (C3a amendment, B defects 1+2): the shared oracle
+# refuses malformed/non-Local rows and DUPLICATE same-named rows instead of silently
+# acting on the first — an inverse steered at the wrong same-named marketplace would
+# remove a registration it cannot attribute.
+MKT_ROW="$(copilot_marketplace_local_path "$MKT_LIST" "$MKT_NAME")" \
+  || die "the 'copilot plugin marketplace list' rows for '$MKT_NAME' are malformed, non-Local, or duplicated (see above) — refusing with zero vendor/filesystem writes."
+if [ "$MKT_ROW" != "absent" ]; then
+  MKT_PRESENT=1
+  MKT_PATH="${MKT_ROW#one }"
+  if [ "$MKT_PATH" != "$ASM" ]; then
+    die "a marketplace named '$MKT_NAME' is registered at '$MKT_PATH', not at the recorded assembly ($ASM). That registration is not provably ours — refusing with zero vendor/filesystem writes; inspect 'copilot plugin marketplace list' manually."
+  fi
+  if [ "$OWNED_MKT" != "true" ]; then
+    die "marketplace '$MKT_NAME' is registered at our recorded path, but the ownership state does not record marketplace ownership. Completing this inverse would leave a registered marketplace pointing at removed backing — refusing with zero vendor/filesystem writes (plugin, marketplace, assembly and state all preserved). Resolve the marketplace registration manually, or re-run './run.sh install-copilot-bridge' to re-bind ownership."
+  fi
+fi
+# 3b. assembly delete safety, decided BEFORE any vendor write: the recorded path must
+#     be a sane rm target or nothing at all may start.
+if [ "$OWNED_ASM" = "true" ]; then
+  case "$ASM" in
+    /) die "recorded assembly path is '/' — refusing everything." ;;
+    /*) : ;;
+    *) die "recorded assembly path is not absolute: $ASM — refusing everything." ;;
+  esac
+  [ -L "$ASM" ] && die "recorded assembly path $ASM is a symlink — refusing everything; the inverse removes only the real recorded directory."
+  if [ -e "$ASM" ] && [ ! -d "$ASM" ]; then
+    die "recorded assembly path $ASM exists but is not a directory — refusing everything."
+  fi
+fi
+# 3c. the plugin half (final amendment): the exact QUALIFIED must be ABSENT (a previous
+#     run got that far — retry-safe) or present EXACTLY ONCE at the state's recorded
+#     version. A different version is `version-drift` — something other than the
+#     recorded install put it there, and this inverse must not remove what it cannot
+#     prove it installed. Malformed/multiple exact rows refuse too. Longer tokens that
+#     merely contain the qualified id remain foreign, same as everywhere.
+PLUGIN_PRESENT=0
+LISTED_ROW="$(copilot_exact_row_version "$INSTALLED_LIST" "$QUALIFIED")" \
+  || die "the 'copilot plugin list' rows for $QUALIFIED are malformed or ambiguous (see above) — refusing with zero vendor/filesystem writes."
+case "$LISTED_ROW" in
+  absent) : ;;
+  "one $STATE_PLUGIN_VERSION") PLUGIN_PRESENT=1 ;;
+  one\ *)
+    die "version-drift: $QUALIFIED is listed at ${LISTED_ROW#one }, but the ownership state recorded v$STATE_PLUGIN_VERSION. This inverse removes only what it provably installed — refusing with zero vendor/filesystem writes (plugin, marketplace, assembly and state all preserved). Re-run './run.sh install-copilot-bridge' to re-bind ownership, then remove." ;;
+  *) die "unexpected exact-row verdict '$LISTED_ROW' — refusing with zero writes." ;;
+esac
+
+# --- 4. vendor mutation (licensed by the complete preflight above) -----------
+if [ "$PLUGIN_PRESENT" -eq 1 ]; then
+  copilot plugin uninstall "$QUALIFIED" >/dev/null \
+    || die "'copilot plugin uninstall $QUALIFIED' failed — stopping with the state retained; re-run to finish."
+  echo "[copilot-bridge-uninstall] uninstalled $QUALIFIED"
+else
+  echo "[copilot-bridge-uninstall] $QUALIFIED (v$STATE_PLUGIN_VERSION) is already absent from 'copilot plugin list' (a previous run got this far) — continuing"
+fi
+if [ "$MKT_PRESENT" -eq 1 ]; then
+  copilot plugin marketplace remove "$MKT_NAME" >/dev/null \
+    || die "'copilot plugin marketplace remove $MKT_NAME' failed (never retried with --force) — stopping with the state retained; re-run to finish."
+  echo "[copilot-bridge-uninstall] removed marketplace $MKT_NAME"
+else
+  echo "[copilot-bridge-uninstall] marketplace $MKT_NAME is already absent (a previous run got this far) — continuing"
+fi
+
+# --- 5. the assembly: only the recorded directory, only when owned -----------
+if [ "$OWNED_ASM" = "true" ]; then
+  if [ -d "$ASM" ]; then
+    rm -rf "$ASM"
+    echo "[copilot-bridge-uninstall] removed assembly $ASM"
+  else
+    echo "[copilot-bridge-uninstall] assembly already absent at $ASM (a previous run got this far) — continuing"
+  fi
+else
+  echo "[copilot-bridge-uninstall] state does not record assembly ownership — preserving $ASM"
+fi
+
+# --- 6. the state, LAST ------------------------------------------------------
+rm -f "$STATE_FILE"
+echo "[copilot-bridge-uninstall] DONE — ownership state cleared ($STATE_FILE). The stale Claude unit, if any, was deliberately not touched (install-only territory)."

package/scripts/copilot-launch.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# copilot-launch.sh — the managed Copilot launch, `entwurf copilot` (#82 RAIL 7).
+#
+# WHY THIS EXISTS. The receiver installer owns the extension artifact but it cannot
+# arm anything by itself: Copilot scans for extensions only when the CLI is started
+# with `COPILOT_CLI_ENABLED_FEATURE_FLAGS=EXTENSIONS`, and that lives in the
+# environment of the operator's own launch. Without it the scan is skipped SILENTLY —
+# no error, no log line, no receiver — so a perfectly installed unit stays inert and
+# the citizen never becomes deliverable. entwurf does not own the operator's shell,
+# and it will not write their rc files. What it can own is ONE invocation: this leaf
+# sets the flag for the process it is about to become, and nothing outside it.
+#
+# WHAT IT IS NOT. It is not a launcher rail. It does not place a tmux window, it is
+# not fresh-call, and it mints NO citizen: birth authority stays exactly where it was,
+# on the Copilot session's FIRST PROMPT (Hard Rule 2 — the record is the sole garden
+# address authority, and nothing here writes a record). It `exec`s in the caller's own
+# terminal, so cwd, tty, pid and exit status are the vendor's, unchanged.
+#
+# CONSENT. Calling `entwurf copilot` IS the consent to the managed profile: EXTENSIONS
+# on, `--model auto` when no model was given, and `--yolo` when no explicit permission
+# or surface policy was given. An operator who wants the plain vendor behaviour keeps
+# running `copilot` directly — that path is untouched and is not deprecated.
+#
+# FAIL-CLOSED SCAN. The argv scan is element-wise and deliberately naive: it does not
+# model which options consume the next word. Both of its possible mistakes are safe.
+# Reading an option's VALUE as a policy token suppresses an injected default; reading
+# it as a model suppresses `--model auto`. Every error direction is "inject less",
+# never "widen the operator's permissions behind their back".
+#
+# PRECONDITION SCOPE, deliberately unchanged by #82 RAIL 9. This launcher guards the
+# RECEIVER and nothing else, because that is the promise the EXTENSIONS flag makes. The
+# fresh-call lane needs more than that (birth, MCP hand, receiver AND visible footer), but
+# those belong to `pi-extensions/lib/copilot-fresh-preflight.ts`, which decides them BEFORE
+# tmux opens a window. A refusal here necessarily happens inside a window that already
+# exists, so widening this list would only turn a clean pre-mutation refusal into a dead
+# window plus a launch receipt for a sibling that never was. The manual `entwurf copilot`
+# contract stays receive-only.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$HERE/.." && pwd)"
+
+UNIT="entwurf-receive"
+EXT_ROOT="${COPILOT_EXTENSIONS_DIR:-$HOME/.copilot/extensions}"
+DEST="$EXT_ROOT/$UNIT"
+STATE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/copilot-receive"
+STATE_FILE="$STATE_DIR/install-state.json"
+FLAG_ENV="COPILOT_CLI_ENABLED_FEATURE_FLAGS"
+FLAG_VALUE="EXTENSIONS"
+REPAIR="entwurf install-copilot-receive"
+
+# The vendor command this leaf manages. A CONSTANT, and deliberately not overridable:
+# an env seam here would be a production switch for "which binary is the Copilot CLI",
+# and anything that can redirect an exec is an authority, not a test convenience. The
+# gate proves the real contract instead — it puts its fake vendor on a sandbox PATH under
+# this exact name and drives the public address.
+VENDOR_CMD="copilot"
+
+fail() { printf 'FAIL: %s\n' "$*" >&2; exit 1; }
+
+# --- recursion fence -------------------------------------------------------
+# A `copilot` earlier on PATH that itself calls `entwurf copilot` would spin forever,
+# and the symptom would be a hung terminal rather than an error. One sentinel closes
+# it: the flag is invocation-local, so seeing it already set means we are inside our
+# own exec chain.
+if [ -n "${ENTWURF_COPILOT_LAUNCH_ACTIVE:-}" ]; then
+	fail "recursive managed launch detected (ENTWURF_COPILOT_LAUNCH_ACTIVE is already set).
+  Something on PATH named '$VENDOR_CMD' resolves back to this launcher. Fix PATH so
+  '$VENDOR_CMD' is the GitHub Copilot CLI, or run the vendor binary by its full path."
+fi
+
+# --- precondition: the receiver this launch promises to arm -----------------
+# The flag is a PROMISE of a doorbell. Setting it while no receiver unit is installed
+# would produce a session that looks managed and can never be delivered to, which is
+# the exact false-success this repo refuses. Every failure below names the one command
+# that repairs it.
+[ -f "$STATE_FILE" ] \
+	|| fail "no receiver install-state at $STATE_FILE.
+  '$VENDOR_CMD' launched with $FLAG_ENV=$FLAG_VALUE would scan for an extension that is
+  not there, and the session would never become deliverable. Run: $REPAIR"
+
+claimed_path=""
+claimed_unit=""
+if ! claimed_path="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("path",""))' "$STATE_FILE" 2>/dev/null)"; then
+	fail "receiver install-state at $STATE_FILE is not readable JSON — refusing to launch on a
+  state file we cannot verify. Run: $REPAIR"
+fi
+claimed_unit="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("unit",""))' "$STATE_FILE" 2>/dev/null || true)"
+
+[ -n "$claimed_path" ] \
+	|| fail "receiver install-state at $STATE_FILE names no path. Run: $REPAIR"
+[ "$claimed_unit" = "$UNIT" ] \
+	|| fail "receiver install-state at $STATE_FILE claims unit '${claimed_unit:-<empty>}', expected '$UNIT'. Run: $REPAIR"
+# Path mismatch is its own failure, not a missing file: it means the state file and the
+# directory this launch would arm from disagree, and the extensions root the CLI will
+# actually scan is $EXT_ROOT.
+[ "$claimed_path" = "$DEST" ] \
+	|| fail "receiver install-state points at '$claimed_path' but this environment scans '$DEST'.
+  The CLI would read a different extensions root than the one that was installed
+  (COPILOT_EXTENSIONS_DIR / HOME differ from install time). Run: $REPAIR"
+[ -d "$claimed_path" ] \
+	|| fail "receiver unit directory '$claimed_path' is missing. Run: $REPAIR"
+[ -f "$claimed_path/extension.mjs" ] \
+	|| fail "receiver unit at '$claimed_path' holds no extension.mjs — it is not our unit any more. Run: $REPAIR"
+
+# --- resolve the vendor executable -----------------------------------------
+# `type -P` returns the PATH hit only — never a shell function, alias or builtin — so
+# what is exec'd is a real external file. `exec command copilot` is deliberately NOT
+# used: it would re-enter shell lookup at exec time and could pick up something other
+# than the file that was validated here.
+copilot_bin="$(type -P "$VENDOR_CMD" 2>/dev/null || true)"
+[ -n "$copilot_bin" ] \
+	|| fail "no '$VENDOR_CMD' executable found on PATH.
+  The managed launch runs the GitHub Copilot CLI; install it, or put it on PATH."
+[ -f "$copilot_bin" ] && [ -x "$copilot_bin" ] \
+	|| fail "'$copilot_bin' is not an executable regular file — refusing to exec it."
+
+# Self-exec fence, the second half of the recursion guard: resolve symlinks and refuse
+# anything that is one of our own entrypoints even if the sentinel was stripped.
+resolved_bin="$(readlink -f "$copilot_bin" 2>/dev/null || printf '%s' "$copilot_bin")"
+for own in "$HERE/copilot-launch.sh" "$REPO_DIR/run.sh"; do
+	own_resolved="$(readlink -f "$own" 2>/dev/null || printf '%s' "$own")"
+	[ "$resolved_bin" = "$own_resolved" ] \
+		&& fail "'$VENDOR_CMD' on PATH resolves to entwurf's own '$own_resolved' — that is a launch loop, not the vendor CLI."
+done
+
+# --- argv scan: everything BEFORE the first literal `--` --------------------
+# The terminator and everything after it belong to the user/vendor as data. We neither
+# read policy out of it nor inject into it: injected defaults go immediately BEFORE the
+# terminator so they remain options, and every original element crosses byte-identical.
+args=("$@")
+term_index=-1
+for i in "${!args[@]}"; do
+	if [ "${args[$i]}" = "--" ]; then
+		term_index="$i"
+		break
+	fi
+done
+scan_end=$(( term_index >= 0 ? term_index : ${#args[@]} ))
+
+# The explicit permission / surface policy overrides, measured against GitHub Copilot
+# CLI 1.0.80 `--help`. Two groups, one rule: if the operator named ANY of them before
+# the terminator, they have stated their own policy and we add none.
+#   authorization: --yolo, --allow-all{,-tools,-paths,-urls}, --allow-tool, --deny-tool,
+#                  --allow-url, --deny-url
+#   tool surface : --available-tools, --excluded-tools
+# Narrowing flags count too: appending `--yolo` (= all tools + paths + URLs) beside an
+# operator's `--allow-url=https://one.example` would silently widen exactly what they
+# were narrowing.
+# NOT overrides, deliberately: `--allow-all-mcp-server-instructions` is prompt content,
+# not authorization, and `--autopilot` is a mode. Matching is EXACT on the token head,
+# so neither is caught by the `--allow-all` entry that is a prefix of one of them.
+POLICY_OVERRIDES=(
+	--yolo
+	--allow-all
+	--allow-all-tools
+	--allow-all-paths
+	--allow-all-urls
+	--allow-tool
+	--deny-tool
+	--allow-url
+	--deny-url
+	--available-tools
+	--excluded-tools
+)
+
+has_model=0
+has_policy=0
+for (( i = 0; i < scan_end; i++ )); do
+	tok="${args[$i]}"
+	# `--opt=value` and `--opt value` are the same option; compare the head only.
+	head="${tok%%=*}"
+	if [ "$head" = "--model" ]; then
+		has_model=1
+	fi
+	for ov in "${POLICY_OVERRIDES[@]}"; do
+		if [ "$head" = "$ov" ]; then
+			has_policy=1
+			break
+		fi
+	done
+done
+
+injected=()
+[ "$has_model" -eq 0 ] && injected+=(--model auto)
+[ "$has_policy" -eq 0 ] && injected+=(--yolo)
+
+# Rebuild argv with the defaults before the terminator. Original elements are copied by
+# index, so empty strings, embedded spaces and post-terminator data all survive intact.
+final_args=()
+for (( i = 0; i < scan_end; i++ )); do final_args+=("${args[$i]}"); done
+if [ "${#injected[@]}" -gt 0 ]; then final_args+=("${injected[@]}"); fi
+for (( i = scan_end; i < ${#args[@]}; i++ )); do final_args+=("${args[$i]}"); done
+
+# --- the feature flag, invocation-local ------------------------------------
+# Preserve the operator's existing tokens and their order, drop empties, drop
+# duplicates, and guarantee EXTENSIONS is present exactly once. Nothing is written to
+# any config or rc file: this export reaches only the image this process becomes.
+flags_out=""
+seen_extensions=0
+if [ -n "${!FLAG_ENV:-}" ]; then
+	IFS=',' read -r -a existing <<< "${!FLAG_ENV}"
+	for tok in "${existing[@]}"; do
+		# Vendor tokens are comma-separated names; surrounding whitespace is noise, and an
+		# empty field (",," or a trailing comma) is not a token.
+		tok="${tok#"${tok%%[![:space:]]*}"}"
+		tok="${tok%"${tok##*[![:space:]]}"}"
+		[ -n "$tok" ] || continue
+		case ",$flags_out," in *",$tok,"*) continue ;; esac
+		[ "$tok" = "$FLAG_VALUE" ] && seen_extensions=1
+		flags_out="${flags_out:+$flags_out,}$tok"
+	done
+fi
+[ "$seen_extensions" -eq 1 ] || flags_out="${flags_out:+$flags_out,}$FLAG_VALUE"
+
+export "$FLAG_ENV=$flags_out"
+export ENTWURF_COPILOT_LAUNCH_ACTIVE=1
+
+# --- foreign identity carriers, removed before exec ------------------------
+# The MCP bridge trusts a COMPLETE `PI_SESSION_ID` + `PI_AGENT_ID` pair ahead of a native
+# sender marker when it resolves who is speaking. Inside the pi process that planted them
+# from record birth that is correct. In another harness they are somebody else's identity:
+# start Copilot from a pi citizen's bash and this session — plus every MCP child and
+# extension child that inherits from it — can speak under the PARENT pi garden id, and the
+# delivery layer will stamp envelopes with an address this session does not hold.
+#
+# Both go, together. Clearing one only changes the wording of the failure while leaving a
+# carrier for a future partial reader to pick up, so an incomplete pair is not a repair.
+# Nothing is substituted: identity for this session comes from its OWN trusted birth marker
+# on its first prompt, which is exactly where the record authority already lives.
+#
+# `unset` is unconditional on purpose. Branching on "was it set?" would only add a way to
+# be wrong; unsetting an absent variable is a no-op in every shell this runs on.
+unset PI_SESSION_ID PI_AGENT_ID
+
+exec "$copilot_bin" "${final_args[@]}"

package/scripts/copilot-mcp-bridge.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# Copilot MCP install adapter. Birth plugin and personal MCP stay separate.
+# Owns ONE mcpServers.entwurf-bridge key; file wrapper is always mcpServers.
+# Entry type is "local" (Copilot CLI writer), never "stdio".
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$HERE/.." && pwd)"
+CONFIG_PY="$HERE/copilot-mcp-config.py"
+CONFIG="${COPILOT_MCP_CONFIG:-$HOME/.copilot/mcp-config.json}"
+COMMAND="${COPILOT_MCP_COMMAND:-entwurf-bridge}"
+STATE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/copilot-mcp"
+STATE_FILE="$STATE_DIR/install-state.json"
+log() { printf '%s\n' "$*"; }
+fail() { printf 'FAIL: %s\n' "$*" >&2; exit 1; }
+command_resolvable() {
+  case "$1" in
+    */*) [ -x "$1" ] ;;
+    *) command -v "$1" >/dev/null 2>&1 ;;
+  esac
+}
+run_config() {
+  local out rc
+  set +e
+  out="$(python3 "$CONFIG_PY" "$@" 2>&1)"
+  rc=$?
+  set -e
+  printf '%s\n' "$out"
+  return "$rc"
+}
+BOOT_PROBED_INVOCATION=""
+BOOT_PROBED_RC=1
+BOOT_PROBED_OUT=""
+BOOT_DETAIL=""
+command_boots() {
+  local invocation="$1" out rc
+  if [ "$invocation" = "$BOOT_PROBED_INVOCATION" ]; then
+    BOOT_DETAIL="$BOOT_PROBED_OUT"
+    return "$BOOT_PROBED_RC"
+  fi
+  set +e
+  out="$("$REPO_DIR/run.sh" probe-bridge-command --invocation-json "$invocation" 2>&1)"
+  rc=$?
+  set -e
+  BOOT_PROBED_INVOCATION="$invocation"; BOOT_PROBED_RC="$rc"; BOOT_PROBED_OUT="$out"; BOOT_DETAIL="$out"
+  return "$rc"
+}
+do_install() {
+  log "[copilot-mcp install]"
+  log "  target:  $CONFIG"
+  log "  command: $COMMAND"
+  log "  state:   $STATE_FILE"
+  if ! command_resolvable "$COMMAND"; then
+    log "  note: '$COMMAND' is not currently resolvable; install records it and doctor stays red until it is on PATH"
+  fi
+  local out rc
+  set +e
+  out="$(run_config install "$CONFIG" "$COMMAND" "$STATE_FILE")"
+  rc=$?
+  set -e
+  case "$rc" in
+    0) log "  ok: $out" ;;
+    3) fail "refused (symlink) — $out" ;;
+    4) fail "invalid config/state — $out" ;;
+    *) fail "install error (rc=$rc) — $out" ;;
+  esac
+  log "  installed. Verify with: ./run.sh doctor-copilot-mcp"
+}
+do_uninstall() {
+  log "[copilot-mcp uninstall]"
+  local out rc
+  set +e
+  out="$(run_config uninstall "$STATE_FILE")"
+  rc=$?
+  set -e
+  case "$rc" in
+    0) log "  ok: $out" ;;
+    2) log "  note: $out" ;;
+    3) fail "refused (symlink) — $out" ;;
+    *) fail "uninstall error (rc=$rc) — $out" ;;
+  esac
+}
+state_target() {
+  python3 - "$STATE_FILE" <<'PY'
+import json, os, sys
+try:
+    state = json.load(open(sys.argv[1]))
+    required = ("serverKey", "command", "detectMode", "configExistedBefore", "preimage")
+    if state.get("schemaVersion") != 1 or any(key not in state for key in required): raise ValueError()
+    if state.get("serverKey") != "entwurf-bridge": raise ValueError()
+    value = state.get("managedConfigPath")
+    if not isinstance(value, str) or not os.path.isabs(value): raise ValueError()
+    print(os.path.abspath(value))
+except Exception:
+    raise SystemExit(1)
+PY
+}
+do_doctor() {
+  log "[copilot-mcp doctor]"
+  local hard_fail=0 status out rc installed=0
+  [ -f "$STATE_FILE" ] && installed=1
+  set +e
+  out="$(run_config doctor-static "$CONFIG" "$COMMAND")"
+  rc=$?
+  set -e
+  status="${out##*$'\n'}"
+  if [ "$rc" -ne 0 ]; then
+    log "  config: unexpected config reader failure (rc=$rc): $out"
+    if [ "$installed" -eq 1 ]; then hard_fail=1; fi
+  else
+    case "$status" in
+      configured\ *)
+        local invocation
+        if ! invocation="$(python3 "$CONFIG_PY" doctor-invocation "$CONFIG" "$COMMAND")"; then
+          log "  config: configured → '$COMMAND' but its exact invocation is unreadable"
+          [ "$installed" -eq 1 ] && hard_fail=1
+        elif command_boots "$invocation"; then
+          log "  config: configured → '$COMMAND' (the exact configured invocation boots the entwurf MCP surface)"
+        else
+          log "  config: configured → '$COMMAND' does NOT serve MCP with its configured args/env"
+          log "        $BOOT_DETAIL"
+          [ "$installed" -eq 1 ] && hard_fail=1
+        fi ;;
+      symlink)
+        log "  config: REFUSED symlink (someone else's SSOT)"
+        [ "$installed" -eq 1 ] && hard_fail=1 ;;
+      invalid-json|invalid-entry)
+        log "  config: $status"
+        [ "$installed" -eq 1 ] && hard_fail=1 ;;
+      file-absent|not-ours)
+        if [ "$installed" -eq 1 ]; then
+          log "  config: $status (owned state present — this is drift)"
+          hard_fail=1
+        else
+          log "  config: $status (not ours; run install-copilot-mcp to adopt)"
+        fi ;;
+      *)
+        log "  config: unexpected status '$out'"
+        [ "$installed" -eq 1 ] && hard_fail=1 ;;
+    esac
+  fi
+  if [ -f "$STATE_FILE" ]; then
+    local managed expected managed_status
+    expected="$(python3 -c 'import os,sys; print(os.path.abspath(sys.argv[1]))' "$CONFIG")"
+    if ! managed="$(state_target)"; then
+      log "  state: CORRUPT — $STATE_FILE has no absolute managedConfigPath"
+      hard_fail=1
+    elif [ "$managed" != "$expected" ]; then
+      log "  state: FOREIGN TARGET — state manages '$managed', Copilot reads '$expected'"
+      hard_fail=1
+    else
+      managed_status="$(run_config doctor-static "$managed" "$COMMAND" | tail -1)"
+      case "$managed_status" in
+        configured\ *) log "  state: install-state present; managed config still configures entwurf-bridge." ;;
+        file-absent)
+          log "  state: ORPHANED — managed config disappeared; removing stale state."
+          rm -f "$STATE_FILE" ;;
+        *)
+          log "  state: DRIFT — managed config no longer satisfies the MCP contract ($managed_status)."
+          hard_fail=1 ;;
+      esac
+    fi
+  else
+    log "  state: absent (no MCP ownership recorded)"
+  fi
+
+  if [ "$hard_fail" -ne 0 ]; then
+    fail "doctor found a broken Copilot MCP configuration."
+  fi
+  log "doctor: ok."
+}
+
+case "${1:-}" in
+  install) do_install ;;
+  uninstall) do_uninstall ;;
+  doctor) do_doctor ;;
+  *) echo "usage: copilot-mcp-bridge.sh <install|uninstall|doctor>" >&2; exit 2 ;;
+esac