@junghanacs/entwurf 0.21.0 → 0.23.0

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

@@ -7,18 +7,32 @@
 #   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?
+#   FOREIGN     what ELSE declares a SessionStart hook in that file — reported, never judged.
 #   TRUST       has the VENDOR recorded the operator's one-time decision for this exact
 #               declaration identity?
 #
+# WHAT THE UNIT AXIS CERTIFIES ABOUT hooks.json, AND WHAT IT STOPPED CERTIFYING (#117). Not the
+# file. entwurf owns ONE `SessionStart` group in a file it SHARES — Herdr's official Codex
+# integration appends its own, and the vendor runs both, because `[source]`
+# hooks/src/engine/discovery.rs:664-665 keys trust by `<path>:<event>:<group_idx>:<handler_idx>`.
+# So this doctor selects entwurf's group by its launcher command, checks its SHAPE and its
+# NORMALIZED digest (key order and indentation blind — measured: Herdr re-serializes the whole
+# document), and reports every other group as FOREIGN without ever certifying or editing it.
+#
 # 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
+# vendor's own receipt at `<hooks.json>:session_start:<our group>:<our handler>`, 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.
 #
+# AND IT IS READ AT THE INDEX OUR DECLARATION WAS JUST MEASURED AT, never at a constant. The old
+# spelling `…:session_start:0:0` was true only while entwurf was alone in the file; with a
+# neighbour at index 0 it reads THEIR receipt and reports it as ours — a green for a hook the
+# vendor has never been asked to run.
+#
 # 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.
@@ -49,7 +63,13 @@ HELPER_DIR="$UNIT_ROOT/helper"
 LAUNCHER_NAME="codex-birth-launch.sh"
 LAUNCHER="$HELPER_DIR/$LAUNCHER_NAME"
 STATE_FILE="$UNIT_ROOT/install-state.json"
+REPO_DIR="$(cd -P -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+DECLARATION_LIB="$REPO_DIR/pi-extensions/lib/codex-declaration.js"
 ME="$(id -u)"
+# Filled by the UNIT axis and read by the TRUST axis: the position our declaration was actually
+# found at. Empty means the UNIT axis could not locate it, and TRUST says so rather than guessing.
+DECL_GROUP_INDEX=""
+DECL_HANDLER_INDEX=""
 
 RED=0
 section() { printf '\n── %s %s\n' "$1" "─────────────────────────────────────────"; }
