@junghanacs/entwurf 0.14.1 → 0.15.0

package/scripts/check-meta-session.ts

@@ -168,6 +168,38 @@ check("upsertMetaSession: creates the store dir if absent; leaves no .tmp residu
 	}
 });
 
+check("upsertMetaSession: unknown-backend neighbour refuses as a stale reader, not a fresh-cut", () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "meta-session-stale-reader-"));
+	try {
+		const gid = "20260101T000000-0a1b2c";
+		fs.writeFileSync(
+			path.join(dir, `${gid}.meta.json`),
+			`${JSON.stringify({
+				schemaVersion: 3,
+				gardenId: gid,
+				backend: "gemini",
+				nativeSessionId: "n-unknown-backend",
+				cwd: "/synthetic",
+				model: null,
+				transcriptPath: null,
+				createdAt: T0.toISOString(),
+				recordUpdatedAt: T0.toISOString(),
+			})}\n`,
+		);
+		assert.throws(
+			() => upsertMetaSession({ dir, input: claudeInput(), now: T1 }),
+			(err: unknown) =>
+				err instanceof MetaRecordError &&
+				err.message.includes('"backend" must be one of') &&
+				err.message.includes("the reader is stale") &&
+				err.message.includes("do not archive those records"),
+			"unknown-backend store must name a stale reader, not only a fresh-cut",
+		);
+	} finally {
+		fs.rmSync(dir, { recursive: true, force: true });
+	}
+});
+
 // ---------------------------------------------------------------- exclusive CREATE publish (#66 fail-closed)
 check("publishExclusiveIdentity: absent final publishes, round-trips, no tmp residue", () => {
 	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "meta-session-excl-"));

