@junghanacs/entwurf 0.20.1 → 0.21.0

package/scripts/check-mux-launch-tmux.ts

@@ -8,7 +8,7 @@
  * and required to be byte-identical, and `TMUX`/`TMUX_PANE` INHERITED from a fixture pane's
  * own `/proc/<pid>/environ` rather than assembled.
  *
- * The runtime under test is a FIXTURE script, not the operator's real `pi`. T1-a's claim is
+ * The runtimes under test are FIXTURE scripts, not the operator's real `pi`/`codex`. T1-a's claim is
  * "the window opens in the right place and the named runtime is what starts in it" — a claim a
  * long-lived stand-in proves exactly, without an interactive agent, a model call, or a session
  * record. `resolvePiRuntime` (which finds the official `pi` on PATH) is proven by the
@@ -27,6 +27,7 @@
  *   - the #105 seat, through the real `freshCall`: an absent seat refuses and creates nothing,
  *     an existing one puts the window in THAT session with a receipt naming the resolved
  *     target, and the resulting handle closes through `closeWindow` from outside that session
+ *   - #95's omitted Codex seat resolves exact existing `codex`, while omitted Pi stays caller-local
  */
 
 import assert from "node:assert/strict";
@@ -120,6 +121,7 @@ async function main(): Promise<void> {
 	// process must be the runtime itself for the pane_pid claim to mean anything.
 	const runtime = path.join(runtimeDir, "pi");
 	fs.writeFileSync(runtime, "#!/bin/sh\nexec sleep 900\n", { mode: 0o755 });
+	fs.writeFileSync(path.join(runtimeDir, "codex"), "#!/bin/sh\nexec sleep 900\n", { mode: 0o755 });
 
 	try {
 		assert.equal(fx("-f", "/dev/null", "new-session", "-d", "-s", SESSION).status, 0, "fixture new-session");
@@ -353,7 +355,7 @@ async function main(): Promise<void> {
 					fxLines("list-windows", "-t", placement.sessionId, "-F", "#{window_id}").join(" ") === callerWindowsBefore,
 			);
 			ok(
-				"seat: an omitted seat still lands in the caller's own session and the receipt names none",
+				"seat: an omitted Pi seat still lands in the caller's own session and the receipt names none",
 				(() => {
 					const own = call();
 					if (!own.ok) return false;
@@ -370,7 +372,50 @@ async function main(): Promise<void> {
 				closeWindow(receipt, inherited) === "closed" &&
 					!fxLines("list-windows", "-a", "-F", "#{window_id}").includes(receipt.windowId),
 			);
+
+			// (iv) Codex's omitted seat is a product default, not fixture prose. Missing home
+			// refuses before mutation; then a private session named exactly `codex` makes the real
+			// composition resolve that name while the Pi omitted-seat control stays caller-local.
+			const beforeMissingHome = inventory();
+			const missingHome = freshCall(
+				{
+					backend: "codex",
+					model: "fixture-model",
+					task: "fixture task",
+					callerGardenId: "20260101T000000-fixture",
+				},
+				inherited,
+			);
+			ok(
+				"codex home: omitted placement refuses a missing exact home without mutation",
+				!missingHome.ok && missingHome.reason === "tmux-session-missing" && inventory() === beforeMissingHome,
+			);
+			assert.equal(fx("new-session", "-d", "-s", "codex").status, 0, "fixture Codex home session");
+			const codexHomeId = fxLines("list-windows", "-t", "=codex", "-F", "#{session_id}")[0];
+			const home = freshCall(
+				{
+					backend: "codex",
+					model: "fixture-model",
+					task: "fixture task",
+					callerGardenId: "20260101T000000-fixture",
+				},
+				inherited,
+			);
+			assert.ok(home.ok, `the omitted-placement Codex call must succeed: ${home.ok ? "" : home.reason}`);
+			ok(
+				"codex home: omitted placement lands in exact existing `codex`, not the caller session",
+				home.receipt.sessionId === codexHomeId &&
+					home.receipt.sessionId !== placement.sessionId &&
+					home.receipt.tmuxSession === "codex" &&
+					home.receipt.tmuxSessionSource === "codex-home",
+			);
+			ok(
+				"codex home: the home receipt closes by stable handle",
+				closeWindow(home.receipt, inherited) === "closed" &&
+					!fxLines("list-windows", "-a", "-F", "#{window_id}").includes(home.receipt.windowId),
+			);
 			fx("kill-session", "-t", seatId);
+			fx("kill-session", "-t", codexHomeId);
 			ok("seat: the fixture is back to one session", sessionCount() === 1);
 		}
 	} finally {

package/scripts/check-native-push-adapter.ts

@@ -29,6 +29,7 @@ import {
 	AGY_SEND_TIMEOUT_MS,
 	antigravityAdapter,
 	createAntigravityAdapter,
+	type NativePushRoute,
 	type NativePushRunner,
 	resolveNativePushAdapter,
 } from "../pi-extensions/lib/native-push/adapter.ts";
@@ -45,6 +46,11 @@ function eq(label: string, actual: unknown, expected: unknown): void {
 	passed++;
 }
 
+function agyAddress(route: NativePushRoute): string {
+	assert.equal(route.backend, "antigravity", "Antigravity adapter returned its own route kind");
+	return route.backend === "antigravity" ? route.lsAddress : "(wrong backend)";
+}
+
 const FAKE_BINARY = "/fake/bin/agy";
 const CONV = "conv-abc-123";
 
@@ -129,7 +135,7 @@ function makeFakeRunner(config: FakeConfig): { runner: NativePushRunner; calls:
 	ok("full-scan: probe finds the route on the SECOND pid (not head -1)", result.status === "alive");
 	eq(
 		"full-scan: route is pid 456's port (5002)",
-		result.status === "alive" ? result.route.lsAddress : "(dead)",
+		result.status === "alive" ? agyAddress(result.route) : "(dead)",
 		"127.0.0.1:5002",
 	);
 	// proof it did NOT stop at pid 123: it probed BOTH 5001 (miss) and 5002 (hit).
@@ -219,7 +225,11 @@ for (const [code, what] of [
 	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
 
 	const r1 = await adapter.probe(CONV);
-	eq("volatile-route: probe #1 route = 5002", r1.status === "alive" ? r1.route.lsAddress : "(dead)", "127.0.0.1:5002");
+	eq(
+		"volatile-route: probe #1 route = 5002",
+		r1.status === "alive" ? agyAddress(r1.route) : "(dead)",
+		"127.0.0.1:5002",
+	);
 	const pgrepAfter1 = calls.filter((c) => c.argv[0] === "pgrep").length;
 
 	// the LS port shifts (per-process, volatile) — a fresh probe must RE-DISCOVER it.
@@ -227,7 +237,7 @@ for (const [code, what] of [
 	const r2 = await adapter.probe(CONV);
 	eq(
 		"volatile-route: probe #2 RE-DISCOVERS the changed route = 5003 (no cache)",
-		r2.status === "alive" ? r2.route.lsAddress : "(dead)",
+		r2.status === "alive" ? agyAddress(r2.route) : "(dead)",
 		"127.0.0.1:5003",
 	);
 	ok(
@@ -241,7 +251,7 @@ for (const [code, what] of [
 {
 	const { runner, calls } = makeFakeRunner({ pids: [123], ss: ssLine(5002, 123), serving: () => true });
 	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
-	await adapter.send({ lsAddress: "127.0.0.1:5002" }, CONV, "hello world");
+	await adapter.send({ backend: "antigravity", lsAddress: "127.0.0.1:5002" }, CONV, "hello world");
 	const sendCall = calls.find((c) => c.argv.includes("send-message"));
 	eq("send: argv === [binary, agentapi, send-message, conv, content]", sendCall?.argv, [
 		FAKE_BINARY,
@@ -262,7 +272,7 @@ for (const [code, what] of [
 	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
 	let threw = false;
 	try {
-		await adapter.send({ lsAddress: "127.0.0.1:5002" }, CONV, "hi");
+		await adapter.send({ backend: "antigravity", lsAddress: "127.0.0.1:5002" }, CONV, "hi");
 	} catch (err) {
 		threw = true;
 		ok("send-fail: error names the non-zero exit", /native-push send failed/.test((err as Error).message));
@@ -286,7 +296,7 @@ for (const [code, what] of [
 	const { runner, calls } = makeFakeRunner({ pids: [123], ss: ssLine(5002, 123), serving: () => true });
 	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
 	await adapter.probe(CONV);
-	await adapter.send({ lsAddress: "127.0.0.1:5002" }, CONV, "hi");
+	await adapter.send({ backend: "antigravity", lsAddress: "127.0.0.1:5002" }, CONV, "hi");
 	const metaCall = calls.find((c) => c.argv.includes("get-conversation-metadata"));
 	const sendCall = calls.find((c) => c.argv.includes("send-message"));
 	eq("timeout: get-conversation-metadata carries the metadata timeout", metaCall?.timeoutMs, AGY_METADATA_TIMEOUT_MS);
@@ -317,7 +327,7 @@ for (const [code, what] of [
 	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
 	let threw = false;
 	try {
-		await adapter.send({ lsAddress: "127.0.0.1:5002" }, CONV, "hi");
+		await adapter.send({ backend: "antigravity", lsAddress: "127.0.0.1:5002" }, CONV, "hi");
 	} catch {
 		threw = true;
 	}
@@ -327,15 +337,9 @@ for (const [code, what] of [
 // ── resolver fail-fast (mirror resolveAcpBackendAdapter) ─────────────────────
 eq("resolve: antigravity → the antigravity adapter", resolveNativePushAdapter("antigravity").id, "antigravity");
 eq("adapter id: antigravityAdapter.id === antigravity", antigravityAdapter.id, "antigravity");
-{
-	let threw = false;
-	try {
-		resolveNativePushAdapter("codex");
-	} catch {
-		threw = true;
-	}
-	ok("resolve: unknown backend (codex) → throw (no silent default)", threw);
-}
+eq("resolve: codex → the Codex adapter", resolveNativePushAdapter("codex").id, "codex");
+eq("retry policy: Antigravity may retry", resolveNativePushAdapter("antigravity").retriable, true);
+eq("retry policy: Codex never retries", resolveNativePushAdapter("codex").retriable, false);
 {
 	let threw = false;
 	try {

package/scripts/check-native-push-register.ts

@@ -39,6 +39,7 @@ const REPO_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."
 function fakeAdapter(probe: NativePushProbeResult): NativePushAdapter {
 	return {
 		id: "antigravity",
+		retriable: true,
 		async probe() {
 			return probe;
 		},
@@ -48,7 +49,10 @@ function fakeAdapter(probe: NativePushProbeResult): NativePushAdapter {
 	};
 }
 
-const ALIVE: NativePushProbeResult = { status: "alive", route: { lsAddress: "127.0.0.1:5599" } };
+const ALIVE: NativePushProbeResult = {
+	status: "alive",
+	route: { backend: "antigravity", lsAddress: "127.0.0.1:5599" },
+};
 
 async function main(): Promise<void> {
 	const dir = mkdtempSync(path.join(os.tmpdir(), "entwurf-register-"));

package/scripts/check-release-gate-outcomes.ts

@@ -297,6 +297,7 @@ function runSubcommand(sub: string, env: Record<string, string | undefined>): {
 		"smoke-acp-long-turn-live": ["VERIFY.md", "on-demand, not part of `release-gate`"],
 		"smoke-mux-fresh-call-live": ["VERIFY.md", "Fresh-call LIVE is on-demand, not part of `release-gate`"],
 		"smoke-agy-native-push-live": ["VERIFY.md", "Aggregate release-gate does not own an agy conversation id"],
+		"smoke-codex-native-push-live": ["VERIFY.md", "Aggregate release-gate does not own a loaded Codex thread"],
 		"smoke-acp-ordering-probe-live": ["docs/acp-backend-rail.md", "opt-in paired observation"],
 		// Cortex needs an external Snowflake connection the HOST owns, so an aggregate
 		// that required it would block every cut taken without that account. Excluded —
@@ -806,6 +807,48 @@ function runSubcommand(sub: string, env: Record<string, string | undefined>): {
 	);
 }
 
+// ===========================================================================
+// Codex first admission is a MUST; the loaded-thread probe remains on-demand
+//
+// The old native-push smoke consumes a thread the operator loaded in an attached
+// TUI, so the aggregate cannot own its prerequisite. The first-admission smoke
+// instead owns all three visible windows in the Pi -> Codex -> Pi chain and takes
+// only an explicit app-server PID as seat authority. The new gate must not silently
+// pull the old loaded-thread probe into release-gate, and keeping the old exclusion
+// must not excuse the new end-to-end acceptance.
+// ===========================================================================
+{
+	const runSh = readFileSync(join(REPO_DIR, "run.sh"), "utf8");
+	const gateBody = runSh.slice(runSh.indexOf("release_gate() {"), runSh.indexOf("# 5. Summary"));
+	const verify = readFileSync(join(REPO_DIR, "VERIFY.md"), "utf8");
+	const admissionSteps = gateBody.split("\n").filter((line) => line.includes('"$self" smoke-codex-fresh-live'));
+	const loadedThreadSteps = gateBody
+		.split("\n")
+		.filter((line) => line.includes('"$self" smoke-codex-native-push-live'));
+	const gaps: string[] = [];
+	if (admissionSteps.length !== 1) {
+		gaps.push(`release_gate runs smoke-codex-fresh-live ${admissionSteps.length}x (need exactly one MUST step)`);
+	}
+	if (admissionSteps.length === 1 && !admissionSteps[0]?.includes("run_live_step")) {
+		gaps.push("smoke-codex-fresh-live does not go through run_live_step, so LIVE=1/SKIP cannot reach --cut");
+	}
+	if (loadedThreadSteps.length !== 0) {
+		gaps.push(`release_gate runs the operator-thread smoke ${loadedThreadSteps.length}x (need zero)`);
+	}
+	if (!verify.includes("Aggregate release-gate does not own a loaded Codex thread")) {
+		gaps.push("VERIFY.md no longer states why smoke-codex-native-push-live remains on-demand");
+	}
+	if (!runSh.includes("ENTWURF_CODEX_APP_SERVER_PID")) {
+		gaps.push("run.sh no longer names the explicit operator-owned app-server PID prerequisite");
+	}
+	assert.ok(
+		gaps.length === 0,
+		"[QK:CODEX-FIRST-ADMISSION-IS-RELEASE-MUST] the fresh Codex acceptance must run exactly once through " +
+			"run_live_step, while the loaded-thread native-push smoke stays excluded for its documented operator-owned " +
+			`prerequisite. Broken: ${gaps.join("; ")}`,
+	);
+}
+
 // ===========================================================================
 // The operator's CONFIGURED bridge invocation is proven BEFORE the cost-bearing LIVE tier
 //
@@ -873,5 +916,8 @@ console.log(
 		"five historical reds; and " +
 		"every gate a committed mutant names is itself inside check:full or states its exclusion in prose an operator " +
 		"reads; and the CI push trigger is filtered to branch refs, so a release tag creates no duplicate run; and " +
-		"the operator's CONFIGURED bridge invocation is booted exactly once through run_step, before the ACP LIVE tier",
+		"Pi -> visible Codex -> visible Pi first-admission callback/addressed/outbound acceptance is a release MUST " +
+		"while the operator-loaded-thread Codex native-push probe remains excluded; and the operator's CONFIGURED " +
+		"bridge invocation is booted exactly once " +
+		"through run_step, before the ACP LIVE tier",
 );

package/scripts/check-setup-qualification.sh

@@ -73,7 +73,7 @@ run_setup() { # $1=HOME-root $2=project $3=PATH $4=PI_BIN $5=COPILOT_BIN(opt) $6
   set +e
   # ONE physical line by contract: check-install-surface S5c is a line-scoped static tripwire,
   # so the sandbox env assignments must ride the same line as the run.sh drive they guard.
-  OUT="$(HOME="$1" XDG_DATA_HOME="$1/.local/share" XDG_STATE_HOME="$1/.local/state" XDG_CACHE_HOME="$1/.cache" XDG_CONFIG_HOME="$1/.config" PI_CODING_AGENT_DIR="$1/.pi/agent" PATH="$3" PI_BIN="$4" CLAUDE_BIN="$ABSENT" AGY_BIN="$ABSENT" COPILOT_BIN="${5:-$ABSENT}" OMP_BIN="${6:-$ABSENT}" ENTWURF_OMP_AGENT_DIR="$1/.omp/agent" bash "$PKG/run.sh" setup "$2" 2>&1)"
+  OUT="$(HOME="$1" XDG_DATA_HOME="$1/.local/share" XDG_STATE_HOME="$1/.local/state" XDG_CACHE_HOME="$1/.cache" XDG_CONFIG_HOME="$1/.config" PI_CODING_AGENT_DIR="$1/.pi/agent" PATH="$3" PI_BIN="$4" CLAUDE_BIN="$ABSENT" AGY_BIN="$ABSENT" COPILOT_BIN="${5:-$ABSENT}" OMP_BIN="${6:-$ABSENT}" CODEX_BIN="$ABSENT" ENTWURF_OMP_AGENT_DIR="$1/.omp/agent" bash "$PKG/run.sh" setup "$2" 2>&1)"
   RC=$?
   set -e
 }
@@ -93,6 +93,8 @@ want "A: an absent copilot is one zero-state SKIP — no unit composed, no .copi
   "printf '%s' \"\$OUT\" | grep -q 'copilot: SKIP' && [ ! -e '$HOME_A/.copilot' ]"
 want "A: an absent omp is one zero-state SKIP — no unit composed, no .omp written [QK:SETUP-OMP-ABSENT-SKIP]" \
   "printf '%s' \"\$OUT\" | grep -q 'omp: SKIP' && [ ! -e '$HOME_A/.omp' ]"
+want "A: an absent Codex is one zero-state SKIP — no unit composed, no .codex written [QK:CODEX-SETUP-ZERO-STATE]" \
+  "printf '%s' \"\$OUT\" | grep -q 'codex: SKIP' && [ ! -e '$HOME_A/.codex' ]"
 want "A control: mode named first, pi/claude/agy SKIP, bins PASS, core FAIL, NON-GREEN summary" \
   "printf '%s' \"\$OUT\" | head -n 1 | grep -q 'mode: installed package' && printf '%s' \"\$OUT\" | grep -q 'pi: SKIP' && printf '%s' \"\$OUT\" | grep -q 'claude: SKIP' && printf '%s' \"\$OUT\" | grep -q 'agy: SKIP' && printf '%s' \"\$OUT\" | grep -q 'bins: PASS' && printf '%s' \"\$OUT\" | grep -q 'core: FAIL' && printf '%s' \"\$OUT\" | grep -q 'NON-GREEN'"
 

package/scripts/codex-birth-doctor.sh

@@ -0,0 +1,276 @@
+#!/usr/bin/env bash
+# codex-birth-doctor — the Codex birth unit verdict: our bytes, and the vendor receipt.
+#
+# Three axes, reported independently, because they fail for different reasons and an
+# operator repairs them with different hands:
+#
+#   RUNTIME     is there a node the launcher can exec, and a Codex CLI at all?
+#   UNIT        are the declaration, launcher and closure present, ours by digest, and
+#               owned/permissioned so that nobody else could have written them?
+#   TRUST       has the VENDOR recorded the operator's one-time decision for this exact
+#               declaration identity?
+#
+# WHAT THE TRUST AXIS IS, EXACTLY. It reads `$CODEX_HOME/config.toml` and looks for the
+# vendor's own receipt at the fixed key `<hooks.json>:session_start:0:0`, whose value must
+# be a `trusted_hash` of the shape `sha256:<64 hex>`. That is ALL it claims: a vendor trust
+# receipt is present for the declaration identity this unit publishes. It does NOT compute
+# what that hash should be, does not compare it to anything of ours, and therefore never
+# says the approval is cryptographically valid — the vendor hashes a normalized identity of
+# its own (`[source]` hooks/src/engine/discovery.rs:775-792) and recomputing it here would
+# be entwurf asserting authority over somebody else's security decision.
+#
+# WHAT THIS DOCTOR NEVER DOES. It does not write, pre-seed or repair `[hooks.state]`, and it
+# never launches Codex. A missing receipt is not something to fix from here: the operator
+# opens a visible Codex, answers the vendor's prompt once, and comes back.
+#
+# Trust missing makes the WHOLE doctor red, on purpose. A unit whose bytes are perfect but
+# whose hook the vendor will not run is a citizen nobody will ever be born as — reporting
+# that as green is the exact false success this file exists to refuse. `--unit-only` exists
+# for the sandbox gate, which has no vendor and no operator; it can never make setup or the
+# fresh preflight green, because neither passes that flag.
+set -euo pipefail
+
+UNIT_ONLY=0
+for arg in "$@"; do
+  case "$arg" in
+    # For the hermetic gate only: there is no vendor and no operator inside a sandbox, so the
+    # TRUST axis has nothing to read. It is REPORTED as skipped, never as green, and setup and
+    # the fresh preflight both call this doctor without the flag.
+    --unit-only) UNIT_ONLY=1 ;;
+    *) printf '[codex-birth-doctor] unknown argument %s — this doctor takes only --unit-only.\n' "'$arg'" >&2; exit 1 ;;
+  esac
+done
+
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+HOOKS_FILE="$CODEX_HOME/hooks.json"
+PACKAGE_STATE_ROOT="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf"
+UNIT_ROOT="$PACKAGE_STATE_ROOT/codex-birth"
+HELPER_DIR="$UNIT_ROOT/helper"
+LAUNCHER_NAME="codex-birth-launch.sh"
+LAUNCHER="$HELPER_DIR/$LAUNCHER_NAME"
+STATE_FILE="$UNIT_ROOT/install-state.json"
+ME="$(id -u)"
+
+RED=0
+section() { printf '\n── %s %s\n' "$1" "─────────────────────────────────────────"; }
+bad() { printf '  RED      %s\n' "$1"; RED=$((RED + 1)); }
+ok() { printf '  ok       %s\n' "$1"; }
+info() { printf '  ·        %s\n' "$1"; }
+
+sha_of() { sha256sum -- "$1" | cut -d' ' -f1; }
+
+section "PATHS"
+# The declaration records an ABSOLUTE launcher path and the vendor keys its trust receipt to
+# it, so a relative CODEX_HOME or XDG_DATA_HOME would make this doctor judge a different unit
+# depending on the caller's cwd.
+case "$CODEX_HOME" in
+  /*) ok "CODEX_HOME resolves absolute ($CODEX_HOME)" ;;
+  *) bad "CODEX_HOME resolves to a relative path ('$CODEX_HOME') — every verdict below would depend on the caller's cwd." ;;
+esac
+case "$UNIT_ROOT" in
+  /*) ok "the unit root resolves absolute ($UNIT_ROOT)" ;;
+  *) bad "the unit root resolves to a relative path ('$UNIT_ROOT') — set an absolute XDG_DATA_HOME or HOME." ;;
+esac
+
+section "RUNTIME"
+if NODE_BIN="$(command -v node 2>/dev/null)"; then
+  NODE_MAJOR="$("$NODE_BIN" -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0)"
+  if [ "$NODE_MAJOR" -ge 24 ] 2>/dev/null; then
+    ok "node $("$NODE_BIN" -p 'process.versions.node') at $NODE_BIN (>= 24, so strip-types runs the payload)"
+  else
+    bad "node at $NODE_BIN reports major '$NODE_MAJOR'; the payload is raw TypeScript and needs >= 24."
+  fi
+else
+  bad "no node on PATH — the hook payload cannot run."
+  NODE_BIN=""
+fi
+if CODEX_BIN="$(command -v "${CODEX_BIN:-codex}" 2>/dev/null)"; then
+  info "codex CLI: $CODEX_BIN $("$CODEX_BIN" --version 2>/dev/null | head -1)"
+else
+  info "no codex CLI on PATH — the unit's bytes are still judged below; the harness is the operator's."
+fi
+
+# The directory holding the receipt carries the receipt's authority: anyone who can write it
+# can replace what licenses every removal. Judged before the state is read, and never repaired.
+judge_parent() { # $1 = dir, $2 = label
+  [ -e "$1" ] || return 0
+  if [ -L "$1" ]; then bad "$2 ($1) is a SYMLINK — ownership authority may not come through a link."; return 0; fi
+  [ -d "$1" ] || { bad "$2 ($1) is not a directory."; return 0; }
+  local st mode uid
+  st="$(stat -c '%a %u' -- "$1")"; mode="$(printf '%s' "$st" | cut -d' ' -f1)"; uid="$(printf '%s' "$st" | cut -d' ' -f2)"
+  [ "$uid" = "$ME" ] || { bad "$2 ($1) is owned by uid $uid, not you ($ME) — it holds the receipt that licenses removals."; return 0; }
+  [ $((8#$mode & 0022)) -eq 0 ] || bad "$2 ($1) is group/world-writable (mode $mode), so the ownership state inside it is not provably ours."
+}
+
+section "UNIT (the bytes this unit publishes, and whether they are still ours)"
+judge_parent "$PACKAGE_STATE_ROOT" "the package state root"
+judge_parent "$UNIT_ROOT" "the unit root"
+if [ ! -e "$STATE_FILE" ] && [ ! -L "$STATE_FILE" ]; then
+  if [ -e "$HOOKS_FILE" ] || [ -e "$HELPER_DIR" ]; then
+    bad "no ownership state at $STATE_FILE, yet $HOOKS_FILE or $HELPER_DIR exists — those bytes are not provably ours and the inverse will refuse them. Inspect them."
+  else
+    # NOT an informational note. "Nothing is installed" is the most complete way for this
+    # unit to be broken: no declaration, no closure, no record will ever be minted — and a
+    # host that has trusted an OLDER declaration still carries a vendor receipt, so the TRUST
+    # axis alone can read green over an empty unit. Measured exactly that way before this was
+    # red. An absent unit is a red unit, in both modes.
+    bad "no Codex birth unit is installed here (no ownership state at $STATE_FILE, no declaration, no closure), so no Codex thread on this host can become a citizen.
+           Install: ./run.sh install-codex-birth"
+  fi
+elif [ -L "$STATE_FILE" ]; then
+  bad "$STATE_FILE is a SYMLINK — removal authority may not come through a link."
+elif [ ! -f "$STATE_FILE" ]; then
+  bad "$STATE_FILE is not a regular file."
+elif [ -z "$NODE_BIN" ]; then
+  bad "the ownership state cannot be parsed without node."
+else
+  STATE_ST="$(stat -c '%a %u' -- "$STATE_FILE")"
+  STATE_MODE="$(printf '%s' "$STATE_ST" | cut -d' ' -f1)"
+  STATE_UID="$(printf '%s' "$STATE_ST" | cut -d' ' -f2)"
+  [ "$STATE_UID" = "$ME" ] || bad "$STATE_FILE is owned by uid $STATE_UID, not you ($ME) — anyone who can rewrite it can license removal of the paths it names."
+  [ $((8#$STATE_MODE & 0022)) -eq 0 ] || bad "$STATE_FILE is group/world-writable (mode $STATE_MODE) — the same authority problem."
+
+  INVENTORY="$("$NODE_BIN" -e '
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const s = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+    const out = [];
+    const hex = (v) => typeof v === "string" && /^[0-9a-f]{64}$/.test(v);
+    if (s.schema !== "codex-birth-install-state/v1") out.push("BAD\tforeign state schema " + JSON.stringify(s.schema));
+    if (s.status !== "installed") out.push("BAD\tthe state status is " + JSON.stringify(s.status) + ", so a previous install did not finish publishing. Repair: ./run.sh install-codex-birth");
+    if (s.hooksFile !== process.argv[2]) out.push("BAD\tthe state is bound to " + s.hooksFile + ", not the fixed path " + process.argv[2]);
+    if (s.helperDir !== process.argv[3]) out.push("BAD\tthe state is bound to helper dir " + s.helperDir + ", not the fixed path " + process.argv[3]);
+    if (!hex(s.hooksSha256)) out.push("BAD\thooksSha256 is not a digest");
+    else out.push("WANT\t" + s.hooksSha256 + "\t" + s.hooksFile + "\tthe declaration");
+    const expected = [
+      "codex-birth-launch.sh",
+      "meta-bridge-hook-codex.ts",
+      "lib/meta-session.ts",
+      "lib/native-push/codex-ws-client.ts",
+      "lib/session-id.js",
+      "entwurf-capabilities.json",
+    ];
+    if (!Array.isArray(s.helperFiles) || s.helperFiles.length === 0) out.push("BAD\thelperFiles is empty");
+    else {
+      // Exactly the closure this unit publishes. A short inventory hides a file the inverse
+      // can never reclaim; a long one licenses deleting something we never wrote.
+      const named = s.helperFiles.map((f) => (f == null ? "" : f.path));
+      const missing = expected.filter((name) => !named.includes(name));
+      const extra = named.filter((name) => !expected.includes(name));
+      const duplicate = named.filter((name, i) => named.indexOf(name) !== i);
+      if (missing.length) out.push("BAD\tthe recorded closure inventory is missing " + missing.join(", ") + " — the doctor cannot judge bytes no state names");
+      if (extra.length) out.push("BAD\tthe recorded closure inventory names files this unit never publishes: " + extra.join(", "));
+      if (duplicate.length) out.push("BAD\tthe recorded closure inventory repeats " + duplicate.join(", "));
+    }
+    if (Array.isArray(s.helperFiles)) for (const f of s.helperFiles) {
+      if (typeof f?.path !== "string" || f.path.startsWith("/") || f.path.split("/").includes("..")) { out.push("BAD\tunsafe helper path " + JSON.stringify(f?.path)); continue; }
+      if (!hex(f.sha256)) { out.push("BAD\tbad helper digest for " + f.path); continue; }
+      out.push(["WANT", f.sha256, path.join(s.helperDir, f.path), "helper member " + f.path, f.mode ?? ""].join("\t"));
+    }
+    out.push("INFO\tunitVersion=" + (s.unitVersion ?? "?") + " nodeBin=" + (s.nodeBin ?? "?"));
+    process.stdout.write(out.join("\n") + "\n");
+  ' "$STATE_FILE" "$HOOKS_FILE" "$HELPER_DIR" 2>&1)" || { bad "the ownership state is unreadable or malformed: $INVENTORY"; INVENTORY=""; }
+
+  while IFS="$(printf '\t')" read -r kind a b c d; do
+    case "$kind" in
+      BAD) bad "$a" ;;
+      INFO) info "$a" ;;
+      WANT)
+        if [ -L "$b" ]; then bad "$c is a SYMLINK ($b) — this unit publishes no links."
+        elif [ ! -e "$b" ]; then bad "$c is MISSING: $b"
+        elif [ ! -f "$b" ]; then bad "$c is not a regular file: $b"
+        else
+          live="$(sha_of "$b")"
+          st="$(stat -c '%a %u' -- "$b")"
+          mode="$(printf '%s' "$st" | cut -d' ' -f1)"; uid="$(printf '%s' "$st" | cut -d' ' -f2)"
+          if [ "$live" != "$a" ]; then bad "$c was EDITED after install ($b: live $live, recorded $a) — the inverse will refuse to remove it."
+          elif [ "$uid" != "$ME" ]; then bad "$c is owned by uid $uid, not you ($ME): $b"
+          elif [ $((8#$mode & 0022)) -ne 0 ]; then bad "$c is group/world-writable (mode $mode): $b"
+          else ok "$c matches the state ($b)"
+          fi
+          [ -n "$d" ] && [ "$mode" != "${d#0}" ] && [ "0$mode" != "$d" ] && info "$c mode is $mode, state recorded $d"
+        fi
+        ;;
+    esac
+  done <<EOF
+$INVENTORY
+EOF
+fi
+
+TRUST_REPAIR="Repair: open a visible plain Codex (no flags), answer the vendor's prompt with
+           'Trust all and continue', send one first turn, then re-run this doctor."
+
+section "TRUST (the vendor's receipt for this exact declaration)"
+if [ "$UNIT_ONLY" = "1" ]; then
+  info "--unit-only: the vendor receipt was NOT read. This is a skipped axis, not a green one."
+elif [ ! -e "$CODEX_HOME/config.toml" ]; then
+  bad "$CODEX_HOME/config.toml does not exist, so the vendor has recorded no trust decision for $HOOKS_FILE.
+           $TRUST_REPAIR"
+elif ! command -v python3 >/dev/null 2>&1; then
+  bad "python3 is required to read the vendor config (the same reader the MCP/status-line atoms use) and is not on PATH."
+else
+  # The key the vendor writes is `<declaration path>:<event>:<group>:<handler>` — measured on
+  # this host after one 'Trust all'. We look for exactly ours: a receipt for a DIFFERENT
+  # declaration is not this unit's approval, however valid it is for whoever owns it.
+  TRUST_KEY="$HOOKS_FILE:session_start:0:0"
+  # python3 + tomllib, the same reader the two config atoms already use — node has no TOML
+  # parser and inventing one here would be a second opinion about the vendor's own file.
+  TRUST_OUT="$(python3 -c '
+import sys, tomllib
+cfg_path, key = sys.argv[1], sys.argv[2]
+try:
+    cfg = tomllib.load(open(cfg_path, "rb"))
+except Exception as err:  # noqa: BLE001 - the message is the verdict
+    sys.stdout.write("ERROR\t" + str(err)); raise SystemExit(0)
+state = cfg.get("hooks", {}).get("state")
+if not isinstance(state, dict):
+    sys.stdout.write("ABSENT\tno [hooks.state] table"); raise SystemExit(0)
+if key not in state:
+    others = sorted(state.keys())
+    sys.stdout.write("WRONGKEY\t" + (", ".join(others) if others else "(none)")); raise SystemExit(0)
+entry = state[key]
+digest = entry.get("trusted_hash") if isinstance(entry, dict) else None
+if not isinstance(digest, str):
+    sys.stdout.write("MALFORMED\tthe receipt carries no trusted_hash string"); raise SystemExit(0)
+import re
+if not re.fullmatch(r"sha256:[0-9a-f]{64}", digest):
+    sys.stdout.write("MALFORMED\ttrusted_hash is not sha256:<64 hex>: " + repr(digest)); raise SystemExit(0)
+sys.stdout.write("PRESENT\t" + digest)
+' "$CODEX_HOME/config.toml" "$TRUST_KEY" 2>&1)" || TRUST_OUT="ERROR	$TRUST_OUT"
+  TRUST_KIND="$(printf '%s' "$TRUST_OUT" | cut -f1)"
+  TRUST_DETAIL="$(printf '%s' "$TRUST_OUT" | cut -f2-)"
+  case "$TRUST_KIND" in
+    PRESENT)
+      ok "a vendor trust receipt is present for $TRUST_KEY ($TRUST_DETAIL)"
+      info "this reports that the vendor RECORDED a decision for this declaration identity — it is"
+      info "not a cryptographic validation, and this doctor never computes what that hash should be."
+      ;;
+    ABSENT)
+      bad "no vendor trust receipt for this declaration — $TRUST_DETAIL. Until the operator answers the
+           vendor's prompt once, this hook is declared and never runs.
+           $TRUST_REPAIR"
+      ;;
+    WRONGKEY)
+      bad "the vendor has trust receipts, but NONE at this unit's key $TRUST_KEY (present: $TRUST_DETAIL).
+           A receipt for another declaration is somebody else's approval, not this one's.
+           $TRUST_REPAIR"
+      ;;
+    MALFORMED)
+      bad "the vendor trust receipt at $TRUST_KEY is unreadable: $TRUST_DETAIL.
+           $TRUST_REPAIR"
+      ;;
+    *)
+      bad "the vendor config at $CODEX_HOME/config.toml could not be read: $TRUST_DETAIL"
+      ;;
+  esac
+fi
+
+if [ "$RED" -ne 0 ]; then
+  printf '\n[codex-birth-doctor] %d RED — see above.\n' "$RED" >&2
+  exit 1
+fi
+if [ "$UNIT_ONLY" = "1" ]; then
+  printf '\n[codex-birth-doctor] unit bytes and ownership are intact; the TRUST axis was skipped (--unit-only).\n'
+else
+  printf '\n[codex-birth-doctor] unit bytes are ours and the vendor trust receipt is present for this declaration.\n'
+fi