@junghanacs/entwurf 0.14.0 → 0.14.2

package/scripts/mutants/meta-retire.json

@@ -0,0 +1,47 @@
+{
+	"schemaVersion": 1,
+	"lane": "meta-retire",
+	"mutants": [
+		{
+			"claim": "META-RETIRE-COMPARE-TYPE",
+			"title": "comparing the current value without its JSON scalar type lets a truthy 1 pass as the true entwurf wrote, so relinquishment overwrites a value that was never ours (#71)",
+			"subject": "scripts/meta-bridge-state.py",
+			"find": [
+				"    existed, value = get_nested(settings, path)",
+				"    if existed and type(value) is type(last_managed_value) and value == last_managed_value:"
+			],
+			"replace": ["    existed, value = get_nested(settings, path)", "    if existed and value == last_managed_value:"],
+			"gate": ["bash", "run.sh", "smoke-meta-install-state"],
+			"timeoutSeconds": 300,
+			"signature": "[QK:META-RETIRE-COMPARE-TYPE]",
+			"signatureSource": "scripts/smoke-meta-install-state.sh"
+		},
+		{
+			"claim": "META-RETIRE-MALFORMED-SILENT",
+			"title": "skipping a malformed retired entry instead of failing discards the only evidence that entwurf owns the key, leaving a still-dangerous value looking operator-clean (#71)",
+			"subject": "scripts/meta-bridge-state.py",
+			"find": [
+				"        die(f\"retired scalar state entry {name} is malformed; refusing to discard ownership evidence\")"
+			],
+			"replace": ["        return"],
+			"gate": ["bash", "run.sh", "smoke-meta-install-state"],
+			"timeoutSeconds": 300,
+			"signature": "[QK:META-RETIRE-MALFORMED-SILENT]",
+			"signatureSource": "scripts/smoke-meta-install-state.sh"
+		},
+		{
+			"claim": "META-RETIRE-FRESH-TOUCH",
+			"title": "synthesising provenance when install-state carries none lets relinquishment rewrite a value the operator set themselves, the exact ownership violation #71 exists to stop",
+			"subject": "scripts/meta-bridge-state.py",
+			"find": ["    if entry is None:", "        return"],
+			"replace": [
+				"    if entry is None:",
+				"        entry = {\"kind\": \"scalar\", \"path\": path, \"original\": {\"existed\": False, \"value\": None}}"
+			],
+			"gate": ["bash", "run.sh", "smoke-meta-install-state"],
+			"timeoutSeconds": 300,
+			"signature": "[QK:META-RETIRE-FRESH-TOUCH]",
+			"signatureSource": "scripts/smoke-meta-install-state.sh"
+		}
+	]
+}

package/scripts/mutants/mux-fresh-call.json

@@ -78,15 +78,59 @@
 			"claim": "FRESHCALL-RECEIPT-WITHOUT-CORRELATION",
 			"title": "the launch receipt grows a sibling garden-id field, making an async correlation look like a synchronous return",
 			"subject": "pi-extensions/lib/mux-fresh-call.ts",
-			"find": ["\tbackend: FreshCallBackend;\n\tmodel: string;\n\truntimePath: string;\n\tnonce: string;\n}"],
-			"replace": [
-				"\tbackend: FreshCallBackend;\n\tmodel: string;\n\truntimePath: string;\n\tnonce: string;\n\tgardenId?: string;\n}"
-			],
+			"find": ["\truntimePath: string;\n\tnonce: string;\n}"],
+			"replace": ["\truntimePath: string;\n\tnonce: string;\n\tgardenId?: string;\n}"],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
 			"timeoutSeconds": 120,
 			"signature": "[QK:FRESHCALL-RECEIPT-WITHOUT-CORRELATION]",
 			"signatureSource": "test/mux-fresh-call.test.ts"
 		},
