@junghanacs/entwurf 0.45.0 → 0.51.0

package/README.md

@@ -1,10 +1,9 @@
 # entwurf
 
-`entwurf` connects independent agent harnesses as visible siblings: open a new session,
-reopen a supported dormant sibling in tmux, or reach an existing sibling by **garden id**. Fresh
-sessions open in the caller's Herdr workspace or tmux session by default; explicit tmux
-placement can name another existing session. Each harness keeps its own runtime,
-authentication, tools and transcript.
+`entwurf` connects independent agent harnesses as visible siblings. Open a fresh sibling, or reopen
+or message an existing one by its **garden id**. Every harness keeps its own runtime,
+authentication, tools and transcript; Entwurf adds identity, delivery, receipts and named
+lifecycle verbs.
 
 ![entwurf — a forged screwdriver for visible sibling sessions](docs/assets/entwurf-hero.jpg)
 
@@ -17,112 +16,91 @@ A recorded source-checkout demo: callback → task → native Bash → reply.
 
 [![npm](https://img.shields.io/npm/v/@junghanacs/entwurf?logo=npm)](https://www.npmjs.com/package/@junghanacs/entwurf) · maintained by [junghanacs.com](https://junghanacs.com/)
 
-A sibling is a visible session with its own runtime boundary, not a disposable
-worker or a subagent of a new central harness. Entwurf supplies identity, delivery,
-receipts and named lifecycle verbs; the operator and native harnesses keep steering.
-Git branches, worktrees, file isolation and internal delegation remain their concern.
+## Why
+
+- **Siblings, not workers.** A sibling is a visible session with its own runtime boundary, not a
+  disposable worker or a subagent of a new central harness. You and the native harnesses keep
+  steering; branches, worktrees, file isolation and internal delegation stay their concern.
+- **Native harnesses stay native.** Claude Code keeps its hooks and tools, Codex its own threads and
+  delegation, pi its extensions. Entwurf reconstructs no prompt, hydrates no transcript and mediates
+  no credential.
+- **One address.** A garden id names a record-backed citizen. A pane, socket, native session id or
+  model is a carrier or an observation, never a second address.
+- **The same verbs on both screens.** In an ordinary tmux session or inside a Herdr workspace, a
+  sibling opens and reopens beside you through the same tools. The rail follows where the caller
+  runs, with no fallback from one to the other.
+
 [Short answers: FAQ](./FAQ.md).
 
-[ENTWURF.json](./ENTWURF.json) is the sole editable source for the product-owned guidance
-currently extracted there: MCP descriptions/parameters, durable short variants, the static
-entwurf_v2 reject hints, the static visible-resume reject hints of entwurf_resume_call, the static tmux launch-stage reject hints of entwurf_fresh_call and entwurf_resume_call (herdr rail hints stay in code), five static delivery-result clauses of the entwurf_v2 dirty-lock and remote-pair receipts (receipt syntax and the mailbox envelope stay in code) and the record-less-socket reject hint's text around its fix command (the command itself stays in code). It is not a user prompt override; its payload revision is independent of
-package releases. Bootstrap, notices, other hints and ACP guidance still have their existing owners. Operator engraving/configuration is unchanged.
+## The four verbs
 
-| Verb | Tool | Where it lands | Harnesses |
+| Verb | Tool | What it does | Harnesses |
 |---|---|---|---|
-| **Open** a new sibling | `entwurf_fresh_call` | Herdr: a new unfocused tab in the caller's workspace. tmux: a new window in the caller's session, or an existing session named by `placement.tmuxSession`; without an explicit tmux placement, a Codex caller opens beside its own TUI pane | Herdr: pi, Claude Code. tmux: pi, pi-durable, Claude Code, Copilot, OMP, Codex |
-| **Reopen** a dormant sibling | `entwurf_resume_call` | A visible tmux window under the same garden id, with its record selecting the native session (Pi: identity-checked recorded transcript supplies launch metadata; Claude Code: `claude --resume <session id>` at the record cwd); the verb submits no prompt | pi, Claude Code |
-| **Retire** one sibling the human operator explicitly requested | `entwurf_retire_call` | One guarded attempt on that target: a Pi shutdown request or Claude Code fd-pinned process termination. Refused/unknown outcomes remain possible; the record stays for guarded same-id return. Not a grant, a roster cleanup or an automatic retry | pi, Claude Code |
-| **Message** an existing sibling | `entwurf_v2` | Its own rail: control socket, self-fetch mailbox or native push; delivery starts no process | pi, pi-durable, Claude Code, Copilot, OMP, Codex (Antigravity native push is paused, #152) |
-
-Antigravity is a legacy citizen: an existing conversation registers itself, and Entwurf never
-launches one. Its native push is paused (#152): on the measured external path the agy language server
-refused Entwurf's calls for a missing CSRF token, so a message to it is refused as `native-push-paused`. A launch receipt is neither the new sibling's address nor proof that it
-processed its task; the sibling's own callback envelope supplies its garden id.
-
-The package holds the v2 core, native-harness bridges, a pi adapter and an ACP
-plugin. ACP is one ingress, not the boundary; pi is one adapter, not the center.
-Claude and Cortex Code are ACP backends. Codex and Antigravity stay native so they
-retain their own tools and work context. Capabilities differ by rail: a shipped
-citizen is not a promise of every lifecycle operation.
-
-[Releases](https://github.com/junghan0611/entwurf/releases) contain each cut's notes and acceptance
-receipts; [CHANGELOG](./CHANGELOG.md) records source history.
+| **Open** | `entwurf_fresh_call` | Opens a new visible sibling beside the caller — a new Herdr tab, or a tmux window — and hands it a first task. The sibling's own callback supplies its garden id | tmux: pi, pi-durable, Claude Code, Copilot, OMP, Codex. Herdr: pi, pi-durable, Claude Code |
+| **Reopen** | `entwurf_resume_call` | Reopens a dormant sibling under the same garden id, its record selecting the native session. Submits no prompt | pi, pi-durable, Claude Code |
+| **Message** | `entwurf_v2` | Delivers to an existing sibling over its own rail. Starts no process | pi, pi-durable, Claude Code, Copilot, OMP, Codex |
+| **Retire** | `entwurf_retire_call` | One guarded attempt on one sibling the human operator explicitly named. The record stays for a later same-id return | pi, Claude Code |
 
-## Install
+Every verb returns a receipt, not the sibling's turn result. Capabilities differ by rail, so a
+shipped citizen is not a promise of every lifecycle operation; [DELIVERY](./DELIVERY.md) owns each
+rail's admission. Antigravity is a legacy citizen: it registers an existing conversation, Entwurf
+never launches one, and its native push is paused (#152).
 
-**Choose by where you work. Bring your own harnesses, subscriptions and login.**
-The native durable route below additionally supplies an app/TUI, Entwurf's own thin composition of
-the durable app upstream omits from its npm release; it does not supply credentials or take
-ownership of the harness.
+Capabilities here describe this source and ref; an installed release can differ — see its
+[release notes](https://github.com/junghan0611/entwurf/releases) and
+[package-specific setup](./docs/setup-clean-host.md#requirements).
 
-### Direct — ordinary shell or tmux
+## Install
 
-Prerequisites: **Node >=24.0.0**, Python 3 for `setup`, and any harnesses you choose
-to use, already installed and authenticated. Pi is optional-by-presence, supported
-range `>=1.4.0 <1.5`; Claude Code supported floor `>=2.1.306` is required for its
-managed exec-hook lifecycle. pnpm is needed only for source-checkout setup.
+Bring your own harnesses, subscriptions and logins. Entwurf installs its own bytes and composes the
+harnesses it finds; it needs Node 24 or newer, Python 3 for `setup`, and whichever harnesses you
+use, already installed and signed in.
 
-**Release state.** The Pi range above belongs to the published 0.41.2, which ships the Pi
-1.4.0 SDK set, as 0.41.1 did. The previous `0.41.0` ships the Pi 1.3.0 set and requires Pi 1.3.x; the README
-inside that tarball and the Herdr snapshot `v2026.10.22-herdr.0.41.0` are its contract.
+### Direct — ordinary shell or tmux
 
 ```bash
-npm install -g @junghanacs/entwurf@0.41.2
+npm install -g @junghanacs/entwurf
 entwurf setup /path/to/your-project
 entwurf check-bridge
 ```
 
-`setup` composes each harness it finds and reports PASS / SKIP / FAIL. An absent
-harness is an explicit SKIP; a detected incomplete/below-floor integration is a
-named FAIL with nonzero exit, not a false green. `check-bridge` proves the installed
-MCP bytes boot and list tools without backend auth; it does **not** certify a real
-model turn or native receive rail.
-
-[Clean-host setup](./docs/setup-clean-host.md) owns project-local/source installs,
-config paths, optional backends, doctors, upgrade/repair and uninstall.
-Codex also needs your own hook-trust decision, app-server and exact-directory
-consent: [the operator steps](./docs/setup-clean-host.md#three-operator-decisions-before-fresh).
-Plain MCP registration alone does not make a garden citizen.
-
-**Platform bounds:** Linux is the certified harness-rail axis. macOS Entwurf-only
-installation is **CERTIFIED (CI)**; native harness rails, ACP and mux remain
-**NOT CERTIFIED — pending physical host**, so detected wiring can still leave setup non-green.
-WSL2 and native Windows have **experimental CI previews**, not general or physical-host support.
-The native-Windows preview covers Pi citizens and offline scripted delivery, not vendor turns,
-other harnesses, shell entrypoints, fresh/resume, mux, Herdr or ACP.
-[BASELINE](./BASELINE.md#release-host-baseline) owns the version-specific receipts and gaps;
-an npm package without an `os` restriction is not an all-platform certification.
+`setup` composes each harness it finds and reports PASS / SKIP / FAIL. An absent harness is an
+explicit SKIP; a detected incomplete or below-floor integration is a named FAIL with a nonzero exit,
+not a false green. `check-bridge` proves the installed MCP bytes boot and list their tools without
+backend auth; it does **not** certify a model turn or a receive rail.
 
-### Native durable (pi-durable)
+[Clean-host setup](./docs/setup-clean-host.md) owns the supported harness versions, installing a
+chosen package version, project-local and source installs, the per-harness steps (Codex needs
+[your own trust decision and app-server](./docs/setup-clean-host.md#three-operator-decisions-before-fresh)),
+doctors, upgrade, repair and uninstall. Plain MCP registration alone does not make a garden citizen.
+Linux is the certified harness-rail axis; [BASELINE](./BASELINE.md#release-host-baseline) owns the
+macOS, WSL2 and native-Windows evidence split, and an npm package without an `os` restriction is not
+an all-platform certification.
 
-**The package supplies Entwurf's owned app/TUI carrier and nine exact Pi 1.4.0 SDK
-members** (the previous 0.41.0 supplies the 1.3.0 set). No separate runtime checkout, patch, build or ordinary Pi CLI is needed.
-The launch verifies carrier integrity and every reachable SDK edge's name/version;
-incomplete, drifted or mixed supply refuses by name.
+### Native durable (pi-durable)
 
 ```bash
 entwurf pi-durable --provider <provider> --model <model-id> --width task-wide
 entwurf pi-durable --continue
 entwurf pi-durable --resume
+entwurf pi-durable --session <native id>
 ```
 
-`--continue` opens this directory's latest-created durable session. `--resume` lists its
-sessions, most recently written first, by creation time, garden id and last write, and
-reopens the one you choose as it was saved; a cancelled choice opens nothing.
-
-The contact adds garden identity and two-way mailbox communication. Entwurf owns the
-thin app/TUI composition (shipped as an emitted JS carrier); execution, models/auth, queues,
-SQLite, transcripts and recovery remain the upstream SDK's:
-[Hard Rule 17](./AGENTS.md#hard-rules), **supply the missing surface; do not become the harness**.
-
-Optional `--native-module <absolute file>` initializes trusted ESM before runtime/TUI
-imports, then installs its default native Extension after the contact.
-`--native-module-dir <absolute directory>` loads that named directory's top-level
-`*.extension.mjs` files in byte-wise order instead. No automatic module discovery or
-classic Pi API shim; guards are not a sandbox or rollback.
-[Native setup](./docs/setup-clean-host.md#2b-optional-native-durable-pi-durable)
-owns flags, refusals and the extension contract.
+The package supplies Entwurf's thin app/TUI carrier, emitted from its own canonical production
+source, and the exact pi SDK set it declares; the launch verifies both and refuses incomplete,
+drifted or mixed supply by name. No separate runtime checkout,
+patch, build or ordinary Pi CLI is needed. The contact adds garden identity and two-way mailbox
+communication; execution, models, auth, queues, storage and recovery stay the upstream SDK's
+([Hard Rule 17](./AGENTS.md#hard-rules): **supply the missing surface; do not become the harness**).
+On a CLI reopen, name the original `--native-module <absolute file>` or
+`--native-module-dir <absolute directory>` again if needed. Public garden-id
+`entwurf_resume_call` is bridge-only: it restores neither those modules nor the old seat. To retain
+them, use the explicit CLI in the terminal you choose, after confirming the old owner has exited.
+For an SDK upgrade, normally close the owner and back up the complete SQLite session file set,
+including WAL/SHM, before the first write; verify the exact version and artifact, then reopen the
+same identity. [Setup §2b](./docs/setup-clean-host.md#2b-optional-native-durable-pi-durable) owns
+selectors and refusals; the [SDK upgrade boundary](./docs/setup-clean-host.md#default-radius-for-a-requested-pi-sdk-upgrade)
+owns the operating and publication gates.
 
 ### Herdr workbench
 
@@ -130,37 +108,36 @@ owns flags, refusals and the extension contract.
 herdr plugin install junghan0611/entwurf/plugins/herdr --yes
 ```
 
-The [Herdr guide](./plugins/herdr/README.md#from-a-raw-linux-box-in-nine-steps) says which
-runtime each ref installs.
-
-This separate path activates Herdr-integrated **pi and Claude Code** with an
-independently locked runtime and an observation pane; it puts no Entwurf bins on PATH.
-An Entwurf release does not automatically re-pin that runtime: while 0.45.0 is an unpublished
-candidate, main's lock rides the `herdr-checkout` verification carrier, and the published 0.41.2
-runtime stays pinned by the Herdr tag `v2026.10.24-herdr.0.41.2`.
-[Herdr guide](./plugins/herdr/README.md) owns install, use, evidence and removal;
-the plugin does not own delivery or the Herdr launch rail.
+This separate path activates Herdr-integrated **pi and Claude Code** with its own locked runtime
+and an observation pane. By default it puts no Entwurf bins on PATH; a runtime that carries
+`herdr-plugin-expose-operator` makes exactly one `entwurf` link, and only when you ask for it.
+An Entwurf release does not re-pin that runtime by itself; the
+[Herdr guide](./plugins/herdr/README.md#from-a-raw-linux-box-in-nine-steps) says which runtime each
+ref installs and owns install, use, evidence and removal. The plugin owns neither delivery nor the
+Herdr launch rail.
 
-### Garden launcher
+## First steps
 
-After direct setup, start a pi citizen in your project:
+Start a citizen in your project:
 
 ```bash
 cd /path/to/your-project
 entwurf pi
-# equivalent when the package is registered (also the Herdr plugin's spelling):
-pi --entwurf-control
 ```
 
-`entwurf pi` execs your own pi with the control flag. A plain pi may load the
-package without becoming a citizen. The record mints the garden id; do not inject
-a session id. Native harness launch and manual Herdr argv instructions live in
-[setup §2–§5](./docs/setup-clean-host.md#2-optional-pi-adapter--acp-plugin).
+`entwurf pi` execs your own pi with the control flag (`pi --entwurf-control` is equivalent once the
+package is registered); the record mints the garden id, so do not inject a session id.
+`entwurf claude [args…]` execs the `claude` on your PATH with its arguments unchanged; a Claude Code
+session is a citizen through the hooks `entwurf install-meta-bridge` installed
+([setup §3](./docs/setup-clean-host.md#3-optional-claude-code-native-citizen)), however it started.
+`entwurf pi-durable` is the durable contact above. `entwurf --help` is the quick overview of the
+other entries and `entwurf help all` the full catalog; `entwurf help team` and
+`entwurf help remote-pair` are the two guides.
 
-In that **harness session**, ask the agent to:
+In that harness session, ask the agent to:
 
-1. Call `entwurf_self` to confirm its authoritative identity.
-2. Call `entwurf_peers` to discover existing citizens and their liveness facts.
+1. Call `entwurf_self` to confirm its identity.
+2. Call `entwurf_peers` to see existing siblings and their liveness facts.
 3. Pick a live garden id and call `entwurf_v2` with a message, for example:
 
 ```json
@@ -172,22 +149,12 @@ In that **harness session**, ask the agent to:
 }
 ```
 
-These are tools, not shell subcommands. Pi calls
-`mcp__entwurf_bridge__<verb>` through Pi's built-in MCP. The bridge exposes **nine**
-verbs; a pi citizen has **seven active + two hidden** (`entwurf_inbox_read` and
-`entwurf_register_native`), since it has no mailbox and its own extension births it.
-Those counts describe the source; a running host offers what its already-loaded bridge
-listed, so see [applying new source to a running host](./docs/setup-clean-host.md#applying-new-source-to-a-running-host).
-The server key stays `entwurf-bridge`. An operator/trusted-project MCP entry with
-that normalized namespace can replace the registration by Pi's own precedence;
-`/mcp` shows it, and Entwurf does not scan or fight that choice.
+These are MCP tools inside a session, not shell commands; pi reaches them as
+`mcp__entwurf_bridge__<verb>` through its built-in MCP. A running host offers what its
+already-loaded bridge listed:
+[applying new source to a running host](./docs/setup-clean-host.md#applying-new-source-to-a-running-host).
 
-## Entwurf orchestration
-
-One narrow dispatch capability connects independent siblings, not an agent factory.
-The record is the **sole address authority**. A pane, socket, native transcript id,
-model or process marker is a carrier or observation, never a second address axis.
-Liveness is read at dispatch time; an id's shape does not tell you its transport.
+## How delivery works
 
 ### `entwurf_v2` — canonical dispatch verb
 
@@ -198,75 +165,50 @@ pi / pi-durable / Claude Code / Copilot / OMP / Antigravity / Codex
       → control-socket | self-fetch mailbox | native-push
 ```
 
-**Delivery starts no process.** A live pi receives over its record-addressed control
-address, an armed self-fetch citizen (Claude Code, Copilot, OMP, pi-durable) through its
-mailbox, a probe-alive native-push citizen (Codex; Antigravity is paused, #152) through its own
-conversation or thread. Anything else is refused honestly, never launched into. The receipt
-is a receiver acceptance boundary, a durable mailbox file or an injection, never completion;
-`wants_reply` is etiquette, not waiting. [DELIVERY](./DELIVERY.md#control-socket-acceptance-boundaries-120)
-owns what each boundary means and each rail's admission.
-
-The lifecycle verbs in the [table above](#entwurf) return their own receipts, never a delivery
-result: fresh a launch receipt (the sibling's callback envelope supplies its garden id), resume
-separate LAUNCH and OBSERVATION receipts, retire separate action, record and lock results.
-**Retirement is never autonomous:** it needs the human operator's explicit target and action, and
-no role, caller identity or tool annotation grants it ([DELIVERY](./DELIVERY.md#candidate-lifecycle-commands-are-not-delivery-boundaries-147)).
-
-**Mux launches; it never delivers.** Fresh opens in the caller's Herdr workspace or tmux session;
-`placement.tmuxSession` names another existing tmux session and is refused inside Herdr. The model
-is required and `cwd` is a literal absolute directory. Missing or ambiguous context refuses with no
-fallback. Exact argv, identity checks and limits: [tmux launch](./docs/mux-launch-rail.md),
-[Herdr launch](./docs/herdr-launch-rail.md).
-
-### Remote siblings — declared pairs across hosts
-
-Opt-in. The v2 file below is read by the published 0.41.2; 0.41.1 and earlier read the
-earlier single-pair file. On each host, write `~/.pi/agent/entwurf-remote-pair.json` (mode `0600`; a
-moved agent dir or meta store moves it, see [setup §2c](./docs/setup-clean-host.md#2c-optional-remote-pair-between-two-hosts-107)). The ids
-below are fictional; use your own records' garden ids:
-
-```json
-{
-  "version": 2,
-  "routes": [
-    {
-      "localGardenId": "20260101T090000-a1b2c3",
-      "remoteGardenId": "20260101T091500-d4e5f6",
-      "ssh": "host-b",
-      "remotePairFile": "/home/me/.pi/agent/entwurf-remote-pair.json"
-    }
-  ]
-}
-```
-
-The other host carries the mirror route: the two garden ids swapped, its own SSH alias for this
-host, and this file's canonical absolute path. Then send with the ordinary `entwurf_v2` to the
-remote garden id: one SSH attempt over your own account, checked and dispatched by the host that
-holds the record. There is no peer discovery, wake or retry. Why: [remote sibling principles](./docs/remote-sibling-principles.md);
-contract: [DELIVERY](./DELIVERY.md#remote-pairs-107-149-declared-pairs-across-hosts); steps and the
-hand conversion from the earlier file: [setup §2c](./docs/setup-clean-host.md#2c-optional-remote-pair-between-two-hosts-107).
-
-### Team bookmarks — `team.json`
-
-A person's bookmark of the siblings one project works with. Copy [`team.json.example`](./team.json.example)
-to an ignored `team.json` at the project root and fill names, backend, garden id, native session id
-and cwd from Entwurf's record facts; read liveness from `entwurf_peers` when you dispatch. Entwurf
-does not load it as runtime configuration, and it is not configuration for identity, routes, roles, permissions or lifecycle. The
-example's own notes say the rest.
+**Delivery starts no process.** The record is the sole address authority, and liveness is read at
+dispatch time: a live pi receives over its control address, an armed self-fetch citizen through its
+mailbox, a probe-alive native-push citizen in its own conversation. Anything else is refused, never
+launched into. The receipt is the receiver's acceptance boundary, a durable mailbox file or an
+injection — never the sibling's turn result; `wants_reply` is etiquette, not waiting.
+[DELIVERY](./DELIVERY.md#control-socket-acceptance-boundaries-120) owns what each boundary means.
+
+**Lifecycle verbs keep their own receipts.** Open returns a launch receipt, not an address; reopen
+separates its launch from its observation; retire reports action, record and lock separately.
+**Retirement is never autonomous:** it needs the human operator's explicit target and action, and no
+role, caller identity or tool annotation grants it
+([DELIVERY](./DELIVERY.md#candidate-lifecycle-commands-are-not-delivery-boundaries-147)).
+
+**Lifecycle launch is separate from `entwurf_v2` delivery.** Open and reopen place a sibling in the
+caller's Herdr workspace or tmux session; `placement.tmuxSession` names another existing tmux session and is refused inside Herdr.
+Missing or ambiguous context refuses with no fallback:
+[tmux launch](./docs/mux-launch-rail.md) · [Herdr launch](./docs/herdr-launch-rail.md).
+
+### Remote siblings and team bookmarks
+
+**Remote pairs** are opt-in. Each host declares the pair in its own file, and `entwurf_v2` to the
+remote garden id makes one SSH attempt over your own account, checked and dispatched by the host that
+holds the record — no discovery, wake or retry. `entwurf help remote-pair`, the steps in
+[setup §2c](./docs/setup-clean-host.md#2c-optional-remote-pair-between-two-hosts-107), the
+[principles](./docs/remote-sibling-principles.md) and the
+[contract](./DELIVERY.md#remote-pairs-107-149-declared-pairs-across-hosts).
+
+**Team bookmarks:** [`team.json.example`](./team.json.example) is a person's note of the siblings one
+project works with, copied to an ignored `team.json`. Entwurf never loads it as configuration for
+identity, routes, roles, permissions or lifecycle. `entwurf help team`.
 
 ## Concepts
 
-**Entwurf** (기투, projection-of-self) connects independent visible siblings;
-**garden id** names a record-backed citizen, not its pane or native transcript.
-[FAQ](./FAQ.md) explains ACP, MCP and context carriers.
+**Entwurf** (기투, projection-of-self) connects independent visible siblings; a **garden id** names
+a record-backed citizen, not its pane or native transcript. The package holds the v2 core, the
+native-harness bridges, a pi adapter and an ACP plugin. ACP is one ingress, not the boundary; pi is
+one adapter, not the center. Claude and Cortex Code are ACP backends; Codex and Antigravity stay
+native so they keep their own tools and work context. The pi adapter registers the compiled bridge
+with Pi's built-in MCP after record birth, while pi's own receive stays its record-addressed control
+address. [FAQ](./FAQ.md) explains ACP, MCP and context carriers.
 
-## Pi integration
-
-The pi adapter registers the compiled bridge with Pi's built-in MCP after record
-birth; Pi supervises the MCP child. **MCP is ingress; pi receive remains the
-record-addressed control address (a Unix socket, or the native-Windows preview's named
-pipe).** Garden identity and dispatch stay Entwurf's.
-Codemode is harness-internal, not another garden citizen.
+Product guidance and CLI help each have one editable source: [ENTWURF.json](./ENTWURF.json) for
+the MCP tool descriptions and the hints extracted there, [ENTWURF-CLI.json](./ENTWURF-CLI.json) for
+`entwurf --help`. [AGENTS](./AGENTS.md#architecture) lists exactly what each carries.
 
 ## Operation guides
 
@@ -292,6 +234,8 @@ credential mediation, subscription bypass, pane-typing delivery or hidden orches
 
 Installation, a doctor, a fixture and an exact release candidate prove different things;
 none is interchangeable with the others or an all-host/long-haul guarantee.
+[Releases](https://github.com/junghan0611/entwurf/releases) carry each cut's notes and acceptance
+receipts; [CHANGELOG](./CHANGELOG.md) records source history.
 
 ## References
 

package/VERIFY.md

@@ -121,7 +121,7 @@ that moved out of `scripts/` and into a file beside its subject would otherwise
 >
 > Be honest about its cost, because it is a MUST: it spends real model turns on the operator's configured runtimes (two pi siblings, each resumed once, plus one Claude Code sibling), it READS the operator's real runtime config, and the siblings' native session transcripts stay in the real pi agent dir — they are not cleaned up, and they are part of the evidence a resume was real. The fence is per-axis rather than absolute: the four meta roots (records, mailbox, receivers, senders) are fixture for every cell, so no garden record is ever minted outside it; the native pi cell's control socket and v2 lock are fixture too; the ACP pi cell's are REAL and transient (see the paragraph above); and the Claude cell runs its runtime under the real HOME while its mailbox and meta stay fixture. The run ends by proving the operator's SIX real roots — the four meta roots plus `~/.pi/entwurf-control` and `~/.pi/entwurf-v2-locks` — hold the entry sets they started with, with no fixture garden id anywhere, and that proof now runs on the failure path as well as the green one. Missing prerequisites decline with the protocol SKIP (97), which `release-gate --cut` refuses rather than rounding up.
 >
-> **Fresh-call LIVE is on-demand, not part of `release-gate`.** `LIVE=1 ./run.sh smoke-mux-fresh-call-live` opens configured Pi and Claude Code siblings, spends four model turns (two in the caller's own session, two in a second SEAT session on the same private server — the #105 seat x cwd matrix), and preserves their native transcripts; run it directly whenever a cut changes mux fresh-call/launch behavior. Its private tmux servers and fixture-bound entwurf write axes make it deterministic about garden-record/socket residue, but those real native turns should not appear unexpectedly in every aggregate cut. **Both this smoke and `smoke-mux-lifecycle-live` enumerate `pi` and `claude-code` only — that exclusion is intentional.** A Copilot visible-fresh (step 9 clause 7) was accepted on 2026-08-25 as an operator-metered LIVE (receipts in `DELIVERY.md`'s Copilot matrix row and the issue #82 thread). It still spends Copilot premium quota, still needs its own grant to re-run, and is never folded into those loops or into the release-gate MUST tier.
+> **Fresh-call LIVE is on-demand, not part of `release-gate`.** `LIVE=1 ./run.sh smoke-mux-fresh-call-live` opens configured Pi and Claude Code siblings, spends four model turns (two in the caller's own session, two in a second SEAT session on the same private server — the #105 seat x cwd matrix), and preserves their native transcripts; run it directly whenever a cut changes mux fresh-call/launch behavior. Its private tmux servers and fixture-bound entwurf write axes make it deterministic about garden-record/socket residue, but those real native turns should not appear unexpectedly in every aggregate cut. **Both this smoke and `smoke-mux-lifecycle-live` enumerate `pi` and `claude-code` only — that exclusion is intentional.** Neither covers pi-durable same-id resume (#157 B3), and no LIVE or release gate does: its proof is the deterministic beside tests plus the local FULL/package floor, and its one public n=1 (Herdr, a pre-final candidate, synthetic callers) is a dated [BASELINE](./BASELINE.md) row, not a floor. The tmux path at the final candidate is unmeasured. Claude Code's same-id resume inside Herdr (#157 stage 4) is covered by no LIVE or release gate either: its proof is the deterministic beside tests plus the local FULL/package floor (a dated receipt, not a floor this text inherits: on 2026-11-02 the affected PARTIAL, six groups, and one frozen FULL of 1016 s passed at the stage-4 candidate, work surface `1075a5c8…` = HEAD `2734f524` plus the then-uncommitted changes; later edits leave that receipt valid for its snapshot but do not certify a later candidate, which owes its own), and its two test-owned n=1 runs on 2026-11-02 are a dated [BASELINE](./BASELINE.md) row, together with the operator vendor-data changes observed inside their windows — not a floor. A Copilot visible-fresh (step 9 clause 7) was accepted on 2026-08-25 as an operator-metered LIVE (receipts in `DELIVERY.md`'s Copilot matrix row and the issue #82 thread). It still spends Copilot premium quota, still needs its own grant to re-run, and is never folded into those loops or into the release-gate MUST tier.
 
 > **A visible-fresh receipt outside the MUST tier is no longer the general rule — it is Copilot's preserved exception.** #87 measured what that wording permitted: because clause 7 sat outside every aggregate, a harness could be admitted as a full D6 citizen that `entwurf_fresh_call` cannot open, carry an honest "not a supported harness" sentence in the delivery matrix, and still pass the whole floor toward a cut. From OMP onward, the FIRST release of a harness admitted under the #82 contract owes its clause 7 receipt as a release-gate MUST step (`smoke-omp-fresh-live`), and the deterministic half of the same rule (`check-harness-admission-parity`, inside `check:full`) makes a citizen backend missing from `FRESH_CALL_BACKENDS` a red floor rather than a documented one. Forward-only by decision: Copilot's row is not reopened. The contract lives in `docs/adding-a-harness.md` step 9, "The release stop"; this note exists so the cost discipline above is not read as permission.
 >
@@ -239,12 +239,19 @@ holds that node and the badge counts it, `pending` while recovered), and the car
 `durableLayout` drawn by the published pi-tui renderer on a fake terminal across rows 1–8 × cols
 1–12, count changes and resizes, against the pinned upstream screen for the zero-task case. Its
 editor is a fixed stand-in: the real `CustomEditor`, overlays, emoji width and a consumer's own task
-are the visible-terminal and consumer subjects. The 1.2 bootstrap child also observes `--resume`
-reopening the chosen session and cancelling to nothing (#143). Two more sandboxed children reach the
-reference app's settings and prompt mapping: one drives the real bootstrap against a loopback
-WebSocket Responses endpoint, whose received frames decide the forwarded transport and its
-continuation and the reference compaction policy (the SDK's background summary beside the turn, held on the
-wire while the turn answers; blocking and overflow kept, #146); the other renders the carrier prompt's skills section with no model, against a fixture
+are the visible-terminal and consumer subjects. Another sandboxed child holds the active transcript the
+TUI renders (#155 D1): the carrier runtime over a session seeded through the SDK's public API, through
+an open with a commit between its read and its watch, appends, one commit past the window's 100, a
+switch away and back, compaction-like and reset head markers, a read held across a switch, a refused
+read and the close. Its oracles are the entry IDs the SDK returned and, after close, a non-participant
+open's `Conversation.context().entries`; the SDK boundary is steered test-only at the Conversation
+prototype the child and carrier share. The bootstrap child on the pinned set also observes `--resume`
+reopening the chosen session, by what its screen shows, and cancelling to nothing (#143). Two more
+sandboxed children reach the owned app's settings and prompt mapping: one drives the real bootstrap
+against a loopback WebSocket Responses endpoint, whose received frames decide the forwarded transport
+and its continuation and the SDK's compaction policy under those settings (the SDK's background summary beside the turn, held on the
+wire while the turn answers; blocking and overflow kept, #146), each placed summary, manual ones
+included, heading the screen's active transcript; the other renders the carrier prompt's skills section with no model, against a fixture
 of both settings scopes, an absolute entry, a same-name pair and a wrong-base decoy.
 `check-pi-runtime-version` asks the
 same installed verifier (`check-pi-durable-beside`) whether this checkout resolves exactly the pinned SDK set (the native set; the PATH
@@ -269,8 +276,8 @@ constructed depth-3 mismatch refused by the verifier and seen by the oracle, the
 app's own model refusal before any birth — also with one installed `--native-module` initialized
 first, a reserved extension name refused before anything opens, one installed `--native-module-dir`
 initializing only its top-level `*.extension.mjs` (#134) and a directory without a module refused
-before anything opens — and the HOST kept a separate subject — a real pi 1.1.0
-binary (the previous generation) beside the pinned native set is a named pi FAIL with zero Pi wiring while pi-durable still
+before anything opens — and the HOST kept a separate subject — a real pi 1.2.0
+binary (below the supported range; a fixture version, not the pinned set's previous generation) beside the pinned native set is a named pi FAIL with zero Pi wiring while pi-durable still
 PASSes — not native admission. The carrier's rebuild
 equality is the owned source's emission (#141): the carrier claim `PI-DURABLE-CARRIER-EMIT-SOURCE-EQUAL`
 on every floor, `emit-pi-durable-carrier --check` as its CLI. The emitter's exact Node is red in the CI
@@ -282,7 +289,7 @@ caller/target/cross-harness LIVE are owed by `smoke-pi-durable-fresh-live`, a re
 | Axis | Required proof | Limit |
 |---|---|---|
 | Source | `pnpm run check:full` in the prepared SHA's CI `check` job | Does not prove an installed consumer. Kill-power of the committed claims is not re-measured per release (#144); the release record says so and lists any earlier-candidate PARTIAL separately. |
-| Packed install | `check-pack-install` | Real tarball, but checkout-visible. |
+| Packed install | `check-pack-install` | Real tarball, but checkout-visible. Every npm install it runs (the npm-managed root and second root, the four #130 pi-durable cells) and its pnpm consumer run with lifecycle scripts off (`--ignore-scripts`), so its executable, bridge and closure checks measure the tree as installed without the package's postinstall; that hook stays shipped as a registry-mode defense this gate does not exercise, and packed file modes remain the pack gate's evidence. |
 | Linux artifact consumer | required `check-install-container` CI job against one preserved candidate | Fixtures prove package/oracle shape, not a real Claude lifecycle. |
 | Exact release commit | the exact SHA's push run: all four required CI jobs green (the qualification body is not read, #144) | A different green SHA is not transferable evidence. |
 | macOS Entwurf-only install | required `macos-install-surface` CI job at the exact release SHA | Shape-only, CERTIFIED (CI): certifies the Entwurf-only install path on macOS only — never Claude/Copilot/OMP/agy wiring, the pi rail, ACP or mux. Promoted from non-voting (`continue-on-error`) to required in 0.20.0 after its first CERTIFIED (CI) green on a GitHub Actions `macos-latest` runner (not a physical host): run 34303884286 @ `70eda03` (2026-09-09), 65s, all 10 steps success — the packed candidate installed clean, `entwurf --help` and `entwurf check-bridge` ran (the latter listing the seven `entwurf-bridge` MCP tools of that date; 0.41.0 declares nine, unmeasured on that runner), an all-harness-absent `entwurf setup` reached `result: green` across the five documented SKIP probes (`pi`/`claude`/`agy`/`copilot`/`omp`), and five checked paths (`.pi`, `settings.json`, `.gemini`, `.copilot`, `auth.json.bak`) plus a byte-identical `auth.json` proved zero harness/credential writes. A macOS runner failure now blocks every release cut, the same as any other required job. |
@@ -374,7 +381,7 @@ The goal is not merely "invoke Claude Code." We want:
 **One install command to remember: `./run.sh setup <project>`.** It is idempotent — re-run the exact same command whenever anything looks wrong. There is no second install surface to juggle: from a clone `setup` runs the whole floor in order.
 
 1. `pnpm install` — installs the pinned development dependencies and builds the bridge (source-checkout bootstrap only; an installed package never runs npm/pnpm inside `node_modules`)
-2. pi wiring → `<project>/.pi/settings.json` + user-scope registration — only when a `pi` inside the supported range (`>=1.4.0 <1.5`) is on PATH; absent pi is an explicit zero-state SKIP, a below-floor pi is a detected FAIL. The user-scope entry is owner-recorded (#86 C2): another root's live-or-missing ownership makes this step a zero-write refusal (setup: pi FAIL) that names `takeover-user-scope`; the install-states bind the exact managed settings path (a drifted/symlinked/corrupt target is a zero-write refusal) and the inverse removes only the recorded owner's exact entry; `doctor-pi-package` reports the verdict
+2. pi wiring → `<project>/.pi/settings.json` + user-scope registration — only when a `pi` inside the supported range (`>=1.5.0 <1.6`) is on PATH; absent pi is an explicit zero-state SKIP, a below-floor pi is a detected FAIL. The user-scope entry is owner-recorded (#86 C2): another root's live-or-missing ownership makes this step a zero-write refusal (setup: pi FAIL) that names `takeover-user-scope`; the install-states bind the exact managed settings path (a drifted/symlinked/corrupt target is a zero-write refusal) and the inverse removes only the recorded owner's exact entry; `doctor-pi-package` reports the verdict
 3. Claude meta-bridge global plugin — only when `claude` is on PATH; otherwise skipped cleanly
 4. source stable-bin exposure — including certified `entwurf` → this checkout's `run.sh`, the managed runtime Copilot fresh resolves; helper units are attempted independently and a foreign helper is a named FAIL
 5. agy bridge + exact permission + statusline + `PreInvocation` hook — only when `agy` is on PATH; each adapter is idempotent and independently doctorable

package/demo/README.md

@@ -24,7 +24,7 @@ takes/helpers/tests are maintainer tooling and are deliberately excluded from th
 
 - Node at the `package.json#engines.node` floor; the checkout's pinned dependencies and
   current compiled bridge. After a source/bootstrap change, build with `pnpm run build-bridge`.
-- Pi at the checkout's supported floor (**current floor 1.4.0**); `entwurf` on PATH must be
+- Pi at the checkout's supported floor (**current floor 1.5.0**); `entwurf` on PATH must be
   the intended source stable-bin. Source evidence is not registry-package acceptance.
 - `herdr` on PATH at exactly `scripts/fixtures/herdr-supply.json#version`; `asciinema` v3.
 - Herdr's existing Pi integration at

package/docs/acp-backend-rail.md

@@ -135,7 +135,7 @@ Dep bump ledger. 0.38.0 (#145) changes only the pi SDK set; the ACP rows are unc
 | Surface | Declaration | Class | What a green actually says |
 |---|---|---|---|
 | Entwurf package | `package.json` `version` | checkout declaration, not a release receipt | names the package label these rows sit beside; whether that label shipped, and with which rows, is CHANGELOG's record |
-| pi runtime | SDK exact `1.4.0`, host `>=1.4.0 <1.5` | **exact** oracle + **closed range** | the SDK set this checkout builds, gates and (since #130) ships as exact production dependencies; an ordinary Pi host inside the range is accepted, and the ceiling moves only on measurement. The published 0.36.0 through 0.37.1 shipped the 1.2.0 set (#141); 0.38.0 (#145) is the first to carry 1.3.0. Historical: the published 0.33.0 through 0.35.1 ship SDK exact 1.1.0, 0.32.0 ships SDK exact 1.0.4 with the next-minor ceiling (ROADMAP's 2026-10-07 bump entry), and 0.31.0 declared the earlier peer floor 1.0.2 |
+| pi runtime | SDK exact `1.5.0`, host `>=1.5.0 <1.6` | **exact** oracle + **closed range** | the #155 development checkout's declared SDK set and derived host range, not a release or operating-host acceptance; an ordinary Pi host inside the range is accepted by the source's version predicate, and the ceiling moves only on measurement. The published 0.36.0 through 0.37.1 shipped the 1.2.0 set (#141); 0.38.0 (#145) is the first to carry 1.3.0. Historical: the published 0.33.0 through 0.35.1 ship SDK exact 1.1.0, 0.32.0 ships SDK exact 1.0.4 with the next-minor ceiling (ROADMAP's 2026-10-07 bump entry), and 0.31.0 declared the earlier peer floor 1.0.2 |
 | ACP wire SDK | `@agentclientprotocol/sdk 1.8.0` | **exact** | the shared wire oracle both adapters speak |
 | Claude ACP adapter | `@agentclientprotocol/claude-agent-acp 0.90.0` | **exact**, bundled | shipped since 0.36.1; resolved before any PATH fallback; declaration is not compatibility evidence |
 | Claude Agent SDK | `0.3.296` (transitive) | **exact** oracle | the runtime risk surface behind the adapter |

package/docs/external-mcp-host.md

@@ -11,9 +11,9 @@ the one-line registration; everything an operator needs to actually wire a host
 
   **Being garden-native is not the same as being replyable, and Copilot is the case that separates them.** Its hook writes a sender marker, so an `entwurf_v2` send carries its own garden id and the receiver learns who wrote — measured 2026-08-21 on Copilot CLI 1.0.80, where a live send arrived under its own garden id with `origin: "meta-session"` and `replyable: false`. Replyability arrived later and through a different process: a first-party extension (`run.sh install-copilot-receive`) that the CLI forks, which binds to the same V3 record and writes a receiver marker owned by its own pid (#82 RAIL 5). So a Copilot citizen is `replyable: true` exactly while that extension is armed for it, and `replyable: false` — honestly, with a real garden identity — when it is not installed, not launched with `COPILOT_CLI_ENABLED_FEATURE_FLAGS=EXTENSIONS` (which is what `entwurf copilot` sets for one invocation), not yet born, or gone. Read the two facts off different rails: the sender marker answers *who sent this*; the receiver marker answers *can a reply land*. The onboarding obligations are in [`adding-a-harness.md`](./adding-a-harness.md) step 7, and the evidence boundary — the managed LIVE acceptance that moved receive to D6, and what D7-partial / D3-pending still exclude — is in [`DELIVERY.md`](../DELIVERY.md).
 
-**Which verb an external agent should reach for:** to deliver to / reply to a garden id, use **`entwurf_v2`** — it is the canonical delivery surface and the only one that reads whether the target is live pi, dormant pi, a mailbox-backed self-fetch citizen (Claude Code, Copilot, OMP), or native-push Antigravity/Codex and routes correctly. Discover targets with `entwurf_peers`, confirm your own identity with `entwurf_self`, drain a mailbox with `entwurf_inbox_read`, and use `entwurf_register_native` only as the explicit/manual fallback for binding an already-running agy conversation. Open a NEW sibling with **`entwurf_fresh_call {backend, model, task, cwd?, placement?}`**, and reopen a DORMANT pi or Claude Code citizen under the same id with **`entwurf_resume_call {target}`**. **`entwurf_retire_call {target}`** (new in 0.41.0) attempts retirement of exactly one target, and only one the human operator explicitly requested; mounting or seeing the tool, a coordinator role or caller identity is not permission, and an unknown result is not a reason to replay.
+**Which verb an external agent should reach for:** to deliver to / reply to a garden id, use **`entwurf_v2`** — it is the canonical delivery surface and resolves the target's current rail: a live pi control socket, a deliverable self-fetch mailbox (pi-durable, Claude Code, Copilot or OMP), or probe-alive Codex native push. Dormant pi and undeliverable targets reject; Antigravity native push is paused and rejects before probing (#152). Discover targets with `entwurf_peers`, confirm your own identity with `entwurf_self`, drain a mailbox with `entwurf_inbox_read`, and use `entwurf_register_native` only as the explicit/manual fallback for binding an already-running agy conversation. Open a NEW sibling with **`entwurf_fresh_call {backend, model, task, cwd?, placement?}`**, and reopen a DORMANT pi, pi-durable or Claude Code citizen under the same id with **`entwurf_resume_call {target}`**. **`entwurf_retire_call {target}`** (new in 0.41.0) attempts retirement of exactly one target, and only one the human operator explicitly requested; mounting or seeing the tool, a coordinator role or caller identity is not permission, and an unknown result is not a reason to replay.
 
-Observed: Claude Code, Codex CLI, Antigravity CLI, GitHub Copilot CLI and OMP all reach this MCP bridge. Claude, Copilot and OMP become symmetric/replyable through mailbox-backed meta-sessions; agy and Codex use native-push. Codex's identity is request-scoped `_meta.threadId`, and its replyability requires that exact record plus a loaded app-server thread. Plain external hosts still need an identity lane to send.
+Observed: Claude Code, Codex CLI, Antigravity CLI, GitHub Copilot CLI and OMP all reach this MCP bridge. Claude, Copilot and OMP become replyable through deliverable mailbox-backed meta-sessions; Codex uses native push, while Antigravity's native-push rail is paused (#152). Codex's identity is request-scoped `_meta.threadId`, and its replyability requires that exact record plus a loaded app-server thread. Plain external hosts still need an identity lane to send.
 
 Prerequisites on the host running the external MCP client:
 
@@ -325,5 +325,5 @@ MCP registration gives the external harness the tools; the host still needs work
 
 For the maintained multi-harness setup and skill/command packaging details, see
 [agent-config](https://github.com/junghan0611/agent-config). See also the
-[concept primer](../README.md#concept-primer), the sender-envelope contract in
-[AGENTS.md](../AGENTS.md), and [custom skills](../README.md#custom-skills).
+[concepts](../README.md#concepts), the sender-envelope contract in
+[AGENTS.md](../AGENTS.md), and [custom skills](./setup-clean-host.md#custom-skills).