package/scripts/check-probe-bridge-command.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// check-probe-bridge-command — deterministic contract gate for the #81 boot probe.
+//
+// The probe is what two doctors now stake their verdict on, so its reason taxonomy is a contract,
+// not an implementation detail: each value names a DIFFERENT operator situation, and collapsing two
+// of them would put the wrong repair in front of an operator. This gate pins the classification and
+// the one side effect the probe owns — reaping the child it spawned.
+//
+// Hermetic: every subject is a stub script in a mktemp dir. No network, no operator state, no MCP
+// server of ours is booted (check-entwurf-bridge-boot owns that axis).
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXPECTED_TOOLS, probeBridgeCommand } from "./probe-bridge-command.ts";
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const PROBE_SRC = readFileSync(join(REPO_ROOT, "scripts", "probe-bridge-command.ts"), "utf8");
+
+let passed = 0;
+// The `[QK:…]` token must land on a FAILURE line (qualification does not count a token printed on
+// an `ok` line — a later red must not self-certify an earlier claim), and it must appear exactly
+// once in this file. So: strip it from the green line, print it verbatim on the red one.
+function ok(label: string, cond: boolean, detail?: string): void {
+	if (!cond) {
+		console.error(`FAIL: ${label}`);
+		if (detail) console.error(detail);
+		process.exit(1);
+	}
+	console.log(`  ok    ${label.replace(/\[QK:[^\]]+\]\s*/, "")}`);
+	passed++;
+}
+
+const dir = mkdtempSync(join(tmpdir(), "entwurf-probe-gate-"));
+const stub = (name: string, body: string): string => {
+	const p = join(dir, name);
+	writeFileSync(p, body);
+	chmodSync(p, 0o755);
+	return p;
+};
+
+/** An MCP stub that answers tools/list with exactly the given verb names. */
+const mcpStub = (name: string, names: readonly string[]): string => {
+	const tools = names.map((n) => `{"name":"${n}"}`).join(",");
+	return stub(
+		name,
+		`#!/usr/bin/env bash
+while IFS= read -r line; do
+  case "$line" in
+    *'"id":1'*) printf '%s\\n' '{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{},"serverInfo":{"name":"fake-entwurf-bridge","version":"0"}}}' ;;
+    *'"id":2'*) printf '%s\\n' '{"jsonrpc":"2.0","id":2,"result":{"tools":[${tools}]}}' ;;
+  esac
+done
+`,
+	);
+};
+
+try {
+	// ── the healthy shape ─────────────────────────────────────────────────────
+	const healthy = mcpStub("healthy", EXPECTED_TOOLS);
+	const rHealthy = await probeBridgeCommand({ command: healthy });
+	ok("the exact verb set is the only green", rHealthy.ok && rHealthy.reason === "ok", JSON.stringify(rHealthy));
+
+	// ── identity: booting an MCP server is not being THIS bridge ──────────────
+	// Missing one verb is the observed #81 shape (a session whose schema had no entwurf_self).
+	const partial = mcpStub(
+		"partial",
+		EXPECTED_TOOLS.filter((t) => t !== "entwurf_self"),
+	);
+	const rPartial = await probeBridgeCommand({ command: partial });
+	ok(
+		"[QK:PROBE-REASON-MISSING-VERB] a served MCP surface MISSING a verb is a mismatch, not ok",
+		!rPartial.ok && rPartial.reason === "tool-set-mismatch" && rPartial.detail.includes("missing entwurf_self"),
+		JSON.stringify(rPartial),
+	);
+	// The other direction: a stale build still serving a retired verb must not read as this bridge.
+	const extra = mcpStub("extra", [...EXPECTED_TOOLS, "entwurf_retired_verb"]);
+	const rExtra = await probeBridgeCommand({ command: extra });
+	ok(
+		"an EXTRA verb is a mismatch too (stale build / foreign binary)",
+		!rExtra.ok && rExtra.reason === "tool-set-mismatch" && rExtra.detail.includes("unexpected entwurf_retired_verb"),
+		JSON.stringify(rExtra),
+	);
+
+	// ── the defect that started #81: resolves, then dies on exec ──────────────
+	const dead = stub("dead", "#!/usr/bin/env bash\necho 'boom: no such file or directory' >&2\nexit 127\n");
+	const rDead = await probeBridgeCommand({ command: dead });
+	ok(
+		"a launcher that exits before tools/list is classified as such, with its stderr",
+		!rDead.ok && rDead.reason === "exited-before-tools-list" && rDead.detail.includes("boom"),
+		JSON.stringify(rDead),
+	);
+
+	// ── not executable at all ─────────────────────────────────────────────────
+	const rMissing = await probeBridgeCommand({ command: join(dir, "does-not-exist") });
+	ok(
+		"an unexecutable command is spawn-failed, NOT a boot failure",
+		!rMissing.ok && rMissing.reason === "spawn-failed",
+		JSON.stringify(rMissing),
+	);
+
+	// ── initialize is a handshake, not a frame we merely write ───────────────
+	const noInitialize = stub(
+		"no-initialize",
+		`#!/usr/bin/env bash
+printf '%s\\n' '{"jsonrpc":"2.0","id":2,"result":{"tools":[${EXPECTED_TOOLS.map((n) => `{"name":"${n}"}`).join(",")}]}}'
+while IFS= read -r _line; do :; done
+`,
+	);
+	const rNoInitialize = await probeBridgeCommand({ command: noInitialize, timeoutMs: 700 });
+	ok(
+		"[QK:PROBE-REQUIRES-INITIALIZE] an exact tools/list sent before initialize completes is not a healthy MCP bridge",
+		!rNoInitialize.ok && rNoInitialize.reason === "initialize-failed",
+		JSON.stringify(rNoInitialize),
+	);
+
+	// ── not an MCP server (answers id:2, no tools array) ──────────────────────
+	const notMcp = stub(
+		"not-mcp",
+		`#!/usr/bin/env bash
+while IFS= read -r line; do
+  case "$line" in
+    *'"id":1'*) printf '%s\\n' '{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{},"serverInfo":{"name":"not-mcp","version":"0"}}}' ;;
+    *'"id":2'*) printf '%s\\n' '{"jsonrpc":"2.0","id":2,"result":{}}' ;;
+  esac
+done
+`,
+	);
+	const rNotMcp = await probeBridgeCommand({ command: notMcp });
+	ok(
+		"an id:2 reply without result.tools is not an MCP server",
+		!rNotMcp.ok && rNotMcp.reason === "no-tools-array",
+		JSON.stringify(rNotMcp),
+	);
+
+	// ── timeout + bounded cleanup ─────────────────────────────────────────────
+	// The probe runs whatever the operator configured, including a launcher that ignores SIGTERM.
+	// If it resolved without escalating, that process would outlive the doctor. The stub records
+	// its own pid so this gate can assert the reap actually happened — an unobserved kill is a
+	// claim, not evidence.
+	const pidFile = join(dir, "hung.pid");
+	const hung = stub(
+		"hung",
+		`#!/usr/bin/env bash
+trap '' TERM
+echo $$ > ${JSON.stringify(pidFile)}
+while true; do sleep 0.05; done
+`,
+	);
+	const rHung = await probeBridgeCommand({ command: hung, timeoutMs: 700 });
+	ok(
+		"a launcher that stays up but never answers is a timeout",
+		!rHung.ok && rHung.reason === "timeout",
+		JSON.stringify(rHung),
+	);
+	const hungPid = Number(readFileSync(pidFile, "utf8").trim());
+	ok(
+		"timeout stub recorded a usable pid (the cleanup assertion below has a subject)",
+		Number.isInteger(hungPid) && hungPid > 0,
+	);
+	// SIGTERM is trapped, so only the SIGKILL escalation can end it — and the probe must have
+	// completed that escalation BEFORE returning. Checking right here (no polling, no grace loop)
+	// is what pins that ordering: a probe that merely scheduled the kill would fail this cell,
+	// which is exactly the state a doctor's immediate process.exit() would leave behind.
+	const alive = spawnSync("kill", ["-0", String(hungPid)], { stdio: "ignore" }).status === 0;
+	// Clean up BEFORE asserting. When this claim's mutant re-plants the leak, `alive` is true and
+	// the assertion exits the process immediately — so without this line the gate that exists to
+	// prove nothing is orphaned would itself orphan the stub on the host, once per qualification
+	// run. A killed mutant must still leave zero residue.
+	if (alive) spawnSync("kill", ["-9", String(hungPid)], { stdio: "ignore" });
+	ok(
+		"[QK:PROBE-CLEANUP-ESCALATES] a SIGTERM-ignoring child is escalated to SIGKILL, never left orphaned",
+		!alive,
+		`pid ${hungPid} was still alive after the probe returned — the probe leaked the process it spawned`,
+	);
+
+	// ── source pin: the stdin EPIPE guard ─────────────────────────────────────
+	// WHY pinned instead of measured: the failure needs the child to exec, die and close its stdin
+	// read end BETWEEN uv_spawn and the parent's first write. Nothing this gate can write to a stub
+	// controls that ordering — measured on this host, five stub shapes (bad shebang, self-closed
+	// stdin, instant exit, missing file, a directory) produced EPIPE 0/20 each while idle, and only
+	// 12-way CPU contention opened the window (11/60 crashes before the fix, 0/60 after). A cell
+	// that only fires under load is a flaky gate, not a proof, so the property is pinned at the
+	// source. It is load-bearing because the crash it prevents is silent-by-substitution: the probe
+	// dies printing a Node stack trace where the doctor verdict should carry the LAUNCHER's stderr —
+	// the one line that names which hop broke. Ordering matters as much as presence: the listener
+	// must be installed before any write can dispatch.
+	const guard = '\t\tchild.stdin.on("error", () => {});';
+	const guardAt = PROBE_SRC.indexOf(guard);
+	const firstWriteAt = PROBE_SRC.indexOf("child.stdin.write(");
+	ok(
+		"[QK:PROBE-STDIN-EPIPE-GUARD] child.stdin carries an error listener installed before the first write — an async EPIPE from a launcher that died on exec must never replace the verdict with an uncaught exception",
+		guardAt >= 0 && firstWriteAt >= 0 && guardAt < firstWriteAt,
+		`guard index ${guardAt}, first child.stdin.write index ${firstWriteAt} in scripts/probe-bridge-command.ts`,
+	);
+} finally {
+	rmSync(dir, { recursive: true, force: true });
+}
+
+console.log(`check-probe-bridge-command: ${passed} checks passed`);

