@junghanacs/entwurf 0.12.0 → 0.12.2

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-deliverability.js

@@ -0,0 +1,76 @@
+/**
+ * entwurf-deliverability — the PURE conversational-mailbox deliverability predicate
+ * (SE-1/SE-2 slice 2c). "If I enqueue a conversational reply to this target's mailbox
+ * right now, will a model actually see it — or will it rot as garbage?"
+ *
+ * Two layers, both pure (facts injected, no IO):
+ *
+ *  - computeMetaReceiverActive(facts): the shared "is this receiver active?" atom —
+ *    recordBacked AND ownerAlive AND watchArmed. This is the SAME conjunction the
+ *    self-addressability predicate uses for its meta branch; both import it so the
+ *    "active receiver" definition has ONE source of truth (concept shared, API split).
+ *
+ *  - mailboxConversationalDeliverable(facts): the enqueue gate. A mailbox enqueue +
+ *    doorbell only delivers for a SELF-FETCH backend (Claude Code / Codex / agy): the
+ *    receiver drains its own inbox on wake. A DIRECT-INJECT backend (pi) has no
+ *    mailbox drain at all — enqueuing for it is the SE-1 false success ("✓ delivered"
+ *    into a void). So deliverable = wakeMode === "self-fetch" AND the receiver is
+ *    active. This is the guard that the v1 fallback, MCP v1, pi-native v1, and the v2
+ *    decider/send-fallback enqueue sites must all pass before writing a .msg (slice 2d).
+ *
+ * The contract is "mailboxConversationalDeliverable", NOT a broad "deliverable": it is
+ * specifically about a conversational reply that needs a live doorbell wake, NOT about
+ * an archival mailbox someone reads later. Naming it narrowly keeps a future archival
+ * path from silently inheriting this gate.
+ */
+/**
+ * The shared active-receiver atom. Every axis is required (fail-closed: an undefined
+ * fact is treated as false, never optimistic), and each failure names its own cause so
+ * a terminated-owner is never conflated with a missing record or an unarmed watch.
+ */
+export function computeMetaReceiverActive(facts) {
+    if (facts.recordBacked !== true) {
+        return { active: false, reason: "no backing meta-record" };
+    }
+    if (facts.ownerAlive !== true) {
+        return { active: false, reason: "owner not alive (start-key mismatch — session exited or pid reused)" };
+    }
+    if (facts.watchArmed !== true) {
+        return { active: false, reason: "idle-watch not armed — a reply would enqueue with no doorbell wake" };
+    }
+    return { active: true, reason: "record backed, owner alive, watch armed" };
+}
+/**
+ * Does this presence marker actually belong to the target identity? A marker that is
+ * absent, or whose garden id / backend / native session id has drifted from the record,
+ * is NOT this receiver — fail-closed (a stale/foreign marker must never raise a dead
+ * target to "active"). The single source of truth for "marker ↔ identity match" shared
+ * by the v1 mailbox guard (gatherMailboxDeliverabilityFacts) and the v2 production
+ * `mailboxDeliverabilityFor` seam, so the two paths cannot drift to different meanings.
+ */
+export function receiverMarkerMatchesIdentity(marker, identity) {
+    return (!!marker &&
+        marker.gardenId === identity.gardenId &&
+        marker.backend === identity.backend &&
+        marker.nativeSessionId === identity.nativeSessionId);
+}
+/**
+ * The conversational-mailbox enqueue gate. False (no enqueue) unless the backend is
+ * self-fetch AND the receiver is active. A direct-inject backend (pi) is refused
+ * outright — it has no mailbox drain, so an enqueue would be a silent false success.
+ */
+export function mailboxConversationalDeliverable(facts) {
+    if (facts.wakeMode !== "self-fetch") {
+        return {
+            deliverable: false,
+            reason: `backend wake mode ${facts.wakeMode ?? "(unset)"} is not self-fetch — a mailbox enqueue would never be drained`,
+        };
+    }
+    const recv = computeMetaReceiverActive(facts);
+    return {
+        deliverable: recv.active,
+        reason: recv.active
+            ? `self-fetch receiver active (${recv.reason})`
+            : `self-fetch receiver inactive — ${recv.reason}`,
+    };
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-fact-provider.js

@@ -0,0 +1,121 @@
+/**
+ * entwurf-fact-provider — the fact-provider's ASSEMBLY layer (0.11 Stage 0 step
+ * 4, slice 4b). Composes the two axes into the listing the MCP `entwurf_peers`
+ * surface (slice 4c) renders. Lives in its own module so nothing imports it back
+ * (one-way: provider → facts / socket-discovery / meta-session) — no import cycle
+ * with `entwurf-facts.ts` (which owns `SocketProbe`/`resolveFactList`).
+ *
+ *   listAllMetaIdentities → pi gid 추출 → scanSocketProbes(piGids)
+ *     → pre-quarantine non-pi/socket conflicts → resolveFactList(clean)
+ *     → { facts, diagnostics }
+ *
+ * Two throw-vs-diagnostics policies, kept distinct (GPT힣 C-원칙):
+ *   - EXPECTED data corruption → diagnostics, listing survives. A meta-record
+ *     parse failure (from listAllMetaIdentities) and a gardenId↔socket address
+ *     collision are external-state problems; one must not blind `entwurf_peers`.
+ *   - IMPOSSIBLE wiring invariant → throw, NOT swallowed. resolveFactList's
+ *     duplicate-identity / unprobed-in-domain throws are assembly BUGS; catching
+ *     them here would hide a code defect. We feed resolveFactList only CLEAN
+ *     inputs (conflicts pre-removed), so its throw stays the last line of defense
+ *     — that is not a re-implementation of the collision rule, it is input
+ *     sanitation that leaves the pure-core invariant intact.
+ *
+ * The non-pi+socket collision quarantines BOTH sides (the PeerFact AND the
+ * socket): gardenId is the universal address and a send path reads the socket
+ * first, so surfacing the record alone (as a clean `unsupported` PeerFact) while
+ * a same-gid socket exists would be half a lie. Both leave the normal output;
+ * one diagnostic carries the fact. (pi + same-gid socket = the normal merge.)
+ */
+import { isNonPiGardenIdSocketConflict, resolveFactList } from "./entwurf-facts.js";
+import { isLivenessSupported } from "./entwurf-v2-contract.js";
+import { listAllMetaIdentities } from "./meta-session.js";
+import { scanSocketProbes } from "./socket-discovery.js";
+function diagnosticSortKey(d) {
+    switch (d.kind) {
+        case "meta-record-read-error":
+            return `0:${d.filename}`;
+        case "garden-id-socket-conflict":
+            return `1:${d.gardenId}`;
+        case "socket-symlink-rejected":
+            return `2:${d.gardenId}`;
+        case "malformed-socket-name":
+            return `3:${d.name}`;
+        case "socket-dir-read-error":
+            return "4:";
+    }
+}
+/**
+ * Assemble the facts-only listing. Pure over its injected deps (no direct IO) so
+ * the gate drives it without a filesystem; slice 4c supplies the real readdir /
+ * readFile / probe. Live socket probes may carry get_info runtime enrich
+ * (cwd/model/idle); null remains honest and renders as "not enriched".
+ */
+export async function listEntwurfFacts(deps) {
+    const diagnostics = [];
+    // 1. meta-store axis — expected corruption becomes diagnostics, not a throw.
+    const { identities, errors } = listAllMetaIdentities(deps.metaEntries, deps.readRecord);
+    for (const e of errors) {
+        diagnostics.push({ kind: "meta-record-read-error", filename: e.filename, message: e.message });
+    }
+    // 2. socket axis — probe (dir sockets) ∪ (in-domain citizen canonical paths).
+    //    Its three hazards (symlink forgery / malformed name / dir-read error) are
+    //    folded into diagnostics here so the listing survives but never lies.
+    const piGids = identities.filter((i) => isLivenessSupported(i.backend)).map((i) => i.gardenId);
+    const scan = await scanSocketProbes(piGids, deps.socket ?? {});
+    const probes = scan.probes;
+    const socketGids = new Set(probes.map((p) => p.gardenId));
+    const symlinkedGids = new Set(scan.symlinkedGardenIds);
+    for (const gardenId of scan.symlinkedGardenIds) {
+        diagnostics.push({
+            kind: "socket-symlink-rejected",
+            gardenId,
+            message: "control socket is a symlink — never probed (it could redirect to another session's listener and forge " +
+                "an alive liveness for this gardenId); a citizen owning it is treated as dead (dormant), a record-less one dropped.",
+        });
+    }
+    for (const name of scan.malformedNames) {
+        diagnostics.push({
+            kind: "malformed-socket-name",
+            name,
+            message: "control-socket filename is not a garden id — no citizen to correlate to; dropped from the listing.",
+        });
+    }
+    if (scan.dirError !== null) {
+        diagnostics.push({
+            kind: "socket-dir-read-error",
+            message: `control-socket directory unreadable (socket axis incomplete; meta-record citizens still listed): ${scan.dirError}`,
+        });
+    }
+    // 3. pre-quarantine non-pi citizens that collide with a control socket. The
+    //    predicate is SHARED with the v2 decider (isNonPiGardenIdSocketConflict) so
+    //    listing and dispatch cannot drift, and it unions socketGids with the
+    //    symlinkedGids: a symlinked socket is never probed (absent from socketGids),
+    //    so the old socketGids-only check let a non-pi citizen with a forged
+    //    (symlinked) socket survive as a clean PeerFact while the legacy send path
+    //    still followed the symlink — the gap this closes.
+    const conflictGids = new Set();
+    for (const id of identities) {
+        if (isNonPiGardenIdSocketConflict(id.backend, id.gardenId, socketGids, symlinkedGids)) {
+            conflictGids.add(id.gardenId);
+            diagnostics.push({
+                kind: "garden-id-socket-conflict",
+                gardenId: id.gardenId,
+                backend: id.backend,
+                message: `non-pi citizen (${id.backend}) shares its gardenId with a control socket (real or symlinked) — address ` +
+                    "ambiguity; both the citizen and the socket are quarantined from the listing.",
+            });
+        }
+    }
+    // 4. resolveFactList over CLEAN inputs only. Its throws (duplicate identity /
+    //    unprobed in-domain citizen) are impossible wiring invariants — left to
+    //    fire as the last line of defense, never caught here.
+    const cleanIdentities = identities.filter((i) => !conflictGids.has(i.gardenId));
+    const cleanProbes = probes.filter((p) => !conflictGids.has(p.gardenId));
+    const facts = resolveFactList(cleanIdentities, cleanProbes);
+    diagnostics.sort((a, b) => {
+        const ka = diagnosticSortKey(a);
+        const kb = diagnosticSortKey(b);
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    return { facts, diagnostics };
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-facts.js

@@ -0,0 +1,155 @@
+/**
+ * entwurf-facts — the TS fact-provider's PURE core (0.11 Stage 0 step 4).
+ *
+ * The "brain" reads disk SSOT (meta-record) + a socket probe and emits FACTS,
+ * never verbs. This module holds the single pure composition step:
+ *
+ *     (MetaIdentity, SocketLiveness | null)  →  PeerFact
+ *
+ * What it deliberately does NOT do (동결결정 10 / bucket B boundary):
+ *   - NO verb-routing. A `PeerFact` carries no `resumable`/`sendable`/`transport`
+ *     /`dispatch` field. Whether a target is resumed or sent-to is computed at
+ *     call time by the entwurf_v2 dispatch table from `liveness` — baking that
+ *     decision into the fact layer is exactly what makes `entwurf_peers` lie
+ *     (the reason 동결결정 10 orders contract-lock before this provider).
+ *   - NO IO. readdir of the meta-store and the live socket probe are slice-2
+ *     wiring; this slice locks the fact SHAPE and the R1/R3b liveness invariant
+ *     in code first (gate-first discipline), with both inputs injected.
+ *   - NO transcriptPath. The transcript path is a private on-disk location, not
+ *     a peer-facing fact; `entwurf_peers` exposes identity + cwd-history, not
+ *     filesystem internals. (who-can / dispatch read it via the meta-record
+ *     directly when they genuinely need it — it does not belong in the listing.)
+ *
+ * The 4-value liveness (`alive|dead|indeterminate|unsupported`, R3b) and the
+ * out-of-domain → `unsupported` rule (R1: never coerce an unprobed backend to
+ * `dead`/`indeterminate`) come from entwurf-v2-contract's `factLivenessOf` — the
+ * frozen contract is the single source for that mapping; this module only shapes
+ * the surrounding identity facts around it.
+ */
+import { factLivenessOf, isLivenessSupported } from "./entwurf-v2-contract.js";
+/**
+ * Compose a `PeerFact` from a citizen's identity and an optional socket probe.
+ *
+ * `socket` is the 3-value control-socket result for an IN-DOMAIN backend (pi),
+ * or `null` when no probe was taken (out-of-domain backend, or in-domain with no
+ * socket found). `factLivenessOf` resolves the 4-value fact:
+ *   - out-of-domain backend       → `unsupported`   (R1, regardless of `socket`)
+ *   - in-domain, socket present    → that socket value
+ *   - in-domain, socket null        → `indeterminate` (no proof, never `dead`)
+ *
+ * Pure: same inputs → same output, no IO.
+ */
+export function resolvePeerFact(identity, socket) {
+    return {
+        gardenId: identity.gardenId,
+        backend: identity.backend,
+        nativeSessionId: identity.nativeSessionId,
+        cwd: identity.cwd,
+        model: identity.model,
+        parentGardenId: identity.parentGardenId,
+        isEntwurf: identity.isEntwurf,
+        createdAt: identity.createdAt,
+        recordUpdatedAt: identity.recordUpdatedAt,
+        liveness: factLivenessOf(identity.backend, socket),
+    };
+}
+/**
+ * A non-pi RECORD whose gardenId collides with a control socket — a real (probed)
+ * one OR a symlinked/forged one. The gardenId is the universal address (동결결정3),
+ * so a non-pi citizen sharing it with a socket means a send-path that reaches the
+ * socket first hits a DIFFERENT receiver than the record names — an address split.
+ * Both the citizen and the socket are quarantined from the facts listing.
+ *
+ * The union `socketGids ∪ symlinkedGardenIds` is load-bearing: `socketGids` are
+ * gids with a real probed `*.sock`, but `symlinkedGardenIds` are NEVER probed (P1)
+ * and so are absent from `socketGids`. Looking at `socketGids` alone (the
+ * fact-provider:125 gap this closes) let a non-pi citizen with a *symlinked* socket
+ * survive as a clean PeerFact while the legacy send path still followed the symlink
+ * to a forged receiver. Both axes claim the gid → both must quarantine it.
+ *
+ * SCOPE: this is the RECORD-side, non-pi conflict only — shared by the fact-provider
+ * (listing) and the v2 decider (dispatch) so the two cannot drift (4c "재유도 금지"
+ * 동형; only the observation-bit source is parameterized). A pi citizen whose own
+ * canonical socket is a symlink is NOT this predicate's concern — that is a
+ * target-specific lstat conflict the decider's `inspectTargetControlSocket` raises
+ * as `address-conflict`, kept deliberately separate (GPT 1차 검수 C).
+ */
+export function isNonPiGardenIdSocketConflict(backend, gardenId, socketGids, symlinkedGardenIds) {
+    return !isLivenessSupported(backend) && (socketGids.has(gardenId) || symlinkedGardenIds.has(gardenId));
+}
+/**
+ * Pure union of the meta-store axis (citizens) and the socket axis (probes) into
+ * a facts-only listing. No IO — slice-3 wiring reads the meta-store and probes
+ * the sockets, then injects both lists.
+ *
+ * Correlation key = `gardenId` (동결결정3; `nativeSessionId` is backend-local, not
+ * a global key). Rules frozen 2026-06-11 (GPT힣 + Fable):
+ *   - in-domain (pi) citizen: liveness = its socket probe (3-value preserved).
+ *     The wiring MUST probe every in-domain citizen's canonical socket path, so a
+ *     citizen ABSENT from `socketProbes` is a wiring-invariant violation → throw.
+ *     We never pass `null` for a pi citizen (resolvePeerFact would map it to
+ *     `indeterminate` and strand a dormant citizen as un-resumable); a dormant
+ *     citizen's absent socket file is probed to `dead` (ENOENT) by the wiring and
+ *     arrives here AS `dead` → dormant → resumable.
+ *   - out-of-domain citizen WITH a control socket at its gardenId → fail-loud
+ *     (address ambiguity; a non-pi citizen must not own a pi control socket).
+ *   - out-of-domain citizen without a socket → `unsupported` (via resolvePeerFact).
+ *   - a probed gardenId with NO citizen → `SocketOnlyFact` (socket-only pi).
+ * A gardenId is never emitted as both a `PeerFact` and a `SocketOnlyFact`; once a
+ * pi meta-record writer ships, a socket-only entry is promoted to a `PeerFact`.
+ */
+export function resolveFactList(identities, socketProbes) {
+    const probeMap = new Map();
+    for (const probe of socketProbes) {
+        if (probeMap.has(probe.gardenId)) {
+            throw new Error(`resolveFactList: duplicate socket probe for gardenId ${probe.gardenId}`);
+        }
+        probeMap.set(probe.gardenId, probe);
+    }
+    const peers = [];
+    const consumed = new Set();
+    for (const identity of identities) {
+        const gid = identity.gardenId;
+        if (consumed.has(gid)) {
+            throw new Error(`resolveFactList: duplicate meta-record for gardenId ${gid}`);
+        }
+        let socket;
+        if (isLivenessSupported(identity.backend)) {
+            const probe = probeMap.get(gid);
+            if (!probe) {
+                throw new Error(`resolveFactList: in-domain citizen ${gid} (${identity.backend}) was not probed — ` +
+                    "wiring must probe every in-domain citizen's canonical socket path (absent file → dead, never unprobed)");
+            }
+            socket = probe.liveness;
+        }
+        else {
+            if (probeMap.has(gid)) {
+                throw new Error(`resolveFactList: out-of-domain citizen ${gid} (${identity.backend}) has a control socket — ` +
+                    "address ambiguity (a non-pi citizen must not own a pi control socket)");
+            }
+            socket = null;
+        }
+        peers.push(resolvePeerFact(identity, socket));
+        consumed.add(gid);
+    }
+    const socketOnly = [];
+    for (const probe of socketProbes) {
+        if (consumed.has(probe.gardenId))
+            continue;
+        socketOnly.push({
+            kind: "socket-only",
+            gardenId: probe.gardenId,
+            liveness: probe.liveness,
+            cwd: probe.cwd,
+            model: probe.model,
+            idle: probe.idle,
+            infoError: probe.infoError,
+        });
+    }
+    // Sort by gardenId with a plain `<` compare (not localeCompare) so both fact
+    // surfaces and the socket scan share one locale-independent ordering.
+    const byGardenId = (a, b) => a.gardenId < b.gardenId ? -1 : a.gardenId > b.gardenId ? 1 : 0;
+    peers.sort(byGardenId);
+    socketOnly.sort(byGardenId);
+    return { peers, socketOnly };
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-peers-render.js

@@ -0,0 +1,119 @@
+/**
+ * entwurf-peers-render — the PURE render/payload layer for the MCP `entwurf_peers`
+ * surface (0.11 Stage 0 step 4, slice 4c). The MCP handler stays thin: it does IO
+ * (readdir the meta-store + probe sockets via `listEntwurfFacts`) and then calls
+ * THIS to shape the text + JSON. No IO here, so the gate drives it without a
+ * filesystem and the SAME facts can feed pi-native / doctor / v2 dispatch later
+ * (a handler that did its own brain work would deny them that reuse).
+ *
+ * Three hard rules carried from the frozen contract (동결결정 10):
+ *   - FACTS ONLY, NO VERB-ROUTING. Neither the payload nor the text may carry a
+ *     `sendable`/`resumable`/`dispatch`/`action`/`transport`/`mailboxDeliverable`
+ *     field or word. Whether a target is sent-to or resumed is computed at call
+ *     time by the entwurf_v2 dispatch table from `liveness` — baking it into the
+ *     listing is exactly what makes `entwurf_peers` lie. The gate scans both the
+ *     JSON keys AND the text for the forbidden words (a section title like
+ *     "resumable peers" leaks routing that a key scan would miss).
+ *   - THREE SECTIONS, NEVER MERGED. `peers` (citizens, 4-value liveness) and
+ *     `socketOnly` (record-less sockets, 3-value liveness) are DISTINCT subjects
+ *     (slice 2's two-array split); `diagnostics` is a third. Merging them into one
+ *     array collapses the subject separation at the surface.
+ *   - LEGACY `sessions` IS A PROJECTION OF FACTS, not a second scan. We do NOT
+ *     re-run the old `getLiveSessions` (a separate live-socket scan would bypass
+ *     the provider's quarantine — a non-pi citizen colliding with a socket, which
+ *     `listEntwurfFacts` removes from BOTH normal arrays, could reappear in
+ *     `sessions`). `sessions` is derived from the SAME facts: alive pi citizens +
+ *     alive socket-only entries. Its socketPath is built by `controlSocketPath`
+ *     (the SSOT helper), never re-concatenated, so the filename↔gardenId
+ *     correlation authority (동결결정3) cannot drift between scan and render.
+ */
+import { controlSocketPath } from "./socket-discovery.js";
+/**
+ * Derive the legacy `sessions` projection from the facts: an active session is an
+ * alive pi citizen OR an alive record-less socket. `peers` and `socketOnly` are
+ * gid-disjoint (resolveFactList guarantees a gid is in one or the other, never
+ * both), so the concatenation needs no dedup. socketPath via `controlSocketPath`
+ * (SSOT). Sorted by sessionId for determinism.
+ */
+function deriveSessions(peers, socketOnly, controlDir) {
+    const sessions = [];
+    for (const p of peers) {
+        if (p.backend === "pi" && p.liveness === "alive") {
+            sessions.push({ sessionId: p.gardenId, socketPath: controlSocketPath(p.gardenId, controlDir) });
+        }
+    }
+    for (const s of socketOnly) {
+        if (s.liveness === "alive") {
+            sessions.push({ sessionId: s.gardenId, socketPath: controlSocketPath(s.gardenId, controlDir) });
+        }
+    }
+    sessions.sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0));
+    return sessions;
+}
+function renderPeerLine(p) {
+    const model = p.model ?? "(unknown)";
+    const entwurf = p.isEntwurf ? " entwurf" : "";
+    return `- ${p.gardenId}  backend=${p.backend}  liveness=${p.liveness}  cwd=${p.cwd}  model=${model}${entwurf}`;
+}
+function renderSocketOnlyLine(s) {
+    // Null enrich is "(not enriched)" — NOT "(unknown)", which would read as
+    // identity-unknown rather than not-yet-fetched / not available for this socket.
+    const cwd = s.cwd ?? "(not enriched)";
+    const model = s.model ?? "(not enriched)";
+    const idle = s.idle === null ? "" : `  idle=${s.idle ? "yes" : "no"}`;
+    const infoError = s.infoError === null ? "" : `  infoError=${s.infoError}`;
+    return `- ${s.gardenId}  liveness=${s.liveness}  cwd=${cwd}  model=${model}${idle}${infoError}`;
+}
+function renderDiagnosticLine(d) {
+    switch (d.kind) {
+        case "meta-record-read-error":
+            return `- meta-record-read-error ${d.filename}: ${d.message}`;
+        case "garden-id-socket-conflict":
+            return `- garden-id-socket-conflict ${d.gardenId} (backend=${d.backend}): ${d.message}`;
+        case "socket-symlink-rejected":
+            return `- socket-symlink-rejected ${d.gardenId}: ${d.message}`;
+        case "malformed-socket-name":
+            return `- malformed-socket-name ${d.name}: ${d.message}`;
+        case "socket-dir-read-error":
+            return `- socket-dir-read-error: ${d.message}`;
+    }
+}
+function compactLines(lines, max = 32) {
+    if (lines.length <= max)
+        return lines;
+    const omitted = lines.length - max;
+    return [`  … (${omitted} older entries omitted; showing latest ${max})`, ...lines.slice(-max)];
+}
+function section(title, lines, opts = {}) {
+    // Empty sections render "(none)" — hiding them would erase the honesty the
+    // listing exists to provide (especially diagnostics: "(none)" is a trust
+    // signal, and an `unsupported` peer must never be silently dropped).
+    const rendered = opts.compact ? compactLines(lines) : lines;
+    return rendered.length > 0 ? `${title}\n${rendered.join("\n")}` : `${title}\n  (none)`;
+}
+/**
+ * Shape the facts into the `entwurf_peers` text + JSON. Pure over its inputs.
+ * `controlDir` is the same directory the socket scan used — passing it here (not
+ * re-deriving) keeps the socketPath SSOT.
+ */
+export function renderEntwurfPeers(result, controlDir) {
+    const { peers, socketOnly } = result.facts;
+    const { diagnostics } = result;
+    const sessions = deriveSessions(peers, socketOnly, controlDir);
+    const text = [
+        section("Garden citizens (meta-record):", peers.map(renderPeerLine), { compact: true }),
+        "",
+        section("Socket-only control sockets (no meta-record):", socketOnly.map(renderSocketOnlyLine), { compact: true }),
+        "",
+        section("Diagnostics:", diagnostics.map(renderDiagnosticLine)),
+    ].join("\n");
+    const payload = {
+        controlDir,
+        count: sessions.length,
+        sessions,
+        peers,
+        socketOnly,
+        diagnostics,
+    };
+    return { text, payload };
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-preflight.js

@@ -0,0 +1,160 @@
+/**
+ * entwurf-preflight — 0.11 Stage 0 (2): the SINGLE trust/launch decision owner.
+ *
+ * The controlled-launch surface, the global `project_trust` handler, and any
+ * MCP fact tool ALL consume this module's outcome — nobody else re-derives a
+ * prefix, re-reads `trust.json`, or re-probes trust inputs. pi's raw trust
+ * semantics are followed by importing pi's PUBLIC root exports directly (frozen
+ * decision 9, 재구현 금지): `ProjectTrustStore` (the canonical `trust.json`
+ * reader, which itself canonicalizes the cwd and takes a `proper-lockfile` on
+ * every read) and `hasTrustRequiringProjectResources` (the trust-input probe).
+ * We never copy pi's trust detail — if pi changes it, this import tracks it.
+ *
+ * The returned `PreflightOutcome` is deliberately RICH, not just {kind,reason}:
+ * a fact tool must explain *why* a cwd is approved and *what* it may load
+ * without re-running the probe, and an error/handler must name the matched root
+ * or the trust-store value. Thin outcomes would push callers to recompute, which
+ * is exactly the re-derivation this module exists to prevent.
+ *
+ * trust ≠ discovery: this decision touches the store for a SINGLE launch-time
+ * cwd only. `peers`/`who-can` discovery does not call here (frozen decision 4).
+ *
+ * Precedence (frozen decision 8) — saved distrust is stronger than a prefix
+ * allow; a prefix only promotes the UNDECIDED (null) case; no-trust-inputs is
+ * trusted but needs no launch arg; everything else is fail-fast:
+ *
+ *   saved === false        → deny           (explicit distrust; store wins)
+ *   saved === true         → approve        (saved trust → internal --approve)
+ *   null + prefix match    → approve        (operator prefix promotes null→yes)
+ *   null + no trust inputs → trusted-no-arg (no trust-gated input — pi 0.79.x
+ *                                             excludes AGENTS.md/CLAUDE.md, so
+ *                                             context files may still be loaded)
+ *   else (null + inputs)   → fail-fast      (unknown/untrusted controlled launch)
+ *
+ * Injection (frozen decision 4): `agentDir` defaults to `getAgentDir()` but is
+ * overridable so tests point `ProjectTrustStore` at a temp dir (or set
+ * `PI_CODING_AGENT_DIR`, same isolation as 0.10.0) and never read or dirty the
+ * operator's real `~/.pi/agent/trust.json`. `prefixRoots` is an OPERATOR-policy
+ * input with NO package default (frozen decision 7): a public package must not
+ * hardcode a broad auto-approve, so an empty roots list means "no prefix
+ * promotion" — the caller injects the operator's roots (e.g. `~/repos/gh`).
+ */
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { getAgentDir, hasTrustRequiringProjectResources, ProjectTrustStore, } from "@earendil-works/pi-coding-agent";
+/**
+ * Render the human-facing reason a controlled launch was refused (N3b). This is
+ * a PURE formatter over a deny outcome — it does NOT touch a launcher, a socket,
+ * or pi; wiring it into the controlled-launch surface is bucket B (step 5), not
+ * here. The launcher/handler/error layers all call this so the refusal text is
+ * identical everywhere and always sourced from F5a evidence.
+ *
+ * The inherited-false branch is the one that matters: an operator distrust on an
+ * ANCESTOR (e.g. `~/repos/gh`) silently denies a child cwd, and an agent CANNOT
+ * lift it — that is an intended security property (N3a: a controlled launch
+ * short-circuits on `trustOverride` and never reaches the human-only active
+ * prompt). So the message must (1) name the inherited source (`inheritedFrom`)
+ * and (2) give the only real remedy: open an interactive pi AT the cwd and
+ * approve, which writes a direct child trust that beats the inherited decision
+ * (the "escape direction" proven in check-pi-preflight #13b).
+ */
+export function formatPreflightDenial(outcome) {
+    const cwd = outcome.canonicalCwd;
+    const openHere = `open an interactive pi at ${cwd} and approve when prompted`;
+    if (outcome.reason === "saved-false") {
+        if (outcome.trustStoreInherited && outcome.trustStoreEntryPath !== undefined) {
+            return (`Controlled launch refused: ${cwd} is distrusted by inheritance from ${outcome.trustStoreEntryPath} ` +
+                `(an ancestor carries a saved "no"). An agent cannot self-promote trust — this is an intended ` +
+                `security property. To trust THIS cwd only, ${openHere}; that writes a direct decision for ${cwd} ` +
+                `which overrides the inherited one.`);
+        }
+        return `Controlled launch refused: ${cwd} is explicitly distrusted (a saved "no" on this directory). To change it, ${openHere}.`;
+    }
+    // fail-fast: undecided + trust inputs + no operator prefix root.
+    return (`Controlled launch refused: ${cwd} is untrusted — it has trust inputs but no saved decision and no ` +
+        `operator prefix root. Refusing a silent degraded launch. Either add ${cwd} under an operator prefix ` +
+        `root, or ${openHere}.`);
+}
+/**
+ * Normalize a path the way pi resolves one before the trust store sees it:
+ * expand a leading `~`, make it absolute (`path.resolve`), then `realpathSync`;
+ * on a resolve failure fall back to the RESOLVED absolute path (not the raw
+ * input), so a not-yet-existing root still compares on an absolute basis.
+ */
+function normalizePath(p) {
+    let expanded = p;
+    if (p === "~") {
+        expanded = homedir();
+    }
+    else if (p.startsWith("~/")) {
+        expanded = join(homedir(), p.slice(2));
+    }
+    const abs = isAbsolute(expanded) ? expanded : resolve(expanded);
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+/**
+ * Return the canonical operator root that contains `canonicalCwd`, by canonical
+ * path + separator boundary (frozen decision 7). `/org` matches `/org/a` but NOT
+ * `/org2` — never a bare `startsWith`. Roots are normalized the same as the cwd.
+ */
+function matchedPrefixRoot(canonicalCwd, roots) {
+    for (const root of roots) {
+        const r = normalizePath(root);
+        if (canonicalCwd === r || canonicalCwd.startsWith(r + sep)) {
+            return r;
+        }
+    }
+    return undefined;
+}
+/** Decide trust for a single controlled-launch cwd. See module header. */
+export function preflight(input) {
+    const agentDir = input.agentDir ?? getAgentDir();
+    const prefixRoots = input.prefixRoots ?? [];
+    const canonicalCwd = normalizePath(input.cwd);
+    const store = new ProjectTrustStore(agentDir);
+    // getEntry, not get: get() throws away which path decided. getEntry returns
+    // `{ path, decision } | null` — the nearest ancestor (or the cwd itself)
+    // carrying an explicit decision. We recover the same decision value AND the
+    // deciding path, so the fact/handler/error layers can name an inherited
+    // source without re-walking the store. entry.path is pi-canonical, the same
+    // realpath axis as `canonicalCwd`, so an entry on the cwd ITSELF compares
+    // equal (= direct) and an ancestor compares unequal (= inherited).
+    const entry = store.getEntry(input.cwd);
+    const trustStoreDecision = entry?.decision ?? null;
+    const trustStoreInherited = entry !== null && entry.path !== canonicalCwd;
+    // Computed unconditionally: a fact tool must report what a prefix-approved
+    // cwd could load, so the probe runs even when a prefix already decides.
+    const hasTrustInputs = hasTrustRequiringProjectResources(input.cwd);
+    const matched = matchedPrefixRoot(canonicalCwd, prefixRoots);
+    const evidence = {
+        launchArgs: [],
+        trustStoreDecision,
+        trustStoreInherited,
+        hasTrustInputs,
+        canonicalCwd,
+        ...(entry !== null ? { trustStoreEntryPath: entry.path } : {}),
+        ...(matched !== undefined ? { matchedPrefixRoot: matched } : {}),
+    };
+    // Explicit distrust wins over everything, including a prefix match.
+    if (trustStoreDecision === false) {
+        return { ...evidence, kind: "deny", reason: "saved-false" };
+    }
+    if (trustStoreDecision === true) {
+        return { ...evidence, kind: "approve", reason: "saved-true", launchArgs: ["--approve"] };
+    }
+    // trustStoreDecision === null (undecided): a prefix promotes it; otherwise the
+    // absence of trust inputs makes it trusted-but-no-arg; otherwise fail-fast.
+    if (matched !== undefined) {
+        return { ...evidence, kind: "approve", reason: "prefix-match", launchArgs: ["--approve"] };
+    }
+    if (!hasTrustInputs) {
+        return { ...evidence, kind: "trusted-no-arg", reason: "no-trust-inputs" };
+    }
+    return { ...evidence, kind: "deny", reason: "fail-fast" };
+}