@@ -105,9 +125,25 @@ judge_parent() { # $1 = dir, $2 = label
 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"
+FOREIGN_LINES=""
+FOREIGN_SCANNED=0
+ORPHAN_DECLARATION=0
+if [ ! -e "$STATE_FILE" ] && [ ! -L "$STATE_FILE" ] && [ -f "$HOOKS_FILE" ] && [ -n "$NODE_BIN" ] && [ -f "$DECLARATION_LIB" ]; then
+  # A hooks.json with NO entwurf state is the ordinary shape on a host where only somebody else
+  # declares hooks — it is not evidence of anything of ours. What IS evidence is a group
+  # commanding OUR launcher with no receipt behind it, so that is the only thing asked about.
+  "$NODE_BIN" -e '
+    const fs = require("node:fs");
+    const [, lib, hooksFile, launcher] = process.argv;
+    import(lib).then((m) => {
+      const sel = m.selectEntwurfDeclaration(JSON.parse(fs.readFileSync(hooksFile, "utf8")), launcher);
+      process.exit(sel.ok || sel.code === "declaration-duplicated" ? 0 : 1);
+    }).catch(() => process.exit(1));
+  ' "$DECLARATION_LIB" "$HOOKS_FILE" "$LAUNCHER" >/dev/null 2>&1 && ORPHAN_DECLARATION=1
+fi
 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."
+  if [ "$ORPHAN_DECLARATION" = "1" ] || [ -e "$HELPER_DIR" ]; then
+    bad "no ownership state at $STATE_FILE, yet an entwurf declaration or helper closure is present — 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
@@ -133,15 +169,21 @@ else
   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 [, stateFile, hooksFile, helperDir, lib, launcher] = process.argv;
+    // An async main, not a top-level body: `node -e` compiles its input as a script, where a
+    // top-level `return` is a SyntaxError, and the declaration leaf is an ESM `import()`.
+    void (async function main() {
+    const s = JSON.parse(fs.readFileSync(stateFile, "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.schema === "codex-birth-install-state/v1") {
+      out.push("BAD\tthe ownership state is codex-birth-install-state/v1, which recorded a digest of the WHOLE hooks.json. This unit now owns ONE declaration inside a file it shares, so that receipt claims bytes it does not own. Repair: ./run.sh install-codex-birth (it supersedes the receipt, removes nothing, and rewrites no foreign byte)");
+    } else if (s.schema !== "codex-birth-install-state/v2") {
+      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");
+    if (s.hooksFile !== hooksFile) out.push("BAD\tthe state is bound to " + s.hooksFile + ", not the fixed path " + hooksFile);
+    if (s.helperDir !== helperDir) out.push("BAD\tthe state is bound to helper dir " + s.helperDir + ", not the fixed path " + helperDir);
     const expected = [
       "codex-birth-launch.sh",
       "meta-bridge-hook-codex.ts",
@@ -168,13 +210,81 @@ else
       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=""; }
+
+    // ── the DECLARATION, judged as one group inside a file this unit shares ──
+    const decl = s.declaration;
+    const declOk = decl !== null && typeof decl === "object" && !Array.isArray(decl) && decl.event === "SessionStart" && typeof decl.command === "string" && hex(decl.sha256);
+    if (!declOk && s.schema === "codex-birth-install-state/v2") out.push("BAD\tthe state records no usable declaration receipt (event/command/sha256)");
+    const emit = () => process.stdout.write(out.join("\n") + "\n");
+    if (!declOk) return emit();
+    const m = await import(lib);
+    // OWNERSHIP BEFORE CONTENT (sol B3, 2026-09-18). This doctor used to read the CONTENT of the
+    // shared file without ever asking who owned it, while the fresh-call preflight refused a foreign
+    // uid or a group-writable mode outright — so a host could be GREEN here and refuse every
+    // launch as `codex-birth-unit-missing`. One predicate now answers for all four surfaces, and
+    // it answers first: a digest measured in a file somebody else can rewrite certifies nothing.
+    const owned = m.classifyOwnedPath(m.statOwnedPath(fs, hooksFile), process.getuid());
+    if (owned === "missing") {
+      out.push("BAD\tthe declaration file is MISSING: " + hooksFile + " — no Codex thread on this host can become a citizen. Repair: ./run.sh install-codex-birth");
+      return emit();
+    }
+    if (owned !== "ok") {
+      out.push("BAD\tthe declaration file " + m.OWNED_PATH_REFUSAL[owned] + " (" + hooksFile + ") — every Codex fresh call refuses this host for the same reason, so a green here would contradict the launcher");
+      return emit();
+    }
+    let text;
+    try {
+      text = fs.readFileSync(hooksFile, "utf8");
+    } catch (err) {
+      out.push("BAD\tthe declaration file could not be read (" + hooksFile + "): " + err.message);
+      return emit();
+    }
+    let sel;
+    try {
+      sel = m.selectEntwurfDeclaration(JSON.parse(text), launcher);
+    } catch (err) {
+      out.push("BAD\t" + hooksFile + " is not readable JSON (" + err.message + ")");
+      return emit();
+    }
+    // The SCAN marker is emitted whether or not there are neighbours, because "none" and "never
+    // looked" are different facts and only one of them claims anything about a file we read.
+    for (const group of sel.foreign) {
+      out.push("FOREIGN\tSessionStart group " + group.index + ": " + (group.commands.join(" | ") || "(no handler)"));
+    }
+    out.push("FOREIGNSCAN\t" + sel.foreign.length);
+    if (!sel.ok) {
+      out.push("BAD\tentwurf\u2019s own declaration is not certifiable in " + hooksFile + " — " + sel.code + ": " + sel.detail + ". Repair: ./run.sh install-codex-birth");
+      return emit();
+    }
+    if (sel.digest !== decl.sha256) {
+      out.push("BAD\tentwurf\u2019s own declaration was EDITED after install (" + hooksFile + " group " + sel.groupIndex + ": live normalized " + sel.digest + ", recorded " + decl.sha256 + ") — the inverse will refuse to remove it");
+      return emit();
+    }
+    if (decl.command !== m.entwurfDeclarationCommand(launcher)) {
+      out.push("BAD\tthe recorded declaration command " + JSON.stringify(decl.command) + " is not the one these fixed paths produce");
+      return emit();
+    }
+    out.push("DECL\t" + sel.groupIndex + "\t" + sel.handlerIndex + "\t" + sel.digest + "\t" + sel.foreign.length);
+    return emit();
+    })().catch((err) => {
+      process.stderr.write(err && err.message ? err.message : String(err));
+      process.exit(1);
+    });
+  ' "$STATE_FILE" "$HOOKS_FILE" "$HELPER_DIR" "$DECLARATION_LIB" "$LAUNCHER" 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" ;;
+      FOREIGN) FOREIGN_LINES="${FOREIGN_LINES}${a}
+" ;;
+      FOREIGNSCAN) FOREIGN_SCANNED=1 ;;
+      DECL)
+        DECL_GROUP_INDEX="$a"; DECL_HANDLER_INDEX="$b"
+        ok "entwurf's declaration is certified at $HOOKS_FILE group $a handler $b (normalized sha256 $c)"
+        info "certified by NORMALIZED digest, not by file bytes: this unit owns one SessionStart group,"
+        info "and a neighbour re-serializing that document changes every byte and nothing of ours."
+        ;;
       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"
