@junghanacs/entwurf 0.14.1 → 0.14.2

package/mcp/entwurf-bridge/dist/scripts/doctor-pi-provider.js

@@ -1,10 +1,23 @@
 #!/usr/bin/env node
 // doctor-pi-provider — fail-loud doctor for the pi provider (entwurfProvider.mcpServers.
-// entwurf-bridge) ownership (#46 Task 2). Side-effect FREE (read-only). Uses the config.ts SSOT
+// entwurf-bridge) ownership (#46 Task 2). A BOUNDED BOOT PROBE, not a static inspector: it writes
+// no operator state, but it does exec the configured command on this host (#81). Uses the config.ts SSOT
 // `readProviderSettingsFile` so the effective (shadow-resolved) view matches what pi actually
 // loads — NOT a re-implemented merge (GPT D: a python re-impl drifts into "doctor green, runtime
 // red"). Reports user / project / EFFECTIVE command (project shadows user per-name, the
-// resolveProviderConfig rule), plus install-state ownership, and gates on stable-bin resolvability.
+// resolveProviderConfig rule), plus install-state ownership, and gates on the stable bin actually
+// BOOTING (#81) — not merely resolving. `command -v` answering yes is not evidence that pi gets a
+// bridge: on the reference host the bare name resolved through a relocated pnpm shim whose $0-derived
+// target did not exist, so the launcher exited 127, the ACP turn had no mcp__entwurf-bridge__* tool,
+// and THIS doctor still printed ok. Resolvability is kept as the first, cheaper cell so the two
+// failures stay distinguishable (nothing on PATH vs. on PATH but dead).
+//
+// The probe sends `initialize` + `tools/list` only — never a `tools/call` — so it takes no lock,
+// writes no record and delivers nothing. That bounds OUR bridge tightly (start.sh is an `exec node`,
+// so there is no grandchild). It does not make the doctor side-effect free in general: whatever the
+// operator configured is what gets executed, and a foreign launcher's own startup is its own
+// business. Running this doctor is therefore a decision to run that command. See
+// probe-bridge-command.ts, which owns the bounded reap of the child it spawns.
 //
 // Env overrides (for the hermetic smoke):
 //   PI_PROVIDER_GLOBAL_SETTINGS   default: $PI_CODING_AGENT_DIR/settings.json or ~/.pi/agent/settings.json
@@ -12,12 +25,13 @@
 //   PI_PROVIDER_STATE             default: $XDG_DATA_HOME/entwurf/pi-provider/install-state.json
 //
 // Exit: 0 ok (incl. honest "never installed / unowned" notes) · 1 hard fail (malformed settings /
-// state-owned-but-drifted / stable bin dangling).
-import { execSync } from "node:child_process";
-import { existsSync, constants as FS, readFileSync, statSync } from "node:fs";
+// state-owned-but-drifted / stable bin dangling / stable bin present but does NOT boot).
+import { execFileSync } from "node:child_process";
+import { accessSync, existsSync, constants as FS, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readProviderSettingsFile } from "../pi-extensions/lib/acp/config.js";
+import { normalizeMcpServers, readProviderSettingsFile } from "../pi-extensions/lib/acp/config.js";
+import { probeBridgeCommand } from "./probe-bridge-command.js";
 const BARE = "entwurf-bridge";
 const KEY = "entwurf-bridge";
 const home = homedir();
@@ -28,29 +42,64 @@ const xdg = process.env.XDG_DATA_HOME || join(home, ".local", "share");
 const statePath = process.env.PI_PROVIDER_STATE || join(xdg, "entwurf", "pi-provider", "install-state.json");
 let hardFail = 0;
 const log = (s) => process.stdout.write(s + "\n");
