@junghanacs/entwurf 0.35.1 → 0.36.1

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

@@ -1,64 +1,107 @@
 {
-	"schemaVersion": 2,
-	"comment": "The one upstream commit the pi-durable carrier is emitted from, the patch it applies, the emitted files and the published SDK set they run against. The experimental durable app is source-only upstream (published pi-coding-agent ships no dist/experimental), so Entwurf ships it as a CARRIER: the pinned app files, type-stripped, with the relocation in pi/pi-durable/carrier-relocation.mjs. scripts/emit-pi-durable-carrier.ts is the only writer of the generated fields (blob, sha256, emitter.node) and the only reader of upstream source; an installed package never reads source. Model data rides the published @earendil-works/pi-ai.",
-	"repository": "https://github.com/earendil-works/pi",
-	"tag": "v1.1.0",
-	"commit": "abe508e1b89912adde45528136c3221eb69acdd7",
-	"patches": ["runtime-contacts.patch"],
+	"schemaVersion": 3,
+	"comment": "The pi-durable carrier: what it is emitted from, what it is, and the published SDK set it runs against. The experimental durable app is source-only upstream (published pi-coding-agent ships no dist/experimental), so Entwurf owns its thin application/TUI composition as canonical source (pi/pi-durable/src) and ships it as a CARRIER: those files, type-stripped, with the relocation in pi/pi-durable/carrier-relocation.mjs. The SDK engine (execution, scheduler, queues, storage/transcript, compaction, cancellation/recovery, providers, auth) stays the published packages in `sdk`. scripts/emit-pi-durable-carrier.ts is the only writer of the generated fields (carrier blob, sha256, emitter.node); an installed package never reads source. Model data rides the published @earendil-works/pi-ai.",
+	"origin": {
+		"comment": "Frozen history, never an input: the upstream commit the owned source was first taken from, its objects as recorded then, the overlay patch that carried Entwurf's changes until it was folded into the source (#141), and the carrier bytes the last patch-built release shipped. Neither install nor emit reads this; `emit-pi-durable-carrier --origin <clone>` checks it as provenance only.",
+		"repository": "https://github.com/earendil-works/pi",
+		"tag": "v1.1.0",
+		"commit": "abe508e1b89912adde45528136c3221eb69acdd7",
+		"license": {
+			"path": "LICENSE",
+			"blob": "b0a8e9b81083294360c69b4ec45d3d39a2b28197"
+		},
+		"files": [
+			{
+				"path": "packages/coding-agent/src/experimental/durable/runtime.ts",
+				"blob": "fcd6e5239e999ebf17dea0335fb3dc9cd7f7ce45"
+			},
+			{
+				"path": "packages/coding-agent/src/experimental/durable/tui.ts",
+				"blob": "397b276cbeb1c90e1fbc96c3cc59e6a25f92dad7"
+			},
+			{
+				"path": "packages/coding-agent/src/experimental/durable/harness-setup.ts",
+				"blob": "4d6a4be5333ebb8e0f17eac1987f18ea35a91fc7"
+			},
+			{
+				"path": "packages/coding-agent/src/experimental/durable/prompt.ts",
+				"blob": "8e2f5d5273fba58da8b314766956ed62951c3814"
+			},
+			{
+				"path": "packages/coding-agent/src/experimental/durable/sessions.ts",
+				"blob": "34f9ceeeaeaf874f7478d56115da2e4f726c6a85"
+			},
+			{
+				"path": "packages/coding-agent/src/experimental/durable/subagent.ts",
+				"blob": "e767d54e0bf2908e0f4f41c6933b55c00562eb25"
+			}
+		],
+		"retiredOverlay": {
+			"name": "runtime-contacts.patch",
+			"sha256": "5b1bd9b48d4ff58ad223006d81cc12c4e0b18959cca5cda5ab3ad89f68bbe898"
+		},
+		"baselineCarrier": {
+			"release": "0.35.1",
+			"node": "v24.18.1",
+			"files": {
+				"runtime.js": "bfd88844fae61e8bd32d57b5b986f48056c64eebb5466d9826318a0783ac9005",
+				"tui.js": "f61cc68e5d32552a8196785093ae9e2f4a946088fe71582bb05690517db8c5b4",
+				"harness-setup.js": "712b630145dc6f5c655a85b01b1e20299c962542e63c5494d2202bb7bf414a15",
+				"prompt.js": "ff1ff765fa313e5cb1c3d7537c901c23adb0562ee433bd050fd35eb3d892134c",
+				"sessions.js": "1bd1a04ece66f5ab3ca22860c64dba9abc848334d11a27a9afe543f1365c7254",
+				"subagent.js": "8a75d934ef87efbb0bb2006a2141f1ea932560851f1718b991ed947d6efdb54c",
+				"LICENSE": "0457f5bcec3b3b211605dfb5d1a49042fd638f3686a410fe099c24a25af13c48"
+			}
+		}
+	},
 	"carrier": {
-		"comment": "files: the six app files bootstrap.mjs needs (main.ts is replaced by the bootstrap). distTargets: every pi-coding-agent internal the stripped files import, as paths under the published dist/; the emitter refuses a set that differs and the resolver answers no other.",
+		"comment": "files: the six app files bootstrap.mjs needs (main.ts is replaced by the bootstrap), each emitted from its owned `source`. distTargets: every pi-coding-agent internal the stripped files import, as paths under the published dist/; the emitter refuses a set that differs and the resolver answers no other.",
 		"emitter": {
 			"tool": "node:module.stripTypeScriptTypes",
 			"mode": "strip",
 			"node": "v24.18.1"
 		},
 		"license": {
-			"source": "LICENSE",
+			"source": "pi/pi-durable/src/LICENSE",
 			"blob": "b0a8e9b81083294360c69b4ec45d3d39a2b28197",
 			"sha256": "0457f5bcec3b3b211605dfb5d1a49042fd638f3686a410fe099c24a25af13c48"
 		},
 		"files": [
 			{
 				"name": "runtime.js",
-				"source": "packages/coding-agent/src/experimental/durable/runtime.ts",
-				"patched": true,
-				"blob": "fcd6e5239e999ebf17dea0335fb3dc9cd7f7ce45",
-				"sha256": "bfd88844fae61e8bd32d57b5b986f48056c64eebb5466d9826318a0783ac9005"
+				"source": "pi/pi-durable/src/experimental/durable/runtime.ts",
+				"blob": "36c352291620ab86184172a1b4a0df4562ab9581",
+				"sha256": "60c2965eadbdbbe78fce1b7eeb89d97eb3104a30b7d58ebca87009d2e9118403"
 			},
 			{
 				"name": "tui.js",
-				"source": "packages/coding-agent/src/experimental/durable/tui.ts",
-				"patched": true,
-				"blob": "397b276cbeb1c90e1fbc96c3cc59e6a25f92dad7",
-				"sha256": "f61cc68e5d32552a8196785093ae9e2f4a946088fe71582bb05690517db8c5b4"
+				"source": "pi/pi-durable/src/experimental/durable/tui.ts",
+				"blob": "dab99cd4778ae1db7f062e64db2d0c068f7e342d",
+				"sha256": "0f9ebaf8fbb2a532ccd1a7198e1a25533a99720b5fedbf03f42d5c381db3abc5"
 			},
 			{
 				"name": "harness-setup.js",
-				"source": "packages/coding-agent/src/experimental/durable/harness-setup.ts",
-				"patched": false,
+				"source": "pi/pi-durable/src/experimental/durable/harness-setup.ts",
 				"blob": "4d6a4be5333ebb8e0f17eac1987f18ea35a91fc7",
 				"sha256": "712b630145dc6f5c655a85b01b1e20299c962542e63c5494d2202bb7bf414a15"
 			},
 			{
 				"name": "prompt.js",
-				"source": "packages/coding-agent/src/experimental/durable/prompt.ts",
-				"patched": false,
+				"source": "pi/pi-durable/src/experimental/durable/prompt.ts",
 				"blob": "8e2f5d5273fba58da8b314766956ed62951c3814",
 				"sha256": "ff1ff765fa313e5cb1c3d7537c901c23adb0562ee433bd050fd35eb3d892134c"
 			},
 			{
 				"name": "sessions.js",
-				"source": "packages/coding-agent/src/experimental/durable/sessions.ts",
-				"patched": false,
+				"source": "pi/pi-durable/src/experimental/durable/sessions.ts",
 				"blob": "34f9ceeeaeaf874f7478d56115da2e4f726c6a85",
 				"sha256": "1bd1a04ece66f5ab3ca22860c64dba9abc848334d11a27a9afe543f1365c7254"
 			},
 			{
 				"name": "subagent.js",
-				"source": "packages/coding-agent/src/experimental/durable/subagent.ts",
-				"patched": false,
-				"blob": "e767d54e0bf2908e0f4f41c6933b55c00562eb25",
-				"sha256": "8a75d934ef87efbb0bb2006a2141f1ea932560851f1718b991ed947d6efdb54c"
+				"source": "pi/pi-durable/src/experimental/durable/subagent.ts",
+				"blob": "3fa9aebbe93e82cfff436e7b9d4c9877e0ed0e27",
+				"sha256": "1cb2390b673a0d914117bc07708c39b004fb10e48b31436bf9d9d2b953a64220"
 			}
 		],
 		"distTargets": [
@@ -89,17 +132,17 @@
 		]
 	},
 	"sdk": {
-		"comment": "The published library set the carrier runs against, derived from the 1.1.0 declarations. members: the @earendil-works packages the carrier imports and every @earendil-works package those declare. direct: a third-party package a carrier file imports itself (sessions.ts: proper-lockfile, at the version pi-coding-agent 1.1.0 pins). Each is an exact production dependency in package.json; the members' own edges are caret ranges, so the installed physical edges, not semver, are what must equal these versions.",
+		"comment": "The published library set the carrier runs against, derived from the 1.2.0 declarations. members: the @earendil-works packages the carrier imports and every @earendil-works package those declare. direct: a third-party package a carrier file imports itself (sessions.ts: proper-lockfile, at the version pi-coding-agent 1.2.0 pins). Each is an exact production dependency in package.json; the members' own edges are caret ranges, so the installed physical edges, not semver, are what must equal these versions.",
 		"members": {
-			"@earendil-works/chord": "1.1.0",
-			"@earendil-works/pi-agent-core": "1.1.0",
-			"@earendil-works/pi-ai": "1.1.0",
-			"@earendil-works/pi-codemode": "1.1.0",
-			"@earendil-works/pi-coding-agent": "1.1.0",
-			"@earendil-works/pi-durable": "1.1.0",
-			"@earendil-works/pi-mcp": "1.1.0",
-			"@earendil-works/pi-telemetry": "1.1.0",
-			"@earendil-works/pi-tui": "1.1.0"
+			"@earendil-works/chord": "1.2.0",
+			"@earendil-works/pi-agent-core": "1.2.0",
+			"@earendil-works/pi-ai": "1.2.0",
+			"@earendil-works/pi-codemode": "1.2.0",
+			"@earendil-works/pi-coding-agent": "1.2.0",
+			"@earendil-works/pi-durable": "1.2.0",
+			"@earendil-works/pi-mcp": "1.2.0",
+			"@earendil-works/pi-telemetry": "1.2.0",
+			"@earendil-works/pi-tui": "1.2.0"
 		},
 		"direct": {
 			"proper-lockfile": "4.1.2"

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

@@ -624,11 +624,12 @@ export async function codexFreshPreflight(
 	if (config === null || trustReceiptMissing(config, key)) return "codex-birth-trust-missing";
 	if (mcpMissing(config)) return "codex-mcp-hand-missing";
 	if (visibleIdentityMissing(config)) return "codex-visible-identity-missing";
-	const socketPath = resolveCodexDefaultSocketPath(env);
-	const socket = (deps.checkSocket ?? checkCodexSocketFile)(socketPath);
+	const socket = (deps.checkSocket ?? checkCodexSocketFile)(resolveCodexDefaultSocketPath(env));
 	if (!socket.ok) return "codex-app-server-unavailable";
+	// The protocol exchange goes to the endpoint the check verified, never the advertised path
+	// again (on Codex 0.162.1 that path is an alias; see `checkCodexSocketFile`).
 	const live = await appServerIsLive(
-		socketPath,
+		socket.connectPath,
 		deps.openProtocol ?? realCodexProtocolOpener,
 		deps.appServerTimeoutMs ?? DEFAULT_APP_SERVER_TIMEOUT_MS,
 	);

package/pi-extensions/lib/native-push/codex-ws-client.ts

@@ -23,30 +23,135 @@ export function resolveCodexDefaultSocketPath(env: CodexSocketEnv): string {
 	return path.join(resolveCodexHome(env), "app-server-control", "app-server-control.sock");
 }
 
-export type CodexSocketFileCheck = { ok: true } | { ok: false; status: "dead" | "indeterminate"; reason: string };
+/**
+ * What the advertised control-socket path is, and the one endpoint a caller may connect to.
+ *
+ * `connectPath` is a transport endpoint for one exchange: the socket this check verified. It is
+ * not an address, a record field or a replacement for `resolveCodexDefaultSocketPath`. `dead`
+ * names which absence it is, because the managed launcher treats them differently: an absent
+ * path is a first launch, and a dangling rendezvous alias is the leftover of a crashed server
+ * that the vendor removes on its next start.
+ */
+export type CodexSocketFileCheck =
+	| { ok: true; connectPath: string }
+	| { ok: false; status: "dead"; layout: "absent" | "dangling-alias"; reason: string }
+	| { ok: false; status: "indeterminate"; reason: string };
+
+/** Test seam only: the gate points these at a sandbox. Production callers pass nothing. */
+export interface CodexSocketFileDeps {
+	readonly daemonRoot?: string;
+	readonly euid?: number;
+}
 
-export function checkCodexSocketFile(socketPath: string): CodexSocketFileCheck {
+/**
+ * The advertised path is exactly one of two layouts, and anything else is refused.
+ *
+ * (A) A plain socket owned by the effective uid: Codex up to 0.153.4 binds the advertised
+ *     path itself. `connectPath` is that path.
+ * (B) Codex's rendezvous alias. From 0.162.1 the advertised path "is only an alias": the
+ *     server binds a 0600 socket under `realpath(/tmp)/codex-daemon-<euid>/` named by the
+ *     sha256 of the canonical advertised path, then symlinks the advertised path to it
+ *     (`[source]` rust-v0.162.1 `app-server-transport/src/transport/unix_socket.rs:43-131,
+ *     290-304`; `uds/src/daemon_directory.rs:1-38`). Upstream's reason is a privileged
+ *     rendezvous root that sandboxes hide; the alias also keeps an over-long advertised path
+ *     usable (`uds/src/lib.rs:167-174`). The alias is accepted only when every hop is the
+ *     vendor's own: the link is owned by the effective uid; its target is BYTE-EQUAL to the
+ *     path Codex derives (a relative, foreign, re-hashed or chained target is refused); the
+ *     daemon directory is a real directory owned by the effective uid with `mode & 0o777`
+ *     exactly 0700, the vendor's own rule; and the target is a socket owned by the effective
+ *     uid that no group or other user can open. `connectPath` is the verified target, so the
+ *     alias is never re-resolved between this check and the connect. A same-euid process can
+ *     still replace the verified socket file itself; that residual is named, not locked.
+ *
+ * Only `lstat` and one `readlink` touch the alias; it is never followed or `realpath`ed.
+ * The effective uid is the vendor's (`libc::geteuid`), not the real uid.
+ */
+export function checkCodexSocketFile(socketPath: string, deps: CodexSocketFileDeps = {}): CodexSocketFileCheck {
+	const euid = deps.euid ?? process.geteuid?.();
+	let stat: fs.Stats;
 	try {
-		const stat = fs.lstatSync(socketPath);
-		if (stat.isSymbolicLink()) {
-			return { ok: false, status: "indeterminate", reason: `app-server socket is a symlink: ${socketPath}` };
-		}
-		if (!stat.isSocket()) {
-			return { ok: false, status: "indeterminate", reason: `app-server path is not a socket: ${socketPath}` };
+		stat = fs.lstatSync(socketPath);
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") {
+			return { ok: false, status: "dead", layout: "absent", reason: `app-server socket is absent: ${socketPath}` };
 		}
-		if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+		return { ok: false, status: "indeterminate", reason: error instanceof Error ? error.message : String(error) };
+	}
+	if (stat.isSymbolicLink()) return checkCodexRendezvousAlias(socketPath, stat, euid, deps);
+	if (!stat.isSocket()) {
+		return { ok: false, status: "indeterminate", reason: `app-server path is not a socket: ${socketPath}` };
+	}
+	if (euid !== undefined && stat.uid !== euid) {
+		return {
+			ok: false,
+			status: "indeterminate",
+			reason: `app-server socket is owned by uid ${stat.uid}, not the effective uid ${euid}`,
+		};
+	}
+	return { ok: true, connectPath: socketPath };
+}
+
+function checkCodexRendezvousAlias(
+	socketPath: string,
+	link: fs.Stats,
+	euid: number | undefined,
+	deps: CodexSocketFileDeps,
+): CodexSocketFileCheck {
+	const refuse = (reason: string): CodexSocketFileCheck => ({ ok: false, status: "indeterminate", reason });
+	if (euid === undefined) {
+		return refuse(`app-server socket is a symlink and this platform has no effective uid to verify it: ${socketPath}`);
+	}
+	if (link.uid !== euid) {
+		return refuse(`app-server socket symlink is owned by uid ${link.uid}, not the effective uid ${euid}`);
+	}
+	let daemonRoot: string;
+	let expected: string;
+	let target: string;
+	try {
+		daemonRoot = deps.daemonRoot ?? path.join(fs.realpathSync("/tmp"), `codex-daemon-${euid}`);
+		const canonical = path.join(fs.realpathSync(path.dirname(socketPath)), path.basename(socketPath));
+		expected = path.join(daemonRoot, crypto.createHash("sha256").update(canonical).digest("hex"));
+		target = fs.readlinkSync(socketPath);
+	} catch (error) {
+		return refuse(
+			`could not verify the app-server socket symlink ${socketPath}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	if (target !== expected) {
+		return refuse(`app-server socket is a symlink that is not Codex's rendezvous alias: ${socketPath} -> ${target}`);
+	}
+	let directory: fs.Stats;
+	try {
+		directory = fs.lstatSync(daemonRoot);
+	} catch (error) {
+		return refuse(`Codex's socket directory cannot be read: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!directory.isDirectory() || directory.uid !== euid || (directory.mode & 0o777) !== 0o700) {
+		return refuse(
+			`Codex's socket directory ${daemonRoot} must be a real directory owned by uid ${euid} with mode 0700`,
+		);
+	}
+	let physical: fs.Stats;
+	try {
+		physical = fs.lstatSync(expected);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
 			return {
 				ok: false,
-				status: "indeterminate",
-				reason: `app-server socket is owned by uid ${stat.uid}, not ${process.getuid()}`,
+				status: "dead",
+				layout: "dangling-alias",
+				reason: `app-server socket is a dangling rendezvous alias: ${socketPath} -> ${expected}`,
 			};
 		}
-		return { ok: true };
-	} catch (error) {
-		const code = (error as NodeJS.ErrnoException).code;
-		if (code === "ENOENT") return { ok: false, status: "dead", reason: `app-server socket is absent: ${socketPath}` };
-		return { ok: false, status: "indeterminate", reason: error instanceof Error ? error.message : String(error) };
+		return refuse(error instanceof Error ? error.message : String(error));
 	}
+	if (!physical.isSocket() || physical.uid !== euid || (physical.mode & 0o077) !== 0) {
+		return refuse(
+			`Codex's physical socket ${expected} must be a socket owned by uid ${euid} that no group or other user can open`,
+		);
+	}
+	return { ok: true, connectPath: expected };
 }
 
 export interface CodexRpcProtocol {
@@ -315,6 +420,7 @@ async function initialize(protocol: CodexRpcProtocol): Promise<void> {
 
 export interface CodexRoute {
 	readonly backend: "codex";
+	/** The endpoint `checkCodexSocketFile` verified for this probe, which the send also uses. Not an address. */
 	readonly socketPath: string;
 }
 
@@ -359,9 +465,14 @@ export async function probeCodexThread(
 	nativeSessionId: string,
 	deps: CodexAdapterDeps = {},
 ): Promise<CodexProbeResult> {
-	const socketPath = resolveCodexDefaultSocketPath(deps.env ?? process.env);
-	const socketCheck = (deps.checkSocket ?? checkCodexSocketFile)(socketPath);
+	const socketCheck = (deps.checkSocket ?? checkCodexSocketFile)(
+		resolveCodexDefaultSocketPath(deps.env ?? process.env),
+	);
 	if (!socketCheck.ok) return { status: socketCheck.status, reason: socketCheck.reason };
+	// The probe, and the queue send its route carries, both use the endpoint just verified. The
+	// advertised path is not resolved again: on 0.162.1 it is an alias that could be retargeted
+	// between the check and a second transport.
+	const socketPath = socketCheck.connectPath;
 	let protocol: CodexRpcProtocol;
 	try {
 		protocol = await (deps.openProtocol ?? realCodexProtocolOpener).open(socketPath);

package/pi-extensions/lib/pi-durable-runtime.ts

@@ -3,9 +3,9 @@
  * under (#129 W, #130).
  *
  * The experimental durable app is source-only upstream: published `@earendil-works/pi-coding-agent`
- * ships no `dist/experimental`. Entwurf therefore ships the app itself as a CARRIER — the pinned
- * upstream files, type-stripped and relocated (pi/pi-durable/carrier/, emitted only by the
- * maintainer's scripts/emit-pi-durable-carrier.ts) — and declares the published SDK set it runs
+ * ships no `dist/experimental`. Entwurf therefore ships the app itself as a CARRIER — its owned
+ * source (pi/pi-durable/src, #141), type-stripped and relocated (pi/pi-durable/carrier/, emitted only
+ * by scripts/emit-pi-durable-carrier.ts) — and declares the published SDK set it runs
  * against as exact production dependencies. Nothing is provisioned beside the package: there is no
  * runtime directory, no source checkout and no model data to copy (it rides the published pi-ai).
  *
@@ -47,7 +47,7 @@ export type PiDurableRuntimeRejectReason =
 export interface PiDurablePackageLayout {
 	readonly root: string;
 	readonly overlayDir: string;
-	/** The emitted upstream app files and their license. */
+	/** The app files emitted from the owned source, and their license. */
 	readonly carrierDir: string;
 	/** The `--import` resolver the launcher runs the bootstrap under. */
 	readonly resolver: string;

package/pi-extensions/meta-bridge-pi-durable.ts

@@ -3,8 +3,9 @@
  *
  * WHAT THIS IS. The long-running durable app (`@earendil-works/pi-coding-agent`
  * `experimental/durable`, which upstream omits from its npm distribution — Entwurf's package
- * supplies it as a pinned carrier, #130, not as an operator prerequisite) owns its runtime, TUI,
- * models/auth, storage, prompt and recovery. This module is the whole Entwurf side of its contact:
+ * supplies it as a carrier emitted from its owned source, #130/#141, not as an operator
+ * prerequisite) owns its runtime, TUI, models/auth, storage, prompt and recovery. This module is
+ * the whole Entwurf side of its contact:
  *
  *   createPiDurableContact({ bridgeEntry })
  *     .extension          tools-only durable Extension, handed to the overlay's
@@ -49,14 +50,16 @@
  * bridge whose list differs: the callable bridge schema is the truth, the copy only has to agree.
  *
  * RECEIVE (self-fetch, announce-only). When the bootstrap hands `attach` the overlay's
- * `submitToRoot`, the contact arms a doorbell after the bridge is ready: mailbox, then signal,
+ * `submitToRoot` and `onFailed`, the contact arms a doorbell after the bridge is ready: mailbox, then signal,
  * then the watch, then a check that the record and this process's sender marker still name the
  * session, and only then the receiver marker. A fresh `.msg` is stamped `.msg.delivered` and
  * announced to the ROOT conversation as input; the body stays in the mailbox until the model
  * calls `entwurf_inbox_read`, which is the read receipt. The watch and the sender marker share
  * this process's pid, so the #101 owner join applies (`pi-durable-host`). A watch error, a
- * vanished signal, a failed ring, a rejected admission or close retires the doorbell — watch
- * closed, our own marker removed, the reason kept by name — and nothing retries it.
+ * vanished signal, a failed ring, a rejected admission, the session failing (at once, from the
+ * overlay's `onFailed`, not at the next ring — and before `attach` returns when it had already
+ * failed, with no receiver marker left behind) or close retires the doorbell — watch closed, our own
+ * marker removed, the reason kept by name — and nothing retries it.
  *
  * WITHDRAW (#140). Each notice is a native `followUp`, placed one per run; a read drains EVERY
  * unread body. So after a read the notices still queued for that mail would each cost a turn and an
@@ -295,9 +298,14 @@ export interface PiDurableRoots {
 // ---------------------------------------------------------------------------
 // Durable surface, typed NARROWLY and locally — read at pi-durable 1.0.2 @cd32f77 (#129,
 // `harness/types.ts`; historical coordinates, not re-anchored here). The current supply is the
-// carrier `pi/pi-durable/overlay/upstream-pin.json` names (1.1.0 at `abe508e`). `[read 2026-10-08]`
-// v1.0.4 → v1.1.0 `harness/types.ts` adds `models`, `contextRetentionMs` and a `context()` options
-// bag only; none of the shapes typed below moved.
+// carrier emitted from Entwurf's owned source (pi/pi-durable/src, #141) against the 1.2.0 SDK set
+// `pi/pi-durable/overlay/upstream-pin.json` names (origin `abe508e`). `[read 2026-10-13]` at
+// v1.2.0 one shape typed below moved: `ToolExecutionResult.content` is now `output`, beside the new
+// `structuredOutput` (`harness/types.ts`, its CHANGELOG's breaking changes). An omitted `output`
+// gives the model the text a tool retained through `api.output()`; `content` is not read, so a
+// result naming only `content` that retained no output reaches the model as nothing. The contact's
+// tools retain none, so they answer in `output`.
+// The submission draft, its `abort()` answers and the identity `define*` helpers did not move.
 // `defineExtension`/`defineTool` are identity functions (`harness/define.ts:6-17`), so a plain
 // object is the extension.
 // ---------------------------------------------------------------------------
@@ -314,8 +322,9 @@ export interface DurableCallContext {
 	readonly abortSignal?: AbortSignal;
 }
 
+/** `ToolExecutionResult`, narrowed: `output` is what the model reads. */
 export interface DurableToolResult {
-	content: { type: "text"; text: string }[];
+	output: { type: "text"; text: string }[];
 }
 
 export interface DurableTool {
@@ -562,14 +571,19 @@ export interface DurableAdmittedSubmission {
 /** The overlay's `OpenDurableResult.submitToRoot`. */
 export type DurableSubmitToRoot = (draft: DurableDoorbellDraft) => Promise<DurableAdmittedSubmission>;
 
+/** The overlay's `OpenDurableResult.onFailed`: one synchronous call when the session fails and closes itself. */
+export type DurableOnFailed = (listener: () => void) => () => void;
+
 /** What `attach` needs to arm the doorbell. Without it the citizen only sends. */
 export interface DurableRootAdmission {
 	submitToRoot: DurableSubmitToRoot;
+	onFailed: DurableOnFailed;
 }
 
 /** Why an armed doorbell was retired. Nothing re-arms it. */
 export type PiDurableReceiverRetirement =
 	| "closed"
+	| "session-failed"
 	| "watch-error"
 	| "signal-vanished"
 	| "doorbell-failed"
@@ -630,7 +644,7 @@ export interface PiDurableAttachment {
 	/** The roots written — and the roots the bridge child was bound to. */
 	roots: PiDurableRoots;
 	bridgePid: number | null;
-	/** The receiver marker this attach published, or null when no root admission was handed in. */
+	/** The receiver marker this attach published; null when no root admission was handed in, or the session had already failed. */
 	receiverMarkerPath: string | null;
 }
 
@@ -682,6 +696,7 @@ interface ArmedDoorbell {
 	markerPath: string;
 	watcher: fs.FSWatcher;
 	submitToRoot: DurableSubmitToRoot;
+	unsubscribeFailed: () => void;
 }
 
 /** One admitted notice: its native handle and the `.msg` names it announced. */
@@ -783,7 +798,7 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 			const call = () => client.callTool(name, (args ?? {}) as Record<string, unknown>, context?.abortSignal);
 			const result = name === "entwurf_inbox_read" ? await readInbox(call, context) : await call();
 			if (result.isError) throw new Error(result.text || `${name} failed`);
-			return { content: [{ type: "text", text: result.text }] };
+			return { output: [{ type: "text", text: result.text }] };
 		},
 	});
 
@@ -836,6 +851,7 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 		const armed = doorbell;
 		if (armed === null) return [];
 		doorbell = null;
+		armed.unsubscribeFailed();
 		const problems: string[] = [];
 		try {
 			armed.watcher.close();
@@ -985,15 +1001,16 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 	 * Mailbox, signal, watch — then the check that the record and this process's sender marker
 	 * still name the session — and only then the receiver marker, the one fact a sender reads.
 	 * Synchronous, so nothing can close the contact between the check and the publish. Throws,
-	 * after closing whatever it opened, when any step fails.
+	 * after closing whatever it opened, when any step fails. Returns null when the session had
+	 * already failed: the doorbell was retired as `session-failed` before this returned.
 	 */
 	const arm = (
 		gardenId: string,
 		nativeSessionId: string,
 		ownerPid: number,
 		roots: PiDurableRoots,
-		submitToRoot: DurableSubmitToRoot,
-	): string => {
+		root: DurableRootAdmission,
+	): string | null => {
 		if (ownerPid !== process.pid) {
 			throw new Error(
 				`the doorbell's watch lives in this process (${process.pid}); a receiver marker naming owner ${ownerPid} would advertise a watch that pid does not hold`,
@@ -1004,6 +1021,7 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 		fs.mkdirSync(mailbox, { recursive: true });
 		if (!fs.existsSync(signal)) fs.writeFileSync(signal, "", { mode: 0o600 });
 		const watcher = watch(signal, () => void ring("signal"));
+		let unsubscribeFailed = (): void => {};
 		try {
 			watcher.on("error", (error) => retire("watch-error", describeError(error)));
 			const identity = readAddressableMetaIdentity(gardenId, roots.sessionsDir);
@@ -1020,6 +1038,21 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 						: `the sender marker for owner ${ownerPid} names ${sender.gardenId}/${sender.nativeSessionId}, not ${gardenId}/${nativeSessionId}`,
 				);
 			}
+			// A failed session admits nothing: retire at once, so no sender reads a marker for a host that cannot wake.
+			// Subscribed before the marker is written, so a registration that throws leaves no marker. A session that
+			// failed before this arm says so during the subscription, before the doorbell exists: that is noted, and
+			// the retirement runs once the doorbell is published below. It is final; nothing re-arms.
+			let published = false;
+			let failedBeforePublished = false;
+			const sessionFailed = (): void => {
+				if (!published) {
+					failedBeforePublished = true;
+					return;
+				}
+				const problems = retire("session-failed", "the durable session failed and closed itself");
+				if (problems.length > 0) throw new Error(`the doorbell did not retire cleanly: ${problems.join("; ")}`);
+			};
+			unsubscribeFailed = root.onFailed(sessionFailed);
 			const markerPath = writeMetaReceiverMarker({
 				gardenId,
 				backend: PI_DURABLE_BACKEND,
@@ -1029,17 +1062,37 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				armProvenance: "session-start",
 				receiversDir: roots.receiversDir,
 			});
-			doorbell = { gardenId, ownerPid, mailbox, signal, markerPath, watcher, submitToRoot };
+			doorbell = {
+				gardenId,
+				ownerPid,
+				mailbox,
+				signal,
+				markerPath,
+				watcher,
+				submitToRoot: root.submitToRoot,
+				unsubscribeFailed,
+			};
 			inbox = mailbox;
 			report = { status: "armed", gardenId, markerPath, admissions };
+			published = true;
+			if (failedBeforePublished) {
+				sessionFailed();
+				return null;
+			}
 			return markerPath;
 		} catch (error) {
-			try {
-				watcher.close();
-			} catch (closeError) {
+			const cleanup: unknown[] = [];
+			for (const step of [unsubscribeFailed, () => watcher.close()]) {
+				try {
+					step();
+				} catch (cleanupError) {
+					cleanup.push(cleanupError);
+				}
+			}
+			if (cleanup.length > 0) {
 				throw new AggregateError(
-					[error, closeError],
-					`${describeError(error)} (cleanup also failed: ${describeError(closeError)})`,
+					[error, ...cleanup],
+					`${describeError(error)} (cleanup also failed: ${cleanup.map(describeError).join("; ")})`,
 				);
 			}
 			throw error;
@@ -1068,6 +1121,9 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				if (root !== undefined && typeof root.submitToRoot !== "function") {
 					throw new Error("the root admission handed to attach has no submitToRoot function");
 				}
+				if (root !== undefined && typeof root.onFailed !== "function") {
+					throw new Error("the root admission handed to attach has no onFailed function");
+				}
 				const ownerPid = options.ownerPid ?? process.pid;
 				const sendersDir = path.resolve(options.sendersDir ?? defaultMetaSendersDir());
 				const upsert = upsertMetaSession({
@@ -1119,7 +1175,7 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				let receiverMarkerPath: string | null = null;
 				if (root !== undefined) {
 					try {
-						receiverMarkerPath = arm(gardenId, id, ownerPid, roots, root.submitToRoot);
+						receiverMarkerPath = arm(gardenId, id, ownerPid, roots, root);
 					} catch (error) {
 						return await failAfterCleanup(new Error(`the doorbell did not arm: ${describeError(error)}`), () =>
 							client.close(),