@junghanacs/entwurf 0.12.0 → 0.12.2

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

@@ -0,0 +1,50 @@
+/**
+ * session-id — garden-native session id SSOT (`YYYYMMDDTHHMMSS-[0-9a-f]{6}`).
+ *
+ * Authored as `.js` for the exact reason protocol.js is (see its header): this
+ * leaf is imported from BOTH runtime paths —
+ *   - tsc-emit path: pi-extension `.ts` files under the root tsconfig (allowJs),
+ *   - `node --experimental-strip-types` path: pure unit gates (check-meta-session,
+ *     new-session-id) that import a lib with a literal specifier.
+ * strip-types does not substitute `.ts` for a literal `.js` import specifier, and
+ * the root config cannot enable `allowImportingTsExtensions` without losing the
+ * tsc emit that check-models relies on. A real `.js` leaf resolves identically in
+ * every path, so the id grammar has ONE definition instead of one-per-importer.
+ *
+ * Keep dependency-free except `node:crypto`. The validator/grammar here is the
+ * same one the 0.9.0 resident garden guard and entwurf spawn collision pre-check
+ * enforce — do NOT fork it.
+ */
+import { randomBytes } from "node:crypto";
+/** `YYYYMMDDTHHMMSS-[0-9a-f]{6}`. Anchored; no surrounding slop. */
+export const SESSION_ID_RE = /^\d{8}T\d{6}-[0-9a-f]{6}$/;
+/**
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isValidSessionId(value) {
+    return typeof value === "string" && SESSION_ID_RE.test(value);
+}
+/**
+ * Local (KST on operator machines) denote-style timestamp `YYYYMMDDTHHMMSS`.
+ * Garden sort sense. Local components on purpose — the denote corpus is local.
+ *
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function formatSessionTimestamp(now = new Date()) {
+    const p = (n, w = 2) => String(n).padStart(w, "0");
+    return (`${p(now.getFullYear(), 4)}${p(now.getMonth() + 1)}${p(now.getDate())}` +
+        `T${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`);
+}
+/**
+ * Durable garden sessionId minted at the session's true birth. 6 hex suffix
+ * defeats same-second parallel-spawn collision; callers that spawn still
+ * header-scan pre-check (assertSessionIdAvailableForSpawn).
+ *
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function generateSessionId(now = new Date()) {
+    return `${formatSessionTimestamp(now)}-${randomBytes(3).toString("hex")}`;
+}

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

@@ -0,0 +1,259 @@
+/**
+ * socket-discovery — the SOCKET-axis wiring for the fact-provider (0.11 Stage 0
+ * step 4, slice 3). Turns the control-socket directory + the in-domain citizen
+ * list into the `SocketProbe[]` that `resolveFactList` (slice 2) consumes.
+ *
+ * Why a probe per in-domain citizen, not just a directory listing: slice 2's
+ * frozen invariant is that EVERY in-domain (pi) citizen must arrive PROBED — a
+ * dormant citizen whose socket file is gone must read as `dead` (ENOENT =
+ * positive proof of absence) so it routes dormant→resumable, never as an
+ * unprobed `null`/`indeterminate` that would strand it (resolveFactList throws
+ * on an unprobed in-domain citizen). So we probe the union of
+ *   (sockets present in the dir) ∪ (every in-domain citizen's canonical path):
+ * a dir-present socket yields alive / indeterminate / dead; a citizen with no
+ * file yields `dead` via ENOENT. Three-valued throughout (`probeSocketLiveness`)
+ * — an indeterminate stall is NEVER folded to dead (F3). This is exactly why we
+ * cannot reuse the legacy `getLiveSessions` (alive-only listing): folding the
+ * hidden indeterminate/dead sockets into "absent" would resurrect the F3 split.
+ *
+ * This slice fills the LIVENESS axis and, for live sockets, best-effort runtime
+ * enrich via the control RPC `get_info` (cwd / model / idle). `SocketProbe`'s
+ * enrich fields remain nullable-by-design: a dead/indeterminate socket or a
+ * failed enrich is HONEST, not synthetic, and carries `infoError` when known.
+ *
+ * Three socket-axis hazards are surfaced (slice 4c, Fable 검수), never swallowed:
+ *   - SYMLINK (P1, security): a `<gid>.sock` that is a symlink can redirect to
+ *     another session's listener, so gid X would probe ALIVE on Y's socket — a
+ *     forgery of 동결결정3's correlation authority (the socket filename = the gid).
+ *     The legacy bridge `getLiveSessions` guarded this (`entry.isSymbolicLink()`);
+ *     deriving the listing from facts would drop that guard unless we re-assert it
+ *     here. A symlinked socket is NEVER probed: a citizen owning one is forced to
+ *     `dead` (→ dormant → resume a fresh process, never SEND to a hijacked
+ *     listener); a record-less one is quarantined out of the listing entirely.
+ *     Both surface as `symlinkedGardenIds`.
+ *   - MALFORMED NAME (P3): a `*.sock` whose stem is not a garden id has no citizen
+ *     to correlate to and is dropped — but VISIBLY (`malformedNames`), not
+ *     silently (the legacy path listed any non-empty name; a silent regex drop
+ *     would violate "no silent drops").
+ *   - DIR-READ ERROR (P2e②): a missing dir (ENOENT) is the normal fresh-install
+ *     empty; ANY OTHER readdir failure (EACCES, …) is asymmetric loss of the whole
+ *     socket axis and is surfaced as `dirError`, not catch-all'd to empty (which
+ *     would silently vanish every socket-only session). When the dir is untrusted
+ *     this way, in-domain citizens are NOT probed (a non-ENOENT readdir failure
+ *     means we cannot confirm the canonical path is not a symlink, and `connect()`
+ *     would follow one) — they are reported `indeterminate` (liveness unknown),
+ *     held not stranded: once the dir reads again they route normally (GPi Q2/P1).
+ * The provider (slice 4b) folds these three into kind-tagged `EntwurfDiagnostic`s;
+ * this lib only reports the raw facts so the import stays one-way (provider →
+ * socket-discovery, never back).
+ *
+ * Deps (dir / readdir / probe) are injectable so the gate drives it without IO.
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fetchControlSocketRuntimeInfo, formatRuntimeModel } from "./entwurf-control-rpc.js";
+import { SESSION_ID_RE } from "./session-id.js";
+import { probeSocketLiveness } from "./socket-probe.js";
+/** Canonical control-socket directory; the socket filename IS the gardenId
+ * (동결결정3 correlation authority). */
+export const CONTROL_SOCKET_DIR = path.join(os.homedir(), ".pi", "entwurf-control");
+export const SOCKET_SUFFIX = ".sock";
+// A control-socket filename is a bare garden id. We reuse the repo-wide
+// `SESSION_ID_RE` SSOT (not a local copy): 동결결정3 makes the socket filename the
+// correlation authority, which only holds if the socket axis and the meta-record
+// axis speak the SAME id grammar — a drifted local regex would silently drop a
+// legitimate gid's socket from the scan. A malformed name has no citizen to
+// correlate to and is ignored.
+export function controlSocketPath(gardenId, dir = CONTROL_SOCKET_DIR) {
+    return path.join(dir, `${gardenId}${SOCKET_SUFFIX}`);
+}
+/**
+ * A1 narrow (0.11.0): does this PROBE-FREE single-lstat inspection of a gid's canonical
+ * control socket mean a record-LESS pi endpoint is addressable as a socket-only target?
+ * TRUE only for a confirmed NON-SYMLINK socket file (`socket-file`); a symlinked /
+ * absent / not-socket / `indeterminate` path is conservatively NOT promoted (never trust a
+ * symlink, never claim a target on an unprovable lstat). Shared by the v2 production
+ * `resolveTarget` so the socket-only acceptance uses the SAME lstat classification the
+ * listing/conflict paths use — listing↔dispatch cannot drift on what counts as a real
+ * control socket. The decider still does its own under-lock `inspectSocket` probe; this is
+ * only the presence hint that promotes `bad-target` → fire-and-forget socket-only pi.
+ */
+export function isSocketOnlyPiCandidate(inspection) {
+    return inspection.kind === "socket-file";
+}
+/**
+ * Inspect the EXACT control-socket path given (no gid re-derivation) and classify it by
+ * lstat alone. This is the path-addressed core of the inspection: the 5c-3 spawn-bg watcher
+ * observes `plan.expectedSocketPath` and MUST inspect that exact path (its contract forbids
+ * re-deriving a path from the gid), so the path-taking form is the SSOT and
+ * `inspectTargetControlSocket` is the thin gid→path wrapper over it. `lstatFn` is injectable
+ * so the gate drives every branch without a real filesystem; the default is `fs.lstat`
+ * (which, unlike connect, does NOT follow the final symlink — that is the whole point: a
+ * symlink is caught as an address-conflict and never connected, P1).
+ */
+export async function inspectControlSocketPath(socketPath, lstatFn = (p) => fs.lstat(p)) {
+    let st;
+    try {
+        st = await lstatFn(socketPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return { kind: "absent", socketPath };
+        // EACCES / unknown: not provably absent, so never treat as dead-and-spawn.
+        return { kind: "indeterminate", socketPath, error: code ?? "unknown lstat error" };
+    }
+    // lstat does NOT dereference the final component — a symlink is caught HERE and
+    // never connected (P1). A non-socket regular file / dir / fifo at the canonical
+    // path is address corruption, not a live socket.
+    if (st.isSymbolicLink())
+        return { kind: "address-conflict", socketPath, reason: "symlink" };
+    if (st.isSocket())
+        return { kind: "socket-file", socketPath };
+    return { kind: "address-conflict", socketPath, reason: "not-socket" };
+}
+/**
+ * The gid-addressed inspection (？2 — lstat-then-connect, v2 decider helper): derive the
+ * canonical control-socket path for `gardenId` and inspect it. A thin wrapper over
+ * `inspectControlSocketPath` so the decider's gid-keyed path and the watcher's exact-path
+ * observation share ONE lstat classifier (no drift in the P1 symlink guard).
+ */
+export async function inspectTargetControlSocket(gardenId, dir = CONTROL_SOCKET_DIR, lstatFn = (p) => fs.lstat(p)) {
+    return inspectControlSocketPath(controlSocketPath(gardenId, dir), lstatFn);
+}
+/**
+ * Map a target's socket inspection to a measured `SocketLiveness` (to feed
+ * resolveDispatch) or a pre-probe address-conflict signal. `absent` (ENOENT only) is
+ * the honest `dead` (the citizen is dormant; its canonical socket is the path a resume
+ * will create). `socket-file` is the only case that connects. `address-conflict`
+ * (symlink / not-a-socket) and `indeterminate` never connect.
+ *
+ * Shared SSOT for the v2 decider (5b, decideDispatch) AND the dead-control-send
+ * fallback resolver (5c-2b): both must map an inspection the SAME way, or one could
+ * route a stalled socket where the other reclaims it — exactly the F3 split this lib
+ * exists to prevent. A per-caller copy would drift; this is the single mapper.
+ */
+export async function mapInspectionToLiveness(inspection, probeSocket) {
+    switch (inspection.kind) {
+        case "absent":
+            return { liveness: "dead", socketPath: inspection.socketPath };
+        case "socket-file": {
+            const liveness = await probeSocket(inspection.socketPath);
+            return { liveness, socketPath: inspection.socketPath };
+        }
+        case "indeterminate":
+            return { liveness: "indeterminate", socketPath: inspection.socketPath };
+        case "address-conflict":
+            return { addressConflict: true };
+    }
+}
+/**
+ * Probe the union of (control sockets present in `dir`) ∪ (`piCitizenGardenIds`)
+ * and return one `SocketProbe` per gardenId (liveness + live get_info enrich), plus
+ * the three surfaced hazards. A missing directory (ENOENT) is the normal empty
+ * (`dirError=null`) — the in-domain citizens are still probed (their absent
+ * canonical paths read `dead`); any OTHER readdir failure sets `dirError`. A
+ * symlinked `*.sock` is never probed (P1): a citizen owning one is forced `dead`,
+ * a record-less one is dropped from `probes` entirely. Output sorted by gardenId.
+ */
+export async function scanSocketProbes(piCitizenGardenIds, deps = {}) {
+    const dir = deps.dir ?? CONTROL_SOCKET_DIR;
+    const readdir = deps.readdir ??
+        (async (d) => {
+            const dirents = await fs.readdir(d, { withFileTypes: true });
+            return dirents.map((e) => ({ name: e.name, isSymbolicLink: e.isSymbolicLink() }));
+        });
+    const probe = deps.probe ?? ((p) => probeSocketLiveness(p));
+    // Deterministic gates commonly inject fake readdir/probe over fake paths. In that
+    // case, default enrich must stay no-op unless the test explicitly injects getInfo.
+    // Real production calls inject neither readdir nor probe, so they get live RPC
+    // enrich by default.
+    const getInfo = deps.getInfo ??
+        (deps.readdir || deps.probe
+            ? async () => ({ cwd: null, model: null, idle: null })
+            : getRuntimeInfoOverControlSocket);
+    let entries = [];
+    let dirError = null;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (err) {
+        // ENOENT = fresh install / no sessions yet = the normal empty. Anything else
+        // (EACCES, EIO, …) is real loss of the socket axis — surface it, don't hide it.
+        const code = err?.code;
+        if (code !== "ENOENT") {
+            dirError = err instanceof Error ? err.message : String(err);
+        }
+        entries = [];
+    }
+    const socketGids = new Set();
+    const symlinkedGardenIds = [];
+    const malformedNames = [];
+    for (const entry of entries) {
+        if (!entry.name.endsWith(SOCKET_SUFFIX))
+            continue;
+        const gid = entry.name.slice(0, -SOCKET_SUFFIX.length);
+        if (!SESSION_ID_RE.test(gid)) {
+            malformedNames.push(entry.name);
+            continue;
+        }
+        if (entry.isSymbolicLink) {
+            // Never trust a symlinked socket: it can point at another session's
+            // listener and forge an `alive` for this gid (동결결정3 authority forgery).
+            symlinkedGardenIds.push(gid);
+            continue;
+        }
+        socketGids.add(gid);
+    }
+    const symlinkSet = new Set(symlinkedGardenIds);
+    // A non-ENOENT readdir failure means the dir is untrusted: we could not enumerate
+    // it, so we cannot confirm a canonical path is not a symlink. connect() follows
+    // symlinks, so probing here would defeat the P1 guard — hold every citizen at
+    // `indeterminate` instead (the socket-dir-read-error diagnostic carries the why).
+    const dirUntrusted = dirError !== null;
+    const allGids = [...new Set([...socketGids, ...piCitizenGardenIds])].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const probes = [];
+    for (const gardenId of allGids) {
+        // A citizen whose canonical socket is a symlink is forced `dead` (→ dormant →
+        // resume a fresh process) rather than probed through the untrusted link. A
+        // record-less symlink gid is not in `allGids` at all (dropped above).
+        let liveness;
+        if (symlinkSet.has(gardenId)) {
+            liveness = "dead";
+        }
+        else if (dirUntrusted) {
+            liveness = "indeterminate";
+        }
+        else {
+            liveness = await probe(controlSocketPath(gardenId, dir));
+        }
+        let cwd = null;
+        let model = null;
+        let idle = null;
+        let infoError = null;
+        if (liveness === "alive") {
+            try {
+                const info = await getInfo(controlSocketPath(gardenId, dir));
+                cwd = info.cwd;
+                model = info.model;
+                idle = info.idle;
+            }
+            catch (err) {
+                infoError = err instanceof Error ? err.message : String(err);
+            }
+        }
+        probes.push({ gardenId, liveness, cwd, model, idle, infoError });
+    }
+    symlinkedGardenIds.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    malformedNames.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return { probes, symlinkedGardenIds, malformedNames, dirError };
+}
+async function getRuntimeInfoOverControlSocket(socketPath) {
+    const info = await fetchControlSocketRuntimeInfo(socketPath, { timeout: 1500 });
+    return {
+        cwd: info.cwd ?? null,
+        model: formatRuntimeModel(info) ?? null,
+        idle: info.idle ?? null,
+    };
+}

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

@@ -0,0 +1,81 @@
+/**
+ * socket-probe — single source of truth for control-socket liveness.
+ *
+ * Why this is a shared lib (not a per-file copy): the entwurf-control
+ * extension (`pi-extensions/entwurf-control.ts`) AND the MCP bridge
+ * (`mcp/entwurf-bridge/src/index.ts`) both probe `~/.pi/entwurf-control/*.sock`.
+ * They used to carry independent `isSocketAlive` copies. If only one side
+ * learned the three-valued classification the two probes would diverge — the
+ * bridge routes a timeout target one way (mailbox fallback) while the
+ * extension's GC reclaims the same socket. Both now consume this module so the
+ * liveness semantics are identical on every surface. (0.11 Stage 0 step 4
+ * plans a probe lib extraction anyway; this is its first slice.)
+ *
+ * Three-valued, not boolean — the F3 fix. A connect probe can mean three
+ * different things, and collapsing them to a boolean is what let
+ * `gcStaleSockets` permanently unlink a *live* socket that merely stalled
+ * under load (→ every later probe sees it as dormant → live-session resume =
+ * identity split). The cure: never destroy a socket we do not understand.
+ *   - alive          → a listener accepted the connection (positive proof)
+ *   - dead           → ECONNREFUSED / ENOENT only (positive proof of absence)
+ *   - indeterminate  → timeout, EACCES, or any other/unknown error
+ *                      (no proof either way — keep the file, hide from listing)
+ */
+import * as net from "node:net";
+export const DEFAULT_PROBE_TIMEOUT_MS = 300;
+/**
+ * Pure classification of a connect-time error code into liveness. Only the two
+ * codes that unambiguously mean "no live listener at this path" are dead:
+ * ECONNREFUSED (socket file exists, nothing listening) and ENOENT (no socket
+ * file). EVERYTHING else — EACCES, ETIMEDOUT, an undefined code, an unknown
+ * code — is indeterminate. The default direction matters: when we don't know,
+ * we do not destroy. (동결결정: "ECONNREFUSED/ENOENT만 dead", taken literally.)
+ */
+export function classifyConnectError(code) {
+    return code === "ECONNREFUSED" || code === "ENOENT" ? "dead" : "indeterminate";
+}
+/**
+ * GC policy: a stale-socket sweep may reclaim ONLY a demonstrably dead socket.
+ * An indeterminate probe (timeout / unknown error) must survive the sweep —
+ * reclaiming it is exactly the F3 live-session split. Alive obviously survives.
+ */
+export function shouldUnlinkOnGc(liveness) {
+    return liveness === "dead";
+}
+/**
+ * Listing policy: a session appears in the live listing only on a positive
+ * connect. Indeterminate is hidden from the listing (preserving the prior
+ * boolean listing semantics) but — unlike GC — is NOT unlinked. dead is hidden
+ * too. This keeps "what GC reclaims" strictly narrower than "what is listed".
+ */
+export function shouldListAsLive(liveness) {
+    return liveness === "alive";
+}
+/**
+ * Probe a control socket and classify it. Positive connect → alive; a
+ * connect-time error is routed through `classifyConnectError`; a connect that
+ * neither connects nor errors within `timeoutMs` → indeterminate (the load
+ * stall case F3 is about — never coerced to dead).
+ */
+export async function probeSocketLiveness(socketPath, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    return await new Promise((resolve) => {
+        const socket = net.createConnection(socketPath);
+        const timer = setTimeout(() => {
+            socket.destroy();
+            resolve("indeterminate");
+        }, timeoutMs);
+        const settle = (liveness) => {
+            clearTimeout(timer);
+            socket.removeAllListeners();
+            resolve(liveness);
+        };
+        socket.once("connect", () => {
+            socket.end();
+            settle("alive");
+        });
+        socket.once("error", (err) => {
+            settle(classifyConnectError(err.code));
+        });
+    });
+}

package/mcp/entwurf-bridge/dist/protocol.js

@@ -0,0 +1,29 @@
+/**
+ * Shared wire-format constants for entwurf surfaces that must agree
+ * across the root bridge and pi-extension / MCP helper code.
+ *
+ * Keep this file dependency-free. Single source for both runtime paths:
+ *   - tsc-emit path: typechecked under root tsconfig.json (allowJs: true)
+ *     and copied through to the .tmp-verify directories by tsc emit.
+ *   - Node --experimental-strip-types path (mcp bridges): resolves explicit
+ *     .js imports literally to this file on disk.
+ *
+ * Why .js and not .ts: strip-types does not substitute .ts source for a
+ * literal .js import specifier, and the root config cannot enable
+ * allowImportingTsExtensions without losing tsc emit (which check-models
+ * relies on). Authoring as .js side-steps the whole drift surface.
+ */
+/**
+ * Opening marker for the project-context block inserted by entwurf's
+ * `enrichTaskWithProjectContext`. The ACP bridge uses the same marker to
+ * detect entwurf-spawned first prompts and remove only the duplicate cwd
+ * AGENTS.md section from its own pi-context augment.
+ */
+export const ENTWURF_PROJECT_CONTEXT_OPEN_TAG = "<project-context";
+/**
+ * Sender-side UI echo custom message type for successful entwurf_v2 send calls.
+ * The bridge emits it, the control renderer draws it, and the provider-level
+ * context filter removes it before LLM conversion. Keep as one SSOT: a typo
+ * here otherwise becomes a silent UI/context split.
+ */
+export const ENTWURF_SENT_MESSAGE_TYPE = "entwurf-sent";

package/mcp/entwurf-bridge/start.sh

@@ -1,8 +1,19 @@
 #!/usr/bin/env bash
-# entwurf-bridge MCP server launcher.
+# entwurf-bridge MCP server launcher (dual-mode, chosen by LOCATION).
 #
-# Runs src/index.ts directly via Node's --experimental-strip-types; no separate
-# build step. Node >= 22.6 (engines.node in ../../package.json).
+# PUBLISHED / INSTALLED (path is under node_modules): runs the prebuilt JS at
+# dist/mcp/entwurf-bridge/src/index.js with plain `node`. This path exists
+# because Node's --experimental-strip-types REFUSES `.ts` under node_modules
+# (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so the 0.12.0 strip-types
+# launcher broke the moment the package was npm-installed. `prepack`
+# (pnpm run build-bridge → rm -rf dist && tsc -p tsconfig.build.json) emits a
+# clean dist/ into the tarball; the package `files` allowlist ("mcp/") carries it.
+#
+# DEV CLONE (path is NOT under node_modules): runs src/index.ts via
+# --experimental-strip-types. The clone lives outside node_modules so strip-types
+# is allowed, edits are picked up with no build step, and a leftover dist/ (e.g.
+# emitted by `prepack` during a `pnpm check` pack gate) can never silently shadow
+# the source. Node >= 22.6 (engines.node in ../../package.json).
 #
 # Env file loading is strictly opt-in — the launcher never reads any dotfile
 # unless ENTWURF_BRIDGE_ENV_FILE points at one. Rationale: entwurf is a
@@ -10,7 +21,16 @@
 # bleed the original author's dotfile habits into every consumer's shell.
 set -euo pipefail
 
-HERE="$(cd "$(dirname "$0")" && pwd)"
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  TARGET="$(readlink "$SOURCE")"
+  case "$TARGET" in
+    /*) SOURCE="$TARGET" ;;
+    *) SOURCE="$DIR/$TARGET" ;;
+  esac
+done
+HERE="$(cd -P "$(dirname "$SOURCE")" && pwd)"
 
 if [ -n "${ENTWURF_BRIDGE_ENV_FILE:-}" ] && [ -f "$ENTWURF_BRIDGE_ENV_FILE" ]; then
   set -a
@@ -19,7 +39,29 @@ if [ -n "${ENTWURF_BRIDGE_ENV_FILE:-}" ] && [ -f "$ENTWURF_BRIDGE_ENV_FILE" ]; t
   set +a
 fi
 
-# All chatter goes to stderr so it never confuses an MCP client reading
-# JSON-RPC frames from stdout.
+# rootDir is the repo root (the bridge graph spans mcp/ and pi-extensions/),
+# so tsc mirrors the source tree under dist/ — hence the nested entry path.
+DIST_ENTRY="$HERE/dist/mcp/entwurf-bridge/src/index.js"
+SRC_ENTRY="$HERE/src/index.ts"
+
+# Mode is decided by LOCATION, not by "does dist happen to exist". A dev clone
+# lives outside node_modules and ALWAYS runs the TS source via strip-types, so an
+# edit is picked up immediately and a stale dist (e.g. left behind by a prior
+# `npm pack`/`prepack` during `pnpm check`) can never silently shadow the source.
+# An installed package lives under node_modules, where Node refuses strip-types,
+# so it MUST run the prebuilt dist. All chatter goes to stderr so it never
+# confuses an MCP client reading JSON-RPC frames from stdout.
+case "$HERE" in
+  */node_modules/*)
+    if [ ! -f "$DIST_ENTRY" ]; then
+      echo "entwurf-bridge: installed under node_modules but the prebuilt dist is missing:" >&2
+      echo "  $DIST_ENTRY" >&2
+      echo "  The published tarball ships dist via prepack; reinstall @junghanacs/entwurf." >&2
+      exit 1
+    fi
+    exec node "$DIST_ENTRY"
+    ;;
+esac
+
 exec node --experimental-strip-types --disable-warning=ExperimentalWarning \
-  "$HERE/src/index.ts"
+  "$SRC_ENTRY"

package/mcp/entwurf-bridge/test.sh

@@ -2,8 +2,17 @@
 set -euo pipefail
 
 # entwurf-bridge smoke (v2-only): tool registration + a few no-side-effect calls.
-ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
-BRIDGE="$ROOT_DIR/mcp/entwurf-bridge/src/index.ts"
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  TARGET="$(readlink "$SOURCE")"
+  case "$TARGET" in
+    /*) SOURCE="$TARGET" ;;
+    *) SOURCE="$DIR/$TARGET" ;;
+  esac
+done
+ROOT_DIR="$(cd -P "$(dirname "$SOURCE")/../.." && pwd)"
+BRIDGE_LAUNCHER="$ROOT_DIR/mcp/entwurf-bridge/start.sh"
 
 fail() { echo "FAIL: $*" >&2; exit 1; }
 ok() { echo "ok: $*"; }
@@ -18,7 +27,7 @@ jsonrpc() {
     -u ENTWURF_META_SENDER_MARKER \
     -u ENTWURF_BRIDGE_REQUIRE_META_SENDER \
     ENTWURF_META_SENDERS_DIR="$tmp_meta_senders" \
-    node --experimental-strip-types "$BRIDGE" <<'EOF'
+    bash "$BRIDGE_LAUNCHER" <<'EOF'
 {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}
 {"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
 {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

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

@@ -0,0 +1,42 @@
+{
+	// Emit config for the entwurf-bridge MCP server (0.12.1 C — install fix).
+	//
+	// WHY THIS EXISTS: Node's `--experimental-strip-types` REFUSES `.ts` files
+	// under `node_modules` (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). So the
+	// 0.12.0 launcher (`node --experimental-strip-types src/index.ts`) works from a
+	// dev clone but breaks the moment the package is installed under node_modules
+	// (every npm/pnpm consumer). This config tsc-EMITS the bridge boot closure to a
+	// plain-JS tree (`dist/`) that boots with vanilla `node` from anywhere. start.sh
+	// runs dist/ when its path is under node_modules (installed) and runs the
+	// strip-types src/ otherwise (dev clone).
+	//
+	// FENCE NOTE: the bridge graph is the SAME `.ts`-extension fence the root
+	// tsconfig excludes (root is emit-capable and can't allow `.ts` imports). This
+	// config pairs `allowImportingTsExtensions` with `rewriteRelativeImportExtensions`
+	// (TS 5.7+) instead of `noEmit`, so emitted JS references `.js` paths, including
+	// the lazy `await import("./entwurf-preflight.ts")` → `./entwurf-preflight.js`.
+	// That dynamic import stays dynamic in the output, so the eager boot closure
+	// remains pi-free (check-entwurf-bridge-pi-free) while the owned-outcome resume
+	// branch still lazy-loads the pi-backed preflight. This is an EMIT pass, not a
+	// typecheck pass — the noEmit typecheck fence (scripts/tsconfig.json) is
+	// untouched, so every `.ts` is still typechecked by exactly one `tsc --noEmit`.
+	"extends": "../../tsconfig.json",
+	"compilerOptions": {
+		"allowImportingTsExtensions": true,
+		"rewriteRelativeImportExtensions": true,
+		"noEmit": false,
+		"declaration": false,
+		"sourceMap": false,
+		"outDir": "./dist",
+		"rootDir": "../.."
+	},
+	// Clear the root `exclude` (it filters out every `.ts`-extension lib file the
+	// bridge graph needs). Only node_modules must stay excluded.
+	"exclude": ["../../node_modules"],
+	// Just the bridge entry (+ the dependency-free protocol.js it reaches via an
+	// explicit `.js` import). tsc auto-follows the import graph — STATIC imports
+	// AND the lazy `await import("./entwurf-preflight.ts")` — and emits exactly the
+	// boot closure, nothing more. This tracks graph drift automatically and keeps
+	// the pi-lane-only acp/* (unreached at boot) out of the tarball.
+	"include": ["./src/index.ts", "../../protocol.js"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.12.0",
+	"version": "0.12.2",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for Claude Code, Codex, Antigravity, and pi harnesses.",
 	"license": "MIT",
 	"author": {
@@ -19,17 +19,17 @@
 		"access": "public"
 	},
 	"keywords": [
-		"pi",
-		"pi-package",
-		"pi-extension",
-		"pi-coding-agent",
-		"garden-session",
 		"entwurf",
+		"garden-id",
+		"garden-citizen",
 		"dispatch",
 		"meta-bridge",
+		"mcp",
 		"claude-code",
 		"codex",
-		"mcp"
+		"antigravity",
+		"pi-coding-agent",
+		"pi-extension"
 	],
 	"type": "module",
 	"files": [
@@ -89,8 +89,10 @@
 		"typescript": "^6.0.2"
 	},
 	"scripts": {
-		"prepare": "husky 2>/dev/null || true",
+		"prepare": "husky 2>/dev/null || true; npm run --silent build-bridge",
 		"postinstall": "node scripts/postinstall-chmod.cjs",
+		"build-bridge": "rm -rf mcp/entwurf-bridge/dist && tsc -p mcp/entwurf-bridge/tsconfig.build.json",
+		"prepack": "pnpm --silent run build-bridge",
 		"prepublishOnly": "pnpm run check && pnpm run check-pack-install",
 		"setup": "./run.sh setup",
 		"check-shell-quote": "./run.sh check-shell-quote",
@@ -116,8 +118,9 @@
 		"typecheck": "tsc --noEmit && tsc -p mcp/tsconfig.json && tsc -p scripts/tsconfig.json",
 		"lint": "biome check .",
 		"format": "biome check --write .",
+		"check-meta-manifest-schema": "./run.sh check-meta-manifest-schema",
 		"check-package-source-routing": "./run.sh check-package-source-routing",
-		"check": "pnpm lint && pnpm typecheck && ./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-record-v2 && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-meta-dual-read && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-migration && ./run.sh check-meta-dual-consumers && ./run.sh check-meta-capability-source && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh smoke-meta-install-state && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-package-source-routing && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-install-preflight && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-lock && ./run.sh check-entwurf-v2-decider && ./run.sh check-entwurf-v2-matrix && ./run.sh check-entwurf-v2-release && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-send-fallback && ./run.sh check-entwurf-v2-mailbox && ./run.sh check-entwurf-v2-runner && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-boot && ./run.sh check-entwurf-v2-spawn && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-spawn-production && ./run.sh check-entwurf-facts && ./run.sh check-socket-discovery && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-entwurf-mailbox-guard && ./run.sh check-auth-boundary && ./run.sh check-acp-provider-surface && ./run.sh check-acp-sdk-surface && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-acp-carrier-augment && ./run.sh check-pack"
+		"check": "pnpm lint && pnpm typecheck && ./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-record-v2 && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-meta-dual-read && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-migration && ./run.sh check-meta-dual-consumers && ./run.sh check-meta-capability-source && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh smoke-meta-install-state && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-package-source-routing && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-install-preflight && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-lock && ./run.sh check-entwurf-v2-decider && ./run.sh check-entwurf-v2-matrix && ./run.sh check-entwurf-v2-release && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-send-fallback && ./run.sh check-entwurf-v2-mailbox && ./run.sh check-entwurf-v2-runner && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-boot && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-entwurf-v2-spawn && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-spawn-production && ./run.sh check-entwurf-facts && ./run.sh check-socket-discovery && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-entwurf-mailbox-guard && ./run.sh check-auth-boundary && ./run.sh check-acp-provider-surface && ./run.sh check-acp-sdk-surface && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-acp-carrier-augment && ./run.sh check-pack"
 	},
 	"pi": {
 		"extensions": [
@@ -126,5 +129,23 @@
 			"./pi-extensions/model-lock.ts"
 		],
 		"image": "https://raw.githubusercontent.com/junghan0611/entwurf/main/docs/assets/entwurf-hero.jpg"
+	},
+	"bin": {
+		"entwurf": "./run.sh",
+		"entwurf-bridge": "./mcp/entwurf-bridge/start.sh"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-ai": {
+			"optional": true
+		},
+		"@earendil-works/pi-coding-agent": {
+			"optional": true
+		},
+		"@earendil-works/pi-tui": {
+			"optional": true
+		},
+		"typebox": {
+			"optional": true
+		}
 	}
 }