@junghanacs/entwurf 0.30.0 → 0.31.0

package/pi-extensions/lib/acp/backend-adapter.ts

@@ -21,6 +21,7 @@
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { RequestError } from "@agentclientprotocol/sdk";
 
 import type { AcpConnectionLike } from "./acp-client.js";
 import { enrichMcpServersWithEnvelope, type ResolvedAcpConfig } from "./config.js";
@@ -235,14 +236,73 @@ export interface AcpBackendAdapter {
 	 *  entwurf actually reads from a NOTIFICATION cannot desync from a response
 	 *  shape it never inspects. */
 	sealsTurnAccounting?: true;
+
+	/** OPTIONAL capability (#127): recognise a typed vendor rejection of `session/prompt`
+	 *  whose raw text must not become pi's `errorMessage`. pi decides a whole-prompt replay
+	 *  from `errorMessage` alone, and a vendor's "Internal error" — or any digit run in the
+	 *  ids it carries — reads as transient, so a turn whose tools already ran would be resent
+	 *  from a cold session. A recognised rejection returns a fixed, authored verdict for
+	 *  `errorMessage`; backend.ts keeps the raw rejection as a pi diagnostic instead.
+	 *
+	 *  ABSENT means every failure of this backend keeps the verbatim-first `errorMessage`.
+	 *  The vocabulary is the vendor's, so only the adapter that speaks it may declare it. */
+	readPromptRejection?(err: unknown): AcpPromptRejection | undefined;
+}
+
+/** A vendor rejection an adapter recognised (`readPromptRejection`). */
+export interface AcpPromptRejection {
+	/** The vendor's own failure kind, as it named it on the wire. */
+	errorKind: string;
+	/** Entwurf-authored and fixed — no vendor text, ids or numbers: this is what pi classifies. */
+	verdict: string;
+	/** The JSON-RPC `data`, re-serialized as evidence (it arrived as parsed JSON). */
+	dataJson: string;
 }
 
+/** The pi diagnostic type under which backend.ts preserves a recognised rejection verbatim. */
+export const ACP_PROMPT_REJECTION_DIAGNOSTIC = "entwurf_acp_prompt_rejection";
+
+/** The verdict for claude-agent-acp's `incomplete_tool_call` (#127; upstream #1212, 0.85.0+). */
+export const INCOMPLETE_TOOL_CALL_VERDICT =
+	"ACP turn failed because foreground tool results are incomplete. Some tools may already have run; automatic replay is unsafe. Inspect the preserved vendor rejection before continuing.";
+
 // ---------------------------------------------------------------------------
 // claude adapter — the first implementation (the rail's reference backend)
 // ---------------------------------------------------------------------------
 
 const SUPPORTED_CLAUDE_IDS: ReadonlySet<string> = new Set(SUPPORTED_ANTHROPIC_MODEL_IDS);
 
