@junghanacs/entwurf 0.15.0 → 0.16.0

package/docs/external-mcp-host.md

@@ -1,25 +1,25 @@
 # Wiring `entwurf-bridge` into an external MCP host
 
-Per-harness registration for Claude Code, Codex CLI, and Antigravity, plus the
-PATH/env boundary and the external vs garden-native semantics. `README.md` keeps only
+Per-harness registration for Claude Code, Codex CLI, Antigravity, GitHub Copilot CLI and OMP,
+plus the PATH/env boundary and the external vs garden-native semantics. `README.md` keeps only
 the one-line registration; everything an operator needs to actually wire a host is here.
 
-`entwurf-bridge` can also be registered in a separate MCP-aware harness (Claude Code, Codex CLI, Antigravity/`agy`, …). That host does **not** become a pi session and does **not** need to be ACP-backed. There are now two honest cases:
+`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. It is not a pi control-socket session, but it can be replyable by garden id when its own mailbox/probe rail says so.
+- **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.
 
   **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, mailbox-backed Claude Code, 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?}`**, 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 needs its selected runtime on the server's PATH (`pi`, `claude`, or `entwurf` — Copilot opens through the managed `entwurf copilot` invocation, never the bare vendor); 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 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?}`**, 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 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.)
 
-Observed: Claude Code, Codex CLI, Antigravity CLI and GitHub Copilot CLI 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 and Copilot 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; 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 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.
 
 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`, or `spawn entwurf 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.
+> **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
@@ -40,6 +40,22 @@ Prerequisites on the host running the external MCP client:
 > 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.
+>
+> **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
+> 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
+> construction. Pinned by `[QK:FRESHCALL-IDENTITY-SCRUB]` in the `check-mux-fresh-call` vitest lane,
+> inside `check:full`. The DETECT half is unchanged and still load-bearing, because a seam covers
+> only the launches that pass through it: `doctor-omp-bridge` reads `/proc/<pid>/environ` for every
+> live `omp` process and goes RED on its own axis when one carries either carrier. An omp the
+> operator started from a pi citizen's bash never touched the seam and is still unsupported, exactly
+> as this boundary says.
 
 Example env file:
 
