@junghanacs/entwurf 0.30.1 → 0.31.0

package/pi-extensions/lib/fresh-call-composition.ts

@@ -25,11 +25,12 @@
 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, and `codex`
- * by #95 after its system birth and app-server rails were measured. The set is joined to the
+ * 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
  * 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"] as const;
+export const FRESH_CALL_BACKENDS = ["pi", "claude-code", "copilot", "omp", "codex", "pi-durable"] as const;
 export type FreshCallBackend = (typeof FRESH_CALL_BACKENDS)[number];
 
 /**
@@ -68,6 +69,11 @@ export const FRESH_CALL_CALLBACK_TOOL: Record<FreshCallBackend, string> = {
 	// Codex's tool process is the operator app-server, not the pane: the no-arg
 	// verb refuses there by name. First action stays the delivery verb with args.
 	codex: "mcp__entwurf_bridge__entwurf_v2",
+	// The durable contact registers the bridge verbs as its OWN tools under their bare names, and the
+	// app offers a tool to the model by its registered name (`durable/harness/registry.ts:99`
+	// @cd32f77). Measured for `entwurf_v2` on the S+native-H wire (receipt 4012c066); the callback
+	// spelling follows the same rule and is owed its first LIVE observation.
+	"pi-durable": "entwurf_callback",
 };
 
 /** Where a sibling SENDS the task result. Always the delivery verb, never the birth callback. */
@@ -77,6 +83,7 @@ export const FRESH_CALL_DELIVERY_TOOL: Record<FreshCallBackend, string> = {
 	copilot: "entwurf-bridge-entwurf_v2",
 	omp: "mcp__entwurf_bridge_entwurf_v",
 	codex: "mcp__entwurf_bridge__entwurf_v2",
+	"pi-durable": "entwurf_v2",
 };
 
 /**
@@ -99,6 +106,7 @@ export const FRESH_CALL_PEERS_TOOL: Record<FreshCallBackend, string> = {
 	copilot: "entwurf-bridge-entwurf_peers",
 	omp: "mcp__entwurf_bridge_entwurf_peers",
 	codex: "mcp__entwurf_bridge__entwurf_peers",
+	"pi-durable": "entwurf_peers",
 };
 
 /**
@@ -139,13 +147,16 @@ export const FRESH_CALL_TOOL_LOAD_HINT: Record<FreshCallBackend, readonly string
 	copilot: [],
 	omp: [],
 	codex: [],
+	"pi-durable": [],
 };
 
 /**
- * What a launch has to say, in the two shapes the five backends need. Four of them are
- * handed a first-turn PROMPT; omp is handed a bootstrap PAYLOAD its own installed extension
- * unpacks. Both are always built, because building one is cheap and a backend switch must
- * never be able to reach a field that was not composed.
+ * What a launch has to say, in the two shapes the six backends need. pi, claude-code, copilot
+ * and codex are handed the first-turn PROMPT as an argument; pi-durable is handed that same
+ * PROMPT inside the closed `{v,task}` payload on the bootstrap flag, which its packaged bootstrap
+ * decodes; omp is handed its own bootstrap PAYLOAD, which its installed extension unpacks. Both
+ * are always built, because building one is cheap and a backend switch must never be able to
+ * reach a field that was not composed.
  */
 export interface FreshCallComposition {
 	prompt: string;
@@ -339,6 +350,30 @@ export function composeBackendArgs(
 				"--dangerously-bypass-approvals-and-sandbox",
 				composition.prompt,
 			];
+		case "pi-durable": {
+			// The managed verb (`entwurf pi-durable`) carries the explicit model as pi's own
+			// `--provider`/`--model` pair, split at the FIRST `/` (the preflight already refused a model
+			// with no provider), the explicit width, and the WHOLE framing as the closed `{v,task}`
+			// payload — the durable bootstrap submits it to the root once, after the birth. The
+			// caller's address rides the env pair, never this payload.
+			const at = model.indexOf("/");
+			if (at <= 0 || at === model.length - 1) {
+				throw new Error(
+					`fresh-call composition: pi-durable model ${JSON.stringify(model)} is not <provider>/<model id>`,
+				);
+			}
+			return [
+				"pi-durable",
+				"--provider",
+				model.slice(0, at),
+				"--model",
+				model.slice(at + 1),
+				"--width",
+				"task-wide",
+				`--${OMP_BOOTSTRAP_FLAG}`,
+				JSON.stringify({ v: OMP_BOOTSTRAP_VERSION, task: composition.prompt }),
+			];
+		}
 	}
 }
 