-function commandOf(settings) {
-    const entry = settings.mcpServers?.[KEY];
-    if (entry && typeof entry === "object" && typeof entry.command === "string") {
-        return entry.command;
-    }
-    return undefined;
+// Build the effective entry EXACTLY the way production does (config.ts `resolveProviderConfig`):
+// a shallow PER-NAME merge of the two `mcpServers` maps, then ONE `normalizeMcpServers` over the
+// merged map. Hand-parsing command/args (this doctor's first shape) dropped a malformed arg
+// silently and probed an invocation production never runs.
+//
+// The ORDER is load-bearing too. Normalizing each file separately validates entries production
+// never sees: a malformed server in the global map that the project map shadows is gone by the time
+// pi normalizes, yet a per-file doctor throws on it and calls a session red that in fact starts
+// fine. That is the same "the doctor's subject differs from the runtime's" defect as the silent
+// arg-drop, pointed the other way — and it is not confined to our key, since any unrelated global
+// server could trip it.
+//
+// THROWS (McpServerConfigError) when the MERGED map is malformed — the fail-loud path, caught by
+// the caller. That error names the offending SERVER and reason, not a file: after the merge an
+// entry no longer belongs to one scope, so claiming a filename here would be a guess. A non-stdio
+// (http/sse) entry is returned as `null` so the caller can say WHY it cannot be probed instead of
+// pretending it is absent.
+function mergedBridgeEntry(globalSettings, projectSettings) {
+    const mergedRaw = { ...(globalSettings.mcpServers ?? {}), ...(projectSettings.mcpServers ?? {}) };
+    const { servers } = normalizeMcpServers(mergedRaw);
+    const entry = servers.find((srv) => srv.name === KEY);
+    if (entry === undefined)
+        return undefined; // not configured in either scope
+    if ("url" in entry)
+        return null; // http/sse — a real config, but nothing to spawn
+    return {
+        command: entry.command,
+        args: entry.args,
+        // The ACP wire shape is a name/value list; collapse it to the env map a spawn wants.
+        env: Object.fromEntries(entry.env.map((kv) => [kv.name, kv.value])),
+    };
+}
+// Per-scope DISPLAY only — never validation. The scope lines exist so an operator can see which
+// file supplied the effective entry; judging shape here would re-introduce the per-file validation
+// the merge rule above exists to avoid.
+function describeScope(settings) {
+    const raw = settings.mcpServers?.[KEY];
+    if (raw === undefined)
+        return "entwurf-bridge NOT configured";
+    const cmd = raw?.command;
+    return typeof cmd === "string" ? `'${cmd}'` : "configured (shape judged in the merged view)";
 }
 // Does the command resolve in the environment (best local proxy for "where pi/agy runs")?
 // A bare name is looked up on PATH; a path must be an executable file.
 function resolvable(cmd) {
     if (cmd.includes("/")) {
         try {
-            statSync(cmd);
-            // eslint-disable-next-line no-bitwise
-            return (statSync(cmd).mode & FS.S_IXUSR) !== 0;
+            accessSync(cmd, FS.X_OK);
+            return true;
         }
         catch {
             return false;
         }
     }
     try {
-        // `command -v` is a POSIX sh builtin; use the default /bin/sh (NixOS has no /bin/bash).
-        execSync(`command -v ${cmd}`, { stdio: "ignore" });
+        // `command -v` is a POSIX sh builtin. Pass the configured name as argv, never shell text:
+        // an unowned override is still operator data and must not become a doctor injection surface.
+        execFileSync("sh", ["-c", 'command -v -- "$1" >/dev/null 2>&1', "sh", cmd], { stdio: "ignore" });
         return true;
     }
     catch {
@@ -59,23 +108,39 @@ function resolvable(cmd) {
 }
 log("[pi-provider doctor]");
 // Read via the SSOT — a malformed settings file THROWS here (fail-loud, named file).
-let userCmd;
-let projCmd;
+let effectiveEntry;
+let userScopeDesc = "";
+let projScopeDesc = "";
+let effectiveScope = "none";
 try {
-    userCmd = commandOf(readProviderSettingsFile(globalPath).settings);
-    projCmd = commandOf(readProviderSettingsFile(projectPath).settings);
+    const userSettings = readProviderSettingsFile(globalPath).settings;
+    const projSettings = readProviderSettingsFile(projectPath).settings;
+    userScopeDesc = describeScope(userSettings);
+    projScopeDesc = describeScope(projSettings);
+    // EFFECTIVE = project shadows user per-NAME. The whole ENTRY shadows, not a field of it, so
+    // command, args and env always come from one scope; the scope label is decided by which map
+    // owns the key, which is exactly what the merge spread resolves.
+    effectiveEntry = mergedBridgeEntry(userSettings, projSettings);
+    const ownsKey = (m) => m !== undefined && Object.hasOwn(m, KEY);
+    effectiveScope = ownsKey(projSettings.mcpServers)
+        ? "project"
+        : ownsKey(userSettings.mcpServers)
+            ? "user(global)"
+            : "none";
 }
 catch (err) {
     log(`  FAIL: ${err instanceof Error ? err.message : String(err)}`);
     process.exit(1);
 }
-// EFFECTIVE = project shadows user per-name (the resolveProviderConfig merge rule).
-const effectiveCmd = projCmd ?? userCmd;
-const effectiveScope = projCmd !== undefined ? "project" : userCmd !== undefined ? "user(global)" : "none";
+const effectiveDesc = effectiveEntry === undefined
+    ? "entwurf-bridge NOT configured"
+    : effectiveEntry === null
+        ? "configured as an http/sse server"
+        : `'${effectiveEntry.command}'`;
 log("── scopes (project shadows user per-name)");
-log(`  user(global) ${globalPath}: ${userCmd ? `'${userCmd}'` : "entwurf-bridge NOT configured"}`);
-log(`  project      ${projectPath}: ${projCmd ? `'${projCmd}'` : "entwurf-bridge NOT configured"}`);
-log(`  EFFECTIVE (${effectiveScope}): ${effectiveCmd ? `'${effectiveCmd}'` : "none"}`);
+log(`  user(global) ${globalPath}: ${userScopeDesc}`);
+log(`  project      ${projectPath}: ${projScopeDesc}`);
+log(`  EFFECTIVE (${effectiveScope}): ${effectiveDesc}`);
 // install-state ownership (user scope). absent state on a configured effective is either a
 // pre-Task-2 install or a user-override we deliberately did not own.
 let ownership;
@@ -94,33 +159,60 @@ else {
     log("  state: no user-scope install-state.");
 }
 log("── verdict");
-if (effectiveCmd === undefined) {
+if (effectiveEntry === undefined) {
     log("  note: no entwurfProvider.mcpServers.entwurf-bridge in any scope (never installed — this is the '?'; run ./run.sh setup).");
 }
-else if (effectiveCmd === BARE) {
-    if (resolvable(effectiveCmd)) {
-        log(`  ok: effective command is the bare stable bin '${BARE}' and it RESOLVES.`);
-    }
-    else {
-        log(`  FAIL: effective command is '${BARE}' but it does NOT resolve (run ./run.sh expose-dev-bin / npm bin-link).`);
-        hardFail = 1;
-    }
+else if (effectiveEntry === null) {
+    // A real, well-formed config that this bridge cannot be: entwurf-bridge is a stdio server, so
+    // an http/sse entry under our key means pi would connect to something that is not us. Nothing
+    // here is spawnable, so there is no boot to prove — say that plainly rather than reporting the
+    // absence of a failure as ok.
+    log(`  FAIL: entwurf-bridge is configured as an http/sse server in ${effectiveScope} scope. This bridge is a stdio server — pi would reach something that is not entwurf, and no boot evidence is possible. Restore a stdio entry with ./run.sh setup, or remove the key if the override is deliberate.`);
+    hardFail = 1;
 }
 else {
-    // effective is NOT the bare bin. If state says we own it → drift (FAIL). Otherwise classify
-    // the effective command honestly: our OWN legacy repo start.sh (not yet adopted) is NOT a
-    // user override — say so distinctly so "run setup" is the clear next step. A truly foreign
-    // command is an unowned override left as the operator's choice. Neither is a hard fail.
-    const isLegacyManaged = effectiveCmd.endsWith("/entwurf/mcp/entwurf-bridge/start.sh");
-    if (ownership && ownership !== "user-override") {
-        log(`  FAIL: state owns entwurf-bridge (ownership=${ownership}) but the effective command drifted to '${effectiveCmd}'.`);
+    const cmd = effectiveEntry.command;
+    const isBare = cmd === BARE;
+    const isLegacyManaged = cmd.endsWith("/entwurf/mcp/entwurf-bridge/start.sh");
+    // Runtime truth is independent of ownership truth. An unowned override remains the operator's
+    // choice, but it still shadows the stable bridge in production; calling a dead override green
+    // repeats #81 under a different spelling. Probe the exact normalized command + args + env for
+    // EVERY effective stdio entry, then classify who owns that entry separately below.
+    if (!resolvable(cmd)) {
+        log(`  FAIL: effective command '${cmd}' does NOT resolve or is not executable.`);
         hardFail = 1;
     }
-    else if (isLegacyManaged) {
-        log(`  note: effective is our LEGACY managed repo path ('${effectiveCmd}'), not yet adopted to the bare stable bin. Run ./run.sh setup to normalize (this is the pre-Task-2 '?').`);
-    }
     else {
-        log(`  note: entwurf-bridge is an UNOWNED override ('${effectiveCmd}') — effective is not the stable bin. Left as the operator's choice (run ./run.sh setup to adopt the bare bin).`);
+        log(`  effective command '${cmd}' RESOLVES — probing the exact configured invocation…`);
+        const probe = await probeBridgeCommand({
+            command: cmd,
+            args: effectiveEntry.args,
+            env: { ...process.env, ...effectiveEntry.env },
+        });
+        if (probe.ok) {
+            log(isBare
+                ? `  ok: effective command is the bare stable bin '${BARE}' and it BOOTS — ${probe.detail}`
+                : `  runtime: configured override BOOTS — ${probe.detail}`);
+        }
+        else {
+            log(`  FAIL: effective invocation does NOT serve MCP [${probe.reason}] — ${probe.detail}`);
+            log(`         Diagnose its launcher and configured args/env; entwurf will not overwrite an unowned command.`);
+            hardFail = 1;
+        }
+    }
+    if (!isBare) {
+        // Ownership classification never rounds a broken runtime up to green. It only says who may
+        // repair the non-canonical entry after the independent boot verdict above.
+        if (ownership && ownership !== "user-override") {
+            log(`  FAIL: state owns entwurf-bridge (ownership=${ownership}) but the effective command drifted to '${cmd}'.`);
+            hardFail = 1;
+        }
+        else if (isLegacyManaged) {
+            log(`  note: effective is our LEGACY managed repo path ('${cmd}'), not yet adopted to the bare stable bin. Run ./run.sh setup to normalize.`);
+        }
+        else {
+            log(`  note: entwurf-bridge is an UNOWNED override ('${cmd}'). Runtime was judged above; run ./run.sh setup only if you choose to adopt the bare stable bin.`);
+        }
     }
 }
 if (hardFail) {

package/mcp/entwurf-bridge/dist/scripts/probe-bridge-command.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// probe-bridge-command — does the EFFECTIVE bridge command actually BOOT and serve MCP?
+//
+// WHY THIS EXISTS (#81): every doctor that judged the bridge wiring asked only whether the
+// configured command RESOLVES — `command -v <bare name>` for pi (doctor-pi-provider) and agy
+// (agy-bridge.sh). Resolvability is not bootability, and the gap is not theoretical: on the
+// reference host `~/.local/bin/entwurf-bridge` was a symlink to the canonical pnpm shim, and
+// that shim derives its target from `$0`. Invoked through the relocated link the derived
+// `../global/...` path does not exist, so the launcher exits 127 and the MCP child never boots
+// — while `command -v` kept answering yes and both doctors kept printing ok. The model in a
+// Pi-hosted ACP turn then had no `mcp__entwurf-bridge__*` tool at all, which is a direct
+// violation of #81's minimum core value (explicit Entwurf bridge connectivity).
+//
+// So this leaf asks the only question that carries the claim: run the command, speak MCP to it,
+// and require the entwurf tool surface back. A green here is about the command the harness
+// actually execs — never a recomputed desired one (the same rule meta-bridge-doctor's delivery
+// self-diagnostic already states for the Claude lane).
+//
+// SIDE EFFECTS: none on operator state. Only `initialize` + `tools/list` are sent — never a
+// `tools/call` — so no lock is taken, no record is written, and no message is delivered. The
+// child is killed as soon as the frame arrives or the deadline passes. This is what makes the
+// probe affordable inside a doctor an operator runs repeatedly.
+//
+// USAGE
+//   library:  const r = await probeBridgeCommand({ command, args });   // doctor-pi-provider.ts
+//   CLI:      node probe-bridge-command.ts <command> [args...]
+//             node probe-bridge-command.ts --invocation-json '{"command":"…","args":[],"env":{}}'
+//             exit 0 = booted and served the entwurf tool surface; 1 = did not (reason on stdout).
+import { spawn } from "node:child_process";
+import { basename } from "node:path";
+// The EXACT public verb set of the current bridge. Identity is the whole set, not one member:
+// the #81 symptom was a session whose schema lacked `entwurf_self` specifically, and a probe that
+// only looked for `entwurf_v2` would have called that host healthy. Exactness also catches the
+// other direction — a STALE build still serving a retired verb, or a foreign binary that happens
+// to expose an `entwurf_v2`. check-entwurf-bridge-boot binds this list to the real runtime
+// tools/list, so a verb added or retired without updating it turns that gate red.
+export const EXPECTED_TOOLS = [
+    "entwurf_v2",
+    "entwurf_self",
+    "entwurf_peers",
+    "entwurf_inbox_read",
+    "entwurf_register_native",
+    "entwurf_fresh_call",
+    "entwurf_resume_call",
+];
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** How long a probed child gets to die politely before it is killed outright. */
+const CLEANUP_GRACE_MS = 500;
+/** Collapse captured stderr into one printable line — a doctor verdict must stay one line. */
+function head(text, limit = 200) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > limit ? `${flat.slice(0, limit)}…` : flat;
+}
+export function probeBridgeCommand(opts) {
+    const { command, args = [], env, timeoutMs = DEFAULT_TIMEOUT_MS } = opts;
+    return new Promise((resolve) => {
+        // No shell: a bare name goes through the normal PATH lookup the harness itself does,
+        // and an argument can never be reinterpreted as shell syntax.
+        const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"], env });
+        // `write()` reports a synchronous closed pipe by throwing, but a launcher that dies on exec
+        // closes stdin under us and the resulting EPIPE arrives ASYNCHRONOUSLY, as an 'error' event on
+        // the stream. Unlistened, Node turns that into an uncaught exception, so the probe dies
+        // printing its own stack trace INSTEAD of the launcher's stderr: precisely the diagnosis #81
+        // exists to surface, destroyed in the one cell that needs it. The window is real, not
+        // theoretical — under CPU contention the child can exec, write its stderr and exit between
+        // uv_spawn and our first write, which is how CI saw a doctor verdict with no launcher stderr
+        // in it. The `close` handler owns the verdict for that child (with captured stderr), so this
+        // listener is installed before anything can write and stays deliberately silent — one reason
+        // per failure, never an unhandled probe crash.
+        child.stdin.on("error", () => { });
+        let stdoutPending = "";
+        let stderr = "";
+        let settled = false;
+        let initialized = false;
+        let exited;
+        let stderrEnded = false;
+        // This probe deliberately runs whatever command the operator configured — including a
+        // foreign or broken one — so it owns closing what it opened. Escalate SIGTERM → SIGKILL
+        // once, bounded: cleanup for THIS child, not a supervisor (no retries, no watching, no
+        // process-tree walking).
+        //
+        // The reap is AWAITED before the result resolves, and that ordering is load-bearing: the
+        // callers are doctors that print a verdict and `process.exit()` immediately, which tears
+        // down any still-pending timer. A fire-and-forget SIGTERM plus a deferred SIGKILL would
+        // therefore leave a TERM-ignoring launcher running after the doctor is gone — the probe
+        // would leak exactly the kind of broken process it exists to detect.
+        const reap = () => new Promise((finished) => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return finished();
+            let reaped = false;
+            let hard;
+            const finish = () => {
+                if (reaped)
+                    return;
+                reaped = true;
+                if (hard)
+                    clearTimeout(hard);
+                finished();
+            };
+            child.once("close", finish);
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                return finish(); // already gone
+            }
+            hard = setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch { }
+                // SIGKILL cannot be trapped, so `close` follows. The outer bound exists only so a
+                // child already reaped by someone else can never hang this promise forever.
+                setTimeout(finish, CLEANUP_GRACE_MS);
+            }, CLEANUP_GRACE_MS);
+        });
+        const done = (reason, detail) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            void reap().then(() => resolve({ ok: reason === "ok", reason, detail }));
+        };
+        const timer = setTimeout(() => {
+            const waitingFor = initialized ? "tools/list" : "initialize";
+            done("timeout", `'${command}' stayed up but never answered ${waitingFor} within ${timeoutMs}ms` +
+                (stderr.trim() ? ` — stderr: ${head(stderr)}` : ""));
+        }, timeoutMs);
+        child.on("error", (err) => {
+            done("spawn-failed", `'${command}' could not be executed: ${String(err)}`);
+        });
+        // `ChildProcess` close is normally after the stdio pipes close, but under nested shell
+        // capture that ordering has raced on this host. Do not mint a no-stderr diagnosis until the
+        // stderr reader ended: the launcher's own final diagnostic is part of the operator verdict.
+        const reportExited = () => {
+            if (!exited || !stderrEnded)
+                return;
+            // Reaching here un-settled means the process died before answering id:2. This is the
+            // cell the relocated pnpm shim lands in (exit 127), and the stderr head is what tells
+            // the operator WHICH launcher hop broke.
+            done("exited-before-tools-list", `'${command}' exited before answering tools/list (code=${exited.code} signal=${String(exited.signal)})` +
+                (stderr.trim() ? ` — stderr: ${head(stderr)}` : " — no stderr"));
+        };
+        child.on("close", (code, signal) => {
+            exited = { code, signal };
+            reportExited();
+        });
+        child.stderr.on("data", (d) => {
+            stderr += String(d);
+        });
+        child.stderr.on("end", () => {
+            stderrEnded = true;
+            reportExited();
+        });
+        child.stdout.on("data", (d) => {
+            const chunk = String(d);
+            stdoutPending += chunk;
+            if (settled)
+                return;
+            // MCP frames are newline-delimited JSON-RPC. Consume each complete frame exactly once:
+            // replaying the accumulated id:1 response on a later data event would send a second
+            // tools/list before the first reply and stop being a sequential handshake.
+            const frames = stdoutPending.split("\n");
+            stdoutPending = frames.pop() ?? "";
+            for (const line of frames) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                let msg;
+                try {
+                    msg = JSON.parse(trimmed);
+                }
+                catch {
+                    continue;
+                }
+                if (msg?.id === 1) {
+                    const result = msg.result;
+                    const valid = msg.error === undefined &&
+                        result?.protocolVersion === "2024-11-05" &&
+                        typeof result.capabilities === "object" &&
+                        result.capabilities !== null &&
+                        typeof result.serverInfo === "object" &&
+                        result.serverInfo !== null;
+                    if (!valid) {
+                        done("initialize-failed", `'${command}' returned an invalid MCP initialize response`);
+                        return;
+                    }
+                    initialized = true;
+                    sendReadyFrames();
+                    continue;
+                }
+                if (msg?.id !== 2)
+                    continue;
+                if (!initialized) {
+                    done("initialize-failed", `'${command}' answered tools/list before MCP initialize completed`);
+                    return;
+                }
+                const tools = msg?.result?.tools;
+                if (!Array.isArray(tools)) {
+                    done("no-tools-array", `'${command}' answered tools/list without result.tools — not an MCP server`);
+                    return;
+                }
+                const names = tools
+                    .map((t) => t?.name)
+                    .filter((n) => typeof n === "string");
+                const served = new Set(names);
+                const missing = EXPECTED_TOOLS.filter((t) => !served.has(t));
+                const unexpected = names.filter((n) => !EXPECTED_TOOLS.includes(n));
+                if (missing.length > 0 || unexpected.length > 0) {
+                    // Name BOTH directions: a missing verb is the #81 symptom (the model had no
+                    // entwurf_self), an unexpected one means this is not the bridge we ship.
+                    const parts = [];
+                    if (missing.length > 0)
+                        parts.push(`missing ${missing.join(", ")}`);
+                    if (unexpected.length > 0)
+                        parts.push(`unexpected ${unexpected.join(", ")}`);
+                    done("tool-set-mismatch", `'${command}' is an MCP server but does not serve this bridge's verb set — ${parts.join("; ")} (served: ${names.join(", ") || "none"})`);
+                    return;
+                }
+                done("ok", `'${command}' booted and served the exact entwurf verb set (${EXPECTED_TOOLS.length} tools)`);
+                return;
+            }
+        });
+        const send = (obj) => {
+            try {
+                child.stdin.write(`${JSON.stringify(obj)}\n`);
+            }
+            catch {
+                // Synchronous throws (a destroyed stream) land here; async EPIPE lands on the
+                // listener above. Both are the same verdict-free silence.
+            }
+        };
+        const sendReadyFrames = () => {
+            send({ jsonrpc: "2.0", method: "notifications/initialized" });
+            send({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+        };
+        send({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "probe-bridge-command", version: "0" },
+            },
+        });
+    });
+}
+// CLI entrypoint. Kept argv-driven (no env carrier) so `./run.sh probe-bridge-command entwurf-bridge`
+// asks about exactly the name an operator typed, and a doctor can shell out to the same verdict.
+// Match the BASENAME exactly. A suffix test would also fire for `check-probe-bridge-command.ts`,
+// which imports this module — the CLI arm would then hijack that gate's argv and exit 2.
+if (process.argv[1] && /^probe-bridge-command\.(ts|js)$/.test(basename(process.argv[1]))) {
+    const argv = process.argv.slice(2);
+    let options;
+    if (argv[0] === "--invocation-json") {
+        let raw;
+        try {
+            raw = JSON.parse(argv[1] ?? "");
+        }
+        catch {
+            console.error("probe-bridge-command: --invocation-json must be valid JSON");
+            process.exit(2);
+        }
+        const obj = raw;
+        if (typeof obj?.command !== "string" ||
+            !obj.command ||
+            !Array.isArray(obj.args) ||
+            !obj.args.every((arg) => typeof arg === "string") ||
+            typeof obj.env !== "object" ||
+            obj.env === null ||
+            Array.isArray(obj.env) ||
+            !Object.values(obj.env).every((value) => typeof value === "string")) {
+            console.error("probe-bridge-command: invocation JSON requires string command, string[] args, string-map env");
+            process.exit(2);
+        }
+        options = {
+            command: obj.command,
+            args: obj.args,
+            env: { ...process.env, ...obj.env },
+        };
+    }
+    else {
+        const [command, ...args] = argv;
+        if (!command) {
+            console.error("usage: probe-bridge-command <command> [args...]");
+            process.exit(2);
+        }
+        options = { command, args };
+    }
+    const result = await probeBridgeCommand(options);
+    console.log(`[probe-bridge-command] ${result.reason}: ${result.detail}`);
+    process.exit(result.ok ? 0 : 1);
+}

