@junghanacs/entwurf 0.14.2 → 0.15.0

package/scripts/copilot-bridge-doctor.sh

@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+# copilot-bridge-doctor.sh — the FAIL-LOUD surface for the Copilot birth plugin (#82).
+#
+# WHY IT IS NOT `doctor-meta-bridge --copilot`. The Claude doctor's red conditions
+# certify Claude's receiver marker and FileChanged/asyncRewake hook rail. Copilot has a
+# receiver too since #82 RAIL 5, but it is a different mechanism owned by a different
+# process (a forked extension) and certified by its own doctor,
+# `doctor-copilot-receive`. This BIRTH doctor certifies birth and who-sent. A shared
+# doctor would make one rail pass on evidence owned by another, which is a branch, not a
+# shared surface.
+#
+# (Until #82 RAIL 5b it had none of the four, and this comment said so. The sender
+# marker joined because who-sent needs a shared parent, not a doorbell — the two facts
+# had been merged under one absence.)
+#
+# WHAT A PASS FROM THIS DOCTOR MEANS, AND WHAT IT DOES NOT. Copilot exposes no plugin
+# load or hook-execution receipt, so this doctor can prove the artifact is correct and
+# REGISTERED, never that Copilot loaded it. A PASS with zero records is therefore
+# consistent with two different worlds — a session not yet spoken to, and a unit Copilot
+# silently never invokes. Only a real first prompt separates them, and that receipt (a
+# record in the store) is what closes admission — not this doctor (cross-review, terra).
+#
+# THE ONE HONEST DIFFERENCE FROM THE CLAUDE DOCTOR. There, a plugin installed with
+# zero meta-records is a SILENT MISS and exits non-zero, because a Claude session
+# mints at session open — so zero records means something ate the hook. A Copilot
+# session is born on its FIRST PROMPT (measured: opening the TUI fires no hook at
+# all), so "installed, zero records" is the ordinary state of a Copilot that has been
+# opened and not yet spoken to. Calling that red would train the operator to ignore
+# the doctor. It is reported as NOT-YET, by name, and the red condition is a hook that
+# RAN and FAILED — an ERROR line this unit wrote to the shared hook log.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(cd "$HERE/.." && pwd)"
+MKT_NAME="meta-bridge-copilot-local"
+PLUGIN="entwurf-meta-receive-copilot"
+# QUALIFIED ids throughout: `copilot plugin list` prints `plugin@marketplace` (measured
+# 2026-08-21), and a bare name would both accept a same-named plugin from somebody
+# else's marketplace as ours and flag theirs as our stale unit (cross-review, terra).
+QUALIFIED="$PLUGIN@$MKT_NAME"
+STALE_CLAUDE_UNIT="entwurf-meta-receive@meta-bridge-local"
+ASM="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/meta-bridge-copilot/.assembled"
+AGENT_DIR="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+SESSIONS_DIR="$AGENT_DIR/meta-sessions"
+HOOK_LOG="$AGENT_DIR/meta-bridge-hook.log"
+
+fail=0
+ok()   { echo "  ok    $*"; }
+bad()  { echo "  FAIL  $*"; fail=1; }
+note() { echo "  note  $*"; }
+
+echo "[copilot-bridge-doctor] toolchain"
+command -v copilot >/dev/null 2>&1 && ok "copilot CLI on PATH" || bad "copilot CLI missing from PATH"
+command -v node >/dev/null 2>&1 && ok "node on PATH" || bad "node missing from PATH"
+
+echo "[copilot-bridge-doctor] assembled artifact"
+if [ -d "$ASM/$PLUGIN" ]; then
+  ok "assembly present at $ASM"
+else
+  bad "assembly missing at $ASM — run ./run.sh install-copilot-bridge"
+fi
+
+LAUNCHER="$ASM/$PLUGIN/scripts/copilot-hook-launch.sh"
+HOOKS="$ASM/$PLUGIN/hooks/hooks.json"
+if [ -x "$LAUNCHER" ]; then
+  ok "launcher present and executable"
+  # The exec form names the launcher as THE executable — a lost +x bit is ENOEXEC at
+  # first prompt, not a degraded path.
+  if grep -q "__NODE_BIN__\|__HOOK_ENTRY__" "$LAUNCHER"; then
+    bad "launcher still carries an installer placeholder (bake did not run)"
+  else
+    ok "launcher is baked (no placeholders)"
+    BAKED_NODE="$(sed -n 's/^NODE_BIN="\(.*\)"$/\1/p' "$LAUNCHER" | head -1)"
+    [ -x "$BAKED_NODE" ] && ok "baked node exists: $BAKED_NODE" \
+      || bad "baked node is missing or not executable: ${BAKED_NODE:-(unparsed)} — node moved (NixOS store churn?); reinstall"
+    BAKED_ENTRY="$(sed -n 's|^HOOK_ENTRY="\$PLUGIN_ROOT/\(.*\)"$|\1|p' "$LAUNCHER" | head -1)"
+    [ -n "$BAKED_ENTRY" ] && [ -f "$ASM/$PLUGIN/$BAKED_ENTRY" ] && ok "hook entry present: $BAKED_ENTRY" \
+      || bad "hook entry missing beside the launcher: ${BAKED_ENTRY:-(unparsed)}"
+  fi
+else
+  bad "launcher missing or not executable: $LAUNCHER"
+fi
+
+[ -f "$ASM/$PLUGIN/entwurf-capabilities.json" ] \
+  && ok "capability registry travels at the plugin root (every mint reads it)" \
+  || bad "capability registry missing at the plugin root — every mint would throw"
+
+if [ -f "$HOOKS" ]; then
+  HOOKS_PATH="$HOOKS" ASM_LAUNCHER="$LAUNCHER" python3 - <<'PY'
+import json, os, sys
+from pathlib import Path
+hooks = json.loads(Path(os.environ["HOOKS_PATH"]).read_text(encoding="utf-8"))
+launcher = os.environ["ASM_LAUNCHER"]
+problems = []
+if hooks.get("version") != 1:
+    problems.append("hooks.json root `version` must be the literal 1 (Copilot rejects the plugin otherwise)")
+events = hooks.get("hooks") or {}
+if set(events) != {"sessionStart", "userPromptSubmitted"}:
+    problems.append(f"hook events drifted: {sorted(events)} — want exactly ['sessionStart', 'userPromptSubmitted']")
+for name, entries in events.items():
+    for i, entry in enumerate(entries if isinstance(entries, list) else []):
+        exec_value = entry.get("exec")
+        if not isinstance(exec_value, str):
+            problems.append(f"hooks.{name}[{i}].exec must be a STRING (an array is rejected at plugin load)")
+        elif exec_value != launcher:
+            problems.append(f"hooks.{name}[{i}].exec does not point at the assembled launcher: {exec_value}")
+        if "args" in entry:
+            problems.append(f"hooks.{name}[{i}] carries `args`, which Copilot's schema has no key for")
+for p in problems:
+    print(f"  FAIL  {p}")
+sys.exit(1 if problems else 0)
+PY
+  [ $? -eq 0 ] && ok "hooks.json is the Copilot native form, baked at the assembled launcher" || fail=1
+else
+  bad "hooks.json missing: $HOOKS"
+fi
+
+echo "[copilot-bridge-doctor] copilot wiring"
+PLUGIN_LIST="$(copilot plugin list 2>/dev/null)"
+case "$PLUGIN_LIST" in
+  *"$QUALIFIED"*)
+    # WHAT THIS DOES NOT PROVE. Copilot exposes no load/execution receipt, so a listing
+    # says the plugin is REGISTERED, never that Copilot loaded this unit or will invoke
+    # its hook. Only a real first prompt settles that — see the birth-evidence section.
+    ok "$QUALIFIED is registered in Copilot (registration, not proof it is loaded)" ;;
+  *) bad "$QUALIFIED is NOT installed in Copilot — run ./run.sh install-copilot-bridge" ;;
+esac
+case "$PLUGIN_LIST" in
+  *"$STALE_CLAUDE_UNIT"*)
+    bad "the Claude unit '$STALE_CLAUDE_UNIT' is still installed in Copilot — it fires on every prompt and exits 1 before node starts (Copilot's schema has no args key). Re-run the installer without --keep-stale-claude-unit." ;;
+  *) ok "the Claude unit is not installed in Copilot" ;;
+esac
+
+echo "[copilot-bridge-doctor] birth evidence"
+COPILOT_RECORDS=0
+if [ -d "$SESSIONS_DIR" ]; then
+  COPILOT_RECORDS="$(grep -l '"backend": "copilot"' "$SESSIONS_DIR"/*.meta.json 2>/dev/null | wc -l | tr -d ' ')"
+fi
+if [ "$COPILOT_RECORDS" -gt 0 ]; then
+  ok "$COPILOT_RECORDS copilot meta-record(s) in $SESSIONS_DIR — the citizen exists"
+else
+  # NOT a failure. See the header: a Copilot session mints on its first prompt, so an
+  # opened-but-unspoken session legitimately has no record yet.
+  note "no copilot meta-record yet. A Copilot session is born on its FIRST PROMPT, not when"
+  note "the window opens — open Copilot, send one prompt, then re-run this doctor."
+  note "NOT-YET is only meaningful BEFORE that first prompt. If a Copilot session has"
+  note "already been prompted on this host and this still says zero, the unit is not"
+  note "being invoked and that IS the failure — Copilot gives no load receipt to tell"
+  note "the two apart from here."
+fi
+
+if [ -f "$HOOK_LOG" ]; then
+  # RECOVERY RULE. The hook log is append-only, so a repaired install would otherwise
+  # stay red forever on errors it has already outgrown (cross-review, terra). What is
+  # red is an ERROR with NO successful mint after it: a failure the unit never recovered
+  # from. An ERROR followed by a create/attach is history, and is reported as such.
+  #
+  # grep -c prints 0 AND exits 1 with no match, so a `|| echo 0` fallback would append a
+  # SECOND line and every numeric test below would die on "0\n0". Keep it to one line.
+  #
+  # MINT ERRORS ONLY. Since #82 RAIL 5b this unit also writes a SENDER marker, and a
+  # failed marker write is an ERROR that lands AFTER the successful mint line — so the
+  # order rule above would read it as "no successful mint after the error" and print a
+  # sentence that is simply false (the record IS there). The two failures are separated
+  # here rather than downgraded in the payload, because a marker write that keeps
+  # breaking must stay loud somewhere; it just is not a birth failure.
+  MINT_ERRORS=' ERROR \[copilot\] (?!sender-marker-)'
+  LAST_ERROR_LINE="$(grep -nP "$MINT_ERRORS" "$HOOK_LOG" 2>/dev/null | tail -1 | cut -d: -f1)"
+  LAST_OK_LINE="$(grep -n ' INFO \[copilot\] \(create\|attach\) ' "$HOOK_LOG" 2>/dev/null | tail -1 | cut -d: -f1)"
+  TOTAL_ERRORS="$(grep -cP "$MINT_ERRORS" "$HOOK_LOG" 2>/dev/null | head -1)"
+  TOTAL_ERRORS="${TOTAL_ERRORS:-0}"
+  if [ -z "$LAST_ERROR_LINE" ]; then
+    ok "no copilot ERROR lines in $HOOK_LOG"
+  elif [ -n "$LAST_OK_LINE" ] && [ "$LAST_OK_LINE" -gt "$LAST_ERROR_LINE" ]; then
+    note "$TOTAL_ERRORS historical copilot ERROR line(s) in $HOOK_LOG, all followed by a successful mint (line $LAST_OK_LINE > $LAST_ERROR_LINE) — recovered, not red"
+  else
+    bad "the newest copilot line in $HOOK_LOG is an unrecovered ERROR — the hook RAN and did not mint:"
+    grep -P "$MINT_ERRORS" "$HOOK_LOG" | tail -3 | sed 's/^/        /'
+  fi
+
+  # WHO-SENT, judged on its own axis. Both outcomes leave a citizen that EXISTS and can
+  # be addressed by others; what is missing is only its ability to send under its own
+  # garden id. So a REFUSAL is a note (fail-closed by design — a session opened before
+  # the current install reaches the payload without launch provenance and correctly
+  # claims no owner), while a failed WRITE is red (we tried and the store would not take
+  # it, and nothing downstream will say why).
+  MARKER_FAILED="$(grep -c ' ERROR \[copilot\] sender-marker-failed ' "$HOOK_LOG" 2>/dev/null | head -1)"
+  MARKER_REFUSED="$(grep -c ' WARN \[copilot\] sender-marker-refused ' "$HOOK_LOG" 2>/dev/null | head -1)"
+  MARKER_OK="$(grep -c ' INFO \[copilot\] sender marker ' "$HOOK_LOG" 2>/dev/null | head -1)"
+  if [ "${MARKER_FAILED:-0}" -gt 0 ]; then
+    bad "${MARKER_FAILED} sender-marker WRITE failure(s) in $HOOK_LOG — those citizens exist but cannot send under their own garden id:"
+    grep ' ERROR \[copilot\] sender-marker-failed ' "$HOOK_LOG" | tail -3 | sed 's/^/        /'
+  elif [ "${MARKER_REFUSED:-0}" -gt 0 ]; then
+    note "${MARKER_REFUSED} sender-marker refusal(s) and ${MARKER_OK:-0} armed — a refusal is fail-closed, not a fault. A session that predates this install reaches the hook without launch provenance; RESTART it to arm who-sent"
+  elif [ "${MARKER_OK:-0}" -gt 0 ]; then
+    ok "${MARKER_OK} sender marker(s) armed — these citizens send under their own garden id"
+  else
+    note "no sender-marker lines yet in $HOOK_LOG (nothing has fired since who-sent landed)"
+  fi
+else
+  note "no hook log yet at $HOOK_LOG (nothing has fired on this host)"
+fi
+
+echo
+if [ "$fail" -ne 0 ]; then
+  echo "[copilot-bridge-doctor] FAIL"
+  exit 1
+fi
+echo "[copilot-bridge-doctor] PASS"

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"