+/** JSON-RPC internal error — the code claude-agent-acp rejects an unfinished-tool turn with. */
+const JSONRPC_INTERNAL_ERROR = -32603;
+/** claude-agent-acp's own kind for a turn that hit `end_turn` with foreground tools unanswered
+ *  (read at v0.85.1 `src/acp-agent.ts:4286-4340`, `errorKindData("incomplete_tool_call")`). */
+const CLAUDE_INCOMPLETE_TOOL_CALL = "incomplete_tool_call";
+
+/**
+ * The claude reader for `readPromptRejection` (#127). Only the root wire SDK's own decode
+ * counts: its client rejects a JSON-RPC error response with `new RequestError(code, message,
+ * data)`, `data` being the parsed `error.data` (sdk 1.4.0 `dist/jsonrpc.js:842-844`). A
+ * look-alike object, another code, or another `errorKind` is not this failure and keeps the
+ * verbatim-first path.
+ */
+function readClaudePromptRejection(err: unknown): AcpPromptRejection | undefined {
+	if (!(err instanceof RequestError) || err.code !== JSONRPC_INTERNAL_ERROR) return undefined;
+	const data = err.data;
+	if (typeof data !== "object" || data === null || !("errorKind" in data)) return undefined;
+	if (data.errorKind !== CLAUDE_INCOMPLETE_TOOL_CALL) return undefined;
+	return { errorKind: CLAUDE_INCOMPLETE_TOOL_CALL, verdict: INCOMPLETE_TOOL_CALL_VERDICT, dataJson: jsonText(data) };
+}
+
+/** Evidence text for a wire value. A value that came off the wire serializes; one that cannot
+ *  (a hand-built fake) is named as such, so recording evidence never breaks the turn's seal. */
+function jsonText(value: unknown): string {
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch (err) {
+		return `[unserializable: ${err instanceof Error ? err.name : typeof err}]`;
+	}
+}
+
 /**
  * Resolve the claude launch — an ENTWURF-OWNED launcher, or the env override for debug.
  * This is the single source for the claude launch spec; backend.ts holds no private copy.
@@ -359,6 +419,10 @@ export const claudeAdapter: AcpBackendAdapter = {
 	// The token partition is NOT declared here: ACP's only token carrier is a
 	// per-turn round-trip aggregate, which is not what pi's four fields mean.
 	sealsTurnAccounting: true,
+
+	// #127: claude-agent-acp 0.85.0+ rejects an `end_turn` with unanswered foreground tools as
+	// -32603 `incomplete_tool_call` (upstream #1212). Its raw text reads as transient to pi.
+	readPromptRejection: readClaudePromptRejection,
 };
 
 // ---------------------------------------------------------------------------
@@ -527,6 +591,10 @@ export const cortexAdapter: AcpBackendAdapter = {
 	// backend.ts seals nothing for a backend without this flag, so cortex's
 	// emitted usage is byte-identical to what it was before #93. Declaring this
 	// with a guess would mint exactly the silent misaccounting #93 exists to end.
+
+	// NO readPromptRejection — also deliberate. Nobody has read which failures cortex's ACP
+	// server rejects a prompt with, so every cortex failure keeps the verbatim-first
+	// errorMessage. Borrowing claude's `incomplete_tool_call` reader would be a guess.
 };
 
 const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter, cortexAdapter];

package/pi-extensions/lib/acp/backend.ts

@@ -45,7 +45,12 @@ import { readFileSync } from "node:fs";
 import { Readable, Writable } from "node:stream";
 import { ndJsonStream, PROTOCOL_VERSION } from "@agentclientprotocol/sdk";
 import type { Api, AssistantMessage, Model, SimpleStreamOptions, TranscriptContext } from "@earendil-works/pi-ai";
-import { createAssistantMessageEventStream, getCurrentTools } from "@earendil-works/pi-ai";
+import {
+	appendAssistantMessageDiagnostic,
+	createAssistantMessageDiagnostic,
+	createAssistantMessageEventStream,
+	getCurrentTools,
+} from "@earendil-works/pi-ai";
 import {
 	type AcpClientHandlers,
 	type AcpConnectionLike,
@@ -53,7 +58,11 @@ import {
 	connectAcpClient,
 } from "./acp-client.js";
 import { prependNewPromptAugment } from "./augment.js";
-import { type AcpBackendAdapter, resolveAcpBackendAdapter } from "./backend-adapter.js";
+import {
+	ACP_PROMPT_REJECTION_DIAGNOSTIC,
+	type AcpBackendAdapter,
+	resolveAcpBackendAdapter,
+} from "./backend-adapter.js";
 import {
 	enrichMcpServersWithEnvelope,
 	mcpServerNames,
@@ -1435,13 +1444,18 @@ export function streamAcpTurn(
 		stderrTail?: string[],
 		lifecycle?: string,
 		launchObservation?: AcpLaunchObservation,
+		/** Passed only from the two prompt-phase catches, where the turn's adapter is resolved. */
+		adapter?: AcpBackendAdapter,
 	): void {
 		finalizeAcpStreamState(state);
 		state.output.stopReason = aborted ? "aborted" : "error";
 		const base = err instanceof Error ? err.message : String(err);
 		// The FIRST failure stays first and verbatim (it is what the backend
 		// actually said); the lifecycle line is added, never substituted, so a
-		// reader can still match the transport's own text.
+		// reader can still match the transport's own text. One typed exception
+		// below: a vendor rejection the adapter recognises keeps that verbatim text
+		// as a pi diagnostic instead, because pi reads errorMessage to decide a
+		// whole-prompt replay (#127).
 		const withLifecycle = lifecycle ? `${base}\n${lifecycle}` : base;
 		// Its OWN line, above the vendor tail: an entwurf-owned observation must not
 		// have to be recovered by reading vendor prose.
@@ -1453,7 +1467,28 @@ export function streamAcpTurn(
 		// overflow gets an actionable hint appended, so "API Error" stops hiding
 		// the turn-scoped full-transcript-replay cause.
 		const hint = aborted ? undefined : actionableAcpBackendHint(full);
-		state.output.errorMessage = hint ? `${full}\n\n${hint}` : full;
+		// #127: pi's retry and overflow classifiers read `errorMessage` ALONE, and a
+		// vendor's "Internal error" or any digit run in its ids/stderr reads as transient
+		// — a replay of a turn whose tools already ran. A rejection the adapter names gets
+		// its fixed verdict there; every raw part rides one diagnostic, appended after any
+		// existing ones. An abort keeps the abort path.
+		const rejection = aborted ? undefined : adapter?.readPromptRejection?.(err);
+		if (rejection) {
+			appendAssistantMessageDiagnostic(
+				state.output,
+				createAssistantMessageDiagnostic(ACP_PROMPT_REJECTION_DIAGNOSTIC, err, {
+					errorKind: rejection.errorKind,
+					dataJson: rejection.dataJson,
+					...(lifecycle ? { lifecycle } : {}),
+					...(observed ? { launchSignal: observed } : {}),
+					...(tail ? { stderrTail: tail } : {}),
+					...(hint ? { hint } : {}),
+				}),
+			);
+			state.output.errorMessage = rejection.verdict;
+		} else {
+			state.output.errorMessage = hint ? `${full}\n\n${hint}` : full;
+		}
 		stream.push({ type: "error", reason: aborted ? "aborted" : "error", error: state.output });
 		stream.end();
 	}
@@ -1915,6 +1950,7 @@ export function streamAcpTurn(
 				session?.stderrTail ?? stderrTail,
 				lifecycle,
 				session?.launchObservation ?? launchObservation,
+				adapter,
 			);
 			// error/abort → drop the (uncertain) session and close its child; an
 			// uncertain connection must never be reused (GPT ④).
@@ -1982,7 +2018,7 @@ export function streamAcpTurn(
 			// Without the session-scoped tail a mid-turn child death on a resident
 			// session surfaced as a bare "ACP connection closed" with nothing to read
 			// it by.
-			finishError(err, aborted, session.stderrTail, lifecycle, session.launchObservation);
+			finishError(err, aborted, session.stderrTail, lifecycle, session.launchObservation, adapter);
 			// error/abort on a reused session → drop it and close the child (GPT ④).
 			session.retiring = true;
 			retainedChildren.delete(session.child);

package/pi-extensions/lib/entwurf-deliverability.ts

@@ -142,7 +142,13 @@ export function receiverMarkerMatchesIdentity(
 // previous garden in-process on its `/new` edge (the unarm the claude hook lacked),
 // so the cell this join closes has a different owner there. Admitting it needs its
 // own measurement, not this file's optimism.
-export const SENDER_JOINED_RECEIVER_OWNER_KINDS: readonly string[] = ["claude-code-cli"];
+//
+// `pi-durable-host` is admitted because the join holds by construction: the durable contact
+// writes its sender marker under the host's own pid and arms its watch in that same process
+// (`meta-bridge-pi-durable.ts`), so the receiver marker's `ownerPid` IS the sender-marker key.
+// Inside the scope a host whose sender marker is gone or names another garden is a retired
+// watch, which is the refusal this admission exists to make reachable.
+export const SENDER_JOINED_RECEIVER_OWNER_KINDS: readonly string[] = ["claude-code-cli", "pi-durable-host"];
 
 /** Does this watch owner share its pid with the backend's sender marker? */
 export function receiverOwnerKindJoinsSender(ownerKind: string): boolean {

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",
+};