@junghanacs/entwurf 0.31.0 → 0.33.0

package/docs/setup-clean-host.md

@@ -28,8 +28,8 @@ evidence split, and its three states must not collapse into "macOS is supported"
 | npm/pnpm | npm is bundled with Node; pnpm is required for source setup | package or source installation |
 | Python 3 | required by `setup`/`install` (project-path normalization + settings writers); `--help`/`check-bridge` stay Python-free | pi/Claude/agy/Copilot/Codex wiring writers |
 | entwurf | global/project-local `@junghanacs/entwurf`, or a source checkout | operator command and garden capability |
-| pi | optional-by-presence, `>=1.0.2 <1.1` — absent is an explicit setup SKIP, below-floor is a named FAIL | ACP provider, control sockets |
-| Native durable (`pi-durable`) | optional-by-presence, operator-provided experimental source runtime at the fixed `…/entwurf/pi-durable/runtime`, pinned to `cd32f77` plus the narrow runtime-contact overlay; not supplied by ordinary Pi npm installation — absent is an explicit setup SKIP, present-but-not-the-pin a named FAIL | optional 0.31.0 candidate contact via `entwurf pi-durable`; first native Pi ↔ pi-durable admission/LIVE accepted on one Linux host, runtime provision and release acceptance separate (§2b) |
+| pi | optional-by-presence, `>=1.1.0 <1.2` — absent is an explicit setup SKIP, below-floor is a named FAIL | ACP provider, control sockets |
+| Native durable (`pi-durable`) | supplied by the Entwurf package (#130): a pinned upstream v1.1.0 app carrier plus the exact 1.1.0 pi SDK set as production dependencies — setup PASS when they verify, a named FAIL otherwise (never SKIP) | the `entwurf pi-durable` contact; native birth/LIVE on this supply surface is a separate release proof (§2b) |
 | Claude Code | optional, **`>=2.1.217`** — the exec-form hook floor | Claude ACP auth/runtime and mailbox-backed native citizen |
 | GitHub Copilot CLI | optional-by-presence, operator-installed and authenticated — absent is an explicit setup SKIP; detected composes all four units (birth/MCP/receiver/footer) | self-fetch citizen and visible fresh |
 | OMP (`omp`) | optional-by-presence, operator-installed — absent is an explicit setup SKIP; detected composes all four units (birth/MCP/`tools.xdev` setting/receiver) | self-fetch citizen and visible fresh (accepted on one host — see §4b) |
@@ -191,7 +191,7 @@ on Darwin; that is wiring, not a rail receipt. If `pi` is on PATH,
 Install the exact release floor, then wire the project:
 
 ```bash
-npm install -g @earendil-works/pi-coding-agent@1.0.2
+npm install -g @earendil-works/pi-coding-agent@1.1.0
 pi --version
 
 cd ~/entwurf-smoke
@@ -199,7 +199,7 @@ entwurf install .
 pi -e "$(npm root -g)/@junghanacs/entwurf" --list-models entwurf
 ```
 
-The supported range is `>=1.0.2 <1.1`. It is a hard minimum: installing this
+The supported range is `>=1.1.0 <1.2`. It is a hard minimum: installing this
 release onto a 0.83.x pi host upgrades the runtime rather than keeping the older
 minor. A host using only the external MCP bridge can skip pi until it needs a
 control socket; no delivery rail launches a pi process.
@@ -285,102 +285,119 @@ emacsclient -s "${PI_EMACS_AGENT_SOCKET:-server}" --eval '(...)'
 
 ## 2b. Optional native durable (`pi-durable`)
 
-**0.31.0 installation contract; first native admission/LIVE accepted on one Linux host.**
-The [DELIVERY matrix](../DELIVERY.md) records the 2026-10-06 LIVE36 candidate
-acceptance; release/artifact and runtime-supply evidence remain separate.
-Durable is a separate native harness contact, not an option automatically enabled
+**#130 / 0.32 installation contract: installing Entwurf supplies pi-durable.** The
+operator clones, patches, builds and copies nothing. 0.31.0 shipped the earlier
+source-runtime route (an operator checkout of Pi 1.0.2/source `cd32f77` at a fixed XDG
+place); that route is retired, not kept as a fallback, and its runtime directory is never
+read. Durable is a separate native harness contact, not an option automatically enabled
 by `entwurf pi` or by registering ordinary Pi's adapter.
 
-There are three different things to install or supply:
-
-1. **Entwurf:** the existing global/project-local npm or source-checkout route in
-   §1 stays unchanged. It supplies Entwurf bytes, not the native harness.
-2. **Durable library:** `@earendil-works/pi-durable` is npm-installable. A library
-   dependency does not install the experimental coding app/TUI or birth a citizen.
-3. **Native app/runtime:** upstream's experimental durable app runs from a Pi
-   source checkout through its source resolver. The pinned 1.0.2 ordinary
-   `pi-coding-agent` package excludes experimental app output; upgrading the global
-   `pi` CLI does not supply it. Entwurf's maintained contact requires the exact
-   upstream commit `cd32f7725fdbddbaecdff5b1e68491563394e0ca` plus its narrow
-   runtime-contact overlay, operator-provided dependencies and pinned runtime data.
-
-The upstream [library installation guide](https://github.com/earendil-works/pi/blob/cd32f7725fdbddbaecdff5b1e68491563394e0ca/packages/durable/README.md#installation)
-and [experimental app guide](https://github.com/earendil-works/pi/blob/cd32f7725fdbddbaecdff5b1e68491563394e0ca/packages/coding-agent/src/experimental/durable/README.md)
-describe different consumers. Running the bare upstream app does not attach
-Entwurf's garden contact. Entwurf does not install a second harness distribution,
-rebuild its controller/model/auth/storage system or proxy a subscription.
-
-### What the operator supplies
-
-The runtime lives at ONE fixed place, with no path override:
-`$XDG_DATA_HOME/entwurf/pi-durable/runtime` (an absolute `XDG_DATA_HOME`; otherwise
-`~/.local/share/entwurf/pi-durable/runtime`). It counts as the pin only when:
-
-- HEAD is `cd32f7725fdbddbaecdff5b1e68491563394e0ca`, nothing is staged, `git diff`
-  equals the packaged overlay `pi/pi-durable/overlay/runtime-contacts.patch` byte for
-  byte, and no non-ignored file is untracked;
-- the upstream source resolver
-  `packages/coding-agent/src/experimental/source-resolver.ts` is present;
-- the git-ignored model data in `packages/ai/src/providers/data` matches the pinned
-  digest: the bytes `@earendil-works/pi-ai@1.0.2` ships in `dist/providers/data`,
-  **including its `.manifest.json` dotfile** (recorded in
-  `pi/pi-durable/overlay/upstream-pin.json`).
-
-The operator supplies it by hand; Entwurf never downloads, installs, repairs,
-moves or deletes the runtime. The sequence below was run on a Linux host
-(2026-10-06); afterwards the runtime verifier `entwurf setup` consults returned
-the pin (exit 0) and the checkout's native contact cells passed against it.
-`ENTWURF_ROOT` is your Entwurf package root or checkout, which ships the patch:
+What the Entwurf package supplies:
+
+1. **The pi SDK set** — `@earendil-works/{pi-coding-agent, pi-ai, pi-tui, pi-agent-core,
+   pi-durable, chord, pi-mcp, pi-codemode, pi-telemetry}` at exactly `1.1.0`, plus
+   `proper-lockfile`, as Entwurf's own production dependencies (declared once in
+   `pi/pi-durable/overlay/upstream-pin.json` `sdk`). Model data rides the published
+   `pi-ai`; there is no catalog copy.
+2. **The native app/TUI carrier** — upstream does not publish the experimental durable
+   app (`pi-coding-agent` excludes `dist/experimental`; `pi-durable` on npm is the
+   library). Entwurf ships the six pinned app files from upstream tag `v1.1.0`
+   (`abe508e1b89912adde45528136c3221eb69acdd7`), its narrow runtime-contact overlay
+   applied to `runtime.ts`, type-stripped and relocated, in `pi/pi-durable/carrier/`
+   with upstream's MIT license. Each file's source blob and emitted digest are in the pin.
+   The carrier reaches pi-coding-agent's internals only through its resolver
+   (`pi/pi-durable/carrier-resolver.mjs`), which maps them to the published package's
+   own `dist/` as installed — never through a source checkout.
+
+The upstream [library guide](https://github.com/earendil-works/pi/blob/v1.1.0/packages/durable/README.md)
+and [experimental app guide](https://github.com/earendil-works/pi/blob/v1.1.0/packages/coding-agent/src/experimental/durable/README.md)
+describe what the carrier is. Running the bare upstream app does not attach Entwurf's
+garden contact. Entwurf does not rebuild the controller/model/auth/storage system or
+proxy a subscription; native execution, models, auth, queues, SQLite and recovery stay
+upstream-owned.
+
+### What Entwurf checks
+
+The carrier is runnable only when, read from where Entwurf is installed: every pinned
+carrier file, the license, the resolver and its relocation grammar are present
+(`pi-durable-package-incomplete`); each carrier file carries its pinned digest
+(`pi-durable-carrier-drift`); every declared SDK package resolves from the carrier
+(`pi-durable-sdk-absent`); and every reachable physical edge — from the carrier to each package,
+and from every package copy it reaches, at any depth, to its own `@earendil-works` dependencies —
+lands on a package of the declared name at exactly the pinned version (`pi-durable-sdk-mismatch`). The members declare one another with caret
+ranges, so semver satisfaction is not the contract; the bytes an import binds are. Sharing
+one copy with an aligned host install of the same version is an ordinary layout. A mixed
+tree (for example an override that binds pi-durable's `pi-ai` to an older published version) still
+*imports* — which is why the edge check exists — and is refused by name.
+
+- `entwurf setup` reports a `pi-durable` row from that check and writes no durable wiring:
+  **PASS** when it verifies, **FAIL** with the named refusal otherwise — never SKIP, because
+  nothing is optional to detect: a missing piece is an incomplete installation, repaired by
+  reinstalling Entwurf.
+- `entwurf pi-durable [args…]` is the managed launch. It verifies first (exit 3 on any
+  refusal), then runs the packaged bootstrap `pi/pi-durable/bootstrap.mjs` under the carrier
+  resolver, owning this terminal:
+
+  ```bash
+  entwurf pi-durable --provider <provider> --model <exact catalog id> --width task-wide
+  entwurf pi-durable --continue    # this directory's newest durable session
+  ```
+
+  The bootstrap imports only the compiled closure shipped beside it
+  (`mcp/entwurf-bridge/dist/…`); a source checkout needs a built bridge
+  (`pnpm run build-bridge`) and its development dependencies installed first.
+  `plugins/pi-durable/bootstrap.mjs` is only the checkout path that re-exports it.
+
+- **One explicit native module (optional).** Add `--native-module <absolute file>` to either
+  launch to load ONE module of your own. It is an ordinary ES module: its top-level code (top-level
+  await included) runs first, before the TUI and the durable runtime load, so it can prepare the
+  environment the provider runtime and tool children will read; its default export is a native
+  durable `Extension` (`{ name, tools?, sections?, hooks?, … }`, the upstream durable API, not
+  ordinary Pi's `ExtensionAPI`), installed after Entwurf's contact. An env-only module exports
+  just `{ name }`. Refused by name before anything opens: a relative or non-file path
+  (`native-module-path-*`), a module that throws (`native-module-import-failed`), a function or
+  nameless default (`native-module-export-invalid`), an extension named like one the app installs
+  itself (`entwurf`, `coding-tools`, `pi-prompt`, `subagent`) or a tool named like one of Entwurf's
+  contact tools (`native-module-name-reserved`; any other duplicate is the native registry's to
+  judge), and a module whose initialization changes
+  `PI_SESSION_ID`, `PI_CODING_AGENT_DIR`, `HOME` or any `ENTWURF_*` (`native-module-env-identity-changed`)
+  or the process directory (`native-module-cwd-changed`). Your module is trusted code; those
+  checks catch mistakes, they do not sandbox it. Nothing else names a module — no directory,
+  setting or profile — and a sibling opened by `entwurf_fresh_call` starts without one.
+
+- **Known warning.** Ordinary Pi may print `Host-provided extension packages must be declared in
+  peerDependencies with a "*" range, not dependencies: @earendil-works/…` for Entwurf's
+  `package.json`. Entwurf declares the exact pi SDK set as production dependencies on purpose:
+  the installed copies serve the separate pi-durable native process. Pi's check reads that
+  manifest field; it is a known constraint of supplying both from one package, accepted for 0.32,
+  not a claim that every load path is harmless.
+
+The ordinary Pi CLI on PATH is a separate subject (§2, range `>=1.1.0 <1.2`): a host Pi is
+not needed to run pi-durable, and a host inside the range need not be the same copy as the
+carrier's. Native Pi owns credentials, model settings and durable SQLite sessions; keep them
+in place rather than copying credentials or migrating ordinary Pi transcripts. Native
+recovery does not prove exactly-once Entwurf dispatch or inbox read recovery. The contact
+provides garden attachment, visible identity and announce-only root-directed self-fetch.
+Package gates prove the installed carrier's load, its physical edges and the public launch up
+to the app's own model resolution; the checkout contact/send/receive gates run the same carrier
+with scripted S plus native H; Pi ↔ pi-durable LIVE on this supply surface is a separate release
+proof ([#130](https://github.com/junghan0611/entwurf/issues/130)).
+
+### Maintainer: re-emitting the carrier
+
+Only a maintainer moving the pin runs `scripts/emit-pi-durable-carrier.ts`. It reads the
+pinned commit's objects (`<commit>:<path>`, `--no-replace-objects`) from a repository the
+maintainer names, applies the overlay patch with `git apply` in a private scratch tree,
+type-strips with Node's own strip-only TypeScript, relocates, and checks that the six files
+import exactly the pin's declared `distTargets`:
 
 ```bash
-case "${XDG_DATA_HOME:-}" in
-  /*) R="$XDG_DATA_HOME/entwurf/pi-durable/runtime" ;;
-  *)  R="$HOME/.local/share/entwurf/pi-durable/runtime" ;;
-esac
-git clone --no-checkout https://github.com/earendil-works/pi.git "$R"
-git -C "$R" checkout --detach cd32f7725fdbddbaecdff5b1e68491563394e0ca
-git -C "$R" apply "$ENTWURF_ROOT/pi/pi-durable/overlay/runtime-contacts.patch"  # worktree only; do not stage
-(cd "$R" && npm ci --ignore-scripts)    # upstream lockfile; dependency install scripts skipped
-T=$(mktemp -d)
-(cd "$T" && npm pack @earendil-works/pi-ai@1.0.2)
-tar -xzf "$T/earendil-works-pi-ai-1.0.2.tgz" -C "$T" package/dist/providers/data
-cp -a "$T/package/dist/providers/data/." "$R/packages/ai/src/providers/data/"   # dotfiles too
-entwurf setup                           # expect: pi-durable PASS
+node scripts/emit-pi-durable-carrier.ts --source <clone holding the pinned commit> --write
+node scripts/emit-pi-durable-carrier.ts --source <clone holding the pinned commit> --check  # rebuild equality
 ```
 
-Why it is a source checkout and not `npm install`: `@earendil-works/pi-coding-agent`
-(1.0.2 and 1.0.4 alike) excludes `dist/experimental` from its `files`, and its only
-experimental export resolves to `src/`, which the tarball does not ship, so the
-durable app's `experimental/durable/runtime.ts` and `tui.ts` exist only in a source
-checkout. `@earendil-works/pi-durable` on npm is the library (no app, TUI or bin).
-
-### What Entwurf does with it
-
-- `entwurf setup` reports a `pi-durable` row from that check and writes no durable
-  wiring in any case: **PASS** when the runtime is the pin, **SKIP** when nothing is
-  at the fixed place, **FAIL** with the named refusal when something is there but is
-  not the pin.
-- `entwurf pi-durable [args…]` is the managed launch. It verifies the same runtime
-  first (refusal exit 4 when absent, 3 otherwise), then runs the packaged bootstrap
-  `pi/pi-durable/bootstrap.mjs` under the runtime's source resolver, owning this
-  terminal. The bootstrap imports only the compiled closure shipped beside it
-  (`mcp/entwurf-bridge/dist/…`), so an installed package never imports checkout
-  TypeScript; a source checkout needs a built bridge (`pnpm run build-bridge`) first.
-  `plugins/pi-durable/bootstrap.mjs` is only the checkout path that re-exports it.
-
-Existing users who do not enable durable keep the same installation steps. For
-durable, native Pi owns credentials, model settings, SQLite sessions and recovery;
-keep them in place rather than copying credentials or migrating ordinary Pi
-transcripts. Native recovery does not prove exactly-once Entwurf dispatch or inbox
-read recovery. The contact provides garden attachment, visible identity and
-announce-only root-directed self-fetch. First native admission closed
-[#129](https://github.com/junghan0611/entwurf/issues/129) at reviewed main:
-visible fresh/callback, addressed receive and both real Pi ↔ pi-durable LIVE legs
-passed on one Linux host. Installed-bootstrap import-only proof is not a native
-runtime/TUI launch or a live Claude ↔ pi-durable receipt. This section states the
-installation contract; exact release/artifact acceptance is a separate floor.
-[#130](https://github.com/junghan0611/entwurf/issues/130) owns npm-only runtime
-supply, later Pi versions, ACP and UI follow-ups.
+`--check` without such a repository is a named SKIP, never rebuild acceptance; the emitter
+version (Node) is part of the pin.
 
 ## 3. Optional Claude Code native citizen
 
@@ -545,7 +562,7 @@ as a note rather than a fault.
 
 **entwurf sets no OMP version floor in code, and will not grow one on schedule.** Detection is
 presence-only (`command -v "${OMP_BIN:-omp}"`); there is no `entwurf.ompFloor`, no coherence
-gate, and no exact pin — unlike Node (`engines.node`), pi (`>=1.0.2 <1.1`) and Claude Code
+gate, and no exact pin — unlike Node (`engines.node`), pi (`>=1.1.0 <1.2`) and Claude Code
 (`entwurf.claudeCodeFloor`), each of which has an enforcement point. That asymmetry is a
 decision, not an omission. A floor is the answer to a vendor that fails SILENTLY — Claude Code
 earned one because an older binary validates the exec manifest, drops `args` at runtime, and

package/mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js

@@ -640,7 +640,7 @@ server.tool("entwurf_fresh_call", "Open ONE fresh visible sibling beside you and
     "a running sibling. Nothing polls. " +
     "For EXISTING citizens use entwurf_v2 — this tool only creates, and entwurf_peers only reports. Model is REQUIRED and passed to the chosen " +
     "runtime CLI (`provider/model` for pi, an id/alias for Claude Code, `provider/model id` exactly as the catalog names it for pi-durable, a pattern for the rest). On tmux, copilot/omp/codex/pi-durable are refused BEFORE any window " +
-    "opens when their birth, MCP, receive or visible-identity units are absent, pi-durable also when its operator-provided pinned runtime is absent or drifted, and codex also needs the " +
+    "opens when their birth, MCP, receive or visible-identity units are absent, pi-durable also on named refusals of its installed carrier or exact SDK set, and codex also needs the " +
     "operator-owned app-server socket entwurf never starts; in herdr they are refused by name first. " +
     "Optional placement.tmuxSession is a TMUX-ONLY seat naming ONE EXISTING session and " +
     "ALWAYS wins; omitted, the seat follows the CALLER, never the backend opened: a CODEX CALLER opens beside " +

package/mcp/entwurf-bridge/dist/pi-extensions/lib/fresh-call-composition.js

@@ -25,7 +25,7 @@ import { randomBytes } from "node:crypto";
 /** The backends this rail can open. Fixed set, not a profile — a further one is a decision,
  * not a config entry. `copilot` was added by #82 RAIL 9, `omp` by #87 Bundle C, `codex`
  * by #95 after its system birth and app-server rails were measured, and `pi-durable` by #129
- * (the operator-provided durable app through the managed `entwurf pi-durable`). The set is joined to the
+ * (the durable app this package carries, through the managed `entwurf pi-durable`). The set is joined to the
  * citizen backends by `check-harness-admission-parity`: a harness that mints records but is
  * missing HERE is not an unwired convenience, it is a release blocker. */
 export const FRESH_CALL_BACKENDS = ["pi", "claude-code", "copilot", "omp", "codex", "pi-durable"];

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-fresh-call.js

@@ -156,9 +156,9 @@ export const FRESH_CALL_RUNTIME = {
     copilot: "entwurf",
     omp: "omp",
     codex: "codex",
-    // #129: like copilot, a MANAGED verb and never the bare app. The durable app is source-only
-    // and runs under the operator-provided runtime's own resolver; `entwurf pi-durable` is the one
-    // fixed invocation that verifies that runtime against the pin and execs the packaged bootstrap.
+    // #129/#130: like copilot, a MANAGED verb and never the bare app. The durable app is this
+    // package's carrier and runs under the carrier's resolver; `entwurf pi-durable` is the one fixed
+    // invocation that verifies the carrier and its SDK set and execs the packaged bootstrap.
     "pi-durable": "entwurf",
 };
 /**
@@ -345,15 +345,13 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
     }
     if (params.backend === "pi-durable") {
         // The framed first input is computed here only to MEASURE it against the bootstrap payload
-        // cap; the same pure function composes it again below. The runtime is located and verified
-        // with THIS process's env, before anything is placed. That is the bridge's env, not
-        // necessarily the window's: a new-window pane inherits the tmux SERVER's environment
-        // (measured, see SCRUBBED_INHERITED_ENV), and the window runs whatever `entwurf` PATH names.
-        // The managed verb re-verifies with its own env before it execs anything, so the window never
-        // runs an unverified runtime — but when HOME/XDG_DATA_HOME or the package closure differ, this
+        // cap; the same pure function composes it again below. The carrier is verified from THIS
+        // process's package closure, before anything is placed. The window runs whatever `entwurf`
+        // PATH names, and the managed verb re-verifies its own package before it execs anything, so
+        // the window never runs an unverified carrier — but when the two package closures differ, this
         // verdict and the window's can disagree, and the window is left showing its own refusal.
         const layout = piDurablePackageLayout();
-        const runtime = layout === null ? null : checkPiDurableRuntime(env, layout);
+        const runtime = layout === null ? null : checkPiDurableRuntime(layout);
         const missing = piDurableFreshPreflight({
             model,
             firstInput: buildFreshCallPrompt({ backend: params.backend, task, callerGardenId, nonce }),

package/mcp/entwurf-bridge/dist/pi-extensions/lib/pi-durable-fresh-preflight.js

@@ -19,9 +19,9 @@
  *                 `{v:2,task}` payload, whose decoder caps `task` at 16000 characters. A framed
  *                 task over that cap would open a window whose bootstrap refuses its own argv.
  *
- * ── Then the runtime, then the four units ──
+ * ── Then the carrier, then the four units ──
  *
- *   runtime          operator-provided at the fixed locator and verified against the pin
+ *   carrier          the package's own pi-durable carrier and its declared SDK set, verified
  *                    (`pi-durable-runtime.ts`); passed in as that check's verdict.
  *   birth            the compiled contact in this package's closure — it mints the record.
  *   MCP hand         the compiled entwurf-bridge entry in the same closure — the contact spawns it.
@@ -32,7 +32,7 @@
  *
  * ── What this deliberately does NOT claim ──
  *
- * Filesystem truth about ONE package closure and ONE runtime directory. It does not prove the durable
+ * Filesystem truth about ONE package closure and the SDK it resolves. It does not prove the durable
  * app opens, the bridge connects, the doorbell arms or a garden id renders — that is runtime truth for
  * the clause 7 LIVE receipt. No spawn, no network, no mutation; every path arrives as an argument, so
  * this leaf imports nothing but types.