@junghanacs/entwurf 0.20.1 → 0.21.0

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

@@ -1,7 +1,8 @@
 /**
  * mux-fresh-call — open ONE visible sibling in the caller's own tmux server (its own session by
  * default, or one named existing session on that server since #105), hand it its first task in
- * the launch argv, and let it name itself back to the caller.
+ * the launch argv, and let it name itself back to the caller. Codex is the one measured topology
+ * exception: an omitted seat selects the existing `codex` home session (#95), never a TUI guess.
  *
  * ── Why this is a third module and not a parameter on the leaf ──
  *
@@ -78,6 +79,7 @@
 
 import { randomBytes } from "node:crypto";
 import { classifyTmuxCwd, type TmuxCwdRejectReason } from "./classify-tmux-cwd.ts";
+import { CODEX_PREFLIGHT_HINT, type CodexPreflightRejectReason } from "./codex-fresh-preflight.ts";
 import {
 	COPILOT_PREFLIGHT_HINT,
 	type CopilotPreflightRejectReason,
@@ -100,15 +102,16 @@ import {
 	runTmux,
 	type WindowHandle,
 } 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 { classifyTmuxSessionName, resolveTmuxSessionId, type TmuxSessionRejectReason } from "./resolve-tmux-session.ts";
 
 /** 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 under the step 9 admission contract, and
- * `omp` by #87 Bundle C under the same one. 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"] as const;
+ * 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
+ * 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 type FreshCallBackend = (typeof FRESH_CALL_BACKENDS)[number];
 
 /**
@@ -138,6 +141,7 @@ export const FRESH_CALL_RUNTIME: Record<FreshCallBackend, string> = {
 	"claude-code": "claude",
 	copilot: "entwurf",
 	omp: "omp",
+	codex: "codex",
 };
 
 /**
@@ -166,6 +170,7 @@ export const FRESH_CALL_CALLBACK_TOOL: Record<FreshCallBackend, string> = {
 	"claude-code": "mcp__entwurf-bridge__entwurf_v2",
 	copilot: "entwurf-bridge-entwurf_v2",
 	omp: "mcp__entwurf_bridge_entwurf_v",
+	codex: "mcp__entwurf_bridge__entwurf_v2",
 };
 
 /** Mirrors the `entwurf_v2` message bound. This is an INTERFACE cap for symmetry with the
@@ -276,6 +281,7 @@ export function buildBackendArgs(
 	backend: FreshCallBackend,
 	composition: FreshCallComposition,
 	model: string,
+	env: NodeJS.ProcessEnv = process.env,
 ): string[] {
 	switch (backend) {
 		case "pi":
@@ -286,11 +292,20 @@ export function buildBackendArgs(
 			return ["copilot", "--interactive", composition.prompt, "--model", model, "--yolo"];
 		case "omp":
 			return [`--${OMP_BOOTSTRAP_FLAG}`, composition.bootstrapPayload, "--model", model, "--approval-mode", "yolo"];
+		case "codex":
+			return [
+				"--remote",
+				`unix://${resolveCodexDefaultSocketPath(env)}`,
+				"--model",
+				model,
+				"--dangerously-bypass-approvals-and-sandbox",
+				composition.prompt,
+			];
 	}
 }
 
 /**
- * What a launch has to say, in the two shapes the four backends need. Three of them are
+ * 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.
@@ -375,6 +390,7 @@ export type FreshCallRejectReason =
 	| TmuxSessionRejectReason
 	| CopilotPreflightRejectReason
 	| OmpPreflightRejectReason
+	| CodexPreflightRejectReason
 	| "caller-identity-unavailable"
 	| "model-empty"
 	| "model-invalid"
@@ -389,6 +405,28 @@ export interface FreshCallPlacement {
 	tmuxSession: string;
 }
 
+/**
+ * Codex's explicit home topology (#95): the operator provides this one existing tmux session
+ * and seats the operator-owned app-server plus supported Codex TUIs there. This is a placement
+ * convention, not an address axis — `threadId` remains the native delivery address.
+ */
+export const CODEX_HOME_TMUX_SESSION = "codex" as const;
+export type FreshCallSeatSource = "requested" | "codex-home";
+export interface FreshCallSeat {
+	tmuxSession: string;
+	source: FreshCallSeatSource;
+}
+
+/** An explicit seat always wins. Only omitted Codex placement gets the fixed home. */
+export function selectFreshCallSeat(
+	backend: FreshCallBackend,
+	placement: FreshCallPlacement | undefined,
+): FreshCallSeat | null {
+	if (placement !== undefined) return { tmuxSession: placement.tmuxSession, source: "requested" };
+	if (backend === "codex") return { tmuxSession: CODEX_HOME_TMUX_SESSION, source: "codex-home" };
+	return null;
+}
+
 /** Coordinates plus what was handed to tmux. Read `runtimePath` as "what we asked to start".
  * There is deliberately NO field here for the callback, the nonce's arrival, or the sibling's
  * garden id — see the module header. */