package/scripts/check-release-gate-outcomes.ts

@@ -439,6 +439,58 @@ function runSubcommand(sub: string, env: Record<string, string | undefined>): {
 	);
 }
 
+// ===========================================================================
+// The operator's CONFIGURED bridge invocation is proven BEFORE the cost-bearing LIVE tier
+//
+// `check-bridge` boots the launcher this checkout SHIPS. It cannot speak for the string
+// pi's provider actually execs, and only that second one reaches a live ACP session.
+// 2026-08-19 measured the difference at full price: a relocated `~/.local/bin/entwurf-bridge`
+// symlink into a pnpm cmd-shim (basedir derived from $0, so not relocatable) exited 127, the
+// bundled bridge never booted, and the model had no `mcp__entwurf-bridge__*` tool — while
+// `command -v` answered yes throughout. #81 had already built the leaf that settles this in
+// under a second, and doctor-pi-provider consumes it; it was simply never a step, so the
+// verdict surfaced sixteen LIVE steps later at smoke-acp-bundled-mcp-live.
+// Pinned here because the step is CHEAP and therefore easy to drop again "to speed the gate up":
+// its whole value is the position, so both the position and the classifier arm are asserted.
+// run_step, not run_live_step — this doctor is not LIVE-gated and never emits 97, so a SKIP arm
+// would describe a prerequisite it cannot have.
+// ===========================================================================
+{
+	const runSh = readFileSync(join(REPO_DIR, "run.sh"), "utf8");
+	const gateBody = runSh.slice(runSh.indexOf("release_gate() {"), runSh.indexOf("# 5. Summary"));
+	const verify = readFileSync(join(REPO_DIR, "VERIFY.md"), "utf8");
+	const STEP =
+		'run_step "doctor-pi-provider (#81: the operator\'s CONFIGURED bridge invocation actually boots)" gate bash "$self" doctor-pi-provider';
+	const doctorSteps = gateBody.split("\n").filter((l) => l.includes('"$self" doctor-pi-provider'));
+	const gaps: string[] = [];
+	if (doctorSteps.length !== 1)
+		gaps.push(`release_gate runs doctor-pi-provider ${doctorSteps.length}x (need exactly one MUST step)`);
+	if (doctorSteps.length === 1 && doctorSteps[0]?.trim() !== STEP)
+		gaps.push(`the doctor step is not the exact pinned invocation (got: ${doctorSteps[0]?.trim()})`);
+	if (doctorSteps.length === 1 && doctorSteps[0]?.includes("run_live_step"))
+		gaps.push("the doctor step goes through run_live_step, inventing a SKIP arm for a doctor that never emits 97");
+	// Position is the point: a cheap probe scheduled after the expensive tier proves nothing new.
+	const doctorAt = gateBody.indexOf('"$self" doctor-pi-provider');
+	// Anchored on the step KEYWORD, not the bare name: prose above this step already discusses
+	// smoke-acp-bundled-mcp-live by name, and a needle that a comment can satisfy would drag the
+	// boundary backwards and fail an ordering that is actually fine.
+	const firstLiveAt = gateBody.indexOf('run_live_step "smoke-acp-');
+	if (doctorAt >= 0 && firstLiveAt >= 0 && doctorAt > firstLiveAt)
+		gaps.push("the doctor step runs AFTER the ACP LIVE tier — the fail-fast position that motivates it is gone");
+	if (!verify.includes("doctor-pi-provider"))
+		gaps.push("VERIFY.md does not name doctor-pi-provider in the MUST tier at all");
+	if (!verify.includes("the invocation the operator's pi provider actually EXECS"))
+		gaps.push("VERIFY.md no longer states WHICH invocation this step proves (ships vs execs)");
+	assert.ok(
+		gaps.length === 0,
+		"[QK:PI-DOCTOR-IS-RELEASE-MUST] the operator's configured bridge invocation must be booted as a release-gate " +
+			"MUST exactly once, through run_step (no SKIP arm — this doctor never emits 97), positioned BEFORE the ACP " +
+			"LIVE tier, with VERIFY naming it and keeping 'what this checkout ships' apart from 'what the provider execs' " +
+			"— drop any of those and the #81 127-class defect goes back to costing sixteen LIVE steps to discover. " +
+			`Broken: ${gaps.join("; ")}`,
+	);
+}
+
 console.log(
 	"[check-release-gate-outcomes] ok — STEP OUTCOME protocol: one skip exit code shared by the shell and TS halves " +
 		`(${LIVE_SKIP_EXIT}, clear of the per-tool 0..4 and shell 126+ bands), classifier maps 0→PASS / skip→SKIP / ` +
@@ -448,5 +500,6 @@ console.log(
 		"a run.sh wrapper declining its own prerequisite (including the measured LIVE=1 no-cortex-connection cell); and every " +
 		"LIVE smoke is either wired into release_gate or excluded by a sentence the docs still carry; and the moved " +
 		"check-gate-qualification stays reachable on its owners (absent from the default chain, exactly once in CI, " +
-		"exactly once as a release-gate MUST step) and the CI step qualifies the FULL floor, which runs before it",
+		"exactly once as a release-gate MUST step) and the CI step qualifies the FULL floor, which runs before it; and " +
+		"the operator's CONFIGURED bridge invocation is booted exactly once through run_step, before the ACP LIVE tier",
 );

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"