package/pi-extensions/lib/meta-sender-identity.ts

@@ -73,7 +73,13 @@ import { type NativePushAdapter, resolveNativePushAdapter } from "./native-push/
  * exactly the #46 defect on agy, and copilot joined the list only once its own hook wrote one
  * (#82 RAIL 5b). Membership says a marker may EXIST, never that a reply can land: the reply
  * rail is chosen from `nativePushSupported` at the bridge, not from this list. */
-export const META_SENDER_BACKENDS: readonly MetaBackend[] = ["claude-code", "antigravity", "copilot", "omp"];
+export const META_SENDER_BACKENDS: readonly MetaBackend[] = [
+	"claude-code",
+	"antigravity",
+	"copilot",
+	"omp",
+	"pi-durable",
+];
 
 /** A marker that passed BOTH guards, together with the record that vouches for it. */
 export interface TrustedMetaSender {

package/pi-extensions/lib/meta-session.ts

@@ -81,7 +81,7 @@ export class MetaRecordError extends Error {
  * every write, including its own. `./run.sh doctor-meta-bridge` already flags a
  * stale deployed writer — run it after the change.
  */
-export const META_BACKENDS = ["claude-code", "antigravity", "codex", "copilot", "omp"] as const;
+export const META_BACKENDS = ["claude-code", "antigravity", "codex", "copilot", "omp", "pi-durable"] as const;
 export type MetaBackend = (typeof META_BACKENDS)[number];
 
 /**
@@ -222,6 +222,24 @@ export const META_BACKEND_DESCRIPTORS: Record<MetaBackend, MetaBackendDescriptor
 		deliveryLevel: "D6",
 		nativeIdLabel: "sessionId",
 	},
+	// The long-running durable app (#129). Graded only as far as its RECORDED receipts reach.
+	//   sessionId the durable session directory name `<13-digit ms>-<uuid>` that
+	//             `selectSession` creates and `--continue` reopens
+	//             (`experimental/durable/sessions.ts:18-55` @cd32f77), surfaced as
+	//             `view.current().session.id`. Not `pi.provider.sessionId`, which a
+	//             fork changes.
+	//   D2        receiver armed: the contact mints the record, names the host as sender, and arms
+	//             a root doorbell (the receiver marker is owned by the host pid as `pi-durable-host`,
+	//             which the owner join admits). The addressed-enqueue → idle-wake → root-notice → drain
+	//             chain has ONE recorded receipt, on the scripted-model + native-harness lab cell
+	//             (`check-pi-durable-receive`, S+H, V not run) — lab evidence, not a vendor-turn D4–D6
+	//             acceptance, and no sibling-isolation (D3) or LIVE fresh receipt exists yet.
+	"pi-durable": {
+		backend: "pi-durable",
+		wakeMode: "self-fetch",
+		deliveryLevel: "D2",
+		nativeIdLabel: "sessionId",
+	},
 };
 
 // ---------------------------------------------------------------------------
@@ -305,7 +323,15 @@ function isoNow(now: Date): string {
 export const META_SCHEMA_VERSION_V3 = 3 as const;
 
 /** Every backend admitted by the one V3 record-citizen schema. */
-export const META_CITIZEN_BACKENDS = ["claude-code", "antigravity", "codex", "copilot", "omp", "pi"] as const;
+export const META_CITIZEN_BACKENDS = [
+	"claude-code",
+	"antigravity",
+	"codex",
+	"copilot",
+	"omp",
+	"pi-durable",
+	"pi",
+] as const;
 export type MetaCitizenBackend = (typeof META_CITIZEN_BACKENDS)[number];
 
 /**

package/pi-extensions/lib/mux-fresh-call.ts

@@ -143,6 +143,12 @@ import {
 } from "./mux-placement.ts";
 import { resolveCodexDefaultSocketPath } from "./native-push/codex-ws-client.ts";
 import { OMP_PREFLIGHT_HINT, type OmpPreflightRejectReason, ompFreshPreflight } from "./omp-fresh-preflight.ts";
+import {
+	PI_DURABLE_PREFLIGHT_HINT,
+	type PiDurablePreflightRejectReason,
+	piDurableFreshPreflight,
+} from "./pi-durable-fresh-preflight.ts";
+import { checkPiDurableRuntime, PI_DURABLE_RUNTIME_HINT, piDurablePackageLayout } from "./pi-durable-runtime.ts";
 import { classifyTmuxSessionName, resolveTmuxSessionId, type TmuxSessionRejectReason } from "./resolve-tmux-session.ts";
 
 /**
@@ -238,6 +244,10 @@ export const FRESH_CALL_RUNTIME: Record<FreshCallBackend, string> = {
 	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.
+	"pi-durable": "entwurf",
 };
 
 /** A launch that was refused, or a placement that could not be established. Every value is a
@@ -251,6 +261,7 @@ export type FreshCallRejectReason =
 	| TmuxSessionRejectReason
 	| CopilotPreflightRejectReason
 	| OmpPreflightRejectReason
+	| PiDurablePreflightRejectReason
 	| CodexPreflightRejectReason
 	| CodexCallerPreflightRejectReason
 	| CodexCallerSeatRejectReason
@@ -350,9 +361,9 @@ export type FreshCallResult = { ok: true; receipt: FreshCallReceipt } | { ok: fa
  * for. That is sufficient and not a compromise: every reader of the carrier trims and tests
  * truthiness (`index.ts:212-217`), so empty and absent are the same answer by construction.
  *
- * It is applied to all five backends because the leak is a property of tmux, not of a vendor. A
+ * It is applied to all six backends because the leak is a property of tmux, not of a vendor. A
  * scrub only on the backend whose measurement surfaced it would encode the claim that the other
- * four are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
+ * five are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
  * authoritative when the process that owns it exported it ITSELF, and a fresh `pi` sibling does
  * exactly that after this argv has run. This is a fixed seam and deliberately NOT a general env
  * carrier — an arbitrary `-e` passthrough would hand callers the environment-shaping power this
@@ -506,6 +517,25 @@ export function freshCall(
 		const missing = ompFreshPreflight(env);
 		if (missing) return { ok: false, reason: missing };
 	}
+	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
+		// 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 missing = piDurableFreshPreflight({
+			model,
+			firstInput: buildFreshCallPrompt({ backend: params.backend, task, callerGardenId, nonce }),
+			layout,
+			runtime: runtime === null || runtime.ok ? null : runtime.reason,
+		});
+		if (missing) return { ok: false, reason: missing };
+	}
 	const inspected = inspectPlacement(env);
 	if (!inspected.ok) return { ok: false, reason: inspected.reason };
 	const placement = inspected.placement;
@@ -626,6 +656,8 @@ const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 	// the sentence an operator reads cannot drift away from the predicate that produced it.
 	...COPILOT_PREFLIGHT_HINT,
 	...OMP_PREFLIGHT_HINT,
+	...PI_DURABLE_RUNTIME_HINT,
+	...PI_DURABLE_PREFLIGHT_HINT,
 	...CODEX_PREFLIGHT_HINT,
 	...CODEX_CALLER_PREFLIGHT_HINT,
 	...CODEX_CALLER_SEAT_HINT,

package/pi-extensions/lib/pi-durable-fresh-preflight.ts

@@ -0,0 +1,113 @@
+/**
+ * pi-durable-fresh-preflight — the pre-mutation check a pi-durable fresh call needs (#129 W, L6;
+ * `docs/adding-a-harness.md` step 9 clauses 2, 3 and 5).
+ *
+ * Same question as `omp-fresh-preflight.ts`, at the same moment: before `mux-fresh-call` mutates the
+ * operator's tmux session, is everything the fresh contract needs actually in place? A refusal HERE,
+ * before placement, leaves no window behind. A pass here does not promise the window's own pass: the
+ * managed verb re-verifies inside the window, whose env is the tmux SERVER's and whose `entwurf` is
+ * whatever PATH names, so under env or package-closure skew it can still refuse after the window
+ * exists — and that refusal is left showing in it.
+ *
+ * ── The inputs, first ──
+ *
+ *   model         the fresh-call model grammar already admits `/`, and a durable launch needs the
+ *                 provider spelled out (the bootstrap refuses a model resolved by inference), so
+ *                 the model here is `<provider>/<model id>` split at the FIRST `/` — a catalog id
+ *                 that itself contains `/` keeps it. A model with no provider part is refused.
+ *   first input   the whole framing (callback first, then the task) rides the bootstrap's closed
+ *                 `{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 ──
+ *
+ *   runtime          operator-provided at the fixed locator and verified against the pin
+ *                    (`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.
+ *   receive          the compiled owner join in the same closure admits `pi-durable-host`; without
+ *                    it every dispatch to the citizen is the honest `mailbox-undeliverable`.
+ *   visible identity the packaged bootstrap — the one that hands the TUI the view whose conversation
+ *                    labels carry the garden id.
+ *
+ * ── What this deliberately does NOT claim ──
+ *
+ * Filesystem truth about ONE package closure and ONE runtime directory. 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.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import type { PiDurablePackageLayout, PiDurableRuntimeRejectReason } from "./pi-durable-runtime.ts";
+
+/** The bootstrap decoder's task cap (`meta-bridge-omp.ts` OMP_BOOTSTRAP_TASK_MAX_CHARS); the beside
+ * test holds the two equal. */
+export const PI_DURABLE_FIRST_INPUT_MAX_CHARS = 16000;
+
+export type PiDurablePreflightRejectReason =
+	| "pi-durable-model-not-provider-qualified"
+	| "pi-durable-first-input-too-long"
+	| PiDurableRuntimeRejectReason
+	| "pi-durable-birth-unit-missing"
+	| "pi-durable-mcp-hand-missing"
+	| "pi-durable-receive-unit-missing"
+	| "pi-durable-visible-identity-missing";
+
+/** `<provider>/<model id>` at the FIRST `/`, or `null` when either side is empty. */
+export function splitPiDurableModel(model: string): { provider: string; model: string } | null {
+	const at = model.indexOf("/");
+	if (at <= 0 || at === model.length - 1) return null;
+	return { provider: model.slice(0, at), model: model.slice(at + 1) };
+}
+
+/** The compiled owner join, read from the emitted bytes the bridge actually loads. */
+function ownerJoinAdmitsDurableHost(file: string): boolean {
+	try {
+		const join = /SENDER_JOINED_RECEIVER_OWNER_KINDS\s*=\s*(\[[^\]]*\])/.exec(readFileSync(file, "utf8"))?.[1];
+		return join?.includes('"pi-durable-host"') ?? false;
+	} catch {
+		// Bounded environment probe: an unreadable file is a missing unit.
+		return false;
+	}
+}
+
+/** The FIRST missing thing, in repair order, or `null` when a fresh launch may proceed. */
+export function piDurableFreshPreflight(params: {
+	readonly model: string;
+	readonly firstInput: string;
+	readonly layout: PiDurablePackageLayout | null;
+	/** The verdict of `checkPiDurableRuntime` for the caller's env: `null` = verified. */
+	readonly runtime: PiDurableRuntimeRejectReason | null;
+}): PiDurablePreflightRejectReason | null {
+	if (splitPiDurableModel(params.model) === null) return "pi-durable-model-not-provider-qualified";
+	if (params.firstInput.length > PI_DURABLE_FIRST_INPUT_MAX_CHARS) return "pi-durable-first-input-too-long";
+	if (params.layout === null) return "pi-durable-package-incomplete";
+	if (params.runtime !== null) return params.runtime;
+	const layout = params.layout;
+	if (!existsSync(layout.adapter)) return "pi-durable-birth-unit-missing";
+	if (!existsSync(layout.bridgeEntry)) return "pi-durable-mcp-hand-missing";
+	if (!ownerJoinAdmitsDurableHost(layout.deliverability)) return "pi-durable-receive-unit-missing";
+	if (!existsSync(layout.bootstrap)) return "pi-durable-visible-identity-missing";
+	return null;
+}
+
+/** Repair text beside the predicate that decides it. The runtime reasons keep theirs on the runtime
+ * leaf; `mux-fresh-call` spreads both tables. */
+export const PI_DURABLE_PREFLIGHT_HINT: Record<
+	Exclude<PiDurablePreflightRejectReason, PiDurableRuntimeRejectReason>,
+	string
+> = {
+	"pi-durable-model-not-provider-qualified":
+		"a pi-durable model is `<provider>/<model id>` — the durable bootstrap resolves no provider by inference",
+	"pi-durable-first-input-too-long":
+		"the framed first input exceeds the 16000-character bootstrap payload cap — shorten the task",
+	"pi-durable-birth-unit-missing":
+		"this Entwurf package has no compiled pi-durable contact (mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-pi-durable.js), so the sibling would mint no record — reinstall or rebuild Entwurf",
+	"pi-durable-mcp-hand-missing":
+		"this Entwurf package has no compiled entwurf-bridge entry, so the sibling's callback tool would not exist — reinstall or rebuild Entwurf",
+	"pi-durable-receive-unit-missing":
+		"this Entwurf package's compiled owner join does not admit pi-durable-host, so nothing could ever be delivered to the sibling — reinstall or rebuild Entwurf",
+	"pi-durable-visible-identity-missing":
+		"this Entwurf package has no packaged pi-durable bootstrap (pi/pi-durable/bootstrap.mjs), so no TUI would carry the garden id — reinstall Entwurf",
+};