@junghanacs/entwurf 0.30.0 → 0.31.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 when its operator-provided pinned runtime is absent or drifted, 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.0",
+	"version": "0.31.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,9 @@
 		"docs/assets/entwurf-entwurf.gif",
 		"pi/entwurf-capabilities.json",
 		"pi/settings.reference.json",
+		"pi/pi-durable/bootstrap.mjs",
+		"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",
@@ -84,25 +87,25 @@
 		"claudeCodeFloor": ">=2.1.217"
 	},
 	"dependencies": {
-		"@agentclientprotocol/claude-agent-acp": "0.79.0",
-		"@agentclientprotocol/sdk": "1.4.0",
+		"@agentclientprotocol/claude-agent-acp": "0.85.1",
+		"@agentclientprotocol/sdk": "1.6.0",
 		"@anthropic-ai/sdk": "0.100.1",
 		"@modelcontextprotocol/sdk": "^1.12.1",
 		"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",
+		"@earendil-works/pi-ai": ">=1.0.2 <1.1",
+		"@earendil-works/pi-coding-agent": ">=1.0.2 <1.1",
+		"@earendil-works/pi-tui": ">=1.0.2 <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",
+		"@earendil-works/pi-agent-core": "1.0.2",
+		"@earendil-works/pi-ai": "1.0.2",
+		"@earendil-works/pi-coding-agent": "1.0.2",
+		"@earendil-works/pi-tui": "1.0.2",
 		"@types/node": "^24.3.0",
 		"husky": "^9.1.7",
 		"rregex": "1.13.1",
@@ -113,7 +116,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 +180,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-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"
 	},

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,281 @@
+#!/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.
+//
+// It runs under the operator-provided runtime's own source resolver, which is what selects the
+// runtime — this file carries no path into it. `entwurf pi-durable` (run.sh) locates that runtime
+// at its one fixed place, verifies it against the pin, and execs:
+//
+//   node --import <runtime>/packages/coding-agent/src/experimental/source-resolver.ts \
+//        <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.
+//
+// Without that resolver the two pi-coding-agent experimental subpath imports below fail: the
+// published package ships no experimental source, and that failure is the honest one. They are the
+// one sanctioned pi private-subpath exception (check-pi-import-surface, #129).
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { decodeOmpBootstrapPayload } from "../../mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-omp.js";
+import {
+	closeAll,
+	createPiDurableContact,
+	failAfterCleanup,
+	withGardenIdentity,
+} from "../../mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-pi-durable.js";
+
+const RUNTIME = "@earendil-works/pi-coding-agent/experimental/durable/runtime.ts";
+const TUI = "@earendil-works/pi-coding-agent/experimental/durable/tui.ts";
+
+/** 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"];
+/** Flags only a NEW session can honour. */
+const FRESH_ONLY_FLAGS = ["--provider", "--model", "--width", "--entwurf-bootstrap"];
+
+/** 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;
+
+/**
+ * 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.
+ *
+ * @param {{
+ *   bridgeEntry?: string,
+ *   continueSession?: boolean,
+ *   cwd?: string,
+ *   model?: { provider: string, model: string },
+ *   firstInput?: string,
+ *   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,
+	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],
+			...(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`,
+		);
+	}
+	if (continueSession) return { continueSession };
+	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 }),
+	};
+}
+
+/**
+ * Parse, load the TUI, open, run, close. `loadTui`, `open` and `contact` are test seams.
+ *
+ * @param {readonly string[]} argv
+ * @param {{
+ *   loadTui?: () => Promise<{ runDurableTui: (...args: any[]) => Promise<void> }>,
+ *   open?: (options: any) => Promise<any>,
+ *   contact?: Record<string, unknown>,
+ * }} [seams]
+ */
+export async function main(argv, { loadTui = () => import(TUI), open, contact } = {}) {
+	// Every refusal is decided here, before the TUI loads and before anything opens.
+	const args = parseArgs(argv);
+	// 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, 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/overlay/runtime-contacts.patch

@@ -0,0 +1,91 @@
+diff --git a/packages/coding-agent/src/experimental/durable/runtime.ts b/packages/coding-agent/src/experimental/durable/runtime.ts
+index fcd6e523..929dbc79 100644
+--- a/packages/coding-agent/src/experimental/durable/runtime.ts
++++ b/packages/coding-agent/src/experimental/durable/runtime.ts
+@@ -8,7 +8,9 @@ import {
+ 	type ConversationView,
+ 	type Cursor,
+ 	type EntryRecord,
++	type Extension,
+ 	Harness,
++	type InputSubmissionDraft,
+ 	type ModelRef,
+ 	ROOT_CONVERSATION_ID,
+ 	type Submission,
+@@ -81,6 +83,10 @@ export interface DurableController {
+ export interface OpenDurableOptions {
+ 	readonly cwd?: string;
+ 	readonly continueSession?: boolean;
++	/** Installed after the built-in extensions and before the Harness opens, so recovered work finds their tools. */
++	readonly extensions?: readonly Extension[];
++	/** A new session's explicit model, resolved as pi's `--provider`/`--model`; unresolved, the open fails. */
++	readonly model?: { readonly provider: string; readonly model: string };
+ }
+ 
+ export interface OpenDurableResult {
+@@ -88,6 +94,8 @@ export interface OpenDurableResult {
+ 	readonly controller: DurableController;
+ 	/** pi's settings, for the TUI's theme and terminal capabilities. */
+ 	readonly settings: SettingsManager;
++	/** Admits input to the root conversation, whichever one is on screen; resolves at admission, not at the answer. */
++	submitToRoot(draft: InputSubmissionDraft): Promise<Submission>;
+ 	close(): Promise<void>;
+ }
+ 
+@@ -122,6 +130,9 @@ function titleOf(entry: EntryRecord | undefined): { title?: string } {
+ }
+ 
+ export async function openDurable(options: OpenDurableOptions = {}): Promise<OpenDurableResult> {
++	if (options.model !== undefined && options.continueSession) {
++		throw new Error("An explicit model applies only to a new session, not to a continued one");
++	}
+ 	const location = await selectSession(options.cwd ?? process.cwd(), options.continueSession ?? false);
+ 	const envs = new ExecutionEnvs(location.cwd);
+ 	let harness: Harness | undefined;
+@@ -132,6 +143,7 @@ export async function openDurable(options: OpenDurableOptions = {}): Promise<Ope
+ 		const settings = createHarnessSettings(settingsManager);
+ 		const registry = createCodingRegistry(settingsManager, location.cwd);
+ 		registry.install(Subagent);
++		for (const extension of options.extensions ?? []) registry.install(extension);
+ 
+ 		const pendingReports: unknown[] = [];
+ 		let report: (error: unknown) => void = (error) => pendingReports.push(error);
+@@ -146,7 +158,29 @@ export async function openDurable(options: OpenDurableOptions = {}): Promise<Ope
+ 			},
+ 			context,
+ 		);
+-		const initial = location.created ? await findInitialAgentModel(settingsManager, modelRuntime) : undefined;
++		const initial = location.created
++			? await findInitialAgentModel(settingsManager, modelRuntime, options.model)
++			: undefined;
++		if (options.model !== undefined) {
++			// pi resolves case-insensitive, partial and unknown ids too (a custom-id fallback with only a warning);
++			// an explicit model must be exactly one registered catalog model, named by its canonical id.
++			const asked = options.model;
++			const ref = initial?.model;
++			const thinking = initial?.thinkingLevel;
++			const registered = ref !== undefined && modelRuntime.getModel(ref.provider, ref.modelId) !== undefined;
++			const named =
++				ref !== undefined &&
++				(asked.model === ref.modelId || (thinking !== undefined && asked.model === `${ref.modelId}:${thinking}`));
++			if (ref === undefined || ref.provider !== asked.provider || !registered || !named) {
++				const resolved =
++					ref === undefined
++						? "none"
++						: `${ref.provider}/${ref.modelId}${thinking === undefined ? "" : `:${thinking}`}`;
++				throw new Error(
++					`explicit-model-not-exact: asked ${asked.provider}/${asked.model}, resolved ${resolved} (registered=${registered})`,
++				);
++			}
++		}
+ 		const root = await harness.root(context, {
+ 			agent: {
+ 				cwd: location.cwd,
+@@ -342,6 +376,7 @@ export async function openDurable(options: OpenDurableOptions = {}): Promise<Ope
+ 			},
+ 			controller,
+ 			settings: settingsManager,
++			submitToRoot: (draft) => root.submit(draft, context),
+ 			close() {
+ 				closing ??= (async () => {
+ 					unsubscribe();

package/pi/pi-durable/overlay/upstream-pin.json

@@ -0,0 +1,16 @@
+{
+	"schemaVersion": 1,
+	"comment": "The one upstream commit this overlay is maintained against, and the patch it applies. The experimental durable app is source-only upstream, so its runtime is a pinned checkout plus this patch, provisioned by the operator; Entwurf ships neither. A checkout's TRACKED tree counts as this overlay only when HEAD equals commit, `git diff` equals the patch bytes exactly, and no non-ignored file is untracked. Git-ignored runtime inputs are outside that equality and are described separately below.",
+	"repository": "https://github.com/earendil-works/pi",
+	"commit": "cd32f7725fdbddbaecdff5b1e68491563394e0ca",
+	"patches": ["runtime-contacts.patch"],
+	"modelData": {
+		"comment": "Git-ignored generated model data the runtime imports at open. Upstream hydrates it by calling vendor model-list endpoints; this overlay instead takes the bytes the v1.0.2 release built from this commit, from the published package below, with no network. aggregateSha256 is sha256 over one `<sha256 of file>  <file name>\\n` line per *.json file (dotfiles excluded), names in C byte order. upstream `packages/ai/scripts/check-model-data.ts` validates these bytes against the manifest.",
+		"path": "packages/ai/src/providers/data",
+		"source": "@earendil-works/pi-ai@1.0.2 dist/providers/data",
+		"integrity": "sha512-JP59xGlSAQ/HhQ6EHN5qmneBlWfDyu6FPPryAvAaSo8A38ubAsEpS9YisCM5Jbbns0srrDffLZonE0OXorHI5A==",
+		"files": 42,
+		"aggregateSha256": "e71a1965a81c29fbe83d6e90dc1f4595602588281374603dee9e3bcbb7f46fa4",
+		"manifestSha256": "d373b99c0860f84281d786d493e8d8237c0a9fd98f142ef31c6db187c5089bc5"
+	}
+}