@@ -197,11 +307,37 @@ $INVENTORY
 EOF
 fi
 
+section "FOREIGN (what else declares a SessionStart hook in that file)"
+# REPORTED, NEVER JUDGED. Another integration's declaration is not this unit's to certify, to
+# repair or to remove, and its state says nothing about whether entwurf's own hook will run —
+# `[source]` discovery.rs:664-665 trusts per declaration, so neighbours are independent. This
+# section exists so an operator can SEE them, which is the difference between coexisting and
+# not knowing.
+if [ "$FOREIGN_SCANNED" = "0" ]; then
+  # NOT "none". The UNIT axis stopped before it read that document — an absent or unreadable
+  # ownership state, a missing file — and reporting "none" here would be this doctor asserting
+  # something about the operator's file that it never looked at.
+  info "NOT READ — the UNIT axis stopped before it could look at $HOOKS_FILE, so this doctor"
+  info "knows nothing about what else declares a SessionStart hook there. Repair the UNIT axis first."
+elif [ -n "$FOREIGN_LINES" ]; then
+  printf '%s' "$FOREIGN_LINES" | while IFS= read -r line; do
+    [ -n "$line" ] && info "$line"
+  done
+  info "present-but-foreign: not certified by this unit, never overwritten, never absorbed, and"
+  info "no input to any verdict above. Their own trust receipts are their owners' business."
+else
+  info "none — entwurf is the only SessionStart declaration in $HOOKS_FILE"
+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
+if [ -z "$DECL_GROUP_INDEX" ] && [ "$UNIT_ONLY" != "1" ]; then
+  bad "the UNIT axis could not locate entwurf's declaration, so there is no index to read a vendor
+           receipt at. A receipt read at a guessed position would be somebody else's approval.
+           Repair the UNIT axis first: ./run.sh install-codex-birth"
+elif [ "$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.
@@ -212,7 +348,11 @@ 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"
+  #
+  # THE INDEX COMES FROM THE UNIT AXIS, which just measured where our declaration actually sits.
+  # Spelling it `0:0` was right only while entwurf was alone in the file: with a neighbour at
+  # index 0, that constant reads THEIR receipt and reports it as ours.
+  TRUST_KEY="$HOOKS_FILE:session_start:$DECL_GROUP_INDEX:$DECL_HANDLER_INDEX"
   # 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 '
@@ -242,8 +382,11 @@ sys.stdout.write("PRESENT\t" + digest)
   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."
+      info "this reports that the vendor RECORDED a decision for this declaration identity AT THE INDEX"
+      info "entwurf's declaration was just measured at — not a cryptographic validation. This doctor"
+      info "deliberately does NOT recompute what that hash should be: the vendor hashes a normalized"
+      info "identity of its own (discovery.rs:775-792), and reimplementing it here would make entwurf a"
+      info "second opinion about somebody else's security decision, drifting with every vendor release."
       ;;
     ABSENT)
       bad "no vendor trust receipt for this declaration — $TRUST_DETAIL. Until the operator answers the