@junghanacs/entwurf 0.12.3 → 0.12.4

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented here. Format follows [Kee
 
 ## Unreleased
 
+## 0.12.4 — 2026-07-01
+
+### Fixed
+
+- **Installed `doctor-meta-bridge` no longer false-fails on node_modules strip-types.** The doctor previously ran `scripts/meta-bridge-store-doctor.ts` and `scripts/check-entwurf-v2-surface.ts` through Node strip-types even from an npm/pnpm-installed package. Node refuses type stripping under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so real floor hosts reported false store-scan / v2-surface failures while development clones stayed green. The doctor now branches by package location: installed packages run the prebuilt `mcp/entwurf-bridge/dist/scripts/meta-bridge-store-doctor.js` with plain `node` and defer the repo-only v2 source-shape gate after confirming the shipped source and runtime wiring; development clones keep the raw `.ts` gates.
+- **The store-doctor helper now ships as a node_modules-safe dist artifact.** The bridge build emits `dist/scripts/meta-bridge-store-doctor.js` alongside the MCP bridge closure, reusing the already-shipped `meta-session.js` dependency without adding a new runtime package lane. `check-pack` / `check-pack-install` require the artifact in the tarball and prove it scans a real fixture store under `node_modules` with plain `node`.
+- **Clean-host install docs call out the 0.12.4 doctor floor check.** The walkthrough now tells operators exactly which doctor lines prove the installed-vs-dev split and flags any `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` as a pre-0.12.4 or broken-tarball signal.
+
+### Verification
+
+- `pnpm check` passed on 2026-07-01 after the doctor/install-floor fix.
+- `./run.sh check-pack-install` passed with the new installed store-doctor scan and doctor-dispatch lock assertions.
+- Release-gate prep evidence: `LIVE=1 ./run.sh release-gate /tmp/psa-release-gate-0.12.4.PliLsd` passed on 2026-07-01; log `/tmp/pi-tmux-entwurf-release-gate-0124.log`; summary `MUST: PASS=17 FAIL=0 SKIP=0`, advisory `BEHAVIOR: PASS=0 FAIL=1` (`smoke-resident-garden-guard` post-`/gnew` autonomous `entwurf_self` identity turn; non-blocking).
+- `hejdev6` real floor host reproduced the pre-fix strip-types failure from an installed package and passed after installing the patched tarball: compiled store-doctor scanned `1 record(s)` with plain `node`, and installed `doctor-meta-bridge` reported store-scan ok plus v2-surface deferred.
+
 ## 0.12.3 — 2026-07-01
 
 ### Changed

package/README.md

@@ -181,6 +181,12 @@ entwurf install-meta-bridge
 entwurf doctor-meta-bridge
 ```
 
+On npm/pnpm-installed packages, `doctor-meta-bridge` must use prebuilt JS for its
+store scan and defer repo-only source-shape gates; Node refuses strip-types for
+raw `.ts` helpers under `node_modules`. If the doctor reports
+`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`, reinstall a current package before
+trusting the floor result.
+
 For manual configuration, [`pi/settings.reference.json`](./pi/settings.reference.json)
 shows the pi adapter settings shape, and the external-host examples below show
 plain MCP registrations.

package/docs/setup-clean-host.md

@@ -4,9 +4,11 @@ End-to-end install of **entwurf** on a host with only `git` available — no
 node, no npm package, no pi binary, no dotfiles. The point is to validate the
 public install surface as an outside user would experience it.
 
-> **Scope.** This is the entwurf 0.12.1 install recipe. The base package install
+> **Scope.** This is the entwurf 0.12.4 install recipe. The base package install
 > is **neutral npm**, not `pi install npm:...`. Pi is an optional adapter lane for
-> the ACP provider / control-socket runtime.
+> the ACP provider / control-socket runtime. The 0.12.4 floor fix is explicitly
+> covered here: installed packages under `node_modules` must not run raw `.ts`
+> doctor helpers through Node strip-types.
 
 `entwurf` is a garden-citizen dispatch substrate and meta-bridge. It does not
 provide, copy, or mediate backend credentials — it lets the official backend CLI
@@ -72,9 +74,11 @@ MCP bridge can boot in Claude Code / Codex / Antigravity without pi present.
 ## Stage 2 — auth-free bridge boot
 
 Prove the installed MCP server answers `tools/list` from inside `node_modules`.
-This is the regression that 0.12.0 missed: Node refuses `--experimental-strip-types`
-for `.ts` under `node_modules`, so the installed package must boot the prebuilt
-JS under `mcp/entwurf-bridge/dist/`.
+This is the first `node_modules` strip-types regression fixed in 0.12.0: Node
+refuses `--experimental-strip-types` for `.ts` under `node_modules`, so the
+installed package must boot the prebuilt JS under `mcp/entwurf-bridge/dist/`.
+The 0.12.4 doctor fix below applies the same installed-vs-dev split to
+`doctor-meta-bridge` helper checks.
 
 ```bash
 node --input-type=module <<'JS'
@@ -141,6 +145,19 @@ entwurf install-meta-bridge
 entwurf doctor-meta-bridge
 ```
 
+On an installed package (`.../node_modules/@junghanacs/entwurf`), the doctor must
+not try to strip-types-run raw `.ts` helpers. In the output, check for these two
+0.12.4 floor-regression signals:
+
+```text
+ok    full store scan: no corrupt records, duplicate nativeSessionId, body/filename drift, or backend↔wakeMode contradiction
+ok    check-entwurf-v2-surface: shipped surface source present; exhaustive source-shape gate is a repo/release invariant (not run under node_modules)
+```
+
+If either section reports `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`, the host
+is still running a pre-0.12.4 package or a broken tarball. Reinstall the current
+package and re-run `entwurf install-meta-bridge && entwurf doctor-meta-bridge`.
+
 A plain external MCP host can call tools but is non-replyable. A garden-native
 meta-session has a garden id, a mailbox, and a trusted sender marker; it can call
 `entwurf_self`, receive mailbox wakeups, and be replied to by garden id.

package/mcp/entwurf-bridge/dist/scripts/meta-bridge-store-doctor.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * meta-bridge-store-doctor — fail-loud full scan for meta-session records.
+ *
+ * The store is the authority for native→garden lookup. Doctor must therefore
+ * refuse corrupt records, duplicate nativeSessionId authorities, and body ↔
+ * filename drift instead of auto-pruning or silently picking one.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseMetaIdentity } from "../pi-extensions/lib/meta-session.js";
+const dir = process.argv[2];
+if (!dir) {
+    console.error("usage: node --experimental-strip-types scripts/meta-bridge-store-doctor.ts <meta-sessions-dir>");
+    process.exit(2);
+}
+const failures = [];
+const nativeToFiles = new Map();
+let scanned = 0;
+if (!fs.existsSync(dir)) {
+    console.log(`meta-store scan ok: ${dir} does not exist yet (0 records)`);
+    process.exit(0);
+}
+for (const filename of fs.readdirSync(dir).sort()) {
+    if (!filename.endsWith(".meta.json"))
+        continue;
+    scanned += 1;
+    const file = path.join(dir, filename);
+    try {
+        // dual-read (3D-4 commit1): parseMetaIdentity reads v1 AND v2 and normalizes,
+        // so doctor's gardenId/nativeSessionId checks survive the v2 cut.
+        const id = parseMetaIdentity(fs.readFileSync(file, "utf8"));
+        const expectedFilename = `${id.gardenId}.meta.json`;
+        if (filename !== expectedFilename) {
+            failures.push(`${filename}: body/filename drift — body gardenId=${id.gardenId}, expected filename ${expectedFilename}`);
+        }
+        const files = nativeToFiles.get(id.nativeSessionId) ?? [];
+        files.push(filename);
+        nativeToFiles.set(id.nativeSessionId, files);
+    }
+    catch (err) {
+        failures.push(`${filename}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+for (const [nativeSessionId, files] of nativeToFiles.entries()) {
+    if (files.length > 1) {
+        failures.push(`duplicate nativeSessionId ${JSON.stringify(nativeSessionId)} in ${files.join(", ")} — authority ambiguity; prune manually`);
+    }
+}
+if (failures.length > 0) {
+    for (const failure of failures)
+        console.error(`FAIL: ${failure}`);
+    process.exit(1);
+}
+console.log(`meta-store scan ok: ${scanned} record(s) scanned, no corrupt/duplicate/drift records`);

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

@@ -33,10 +33,18 @@
 	// 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"]
+	// The bridge boot entry (+ the dependency-free protocol.js it reaches via an
+	// explicit `.js` import) PLUS the doctor's store-scan helper. tsc auto-follows
+	// the import graph — STATIC imports AND the lazy
+	// `await import("./entwurf-preflight.ts")` — and emits exactly that closure,
+	// nothing more (the pi-lane-only acp/* stays out of the tarball).
+	//
+	// WHY store-doctor rides THIS build: meta-bridge-doctor.sh's full store scan
+	// must run from an INSTALLED package (under node_modules, where strip-types is
+	// refused) — the same node_modules boundary start.sh crosses. Its only repo
+	// import is pi-extensions/lib/meta-session.ts, which the bridge graph ALREADY
+	// emits here, so it adds ONE leaf JS (dist/scripts/meta-bridge-store-doctor.js)
+	// and ZERO new deps. It is NOT in index.ts's boot closure, so
+	// check-entwurf-bridge-pi-free (which walks the index eager closure) is unaffected.
+	"include": ["./src/index.ts", "../../protocol.js", "../../scripts/meta-bridge-store-doctor.ts"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.12.3",
+	"version": "0.12.4",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for Claude Code, Codex, Antigravity, and pi harnesses.",
 	"license": "MIT",
 	"author": {

package/run.sh

@@ -1731,6 +1731,10 @@ check_pack() {
     # this dist JS when present (the .ts source can't strip-types under
     # node_modules). prepack runs on `npm pack --dry-run`, so it is in this gate.
     "mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js"
+    # 0.12.4 — the doctor's node_modules-safe store-scan artifact. meta-bridge-
+    # doctor.sh runs this prebuilt JS when installed under node_modules (strip-types
+    # refuses the .ts there), same boundary start.sh crosses. build-bridge emits it.
+    "mcp/entwurf-bridge/dist/scripts/meta-bridge-store-doctor.js"
     "scripts/postinstall-chmod.cjs"
     "pi/entwurf-capabilities.json"
     "pi/entwurf-targets.json"
@@ -1880,6 +1884,9 @@ check_pack_install() {
     "mcp/entwurf-bridge/src/index.ts"
     # 0.12.1 C — prepack-built node_modules-safe boot artifact (see check-pack).
     "mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js"
+    # 0.12.4 — prebuilt node_modules-safe store-scan artifact for the doctor
+    # (see check-pack). The installed-scan smoke below runs exactly this file.
+    "mcp/entwurf-bridge/dist/scripts/meta-bridge-store-doctor.js"
     "scripts/postinstall-chmod.cjs"
     "pi/entwurf-capabilities.json"
     "pi/entwurf-targets.json"
@@ -2127,6 +2134,52 @@ JS
   fi
   echo "[check-pack-install] installed bridge boot pass (dist boots under node_modules, pi-free: $boot_out)"
 
+  # 0.12.4 — installed STORE-DOCTOR regression. meta-bridge-doctor.sh's full store
+  # scan runs the prebuilt dist JS when it lives under node_modules (strip-types
+  # refuses the .ts there — the same class as the bridge boot above). Before the dist
+  # split the doctor ran the raw .ts and reported a FALSE "corrupt records" FAIL on
+  # EVERY installed host. Prove the shipped dist JS scans a fixture store with PLAIN
+  # node (a strip-types fallback would crash with the exact
+  # ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING) AND that its rewritten import of the
+  # emitted meta-session.js resolves — a real record exercises parseMetaIdentity.
+  local installed_store_doctor="$npm_pkg/mcp/entwurf-bridge/dist/scripts/meta-bridge-store-doctor.js"
+  if [ ! -f "$installed_store_doctor" ]; then
+    fail "[check-pack-install] installed store-doctor missing prebuilt dist (prepack did not emit it into the tarball?): $installed_store_doctor"
+    return 1
+  fi
+  local sd_fixture="$npm_tmp/store-fixture"
+  mkdir -p "$sd_fixture"
+  # One valid v2 record: filename == "${gardenId}.meta.json" (no drift), unique
+  # nativeSessionId (no dupe). gardenId must match YYYYMMDDTHHMMSS-[0-9a-f]{6}.
+  printf '%s\n' '{"schemaVersion":2,"gardenId":"20990101T000000-abcdef","backend":"claude-code","nativeSessionId":"native-store-doctor-fixture","cwd":"/tmp/entwurf-fixture","model":null,"transcriptPath":null,"parentGardenId":null,"isEntwurf":false,"createdAt":"2099-01-01T00:00:00.000Z","recordUpdatedAt":"2099-01-01T00:00:00.000Z"}' \
+    > "$sd_fixture/20990101T000000-abcdef.meta.json"
+  local sd_out
+  if ! sd_out=$(node "$installed_store_doctor" "$sd_fixture" 2>&1); then
+    fail "[check-pack-install] installed store-doctor FAILED to scan under node_modules (strip-types-under-node_modules regression, or the emitted meta-session import broke):"
+    echo "$sd_out" | tail -15 | sed 's/^/    /' >&2
+    return 1
+  fi
+  if ! grep -q "1 record(s) scanned" <<<"$sd_out"; then
+    fail "[check-pack-install] installed store-doctor scanned but did not report the fixture record (parseMetaIdentity path not exercised?): $sd_out"
+    return 1
+  fi
+  echo "[check-pack-install] installed store-doctor scan pass (dist JS scans under node_modules with plain node: $sd_out)"
+
+  # 0.12.4 — installed DOCTOR DISPATCH lock. The artifact above proves the store-scan
+  # target runs under node_modules; this proves the doctor SCRIPT actually routes to
+  # it (store scan → dist JS) and defers the strip-types-only source-shape gate
+  # (v2-surface) when installed, instead of running raw .ts and false-failing.
+  local installed_doctor="$npm_pkg/scripts/meta-bridge-doctor.sh"
+  if ! grep -q 'dist/scripts/meta-bridge-store-doctor.js' "$installed_doctor"; then
+    fail "[check-pack-install] installed doctor does not dispatch the store scan to the dist JS under node_modules: $installed_doctor"
+    return 1
+  fi
+  if ! grep -q 'shipped surface source present' "$installed_doctor"; then
+    fail "[check-pack-install] installed doctor does not defer the v2-surface source-shape gate on installed hosts: $installed_doctor"
+    return 1
+  fi
+  echo "[check-pack-install] installed doctor dispatch lock pass (store-scan → dist JS, v2-surface deferred)"
+
   ok "[check-pack-install] publish install smoke pass"
   return 0
 }

package/scripts/meta-bridge-doctor.sh

@@ -147,10 +147,36 @@ echo "[meta-record store]"
 mkdir -p "$META_SESSIONS" 2>/dev/null || true
 if [ -d "$META_SESSIONS" ] && [ -w "$META_SESSIONS" ]; then ok "writable: $META_SESSIONS"; else bad "meta-sessions dir not writable: $META_SESSIONS"; fi
 if command -v node >/dev/null; then
-  if node --experimental-strip-types "$REPO/scripts/meta-bridge-store-doctor.ts" "$META_SESSIONS" >/dev/null 2>&1; then
-    ok "full store scan: no corrupt records, duplicate nativeSessionId, body/filename drift, or backend↔wakeMode contradiction"
-  else
-    bad "full store scan failed — corrupt/duplicate/drift meta-record(s) present. Inspect with: node --experimental-strip-types $REPO/scripts/meta-bridge-store-doctor.ts $META_SESSIONS"
+  # Full store scan — mode by LOCATION (mirror mcp/entwurf-bridge/start.sh). Node
+  # REFUSES --experimental-strip-types for a .ts under node_modules
+  # (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so an INSTALLED package must scan
+  # via the prebuilt dist JS (build-bridge emits it; files:["mcp/"] ships it); a DEV
+  # CLONE lives outside node_modules and runs the .ts source. Before this split the
+  # doctor always ran the .ts and reported a FALSE "corrupt records" FAIL on every
+  # installed host (the 0.12.0 strip-types-under-node_modules class the bridge boot
+  # already fixed, but this doctor helper still ran raw .ts).
+  case "$REPO" in
+    */node_modules/*)
+      store_doctor="$REPO/mcp/entwurf-bridge/dist/scripts/meta-bridge-store-doctor.js"
+      if [ -f "$store_doctor" ]; then
+        store_scan=(node "$store_doctor" "$META_SESSIONS")
+      else
+        bad "installed under node_modules but prebuilt store-doctor missing: $store_doctor — the tarball ships it via prepack; reinstall @junghanacs/entwurf"
+        store_scan=()
+      fi
+      ;;
+    *)
+      store_scan=(node --experimental-strip-types "$REPO/scripts/meta-bridge-store-doctor.ts" "$META_SESSIONS")
+      ;;
+  esac
+  # Guard the expansion: bash 3.2 (macOS) + set -u errors on "${arr[@]}" for a
+  # zero-length array, so only run/print when the command was actually built.
+  if [ "${#store_scan[@]}" -gt 0 ]; then
+    if "${store_scan[@]}" >/dev/null 2>&1; then
+      ok "full store scan: no corrupt records, duplicate nativeSessionId, body/filename drift, or backend↔wakeMode contradiction"
+    else
+      bad "full store scan failed — corrupt/duplicate/drift meta-record(s) present. Inspect with: ${store_scan[*]}"
+    fi
   fi
 else
   bad "cannot scan meta-record store without node"
@@ -297,11 +323,30 @@ if [ -f "$V2_MCP_SRC" ] && grep -q 'server.tool(' "$V2_MCP_SRC" && grep -q '"ent
 else
   bad "MCP entwurf_v2 verb not found in entwurf-bridge"
 fi
-if [ -f "$V2_SURFACE_SRC" ] && (cd "$REPO" && node --experimental-strip-types scripts/check-entwurf-v2-surface.ts >/dev/null 2>&1); then
-  ok "check-entwurf-v2-surface gate passes (surface adapter + pi-native/MCP wiring)"
-else
-  bad "check-entwurf-v2-surface gate FAILED or surface adapter missing — run: ./run.sh check-entwurf-v2-surface"
-fi
+# check-entwurf-v2-surface is a SOURCE-SHAPE gate: it strip-types-runs a .ts gate
+# (which imports typebox, a dev dep) to assert the surface source shape. Under
+# node_modules that cannot run (strip-types refused + dev deps absent), AND its
+# subject — the shipped surface source shape — is a repo/release invariant already
+# enforced by the release gate. So on an INSTALLED host, confirm the surface source
+# SHIPPED and defer the exhaustive gate; the live runtime wiring (flag/tool/MCP verb)
+# is already proven by the grep checks just above. Running the full .ts gate here
+# produced a FALSE "gate FAILED" on every installed host.
+case "$REPO" in
+  */node_modules/*)
+    if [ -f "$V2_SURFACE_SRC" ]; then
+      ok "check-entwurf-v2-surface: shipped surface source present; exhaustive source-shape gate is a repo/release invariant (not run under node_modules)"
+    else
+      bad "entwurf-v2-surface.ts missing from the installed package — the v2 surface source did not ship"
+    fi
+    ;;
+  *)
+    if [ -f "$V2_SURFACE_SRC" ] && (cd "$REPO" && node --experimental-strip-types scripts/check-entwurf-v2-surface.ts >/dev/null 2>&1); then
+      ok "check-entwurf-v2-surface gate passes (surface adapter + pi-native/MCP wiring)"
+    else
+      bad "check-entwurf-v2-surface gate FAILED or surface adapter missing — run: ./run.sh check-entwurf-v2-surface"
+    fi
+    ;;
+esac
 # prefixRoots operator policy (5d-4b): the shared env SSOT both v2 surfaces read. Display
 # ONLY — the parser SSOT lives in entwurf-v2-surface.ts (proven by check-entwurf-v2-surface);
 # the doctor does NOT re-implement parsing. Unset ⇒ no prefix promotion (the safe default).