package/mcp/entwurf-bridge/tsconfig.build.json

@@ -42,13 +42,16 @@
 	//
 	// It is a TYPE closure, not a boot closure, and the difference is shipped bytes.
 	// The retired claim here ("the pi-lane-only acp/* stays out of the tarball") is
-	// FALSE: dist/pi-extensions/lib/acp/ carries 8 modules (acp-client, backend-adapter,
-	// config, context, engraving, models, overlay, tool-surface) that no bridge code
-	// path executes — tsc followed a type reference and emitted them. Dead emit is a
+	// FALSE: dist/pi-extensions/lib/acp/ is not a boot closure. config.js IS reached —
+	// doctor-pi-provider (#81) value-imports it. The other 7 modules (acp-client,
+	// backend-adapter, context, engraving, models, overlay, tool-surface) execute on
+	// no bridge/operator path: tsc followed config.ts's `import type { AcpBackendAdapter }`
+	// and emitted backend-adapter.js, which value-imports the rest. Dead emit is a
 	// correctness question only for anything that reads its own location (see the
-	// registry corpse), but it is dead weight in every consumer's tarball. Cleanup is
+	// registry corpse), but the 7 are dead weight in every consumer's tarball. Cleanup is
 	// tracked as a follow-up, and the choice is one of two: narrow the emit, or ship
