@junghanacs/entwurf 0.15.1 → 0.16.1

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

@@ -119,7 +119,13 @@ export interface AcpChildLike {
 	signalCode: NodeJS.Signals | null;
 	stdin: { destroy(): void; unref?(): void };
 	stdout: { destroy(): void; unref?(): void };
-	stderr: { on(event: "data", listener: (chunk: Buffer) => void): void; destroy(): void; unref?(): void };
+	stderr: {
+		on(event: "data", listener: (chunk: Buffer) => void): void;
+		/** Optional: absent on minimal fakes; the flush is best-effort, never load-bearing for liveness. */
+		once?(event: "close", listener: () => void): void;
+		destroy(): void;
+		unref?(): void;
+	};
 	kill(signal?: NodeJS.Signals | number): boolean;
 	unref(): void;
 	once(event: "exit" | "error", listener: (...args: unknown[]) => void): void;
@@ -210,6 +216,11 @@ interface BridgeSession {
 	 * nothing to diagnose it by (observed 2026-07-30 on a live sonnet reuse turn).
 	 */
 	stderrTail: string[];
+	/**
+	 * SESSION-scoped like `stderrTail`, and for the same reason: the launcher's
+	 * frame can arrive on a turn later than the one that spawned the child.
+	 */
+	launchObservation: AcpLaunchObservation;
 	/** How the child ended, once it has — folded into the prompt-phase error. */
 	exit?: { code: number | null; signal: NodeJS.Signals | null };
 	/**
@@ -367,6 +378,85 @@ const CHILD_END_SETTLE_MS = 500;
  */
 const ACP_CONNECTION_CLOSED_TEXT = "ACP connection closed";
 
+/**
+ * The launcher's control frame — see `claude-acp-launch.js`.
+ *
+ * Matched as an EXACT FULL LINE and nothing else. The vendor writes prose that
+ * mentions signals; a substring test would let vendor text manufacture an
+ * entwurf observation, which is precisely the confusion #72 cost three
+ * diagnosis passes. Our own frame is a fixed enum, so exact-line matching is
+ * sufficient AND necessary.
+ */
+const LAUNCH_SIGNAL_FRAME_PREFIX = "ENTWURF_ACP_LAUNCH_SIGNAL=";
+const LAUNCH_SIGNAL_FRAME_VALUES: ReadonlySet<string> = new Set(["SIGTERM", "SIGINT"]);
+
+/** A mutable, session-scoped record of a terminating signal the LAUNCHER caught. */
+export type AcpLaunchObservation = { signal?: "SIGTERM" | "SIGINT" };
+
+/**
+ * Split a stderr chunk stream into lines, consuming our own frames and passing
+ * everything else through to the tail untouched.
+ *
+ * Line-buffered because a chunk boundary can fall inside a frame; the trailing
+ * partial line is held, not emitted, so a frame split across two reads is still
+ * recognised exactly.
+ */
+function makeLaunchFrameFilter(observation: AcpLaunchObservation, onText: (text: string) => void) {
+	let held = "";
+	return {
+		write(chunk: string): void {
+			held += chunk;
+			let nl = held.indexOf("\n");
+			let passed = "";
+			while (nl !== -1) {
+				const line = held.slice(0, nl);
+				if (
+					line.startsWith(LAUNCH_SIGNAL_FRAME_PREFIX) &&
+					LAUNCH_SIGNAL_FRAME_VALUES.has(line.slice(LAUNCH_SIGNAL_FRAME_PREFIX.length))
+				) {
+					// FIRST caught signal wins: a later one is our own teardown racing
+					// the external kill, and reporting that would bury the cause.
+					observation.signal ??= line.slice(LAUNCH_SIGNAL_FRAME_PREFIX.length) as "SIGTERM" | "SIGINT";
+				} else {
+					passed += `${line}\n`;
+				}
+				held = held.slice(nl + 1);
+				nl = held.indexOf("\n");
+			}
+			if (passed) onText(passed);
+		},
+		/**
+		 * The child's LAST words may arrive without a trailing newline — a process
+		 * dying mid-write is exactly when that happens, and it is exactly when the
+		 * tail matters most. Line buffering would otherwise hold that fragment
+		 * forever, so the stream's close flushes it VERBATIM.
+		 *
+		 * No frame check here, deliberately: the launcher writes its frame with a
+		 * single `writeSync` including the newline, well under PIPE_BUF, so a
+		 * complete frame can never be the un-terminated remainder. Anything left
+		 * without a newline is vendor text by construction.
+		 */
+		flush(): void {
+			if (!held) return;
+			onText(held);
+			held = "";
+		},
+	};
+}
+
+/**
+ * What the operator is told about a caught signal — and what they are NOT told.
+ *
+ * Absence is reported as "not observed", never as "no signal": the launcher can
+ * only see what reached it, and an override launch (`CLAUDE_AGENT_ACP_COMMAND`)
+ * has no launcher at all. Attribution of the SENDER is not claimed here either —
+ * that needs the host's journal, which this process cannot read.
+ */
+function launchSignalLine(observation: AcpLaunchObservation | undefined): string | undefined {
+	if (!observation?.signal) return undefined;
+	return `[acp] launch observed ${observation.signal} before child exit (sender not attributed)`;
+}
+
 function isAcpConnectionClosure(err: unknown): boolean {
 	const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
 	return message.trim() === ACP_CONNECTION_CLOSED_TEXT;
@@ -921,14 +1011,24 @@ export function streamAcpTurn(
 		stream.end();
 	}
 
-	function finishError(err: unknown, aborted: boolean, stderrTail?: string[], lifecycle?: string): void {
+	function finishError(
+		err: unknown,
+		aborted: boolean,
+		stderrTail?: string[],
+		lifecycle?: string,
+		launchObservation?: AcpLaunchObservation,
+	): 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.
-		const diagnosed = lifecycle ? `${base}\n${lifecycle}` : base;
+		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.
+		const observed = launchSignalLine(launchObservation);
+		const diagnosed = observed ? `${withLifecycle}\n${observed}` : withLifecycle;
 		const tail = (stderrTail ?? []).join("").trim().slice(-1_000);
 		const full = tail ? `${diagnosed}\n--- backend stderr (tail) ---\n${tail}` : diagnosed;
 		// A-c: a real failure (not an abort) that looks like a context-window
@@ -1124,6 +1224,8 @@ export function streamAcpTurn(
 		/** Which phase a failure belongs to — flipped once the prompt is on the wire. */
 		let phase: "pre-prompt" | "prompt" = "pre-prompt";
 		const stderrTail: string[] = [];
+		// Session-scoped alongside the tail — see the field's note on the session type.
+		const launchObservation: AcpLaunchObservation = {};
 		const sessionKey = resolveSessionKey(opts, cwd);
 		try {
 			if (signal?.aborted) throw new Error("aborted before launch");
@@ -1156,10 +1258,18 @@ export function streamAcpTurn(
 			const spawned = child;
 
 			// Drain stderr (an unconsumed pipe can backpressure-deadlock a long turn).
-			spawned.stderr.on("data", (c: Buffer) => {
-				stderrTail.push(c.toString());
+			// The launcher's own control frames are consumed here and kept OUT of the
+			// tail: the tail is vendor evidence, the observation is an entwurf fact,
+			// and mixing the two is the overloading #72 was made of.
+			const consumeStderr = makeLaunchFrameFilter(launchObservation, (text) => {
+				stderrTail.push(text);
 				if (stderrTail.length > 50) stderrTail.shift();
 			});
+			spawned.stderr.on("data", (c: Buffer) => consumeStderr.write(c.toString()));
+			// `close` rather than `end`: it covers the destroy path our own teardown
+			// takes, and on the EOF-first death it lands inside the post-mortem
+			// settle window, so the flushed fragment is in the tail before we seal.
+			spawned.stderr.once?.("close", () => consumeStderr.flush());
 
 			// Abort during BOOTSTRAP (spawn → initialize → newSession → set-model):
 			// there is no prompt turn for the agent to cancel yet, so the child is
@@ -1211,6 +1321,8 @@ export function streamAcpTurn(
 				// this turn with the session, so a later reuse turn can still report
 				// the child's dying words.
 				stderrTail,
+				// SAME object the frame filter writes into, for the same reason.
+				launchObservation,
 				// Armed at spawn, before ANY turn can fail on this child — the latch
 				// must already exist when the `exit` listener below can fire.
 				childEnd: makeChildEndLatch(),
@@ -1345,7 +1457,13 @@ export function streamAcpTurn(
 			// own SIGTERM; the tail collected by then is sealed before our cleanup
 			// touches the stderr pipe.
 			const lifecycle = await diagnoseTransportClosure({ err, session, phase, aborted });
-			finishError(err, aborted, session?.stderrTail ?? stderrTail, lifecycle);
+			finishError(
+				err,
+				aborted,
+				session?.stderrTail ?? stderrTail,
+				lifecycle,
+				session?.launchObservation ?? launchObservation,
+			);
 			// error/abort → drop the (uncertain) session and close its child; an
 			// uncertain connection must never be reused (GPT ④).
 			if (child) {
@@ -1412,7 +1530,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);
+			finishError(err, aborted, session.stderrTail, lifecycle, session.launchObservation);
 			// error/abort on a reused session → drop it and close the child (GPT ④).
 			session.retiring = true;
 			retainedChildren.delete(session.child);

package/pi-extensions/lib/acp/claude-acp-launch.js

@@ -0,0 +1,100 @@
+// entwurf-owned launcher for the Claude ACP backend (#72).
+//
+// WHY THIS FILE EXISTS — it is not a wrapper for its own sake.
+//
+// The vendor bin is named `claude-agent-acp`, and that name is not ours: any
+// harness on the host that spawns the same package produces a process with the
+// same name. On GLG's oracle host a janitor installed for a DIFFERENT harness
+// (openclaw's acpx, upstream PR #245) selects `claude-agent-acp` by argv
+// SUBSTRING and SIGTERMs anything older than 900s. entwurf's child is retained
+// across turns, so its age is the age of the SESSION, not of a turn — every
+// session older than 15 minutes was shot at every 5 minutes. Measured: 12 of 12
+// anomalous terminations across two boots, pid- and timestamp-locked (receipts
+// in `scripts/raw-acp-child-exit-measure/README.md` §ANSWERED).
+//
+// So this launcher does two things, and deliberately nothing else:
+//
+//   1. NAMESPACE. It carries a name that is ours, so a name-matching janitor
+//      stops selecting our process. The vendor is `import`ed INTO this same
+//      process — not spawned as a child. That distinction is what keeps this
+//      inside #72's repair fence: with no child to restart, this cannot become
+//      the supervisor/watcher/retry the issue forbids. Any variant that spawns
+//      the vendor breaks the fence and must not be written.
+//
+//   2. OBSERVE A CAUGHT SIGNAL. The vendor's own handler turns SIGTERM/SIGINT
+//      into `dispose(); process.exit(0)`, so by the time entwurf sees the child
+//      end there is an exit code 0 and NO signal — a clean external kill and a
+//      vendor fault are indistinguishable. Registering first lets us record
+//      that a terminating signal was caught, before the vendor erases it.
+//
+// WHAT THIS COSTS, STATED SO NOBODY DISCOVERS IT LATER. Once the name split is
+// in place, a host janitor that scans for the vendor name can no longer see
+// entwurf's children AT ALL — including ones that genuinely leaked. If pi is
+// SIGKILLed so `teardownChild` never runs, this adapter reparents to PID 1 and
+// matches neither that janitor's name phase nor its orphan phase (which looks
+// for a bare `claude`). That leak class now belongs to entwurf: after the split,
+// we own our own cleanup story and cannot expect someone else's timer to cover
+// it. This is a deliberate trade — being killed mid-turn is worse than leaking
+// a process on an abnormal exit — but it is a trade, not a free win.
+//
+// ARGV IS NOT OURS TO TOUCH. The vendor reads `--cli` / `--version` /
+// `--hide-claude-auth` from `process.argv`, and builds its own re-invocation
+// command from `process.argv.slice(1)` for the terminal-auth advert. Under this
+// launcher that advert becomes `node <this file> --cli auth login …`, which
+// keeps working ONLY because we consume no flags and resolve the vendor
+// ourselves. Never give this file an option of its own.
+
+import { readFileSync, writeSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * The one line entwurf's stderr drain looks for, matched as an EXACT full line.
+ * A fixed enum, never interpolated from vendor text: the backend must be unable
+ * to mistake vendor prose (which mentions signals) for our own observation.
+ */
+const SIGNAL_FRAME_PREFIX = "ENTWURF_ACP_LAUNCH_SIGNAL=";
+
+/** Signals the vendor normalizes to exit 0, and which are therefore invisible downstream. */
+const OBSERVED_SIGNALS = /** @type {const} */ (["SIGTERM", "SIGINT"]);
+
+for (const signal of OBSERVED_SIGNALS) {
+	process.on(signal, () => {
+		// writeSync, not console.error: a handler may run while the process is
+		// tearing down and an async write can be dropped.
+		try {
+			writeSync(2, `${SIGNAL_FRAME_PREFIX}${signal}\n`);
+		} catch {
+			// stderr already gone — the observation is best-effort, never fatal.
+		}
+		// THE SINK GUARD. Registering a handler SUPPRESSES node's default
+		// termination. If we are still the only listener — the vendor has not
+		// registered yet, or its import failed — this observer would make the
+		// process immune to the very signal it is observing, including entwurf's
+		// own teardown SIGTERM. Stand down and let the signal land for real.
+		if (process.listenerCount(signal) === 1) {
+			process.removeAllListeners(signal);
+			process.kill(process.pid, signal);
+		}
+	});
+}
+
+// Resolution lives INSIDE the same try as the import so both failures speak with
+// one voice: a missing package and a broken package are the same event to an
+// operator reading stderr, and only one of them would otherwise be legible.
+try {
+	const require = createRequire(import.meta.url);
+	const pkgJsonPath = require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
+	const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+	const binPath = typeof pkgJson.bin === "string" ? pkgJson.bin : pkgJson.bin?.["claude-agent-acp"];
+	if (!binPath) throw new Error("@agentclientprotocol/claude-agent-acp resolved but exposes no bin entry");
+	// Same process, no argv touched. The vendor bin has no main-module guard, so
+	// importing it starts the agent exactly as executing it would.
+	await import(pathToFileURL(join(dirname(pkgJsonPath), binPath)).href);
+} catch (err) {
+	// Fail loud and DIE. No retry, no fallback: a launcher that survives its own
+	// failure is the hidden supervisor #72 forbids.
+	writeSync(2, `entwurf acp launcher: vendor import failed: ${err instanceof Error ? err.stack : String(err)}\n`);
+	process.exit(1);
+}

package/pi-extensions/lib/entwurf-self-address.ts

@@ -33,10 +33,13 @@
  *  - external-mcp: never replyable — no authoritative reply address.
  *
  * `origin` stays sender-carrier PROVENANCE, never the citizen identity authority and never a rail.
- * Which rail a meta citizen's reply rides is a SECOND axis — `metaDeliveryDomain`, derived
- * by the caller from `nativePushSupported(backend)`, not from `wakeMode` (direct-inject also
- * covers codex/pi, which have no native-push adapter). Fail-closed: an unsupplied domain is
- * not replyable.
+ * Which rail a meta citizen's reply rides is a SECOND axis — `metaDeliveryDomain`.
+ * The caller derives it as three values, never as a native-push-or-self-fetch binary:
+ *   native-push  ← `nativePushSupported(backend)` (the adapter list; NOT wakeMode —
+ *                  `direct-inject` also covers codex/pi, which have no native-push adapter)
+ *   self-fetch   ← `resolveMailboxWakeModeCapability` (the decider's own mailbox seam)
+ *   none         ← neither (omp today: no mailbox drain, no native-push adapter)
+ * Fail-closed: an unsupplied domain is not replyable.
  */
 
 import { computeMetaReceiverActive, nativePushDeliverable } from "./entwurf-deliverability.ts";
@@ -44,7 +47,7 @@ import { computeMetaReceiverActive, nativePushDeliverable } from "./entwurf-deli
 export type SelfOrigin = "pi-session" | "meta-session" | "external-mcp";
 
 /** Which delivery rail carries a reply back to a meta citizen (the second axis, never `origin`). */
-export type MetaDeliveryDomain = "self-fetch" | "native-push";
+export type MetaDeliveryDomain = "self-fetch" | "native-push" | "none";
 
 /**
  * pi control-socket reachability for a reply addressed back to this session.
@@ -108,9 +111,11 @@ export function computeSelfAddressability(facts: SelfAddressabilityFacts): SelfA
 			};
 		}
 		case "meta-session": {
-			// TWO rails, pinned apart (보정①). Each branch composes the predicate that OWNS its
+			// THREE rails, pinned apart (보정①). Each branch composes the predicate that OWNS its
 			// axis — the mailbox receiver atom and the native-push predicate share nothing, so a
-			// mailbox liveness fact can never leak into a backend that has no mailbox.
+			// mailbox liveness fact can never leak into a backend that has no mailbox. `none` is
+			// the remainder: no inbound rail at all (not an unsupplied domain — that stays the
+			// default fail-closed row).
 			switch (facts.metaDeliveryDomain) {
 				case "native-push": {
 					const push = nativePushDeliverable({ recordBacked: facts.recordBacked, probeAlive: facts.probeAlive });
@@ -136,6 +141,12 @@ export function computeSelfAddressability(facts: SelfAddressabilityFacts): SelfA
 						reason: recv.active ? `meta receiver active (${recv.reason})` : `meta receiver inactive — ${recv.reason}`,
 					};
 				}
+				case "none":
+					return {
+						replyable: false,
+						socketState: "none",
+						reason: "no inbound rail — this backend has no mailbox and no native-push adapter",
+					};
 				default:
 					return {
 						replyable: false,

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

@@ -57,7 +57,7 @@ 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"];
+export const META_SENDER_BACKENDS: readonly MetaBackend[] = ["claude-code", "antigravity", "copilot", "omp"];
 
 /** 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"] as const;
+export const META_BACKENDS = ["claude-code", "antigravity", "codex", "copilot", "omp"] as const;
 export type MetaBackend = (typeof META_BACKENDS)[number];
 
 /**
@@ -170,6 +170,58 @@ export const META_BACKEND_DESCRIPTORS: Record<MetaBackend, MetaBackendDescriptor
 		deliveryLevel: "D6",
 		nativeIdLabel: "sessionId",
 	},
+	// SELF-FETCH citizen since #87 bundle B (oh-my-pi v18.0.0). An omp "hook" is an
+	// in-process EXTENSION (`--hook` aliases `--extension`), so BOTH units run inside the
+	// omp host: the birth unit mints on `session_start`/`session_switch`, and the receiver
+	// unit arms a mailbox watch in the same process and rings the doorbell.
+	//   self-fetch  The doorbell announces and the model drains its own inbox with
+	//             `entwurf_inbox_read` — that read is the receipt, and the notice never
+	//             carries the body. `[LIVE 2026-08-30, oracle, omp 18.0.0]` the vendor's
+	//             own wake surface was measured rather than inherited:
+	//             `pi.sendUserMessage(text,{deliverAs:"user"})` (on the FACTORY object, not
+	//             the event ctx) called on an IDLE tui session with zero typing started a
+	//             real turn — `agent_start` +31ms, `turn_start` +64ms, `turn_end` +2.45s,
+	//             model reply in the transcript. It was `direct-inject` while no process
+	//             held a watch; that label was the honest "not a drainable mailbox" bucket,
+	//             and it stopped being true when the receiver unit landed.
+	//             Replyability is still a fact about a LIVE marker, never a constant of this
+	//             backend: with no armed receiver every dispatch is refused
+	//             `mailbox-undeliverable`, which is exactly what an omp host with the birth
+	//             unit and no receiver unit still gets.
+	//   D6        the PRODUCT grade, earned by the LIVE roundtrip of 2026-08-30 on oracle
+	//             (omp 18.0.0). The code landing was NOT the evidence — this number moved
+	//             when the receipt did (`adding-a-harness.md` step 8(c)):
+	//             garden `20260830T140819-116f6a`, `lastEnqueuedAt 05:08:20.555Z` /
+	//             `lastReadAt 05:08:23.958Z`, doorbell rung on an idle session with zero
+	//             typing, and the citizen's OWN transcript carrying
+	//             `mcp__entwurf_bridge_entwurf_inbox_read` for its own garden id — the join
+	//             that makes the drain a fact about THAT session rather than about the clock.
+	//             D3 is PROVEN here rather than pending: with two live omp citizens armed
+	//             (pids 3154765 / 3154835) a single addressed enqueue rang exactly one
+	//             doorbell, and the sibling persisted no transcript and kept an empty
+	//             mailbox. That is the cell the Copilot row still lists as PENDING.
+	//             D7 is PARTIAL, deliberately: `lastReadAt` is observable without scraping,
+	//             but the reply itself is only visible in the transcript, and no completion
+	//             taxonomy or long-haul operation was measured.
+	//             D8 is PARTIAL: fresh-only ring (dedupe), `/new` unarm, watch-error unarm,
+	//             vanished-signal unarm and the identity-guarded teardown are implemented and
+	//             pinned hermetically by `check-omp-receive-arm`; ordering under load, loop
+	//             guards and crash recovery are not measured.
+	//             Replyability stays a fact about a LIVE marker: with no armed receiver every
+	//             dispatch is still refused `mailbox-undeliverable` — re-proved on the same
+	//             day against a garden id whose session had just been replaced by `/new`.
+	//   sessionId the native join key: `ReadonlySessionManager.getSessionId()`
+	//             (`session-manager.ts:1946-1948`), a UUIDv7 minted at
+	//             `mintSessionId()` `:95-97` — NOT the transcript filename, which is
+	//             `<iso>_<uuidv7>.jsonl` (`:1134-1137`). Measured LIVE 2026-08-27:
+	//             host `01a042da-537a-7770-a275-7b8162eecca4`
+	//             (`scripts/raw-omp-measure/README.md` M1).
+	omp: {
+		backend: "omp",
+		wakeMode: "self-fetch",
+		deliveryLevel: "D6",
+		nativeIdLabel: "sessionId",
+	},
 };
 
 // ---------------------------------------------------------------------------
@@ -253,7 +305,7 @@ 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", "pi"] as const;
+export const META_CITIZEN_BACKENDS = ["claude-code", "antigravity", "codex", "copilot", "omp", "pi"] as const;
 export type MetaCitizenBackend = (typeof META_CITIZEN_BACKENDS)[number];
 
 /**
@@ -1234,12 +1286,16 @@ export function decideUpsert(
 // stays strip-types clean (see module header for why this is not a sibling file).
 // ---------------------------------------------------------------------------
 
-function expandTilde(p: string): string {
-	if (p === "~") return os.homedir();
-	if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+function expandTildeIn(p: string, home: string): string {
+	if (p === "~") return home;
+	if (p.startsWith("~/")) return path.join(home, p.slice(2));
 	return p;
 }
 
+function expandTilde(p: string): string {
+	return expandTildeIn(p, os.homedir());
+}
+
 /**
  * The pi agent dir — the persistence root pi owns. `PI_CODING_AGENT_DIR` lets an
  * isolated install / test relocate it (symmetric with how pi's own sessions
@@ -1320,6 +1376,164 @@ export function defaultMetaReceiversDir(): string {
 	return path.join(piAgentDir(), "meta-receivers");
 }
 
+// ---------------------------------------------------------------------------
+// OMP meta-root policy (#87 B1) — ADDITIVE, and only for backend `omp`.
+//
+// THE COLLISION THIS CLOSES. `PI_CODING_AGENT_DIR` has two owners. To entwurf it
+// means "pi's persistence root", and `piAgentDir()` above derives all four garden
+// roots from it. To the OMP vendor it means "my agent dir": `setProfile` exports it
+// in-process for every named profile (`oh-my-pi` v18.0.0 `packages/utils/src/dirs.ts:452-473`,
+// reached from `cli.ts:342-360`), so a plain `omp --profile work` sets it. An OMP
+// birth that resolved its roots through `piAgentDir()` would therefore mint its record
+// and marker into a DIFFERENT garden store — and if the value came from a pi sandbox,
+// into that sandbox. Record-authority violation (Hard Rules 2 and 7), reachable on an
+// ordinary vendor workflow rather than an exotic one.
+//
+// WHY A BUNDLE OF FOUR AND NOT TWO. Splitting mailbox from receivers is the dangerous
+// cell: dispatch can trust an armed receiver marker in one root and enqueue into the
+// mailbox of the other while the real watcher drains the first — FALSE DELIVERABILITY.
+// So the four move together or not at all. Birth (bundle A) writes only sessions and
+// senders; receive (bundle B) consumes mailbox and receivers from this same object.
+//
+// WHAT IT DELIBERATELY DOES NOT DO. It does not change `piAgentDir()` or any
+// `defaultMeta*Dir()` — every existing backend keeps byte-identical behaviour, and pi's
+// own sandboxing still relocates through `PI_CODING_AGENT_DIR`. It honours the four
+// entwurf-owned `ENTWURF_META_*_DIR` overrides INDEPENDENTLY, so Hard Rule 12 sandboxing
+// stays usable. It bakes no absolute path into any record, marker, install-state or MCP
+// entry, and it introduces no new authority carrier: the roots are computed, never stored.
+// ---------------------------------------------------------------------------
+
+/** The four Entwurf-owned meta roots, resolved as ONE indivisible bundle. */
+export interface MetaRootBundle {
+	sessionsDir: string;
+	mailboxDir: string;
+	sendersDir: string;
+	receiversDir: string;
+}
+
+/** The env shape these pure resolvers read. `process.env` satisfies it. */
+export type MetaRootEnv = Record<string, string | undefined>;
+
+/**
+ * The exact provenance label the omp-native MCP entry carries
+ * (`scripts/omp-mcp-config.py` `EXTERNAL_AGENT_ID`). It is what lets a bridge CHILD know
+ * it is an OMP child — the same string both sides pin, never re-spelled.
+ */
+export const OMP_BRIDGE_PROVENANCE_LABEL = "external-mcp/omp";
+
+/** `HOME` as the process that owns this env sees it; `os.homedir()` returns exactly this
+ * on POSIX when HOME is set, so a real process and a composed child env agree. */
+function metaRootHome(env: MetaRootEnv): string {
+	const home = env.HOME;
+	return home !== undefined && home.length > 0 ? home : os.homedir();
+}
+
+/**
+ * THE shared OMP root policy — one pure function, two consumers (the in-process birth
+ * extension and the OMP-labeled bridge child). Agreement is by CONSTRUCTION, not by two
+ * places computing the same thing: both read this leaf, and both see the same HOME and the
+ * same four overrides because the vendor composes the child env as parent + entry env
+ * (`oh-my-pi` `packages/coding-agent/src/mcp/transports/stdio.ts:575-607`) and that entry
+ * env is provenance-only.
+ */
+export class MetaRootPolicyError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "MetaRootPolicyError";
+	}
+}
+
+/**
+ * The unambiguous base the OMP bundle hangs off when no override is set. Separate from
+ * {@link ompMetaRoots} because it must NEVER throw: the hook log is a diagnostic, and a
+ * policy refusal still has to be visible somewhere.
+ */
+export function ompMetaRootBase(env: MetaRootEnv = process.env, home: string = metaRootHome(env)): string {
+	// NEVER `piAgentDir()` here: for backend omp that variable is the VENDOR's agent dir.
+	return path.join(home, ".pi", "agent");
+}
+
+/**
+ * THE OVERRIDE GRAMMAR IS NARROW ON PURPOSE: absolute, or `~` / `~/…`. Anything else —
+ * a relative path, or `~user` — is a NAMED REFUSAL, not a resolution.
+ *
+ * Why fail closed rather than resolve: this bundle has to mean the same thing in two
+ * processes that do not share a working directory. `path.resolve` on a relative value
+ * silently makes CWD an authority, and the OMP extension's cwd is whatever the operator
+ * launched omp from while the doctor's is the repository (`run_ts` cd's there). `[측정]`
+ * the same `ENTWURF_META_SESSIONS_DIR=relative-records` resolved to two different stores
+ * that way, so the doctor could report NOT-YET off an empty directory while the extension's
+ * real store held records (#87 A2, Terra review). Refusing is what keeps cwd from becoming
+ * a garden-root carrier. `~` is allowed because it expands from HOME, which both halves
+ * share by construction.
+ *
+ * The refusal is shared: extension and OMP-labeled bridge child both reach it through this
+ * one leaf, so neither can proceed on a value the other would read differently.
+ */
+export function ompMetaRoots(env: MetaRootEnv = process.env, home: string = metaRootHome(env)): MetaRootBundle {
+	const base = ompMetaRootBase(env, home);
+	const surface = (key: string, leaf: string): string => {
+		const override = env[key];
+		if (override === undefined || override === "") return path.join(base, leaf);
+		if (override === "~" || override.startsWith("~/")) return path.resolve(expandTildeIn(override, home));
+		if (path.isAbsolute(override)) return path.resolve(override);
+		throw new MetaRootPolicyError(
+			`omp meta-root policy refuses ${key}=${JSON.stringify(override)}: a garden root must be absolute or ~-rooted ` +
+				"(`~` or `~/…`). A relative value would resolve against each process's own working directory, and the omp " +
+				"extension and its doctor do not share one — set an absolute path, or unset it to use the default under HOME.",
+		);
+	};
+	return {
+		sessionsDir: surface("ENTWURF_META_SESSIONS_DIR", "meta-sessions"),
+		mailboxDir: surface("ENTWURF_META_MAILBOX_DIR", "meta-mailbox"),
+		sendersDir: surface("ENTWURF_META_SENDERS_DIR", "meta-senders"),
+		receiversDir: surface("ENTWURF_META_RECEIVERS_DIR", "meta-receivers"),
+	};
+}
+
+/**
+ * The bridge CHILD half of the same policy, applied to that child's own environment.
+ *
+ * A bridge child selects this by the exact provenance label its managed entry carries —
+ * no probing, no guessing, and no effect on any other harness's child. It then does two
+ * things, in this order and before any lazy default-root consumer has run:
+ *
+ *   1. removes the foreign `PI_CODING_AGENT_DIR` from THIS PROCESS only. The OMP HOST
+ *      keeps it — there it is the vendor's own agent dir and deleting it would rewrite
+ *      vendor path semantics — but the child has no vendor lookup left to do.
+ *   2. pins the four `ENTWURF_META_*_DIR` overrides to this leaf's answer, so every
+ *      `defaultMeta*Dir()` consumer in the bridge reads the OMP bundle literally rather
+ *      than recomputing something that merely happens to match. Idempotent: an override
+ *      the operator already set was honoured by the leaf and is written back unchanged.
+ *
+ * These four are entwurf's OWN documented override vocabulary, set in our own process —
+ * not a new carrier, not a record field, not a marker.
+ *
+ * The in-process birth extension cannot use this and must not try: it runs INSIDE the omp
+ * host, so mutating that process's env is exactly the thing forbidden above. It passes
+ * explicit directories from {@link ompMetaRoots} instead.
+ */
+export function applyOmpBridgeChildRootPolicy(
+	env: MetaRootEnv = process.env,
+	home?: string,
+): { applied: boolean; roots: MetaRootBundle | null } {
+	// EXACT equality on the RAW label (#87 A3). Trimming was a courtesy that let a
+	// whitespace-drifted entry — one `doctor-omp-mcp` and the writer both call foreign —
+	// still select OMP root mutation in its child. The writer emits the literal and the
+	// doctor compares the literal; this compares the literal too, so all three agree on
+	// what "our entry" means.
+	if (env.ENTWURF_BRIDGE_EXTERNAL_AGENT_ID !== OMP_BRIDGE_PROVENANCE_LABEL) {
+		return { applied: false, roots: null };
+	}
+	const roots = ompMetaRoots(env, home ?? metaRootHome(env));
+	delete env.PI_CODING_AGENT_DIR;
+	env.ENTWURF_META_SESSIONS_DIR = roots.sessionsDir;
+	env.ENTWURF_META_MAILBOX_DIR = roots.mailboxDir;
+	env.ENTWURF_META_SENDERS_DIR = roots.sendersDir;
+	env.ENTWURF_META_RECEIVERS_DIR = roots.receiversDir;
+	return { applied: true, roots };
+}
+
 /**
  * A boot-unique identity for a live process: pid is reused, but pid + start-time
  * is unique within a boot. Linux reads `/proc/<pid>/stat` field 22 (starttime in