@junghanacs/entwurf 0.20.0 → 0.21.0

package/docs/external-mcp-host.md

@@ -6,47 +6,45 @@ the one-line registration; everything an operator needs to actually wire a host
 
 `entwurf-bridge` can also be registered in a separate MCP-aware harness (Claude Code, Codex CLI, Antigravity/`agy`, GitHub Copilot CLI, OMP, …). That host does **not** become a pi session and does **not** need to be ACP-backed. There are now two honest cases:
 
-- **plain external MCP host**: no garden meta-record / sender marker. It can call the read surfaces (`entwurf_peers`, `entwurf_inbox_read`), but `entwurf_v2` sends are **refused by default** (#50 C4: "if we don't know who sent it, we don't send it"). The operator may wire the explicit hatch below; the send then goes out external/non-replyable.
-- **garden-native native session**: a trusted lifecycle hook minted a garden id and sender marker — `SessionStart` for Claude Code, `PreInvocation` for agy, `userPromptSubmitted`/`sessionStart` for GitHub Copilot CLI, and for OMP an in-process extension on `session_start`/`session_switch` that mints only a `mode === "tui"` host. It is not a pi control-socket session, but it can be replyable by garden id when its own mailbox/probe rail says so.
+- **plain external MCP host**: no garden meta-record or authoritative identity carrier. It can call the read surfaces (`entwurf_peers`, `entwurf_inbox_read`), but `entwurf_v2` sends are **refused by default** (#50 C4: "if we don't know who sent it, we don't send it"). The operator may wire the explicit hatch below; the send then goes out external/non-replyable.
+- **garden-native native session**: a trusted lifecycle event minted a garden id — `SessionStart` for Claude Code and Codex, `PreInvocation` for agy, `userPromptSubmitted`/`sessionStart` for GitHub Copilot CLI, and for OMP an in-process extension on `session_start`/`session_switch` that mints only a `mode === "tui"` host. Claude/Copilot/agy/OMP then use record-backed process markers; Codex instead carries its matching native `threadId` on every MCP request. It is not a pi control-socket session, but it can be replyable by garden id when its own mailbox/probe rail says so.
 
   **Being garden-native is not the same as being replyable, and Copilot is the case that separates them.** Its hook writes a sender marker, so an `entwurf_v2` send carries its own garden id and the receiver learns who wrote — measured 2026-08-21 on Copilot CLI 1.0.80, where a live send arrived under its own garden id with `origin: "meta-session"` and `replyable: false`. Replyability arrived later and through a different process: a first-party extension (`run.sh install-copilot-receive`) that the CLI forks, which binds to the same V3 record and writes a receiver marker owned by its own pid (#82 RAIL 5). So a Copilot citizen is `replyable: true` exactly while that extension is armed for it, and `replyable: false` — honestly, with a real garden identity — when it is not installed, not launched with `COPILOT_CLI_ENABLED_FEATURE_FLAGS=EXTENSIONS` (which is what `entwurf copilot` sets for one invocation), not yet born, or gone. Read the two facts off different rails: the sender marker answers *who sent this*; the receiver marker answers *can a reply land*. The onboarding obligations are in [`adding-a-harness.md`](./adding-a-harness.md) step 7, and the evidence boundary — the managed LIVE acceptance that moved receive to D6, and what D7-partial / D3-pending still exclude — is in [`DELIVERY.md`](../DELIVERY.md).
 
-**Which verb an external agent should reach for:** to deliver to / reply to a garden id, use **`entwurf_v2`** — it is the canonical delivery surface and the only one that reads whether the target is live pi, dormant pi, a mailbox-backed self-fetch citizen (Claude Code, Copilot, OMP), or native-push Antigravity and routes correctly. Discover targets with `entwurf_peers`, confirm your own identity with `entwurf_self`, drain a mailbox with `entwurf_inbox_read`, and use `entwurf_register_native` only as the explicit/manual fallback for binding an already-running agy conversation (normal agy birth is automatic through the installed hook). Open a NEW sibling with **`entwurf_fresh_call {backend, model, task, cwd?, placement?}`**, and reopen a DORMANT pi citizen under its own garden id with **`entwurf_resume_call {target}`**. Fresh call accepts one optional literal absolute `cwd`: omit it or pass `""` for the caller's cwd; otherwise it must name an existing directory and may not contain `#`. Use that input for a new cross-repository sibling — resume preserves a dormant Pi citizen's recorded continuity and is not a cwd substitute. Fresh call also accepts one optional `placement.tmuxSession`: the exact name of an EXISTING session on the caller's own tmux server, so the sibling opens in the operator's project seat rather than beside the caller. It creates nothing — an absent session is refused as `tmux-session-missing`, a name outside `[A-Za-z0-9][A-Za-z0-9_-]*` as `tmux-session-name-invalid`, and no window and no session are left behind either way. The seat and the `cwd` never infer each other: with `cwd` omitted a seated sibling starts in the CALLING agent's own directory, not the target session's path. Fresh call needs its selected runtime on the server's PATH (`pi`, `claude`, `entwurf` or `omp` — Copilot opens through the managed `entwurf copilot` invocation, never the bare vendor, while OMP is opened as the bare `omp` runtime); resume call always needs `pi`. Both start a runtime, while delivery does not. (The old v1 verbs `entwurf` / `entwurf_resume` / `entwurf_send` are gone.)
+**Which verb an external agent should reach for:** to deliver to / reply to a garden id, use **`entwurf_v2`** — it is the canonical delivery surface and the only one that reads whether the target is live pi, dormant pi, a mailbox-backed self-fetch citizen (Claude Code, Copilot, OMP), or native-push Antigravity/Codex and routes correctly. Discover targets with `entwurf_peers`, confirm your own identity with `entwurf_self`, drain a mailbox with `entwurf_inbox_read`, and use `entwurf_register_native` only as the explicit/manual fallback for binding an already-running agy conversation. Open a NEW sibling with **`entwurf_fresh_call {backend, model, task, cwd?, placement?}`**, and reopen a DORMANT pi citizen under the same id with **`entwurf_resume_call {target}`**.
 
-Observed: Claude Code, Codex CLI, Antigravity CLI, GitHub Copilot CLI and OMP all reach the read surfaces through this MCP bridge from a plain external host — `entwurf_peers` is a pure fact projection, while `entwurf_inbox_read` is a **mutating drain** (it archives the messages and stamps the read-receipt), so "read" here does not mean side-effect-free; **sending** needs an identity lane. Claude, Copilot and OMP become symmetric/replyable through a mailbox-backed meta-session — Claude's watch armed by its own hook, Copilot's by the forked extension it installs, OMP's by an extension running inside the operator's own TUI process; agy becomes symmetric/replyable through its record-backed sender marker plus live native-push probe. Codex has no managed citizen lifecycle yet, so a Codex host cannot send without the explicit anonymous hatch below.
+Observed: Claude Code, Codex CLI, Antigravity CLI, GitHub Copilot CLI and OMP all reach this MCP bridge. Claude, Copilot and OMP become symmetric/replyable through mailbox-backed meta-sessions; agy and Codex use native-push. Codex's identity is request-scoped `_meta.threadId`, and its replyability requires that exact record plus a loaded app-server thread. Plain external hosts still need an identity lane to send.
 
 Prerequisites on the host running the external MCP client:
 
 - A live pi session launched with `--entwurf-control` populates `~/.pi/entwurf-control/<gardenId>.sock` — the key is the **record's** garden id, never a transcript/session id (`PI_SESSION_ID` only carries the id record birth already established). Required for `entwurf_v2` control-socket dispatch and `entwurf_peers`.
 
-> **PATH boundary.** MCP servers are often launched by GUI/editor daemons and may not inherit the interactive shell's PATH. No `entwurf_v2` rail launches a process, so this does not affect delivery — but `entwurf_fresh_call` and `entwurf_resume_call` do open a fixed runtime. If that runtime works in your terminal but an external-host call fails with `spawn pi ENOENT`, `spawn claude ENOENT`, `spawn entwurf ENOENT`, or `spawn omp ENOENT`, pass a full PATH in the MCP server `env`, set `ENTWURF_BRIDGE_ENV_FILE` to a small shell file that exports PATH, or point the host at a wrapper that can find the runtime. `start.sh` sources only the explicit `ENTWURF_BRIDGE_ENV_FILE`; it never reads personal dotfiles automatically.
-
-> **Identity-carrier boundary.** A complete `PI_SESSION_ID` + `PI_AGENT_ID` pair wins before a
-> native sender marker in the bridge's authoritative-self resolution. Those variables are correct
-> inside the pi process that planted them from record birth; they are foreign identity in another
-> native harness. Starting that harness from a pi citizen's bash can otherwise make the new host —
-> and any internal agents borrowing its MCP manager — speak under the parent pi garden id. Every
-> managed native launcher therefore removes both variables before exec and lets the launched
-> harness establish its own identity through its trusted birth marker. Clearing only one is not a
-> repair: an incomplete pair merely changes the failure wording, while retaining either carrier
-> invites future partial-reader drift. An unmanaged launch that inherits them is unsupported. A
-> native-harness admission made under this contract must add a doctor cell that names this
-> contamination rather than silently preferring the marker.
+> **PATH boundary.** MCP servers are often launched by GUI/editor daemons and may not inherit the interactive shell's PATH. No `entwurf_v2` rail launches a process, so this does not affect delivery — but `entwurf_fresh_call` and `entwurf_resume_call` do open a fixed runtime. If that runtime works in your terminal but an external-host call fails with `spawn pi ENOENT`, `spawn claude ENOENT`, `spawn entwurf ENOENT`, `spawn omp ENOENT`, or `spawn codex ENOENT`, pass a full PATH in the MCP server `env`, set `ENTWURF_BRIDGE_ENV_FILE` to a small shell file that exports PATH, or point the host at a wrapper that can find the runtime. `start.sh` sources only the explicit `ENTWURF_BRIDGE_ENV_FILE`; it never reads personal dotfiles automatically.
+
+> **Identity-carrier boundary.** The bridge reconciles every authoritative claim available to
+> the request: the complete `PI_SESSION_ID` + `PI_AGENT_ID` pair, a native sender marker, and
+> Codex request `_meta`. Zero claims is refused; multiple claims must name the same garden id or
+> the call throws. Nothing silently wins. Those pi variables are correct only inside the pi
+> process that planted them from record birth; they are foreign identity in another native
+> harness. Every managed fresh launch therefore empties both variables at the tmux seam and lets
+> the launched harness establish its own identity. Clearing only one is not a repair: an
+> incomplete pair is itself invalid, while retaining either carrier invites future reader drift.
+> An unmanaged launch that inherits them is unsupported. A native-harness admission must add a
+> doctor or request-level contract that names contamination rather than trusting precedence.
 >
-> **Certified so far: Copilot only** (#82 RAIL 9). `scripts/copilot-launch.sh` unsets both before
-> `exec`, `check-copilot-launch` asserts their absence from the vendor's OWN report of its
-> environment (and that clearing one alone does not pass), and `doctor-copilot-receive` reports any
-> live Copilot CLI still carrying either as RED on its own axis — a session can be perfectly armed
-> and still speak under the parent's garden id, so the flag verdict must not absorb it. The other
-> native launchers have NOT been certified against this failure mode; do not read Copilot's cells
-> as coverage for them.
+> **The defenses are layered.** Copilot's managed launcher unsets both carriers before `exec`,
+> and `doctor-copilot-receive` detects a contaminated live CLI. The shared fresh-call tmux seam
+> empties them for every backend. OMP retains its process-environment doctor for manually opened
+> sessions. Codex's request-level reconciler adds a different last line: a foreign pi claim and
+> `_meta.threadId` claim cannot coexist under different garden ids. These are complementary;
+> no backend's cell is evidence for another's unmanaged launch.
 >
 > **OMP has both halves, and the strip one is not an omp launcher** (#87 Bundle C). entwurf still
 > owns no managed omp invocation — the bare vendor runtime IS this harness's clause 1 answer, and
 > nothing here argues for a wrapper. The strip sits one level up instead, at the shared launch seam
 > every `entwurf_fresh_call` backend passes through: `SCRUBBED_INHERITED_ENV` empties
 > `PI_SESSION_ID` and `PI_AGENT_ID` on the `new-window` argv itself
-> (`pi-extensions/lib/mux-fresh-call.ts:402`), for all four backends rather than only the one whose
+> (`pi-extensions/lib/mux-fresh-call.ts`), for all five backends rather than only the one whose
 > measurement surfaced it, because the leak is a property of tmux and not of a vendor. `-e VAR=`
 > sets the variable empty rather than unsetting it — tmux has no per-window unset — and every
 > carrier reader trims and tests truthiness, so empty and absent are the same answer by
@@ -78,16 +76,16 @@ Then add it to the external MCP config:
 }
 ```
 
-**Anonymous sender hatch (explicit, documented — never a default).** The bridge refuses an `entwurf_v2` send when the process has neither pi-session env (`PI_SESSION_ID` + `PI_AGENT_ID`) nor a trusted meta-sender marker (#50 C4). A deliberately-anonymous external host — e.g. a Codex CLI wiring, which has no managed citizen lifecycle — may opt out by adding `"ENTWURF_BRIDGE_ALLOW_ANONYMOUS_SENDER": "1"` to the MCP server `env`. The cost is honest and fixed: the send lands with `origin: "external-mcp"`, `replyable: false` (there is no reply address), and `wants_reply: true` stays pointless. The retired opt-in `ENTWURF_BRIDGE_REQUIRE_META_SENDER` is no longer read — its demand became the default, so a stale copy in an old install env is inert.
+**Anonymous sender hatch (explicit, documented — never a default).** The bridge refuses an `entwurf_v2` send when the process has neither pi-session env nor a trusted native identity claim. A deliberately-anonymous plain external host may opt out by adding `"ENTWURF_BRIDGE_ALLOW_ANONYMOUS_SENDER": "1"` to the MCP server `env`. The cost is honest and fixed: the send lands with `origin: "external-mcp"`, `replyable: false`, and `wants_reply: true` stays pointless. A managed Codex citizen does **not** use this hatch; request `_meta` supplies its authoritative identity.
 
 Emergency/manual workaround when the MCP server environment is wrong but an existing entwurf session must be resumed: run `pi --session /path/to/entwurf.jsonl ...` from an interactive shell whose PATH is known-good. Treat this as a debug escape hatch, not a replacement for fixing the MCP launch environment.
 
 External/meta-session semantics:
 
 - `entwurf_v2` from a plain external host is **refused by default** (no authoritative sender — #50 C4). With the explicit `ENTWURF_BRIDGE_ALLOW_ANONYMOUS_SENDER=1` hatch it delivers with `origin: "external-mcp"` / `replyable: false`; there is still no reply address.
-- `entwurf_v2` from a trusted meta-session delivers with `origin: "meta-session"`, and `replyable` is **derived from that sender's own rail — not granted by being trusted**: a self-fetch sender (Claude Code, Copilot, OMP) is replyable only while its receiver is live and armed, and a native-push sender (Antigravity) only while its adapter probe finds the live conversation. Identity survives either way; only `replyable` drops to `false`. When it is `true`, `wants_reply: true` is allowed and the receiver can reply to the sender's garden id.
+- `entwurf_v2` from a trusted meta-session delivers with `origin: "meta-session"`, and `replyable` is **derived from that sender's own rail — not granted by being trusted**: a self-fetch sender (Claude Code, Copilot, OMP) is replyable only while its receiver is live and armed; Antigravity requires a live native probe; Codex requires a matching request-scoped record and loaded app-server thread. Identity survives either way; only `replyable` drops to `false`.
 - `entwurf_v2` never launches a process, so no delivery path needs `pi` on PATH. A dormant pi target is refused as `dormant-fire-forget-unsupported`: the hidden background resume that used to answer there was withdrawn under the visible-first rule, and re-opening the session is the separate `entwurf_resume_call` verb — which DOES need `pi` on PATH, because it starts one.
-- `entwurf_self` returns the same authoritative identity for pi sessions **and** trusted meta-sessions. A plain external host with no pi env and no trusted sender marker still fails because there is no reply address to report.
+- `entwurf_self` returns the same authoritative identity for pi sessions **and** trusted meta-sessions. A plain external host with no pi env, native marker, or Codex request claim still fails because there is no reply address to report.
 
 #### Claude Code
 
@@ -129,14 +127,37 @@ Claude Code reads `~/.mcp.json` in addition to `~/.claude.json`'s top-level `mcp
 
 #### Codex CLI
 
-Add the server to `~/.codex/config.toml`:
+Use the owned surfaces rather than editing `~/.codex/config.toml`:
 
-```toml
-[mcp_servers.entwurf-bridge]
-command = "/absolute/path/to/entwurf/mcp/entwurf-bridge/start.sh"
+```bash
+entwurf install-codex-birth
+entwurf install-codex-mcp
+entwurf install-codex-statusline
+
+entwurf doctor-codex-birth
+entwurf doctor-codex-mcp
+entwurf doctor-codex-statusline
+```
+
+The birth unit owns a `SessionStart` declaration in `$CODEX_HOME/hooks.json`, which the vendor
+runs only after the operator trusts it once in a visible Codex; the other two units own
+only `[mcp_servers.entwurf-bridge]` and the `thread-title` status-line member. The MCP
+entry carries `ENTWURF_BRIDGE_NATIVE_HOST=codex`, which tells the bridge to require and
+reconcile Codex request `_meta`. Do not add the anonymous hatch.
+
+Native receive and visible fresh require the operator-owned default app-server. Entwurf
+does not start or supervise it:
+
+```bash
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+codex app-server --listen "unix://$CODEX_HOME/app-server-control/app-server-control.sock"
 ```
 
-Codex has no managed citizen lifecycle (no sender marker), so this wiring can read `entwurf_peers`/`entwurf_inbox_read` but `entwurf_v2` sends are refused by default (#50 C4). To send anonymously anyway, add the explicit hatch to the same block: `env = { ENTWURF_BRIDGE_ALLOW_ANONYMOUS_SENDER = "1" }` — the send is then marked external/non-replyable (see the hatch paragraph above).
+Birth occurs on the first turn, not window open. It mints
+`record.nativeSessionId = threadId` and sets the visible thread title to the garden id.
+`entwurf_v2` probes the loaded-thread list and sends once through `codex queue`; it never
+retries. `entwurf_fresh_call` accepts `backend: "codex"` after all three owned units and
+the default socket pass preflight. Codex remains outside ACP and has no resume surface.
 
 #### Antigravity CLI (`agy`)
 
@@ -169,6 +190,7 @@ Use the managed install surface rather than editing omp's files by hand:
 ```bash
 entwurf install-omp-bridge     # the BIRTH extension (a garden id per visible TUI session)
 entwurf install-omp-mcp        # the MCP hand (this section)
+entwurf install-omp-config     # the operator setting (tools.xdev: false)
 entwurf install-omp-receive    # the RECEIVER extension (mailbox watch + announce-only doorbell)
 
 entwurf doctor-omp-bridge
@@ -176,7 +198,7 @@ entwurf doctor-omp-mcp
 entwurf doctor-omp-receive
 ```
 
-Three units, not two. The receiver is what makes the citizen answerable at all — without it omp
+Four units, not two. The receiver is what makes the citizen answerable at all — without it omp
 sends under its own garden id and every reply is refused as `mailbox-undeliverable` — and it is
 also a prerequisite of visible fresh: the fresh preflight refuses this host before touching tmux
 when the receive unit is missing, rather than opening a window that can never be reached.
@@ -244,7 +266,8 @@ bridge registered, **11 devices**: omp's own `ast_edit`, `debug`, `lsp`, `browse
 seven `entwurf_*`. So the default does not merely wrap entwurf — it wraps omp's own LSP and
 debugger too.
 
-**Set this on any omp host that is meant to work as a citizen:**
+**`entwurf setup` writes this for a detected omp host, and `entwurf install-omp-config` is
+the repair leaf. The value they own:**
 
 ```yaml
 # ~/.omp/agent/config.yml

package/docs/fresh-cut-policy.md

@@ -22,7 +22,8 @@ the new generation.
 ## What certification checks
 
 `certifyActiveStore` is shared by the doctor and all identity writers: pi birth,
-Claude's `SessionStart`, agy's imprint, and `entwurf_register_native`. Every active
+Claude's `SessionStart`, Copilot's first-prompt birth hook, OMP's birth extension,
+agy's imprint, and `entwurf_register_native`. Every active
 record must be:
 
 - a regular, non-symlink `.meta.json` file;
@@ -43,7 +44,7 @@ are opened without following symlinks; implementation and race proofs live besid
 
 ## Running a cut
 
-First close every pi, Claude Code, and agy session that could own a citizen or
+First close every pi, Claude Code, Copilot, OMP, and agy session that could own a citizen or
 transport artifact. Then run:
 
 ```bash

package/docs/setup-clean-host.md

@@ -8,8 +8,8 @@ evidence split, and its three states must not collapse into "macOS is supported"
   (`macos-install-surface`). Weaker than a physical-host doctor green. §1 is
   this surface.
 - **NOT CERTIFIED — pending physical host** — **on macOS**, every garden-native
-  harness rail in §2–§6 (pi, Claude, Copilot, OMP, agy), marker join, ACP turn,
-  mux. Wiring may be written; that is not a rail receipt. The remaining
+  harness rail in §2–§6 (pi, Claude, Copilot, OMP, agy, Codex), marker/request join,
+  ACP turn, mux. Wiring may be written; that is not a rail receipt. The remaining
   unmeasured Darwin doctor reason is per-process environment DISCOVERY
   (start-key is portable).
 - **UNSUPPORTED** — native Windows only. macOS is never this.
@@ -20,13 +20,14 @@ evidence split, and its three states must not collapse into "macOS is supported"
 |---|---|---|
 | Node | **`>=24.0.0`** | package and bridge runtime |
 | npm/pnpm | npm is bundled with Node; pnpm is required for source setup | package or source installation |
-| Python 3 | required by `setup`/`install` (project-path normalization + settings writers); `--help`/`check-bridge` stay Python-free | pi/Claude/agy/Copilot wiring writers |
+| Python 3 | required by `setup`/`install` (project-path normalization + settings writers); `--help`/`check-bridge` stay Python-free | pi/Claude/agy/Copilot/Codex wiring writers |
 | entwurf | global/project-local `@junghanacs/entwurf`, or a source checkout | operator command and garden capability |
 | pi | optional-by-presence, `>=0.85.1 <0.86` — absent is an explicit setup SKIP, below-floor is a named FAIL | ACP provider, control sockets |
 | Claude Code | optional, **`>=2.1.217`** — the exec-form hook floor | Claude ACP auth/runtime and mailbox-backed native citizen |
 | GitHub Copilot CLI | optional-by-presence, operator-installed and authenticated — absent is an explicit setup SKIP; detected composes all four units (birth/MCP/receiver/footer) | self-fetch citizen and visible fresh |
 | OMP (`omp`) | optional-by-presence, operator-installed — absent is an explicit setup SKIP; detected composes all four units (birth/MCP/`tools.xdev` setting/receiver) | self-fetch citizen and visible fresh (accepted on one host — see §4b) |
 | Antigravity `agy` | optional, operator-installed and authenticated | native-push citizen |
+| OpenAI Codex CLI | optional-by-presence, operator-installed and authenticated; detected composes all three operator-owned units (birth/MCP/status-line) and stays non-green until the operator trusts the birth declaration once in a visible Codex; visible fresh also requires an operator-owned existing tmux session named `codex`, with its app-server and supported TUIs seated there | native-push and visible fresh, supported in 0.21.0 |
 | Cortex Code | optional, operator-installed and authenticated | Cortex ACP backend |
 
 Claude Code >=2.1.217 is required for the managed exec-hook lifecycle. The package
@@ -52,9 +53,9 @@ harness. The wiring is written; the row is FAIL:
 > platform. Tracking: #78.
 
 That FAIL is honest: setup runs no doctor, and no physical-host rail
-receipt exists — it is not an install failure. An Entwurf-only host (no
-harness on PATH) stays green (five SKIP, `bins: PASS`, `core: PASS`,
-`result: green`), which is what CERTIFIED (CI) observed.
+receipt exists — it is not an install failure. An Entwurf-only host with no
+harness on PATH stays green (six SKIP, `bins: PASS`, `core: PASS`,
+`result: green`), which is what CERTIFIED (CI) observes.
 
 A physical Mac can send host facts without installing entwurf or logging
 into a harness: `scripts/raw-macos-measure/probe.sh` (`/bin/sh`, ~3.5s,
@@ -91,10 +92,10 @@ npx entwurf check-bridge
 `check-bridge` is auth-free. It proves the installed prebuilt MCP server boots and
 lists the seven garden tools; it does not prove a backend model turn or native hook.
 
-Neither npm form installs a harness runtime. `pi`, Claude Code, Copilot CLI, agy, Cortex and their
-authentication remain operator-owned optional prerequisites for the integrations that use them;
-all may be absent on an Entwurf-only host. A source checkout's pinned Pi development packages are
-for building and testing this repo, not a transitive product installation promise.
+Neither npm form installs a harness runtime. `pi`, Claude Code, Copilot CLI, Codex CLI, agy,
+Cortex, and their authentication remain operator-owned optional prerequisites for the
+integrations that use them; all may be absent on an Entwurf-only host. A source checkout's
+pinned Pi development packages are for building and testing this repo, not a transitive product installation promise.
 
 Maintainers using a source checkout do not install a second global entwurf package. Full source
 setup currently requires Node 24, pnpm, and Python 3 on PATH; every harness — including pi — is
@@ -109,12 +110,14 @@ cd ~/repos/gh/entwurf
 
 This owns `~/.local/bin/entwurf` as a symlink to that checkout's `run.sh` and fails if the
 link is foreign, outside PATH, or shadowed by another command. It detects and wires
-pi/Claude/agy/Copilot/OMP by presence and prints a computed per-component PASS/SKIP/FAIL summary — a
-detected harness that cannot be completed makes setup exit nonzero. A detected `copilot`
-composes all four native units (birth → MCP → receiver → visible footer) with independent
-per-unit verdicts (#86 C3b), and a detected `omp` composes its own four (birth → MCP →
-`tools.xdev` setting → receiver) the same way; §4 and §4b keep the explicit per-unit
-install/doctor/inverse surfaces for repair.
+pi/Claude/agy/Copilot/OMP/Codex by presence and prints a computed per-component
+PASS/SKIP/FAIL summary — a detected harness that cannot be completed makes setup exit nonzero.
+A detected `copilot` composes all four native units, and a detected `omp` composes its own four.
+A detected Codex install is a supported 0.21.0 path: setup composes its user-scope birth,
+MCP, and status-line atoms but never escalates or starts the app-server. It reports independent
+component outcomes, preserves exact env forwarding and idempotence, and returns a named
+`codex-birth FAIL` until the vendor trust receipt exists.
+§4, §4b, and §4c keep the explicit per-unit install/doctor/inverse surfaces.
 
 ### 1.1 User-scope ownership (one shared registration, one recorded owner)
 
@@ -396,6 +399,92 @@ The MCP entry deliberately uses the same server key as any Claude Code import so
 SHADOWS it; see [`external-mcp-host.md`](./external-mcp-host.md) for why that key is pinned and
 why `disabledServers` is never the way to hide an import.
 
+## 4c. Optional OpenAI Codex CLI native citizen
+
+Supported in 0.21.0 with Linux-focused evidence; on macOS it is NOT CERTIFIED —
+pending physical host. It is native, not ACP: the purpose is to preserve the operator's
+Codex tools, delegation, and work context rather than provide another GPT access path.
+Entwurf owns three atoms, not the harness and not a daemon:
+
+```bash
+# All three are operator-scope; `entwurf setup` runs them when it detects Codex. No root.
+entwurf install-codex-birth
+entwurf install-codex-mcp
+entwurf install-codex-statusline
+
+entwurf doctor-codex-birth
+entwurf doctor-codex-mcp
+entwurf doctor-codex-statusline
+```
+
+The birth atom publishes a `SessionStart` declaration into `$CODEX_HOME/hooks.json` with its
+launcher closure under `$XDG_DATA_HOME/entwurf/codex-birth`; it mints a V3 record on the
+thread's first turn and sets the thread title to the garden id.
+
+**One step is the operator's, and no command can do it for them.** The vendor will not run a
+user-layer hook until it has been trusted once: open a visible plain Codex, answer
+`Trust all and continue`, then send one first turn. `doctor-codex-birth` reads the receipt the
+vendor writes for that declaration and is RED without it — entwurf never writes, pre-seeds or
+recomputes that value, because it is the operator's security decision, not ours. After the one
+answer, later sessions raise no prompt and are born automatically. The MCP writer owns
+`[mcp_servers.entwurf-bridge]` in `$CODEX_HOME/config.toml`. Its exact `env_vars` allowlist is
+`CODEX_HOME`, `ENTWURF_DIR`, `PI_CODING_AGENT_DIR`, `ENTWURF_META_SESSIONS_DIR`,
+`ENTWURF_META_MAILBOX_DIR`, `ENTWURF_META_SENDERS_DIR`, `ENTWURF_META_RECEIVERS_DIR`,
+`TMUX`, and `TMUX_PANE`.
+The status-line writer owns only `thread-title`. Foreign or symlinked config is refused.
+
+Native delivery requires the operator-owned default app-server and one existing tmux session
+named exactly `codex`. Start the app-server from a pane there and seat supported Codex TUIs there:
+
+```bash
+# Run these commands inside the operator-owned tmux session named exactly `codex`.
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+mkdir -p "$CODEX_HOME/app-server-control"
+codex app-server --listen "unix://$CODEX_HOME/app-server-control/app-server-control.sock"
+codex --remote "unix://$CODEX_HOME/app-server-control/app-server-control.sock"
+```
+
+Omitted Codex fresh placement resolves exact `codex` on the caller's tmux server. The app-server's
+`TMUX`/`TMUX_PANE` is forwarded to its MCP child, so a Codex citizen's omitted outbound Pi placement
+stays in that home. It is **not** an arbitrary attached-TUI pane join. Exact Codex 0.153.4 source
+exposes no request→attached-TUI-seat carrier, so clients attached from other sessions have no
+adjacency claim; that wider topology is unsupported and unclaimed. Entwurf does not guess panes,
+create the tmux home, expose a generic app-server manager/API, or start/restart the server. Custom
+`CODEX_HOME` and Entwurf roots cross the same explicit `env_vars` boundary. Strict request `_meta`
+identifies the thread caller, not its seat. Delivery uses one `codex queue` invocation with no retry.
+
+The 2026-09-11 loaded-thread run remains pre-amendment native-push/identity evidence. The final
+first-admission acceptance passed on 2026-09-12: real initial Pi outside `codex`, then omitted-placement
+Codex and outbound Pi inside it, with exact callbacks and addressed delivery both ways. `DELIVERY.md`
+owns the 57-assertion receipt, four coordinates, and digest.
+
+`entwurf_fresh_call` accepts backend `codex` — supported in 0.21.0 — and requires an explicit model. Its
+preflight must prove the safe birth closure, exact MCP/env atom, `thread-title`, and app-server
+socket before tmux mutation. The sibling's garden id comes from the callback sender envelope,
+never the launch receipt. There is no Codex resume surface, watcher, supervisor, or app-server
+lifecycle ownership. The accepted LIVE used a real record-backed visible Pi for the first leg;
+release-gate stripped ambient `PI_SESSION_ID`/`PI_AGENT_ID`, and the fixture/self-fetch citizen only
+collected receipts. The smoke reported initial Pi, app-server, fresh Codex, and outbound Pi
+coordinates separately: the initial Pi differed and the latter three matched the exact `codex` home.
+Qualification and the frozen full floor are complete for this lane: `check-gate-qualification`
+killed 475/475 across 43 lanes with origin purity green, `check:full` exited 0, and the LIVE release
+gate reported MUST 24/0/0 with `cut: OK`. The bounds above are unchanged — no request→arbitrary
+attached-TUI seat join, no resume surface, and macOS remains NOT CERTIFIED pending a physical host.
+
+Oracle runs the first-admission LIVE with explicit ownership/model selectors:
+
+```bash
+LIVE=1 \
+ENTWURF_CODEX_APP_SERVER_PID=<existing-app-server-pid> \
+ENTWURF_CODEX_FRESH_MODEL=<codex-model> \
+ENTWURF_CODEX_FRESH_PI_MODEL=<pi-model> \
+entwurf smoke-codex-fresh-live
+```
+
+Run this from a tmux session other than `codex`. The entrypoint name does not waive the contract
+above. A fixture/self-fetch citizen may collect receipts but cannot replace the real visible Pi leg;
+a Pi that starts inside the Codex home proves only the weaker shared-seat mechanism.
+
 ## 5. Optional Antigravity native citizen
 
 This rail is CERTIFIED on Linux; on macOS it is NOT CERTIFIED — pending
@@ -464,7 +553,7 @@ rail receipt. Doctors refuse on Darwin until a physical-host receipt
 exists.
 
 If install or doctor reports an unreadable/old active citizen generation, do not edit
-records by hand. Close pi, Claude, Copilot, and agy sessions first, run
+records by hand. Close pi, Claude, Copilot, OMP, agy, and Codex sessions first, run
 `entwurf meta-bridge-fresh-cut`, and read its exit status before any install. Then choose the
 installation mode you actually own:
 
@@ -496,6 +585,7 @@ PASS/SKIP/FAIL summary. The complete quiescence, archive, and exit-code contract
 - `scripts/raw-macos-measure/probe.sh`: physical-Darwin host facts (~3.5s,
   no install, no login). Measurement, not a certification path.
 - `doctor-meta-bridge`: one installed real Claude host, only with a new live session.
+- `doctor-codex-{birth,mcp,statusline}` plus `LIVE=1 CODEX_LIVE_THREAD_ID=<id> entwurf smoke-codex-native-push-live`: one installed Codex host; the aggregate does not own a loaded thread.
 - `LIVE=1 entwurf release-gate /path/to/scratch --cut`: aggregate runtime acceptance (`--cut` makes any MUST SKIP red; without it the run is a diagnostic pass).
 
 Keep these verdicts separate. Current protocol is [VERIFY.md](../VERIFY.md); recorded
@@ -519,6 +609,9 @@ entwurf uninstall-copilot-bridge
 entwurf uninstall-agy-hooks
 entwurf uninstall-agy-statusline
 entwurf uninstall-agy-bridge
+entwurf uninstall-codex-statusline
+entwurf uninstall-codex-mcp
+entwurf uninstall-codex-birth
 entwurf remove ~/entwurf-smoke
 # only when no other project uses the shared user-scope pi registration:
 entwurf remove-user-scope