@@ -66,7 +82,7 @@ Emergency/manual workaround when the MCP server environment is wrong but an exis
 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) 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, 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` 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.
 
@@ -143,9 +159,131 @@ Unrelated servers, permissions, settings, and hooks are preserved; every adapter
 
 The **global** MCP config live agy reads is `~/.gemini/config/mcp_config.json`. `~/.gemini/antigravity-cli/mcp_config.json` is not the global MCP root; the bridge installer one-way cleans only a stale entwurf-owned entry there. After the first model invocation, the imprint hook binds the native `conversationId` to a garden id, the statusline shows `🪛 <garden-id> agy`, and sends from that MCP child carry `agentId=meta-session/antigravity` with `replyable:true` only when the record exists and the live native-push probe succeeds.
 
+#### OMP (`omp`, oh-my-pi)
+
+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-receive    # the RECEIVER extension (mailbox watch + announce-only doorbell)
+
+entwurf doctor-omp-bridge
+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
+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.
+
+`install-omp-mcp` writes ONE server into omp's own user MCP file,
+`<omp agent dir>/mcp.json` (`~/.omp/agent/mcp.json`, profile-aware), in omp's own writer
+shape — `{command, args?, env?}` with `type` omitted, since stdio is the default:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
+  "mcpServers": {
+    "entwurf-bridge": {
+      "command": "bash",
+      "args": ["/absolute/path/to/entwurf/mcp/entwurf-bridge/start.sh"],
+      "env": { "ENTWURF_BRIDGE_EXTERNAL_AGENT_ID": "external-mcp/omp" }
+    }
+  }
+}
+```
+
+**The server key is a pinned literal, and that is the whole point.** omp translates Claude
+Code's `~/.claude.json` as an import provider, so a host that ever used Claude Code already
+has an `entwurf-bridge` — carrying `external-mcp/claude-code`. An omp session riding that
+import introduces itself to the bridge under Claude Code's name. Writing the native entry
+under the byte-identical key shadows it: native provider priority 100 beats claude 80,
+dedupe is first-wins on the server NAME, and on a key hit the equivalence check is never
+consulted, so an entry whose env deliberately differs still suppresses the import outright
+— not both-loaded, not merged, no warning. A different key would load BOTH.
+`[측정]` 2026-08-27, omp/18.0.0: the vendor's own `/mcp list` pane flipped from
+`Claude Code (~/.claude.json): entwurf-bridge ● connected` to
+`User level (~/.omp/agent/mcp.json): entwurf-bridge ● connected [stdio]`, and the spawned
+bridge child's environ flipped with it.
+
+**`disabledServers` is never the way to hide the import.** Suppression is by name and a
+suppressed item still claims the dedupe key, so denylisting `entwurf-bridge` kills the
+native entry and the import together. `[측정]` with that denylist the pane shows
+`entwurf-bridge ○ not connected` and no Claude Code section at all, and no MCP child is
+spawned. The installer refuses to write into a config that denylists its own key, and
+`doctor-omp-mcp` is red while one exists.
+
+**The tool names are omp's dialect, not Claude's.** omp mints `mcp__<server>_<tool>` after
+lowercasing and replacing every `[^a-z_]+` run with `_`, collapsing runs and trimming edges,
+so `entwurf_v2` surfaces as `mcp__entwurf_bridge_entwurf_v` — the trailing digit is eaten by
+the charset, not by the length cap. The live tool list is the acceptance oracle; a live
+session mounts all seven.
+
+**And the NAME is not the invocation. Under omp's default settings an MCP tool is not a
+function the model calls — it is a virtual file it writes to.** `tools.xdev` (boolean,
+**default on**) mounts "discoverable" tools as `xd://<tool>` devices and DROPS them from the
+top-level toolset; the model then reads `xd://<tool>` for the schema and *writes* the JSON
+argument object to `xd://<tool>` to execute it. `tools.xdevDocs` (**default `builtins`**)
+keeps built-in docs inline while MCP and extension schemas stay off-prompt until read. That
+default costs a real capability. `[측정]` 2026-08-28, omp/18.0.0: with the defaults, a plain
+"send this message to garden id X" produced a `write` to `xd://…entwurf_peers` (a LISTING)
+and then the sentence "보냈습니다" — no `entwurf_v2` call, nothing enqueued, `lastEnqueuedAt`
+unchanged. Discovery and delivery share one verb (`write`) and neither schema was in the
+prompt. The vendor has hit the same shape in its own toolset: its changelog records
+`web_search` becoming unreachable under `tools.xdev: true` because the mount dropped it from
+top-level (`Tool web_search not found`, upstream #5973), fixed by pinning it via
+`XDEV_KEEP_TOP_LEVEL` — a pin no MCP tool has.
+
+`read xd://` reports exactly what the default hides. `[측정]` on a host with only this
+bridge registered, **11 devices**: omp's own `ast_edit`, `debug`, `lsp`, `browser`, plus all
+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:**
+
+```yaml
+# ~/.omp/agent/config.yml
+tools:
+  xdev: false      # every enabled tool top-level — MCP is MCP again
+```
+
+Nothing is disabled by that: the setting's own text is *"Disable to expose every enabled tool
+top-level"*, and it moves tools rather than removing them. `[측정]` with `xdev: false` the
+same plain-language request produced a first-try `mcp__entwurf_bridge_entwurf_v` function
+call carrying a correct `intent`, the marker landed in the target mailbox, `read xd://`
+answered `xd:// is not mounted in this session.`, and `lsp` / `debug` / `browser` /
+`ast_edit` were all present top-level. The cost is prompt size: the system prompt's
+non-message tokens went 18,707 → 21,834 (+3,127, +17%) on that host.
+
+Two boundaries worth carrying:
+
+- **`xd://` resolution devices survive the switch.** omp's plan mode and every staged-action
+  finalization write to `xd://propose` / `xd://resolve` / `xd://reject`, and its plan prompt
+  names them unconditionally — so "turn xdev off" looks like it should break planning. It
+  does not: the write dispatcher matches the resolution devices BEFORE the mount check.
+  `[측정]` with `xdev: false`, plan mode reached `write xd://propose` and the approval dialog
+  normally.
+- **The narrow alternative keeps the wrapper.** `tools.xdevInlineDevices:
+  ["mcp__entwurf_bridge_*"]` inlines only our schemas (+1,013 tokens instead of +3,127) and
+  also fixed the send in the same measurement — but the 11 devices stay off top-level, `lsp`
+  included, and the listing/delivery verb stays shared. Prefer it only on a host carrying so many MCP servers
+  that the full top-level toolset is the larger problem.
+
+All of the above is measured against omp 18.0.0 and is a setting, not a contract: re-measure
+at a vendor upgrade.
+
+Registration is tools, not identity: sending needs the birth extension
+(`install-omp-bridge`), whose sender marker is keyed to the omp host's OWN pid — omp runs
+its extensions in-process, so the marker's owner, the host, and the MCP child's parent are
+one pid rather than the two-process join Claude and Copilot have. An omp session is a
+citizen only in the operator-visible TUI; task subagents borrow its tools under its garden
+id and never receive a second address.
+
 #### External-host skills and commands
 
-MCP registration gives the external harness the tools; the host still needs workflow guidance. Put the Mitsein-over-MCP (cross-harness collaboration) rules in that host's instruction file or, when supported, as a host-native skill. Do not assume pi slash commands are portable across external hosts — if a workflow must work across Claude Code, Codex CLI, Antigravity, and future hosts, make it a skill or MCP tool rather than a command shortcut.
+MCP registration gives the external harness the tools; the host still needs workflow guidance. Put the Mitsein-over-MCP (cross-harness collaboration) rules in that host's instruction file or, when supported, as a host-native skill. Do not assume pi slash commands are portable across external hosts — if a workflow must work across Claude Code, Codex CLI, Antigravity, OMP, and future hosts, make it a skill or MCP tool rather than a command shortcut.
 
 For the maintained multi-harness setup and skill/command packaging details, see
 [agent-config](https://github.com/junghan0611/agent-config). See also the

package/docs/setup-clean-host.md

@@ -9,10 +9,13 @@ only on Linux because its strict live-owner join uses `/proc`.
 | Component | Requirement | Needed for |
 |---|---|---|
 | Node | **`>=24.0.0`** | package and bridge runtime |
-| npm | bundled with Node | package installation |
-| entwurf | `@junghanacs/entwurf` | all lanes |
-| pi | optional, `@earendil-works/pi-coding-agent >=0.84.3 <0.85` | ACP provider, control sockets |
+| 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 |
+| entwurf | global/project-local `@junghanacs/entwurf`, or a source checkout | operator command and garden capability |
+| pi | optional-by-presence, `>=0.84.3 <0.85` — 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, operator-installed; three units (birth/MCP/receiver) plus `tools: xdev: false` in the agent config | self-fetch citizen and visible fresh (accepted on one host — see §4b) |
 | Antigravity `agy` | optional, operator-installed and authenticated | native-push citizen |
 | Cortex Code | optional, operator-installed and authenticated | Cortex ACP backend |
 
@@ -51,6 +54,56 @@ 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.
+
+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
+optional-by-presence (absent → explicit SKIP, detected but below the supported floor → named FAIL
+with a nonzero setup result):
+
+```bash
+git clone https://github.com/junghan0611/entwurf ~/repos/gh/entwurf
+cd ~/repos/gh/entwurf
+./run.sh setup /path/to/consumer-project
+```
+
+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 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); §4 keeps the explicit per-unit install/doctor/inverse surfaces for
+repair.
+
+### 1.1 User-scope ownership (one shared registration, one recorded owner)
+
+The GLOBAL pi user-scope registration (`~/.pi/agent/settings.json` `packages[]` plus the
+`entwurfProvider.mcpServers.entwurf-bridge` key) is ONE shared entry across every install root, and
+it carries a recorded owner: `packageRoot` in `$XDG_DATA_HOME/entwurf/pi-package/install-state.json`
+and `installerRoot` in the provider install-state. Normal `install`/`setup` from a different root —
+whether the recorded owner is live or missing — refuses with zero settings bytes written; the only
+writer that moves the shared entry is the operator-explicit `entwurf takeover-user-scope`
+(old→new reported). Every user-scope operation is ATOMIC across the two halves: both ownership
+preflights run read-only first, so a refusal on either side leaves the other byte-identical. A
+takeover over an operator's own provider override is a SPLIT verdict — the package owner moves,
+the override is preserved and stays unowned (its stale ownership state is cleared), never a false
+"both owned". A LEGACY provider state (no `installerRoot`) accepts no inverse: run `setup`/`install`
+from the owning root first (named adoption), then remove. Both install-states also bind the exact
+settings file they manage (`managedSettingsPath`): pointing an operation at a different, symlinked
+or unparseable file refuses with zero writes before either half proceeds, and the owned/orphan
+inverse removes only the recorded owner's exact `packages[]` entry (0 or 2+ exact entries refuse).
+`entwurf doctor-pi-package` names the package-side verdict including the
+packageRoot↔installerRoot coupling mismatch and a package/provider managed-path mismatch.
+
+| Root shape | Package root written | Stable commands from | Project write | User write | Takeover trigger | Inverse | Stale/moved verdict |
+|---|---|---|---|---|---|---|---|
+| source checkout | the checkout dir | `dev-bin` symlinks (`setup`) | `<project>/.pi/settings.json` | shared entry + owner state | `takeover-user-scope` from the new checkout | `remove` (project) / `remove-user-scope` (global, same-owner-only) | `doctor-pi-package` → `missing-owner`; normal install still refuses |
+| global npm (`npm i -g`) | the global `node_modules/@junghanacs/entwurf` | npm bin linking | same | same shared entry | same explicit action | same; a LIVE foreign owner always refuses | same |
+| project-local npm | that project's `node_modules/@junghanacs/entwurf` | `node_modules/.bin` | same | same shared entry | same explicit action | same | same; a deleted root becomes the aligned `remove-user-scope` orphan cleanup (entry + package state + provider installerRoot must all name that missing root) |
+
 ## 2. Optional pi adapter / ACP plugin
 
 Install the exact release floor, then wire the project:
@@ -109,7 +162,135 @@ New macOS wiring is refused because the live join is not instrumented there. Dar
 uninstall remains available for cleaning an older managed install; this is an evidence
 boundary, not a permanent impossibility claim.
 
-## 4. Optional Antigravity native citizen
+## 4. Optional GitHub Copilot CLI native citizen
+
+Copilot has four independently owned surfaces. `setup` composes all four when `copilot` is on
+PATH (#86 C3b); the commands below are the per-unit repair, doctor, and inverse surfaces. All
+four must be green for supported visible fresh; a manual citizen may omit the footer, but fresh
+refuses before opening a window when any required surface is absent.
+
+```bash
+entwurf install-copilot-bridge
+entwurf install-copilot-mcp
+entwurf install-copilot-receive
+entwurf install-copilot-statusline
+
+entwurf doctor-copilot-bridge
+entwurf doctor-copilot-mcp
+entwurf doctor-copilot-receive
+entwurf doctor-copilot-statusline
+```
+
+Launch the supported invocation with `entwurf copilot`, not bare `copilot`. It enables extension
+scanning for that process, checks the receiver, removes inherited pi identity carriers, and owns
+the model/permission defaults. Birth occurs on the first prompt. `entwurf_fresh_call` uses this
+same managed invocation and requires the birth, MCP, receiver, and visible-identity preflight.
+
+## 4b. Optional OMP (`omp`) native citizen — accepted on one host
+
+Three independently owned surfaces, and a boundary that is part of the instructions rather
+than a footnote. Birth, visible identity, who-sent, the MCP hand and RECEIVE are landed, and
+`entwurf_fresh_call` opens an omp sibling on all three public surfaces. The clause 7 LIVE
+receipt has been taken: `smoke-omp-fresh-live` went green on 2026-08-30 (omp 18.0.0, one
+model, one accepted run), which is what `docs/adding-a-harness.md` step 9 asks for and why
+that smoke is wired as a release-gate MUST — the label was never allowed to move ahead of the
+evidence, and it moved only once the evidence existed. Read the receipt itself in DELIVERY.md's
+OMP row; what it does NOT establish is multi-host, multi-model, or repeated fresh calls in one
+process. Open omp yourself and it is a two-way citizen either way — it sends under its own
+garden id and a reply lands on it.
+
+The first turn of a fresh omp sibling is a TWO-STAGE BOOTSTRAP, not a positional prompt: the
+launcher carries `{v,target,nonce,task}` on the fixed registered flag `--entwurf-bootstrap`,
+and the installed birth extension waits until the callback tool is actually callable, sends a
+callback-only prompt, and delivers the operator's task only after that exact call succeeds.
+That is a measured correction — the interactive host defers MCP discovery, so a positional
+first turn began before the tool it named existed.
+
+**One operator setting is load-bearing for fresh, not just for receive.** `tools: xdev: false`
+in the omp agent config is checked by the fresh preflight BEFORE any window opens, because the
+vendor default mounts MCP tools as `xd://` devices whose schemas never reach the prompt: a
+sibling launched onto a default-config host would start, look healthy, and be unable to call
+the callback tool at all. A refusal there names `omp-callback-tool-uncallable` and opens
+nothing.
+
+```bash
+entwurf install-omp-bridge     # the birth extension, into <omp agent dir>/extensions/
+entwurf install-omp-mcp        # the omp-native entwurf-bridge server
+entwurf install-omp-receive    # the receiver extension: mailbox watch + doorbell
+
+entwurf doctor-omp-bridge
+entwurf doctor-omp-mcp
+entwurf doctor-omp-receive
+```
+
+Order matters only in one direction: the receiver JOINS the citizen birth mints, and
+announces a tool the MCP hand provides. Install it without them and it will log
+`arm-deferred`, give up after ~20s, and `doctor-omp-receive` will name the missing sibling
+as a note rather than a fault.
+
+**The receiver arms per session, and only for the visible TUI host.** Opening omp arms it;
+`/new` re-arms it for the replacement citizen and retires the previous one; closing omp
+retires it. A task subagent arms nothing. While nothing is armed, dispatch to that garden
+id is the honest `mailbox-undeliverable` refusal — an unarmed receiver is a legible state,
+not a broken one.
+
+The admission work has landed and `setup` still does not compose these: the three omp
+units stay operator-selectable installs, so run them yourself on an omp host.
+
+Both installers resolve the omp agent directory the way omp itself does, and REFUSE rather
+than guess when an inherited `PI_CODING_AGENT_DIR`, `PI_CONFIG_DIR` or `PI_PROFILE` makes it
+ambiguous: omp is a pi fork and reads pi's env vocabulary, so those names no longer say which
+harness they address. Pass `ENTWURF_OMP_AGENT_DIR` if you genuinely mean a non-default one.
+
+Two things the installers deliberately will NOT do. They never adopt an artifact already
+sitting at their path without entwurf's own ownership state — a directory that merely looks
+like our unit could be yours, and adopting it would overwrite it with no way back — so a
+no-state path is a named refusal you resolve by hand. And the MCP writer's target is exactly
+`<resolved omp agent dir>/mcp.json`; there is no path override, so it can never be aimed at
+another tool's config.
+
+**Where an omp citizen's garden artifacts live.** Under `$HOME/.pi/agent/meta-*`, the same
+garden every other citizen uses — and that stays true under `omp --profile work`. omp is a pi
+fork, so the vendor exports `PI_CODING_AGENT_DIR` for every named profile; for entwurf that
+name means pi's persistence root, so honouring it here would put an omp session's record in a
+different store (or in a pi sandbox). For backend omp it is read as the VENDOR's agent dir
+only, and never as a garden root. Its presence on a live omp is normal and is not a fault.
+The four `ENTWURF_META_*` variables remain the way to relocate the garden roots, and for
+backend omp each one must be **absolute or `~`-rooted** (`~` or `~/…`). A relative value is
+refused by name rather than resolved: it would resolve against each process's own working
+directory, and the omp extension and `doctor-omp-bridge` do not share one — the doctor would
+then report on a directory the extension never writes to. A refused value mints nothing and
+turns the doctor's runtime axis red.
+
+**One vendor setting is required, and the default is wrong for a citizen.** omp's
+`tools.xdev` (default ON) mounts MCP tools as `xd://<tool>` devices and removes them from the
+model's top-level toolset, so `entwurf_v2` is reached by WRITING JSON to a virtual file rather
+than by calling a tool — and with `tools.xdevDocs` at its `builtins` default its schema is not
+in the prompt at all. On that default a plain "send this to garden id X" was measured to list
+peers and then CLAIM the send without ever dispatching. Put this in `~/.omp/agent/config.yml`
+and restart the session:
+
+```yaml
+tools:
+  xdev: false
+```
+
+It disables nothing — it exposes every enabled tool top-level, omp's own `lsp`, `debug`,
+`browser` and `ast_edit` included, which the default was hiding as well. Plan mode and staged
+`xd://resolve` / `xd://propose` finalization keep working. The rationale, the numbers and the
+narrower `tools.xdevInlineDevices` alternative are in
+[`external-mcp-host.md`](./external-mcp-host.md).
+
+Birth happens when the TUI OPENS (not on the first prompt, unlike Copilot), and the garden id
+appears on omp's status line as `🪛 <garden-id> omp`. `/new`, fork and in-TUI resume mint the
+replacement session's own record. Task subagents of that session are refused by design — they
+borrow the host's tools under the host's garden id and never get a second address.
+
+The MCP entry deliberately uses the same server key as any Claude Code import so that it
+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.
+
+## 5. Optional Antigravity native citizen
 
 Install the three independently owned surfaces:
 
@@ -134,7 +315,7 @@ Real native-push acceptance needs an already-running conversation:
 LIVE=1 AGY_CONVERSATION_ID=<id> entwurf smoke-agy-native-push-live
 ```
 
-## 5. Optional ACP backend turns
+## 6. Optional ACP backend turns
 
 Claude uses the operator's existing local Claude authentication:
 
@@ -153,25 +334,34 @@ LIVE=1 ENTWURF_ACP_CORTEX_CONNECTION=<conn> \
 The aggregate release gate is Claude-backed and does not run Cortex automatically.
 Its silence is not a Cortex PASS.
 
-## 6. Upgrade and repair
+## 7. Upgrade and repair
 
 After upgrading the package, rerun the managed installers for every native harness
 in use and restart their existing processes. Native plugin caches are not live-reload
 safe across launch-contract changes.
 
 If install or doctor reports an unreadable/old active citizen generation, do not edit
-records by hand:
+records by hand. Close pi, Claude, Copilot, and agy sessions first, run
+`entwurf meta-bridge-fresh-cut`, and read its exit status before any install. Then choose the
+installation mode you actually own:
 
 ```bash
-# close pi, Claude, and agy sessions first
-entwurf meta-bridge-fresh-cut
-entwurf setup ~/entwurf-smoke
+# npm package consumer
+entwurf install ~/entwurf-smoke
+entwurf install-meta-bridge
+# `entwurf setup` re-composes the four Copilot units when `copilot` is on PATH
+
+# source maintainer — from the checkout
+./run.sh setup ~/entwurf-smoke
 ```
 
-Read the cut's exit status before chaining setup. The complete quiescence, archive,
-and exit-code contract is [fresh-cut-policy.md](./fresh-cut-policy.md).
+The package-installed `entwurf setup` is the same consumer command in installed mode: it names
+that mode first, never runs npm/pnpm inside `node_modules` (the frozen pnpm bootstrap is
+source-checkout-only), and composes the detected harnesses with the same per-component
+PASS/SKIP/FAIL summary. The complete quiescence, archive, and exit-code contract is
+[fresh-cut-policy.md](./fresh-cut-policy.md).
 
-## 7. Release acceptance versus host acceptance
+## 8. Release acceptance versus host acceptance
 
 - `entwurf check-bridge`: installed MCP bytes boot; no backend auth.
 - `pnpm check` / `pnpm run check:full`: tiered source deterministic floors (everyday
@@ -190,12 +380,27 @@ Run only the surfaces this host owns:
 
 ```bash
 entwurf uninstall-meta-bridge
+entwurf uninstall-copilot-statusline
+entwurf uninstall-copilot-receive
+entwurf uninstall-copilot-mcp
+entwurf uninstall-copilot-bridge
 entwurf uninstall-agy-hooks
 entwurf uninstall-agy-statusline
 entwurf uninstall-agy-bridge
-entwurf uninstall ~/entwurf-smoke
+entwurf remove ~/entwurf-smoke
+# only when no other project uses the shared user-scope pi registration:
+entwurf remove-user-scope
 npm uninstall -g @junghanacs/entwurf
 ```
 
-Each managed surface has an honest inverse and preserves unrelated native-harness
-configuration.
+The package `uninstall-*`/`remove` surfaces preserve unrelated native-harness configuration.
+Copilot birth now has a package-owned inverse: `uninstall-copilot-bridge` removes exactly what
+its install-state (`$XDG_DATA_HOME/entwurf/copilot-bridge/install-state.json`) records — the
+qualified plugin, the local marketplace registration when it is owned and still at the recorded
+path, and the recorded assembly — never with `--force`, never a bare plugin name that could
+match somebody else's unit, and never the stale Claude unit. The complete ownership preflight
+runs read-only before the first vendor write, so a marketplace under our name at another path,
+a registration the state does not own, or a failing vendor list (UNKNOWN, never absence)
+refuses the whole inverse with zero writes; the state is deleted last, so a partial failure
+keeps a rerun-repair authority.
+A legacy no-state installation is adopted by re-running `install-copilot-bridge` first.