@junghanacs/entwurf 0.20.1 → 0.22.0

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-app-server-launch.sh

@@ -0,0 +1,275 @@
+#!/usr/bin/env bash
+# codex-app-server-launch.sh — the managed Codex app-server launch,
+# `entwurf codex-app-server` (#95, the operator-UX half).
+#
+# WHY THIS EXISTS. Every Codex rail in this repo — native-push delivery, visible fresh,
+# the loaded-thread probe — needs one thing the operator has to start themselves:
+#
+#   codex app-server --listen "unix://$CODEX_HOME/app-server-control/app-server-control.sock"
+#
+# That string is correct and nobody types it. It appeared in three documents and in the
+# text of a refusal, which means the first time most operators meet it is AFTER something
+# has already failed. This leaf owns the SPELLING of that command and nothing else.
+#
+# WHAT IT IS NOT — and this is the whole boundary. It is not a supervisor, a daemon, a
+# restarter, a health loop or a pid file. It does not fork. It `exec`s in the caller's own
+# terminal, so the server's cwd, tty, pid and exit status are the vendor's, and Ctrl-C is
+# the operator's. Entwurf still does not own the app-server's lifecycle (AGENTS Hard Rule
+# 16, NEXT CARRIED step 2): a missing app-server still REJECTS at fresh-call preflight
+# rather than being started behind anyone's back. What changed is only that the refusal can
+# now name a command a person can actually type.
+#
+# THE SOCKET PATH IS SPELLED ONCE, SOMEWHERE ELSE. `resolveCodexDefaultSocketPath`
+# (pi-extensions/lib/native-push/codex-ws-client.ts) is where the product computes this path,
+# and it is the leaf every OTHER Codex surface reads. A bash leaf cannot import it, so this one
+# ASKS — `run.sh codex-socket-path`, through `run_ts`. It was written the other way first, with
+# a bash transcription and a gate comparing the two over an environment matrix; they agreed on
+# every ASCII input and diverged on a BOM-only CODEX_HOME and on path normalization. See
+# scripts/codex-socket-path.ts for that measurement. A transcription can only be tested on the
+# inputs somebody thought of, which is why there is no longer one to test.
+#
+# THE TMUX LINE IS A FACT, NOT A REFUSAL. The MCP bridge is a CHILD of this server and
+# inherits its `TMUX`, so the tmux server this process sits in is the one caller-seat
+# lookups will read (docs/mux-launch-rail.md §Codex). Running outside tmux is a legitimate
+# operator choice with a consequence, so it is reported as a consequence. Refusing it here
+# would make this leaf an authority over the operator's terminal, which it is not.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$HERE/.." && pwd)"
+
+# The vendor command this leaf manages. A CONSTANT, deliberately not overridable: an env
+# seam here would be a production switch for "which binary is the Codex CLI", and anything
+# that can redirect an exec is an authority, not a test convenience. The gate proves the
+# real contract instead — it puts its fake vendor on a sandbox PATH under this exact name.
+VENDOR_CMD="codex"
+
+fail() { printf 'FAIL: %s\n' "$*" >&2; exit 1; }
+note() { printf '[entwurf] %s\n' "$*" >&2; }
+
+# --- recursion fence -------------------------------------------------------
+# A `codex` earlier on PATH that itself calls `entwurf codex-app-server` would spin
+# forever, and the symptom would be a hung terminal rather than an error. The sentinel is
+# invocation-local, so seeing it already set means we are inside our own exec chain.
+if [ -n "${ENTWURF_CODEX_APP_SERVER_ACTIVE:-}" ]; then
+	fail "recursive managed launch detected (ENTWURF_CODEX_APP_SERVER_ACTIVE is already set).
+  Something on PATH named '$VENDOR_CMD' resolves back to this launcher. Fix PATH so
+  '$VENDOR_CMD' is the OpenAI Codex CLI, or run the vendor binary by its full path."
+fi
+
+# --- the socket path: ASKED, never re-derived -------------------------------
+# This leaf does no path arithmetic at all, and that is the correction rather than the style.
+# Its first version mirrored `resolveCodexHome` in bash — `${CODEX_HOME:-$HOME/.codex}` plus a
+# POSIX `[:space:]` trim — with a gate comparing the two spellings over four ASCII-normal
+# inputs they happened to agree on. `[측정 2026-09-16, independent review]` they disagree
+# elsewhere: with `CODEX_HOME=$'\ufeff'` the TS leaf trims (JS trim strips U+FEFF) and falls
+# back to `$HOME/.codex`, while the bash trim kept the byte and produced
+# `<BOM>/app-server-control/app-server-control.sock`; `path.join` likewise normalizes a
+# trailing slash or a `..` segment where the bash concatenation did not. Each of those starts a
+# server at an address delivery and preflight never look at.
+#
+# So the second spelling is gone instead of widened — a transcription can only ever be tested
+# on the inputs somebody thought of. `run.sh codex-socket-path` prints what
+# `resolveCodexDefaultSocketPath` computes for THIS environment, through `run_ts` (compiled twin
+# when installed, strip-types in a clone). An empty or failed answer is a hard refusal: there is
+# no fallback spelling left to guess with, and that is the point.
+if ! SOCK="$(bash "$REPO_DIR/run.sh" codex-socket-path)"; then
+	fail "could not resolve the Codex control-socket path.
+  '$REPO_DIR/run.sh codex-socket-path' failed; that leaf is the only spelling of this address,
+  and this launcher will not invent a second one. Its output above says why."
+fi
+[ -n "$SOCK" ] \
+	|| fail "the Codex control-socket resolver returned an empty path — neither CODEX_HOME nor
+  HOME names a usable Codex home. Set CODEX_HOME."
+
+# Asking one authority for the address does not make the ANSWER safe to act on, and this is the
+# one place that acts on it: `mkdir -p` creates a directory at it and the vendor binds it. The
+# resolver faithfully returns whatever `CODEX_HOME` holds — it neither requires an absolute path
+# nor rejects control characters, because the surfaces that merely READ it (preflight's lstat,
+# the delivery probe) fail closed on their own. A RELATIVE address is a different file for every
+# process that resolves it, and the bridge that will look for this socket is the app-server's MCP
+# child with its own cwd — so the one thing a launch cannot do is bind a path whose meaning
+# depends on where it was typed. Control characters are refused with it: a newline in an address
+# is not a path this repo will create on an operator's behalf. Both refuse BEFORE any write.
+case "$SOCK" in
+	/*) ;;
+	*) fail "codex-app-server-socket-path-not-absolute: the resolver returned
+  '$SOCK'
+  A relative control-socket address resolves to a different file for every process that reads it,
+  and the bridge that looks for this socket runs with its own working directory. Set CODEX_HOME to
+  an absolute path." ;;
+esac
+case "$SOCK" in
+	*[[:cntrl:]]*) fail "codex-app-server-socket-path-untrusted: the resolved control-socket address
+  carries a control character (CODEX_HOME almost certainly does). Refusing to create or bind it." ;;
+esac
+
+# --- operator argv: forwarded, never reinterpreted -------------------------
+# Everything the operator passes is appended after the injected pair and crosses
+# byte-identical. The single exception is a second `--listen`: injecting ours beside theirs
+# would hand the vendor two listen addresses and let one of them win silently, and a silent
+# winner is exactly the false success this repo refuses. `--opt=value` and `--opt value` are
+# the same option, so the head is what is compared.
+for tok in "$@"; do
+	if [ "${tok%%=*}" = "--listen" ]; then
+		fail "codex-app-server-listen-override: this verb exists to spell ONE --listen address
+  (unix://$SOCK), and you passed your own. Run the vendor directly if you mean a
+  different address: $VENDOR_CMD app-server --listen <your-address>"
+	fi
+done
+
+# --- resolve the vendor executable -----------------------------------------
+# `type -P` returns the PATH hit only — never a shell function, alias or builtin — so what
+# is exec'd is a real external file. `exec command codex` is deliberately NOT used: it would
+# re-enter shell lookup at exec time and could pick up something other than the file
+# validated here.
+codex_bin="$(type -P "$VENDOR_CMD" 2>/dev/null || true)"
+[ -n "$codex_bin" ] \
+	|| fail "no '$VENDOR_CMD' executable found on PATH.
+  The managed launch runs the OpenAI Codex CLI; install it, or put it on PATH."
+[ -f "$codex_bin" ] && [ -x "$codex_bin" ] \
+	|| fail "'$codex_bin' is not an executable regular file — refusing to exec it."
+
+# Self-exec fence, the second half of the recursion guard: resolve symlinks and refuse
+# anything that is one of our own entrypoints even if the sentinel was stripped. POSIX walk,
+# same shape as scripts/copilot-launch.sh — BSD readlink has no -f.
+resolve_path() {
+	local SOURCE="$1" DIR TARGET
+	while [ -L "$SOURCE" ]; do
+		DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+		TARGET="$(readlink "$SOURCE")"
+		case "$TARGET" in
+			/*) SOURCE="$TARGET" ;;
+			*) SOURCE="$DIR/$TARGET" ;;
+		esac
+	done
+	DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+	printf '%s/%s\n' "$DIR" "$(basename "$SOURCE")"
+}
+resolved_bin="$(resolve_path "$codex_bin")"
+for own in "$HERE/codex-app-server-launch.sh" "$REPO_DIR/run.sh"; do
+	own_resolved="$(resolve_path "$own")"
+	[ "$resolved_bin" = "$own_resolved" ] \
+		&& fail "'$VENDOR_CMD' on PATH resolves to entwurf's own '$own_resolved' — that is a launch loop, not the vendor CLI."
+done
+
+# --- is somebody already listening there? ----------------------------------
+# Three outcomes, and they are NOT the same repair. A live socket means a second server
+# would either lose the bind race or silently replace the endpoint every citizen's record
+# already points at — refuse and name the holder. An indeterminate path (symlink, not a
+# socket, owned by another uid) is the classification `checkCodexSocketFile` already uses in
+# the product, and a launcher that guessed past it would be clobbering something it cannot
+# identify. A dead socket file is the ordinary leftover of a Ctrl-C, and the vendor replaces
+# it — that one is a fact line, not a refusal.
+probe="$(python3 - "$SOCK" <<'PY'
+import os, socket, stat, sys
+
+path = sys.argv[1]
+try:
+	st = os.lstat(path)
+except FileNotFoundError:
+	print("absent")
+	raise SystemExit(0)
+except OSError as exc:
+	print(f"indeterminate\t{exc.strerror or exc}")
+	raise SystemExit(0)
+
+if stat.S_ISLNK(st.st_mode):
+	print("indeterminate\tthe path is a symlink")
+	raise SystemExit(0)
+if not stat.S_ISSOCK(st.st_mode):
+	print("indeterminate\tthe path exists and is not a socket")
+	raise SystemExit(0)
+if st.st_uid != os.getuid():
+	print(f"indeterminate\tthe socket is owned by uid {st.st_uid}, not {os.getuid()}")
+	raise SystemExit(0)
+
+probe = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+probe.settimeout(2)
+try:
+	probe.connect(path)
+except (ConnectionRefusedError, FileNotFoundError):
+	print("stale")
+except OSError as exc:
+	print(f"indeterminate\t{exc.strerror or exc}")
+else:
+	print("live")
+finally:
+	probe.close()
+PY
+)" || fail "could not classify the control socket at $SOCK (python3 is required by this launcher)."
+
+probe_status="${probe%%	*}"
+probe_reason="${probe#*	}"
+case "$probe_status" in
+	live)
+		# Show what the host actually says, and say so when it says nothing. The owner is read
+		# out of /proc rather than inferred from the socket: a socket file names no pid, so the
+		# only honest answer when no cmdline matches is that no match was found.
+		owner=""
+		if [ -d /proc ]; then
+			for cl in /proc/[0-9]*/cmdline; do
+				[ -r "$cl" ] || continue
+				if tr '\0' ' ' < "$cl" 2>/dev/null | grep -qF "$SOCK"; then
+					owner="${owner}    pid $(basename "$(dirname "$cl")"): $(tr '\0' ' ' < "$cl")
+"
+				fi
+			done
+		fi
+		[ -n "$owner" ] || owner="    (no process on this host spells that socket in its cmdline — read, not inferred)
+"
+		fail "codex-app-server-already-listening: a live app-server is answering on
+  unix://$SOCK
+  Entwurf never replaces one. What /proc reports about it:
+$owner  Use that server, or stop it first."
+		;;
+	indeterminate)
+		fail "codex-app-server-socket-indeterminate: $probe_reason
+  Path: $SOCK
+  This is the same classification the delivery rail's socket check uses, and a launcher that
+  guessed past it would be clobbering something it cannot identify. Inspect that path."
+		;;
+	stale)
+		note "a dead control socket is already at $SOCK (nothing is listening); the vendor replaces it."
+		;;
+	absent)
+		: # nothing is there; the ordinary first launch
+		;;
+	*)
+		# Hard Rule 15. Every branch above is a decision about whether this launch would
+		# CLOBBER a running server, so an unrecognised classification is the one case where
+		# proceeding is unsafe — and a probe that exits 0 while printing something nobody wrote
+		# would otherwise fall straight through to the exec.
+		fail "codex-app-server-socket-probe-unrecognised: the socket classifier answered
+  '$probe_status', which is not one of live/stale/indeterminate/absent. Refusing to launch on a
+  reading nothing understands."
+		;;
+esac
+
+# --- the control directory the address lives in ----------------------------
+# The same `mkdir -p` the three documents told the operator to run by hand. It is inside
+# their own CODEX_HOME, and without it a first launch fails on a directory rather than on
+# anything meaningful.
+mkdir -p "$(dirname "$SOCK")" \
+	|| fail "could not create $(dirname "$SOCK") — the control socket has nowhere to live."
+
+# --- the tmux fact, stated once --------------------------------------------
+note "this app-server's tmux seat: ${TMUX:-(none — not inside tmux)}"
+note "the bridge is this server's MCP child and inherits that TMUX, so caller-seat lookups read THAT tmux server's panes."
+note "entwurf neither supervises nor restarts this process — Ctrl-C is yours."
+
+export ENTWURF_CODEX_APP_SERVER_ACTIVE=1
+
+# --- foreign identity carriers, removed before exec ------------------------
+# The MCP bridge trusts a COMPLETE `PI_SESSION_ID` + `PI_AGENT_ID` pair ahead of a native
+# sender marker when it resolves who is speaking. Inside the pi process that planted them
+# from record birth that is correct. Here they would be somebody else's identity inherited by
+# the app-server and by EVERY bridge child it spawns — start the server from a pi citizen's
+# bash and each Codex thread's MCP child could speak under the parent pi garden id.
+#
+# Both go, together: clearing one only changes the wording of a later failure while leaving a
+# carrier for a partial reader. Nothing is substituted — a Codex thread's identity comes from
+# its own trusted birth hook, which is where the record authority already lives.
+unset PI_SESSION_ID PI_AGENT_ID
+
+exec "$codex_bin" app-server --listen "unix://$SOCK" "$@"

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