@junghanacs/entwurf 0.12.0 → 0.12.1

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented here. Format follows [Kee
 
 ## Unreleased
 
+## 0.12.1 — 2026-06-29
+
+### Fixed
+
+- **Installed MCP bridge boots from npm/node_modules.** The 0.12.0 launcher ran `src/index.ts` through Node strip-types, but Node refuses type stripping below `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). The npm tarball now carries a clean tsc-emitted bridge JS closure under `mcp/entwurf-bridge/dist/`, and `start.sh` runs that dist path when installed while keeping the strip-types source path for development clones.
+- **Stale dist files cannot ship.** `build-bridge` removes `mcp/entwurf-bridge/dist` before emit, and `check-pack-install` plants a stale sentinel before `npm pack` to prove prepack cleaned the tree. This closes the orphan-emit tarball contamination found during the 0.12.1 C review.
+- **npm bin symlink installs resolve the package root.** `run.sh`, `start.sh`, and the bridge protocol smoke now resolve symlinks before computing their root, so `node_modules/.bin/entwurf` and `node_modules/.bin/entwurf-bridge` work like direct package paths.
+- **Two live ACP MUST smokes no longer flake on model-in-loop phrasing.** `smoke-acp-carrier-augment-live` proved augment delivery by asking the model to echo a `SECRET_PROJECT_CODE` planted in a `/tmp` `AGENTS.md` — current Claude correctly refuses that as a prompt-injection/exfil pattern, so the MUST gate failed even though the augment rode the wire and the empty carrier billed clean. It now uses a benign factual marker (an internal build codename) asked back as a normal "answer from project context" task. `smoke-acp-bundled-mcp-live` asked the model for "values only, one per line" yet asserted on field-name-labeled lines (`socketState: alive`), so a compliant bare-value reply was dropped by the envelope filter while the `[tool:done]` notice truncated `socketState`; it now requests labeled lines so the three identity fields are deterministically observable. Neither change weakens the gate (same MUST assertions, same non-circular gid proof) — both only realign the observation contract with current model behavior.
+
+### Changed
+
+- **Install docs are npm-first and pi-adapter-second.** The README and clean-host walkthrough now lead with neutral `npm install @junghanacs/entwurf`, document the `entwurf` / `entwurf-bridge` bins, and move pi to the optional ACP-provider/control-socket adapter lane (`@earendil-works/pi-coding-agent >=0.80.2 <0.81`). `pi install npm:...` is no longer the public primary install recipe.
+- **Pi peers are optional for the neutral package.** The `@earendil-works/*` peer trio and `typebox` are marked optional so a plain npm install can boot the MCP bridge without pulling the pi adapter stack. The pi loader lane is still verified separately with explicit pi peers.
+- **Garden id concept is documented up front.** The concept primer now defines garden/garden id as the shared address space for independent harness citizens, not a worker name or proof of pi ownership, and points callers to `entwurf_peers` + `entwurf_v2` instead of hand-picking transports.
+
+### Verification
+
+- `./run.sh check-pack-install` passes with the neutral npm install regression: package bins present, optional pi peers absent, installed dist bridge answers `tools/list`, and pi-loader registration still passes on the explicit pi-peer lane.
+- Remote `hejdev6` real-install probe from the packed tarball passed: local npm install, package bins, optional pi peers absent, installed `entwurf-bridge` `tools/list`, `entwurf install` with isolated HOME, and `entwurf check-bridge`. The host's real HOME also exposed a pre-existing stale `~/.pi/agent/entwurf-targets.json` symlink to `pi-shell-acp`; fix with `entwurf setup:links --force` or an explicit `ENTWURF_TARGETS_PATH` if that old registry is intentional.
+- `LIVE=1 ./run.sh release-gate /tmp/psa-release-gate-0.12.1.GUFDUb` tiers `MUST: PASS=17 FAIL=0 SKIP=0` with `BEHAVIOR: PASS=1 FAIL=0` on 2026-06-29; log `/tmp/entwurf-release-gate-0.12.1-20260629T191543.log` (the two live-smoke observation fixes above were what moved the gate from `MUST FAIL=1` to green; the install change is harness-neutral and touches no ACP code path).
+
 ## 0.12.0 — 2026-06-29
 
 > This release hard-cuts the project from `pi-shell-acp` to **`entwurf`**. It is not a compatibility rename: the package/provider/model/MCP identity is now `entwurf`, v1 entwurf verbs are gone, and `entwurf_v2` is the canonical garden-id dispatch verb. The repo is **entwurf-core (v2 dispatch) + meta-bridge + pi adapter + ACP plugin**. Pi remains an important adapter and ACP host, but the project subject is the garden-citizen dispatch substrate. Verified release floor: `pnpm check`, `check-pack`, `check-pack-install`, and `LIVE=1 ./run.sh release-gate <scratch>` MUST tier `PASS=17 FAIL=0 SKIP=0` on 2026-06-29, with BEHAVIOR (advisory model-in-loop autonomous MCP tool-selection) `PASS=1 FAIL=0` and recorded separately from the cut decision.

package/README.md

@@ -8,9 +8,11 @@
 
 npm package: <https://www.npmjs.com/package/@junghanacs/entwurf>
 
+Legacy package: [`@junghanacs/pi-shell-acp`](https://www.npmjs.com/package/@junghanacs/pi-shell-acp). `entwurf` is its 0.12+ successor line: the same work renamed around the garden-citizen dispatch substrate rather than the pi adapter.
+
 > **Public, active development.** Real working code, still young. Verify it in your own workflow before relying on it all day. Evidence calibration: [VERIFY.md](./VERIFY.md); native async-delivery capability levels: [DELIVERY.md](./DELIVERY.md).
 
-> **Current state for 0.12.0.** This repo is **entwurf-core (v2 dispatch) + a meta-bridge + a pi adapter + an ACP plugin**. Pi is one supported harness adapter — important because it supplies control sockets and hosts the ACP plugin today — but it is not the project subject. Claude Code is shipped through the meta-bridge; pi is shipped through the control-socket adapter; Codex and Antigravity (`agy`) reach the garden with verified delivery probes, documented per launch mode in [DELIVERY.md](./DELIVERY.md), with shipped adapter/install lanes landing after the 0.12.0 doc cut. The ACP plugin is Claude-first; Cortex/vendor-governed ACP backends are future lanes.
+> **Current state for 0.12.1.** This repo is **entwurf-core (v2 dispatch) + a meta-bridge + a pi adapter + an ACP plugin**. Pi is one supported harness adapter — important because it supplies control sockets and hosts the ACP plugin today — but it is not the project subject. Claude Code is shipped through the meta-bridge; pi is shipped through the control-socket adapter; Codex and Antigravity (`agy`) reach the garden with verified delivery probes, documented per launch mode in [DELIVERY.md](./DELIVERY.md), with shipped adapter/install lanes landing after the 0.12.0 doc cut. The ACP plugin is Claude-first; Cortex/vendor-governed ACP backends are future lanes.
 
 <details>
 <summary>Watch archived pre-0.12 demo (2131×1142 GIF, click to expand)</summary>
@@ -68,68 +70,126 @@ This meta-bridge installer/doctor is **Claude Code only** in the shipped 0.12.0
 A few words that look unusual for a coding tool.
 
 - **Entwurf** (기투, projection-of-self) — sibling sessions with their own runtime boundary. Not "delegate," not "worker," not "sub-agent." Spawn, resume, and live peer messaging are first-class.
+- **Garden / garden id** — the garden is the shared address space where independent harness sessions become citizens without losing their own runtime or transcript. A garden id is the stable address of one such citizen (for pi, a garden-native session id like `YYYYMMDDTHHMMSS-<6hex>`; for native harnesses, a meta-session id minted by the `SessionStart` hook). It is not a worker name and not proof that pi owns the session. The same-looking id may name a live control socket, a dormant pi record, or a mailbox-backed native session, so callers discover facts with `entwurf_peers` and deliver with `entwurf_v2` instead of choosing a transport by hand.
 - **Engraving** — optional short operator text delivered through each backend's native identity carrier. Not a giant hidden prompt, not a tool catalog.
 - **MCP** — in this repo, MCP is just the transport by which ACP-backed sessions receive pi capabilities that native pi exposes directly as extensions. It is not a general MCP platform. Explicit `entwurfProvider.mcpServers` only; no ambient `~/.mcp.json` scanning, no automatic retrieval. The same `entwurf-bridge` entry can also be wired into another host's MCP catalog (Claude Code, Codex, Antigravity, …) when the operator chooses. `entwurf_self` returns an authoritative pi-session or trusted meta-session identity envelope; `entwurf_v2` can deliver from plain external MCP hosts, but only pi-session and trusted meta-session senders are replyable.
 - **Session persistence** — re-attaches pi to the same remote ACP session. Does not hydrate backend transcripts into pi history.
 
 ## Install
 
-`entwurf` is a thin garden-citizen bridge with a **Claude-first ACP plugin**. Pi is the host adapter for that ACP plugin today; Codex runs as a direct pi-native provider by default, with a tested `ENTWURF_ACP_FOR_CODEX=1` opt-in that routes it through the ACP bridge too. The bridge does not provide Claude credentials, tokens, or subscription access, and does not bypass any backend auth. Whatever the operator's local `claude` / `codex` already trusts is what entwurf uses.
+`entwurf` is a neutral npm package first. Install the package with `npm` (or
+`pnpm`/`yarn`) and then wire the harness you want to use. Pi is still the
+adapter that hosts the ACP plugin and live control-socket surface, but the base
+install is **not** `pi install npm:...` anymore.
+
+The package exposes two bins:
 
-`pi` installs the bridge from an `npm:` source (the published `@junghanacs/entwurf` package) in **global** (default, writes to `~/.pi/agent/settings.json`) or **project** (`-l` flag, writes to `.pi/settings.json`) scope. A `git:` source and a local clone remain available for tracking `main` or hacking on the bridge.
+- `entwurf` → `run.sh` (installer, checks, meta-bridge doctor/install)
+- `entwurf-bridge` → the MCP stdio launcher (`mcp/entwurf-bridge/start.sh`)
 
-After installing the package, run `run.sh install .` in your target project. The script writes the `entwurfProvider` block into `.pi/settings.json` with the correct absolute path for `entwurf-bridge/start.sh` — no hand-editing required. The exact location of `run.sh` depends on which install path was used (each section below shows it). For manual configuration, [`pi/settings.reference.json`](./pi/settings.reference.json) is the reference shape — see [Settings](#settings) below.
+The bridge does not provide Claude credentials, tokens, or subscription access,
+and does not bypass any backend auth. Whatever the operator's local `claude` /
+`codex` / pi runtime already trusts is what entwurf can use.
 
-### From npm via pi — global
+### From npm — user/global install
 
 ```bash
-pi install npm:@junghanacs/entwurf
+npm install -g @junghanacs/entwurf
+
+# wire a target project for the pi adapter / ACP plugin lane
 cd /path/to/your-project
-~/.pi/agent/npm/node_modules/@junghanacs/entwurf/run.sh install .
-~/.pi/agent/npm/node_modules/@junghanacs/entwurf/run.sh check-bridge
+entwurf install .
+entwurf check-bridge
 ```
 
-### From npm via pi — project (`-l` flag)
+This writes `.pi/settings.json` in the target project with the absolute path to
+the installed `entwurf-bridge` launcher. It also links the target registry under
+`~/.pi/agent/` for spawn-bg resume. The global install is the easiest path when
+Claude Code's USER-scope MCP registration should work from every cwd.
+
+### From npm — project-local install
 
 ```bash
 cd /path/to/your-project
-pi install -l npm:@junghanacs/entwurf
-./.pi/npm/node_modules/@junghanacs/entwurf/run.sh install .
-./.pi/npm/node_modules/@junghanacs/entwurf/run.sh check-bridge
+npm install --save-dev @junghanacs/entwurf
+
+npx entwurf install .
+npx entwurf check-bridge
 ```
 
-### From source via pi — global (alternative)
+For manual MCP registration from a project-local install, point the host at:
 
-```bash
-pi install git:github.com/junghan0611/entwurf
-cd /path/to/your-project
-~/.pi/agent/git/github.com/junghan0611/entwurf/run.sh install .
-~/.pi/agent/git/github.com/junghan0611/entwurf/run.sh check-bridge
+```text
+/path/to/your-project/node_modules/.bin/entwurf-bridge
 ```
 
-### From source via pi — project (`-l` flag)
+or at the package launcher directly:
 
-```bash
-cd /path/to/your-project
-pi install -l git:github.com/junghan0611/entwurf
-./.pi/git/github.com/junghan0611/entwurf/run.sh install .
-./.pi/git/github.com/junghan0611/entwurf/run.sh check-bridge
+```text
+/path/to/your-project/node_modules/@junghanacs/entwurf/mcp/entwurf-bridge/start.sh
 ```
 
-### Local development clone
+### From source — development clone
 
 ```bash
 git clone https://github.com/junghan0611/entwurf ~/repos/gh/entwurf
 cd ~/repos/gh/entwurf
 pnpm install
-pi install ./
+
 ./run.sh install /path/to/your-project
 ./run.sh check-bridge
 ```
 
-> **First time on a clean Ubuntu / Debian / macOS host?** See the [clean-host walk-through](./docs/setup-clean-host.md) — `nvm` + `pnpm` + `pi` install, `pi install git:...`, `run.sh install .`, the missing-auth boundary surface, and an authenticated runtime smoke for Claude.
+A development clone runs the bridge source through Node's strip-types path;
+an npm-installed package runs the prebuilt JS under `mcp/entwurf-bridge/dist/`
+because Node refuses to strip `.ts` files under `node_modules`.
+
+### Pi adapter / ACP plugin lane
+
+To use the `entwurf` provider inside pi, install a compatible pi binary
+separately (`@earendil-works/pi-coding-agent >=0.80.2 <0.81`). Then point pi at
+the npm-installed package or development clone:
+
+```bash
+# global npm install path
+pi -e "$(npm root -g)/@junghanacs/entwurf" --list-models entwurf
+
+# project-local install path
+pi -e ./node_modules/@junghanacs/entwurf --list-models entwurf
+```
+
+For daily operator sessions, launch pi with `--entwurf-control` and a garden id
+from `entwurf new-session-id`; see [Garden launcher](#garden-launcher). Older pi
+versions may silently miss the provider/extension surface, so treat the pi floor
+as release-critical for the ACP/plugin lane. A host that only uses
+`entwurf-bridge` from Claude Code / Codex / Antigravity does not need pi until it
+tries an `owned-outcome` spawn-bg resume target.
+
+### External MCP host lane
+
+After any npm install, register `entwurf-bridge` with the external host:
+
+```bash
+claude mcp add --scope user entwurf-bridge \
+  entwurf-bridge
+```
+
+If the host does not inherit the npm bin directory, use an absolute path to the
+bin or `start.sh`. For a garden-native Claude Code meta-session (replyable by
+garden id), run:
+
+```bash
+entwurf install-meta-bridge
+entwurf doctor-meta-bridge
+```
+
+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.
+
+> **First time on a clean Ubuntu / Debian / macOS host?** See the [clean-host walk-through](./docs/setup-clean-host.md) — Node/npm install, auth-free bridge boot, optional pi adapter verification, and authenticated runtime smokes.
 
-> **Post-install checks.** `run.sh check-bridge` proves the `entwurf-bridge` MCP surface loads (provider registration + protocol/negative-path), with no backend auth needed. To prove the **ACP backend actually answers** — the bridge spawns Claude through the provider path and a real turn comes back — run `LIVE=1 run.sh smoke-acp-provider-live` (it needs the operator's local Claude auth/credit). Package-source routing — so that a `provider=entwurf` Entwurf target from a `git:` / `npm:` install resolves and does not die with `Unknown provider "entwurf"` (#29) — is pinned deterministically by `run.sh check-package-source-routing`, which runs inside `pnpm check` and the release gate.
+> **Post-install checks.** `entwurf check-bridge` (or `./run.sh check-bridge` from a clone) proves the `entwurf-bridge` MCP surface loads with no backend auth needed. To prove the **ACP backend actually answers** — the bridge spawns Claude through the pi provider path and a real turn comes back — run `LIVE=1 entwurf smoke-acp-provider-live` from an installed package/clone with pi and Claude auth available. Package-source routing is pinned deterministically by `run.sh check-package-source-routing`, which runs inside `pnpm check` and the release gate.
 
 > **Extension set — do not filter.** `entwurf` ships three `pi.extensions` entries as a single set: the ACP provider extension (`pi-extensions/acp-provider.ts`) plus `pi-extensions/entwurf-control.ts` and `pi-extensions/model-lock.ts`. Filtering some out via pi's object-form package configuration can leave the model lock or entwurf-control surface in a broken state. Disable the entire package or none of it unless you know precisely which boundary you are turning off.
 

package/docs/setup-clean-host.md

@@ -1,305 +1,203 @@
 # Clean-host setup walk-through
 
 End-to-end install of **entwurf** on a host with only `git` available — no
-node, no pnpm, no pi binary, no dotfiles. The point is to validate the public
-install surface as an outside user would experience it.
+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.0 install recipe. The earlier per-command
-> cleanhost evidence dumps (recorded 2026-05-18, pi-shell-acp era) are not
-> carried forward here — they live in git history. The command *shape* below is
-> the current one; substitute your own host.
+> **Scope.** This is the entwurf 0.12.1 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.
 
-`entwurf` is a thin meta-bridge. It does not provide, copy, or mediate any
-backend credential — it spawns the official backend CLI and lets it read
-whatever auth the user already trusts on the host (AGENTS.md Hard Rule #9).
+`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
+or the pi adapter read whatever auth the user already trusts on the host
+(AGENTS.md Hard Rule #9).
 
 ## Reference target
 
 Written against a clean Ubuntu / Debian / macOS host reachable via SSH, here
-called `cleanhost`. `nvm` + `corepack` keep the path identical across them.
+called `cleanhost`. `nvm` keeps the path identical across them.
 
 ```bash
-ssh cleanhost 'uname -a; whoami; which git node pnpm pi 2>/dev/null'
-# expect: git present, node/pnpm/pi absent
+ssh cleanhost 'uname -a; whoami; which git node npm pi claude 2>/dev/null'
+# expect on a fully clean host: git present, node/npm/pi/claude absent
 ```
 
 ## Pin matrix
 
-These pins are the verification axis — drift from them moves you off the
-walk-through and onto your own integration.
-
-| Component | Pin | Source of truth |
+| Component | Pin / floor | Source of truth |
 |---|---|---|
-| Node | **24** (LTS line) | `engines.node` is `>=22.6.0` (minimum, for TypeScript strip-types); verification axis is **24** |
-| pnpm | **10.33.0** (via corepack) | matches the version entwurf's `pnpm check` chain runs under |
-| pi binary | **`@earendil-works/pi-coding-agent` 0.80.2 or newer** | npm registry; binary name `pi`; garden-native session identity needs `--session-id` / `--name` |
-| entwurf install path | `npm:@junghanacs/entwurf` (published release path) | the `git:github.com/junghan0611/entwurf` source path remains the alternative for tracking `main` |
+| Node | **24** recommended; `>=22.6.0` minimum | `engines.node` (Node strip-types / ESM runtime) |
+| npm | bundled with Node 24 | public package install path |
+| entwurf | `@junghanacs/entwurf` | neutral npm package; exposes `entwurf` and `entwurf-bridge` bins |
+| pi binary | **optional**, `@earendil-works/pi-coding-agent >=0.80.2 <0.81` | needed only for the pi adapter / ACP provider / spawn-bg resume lane |
 
-## Stage 0 — Node 24 + pnpm via nvm
+## Stage 0 — Node 24 via nvm
 
 ```bash
 ssh cleanhost
 
-# nvm (user-scope, no global root)
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
 source ~/.nvm/nvm.sh
 
-# Node 24 explicit — not --lts (re-runnable across calendar drift)
 nvm install 24
 nvm alias default 24
-node -v          # expect: v24.x.y
-
-# pnpm via corepack (user-scope, no -g)
-corepack enable
-corepack prepare pnpm@10.33.0 --activate
-pnpm -v          # expect: 10.33.0
+node -v
+npm -v
 ```
 
 Drift points:
-- corporate proxy / sudo policy may block `curl | bash`. Fallback: clone `nvm` via git and source `~/.nvm/nvm.sh` directly.
-- `corepack enable` needs Node 24's bundled corepack — confirm with `corepack -v` before activate.
-- **Subshell trap**: `nvm install 24 | tail` runs the install inside a pipe-subshell, so PATH changes do not reach the parent shell and `node -v` fails right after. Drop the pipe, or follow with an explicit `nvm use 24` in the same shell (the recipe above already does).
+- Corporate proxy / sudo policy may block `curl | bash`. Fallback: clone `nvm`
+  via git and source `~/.nvm/nvm.sh` directly.
+- **Subshell trap**: `nvm install 24 | tail` runs in a pipe-subshell, so PATH
+  changes do not reach the parent shell. Drop the pipe, or run `nvm use 24` in
+  the same shell afterward.
 
-## Stage 1 — pi binary
+## Stage 1 — neutral entwurf npm install
+
+Install the public package with npm. This does **not** require pi.
 
 ```bash
-# global install with the user's nvm shim (no system-wide root)
-npm i -g @earendil-works/pi-coding-agent
-pi --version     # expect: 0.80.2 or newer
+npm install -g @junghanacs/entwurf
 
-# pi's data dir is created lazily on first run
-pi --help | head -5
+which entwurf
+which entwurf-bridge
+entwurf --help | head -5
 ```
 
-Drift points:
-- if `npm i -g` lands outside the nvm shim, `pi` may not be on `$PATH` after a shell reload. `which pi` should resolve under `~/.nvm/versions/node/v24.*/bin/pi`.
-- backend ACP server packages (e.g. `claude-agent-acp`) ship as pinned `dependencies` of entwurf and get installed in the next stage — **do not install them globally yourself**.
+`@earendil-works/*` pi packages are optional peers. A neutral npm install should
+not pull them in as package dependencies. That separation is intentional: the
+MCP bridge can boot in Claude Code / Codex / Antigravity without pi present.
 
-## Stage 2 — entwurf install (npm path)
+## Stage 2 — auth-free bridge boot
 
-Install the bridge from the published npm package. `pi install` lands it under
-`~/.pi/agent/npm/node_modules/@junghanacs/entwurf/`, then `run.sh install` wires
-it into a target project's `.pi/` directory.
+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/`.
 
 ```bash
-# package-side install — populates ~/.pi/agent/npm/node_modules/...
-pi install npm:@junghanacs/entwurf
-
-# verify the package landed where pi expects it
-ls ~/.pi/agent/npm/node_modules/@junghanacs/entwurf/
-
-# project-side wire-up — pick an empty cwd for the smoke
-mkdir -p ~/entwurf-smoke
-cd ~/entwurf-smoke
-~/.pi/agent/npm/node_modules/@junghanacs/entwurf/run.sh install .
-```
-
-`run.sh install .` runs the one-shot wiring the consumer-project README
-documents: writes `.pi/` config, registers the extensions (provider,
-`entwurf-control`, `model-lock`), adds `entwurfProvider.mcpServers.entwurf-bridge`,
-and links `~/.pi/agent/entwurf-targets.json` to the package's
-`pi/entwurf-targets.json`. Expected log lines:
-
-```
-install: added entwurfProvider.mcpServers.entwurf-bridge
-install: updated <cwd>/.pi/settings.json
-install: package source -> ~/.pi/agent/npm/node_modules/@junghanacs/entwurf
-install: linked ~/.pi/agent/entwurf-targets.json -> .../pi/entwurf-targets.json
+node --input-type=module <<'JS'
+import { spawn } from 'node:child_process';
+const child = spawn('entwurf-bridge', { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, NODE_PATH: '' } });
+let out = '', err = '';
+const timer = setTimeout(() => { child.kill('SIGKILL'); console.error(err || 'timeout'); process.exit(1); }, 5000);
+child.stderr.on('data', d => err += d);
+child.stdout.on('data', d => {
+  out += d;
+  try {
+    const msg = JSON.parse(out.trim());
+    const names = (msg.result?.tools ?? []).map(t => t.name).sort();
+    for (const n of ['entwurf_v2','entwurf_peers','entwurf_self','entwurf_inbox_read']) {
+      if (!names.includes(n)) throw new Error(`missing ${n}: ${names.join(',')}`);
+    }
+    clearTimeout(timer);
+    child.kill('SIGTERM');
+    console.log(names.join(','));
+  } catch {}
+});
+child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }) + '\n');
+JS
 ```
 
-Drift points:
-- with no backend credentials yet, `run.sh install .` still completes — it does not validate backend auth, only registers the bridge.
-- `~/.pi/agent/npm/...` is fixed by pi's install scanner. Use `pi install -l npm:...` to land it inside the project cwd instead.
-- the `git:github.com/junghan0611/entwurf` source path is the alternative for tracking `main` or hacking on the bridge; it clones into `~/.pi/agent/git/...` with the same `run.sh install .` wire-up.
-- `pi install` runs `npm install` inside the package; `husky` is dev-only and absent on a target host, so its `prepare` hook silently exits 0.
+Expected: a comma-separated tool list containing all four `entwurf_*` tools,
+exit code 0, no backend auth required.
 
-## Stage 3 — package-surface verification (auth-free)
+## Stage 3 — wire a project for the pi adapter / ACP plugin (optional)
 
-Proves the bridge is registered and visible to pi, without touching any
-backend.
+If the host will run pi sessions or the Claude ACP provider through pi, install
+a compatible pi binary separately and wire the target project.
 
 ```bash
+npm install -g @earendil-works/pi-coding-agent@0.80.2
+pi --version
+
+mkdir -p ~/entwurf-smoke
 cd ~/entwurf-smoke
+entwurf install .
+entwurf check-bridge
 
-# the entwurf provider should now appear in pi's catalog
-pi --list-models entwurf
-# expect: curated model ids under provider entwurf
-#   (claude-opus-4-8, claude-sonnet-4-6, ...), exit code 0
+# pi adapter/provider registration smoke
+pi -e "$(npm root -g)/@junghanacs/entwurf" --list-models entwurf
 ```
 
-Deterministic gates (no live backend) from the clone:
+Drift points:
+- `entwurf install .` writes `.pi/settings.json`, registers the bundled
+  `entwurf-bridge`, and links `~/.pi/agent/entwurf-targets.json` to the package's
+  `pi/entwurf-targets.json`.
+- Older pi versions may silently miss the provider/extension surface. Use the
+  pinned floor (`>=0.80.2 <0.81`) for release verification.
+- A host that only uses the external MCP bridge can skip this stage until it
+  needs `owned-outcome` spawn-bg resume or pi-native control sockets.
+
+## Stage 4 — Claude Code meta-bridge (optional, garden-native native sessions)
+
+For an external Claude Code session to be replyable by garden id, install the
+meta-bridge plugin globally. This is still a neutral npm-package command; it
+registers Claude Code USER-scope MCP + the SessionStart hook.
 
 ```bash
-cd ~/.pi/agent/git/github.com/junghan0611/entwurf
-pnpm install
-pnpm typecheck
-./run.sh check-bridge                  # MCP tool contract (tools/list + negatives)
-./run.sh check-package-source-routing  # install-root resolver, fail-fast routing
-# full deterministic floor (longer, ~60 gates): pnpm check
+entwurf install-meta-bridge
+entwurf doctor-meta-bridge
 ```
 
-Drift points:
-- `pi --list-models entwurf` failing here means the install scanner did not register the extension — most often a node engines mismatch or a permission issue under `~/.pi/`. Re-run Stage 2 after fixing.
-- the `pnpm install` step may emit an `Ignored build scripts` warning for transitive deps (pnpm refuses postinstall hooks by default). Our surface does not need them; the warning is informational.
-
-## Stage 4 — runtime smoke (backend auth required)
+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.
 
-Backend authentication is **the operator's responsibility** and lives entirely
-outside entwurf. The 0.12.0 runtime floor is **Claude-first** — the
-`smoke-acp-*-live` floor inside `release-gate` exercises the Claude ACP backend
-only (there is no standalone per-backend smoke command). Codex reaches the
-garden as a native citizen (ACP only via the `ENTWURF_ACP_FOR_CODEX=1` opt-in,
-off the live floor); the Gemini path is deprecated.
+## Stage 5 — backend auth and live runtime smoke
 
-### Stage 4 prep — Claude CLI install + login
+Backend authentication is the operator's responsibility and lives entirely
+outside entwurf. For the Claude ACP lane:
 
 ```bash
-# Claude — official install script (writes into ~/.local/bin, no sudo).
 curl -fsSL https://claude.ai/install.sh | bash
 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
 source ~/.bashrc
-which claude && claude --version
-
-# interactive login (opens browser or prints a token-paste URL)
 claude login
-```
-
-`claude login` writes into Claude's own state directory. entwurf does not
-provide, copy, decrypt, or mediate these credentials. If a smoke fails, run the
-backend CLI directly first (`claude -p "ping"`); if that also fails, the
-missing piece is upstream of entwurf.
-
-> **Codex / Gemini (optional).** `npm i -g @openai/codex` + `codex login` for
-> the Codex lane; `npm i -g @google/gemini-cli` + `gemini auth` for the
-> deprecated Gemini probe. Neither is on the 0.12.0 live floor — the
-> `smoke-acp-*-live` gates run the Claude ACP backend only; Codex/agy delivery
-> is captured as raw probes in [DELIVERY.md](../DELIVERY.md).
-
-### Stage 4 prep — interactive setting (optional)
-
-For live interactive use (vs. headless CI), pin tool-progress visibility:
 
-```bash
-node -e '
-const fs = require("fs");
-const path = process.env.HOME + "/entwurf-smoke/.pi/settings.json";
-const cur = JSON.parse(fs.readFileSync(path, "utf8"));
-cur.entwurfProvider = cur.entwurfProvider || {};
-cur.entwurfProvider.showToolNotifications = true;
-fs.writeFileSync(path, JSON.stringify(cur, null, 2) + "\n");
-'
-```
-
-`showToolNotifications` defaults to `true` already; setting it explicitly pins
-the value for reproducibility. **No operator config is needed to make tool
-calls flow without prompts when a backend is invoked through entwurf** — the
-bridge runs the backend YOLO inside its own isolated overlay
-(`~/.pi/agent/*-config-overlay/`, AGENTS.md Hard Rule #10), so native backend
-config is neither read nor required on the bridged path.
-
-### Stage 4 — runtime smoke
-
-```bash
-ENTWURF=~/.pi/agent/git/github.com/junghan0611/entwurf
 cd ~/entwurf-smoke
-
-# lightweight: one Claude turn through entwurf (proves auth + bridge round-trip)
 pi --provider entwurf --model claude-sonnet-4-6 -p "reply with ok only"
-
-# full live floor (LIVE=1 required): pnpm check + the v2-native live gates
-# + the ACP plugin acceptance floor (10 smoke-acp-*-live smokes). Two-tier
-# MUST/BEHAVIOR summary; MUST owns the exit code. GLG authorizes the cut.
-LIVE=1 $ENTWURF/run.sh release-gate .
-```
-
-A passing turn is a full round-trip: bootstrap → ACP session → bridge response
-→ clean shutdown.
-
-Drift points:
-- a backend you have not authenticated fails loudly with `Authentication required` (Claude/Codex shape) or an early `EPIPE` (Gemini-CLI shape). **That is not an entwurf failure** — the bridge surfaces missing auth, it does not fix it. Add the credential and re-run.
-- `release-gate` honest-skips its LIVE-gated MUST steps when `LIVE!=1`; a real cut needs `LIVE=1` with `SKIP=0`.
-
-## Stage 5 — entwurf surface (optional)
-
-> Do not run Stage 5 until at least one authenticated `smoke-*` is green — a
-> live entwurf flow drives a real backend turn, so an unauthenticated host just
-> re-surfaces the Stage 4 auth noise.
-
-### Package-source ACP routing — auth-free, run this first
-
-Covers the boundary where a package-installed bridge (a `git:` / `npm:`
-settings source, not a local checkout) must still resolve so a
-`provider=entwurf` child does not die with `Unknown provider`:
-
-```bash
-# from the installed bridge root (auth-free, also in pnpm check)
-./run.sh check-package-source-routing
 ```
 
-It pins the package-source → install-root resolver math across the full install
-matrix (local / git / npm / missing × local + remote). The live ACP routing
-itself is exercised by the `smoke-acp-*-live` floor under `release-gate`.
+If the backend CLI fails directly (`claude -p "ping"`), fix that upstream first.
+`entwurf` surfaces missing auth; it does not repair it.
 
-### Resident control session
+## Stage 6 — garden/control-socket surface (optional)
 
-To address a long-lived pi session from another session (or an external MCP
-host like Claude Code), open it with `--entwurf-control`. A garden-native
-`--session-id` is **required** — a raw `pi --entwurf-control` (pi-assigned
-uuid) hard-exits at `session_start` before any model turn. Mint the id from the
-SSOT:
+To address a long-lived pi session from another session or an external MCP host,
+open it with `--entwurf-control`. A garden-native `--session-id` is required —
+a raw pi-assigned uuid hard-exits before any model turn.
 
 ```bash
-pi --session-id "$(/path/to/entwurf/run.sh new-session-id)" \
+pi --session-id "$(entwurf new-session-id)" \
   --entwurf-control --provider entwurf --model claude-sonnet-4-6
-# control socket: ~/.pi/entwurf-control/<sessionId>.sock
+# control socket: ~/.pi/entwurf-control/<garden-id>.sock
 ```
 
-Inside such a session, builtin `/new` / `/fork` / `/clone` are blocked (they
-would mint a non-garden uuid); use `/gnew` (alias `/garden-new`) for a
-same-terminal fresh garden session (a zero-token switch into a pre-created
-garden file).
-
-The bridge exposes four MCP tools — `entwurf_v2` (canonical dispatch /
-delivery verb), `entwurf_peers` (discover live citizens), `entwurf_self`
-(identity envelope), `entwurf_inbox_read` (drain meta-bridge inbox). From any
-other pi session on the same host, call `entwurf_peers` to list live targets
-and `entwurf_v2` to message/hand off by garden id. Dispatch is fire-and-forget
-on a live target; set `wants_reply` if you need an answer. See AGENTS.md
-`Send-is-throw` for the full rule.
-
-### Native-harness wake (optional)
-
-For an external Claude Code session to receive async messages, install the
-meta-bridge plugin globally (Claude Code only):
-
-```bash
-./run.sh install-meta-bridge     # plugin + USER-scope entwurf-bridge MCP
-./run.sh doctor-meta-bridge      # fail-loud health check
-```
+Use `entwurf_peers` to discover citizens and `entwurf_v2` to deliver by garden
+id. Do not choose the transport by hand: the same-looking id may name a live pi
+socket, a dormant pi record, or a mailbox-backed native session.
 
 ## Teardown
 
-The bridge has no daemon. To remove everything installed:
-
 ```bash
-# entwurf clone
-rm -rf ~/.pi/agent/git/github.com/junghan0611/entwurf
-
-# project wiring (per-project)
+# project wiring
 rm -rf ~/entwurf-smoke/.pi
 
 # meta-bridge plugin (if installed)
-~/.pi/agent/git/github.com/junghan0611/entwurf/run.sh uninstall-meta-bridge 2>/dev/null || true
+entwurf uninstall-meta-bridge 2>/dev/null || true
 
-# pi binary
-npm uninstall -g @earendil-works/pi-coding-agent
+# package and optional pi binary
+npm uninstall -g @junghanacs/entwurf
+npm uninstall -g @earendil-works/pi-coding-agent 2>/dev/null || true
 
-# node + pnpm via nvm
+# node via nvm
 nvm uninstall 24
 rm -rf ~/.nvm
 ```
 
-This walk-through is the **verification floor** underneath every downstream
-publish step — install, package surface, and at least one authenticated
-runtime smoke green — not the publish trigger itself. GLG owns the publish/tag
-decision.
+This walk-through is a verification floor underneath release cuts: neutral npm
+install, installed bridge boot, optional pi adapter registration, and at least
+one authenticated runtime smoke when cutting a live release. GLG owns the
+publish/tag decision.