@junghanacs/entwurf 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to this project will be documented here. Format follows [Kee
 
 ## Unreleased
 
+## 0.12.2 — 2026-06-29
+
+### Fixed
+
+- **Claude Code meta-bridge installs on the supported 2.1.x floor.** Claude's plugin validator is a closed schema whose accepted marketplace keys differ by patch level; 0.12.1's root-level `marketplace.json` `description` passed on Claude 2.1.195 but failed on the floor host's 2.1.97 with `Unrecognized key: "description"`. The marketplace manifest now keeps only the minimal root keyset confirmed on the floor (`name`, `owner`, `plugins`), leaving explanatory text in installer/docs comments rather than in closed-schema JSON.
+- **Installed meta-bridge MCP wiring no longer bakes pnpm store paths.** On npm/pnpm-installed hosts, the user-scope Claude MCP entry now points at the stable `entwurf-bridge` bin instead of `$REPO/mcp/entwurf-bridge/start.sh`, whose `$REPO` can be a `.pnpm/@junghanacs+entwurf@.../node_modules/...` hash path that goes stale on version or peer changes. Development clones still pin to that clone's `start.sh`; both branches preserve the external Claude sender env (`ENTWURF_BRIDGE_EXTERNAL_AGENT_ID=external-mcp/claude-code`, `ENTWURF_BRIDGE_REQUIRE_META_SENDER=1`).
+
+### Added
+
+- **`check-meta-manifest-schema` — a CLI-version-independent meta-bridge manifest guard.** The new deterministic gate pins the Claude marketplace/plugin/hooks manifests to the minimal keysets used by the meta-bridge, including the load-bearing hook event names (`SessionStart`, `CwdChanged`, `UserPromptSubmit`, `FileChanged`) and hook command keys. It also asserts `meta-bridge-state.py::desired_mcp()` chooses the installed-vs-clone MCP wiring without invoking a real Claude CLI. The gate is wired into `pnpm check` so future decorative closed-schema keys fail before release.
+
+### Verification
+
+- `pnpm check` passes with the new `check-meta-manifest-schema` static guard included.
+- `./run.sh smoke-meta-install-state` passes, proving the state manager/doctor consumers still follow `desired_mcp()` without drift.
+- Installed-location regression probe passes: running `scripts/check-meta-manifest-schema.py` from a synthetic `node_modules/@junghanacs/entwurf` package no longer self-fails.
+- Claude Code 2.1.97 floor validation passed on `hejdev6` after removing the root marketplace `description`; current Claude 2.1.195 validation also passes with warnings only.
+- `LIVE=1 ./run.sh release-gate /tmp/psa-release-gate-0.12.2.NLGhet` passed on 2026-06-29 with `MUST: PASS=17 FAIL=0 SKIP=0` and `BEHAVIOR: PASS=1 FAIL=0`; log `/tmp/entwurf-release-gate-0.12.2-20260629T205339.log`.
+
+## 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.