+		{
+			"claim": "FRESHCALL-CWD-ARGV",
+			"title": "the requested cwd stops reaching tmux, so a cross-repo fresh sibling silently opens in the CALLER's repo and the launch looks successful",
+			"subject": "pi-extensions/lib/mux-fresh-call.ts",
+			"find": ["\t\t...(cwd === undefined ? [] : [\"-c\", cwd]),\n"],
+			"replace": [""],
+			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:FRESHCALL-CWD-ARGV]",
+			"signatureSource": "test/mux-fresh-call.test.ts"
+		},
+		{
+			"claim": "FRESHCALL-CWD-REFUSED-PREMUTATION",
+			"title": "the pre-mutation cwd classification is ignored, so a relative/'#'/deleted/file path rides on toward tmux instead of refusing by name",
+			"subject": "pi-extensions/lib/mux-fresh-call.ts",
+			"find": ["\t\tif (badCwd) return { ok: false, reason: badCwd };"],
+			"replace": ["\t\tvoid badCwd;"],
+			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:FRESHCALL-CWD-REFUSED-PREMUTATION]",
+			"signatureSource": "test/mux-fresh-call.test.ts"
+		},
+		{
+			"claim": "FRESHCALL-CWD-RECEIPT-REQUESTED",
+			"title": "production freshCall stops assembling the requested cwd into its receipt, so the operator-visible answer silently loses the one placement fact the caller asked for",
+			"subject": "pi-extensions/lib/mux-fresh-call.ts",
+			"find": ["\t\t\t...(cwd === undefined ? {} : { cwd }),\n"],
+			"replace": [""],
+			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:FRESHCALL-CWD-RECEIPT-REQUESTED]",
+			"signatureSource": "test/mux-fresh-call.test.ts"
+		},
+		{
+			"claim": "FRESHCALL-CWD-SURFACE-PARITY",
+			"title": "one surface drops the optional cwd from its schema, so cross-repo fresh works from pi and silently cannot exist from the MCP bridge",
+			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"find": [
+				"\t\tcwd: z\n\t\t\t.string()\n\t\t\t.optional()\n\t\t\t.describe(\n\t\t\t\t\"Optional literal ABSOLUTE path of an existing directory to start the sibling in (cross-repo fresh). Omit or pass \\\"\\\" to start in this agent's own cwd. Taken exactly as given — no trim, no realpath, no project-name resolution; '#' is refused (tmux format expansion). The receipt echoes what was REQUESTED, never an observation.\",\n\t\t\t),\n"
+			],
+			"replace": [""],
+			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:FRESHCALL-CWD-SURFACE-PARITY]",
+			"signatureSource": "test/fresh-call-surfaces.contract.test.ts"
+		},
 		{
 			"claim": "FRESHCALL-PI-SURFACE-IDENTITY",
 			"title": "native pi takes the caller garden id from the environment instead of its own resident closure — the uuidv7 confusion, reintroduced",

package/scripts/mutants/mux-resume-call.json

@@ -5,7 +5,7 @@
 		{
 			"claim": "MUXRESUME-CWD-MISSING-REFUSED",
 			"title": "a deleted recorded cwd is accepted — tmux then opens the window in $HOME and the wrong-project resume looks successful",
-			"subject": "pi-extensions/lib/mux-resume-call.ts",
+			"subject": "pi-extensions/lib/classify-tmux-cwd.ts",
 			"find": ["\t\treturn \"cwd-missing\";"],
 			"replace": ["\t\treturn null;"],
 			"gate": ["bash", "run.sh", "check-mux-resume-call"],
@@ -16,7 +16,7 @@
 		{
 			"claim": "MUXRESUME-CWD-FORMAT-REFUSED",
 			"title": "the '#' refusal stops matching, so tmux format-expands the path it was handed",
-			"subject": "pi-extensions/lib/mux-resume-call.ts",
+			"subject": "pi-extensions/lib/classify-tmux-cwd.ts",
 			"find": ["\tif (cwd.includes(\"#\")) return \"cwd-format-token\";"],
 			"replace": ["\tif (cwd.includes(\"\\u0000\")) return \"cwd-format-token\";"],
 			"gate": ["bash", "run.sh", "check-mux-resume-call"],
@@ -27,7 +27,7 @@
 		{
 			"claim": "MUXRESUME-CWD-WHITESPACE-OK",
 			"title": "a quoting fear is added back as a whitespace refusal, which would reject real project directories tmux handles fine",
-			"subject": "pi-extensions/lib/mux-resume-call.ts",
+			"subject": "pi-extensions/lib/classify-tmux-cwd.ts",
 			"find": ["\tif (cwd.includes(\"#\")) return \"cwd-format-token\";"],
 			"replace": ["\tif (cwd.includes(\"#\") || /\\s/.test(cwd)) return \"cwd-format-token\";"],
 			"gate": ["bash", "run.sh", "check-mux-resume-call"],

package/scripts/mutants/release-gate.json

@@ -135,6 +135,19 @@
 			"timeoutSeconds": 180,
 			"signature": "[QK:MUX-LIFECYCLE-IS-RELEASE-MUST]",
 			"signatureSource": "scripts/check-release-gate-outcomes.ts"
+		},
+		{
+			"claim": "PI-DOCTOR-IS-RELEASE-MUST",
+			"title": "the pi-provider boot doctor is quietly dropped from the gate — the operator's CONFIGURED bridge invocation is never booted, so a 127 launcher (the #81 relocated cmd-shim class) stays invisible until smoke-acp-bundled-mcp-live sixteen LIVE steps and real model spend later",
+			"subject": "run.sh",
+			"find": [
+				"  run_step \"doctor-pi-provider (#81: the operator's CONFIGURED bridge invocation actually boots)\" gate bash \"$self\" doctor-pi-provider"
+			],
+			"replace": ["  : # pi doctor quietly dropped — the configured invocation is never booted"],
+			"gate": ["bash", "run.sh", "check-release-gate-outcomes"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:PI-DOCTOR-IS-RELEASE-MUST]",
+			"signatureSource": "scripts/check-release-gate-outcomes.ts"
 		}
 	]
 }

package/scripts/probe-bridge-command.ts

@@ -0,0 +1,330 @@
+#!/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";
+
+/** Why a probe failed. Each value is a DISTINCT operator situation, never a generic "broken". */
+export type BridgeProbeReason =
+	| "ok"
+	| "spawn-failed" // the command could not be executed at all (ENOENT / EACCES)
+	| "exited-before-tools-list" // it ran and DIED — the relocated-shim 127 class lands here
+	| "initialize-failed" // it did not complete the MCP initialize handshake before tools/list
+	| "timeout" // it stayed up but never answered — a hung/wrong binary
+	| "no-tools-array" // it answered id:2 without result.tools — not an MCP server
+	| "tool-set-mismatch"; // an MCP server, but not THIS bridge (foreign binary, or a stale build)
+
+export interface BridgeProbeResult {
+	ok: boolean;
+	reason: BridgeProbeReason;
+	/** One line, safe to print in a doctor verdict. Carries rc/signal/stderr head when relevant. */
+	detail: string;
+}
+
+export interface BridgeProbeOptions {
+	command: string;
+	args?: string[];
+	env?: NodeJS.ProcessEnv;
+	timeoutMs?: number;
+}
+
+// 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",
+] as const;
+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: string, limit = 200): string {
+	const flat = text.replace(/\s+/g, " ").trim();
+	return flat.length > limit ? `${flat.slice(0, limit)}…` : flat;
+}
+
+export function probeBridgeCommand(opts: BridgeProbeOptions): Promise<BridgeProbeResult> {
+	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: { code: number | null; signal: NodeJS.Signals | null } | undefined;
+		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 = (): Promise<void> =>
+			new Promise((finished) => {
+				if (child.exitCode !== null || child.signalCode !== null) return finished();
+				let reaped = false;
+				let hard: ReturnType<typeof setTimeout> | undefined;
+				const finish = (): void => {
+					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: BridgeProbeReason, detail: string): void => {
+			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 = (): void => {
+			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: {
+					id?: unknown;
+					error?: unknown;
+					result?: { protocolVersion?: unknown; capabilities?: unknown; serverInfo?: unknown; tools?: unknown };
+				};
+				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 as { name?: unknown })?.name)
+					.filter((n): n is string => typeof n === "string");
+				const served = new Set(names);
+				const missing = EXPECTED_TOOLS.filter((t) => !served.has(t));
+				const unexpected = names.filter((n) => !(EXPECTED_TOOLS as readonly string[]).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: string[] = [];
+					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: unknown): void => {
+			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 = (): void => {
+			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: BridgeProbeOptions;
+	if (argv[0] === "--invocation-json") {
+		let raw: unknown;
+		try {
+			raw = JSON.parse(argv[1] ?? "");
+		} catch {
+			console.error("probe-bridge-command: --invocation-json must be valid JSON");
+			process.exit(2);
+		}
+		const obj = raw as { command?: unknown; args?: unknown; env?: unknown };
+		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 as string[],
+			env: { ...process.env, ...(obj.env as Record<string, string>) },
+		};
+	} 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);
+}