@junghanacs/entwurf 0.14.2 → 0.15.0

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

package/scripts/copilot-mcp-config.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""Stateful Copilot MCP-config adapter; stdlib only.
+
+Owns ONE server key (``entwurf-bridge``) inside ``~/.copilot/mcp-config.json``.
+The file wrapper is always ``mcpServers``. The stdio entry follows Copilot CLI's
+writer, not the API wire schema: ``{type:"local", command, args?}``.
+Adopts regular files, refuses symlinks, records first-install preimages.
+"""
+
+import datetime
+import json
+import os
+import sys
+import tempfile
+
+STATE_SCHEMA_VERSION = 1
+SERVER_KEY = "entwurf-bridge"
+ENTRY_TYPE = "local"
+
+
+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"copilot-mcp: cannot read {label} {path}: {error}")
+    if not raw.strip():
+        return {}
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as error:
+        die(4, f"copilot-mcp: {label} {path} is not valid JSON: {error}")
+    if not isinstance(value, dict):
+        die(4, f"copilot-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=".copilot-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) -> dict:
+    # CLI `copilot mcp add` writes type:"local" (not "stdio") plus command/args.
+    # args is present and empty so the inverse has a stable shape; env/timeout/tools stay omitted.
+    return {"type": ENTRY_TYPE, "command": command, "args": []}
+
+
+def checked_state(state_path: str) -> dict:
+    state = load_object(state_path, "install-state")
+    required = (
+        "managedConfigPath",
+        "serverKey",
+        "command",
+        "detectMode",
+        "configExistedBefore",
+        "preimage",
+    )
+    if state.get("schemaVersion") != STATE_SCHEMA_VERSION or any(key not in state for key in required):
+        die(4, f"copilot-mcp: install-state {state_path} has an unsupported shape")
+    if state.get("serverKey") != SERVER_KEY:
+        die(4, f"copilot-mcp: install-state {state_path} serverKey is not {SERVER_KEY}")
+    return state
+
+
+def prior_state(state_path: str, config_path: str) -> dict | None:
+    if not os.path.exists(state_path):
+        return None
+    state = checked_state(state_path)
+    return state if state["managedConfigPath"] == os.path.abspath(config_path) else None
+
+
+def install(config_path: str, command: str, state_path: str) -> None:
+    if os.path.islink(config_path):
+        die(3, f"copilot-mcp: refusing to adopt {config_path} — symlink to {os.readlink(config_path)} (someone else's SSOT)")
+
+    existed = os.path.exists(config_path)
+    data = load_object(config_path, "config") if existed else {}
+    servers = data.get("mcpServers")
+    if servers is None:
+        servers = {}
+        data["mcpServers"] = servers
+    if not isinstance(servers, dict):
+        die(4, f"copilot-mcp: {config_path} mcpServers must be a JSON object")
+
+    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,
+            "detectMode": "adopt-regular-file" if existed else "created-new",
+            "configExistedBefore": existed,
+            "preimage": servers.get(SERVER_KEY),
+            "installedAt": now(),
+        }
+    else:
+        state = prior
+
+    servers[SERVER_KEY] = our_entry(command)
+    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"copilot-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"copilot-mcp: install-state {state_path} has no absolute managedConfigPath")
+    if os.path.islink(config_path):
+        die(3, f"copilot-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
+            only_ours = created and len(servers) == 0 and set(data.keys()) == {"mcpServers"}
+            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 _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
+    servers = data.get("mcpServers")
+    if not isinstance(servers, dict) or SERVER_KEY not in servers:
+        return "not-ours", None
+    server = servers.get(SERVER_KEY)
+    if not isinstance(server, dict):
+        return "invalid-entry", None
+    found = server.get("command")
+    args = server.get("args", [])
+    env = server.get("env", {})
+    if server.get("type") != ENTRY_TYPE:
+        return "invalid-entry", None
+    if not isinstance(found, str) or not found:
+        return "invalid-entry", None
+    if found != command:
+        return "not-ours", None
+    if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args):
+        return "invalid-entry", None
+    if not isinstance(env, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in env.items()):
+        return "invalid-entry", 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"copilot-mcp: cannot read configured invocation from {config_path}: {status}")
+    sys.stdout.write(json.dumps(invocation, separators=(",", ":")) + "\n")
+
+
+def main(argv: list[str]) -> None:
+    if len(argv) < 2:
+        die(5, "usage: copilot-mcp-config.py <install|uninstall|doctor-static|doctor-invocation> ...")
+    match argv[1]:
+        case "install" if len(argv) == 5:
+            install(argv[2], argv[3], argv[4])
+        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 _:
+            die(5, "usage: copilot-mcp-config.py <install config command state|uninstall state|doctor-static config command|doctor-invocation config command>")
+
+
+if __name__ == "__main__":
+    main(sys.argv)