@junghanacs/entwurf 0.30.1 → 0.32.0

package/mcp/entwurf-bridge/src/index.ts

@@ -752,8 +752,8 @@ server.tool(
 	"Open ONE fresh visible sibling beside you and hand it a first task. WHERE it opens is decided by where THIS " +
 		"agent runs, never by a parameter: inside herdr (HERDR_ENV=1) it opens a NEW UNFOCUSED TAB in your own " +
 		"herdr workspace, pi and claude-code " +
-		"only; everywhere else it opens in the operator's tmux with all five backends (pi, " +
-		"claude-code, copilot, omp, codex). No fallback: an incomplete herdr context is refused by name, " +
+		"only; everywhere else it opens in the operator's tmux with all six backends (pi, " +
+		"claude-code, copilot, omp, codex, pi-durable). No fallback: an incomplete herdr context is refused by name, " +
 		"never by a tmux window you cannot see from herdr. The sibling's FIRST action " +
 		"is a callback to you carrying a nonce, whose sender envelope is its garden id — that is how you learn the " +
 		"address of a thing that did not exist a moment ago. This returns a LAUNCH receipt (the owner's " +
@@ -761,8 +761,8 @@ server.tool(
 		"the task was delivered. Those coordinates are a VIEW, never an address — a herdr tab/pane id can change under " +
 		"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, a pattern for the rest). On tmux, copilot/omp/codex are refused BEFORE any window " +
-		"opens when their birth, MCP, receive or visible-identity units are absent, and codex also needs the " +
+		"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 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 " +
@@ -771,9 +771,9 @@ server.tool(
 		"processes.",
 	{
 		backend: z
-			.enum(["pi", "claude-code", "copilot", "omp", "codex"])
+			.enum(["pi", "claude-code", "copilot", "omp", "codex", "pi-durable"])
 			.describe(
-				"Which fixed runtime to open. Only these five, and only pi/claude-code when this agent runs inside herdr; there is no arbitrary command.",
+				"Which fixed runtime to open. Only these six, and only pi/claude-code when this agent runs inside herdr; there is no arbitrary command.",
 			),
 		model: z
 			.string()
@@ -789,7 +789,7 @@ server.tool(
 			// biome-ignore lint/complexity/noUselessEscapeInRegex: emitted to a Rust regex validator, see above
 			.regex(/^[A-Za-z0-9][A-Za-z0-9._/:\[\]-]*$/)
 			.describe(
-				"Required runtime model: canonical provider/model for pi, a Claude Code model id/alias, or a Copilot/OMP/Codex model name.",
+				"Required runtime model: canonical provider/model for pi, provider/<exact catalog model id> for pi-durable, a Claude Code model id/alias, or a Copilot/OMP/Codex model name.",
 			),
 		task: z
 			.string()

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

@@ -122,6 +122,12 @@
 	// twin would make the one-command launch die before its first line. Its only repo import is
 	// native-push/codex-ws-client.ts, ALREADY emitted for meta-bridge-hook-codex, so this adds ONE
 	// leaf JS and ZERO new deps.
+	// WHY meta-bridge-pi-durable rides THIS build (#129 W, L4): the packaged durable bootstrap
+	// (pi/pi-durable/bootstrap.mjs) imports the contact from THIS closure — the same closure whose
+	// bridge entry the contact spawns and whose meta-bridge-omp.js decodes the first-input payload —
+	// so an installed Entwurf never imports checkout TypeScript. Its only repo import is
+	// meta-session, ALREADY emitted for the bridge; it is never in index.ts's boot closure. The runtime locator/verifier and the fresh preflight arrive
+	// through the import graph (mux-fresh-call) and need no entry here.
 	// WHY meta-bridge-omp rides THIS build (#87): `install-omp-bridge` explicitly SELECTS
 	// `dist/pi-extensions/meta-bridge-omp.js` when REPO_DIR is under node_modules — the same
 	// strip-types fence the Claude and Copilot birth entries cross — and
@@ -149,6 +155,7 @@
 		"../../pi-extensions/meta-bridge-hook-copilot.ts",
 		"../../pi-extensions/meta-bridge-hook-codex.ts",
 		"../../pi-extensions/meta-bridge-omp.ts",
-		"../../pi-extensions/meta-bridge-receive-omp.ts"
+		"../../pi-extensions/meta-bridge-receive-omp.ts",
+		"../../pi-extensions/meta-bridge-pi-durable.ts"
 	]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.30.1",
+	"version": "0.32.0",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for pi, Claude Code, Copilot CLI, OMP, Antigravity, and Codex CLI; Claude and Snowflake Cortex Code ACP backends.",
 	"license": "MIT",
 	"author": {
@@ -52,6 +52,12 @@
 		"docs/assets/entwurf-entwurf.gif",
 		"pi/entwurf-capabilities.json",
 		"pi/settings.reference.json",
+		"pi/pi-durable/bootstrap.mjs",
+		"pi/pi-durable/carrier-relocation.mjs",
+		"pi/pi-durable/carrier-resolver.mjs",
+		"pi/pi-durable/carrier/",
+		"pi/pi-durable/overlay/upstream-pin.json",
+		"pi/pi-durable/overlay/runtime-contacts.patch",
 		"pi/meta-bridge/.claude-plugin/marketplace.json",
 		"pi/meta-bridge/entwurf-meta-receive/.claude-plugin/plugin.json",
 		"pi/meta-bridge/entwurf-meta-receive/hooks/hooks.json",
@@ -87,22 +93,25 @@
 		"@agentclientprotocol/claude-agent-acp": "0.85.1",
 		"@agentclientprotocol/sdk": "1.6.0",
 		"@anthropic-ai/sdk": "0.100.1",
+		"@earendil-works/chord": "1.0.4",
+		"@earendil-works/pi-agent-core": "1.0.4",
+		"@earendil-works/pi-ai": "1.0.4",
+		"@earendil-works/pi-codemode": "1.0.4",
+		"@earendil-works/pi-coding-agent": "1.0.4",
+		"@earendil-works/pi-durable": "1.0.4",
+		"@earendil-works/pi-mcp": "1.0.4",
+		"@earendil-works/pi-telemetry": "1.0.4",
+		"@earendil-works/pi-tui": "1.0.4",
 		"@modelcontextprotocol/sdk": "^1.12.1",
+		"proper-lockfile": "4.1.2",
 		"smol-toml": "^1.8.0",
 		"zod": "^3.25.0 || ^4.0.0"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-ai": ">=1.0.0 <1.1",
-		"@earendil-works/pi-coding-agent": ">=1.0.0 <1.1",
-		"@earendil-works/pi-tui": ">=1.0.0 <1.1",
 		"typebox": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.13",
-		"@earendil-works/pi-agent-core": "1.0.0",
-		"@earendil-works/pi-ai": "1.0.0",
-		"@earendil-works/pi-coding-agent": "1.0.0",
-		"@earendil-works/pi-tui": "1.0.0",
 		"@types/node": "^24.3.0",
 		"husky": "^9.1.7",
 		"rregex": "1.13.1",
@@ -113,7 +122,7 @@
 		"prepare": "husky 1>&2 || true; npm run --silent build-bridge 1>&2",
 		"postinstall": "node scripts/postinstall-chmod.cjs",
 		"build-bridge": "bash scripts/with-dist-lock.sh bash scripts/build-bridge.sh",
-		"prepack": "pnpm --silent run build-bridge",
+		"prepack": "pnpm run build-bridge 1>&2",
 		"prepublishOnly": "pnpm run check:full && pnpm run check-pack-install",
 		"setup": "./run.sh setup",
 		"check-shell-quote": "./run.sh check-shell-quote",
@@ -177,7 +186,7 @@
 		"check:core": "pnpm run check:toolchain && pnpm run check:vitest && pnpm run check:contracts",
 		"check:toolchain": "pnpm lint && pnpm typecheck",
 		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface && ./run.sh check-pi-queue-oracle && ./run.sh check-tests-beside-behavior",
-		"check:contracts": "./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-runner && ./run.sh check-control-send-receipt && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-control-socket-path && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-herdr-placement && ./run.sh check-herdr-fresh-call && ./run.sh check-herdr-supply && ./run.sh check-fresh-call-dispatch && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-acp-foreground-only && ./run.sh check-acp-vendor-rejection && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push",
+		"check:contracts": "./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-runner && ./run.sh check-control-send-receipt && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-control-socket-path && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-herdr-placement && ./run.sh check-herdr-fresh-call && ./run.sh check-herdr-supply && ./run.sh check-fresh-call-dispatch && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-acp-foreground-only && ./run.sh check-acp-vendor-rejection && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push && ./run.sh check-pi-durable-beside",
 		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-meta-hook-session-switch && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-pi-launch && ./run.sh check-codex-app-server-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-birth-hook && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-peer-facts && ./run.sh check-herdr-plugin && ./run.sh check-herdr-plugin-profile && ./run.sh check-herdr-plugin-build && ./run.sh check-herdr-runtime-bootstrap && ./run.sh check-herdr-activation && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-usage-accounting && ./run.sh check-acp-launch-namespace && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-typing-call-fence && ./run.sh check-gate-manifests && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex && ./run.sh check-codex-bridge-identity && ./run.sh check-pi-bridge-sender && ./run.sh check-pi-mcp-register && ./run.sh check-pi-mcp-bridge && ./run.sh check-codex-birth-hook && ./run.sh smoke-codex-config-state && ./run.sh smoke-codex-birth && ./run.sh check-herdr-sandbox",
 		"check:package": "./run.sh check-install-surface && ./run.sh smoke-meta-install-state && ./run.sh smoke-agy-install-state && ./run.sh smoke-setup-verdict && ./run.sh check-pack-pin-matcher && ./run.sh check-pack-consumer-roots && ./run.sh check-package-source-routing && ./run.sh check-install-preflight && ./run.sh check-pack"
 	},
@@ -198,15 +207,6 @@
 		"entwurf-copilot-statusline": "./scripts/copilot-statusline.sh"
 	},
 	"peerDependenciesMeta": {
-		"@earendil-works/pi-ai": {
-			"optional": true
-		},
-		"@earendil-works/pi-coding-agent": {
-			"optional": true
-		},
-		"@earendil-works/pi-tui": {
-			"optional": true
-		},
 		"typebox": {
 			"optional": true
 		}

package/pi/entwurf-capabilities.json

@@ -6,6 +6,7 @@
 		"codex": { "wakeMode": "direct-inject", "deliveryLevel": "D6", "nativeIdLabel": "threadId" },
 		"copilot": { "wakeMode": "self-fetch", "deliveryLevel": "D6", "nativeIdLabel": "sessionId" },
 		"omp": { "wakeMode": "self-fetch", "deliveryLevel": "D6", "nativeIdLabel": "sessionId" },
+		"pi-durable": { "wakeMode": "self-fetch", "deliveryLevel": "D2", "nativeIdLabel": "sessionId" },
 		"pi": { "wakeMode": "direct-inject", "deliveryLevel": "D6", "nativeIdLabel": "sessionId" }
 	}
 }

package/pi/pi-durable/bootstrap.mjs

@@ -0,0 +1,404 @@
+#!/usr/bin/env node
+// Durable host bootstrap for Entwurf's pi-durable contact (#129). PACKAGED: this file ships in the
+// package `files`, and every Entwurf module it imports is the COMPILED closure that ships beside it
+// (`mcp/entwurf-bridge/dist/…`) — an installed package never imports checkout TypeScript. The bridge
+// the contact spawns is derived from that same closure, never from argv. A checkout runs it the same
+// way, after `pnpm run build-bridge`; `plugins/pi-durable/bootstrap.mjs` re-exports this file.
+//
+// The same shape as upstream `experimental/durable/main.ts` (parse, open, run the TUI, close),
+// with these differences:
+// - Entwurf's tools-only extension is handed to `openDurable`;
+// - a NEW session is opened with an explicit model and an explicit width, never a default (below);
+// - the citizen is born once `openDurable` returns, with the overlay's `submitToRoot` so its
+//   doorbell can announce mail to the root conversation;
+// - a launcher's first input, when given, is admitted to the root ONCE, after that birth;
+// - the TUI is handed the native view with the garden id on every conversation label
+//   (`withGardenIdentity`).
+// Nothing of the native registry, controller or TUI is rebuilt here.
+//
+// The durable app itself is this package's CARRIER (./carrier/, the pinned upstream files emitted by
+// the maintainer — upstream publishes no experimental app), and it runs under the carrier's resolver,
+// which maps the app's pi-coding-agent internals to the published package the carrier resolves.
+// `entwurf pi-durable` (run.sh) verifies the carrier and its SDK set (pi-durable-runtime.ts) and
+// execs:
+//
+//   node --import <entwurf>/pi/pi-durable/carrier-resolver.mjs \
+//        <entwurf>/pi/pi-durable/bootstrap.mjs \
+//        --provider <provider> --model <model id> --width task-wide [--entwurf-bootstrap <json>]
+//   ... bootstrap.mjs --continue
+//
+// Explicit means the native API, not a vendor argv: upstream's durable main takes only
+// `--continue`, so `--provider`/`--model` reach pi's own `findInitialAgentModel` through the
+// overlay's `model` option, for a new session only, and an unresolvable pair fails the open
+// before any citizen is born (the native session directory may already exist by then). The model
+// must be one registered catalog model of that provider, named by its canonical id or by
+// `id:<level>` as pi's own parser reads a thinking level: a typo, a partial or case-variant match, a
+// provider-prefixed id or an unregistered custom-id fallback is refused by the overlay as
+// `explicit-model-not-exact`, before the birth and the first input.
+// `--width task-wide` is the one width: no tool filter, so the model is offered exactly the tools
+// the installed extensions register. It is a statement of what is OFFERED, not an approval or
+// sandbox policy; the native app has no approval prompt, so a narrower width would be a sibling
+// that can never reach its task's tools, and none is offered.
+// `--entwurf-bootstrap` is the existing fixed `{v,task}` payload grammar (meta-bridge-omp.ts,
+// read-only reuse): unknown keys — a target or a nonce included — are refused; the caller's
+// address rides the process env only.
+// `--continue` opens the newest session for this directory as upstream does (not a chosen
+// record), so every flag that only a new session can honour is refused beside it by name.
+//
+// `--native-module <absolute file>` (#130 P2) names ONE operator module, for a new or a continued
+// session. It is an ordinary ES module: its own top-level evaluation (top-level await included) is
+// its initialization, and its default export is a native durable Extension, handed to `openDurable`
+// by reference after the contact. Initialization runs before the TUI or the runtime is imported —
+// the runtime creates the provider runtime before it installs any extension (carrier/runtime.js
+// 140-146), so an extension object cannot carry an environment phase. Entwurf checks only what the
+// ingress needs: a default export object with a name, no extension name the app installs itself (a
+// same-name install REPLACES), and no tool name of the contact. Every other field is the native
+// registry's to validate. The module is trusted operator code: the identity carriers and the
+// process directory are compared across its initialization and a change is refused by name — a
+// mistake guard, not a sandbox, and nothing is rolled back. Nothing is discovered: no directory,
+// setting, environment variable or profile names a module.
+//
+// Without that resolver the carrier's first pi-coding-agent internal import fails by name (an
+// unsupported entwurf-pi-dist: URL scheme), and that failure is the honest one.
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { decodeOmpBootstrapPayload } from "../../mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-omp.js";
+import {
+	closeAll,
+	createPiDurableContact,
+	failAfterCleanup,
+	PI_DURABLE_EXTENSION_NAME,
+	PI_DURABLE_TOOL_NAMES,
+	withGardenIdentity,
+} from "../../mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-pi-durable.js";
+
+const RUNTIME = "./carrier/runtime.js";
+const TUI = "./carrier/tui.js";
+
+/** The entwurf-bridge of THIS package closure: the one the contact spawns as its MCP hand. */
+export const PACKAGED_BRIDGE_ENTRY = fileURLToPath(
+	new URL("../../mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js", import.meta.url),
+);
+
+/** Flags that take a value. Anything else but `--continue`/`-c` is an unknown argument — a bridge
+ * entry included: the launch argv cannot point the contact at another bridge. */
+const VALUE_FLAGS = ["--provider", "--model", "--width", "--entwurf-bootstrap", "--native-module"];
+/** Flags only a NEW session can honour. */
+const FRESH_ONLY_FLAGS = ["--provider", "--model", "--width", "--entwurf-bootstrap"];
+
+/**
+ * Extension names the durable app installs itself — the contact, then the carrier's own
+ * (`coding-tools` pi-durable/tools, `pi-prompt` carrier/prompt.js:70, `subagent`
+ * carrier/subagent.js:25). The native registry REPLACES an installed extension of the same name.
+ */
+const RESERVED_EXTENSION_NAMES = [PI_DURABLE_EXTENSION_NAME, "coding-tools", "pi-prompt", "subagent"];
+/** The identity carriers a module's initialization must leave as it found them, every ENTWURF_* included. */
+const IDENTITY_KEYS = ["PI_SESSION_ID", "PI_CODING_AGENT_DIR", "HOME"];
+
+/** A refusal with a stable name first, so a launcher and an operator can tell the repairs apart. */
+function refuse(reason, detail) {
+	return Object.assign(new Error(`${reason}: ${detail}`), { reason });
+}
+
+const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
+
+/** The identity carriers present now: names and values, compared in memory and never printed. */
+function identitySnapshot() {
+	return Object.fromEntries(
+		Object.entries(process.env).filter(([key]) => IDENTITY_KEYS.includes(key) || key.startsWith("ENTWURF_")),
+	);
+}
+
+/** Keys changed, added or removed between two snapshots, sorted. */
+function identityChanges(before, after) {
+	return [...new Set([...Object.keys(before), ...Object.keys(after)])]
+		.filter((key) => before[key] !== after[key])
+		.sort();
+}
+
+/** The operator's module path: absolute, resolving to a regular file. Decided before anything loads. */
+function nativeModuleFile(value) {
+	if (!isAbsolute(value))
+		throw refuse("native-module-path-not-absolute", `--native-module takes an absolute path, got ${value}`);
+	let file;
+	try {
+		file = realpathSync(value);
+	} catch (error) {
+		throw Object.assign(refuse("native-module-path-invalid", `${value} does not resolve`), { cause: error });
+	}
+	if (!statSync(file).isFile()) throw refuse("native-module-path-invalid", `${value} is not a regular file`);
+	return file;
+}
+
+/** The module's default export, checked only for what the ingress needs and returned BY REFERENCE. */
+function nativeExtensionOf(extension, file) {
+	if (typeof extension === "function") {
+		throw refuse(
+			"native-module-export-invalid",
+			`${file} exports a function by default — a classic ExtensionAPI factory is not a native durable extension; export the Extension object ({ name, tools?, … })`,
+		);
+	}
+	if (typeof extension !== "object" || extension === null || Array.isArray(extension)) {
+		throw refuse("native-module-export-invalid", `${file} has no default export object`);
+	}
+	if (!nonEmpty(extension.name)) throw refuse("native-module-export-invalid", `${file}'s default export has no name`);
+	if (RESERVED_EXTENSION_NAMES.includes(extension.name)) {
+		throw refuse(
+			"native-module-name-reserved",
+			`${file} names its extension ${extension.name}, which the durable app installs itself; the same name would replace it`,
+		);
+	}
+	const taken = (Array.isArray(extension.tools) ? extension.tools : [])
+		.map((tool) => tool?.name)
+		.filter((name) => PI_DURABLE_TOOL_NAMES.includes(name));
+	if (taken.length > 0) {
+		throw refuse("native-module-name-reserved", `${file} registers ${taken.join(", ")}, the contact's own tool name`);
+	}
+	return extension;
+}
+
+/**
+ * Initialize the operator's module and return its native Extension. The identity carriers and the
+ * process directory are read BEFORE its first line runs and compared once its evaluation completes.
+ */
+async function loadNativeModule(file) {
+	const before = identitySnapshot();
+	const cwd = process.cwd();
+	let namespace;
+	try {
+		namespace = await import(pathToFileURL(file).href);
+	} catch (error) {
+		throw Object.assign(
+			refuse("native-module-import-failed", `${file}: ${error instanceof Error ? error.message : String(error)}`),
+			{ cause: error },
+		);
+	}
+	const changed = identityChanges(before, identitySnapshot());
+	if (changed.length > 0) {
+		throw refuse(
+			"native-module-env-identity-changed",
+			`initializing ${file} changed ${changed.join(", ")}; a module sets its own environment, never an identity carrier`,
+		);
+	}
+	if (process.cwd() !== cwd) {
+		throw refuse("native-module-cwd-changed", `initializing ${file} moved the process out of ${cwd}`);
+	}
+	return nativeExtensionOf(namespace.default, file);
+}
+
+/**
+ * Open the durable app with the contact installed, then birth the citizen and arm its doorbell on
+ * the root conversation, then admit the first input (when given) to the root once. On any failure
+ * the contact is told why (waiting tools reject by name), everything opened is closed again, and a
+ * cleanup failure is reported beside the cause instead of replacing it.
+ *
+ * `model` and `firstInput` apply to a new session only; with `continueSession` they are refused
+ * before anything opens. `contact` carries extra `createPiDurableContact` options (explicit garden
+ * roots; tests also pass a connector). `open` replaces the runtime's `openDurable` for tests.
+ * `bridgeEntry` defaults to this package's own compiled bridge; only a programmatic caller (the
+ * checkout-only gates, which drive a private bundle) passes another one — never the launch argv.
+ * `extensions` are the operator's native extensions (`--native-module`), installed after the
+ * contact, by reference.
+ *
+ * @param {{
+ *   bridgeEntry?: string,
+ *   continueSession?: boolean,
+ *   cwd?: string,
+ *   model?: { provider: string, model: string },
+ *   firstInput?: string,
+ *   extensions?: readonly object[],
+ *   contact?: Record<string, unknown>,
+ *   open?: (options: { cwd: string, continueSession: boolean, extensions: readonly object[], model?: { provider: string, model: string } }) => Promise<any>,
+ * }} options
+ * @returns {Promise<{ durable: any, contact: any, attachment: { gardenId: string } & Record<string, any>, firstInput?: any, close(): Promise<void> }>}
+ *   (stated, because the compiled closure carries no declarations: a cleanup path that rethrows
+ *   through `failAfterCleanup` never resolves)
+ */
+export async function openDurableCitizen({
+	bridgeEntry = PACKAGED_BRIDGE_ENTRY,
+	continueSession = false,
+	cwd = process.cwd(),
+	model,
+	firstInput,
+	extensions = [],
+	contact: contactOptions = {},
+	open,
+}) {
+	if (continueSession && (model !== undefined || firstInput !== undefined)) {
+		throw refuse(
+			"fresh-only-argument-with-continue",
+			"an explicit model and a first input apply only to a new session; a continued session is reopened as it was saved",
+		);
+	}
+	if (model !== undefined && !(nonEmpty(model.provider) && nonEmpty(model.model))) {
+		throw refuse("explicit-model-incomplete", "an explicit model names both its provider and its model id");
+	}
+	if (firstInput !== undefined && !nonEmpty(firstInput)) {
+		throw refuse("first-input-empty", "a first input is a non-empty task");
+	}
+	const openDurable = open ?? (await import(RUNTIME)).openDurable;
+	const contact = createPiDurableContact({ ...contactOptions, bridgeEntry });
+	let durable;
+	try {
+		durable = await openDurable({
+			cwd,
+			continueSession,
+			extensions: [contact.extension, ...extensions],
+			...(model === undefined ? {} : { model }),
+		});
+	} catch (error) {
+		contact.fail(error);
+		throw error;
+	}
+	let attachment;
+	try {
+		attachment = await contact.attach(durable.view.current().session, { submitToRoot: durable.submitToRoot });
+	} catch (error) {
+		return failAfterCleanup(
+			error,
+			() => contact.close(),
+			() => durable.close(),
+		);
+	}
+	// After the birth, so a callback the input asks for finds a citizen. Admission, not the answer:
+	// the turn runs under the TUI. A refused admission is the cause, never a notice.
+	let first;
+	if (firstInput !== undefined) {
+		try {
+			first = await durable.submitToRoot({
+				type: "input",
+				content: firstInput,
+				requestId: `entwurf-first-input:${attachment.gardenId}`,
+			});
+		} catch (error) {
+			return failAfterCleanup(
+				error,
+				() => contact.close(),
+				() => durable.close(),
+			);
+		}
+	}
+	let closing;
+	return {
+		durable,
+		contact,
+		attachment,
+		...(first === undefined ? {} : { firstInput: first }),
+		close() {
+			closing ??= closeAll(
+				() => contact.close(),
+				() => durable.close(),
+			);
+			return closing;
+		},
+	};
+}
+
+function parseArgs(argv) {
+	let continueSession = false;
+	const values = new Map();
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--continue" || arg === "-c") {
+			continueSession = true;
+			continue;
+		}
+		if (!VALUE_FLAGS.includes(arg)) throw new Error(`Unknown argument: ${arg}`);
+		if (values.has(arg)) throw refuse("argument-repeated", `${arg} is given more than once`);
+		const value = argv[++i];
+		if (value === undefined || value === "" || value.startsWith("-")) {
+			throw refuse("argument-value-missing", `${arg} needs a value`);
+		}
+		values.set(arg, value);
+	}
+	const fresh = FRESH_ONLY_FLAGS.filter((flag) => values.has(flag));
+	if (continueSession && fresh.length > 0) {
+		throw refuse(
+			"fresh-only-argument-with-continue",
+			`${fresh.join(", ")} apply only to a new session; --continue reopens this directory's newest session as it was saved`,
+		);
+	}
+	const moduleArg = values.get("--native-module");
+	const nativeModule = moduleArg === undefined ? {} : { nativeModule: nativeModuleFile(moduleArg) };
+	if (continueSession) return { continueSession, ...nativeModule };
+	const provider = values.get("--provider");
+	if (provider === undefined) {
+		throw refuse(
+			"explicit-provider-required",
+			"a new session names its provider with --provider; a model is never resolved to a provider by inference",
+		);
+	}
+	const model = values.get("--model");
+	if (model === undefined) throw refuse("explicit-model-required", "a new session names its model with --model");
+	const width = values.get("--width");
+	if (width !== "task-wide") {
+		throw refuse(
+			width === undefined ? "width-required" : "width-unsupported",
+			"a new session is opened with --width task-wide: every tool the installed extensions register is offered",
+		);
+	}
+	const payload = values.get("--entwurf-bootstrap");
+	let firstInput;
+	if (payload !== undefined) {
+		const decoded = decodeOmpBootstrapPayload(payload);
+		if (!decoded.ok) throw refuse("bootstrap-payload-rejected", decoded.reason);
+		firstInput = decoded.value.task;
+	}
+	return {
+		continueSession,
+		model: { provider, model },
+		...(firstInput === undefined ? {} : { firstInput }),
+		...nativeModule,
+	};
+}
+
+/**
+ * Parse, initialize the operator's module, load the TUI, open, run, close. `loadTui`, `open` and
+ * `contact` are test seams; `bridgeEntry` is the checkout-only gates' private bundle, as in
+ * `openDurableCitizen` — never the launch argv.
+ *
+ * @param {readonly string[]} argv
+ * @param {{
+ *   loadTui?: () => Promise<{ runDurableTui: (...args: any[]) => Promise<void> }>,
+ *   open?: (options: any) => Promise<any>,
+ *   contact?: Record<string, unknown>,
+ *   bridgeEntry?: string,
+ * }} [seams]
+ */
+export async function main(argv, { loadTui = () => import(TUI), open, contact, bridgeEntry } = {}) {
+	// Every argument refusal is decided here, before any module, the TUI or the app loads.
+	const { nativeModule, ...args } = parseArgs(argv);
+	// The caller's directory, fixed before any operator code runs and handed to the app explicitly.
+	const cwd = process.cwd();
+	const extensions = nativeModule === undefined ? [] : [await loadNativeModule(nativeModule)];
+	// Loaded before anything opens, as upstream main.ts imports it statically: a TUI that cannot
+	// load opens no session, mints no citizen and leaves nothing to clean up.
+	const { runDurableTui } = await loadTui();
+	const citizen = await openDurableCitizen({ ...args, cwd, extensions, bridgeEntry, open, contact });
+	try {
+		await runDurableTui(
+			withGardenIdentity(citizen.durable.view, citizen.attachment.gardenId),
+			citizen.durable.controller,
+			citizen.durable.settings,
+		);
+	} catch (error) {
+		return failAfterCleanup(error, () => citizen.close());
+	}
+	await citizen.close();
+}
+
+// Run only when THIS file is the process entry (`node --import <resolver> bootstrap.mjs …`), decided
+// by an argv realpath as in meta-bridge-hook-codex.ts — not by the `main` flag on import.meta, which
+// Node gained in 24.2.0, above the package's major-24 floor. Importing this file starts nothing.
+const invokedDirectly = (() => {
+	const entry = process.argv[1];
+	if (typeof entry !== "string" || entry.length === 0) return false;
+	try {
+		return realpathSync(entry) === realpathSync(import.meta.filename);
+	} catch {
+		// Bounded environment probe: an entry that cannot be resolved is not this file.
+		return false;
+	}
+})();
+if (invokedDirectly) await main(process.argv.slice(2));

package/pi/pi-durable/carrier/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.