-	// the assets those modules expect. Do NOT restore the old sentence.
+	// the assets those modules expect. Do NOT restore the old sentence, and do NOT
+	// put config.js back on the dead list.
 	//
 	// WHY store-doctor rides THIS build: meta-bridge-doctor.sh's full store scan
 	// must run from an INSTALLED package (under node_modules, where strip-types is
@@ -86,6 +89,12 @@
 	// and run_ts refuses them under an installed package rather than emitting 70+
 	// gate leaves into the tarball.
 	//
+	// WHY probe-bridge-command rides this build (#81): doctor-pi-provider IMPORTS it, and that
+	// doctor is one of the three operator commands above — so on an installed host the import
+	// resolves under node_modules where strip-types is refused. Emitting the leaf keeps the
+	// installed doctor's new boot cell alive; a missing twin would kill the doctor before its
+	// first verdict line. Its only imports are node builtins, so it adds ZERO new deps.
+	//
 	// WHY meta-facts rides this build (#65): it is the operator projection external
 	// consumers call INSTEAD of parsing the store, and those consumers live on
 	// INSTALLED hosts — under node_modules, where run_ts needs a compiled twin.
@@ -107,6 +116,7 @@
 		"../../scripts/meta-bridge-store-doctor.ts",
 		"../../scripts/agy-imprint.ts",
 		"../../scripts/doctor-pi-provider.ts",
+		"../../scripts/probe-bridge-command.ts",
 		"../../scripts/new-session-id.ts",
 		"../../scripts/meta-bridge-prune.ts",
 		"../../scripts/meta-bridge-fresh-cut.ts",