@@ -399,10 +437,11 @@ export interface FreshCallReceipt extends WindowHandle {
 	 * of fact as `runtimePath`: what tmux was asked for, never an observation of where the pane
 	 * landed. */
 	cwd?: string;
-	/** The REQUESTED session name — present only when the caller named a seat. The RESOLVED
-	 * target is the inherited `sessionId`, which is the session the window is actually in; this
-	 * field is the request that produced it, exactly as `cwd` is. */
+	/** The selected session name — either caller-requested or Codex's fixed home. The RESOLVED
+	 * target is the inherited `sessionId`, which is the session the window is actually in. */
 	tmuxSession?: string;
+	/** Why `tmuxSession` was selected. Absent exactly when no named seat was used. */
+	tmuxSessionSource?: FreshCallSeatSource;
 	runtimePath: string;
 	nonce: string;
 }
@@ -435,9 +474,9 @@ function defaultRandomHex(): string {
  * 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 four backends because the leak is a property of tmux, not of a vendor. A
+ * It is applied to all five 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
- * three are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
+ * four 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 two-variable seam and deliberately NOT a
  * general env carrier — an arbitrary `-e` passthrough would hand callers the environment-shaping
@@ -526,8 +565,10 @@ export function freshCall(
 	// without tmux, so an unresolvable name is answered before anything else runs. Whether that
 	// session EXISTS is a tmux question and is asked below, after the caller's own context is
 	// proven — a name check that needed a live server would refuse for the wrong reason on a
-	// host with no tmux at all.
-	const seat = params.placement?.tmuxSession;
+	// host with no tmux at all. Codex alone selects its fixed home when the caller omitted a seat;
+	// an explicit seat remains an expert override and is reported as such.
+	const selectedSeat = selectFreshCallSeat(params.backend, params.placement);
+	const seat = selectedSeat?.tmuxSession;
 	if (seat !== undefined) {
 		const badSeat = classifyTmuxSessionName(seat);
 		if (badSeat) return { ok: false, reason: badSeat };
@@ -555,7 +596,6 @@ export function freshCall(
 		const missing = ompFreshPreflight(env);
 		if (missing) return { ok: false, reason: missing };
 	}
-
 	const inspected = inspectPlacement(env);
 	if (!inspected.ok) return { ok: false, reason: inspected.reason };
 	const placement = inspected.placement;
@@ -582,7 +622,7 @@ export function freshCall(
 		bootstrapPayload: buildOmpBootstrapPayload({ callerGardenId: params.callerGardenId, nonce, task }),
 	};
 	const run = runTmux(
-		buildFreshCallArgs(targetSessionId, runtimePath, buildBackendArgs(params.backend, composition, model), cwd),
+		buildFreshCallArgs(targetSessionId, runtimePath, buildBackendArgs(params.backend, composition, model, env), cwd),
 		env,
 	);
 	assertTmuxOk("new-window", run);
@@ -610,7 +650,9 @@ export function freshCall(
 			backend: params.backend,
 			model,
 			...(cwd === undefined ? {} : { cwd }),
-			...(seat === undefined ? {} : { tmuxSession: seat }),
+			...(selectedSeat === null
+				? {}
+				: { tmuxSession: selectedSeat.tmuxSession, tmuxSessionSource: selectedSeat.source }),
 			runtimePath,
 			nonce,
 		},
@@ -624,6 +666,7 @@ 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,
+	...CODEX_PREFLIGHT_HINT,
 	"no-tmux-context": "this agent is not running inside tmux, so there is no session to open a sibling beside",
 	"anchor-malformed": "TMUX_PANE is not a native pane id",
 	"anchor-unresolved": "tmux resolved no pane for this agent's anchor",
@@ -640,7 +683,7 @@ const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 	"tmux-session-name-invalid":
 		"the requested tmux session name is outside the shape this rail addresses (start with a letter or digit, then letters, digits, '_' or '-') — some other shapes tmux cannot resolve at all ('#' is expanded when the name is stored; '.' and ':' are its own pane/window separators inside a target; a name like '$0' loses to the session id '$0'), and the rest are declined to keep one narrow grammar, so rename the session or open one whose name fits",
 	"tmux-session-missing":
-		"no session with that exact name answers on this agent's tmux server (or that server stopped answering) — nothing was created, so open the session yourself and call again",
+		"no session with that exact name answers on this agent's tmux server (or that server stopped answering) — nothing was created, so open the session yourself and call again; Codex's omitted-placement home is the exact session name 'codex'",
 	"model-empty": "model is empty after trimming; fresh calls require an explicit model",
 	"model-invalid": `model must be one ${MODEL_MAX_CHARS}-character argv-safe id/alias without whitespace or tmux syntax`,
 	"task-empty": "task is empty after trimming",
@@ -678,7 +721,9 @@ export function renderFreshCall(result: FreshCallResult): { text: string; isErro
 			(r.cwd === undefined ? "" : `  cwd:      ${r.cwd} (requested start directory — not an observation)\n`) +
 			(r.tmuxSession === undefined
 				? ""
-				: `  seat:     ${r.tmuxSession} (requested tmux session, resolved to ${r.sessionId})\n`) +
+				: r.tmuxSessionSource === "codex-home"
+					? `  seat:     ${r.tmuxSession} (Codex home tmux session, resolved to ${r.sessionId})\n`
+					: `  seat:     ${r.tmuxSession} (requested tmux session, resolved to ${r.sessionId})\n`) +
 			`  window:   ${r.windowId} (index ${r.windowIndex}) in session ${r.sessionId}\n` +
 			`  pane:     ${r.paneId} pid ${r.panePid}\n` +
 			`  nonce:    ${r.nonce}\n` +

package/pi-extensions/lib/native-push/adapter.ts

@@ -1,7 +1,7 @@
 /**
  * native-push adapter rail — the transport LEAF by which a native-push backend
- * (antigravity, the first) is (1) probed for a LIVE conversation and (2) direct-injected
- * with a message. Mirrors the ACP backend-adapter rail (acp/backend-adapter.ts §ADAPTERS
+ * is (1) probed for a LIVE native target and (2) direct-injected with a message.
+ * Mirrors the ACP backend-adapter rail (acp/backend-adapter.ts §ADAPTERS
  * /resolveAcpBackendAdapter): one interface, one registry, a fail-fast resolver.
  *
  * Purity contract (봉인 3):
@@ -26,6 +26,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 
 import type { NativePushBackend } from "../entwurf-v2-contract.ts";
+import { codexNativePushAdapter } from "./codex-ws-client.ts";
 
 // ── runner seam (injectable process exec) ───────────────────────────────────
 
@@ -85,14 +86,13 @@ export const realNativePushRunner: NativePushRunner = {
 // ── route + probe result ────────────────────────────────────────────────────
 
 /**
- * A VOLATILE native-push route — the live LS address (`127.0.0.1:PORT`) a probe found
- * serving the conversation. MUST NOT be stored (봉인 3): it is re-derived every dispatch
- * by a fresh probe (the LS port is per-process and shifts). Carried only within a single
- * `send` call, handed straight from a fresh `probe`.
+ * A VOLATILE native-push route. Antigravity carries its live LS address; Codex carries
+ * the one app-server UDS that proved the target thread loaded. Routes are never stored:
+ * every dispatch derives one from a fresh probe and hands it straight to `send`.
  */
-export interface NativePushRoute {
-	readonly lsAddress: string;
-}
+export type NativePushRoute =
+	| { readonly backend: "antigravity"; readonly lsAddress: string }
+	| { readonly backend: "codex"; readonly socketPath: string };
 
 /**
  * A probe outcome. `alive` carries the volatile route; `dead`/`indeterminate` carry a
@@ -108,17 +108,12 @@ export type NativePushProbeResult =
 export interface NativePushAdapter {
 	/** Backend discriminator (a member of NATIVE_PUSH_BACKENDS). */
 	readonly id: NativePushBackend;
-	/**
-	 * Full-scan probe: find a LIVE route serving `nativeSessionId`, else report
-	 * dead/indeterminate. Scans EVERY host pid (never `head -1`) and re-discovers the
-	 * route on every call (no cache — volatile-route discipline, 봉인 3).
-	 */
+	/** Whether the executor may re-probe and retry once after an ambiguous send failure.
+	 * Codex is false: `codex queue` may accept before its receipt fails, so retry can duplicate. */
+	readonly retriable: boolean;
+	/** Probe the backend's current native route for `nativeSessionId`. */
 	probe(nativeSessionId: string): Promise<NativePushProbeResult>;
-	/**
-	 * Direct-inject `content` into the conversation over `route`. Single attempt: throws
-	 * on failure (fail-loud). Does NOT probe and does NOT retry — the executor hand owns
-	 * re-probe/retry (봉인 3), so the adapter can never silently paper over a dead route.
-	 */
+	/** Direct-inject once through the just-probed route. Throws on failure. */
 	send(route: NativePushRoute, nativeSessionId: string, content: string): Promise<void>;
 }
 
@@ -211,6 +206,7 @@ export function createAntigravityAdapter(deps: AntigravityAdapterDeps): NativePu
 
 	return {
 		id: "antigravity",
+		retriable: true,
 
 		async probe(nativeSessionId) {
 			let pids: number[];
@@ -237,7 +233,7 @@ export function createAntigravityAdapter(deps: AntigravityAdapterDeps): NativePu
 			for (const pid of pids) {
 				for (const lsAddress of portsByPid.get(pid) ?? []) {
 					if (await servesConversation(lsAddress, nativeSessionId)) {
-						return { status: "alive", route: { lsAddress } };
+						return { status: "alive", route: { backend: "antigravity", lsAddress } };
 					}
 				}
 			}
@@ -251,12 +247,13 @@ export function createAntigravityAdapter(deps: AntigravityAdapterDeps): NativePu
 		},
 
 		async send(route, nativeSessionId, content) {
+			if (route.backend !== "antigravity") {
+				throw new Error(`antigravity adapter received ${route.backend} route`);
+			}
 			const r = await runner.exec([binary, "agentapi", "send-message", nativeSessionId, content], {
 				env: { ANTIGRAVITY_LS_ADDRESS: route.lsAddress },
 				timeoutMs: AGY_SEND_TIMEOUT_MS,
 			});
-			// A non-zero code — including a timeout kill (124) on a stalled route — THROWS
-			// (fail-loud); the executor hand owns the 1-shot re-probe→re-send on that throw.
 			if (r.code !== 0) {
 				throw new Error(
 					`native-push send failed (agentapi send-message exit ${r.code}) via ${route.lsAddress}: ${
@@ -268,12 +265,12 @@ export function createAntigravityAdapter(deps: AntigravityAdapterDeps): NativePu
 	};
 }
 
-/** The production antigravity adapter (real runner + env-resolved binary). */
+/** Production adapters. */
 export const antigravityAdapter: NativePushAdapter = createAntigravityAdapter({ runner: realNativePushRunner });
 
 // ── registry + fail-fast resolver (mirror resolveAcpBackendAdapter) ──────────
 
-const ADAPTERS: readonly NativePushAdapter[] = [antigravityAdapter];
+const ADAPTERS: readonly NativePushAdapter[] = [antigravityAdapter, codexNativePushAdapter];
 
 /**
  * Resolve the native-push adapter that owns backend `id`. Fail-fast, like