@junghanacs/entwurf 0.12.6 → 0.12.7

package/mcp/entwurf-bridge/dist/pi-extensions/lib/native-push/adapter.js

@@ -0,0 +1,158 @@
+/**
+ * native-push adapter rail — the transport LEAF by which a native-push backend
+ * (antigravity, the first) is (1) probed for a LIVE conversation and (2) direct-injected
+ * with a message. Mirrors the ACP backend-adapter rail (acp/backend-adapter.ts §ADAPTERS
+ * /resolveAcpBackendAdapter): one interface, one registry, a fail-fast resolver.
+ *
+ * Purity contract (봉인 3):
+ *  - LEAF: this file imports NO entwurf-core / no decider / no meta-session — only node
+ *    builtins + type-only contract types. So the pi-free MCP bridge (entwurf_register_native)
+ *    can reach it at boot without re-coupling to pi, and the decider stays pure.
+ *  - injectable runner: every process call goes through the injected `NativePushRunner`,
+ *    so `check-native-push-adapter` drives probe/send with a fake — no real agy needed.
+ *  - VOLATILE route: a probe's `route` (the live LS address serving the conversation) is
+ *    NEVER stored — every probe re-scans and re-discovers it (the LS port is per-process
+ *    and shifts). `check-native-push-adapter` asserts a repeated probe re-runs the scan.
+ *  - NO retry HERE: `send` is a single attempt that throws on failure. The 1-shot
+ *    re-probe→re-send on failure is the EXECUTOR hand's job (step ⑥ — decider purity /
+ *    control-socket send-fallback mirror), NOT the adapter's.
+ *
+ * The probe corrects raw-agy-send.sh:16's `pgrep -x agy | head -1` single-pid assumption:
+ * it scans EVERY host pid, since the conversation may be served by any live host process.
+ */
+import { execFile } from "node:child_process";
+import * as os from "node:os";
+import * as path from "node:path";
+// The agy agentapi calls are bounded so a dead/stalled LS route cannot hang a dispatch
+// (raw-agy-send.sh used `timeout 8` — production had lost that; Q12 restores it). pgrep/ss
+// are fast local scans and stay unbounded.
+export const AGY_METADATA_TIMEOUT_MS = 8000;
+export const AGY_SEND_TIMEOUT_MS = 8000;
+/** The production runner — `execFile` (no shell), env overlay, bounded, output captured. */
+export const realNativePushRunner = {
+    exec(argv, opts) {
+        return new Promise((resolve) => {
+            const [cmd, ...args] = argv;
+            execFile(cmd ?? "", args, {
+                env: opts?.env ? { ...process.env, ...opts.env } : process.env,
+                maxBuffer: 8 * 1024 * 1024,
+                timeout: opts?.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs : 0,
+            }, (err, stdout, stderr) => {
+                const e = err;
+                // A timeout kill surfaces as `killed` — map it to 124 (timeout convention) so
+                // probe reads it as "no serve" (→ indeterminate) and send reads it as failure.
+                const code = e == null ? 0 : e.killed ? 124 : typeof e.code === "number" ? e.code : 127;
+                resolve({ code, stdout: stdout ?? "", stderr: stderr ?? "" });
+            });
+        });
+    },
+};
+/** Resolve the agy binary — $AGY_BIN, else ~/.local/bin/agy (raw-agy-send.sh:14). */
+export function resolveAgyBinary() {
+    const env = process.env.AGY_BIN?.trim();
+    if (env)
+        return env;
+    return path.join(os.homedir(), ".local", "bin", "agy");
+}
+/** Parse `ss -lntp` output into a pid → [127.0.0.1:PORT, …] map (localhost listeners). */
+function parseSsListeners(ssStdout) {
+    const byPid = new Map();
+    for (const line of ssStdout.split("\n")) {
+        const addr = line.match(/127\.0\.0\.1:([0-9]+)/);
+        if (!addr)
+            continue;
+        // ss -lntp tags the owner as `pid=<n>,`; a line may carry several `pid=` when the
+        // socket is shared, so collect them all.
+        for (const m of line.matchAll(/pid=([0-9]+),/g)) {
+            const pid = Number(m[1]);
+            const list = byPid.get(pid) ?? [];
+            list.push(`127.0.0.1:${addr[1]}`);
+            byPid.set(pid, list);
+        }
+    }
+    return byPid;
+}
+export function createAntigravityAdapter(deps) {
+    const { runner } = deps;
+    const binary = deps.binary ?? resolveAgyBinary();
+    const processName = deps.processName ?? "agy";
+    async function scanHostPids() {
+        // pgrep -x <name> — ALL matching pids (raw-agy-send.sh:16 `head -1` corrected here).
+        const r = await runner.exec(["pgrep", "-x", processName]);
+        if (r.code !== 0)
+            return []; // pgrep exit != 0 → no matching process
+        return r.stdout
+            .split("\n")
+            .map((s) => s.trim())
+            .filter((s) => /^[0-9]+$/.test(s))
+            .map((s) => Number(s));
+    }
+    async function servesConversation(lsAddress, conversationId) {
+        const r = await runner.exec([binary, "agentapi", "get-conversation-metadata", conversationId], {
+            env: { ANTIGRAVITY_LS_ADDRESS: lsAddress },
+            timeoutMs: AGY_METADATA_TIMEOUT_MS,
+        });
+        // A non-zero code — not-found, error, OR a timeout kill (124) — means this port does not
+        // serve the conversation; the scan moves on (a timeout never blocks the whole probe).
+        return r.code === 0 && r.stdout.includes("conversationMetadata");
+    }
+    return {
+        id: "antigravity",
+        async probe(nativeSessionId) {
+            const pids = await scanHostPids();
+            if (pids.length === 0) {
+                return { status: "dead", reason: `no live ${processName} process (native-push target has no host)` };
+            }
+            // ONE ss scan per probe (re-derived every call — no cross-dispatch cache).
+            const ss = await runner.exec(["ss", "-lntp"]);
+            const portsByPid = ss.code === 0 ? parseSsListeners(ss.stdout) : new Map();
+            // Scan EVERY pid's ports — the conversation may be served by any live host, so a
+            // head -1 single-pid assumption (raw-agy-send.sh:16) would misroute.
+            for (const pid of pids) {
+                for (const lsAddress of portsByPid.get(pid) ?? []) {
+                    if (await servesConversation(lsAddress, nativeSessionId)) {
+                        return { status: "alive", route: { lsAddress } };
+                    }
+                }
+            }
+            // Host(s) alive but no LS port served this conversation: INDETERMINATE, not dead
+            // (a WAL/loading race or a different host instance). Never coerce absence-of-proof
+            // into `dead` — that would be a hard reject on a maybe-live conversation.
+            return {
+                status: "indeterminate",
+                reason: `${processName} live (${pids.length} pid(s)) but no LS port served conversation ${nativeSessionId}`,
+            };
+        },
+        async send(route, nativeSessionId, content) {
+            const r = await runner.exec([binary, "agentapi", "send-message", nativeSessionId, content], {
+                env: { ANTIGRAVITY_LS_ADDRESS: route.lsAddress },
+                timeoutMs: AGY_SEND_TIMEOUT_MS,
+            });
+            // A non-zero code — including a timeout kill (124) on a stalled route — THROWS
+            // (fail-loud); the executor hand owns the 1-shot re-probe→re-send on that throw.
+            if (r.code !== 0) {
+                throw new Error(`native-push send failed (agentapi send-message exit ${r.code}) via ${route.lsAddress}: ${r.stderr.trim() || "(no stderr)"}`);
+            }
+        },
+    };
+}
+/** The production antigravity adapter (real runner + env-resolved binary). */
+export const antigravityAdapter = createAntigravityAdapter({ runner: realNativePushRunner });
+// ── registry + fail-fast resolver (mirror resolveAcpBackendAdapter) ──────────
+const ADAPTERS = [antigravityAdapter];
+/**
+ * Resolve the native-push adapter that owns backend `id`. Fail-fast, like
+ * resolveAcpBackendAdapter: 0 matches → throw (unknown backend, no silent default);
+ * 2+ matches → throw (a startup-visible registry bug). A second native-push backend
+ * appends to ADAPTERS with its own id and this proves no two adapters claim one id.
+ */
+export function resolveNativePushAdapter(id) {
+    const matches = ADAPTERS.filter((a) => a.id === id);
+    if (matches.length === 0) {
+        throw new Error(`entwurf: no native-push adapter owns backend id ${JSON.stringify(id)}`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`entwurf: backend id ${JSON.stringify(id)} is claimed by multiple native-push adapters`);
+    }
+    return matches[0];
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/native-push/register.js

@@ -0,0 +1,61 @@
+/**
+ * native-push/register — the pure-ish core of the `entwurf_register_native` MCP tool
+ * (봉인 5). It REGISTERS an already-running native conversation (antigravity) as a garden
+ * citizen; it does NOT spawn one (that is the deferred v2 fresh-mint capability — kept
+ * distinct so a caller never confuses "bind an existing conversation" with "create a new
+ * sibling").
+ *
+ * Flow (봉인 5):
+ *   1. Resolve the native-push adapter for the backend and PROBE the conversation. Only a
+ *      LIVE, verifiable conversation may be registered — a dead/indeterminate probe throws,
+ *      so we never engrave a garden id onto a pointer that does not resolve to a real host.
+ *   2. Reuse `upsertMetaSession` (scan-by-nativeId → create/attach). Re-registration attaches
+ *      to the SAME garden id and refreshes the cwd; the meta-record authority rules (duplicate
+ *      nativeSessionId / backend↔wakeMode contradiction) are inherited unchanged.
+ *
+ * Receiver-marker abstinence (보정①): this module NEVER writes a receiver marker. That marker
+ * means "idle-wake mailbox watch armed" and is a MAILBOX-only atom; a native-push citizen has
+ * no mailbox and no watch, so arming one would smuggle native-push liveness into the mailbox
+ * deliverability semantics. `check-native-push-register` asserts this file references no
+ * receiver-marker writer. (A dedicated register-provenance slot is a future concern.)
+ *
+ * LEAF-adjacent + pi-free: imports only the native-push adapter (pi-free) and the meta-session
+ * upsert (pi-free), so the harness-neutral MCP bridge can reach it at boot.
+ */
+import { upsertMetaSession } from "../meta-session.js";
+import { resolveNativePushAdapter } from "./adapter.js";
+/**
+ * Register (or re-attach) a live native conversation as a garden citizen. Throws if the
+ * conversation is not live (probe status !== "alive") — a non-live conversation cannot become
+ * an addressable citizen. On success returns the garden id + the create/attach action.
+ */
+export async function registerNativeConversation(input, deps = {}) {
+    const resolveAdapter = deps.resolveAdapter ?? resolveNativePushAdapter;
+    const adapter = resolveAdapter(input.backend);
+    const probe = await adapter.probe(input.nativeSessionId);
+    if (probe.status !== "alive") {
+        throw new Error(`entwurf_register_native: refusing to register ${input.backend} conversation ${JSON.stringify(input.nativeSessionId)} — it is not live (${probe.status}: ${probe.reason}). Only a live, verifiable conversation can be ` +
+            `registered as a garden citizen; open/resume it, then retry.`);
+    }
+    // Reuse the meta-record upsert authority (scan-by-nativeId → create/attach). model /
+    // transcriptPath are null: a native app-server conversation exposes neither to us. cwd is
+    // the caller-stated value (refreshed on attach). NO receiver marker is written here (보정①).
+    const result = upsertMetaSession({
+        input: {
+            backend: input.backend,
+            nativeSessionId: input.nativeSessionId,
+            cwd: input.cwd,
+            model: null,
+            transcriptPath: null,
+        },
+        dir: deps.sessionsDir,
+        now: deps.now,
+    });
+    return {
+        action: result.action,
+        gardenId: result.record.gardenId,
+        backend: result.record.backend,
+        nativeSessionId: result.record.nativeSessionId,
+        cwd: result.record.cwd,
+    };
+}

package/mcp/entwurf-bridge/dist/scripts/agy-imprint.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * entwurf-agy-imprint — Antigravity PreInvocation birth hook.
+ *
+ * Reads agy's camelCase PreInvocation payload from stdin, idempotently upserts an
+ * antigravity meta-session by conversationId, writes the sender marker that lets the
+ * entwurf-bridge MCP child name this conversation as the caller, and ALWAYS prints exactly
+ * the PreInvocation neutral response so the agy loop keeps running.
+ *
+ * Still deliberately thin: no transcript hydration, no cwd guessing from process.cwd(), and
+ * NO receiver marker — that is a mailbox atom, and agy is a native-push citizen with no
+ * mailbox (보정①). The record body is the authority; the sender marker is only a pid→garden
+ * hint the bridge re-validates against it.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parentPid, processStartKey, upsertMetaSession, writeMetaSenderMarker, } from "../pi-extensions/lib/meta-session.js";
+const NEUTRAL_RESPONSE = '{"injectSteps":[]}';
+function logPath() {
+    const root = process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state");
+    return path.join(root, "entwurf", "agy-imprint.log");
+}
+function logLine(message) {
+    try {
+        const file = logPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${new Date().toISOString()} ${message}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // Logging is best-effort; never break agy's PreInvocation loop.
+    }
+}
+/**
+ * OPT-IN owner-topology trace (`ENTWURF_AGY_TRACE_OWNER=1`).
+ *
+ * The whole sender lane rests on one measured fact: this hook's parent IS the process that also
+ * parents the MCP child (both are the agy host). When a send from a birthed agy still arrives
+ * anonymous, this trace is the only thing that can say WHY — a plugin host in between, a per-turn
+ * worker, a shell wrapper. Compare it with the live bridge's own ancestry (`/proc/<pid>/stat`).
+ *
+ * OFF by default, and it must stay off: PreInvocation runs before EVERY model turn, so leaving it
+ * on would append a line and walk /proc six times per turn, forever — an unbounded trace in a log
+ * whose job is to hold birth evidence. The normal log already records the marker write (pid → gid),
+ * which is what a healthy host needs.
+ */
+function comm(pid) {
+    try {
+        return fs.readFileSync(`/proc/${pid}/comm`, "utf8").trim() || "?";
+    }
+    catch {
+        return "?";
+    }
+}
+function ancestry(startPid, depth = 6) {
+    const steps = [];
+    let pid = startPid;
+    for (let i = 0; i < depth && typeof pid === "number" && pid > 1; i++) {
+        steps.push(`${pid}:${comm(pid)}:${processStartKey(pid) || "-"}`);
+        pid = parentPid(pid);
+    }
+    return steps.join(" < ");
+}
+function traceOwnerTopology(conversationId) {
+    if (process.env.ENTWURF_AGY_TRACE_OWNER !== "1")
+        return;
+    logLine(`pids conversationId=${conversationId} hookPid=${process.pid} ppid=${process.ppid} chain=${ancestry(process.pid)}`);
+}
+function readStdin() {
+    try {
+        return fs.readFileSync(0, "utf8");
+    }
+    catch (err) {
+        logLine(`read-stdin-failed ${err instanceof Error ? err.message : String(err)}`);
+        return "";
+    }
+}
+function firstWorkspace(value) {
+    if (!Array.isArray(value))
+        return null;
+    const first = value[0];
+    return typeof first === "string" && first.trim() ? first : null;
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() ? value : null;
+}
+function imprint(raw) {
+    let payload;
+    try {
+        const parsed = JSON.parse(raw || "{}");
+        payload = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch (err) {
+        logLine(`skip invalid-json ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    const conversationId = optionalString(payload.conversationId);
+    if (!conversationId) {
+        logLine("skip missing-conversationId");
+        return;
+    }
+    const cwd = firstWorkspace(payload.workspacePaths);
+    if (!cwd) {
+        logLine(`skip missing-workspacePaths conversationId=${conversationId}`);
+        return;
+    }
+    traceOwnerTopology(conversationId);
+    try {
+        const result = upsertMetaSession({
+            input: {
+                backend: "antigravity",
+                nativeSessionId: conversationId,
+                cwd,
+                model: optionalString(payload.modelName),
+                transcriptPath: optionalString(payload.transcriptPath),
+            },
+        });
+        logLine(`ok ${result.action} gardenId=${result.record.gardenId} conversationId=${conversationId} cwd=${cwd}`);
+        // Sender marker — what lets the entwurf-bridge MCP child name WHO is calling it. The
+        // bridge and this hook are both children of the same agy process (measured: hook.ppid ==
+        // bridge.ppid == the `agy` pid, identical start-key), so that pid is the join key; the
+        // bridge looks a marker up under its own parent, finds this one, and the send goes out as
+        // a replyable garden citizen instead of anonymous external-mcp.
+        //
+        // The marker binds the pid to the conversation it is CURRENTLY invoking — not to one
+        // conversation forever. PreInvocation runs synchronously before every model turn, so a
+        // `/new` (same pid, new conversationId) rebinds the marker before that conversation can
+        // make its first tool call. Overwriting is a binding refresh, not an identity mutation:
+        // both conversations keep their meta-records.
+        //
+        // THE LIMIT, stated plainly: one pid has exactly ONE marker file per backend
+        // (`<senders>/antigravity/<pid>.json`). Two conversations invoking CONCURRENTLY under one
+        // agy process would therefore NOT leave two markers for the bridge to refuse — the second
+        // hook write silently overwrites the first, and a tool call still in flight from the first
+        // would be attributed to the second. Nothing downstream can detect that. So this binding
+        // rests on a runtime invariant: an agy process serializes its model invocations (its hook
+        // runs synchronously before each turn). Same-process concurrency is NOT supported, and
+        // there is no fail-closed guard for it — if agy ever gains it, the pid stops identifying
+        // the caller and the join key must change.
+        //
+        // Written only after the upsert above: the record store is the identity authority, and a
+        // marker pointing at a garden-id with no record would be a window of un-backed identity.
+        // A failed marker costs reply-addressability, never the session — log and move on.
+        const ownerPid = process.ppid;
+        if (typeof ownerPid === "number" && ownerPid > 0) {
+            try {
+                writeMetaSenderMarker({
+                    backend: "antigravity",
+                    gardenId: result.record.gardenId,
+                    nativeSessionId: conversationId,
+                    cwd,
+                    ownerPid,
+                });
+                logLine(`sender marker ${ownerPid} -> ${result.record.gardenId} conversationId=${conversationId}`);
+            }
+            catch (err) {
+                logLine(`sender-marker-failed pid=${ownerPid} gardenId=${result.record.gardenId} ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    catch (err) {
+        logLine(`upsert-failed conversationId=${conversationId} ${err instanceof Error ? err.stack || err.message : String(err)}`);
+    }
+}
+imprint(readStdin());
+process.stdout.write(`${NEUTRAL_RESPONSE}\n`);

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

@@ -0,0 +1,130 @@
+#!/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
+// `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.
+//
+// Env overrides (for the hermetic smoke):
+//   PI_PROVIDER_GLOBAL_SETTINGS   default: $PI_CODING_AGENT_DIR/settings.json or ~/.pi/agent/settings.json
+//   PI_PROVIDER_PROJECT_SETTINGS  default: <cwd>/.pi/settings.json
+//   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";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readProviderSettingsFile } from "../pi-extensions/lib/acp/config.js";
+const BARE = "entwurf-bridge";
+const KEY = "entwurf-bridge";
+const home = homedir();
+const agentDir = process.env.PI_CODING_AGENT_DIR || join(home, ".pi", "agent");
+const globalPath = process.env.PI_PROVIDER_GLOBAL_SETTINGS || join(agentDir, "settings.json");
+const projectPath = process.env.PI_PROVIDER_PROJECT_SETTINGS || join(process.cwd(), ".pi", "settings.json");
+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;
+}
+// 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;
+        }
+        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" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+log("[pi-provider doctor]");
+// Read via the SSOT — a malformed settings file THROWS here (fail-loud, named file).
+let userCmd;
+let projCmd;
+try {
+    userCmd = commandOf(readProviderSettingsFile(globalPath).settings);
+    projCmd = commandOf(readProviderSettingsFile(projectPath).settings);
+}
+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";
+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"}`);
+// 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;
+if (existsSync(statePath)) {
+    try {
+        const st = JSON.parse(readFileSync(statePath, "utf8"));
+        ownership = typeof st.ownership === "string" ? st.ownership : undefined;
+        log(`  state: install-state present (ownership=${ownership}).`);
+    }
+    catch {
+        log(`  state: FAIL — install-state ${statePath} is unreadable/corrupt.`);
+        hardFail = 1;
+    }
+}
+else {
+    log("  state: no user-scope install-state.");
+}
+log("── verdict");
+if (effectiveCmd === 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 {
+    // 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}'.`);
+        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).`);
+    }
+}
+if (hardFail) {
+    log("pi-provider doctor: FAIL.");
+    process.exit(1);
+}
+log("pi-provider doctor: ok.");