@junghanacs/entwurf 0.14.1 → 0.15.0

package/scripts/copilot-bridge-install.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# copilot-bridge-install.sh — operator-grade global installer for the Copilot BIRTH
+# plugin (#82). The Copilot sibling of meta-bridge-install.sh, deliberately NOT a
+# mode of it.
+#
+# WHY A SEPARATE INSTALLER (§4-5, and one measured blocker)
+#
+#   1. The Claude installer assembles ONE marketplace root and copies exactly one
+#      plugin out of it (`cp -r "$SRC/$PLUGIN"`). Adding the Copilot unit to that
+#      same marketplace.json would publish a manifest whose second `source` is not
+#      in the assembly, and `claude plugin validate` runs over that root before any
+#      user config is touched. Two marketplace roots, two assemblies (cross-review,
+#      terra, 2026-08-20).
+#   2. The Claude doctor certifies Claude's own receiver marker and
+#      FileChanged/asyncRewake doorbell. Copilot's receiver is a forked first-party
+#      extension with its own installer and its own doctor. Sharing a doctor would
+#      make one rail certify evidence owned by another.
+#
+# WHAT THIS INSTALLS. One plugin whose managed job is to mint a meta-record on the
+# first prompt of a Copilot session and name that citizen as this host's sender. MCP
+# wiring has its own installer, and so does the RECEIVER: the doorbell is a forked
+# first-party extension, installed by `run.sh install-copilot-receive`, which also owns
+# the launch-flag check. Four surfaces, four installers, four failure modes.
+#
+# Platform: Linux only, same fence as the Claude installer.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(cd "$HERE/.." && pwd)"
+MKT_NAME="meta-bridge-copilot-local"
+PLUGIN="entwurf-meta-receive-copilot"
+SRC="$REPO/pi/meta-bridge-copilot"
+# `ENTWURF_COPILOT_ASM` exists for ONE caller: check-copilot-birth-hook drives this
+# script for real, into a temp dir, with --assemble-only. A gate that re-implemented
+# the bake would be testing its own copy of the logic instead of the shipped one.
+ASM="${ENTWURF_COPILOT_ASM:-${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/meta-bridge-copilot/.assembled}"
+# The Claude unit that is currently installed INTO Copilot. It fires there and then
+# dies in hook-launch.sh's no-argv refusal on every prompt, because Copilot's schema
+# has no `args` (measured: that refusal is why copilot held 0 of 409 meta-records).
+#
+# QUALIFIED, never bare. `copilot plugin uninstall` accepts `plugin-name` or
+# `plugin-name@marketplace-name` (measured 2026-08-21 from `plugin uninstall --help`),
+# and `copilot plugin list` prints the qualified id. A bare name would also match a
+# same-named plugin from somebody else's marketplace — this installer may only remove
+# the unit THIS repo installed (cross-review, terra).
+STALE_CLAUDE_UNIT="entwurf-meta-receive@meta-bridge-local"
+QUALIFIED="$PLUGIN@$MKT_NAME"
+KEEP_STALE=0
+# --assemble-only stops after the assembly, before the Copilot CLI is touched. It is
+# how the gate reaches the real bake on a host (and in CI) that has no Copilot.
+ASSEMBLE_ONLY=0
+
+die() { echo "[copilot-bridge-install] $*" >&2; exit 1; }
+
+for arg in "$@"; do
+  case "$arg" in
+    --keep-stale-claude-unit) KEEP_STALE=1 ;;
+    --assemble-only) ASSEMBLE_ONLY=1 ;;
+    *) die "unknown argument: $arg (--keep-stale-claude-unit, --assemble-only)" ;;
+  esac
+done
+
+[ "$(uname -s)" = "Linux" ] || die "Linux only; $(uname -s) is not a certified axis for this install."
+if [ "$ASSEMBLE_ONLY" -eq 0 ]; then
+  command -v copilot >/dev/null 2>&1 || die "the 'copilot' CLI is not on PATH."
+fi
+
+# PREFLIGHT, and all of it BEFORE the first destructive step. The assembly is removed
+# and rebuilt in place further down; discovering a missing python3 or an under-floor
+# node AFTER that would leave the operator with no assembly at all (cross-review, terra).
+command -v python3 >/dev/null 2>&1 || die "python3 is required (both bakes run through it) and is not on PATH."
+NODE_BIN="$(command -v node)" || die "node is not on PATH."
+[ -x "$NODE_BIN" ] || die "resolved node is not executable: $NODE_BIN"
+NODE_MAJOR="$("$NODE_BIN" -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0)"
+# The dev-clone shape bakes the raw `.ts` entry and relies on strip-types, so an
+# under-floor node does not fail at install — it fails at the operator's first prompt,
+# inside Copilot, where nothing surfaces it. Refuse here instead.
+[ "$NODE_MAJOR" -ge 24 ] 2>/dev/null || die "node >= 24 is required (package engines); resolved $NODE_BIN reports major '$NODE_MAJOR'."
+
+# Same install-shape split as the Claude installer: an installed package lives below
+# node_modules where Node refuses strip-types on `.ts`, so it runs the tsc-emitted
+# closure; a dev clone (and the XDG artifact) runs the `.ts` source.
+case "$REPO" in
+  */node_modules/@junghanacs/entwurf)
+    HOOK_ENTRY="meta-bridge-hook-copilot.js"
+    HOOK_SRC="$REPO/mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-hook-copilot.js"
+    LIB_SRC="$REPO/mcp/entwurf-bridge/dist/pi-extensions/lib/meta-session.js"
+    LIB_EXT="js" ;;
+  *)
+    HOOK_ENTRY="meta-bridge-hook-copilot.ts"
+    HOOK_SRC="$REPO/pi-extensions/meta-bridge-hook-copilot.ts"
+    LIB_SRC="$REPO/pi-extensions/lib/meta-session.ts"
+    LIB_EXT="ts" ;;
+esac
+
+# --- 1. assemble a self-contained, baked plugin -----------------------------
+[ -f "$HOOK_SRC" ] || die "hook artifact missing: $HOOK_SRC (run 'pnpm run build-bridge' in a dev clone, or reinstall the package)."
+[ -f "$LIB_SRC" ]  || die "hook lib artifact missing: $LIB_SRC (same build-bridge dist closure)."
+
+# ATOMIC: assemble beside the live artifact and swap only once it is complete. The
+# previous shape removed the live assembly first, so any failure between there and the
+# marketplace re-registration left the INSTALLED plugin pointing at a launcher that no
+# longer existed — a working hook broken by a failed upgrade (cross-review, terra).
+STAGE="$ASM.staging.$$"
+rm -rf "$STAGE"
+trap 'rm -rf "$STAGE"' EXIT
+mkdir -p "$STAGE"
+cp -r "$SRC/.claude-plugin" "$STAGE/.claude-plugin"
+cp -r "$SRC/$PLUGIN" "$STAGE/$PLUGIN"
+cp "$HOOK_SRC" "$STAGE/$PLUGIN/$HOOK_ENTRY"
+mkdir -p "$STAGE/$PLUGIN/lib"
+cp "$LIB_SRC" "$STAGE/$PLUGIN/lib/meta-session.$LIB_EXT"
+cp "$REPO/pi-extensions/lib/session-id.js" "$STAGE/$PLUGIN/lib/session-id.js"
+# The capability registry must travel at the plugin ROOT: metaCapabilitiesFilePath()
+# resolves it via `../` from lib/ in the bundle layout. Without it every mint throws.
+cp "$REPO/pi/entwurf-capabilities.json" "$STAGE/$PLUGIN/entwurf-capabilities.json"
+
+LAUNCHER="$STAGE/$PLUGIN/scripts/copilot-hook-launch.sh"
+# What gets BAKED into hooks.json is the FINAL path, not the staging one: the manifest
+# has to name where the launcher will live after the swap.
+FINAL_LAUNCHER="$ASM/$PLUGIN/scripts/copilot-hook-launch.sh"
+chmod +x "$LAUNCHER"
+
+# Bake node + entry into the LAUNCHER (not into hooks.json): Copilot's `exec` is a
+# single string with no argv beside it, so the payload coordinates cannot ride the
+# manifest the way Claude's `args` array carries them.
+LAUNCHER_PATH="$LAUNCHER" NODE_PATH_TO_BAKE="$NODE_BIN" HOOK_ENTRY_TO_BAKE="$HOOK_ENTRY" python3 - <<'PY'
+from pathlib import Path
+import os
+launcher = Path(os.environ["LAUNCHER_PATH"])
+node = os.environ["NODE_PATH_TO_BAKE"]
+hook_entry = os.environ["HOOK_ENTRY_TO_BAKE"]
+text = launcher.read_text(encoding="utf-8")
+for placeholder in ("__NODE_BIN__", "__HOOK_ENTRY__"):
+    if placeholder not in text:
+        raise SystemExit(f"launcher bake failed before replacement ({placeholder} absent in {launcher})")
+launcher.write_text(text.replace("__NODE_BIN__", node).replace("__HOOK_ENTRY__", hook_entry), encoding="utf-8")
+PY
+for placeholder in "__NODE_BIN__" "__HOOK_ENTRY__"; do
+  grep -q "$placeholder" "$LAUNCHER" && die "launcher bake failed ($placeholder still present in $LAUNCHER)."
+done
+
+# Bake the launcher's ABSOLUTE path into hooks.json. `${COPILOT_PLUGIN_ROOT}` and
+# `${CLAUDE_PLUGIN_ROOT}` both appear as recognized names in the shipped runtime, but
+# whether an `exec` string is substituted was never measured — and the assembly path
+# is stable and outside the checkout, so baking needs no such bet.
+HOOKS="$STAGE/$PLUGIN/hooks/hooks.json"
+HOOKS_PATH="$HOOKS" LAUNCHER_TO_BAKE="$FINAL_LAUNCHER" python3 - <<'PY'
+from pathlib import Path
+import os
+hooks = Path(os.environ["HOOKS_PATH"])
+launcher = os.environ["LAUNCHER_TO_BAKE"]
+text = hooks.read_text(encoding="utf-8")
+if "__COPILOT_LAUNCHER__" not in text:
+    raise SystemExit(f"hooks bake failed before replacement (__COPILOT_LAUNCHER__ absent in {hooks})")
+hooks.write_text(text.replace("__COPILOT_LAUNCHER__", launcher), encoding="utf-8")
+PY
+grep -q "__COPILOT_LAUNCHER__" "$HOOKS" && die "hooks bake failed (__COPILOT_LAUNCHER__ still present in $HOOKS)."
+
+# SWAP. Move the old assembly aside rather than deleting it, so a failed rename can be
+# undone; only then drop it.
+PREV=""
+if [ -d "$ASM" ]; then
+  PREV="$ASM.previous.$$"
+  mv "$ASM" "$PREV" || die "could not move the previous assembly aside ($ASM)."
+fi
+mkdir -p "$(dirname "$ASM")"
+if ! mv "$STAGE" "$ASM"; then
+  [ -n "$PREV" ] && mv "$PREV" "$ASM"
+  die "could not publish the staged assembly into $ASM (previous assembly restored)."
+fi
+trap - EXIT
+[ -n "$PREV" ] && rm -rf "$PREV"
+
+echo "[copilot-bridge-install] assembled $ASM (birth plugin only; MCP and receive are separate surfaces)"
+
+if [ "$ASSEMBLE_ONLY" -eq 1 ]; then
+  echo "[copilot-bridge-install] --assemble-only: stopping before the Copilot CLI is touched"
+  exit 0
+fi
+
+# --- 2. retire the stale Claude unit from Copilot ---------------------------
+# It is ours, it fires on every Copilot prompt, and it exits 1 before node starts.
+# Leaving it installed means the operator keeps paying for a hook that cannot work.
+if [ "$KEEP_STALE" -eq 0 ]; then
+  # ASK FIRST, then act. Treating every nonzero uninstall as "not present" would report
+  # a CLI, config or permission failure as an absence and then install on top of a unit
+  # that is still firing (cross-review, terra). `copilot plugin list` prints the
+  # QUALIFIED id, which is also what distinguishes our unit from a same-named plugin
+  # somebody else installed from another marketplace.
+  # The LIST failing is not an empty list. `|| true` would hand the "nothing installed"
+  # arm a broken, unauthenticated or permission-denied Copilot CLI and then install on
+  # top of whatever is really there (cross-review, terra). The assignment IS the
+  # condition so `set -e` cannot kill us before we can say why.
+  if ! INSTALLED_LIST="$(copilot plugin list 2>/dev/null)"; then
+    die "'copilot plugin list' failed, so this host's installed plugins are UNKNOWN. An unknown list is not an empty one — the stale Claude unit may still be firing. Fix the Copilot CLI error, or re-run with --keep-stale-claude-unit to skip this check deliberately."
+  fi
+  case "$INSTALLED_LIST" in
+    *"$STALE_CLAUDE_UNIT"*)
+      copilot plugin uninstall "$STALE_CLAUDE_UNIT" >/dev/null \
+        || die "the stale Claude unit '$STALE_CLAUDE_UNIT' is installed in Copilot but could not be removed. It fires on every prompt and exits 1 before node starts, so installing on top of it would leave that noise in place. Fix the Copilot CLI error above, or re-run with --keep-stale-claude-unit to proceed deliberately."
+      echo "[copilot-bridge-install] removed the stale Claude unit '$STALE_CLAUDE_UNIT' from Copilot (it exits 1 on every prompt there)"
+      ;;
+    *)
+      echo "[copilot-bridge-install] stale Claude unit '$STALE_CLAUDE_UNIT' is not installed in Copilot (nothing to remove)"
+      ;;
+  esac
+fi
+
+# --- 3. (re)register the marketplace and install ----------------------------
+copilot plugin uninstall "$QUALIFIED" >/dev/null 2>&1 || true
+copilot plugin marketplace remove "$MKT_NAME" >/dev/null 2>&1 || true
+copilot plugin marketplace add "$ASM" >/dev/null || die "'copilot plugin marketplace add $ASM' failed."
+copilot plugin install "$QUALIFIED" >/dev/null || die "'copilot plugin install $QUALIFIED' failed."
+
+# --- 4. evidence ------------------------------------------------------------
+echo "--- copilot plugin list ---"
+# The qualified id, not the bare name: a bare grep would be satisfied by a same-named
+# plugin from another marketplace and report an install that never happened.
+copilot plugin list 2>/dev/null | grep -F "$QUALIFIED" || die "post-install: $QUALIFIED is not in 'copilot plugin list' (install did not take)."
+echo
+echo "[copilot-bridge-install] DONE. A Copilot session becomes a citizen on its FIRST PROMPT,"
+echo "not when the window opens — sessionStart is deferred to the first prompt (measured)."
+echo "Verify with: ./run.sh doctor-copilot-bridge"

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