@junghanacs/entwurf 0.16.0 → 0.17.1

package/pi-extensions/lib/acp/claude-acp-launch.js

@@ -0,0 +1,100 @@
+// entwurf-owned launcher for the Claude ACP backend (#72).
+//
+// WHY THIS FILE EXISTS — it is not a wrapper for its own sake.
+//
+// The vendor bin is named `claude-agent-acp`, and that name is not ours: any
+// harness on the host that spawns the same package produces a process with the
+// same name. On GLG's oracle host a janitor installed for a DIFFERENT harness
+// (openclaw's acpx, upstream PR #245) selects `claude-agent-acp` by argv
+// SUBSTRING and SIGTERMs anything older than 900s. entwurf's child is retained
+// across turns, so its age is the age of the SESSION, not of a turn — every
+// session older than 15 minutes was shot at every 5 minutes. Measured: 12 of 12
+// anomalous terminations across two boots, pid- and timestamp-locked (receipts
+// in `scripts/raw-acp-child-exit-measure/README.md` §ANSWERED).
+//
+// So this launcher does two things, and deliberately nothing else:
+//
+//   1. NAMESPACE. It carries a name that is ours, so a name-matching janitor
+//      stops selecting our process. The vendor is `import`ed INTO this same
+//      process — not spawned as a child. That distinction is what keeps this
+//      inside #72's repair fence: with no child to restart, this cannot become
+//      the supervisor/watcher/retry the issue forbids. Any variant that spawns
+//      the vendor breaks the fence and must not be written.
+//
+//   2. OBSERVE A CAUGHT SIGNAL. The vendor's own handler turns SIGTERM/SIGINT
+//      into `dispose(); process.exit(0)`, so by the time entwurf sees the child
+//      end there is an exit code 0 and NO signal — a clean external kill and a
+//      vendor fault are indistinguishable. Registering first lets us record
+//      that a terminating signal was caught, before the vendor erases it.
+//
+// WHAT THIS COSTS, STATED SO NOBODY DISCOVERS IT LATER. Once the name split is
+// in place, a host janitor that scans for the vendor name can no longer see
+// entwurf's children AT ALL — including ones that genuinely leaked. If pi is
+// SIGKILLed so `teardownChild` never runs, this adapter reparents to PID 1 and
+// matches neither that janitor's name phase nor its orphan phase (which looks
+// for a bare `claude`). That leak class now belongs to entwurf: after the split,
+// we own our own cleanup story and cannot expect someone else's timer to cover
+// it. This is a deliberate trade — being killed mid-turn is worse than leaking
+// a process on an abnormal exit — but it is a trade, not a free win.
+//
+// ARGV IS NOT OURS TO TOUCH. The vendor reads `--cli` / `--version` /
+// `--hide-claude-auth` from `process.argv`, and builds its own re-invocation
+// command from `process.argv.slice(1)` for the terminal-auth advert. Under this
+// launcher that advert becomes `node <this file> --cli auth login …`, which
+// keeps working ONLY because we consume no flags and resolve the vendor
+// ourselves. Never give this file an option of its own.
+
+import { readFileSync, writeSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * The one line entwurf's stderr drain looks for, matched as an EXACT full line.
+ * A fixed enum, never interpolated from vendor text: the backend must be unable
+ * to mistake vendor prose (which mentions signals) for our own observation.
+ */
+const SIGNAL_FRAME_PREFIX = "ENTWURF_ACP_LAUNCH_SIGNAL=";
+
+/** Signals the vendor normalizes to exit 0, and which are therefore invisible downstream. */
+const OBSERVED_SIGNALS = /** @type {const} */ (["SIGTERM", "SIGINT"]);
+
+for (const signal of OBSERVED_SIGNALS) {
+	process.on(signal, () => {
+		// writeSync, not console.error: a handler may run while the process is
+		// tearing down and an async write can be dropped.
+		try {
+			writeSync(2, `${SIGNAL_FRAME_PREFIX}${signal}\n`);
+		} catch {
+			// stderr already gone — the observation is best-effort, never fatal.
+		}
+		// THE SINK GUARD. Registering a handler SUPPRESSES node's default
+		// termination. If we are still the only listener — the vendor has not
+		// registered yet, or its import failed — this observer would make the
+		// process immune to the very signal it is observing, including entwurf's
+		// own teardown SIGTERM. Stand down and let the signal land for real.
+		if (process.listenerCount(signal) === 1) {
+			process.removeAllListeners(signal);
+			process.kill(process.pid, signal);
+		}
+	});
+}
+
+// Resolution lives INSIDE the same try as the import so both failures speak with
+// one voice: a missing package and a broken package are the same event to an
+// operator reading stderr, and only one of them would otherwise be legible.
+try {
+	const require = createRequire(import.meta.url);
+	const pkgJsonPath = require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
+	const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+	const binPath = typeof pkgJson.bin === "string" ? pkgJson.bin : pkgJson.bin?.["claude-agent-acp"];
+	if (!binPath) throw new Error("@agentclientprotocol/claude-agent-acp resolved but exposes no bin entry");
+	// Same process, no argv touched. The vendor bin has no main-module guard, so
+	// importing it starts the agent exactly as executing it would.
+	await import(pathToFileURL(join(dirname(pkgJsonPath), binPath)).href);
+} catch (err) {
+	// Fail loud and DIE. No retry, no fallback: a launcher that survives its own
+	// failure is the hidden supervisor #72 forbids.
+	writeSync(2, `entwurf acp launcher: vendor import failed: ${err instanceof Error ? err.stack : String(err)}\n`);
+	process.exit(1);
+}

package/pi-extensions/lib/acp/event-mapper.ts

@@ -49,6 +49,22 @@ export type AcpPiStreamState = {
 	/** When false, tool/permission notices are suppressed (kept terse for smokes). */
 	showToolNotifications?: boolean;
 	observedTools?: Map<string, ObservedToolState>;
+	/**
+	 * RAW, UNINTERPRETED observations from this turn's `usage_update` notifications
+	 * — carried beside the pi message, never folded into it here.
+	 *
+	 * The mapper is COMMON layer and deliberately assigns no meaning to either
+	 * number: what `cost.amount` is CUMULATIVE OVER, and whether that even holds
+	 * for a non-claude backend, is a per-backend measurement. backend.ts seals them
+	 * only for a backend whose adapter declares `sealsTurnAccounting` (#93).
+	 *
+	 * Last write wins, never a sum: both are latest session-level observations, and
+	 * one turn can legitimately see several (claude emits one per `result` message,
+	 * including a sub-agent's own — read at claude-agent-acp 0.73.0
+	 * `dist/acp-agent.js:2918-2933`), each carrying that result's current values.
+	 */
+	observedSessionCostUsd?: number;
+	observedContextOccupancyTokens?: number;
 };
 
 /** A zeroed pi Usage block. */
@@ -328,13 +344,34 @@ export function applyAcpSessionUpdate(
 			break;
 		}
 		case "usage_update": {
-			// S2c maps COARSE ACP usage only: `used` is occupancy-shaped and does
-			// not split cleanly into pi's input/output/cache fields, so we fill
-			// totalTokens + cost.total and leave the rest zero. Richer accounting
-			// is a later lane (S2e/PR-polish).
-			if (typeof update.used === "number") state.output.usage.totalTokens = update.used;
+			// `used` is OCCUPANCY-shaped — the backend's post-turn context size, not
+			// the prompt response's turn aggregate. Claude sends `lastAssistantTotalUsage`
+			// as `used` (read at claude-agent-acp 0.73.0
+			// `dist/acp-agent.js:3290-3297`), after constructing that scalar from the
+			// latest assistant snapshot (`:3273-3289`). pi reads `usage.totalTokens` as
+			// exactly that occupancy (`calculateContextTokens(usage) = usage.totalTokens
+			// || input + output + cacheRead + cacheWrite`, read at pi-coding-agent
+			// `dist/core/compaction/compaction.js:86-88`). The assignment below is the
+			// raw observation; backend.ts seals the measured occupancy and relays the
+			// turn aggregate separately on `usage.acp`, never onto pi's four fields.
+			if (typeof update.used === "number") {
+				state.output.usage.totalTokens = update.used;
+				state.observedContextOccupancyTokens = update.used;
+			}
+			// `cost.amount` is a running SESSION total on the claude backend, so
+			// assigning it to a TURN field is wrong wherever an adapter has measured
+			// that (#93: pi sums per-message cost, which inflated a long session
+			// 10-18x). It stays here for a backend whose adapter has NOT measured its
+			// semantics — for those, this coarse assignment is the pre-#93 behaviour
+			// and changing it would be an unmeasured claim. backend.ts OVERWRITES
+			// this field authoritatively (from the baseline diff) for every turn of a
+			// backend that HAS sealsTurnAccounting, so the cumulative can never reach
+			// an operator's dashboard as a turn cost on that path.
 			const cost = update.cost as { amount?: unknown } | undefined;
-			if (typeof cost?.amount === "number") state.output.usage.cost.total = cost.amount;
+			if (typeof cost?.amount === "number") {
+				state.output.usage.cost.total = cost.amount;
+				state.observedSessionCostUsd = cost.amount;
+			}
 			break;
 		}
 		default:

package/run.sh

@@ -119,7 +119,7 @@ run_vitest() {
 usage() {
   cat <<'EOF'
 Usage:
-  ./run.sh setup [project-dir]        # ONE presence-driven composition (#86): mode-first (source bootstrap only on a checkout), then per-component PASS/SKIP/FAIL for pi (presence+floor)/claude/agy/copilot (all four units: birth→MCP→receiver→footer, independently) + stable dev bins + v2 install smoke; absent harness = zero-state SKIP, detected-incomplete = named FAIL + nonzero exit. Never installs a harness or touches credentials
+  ./run.sh setup [project-dir]        # ONE presence-driven composition (#86): mode-first (source bootstrap only on a checkout), then per-component PASS/SKIP/FAIL for pi (presence+floor)/claude/agy/copilot (all four units: birth→MCP→receiver→footer, independently)/omp (four units: birth→MCP→tools.xdev setting→receiver, independently) + stable dev bins + v2 install smoke; absent harness = zero-state SKIP, detected-incomplete = named FAIL + nonzero exit. Never installs a harness or touches credentials
   ./run.sh release-gate [project-dir] [--cut] [--allow-skip-gemini]  # SINGLE release gate: full static (pnpm run check:full) + the v2-native live gates (v2 matrix-live, check-bridge, doctor-pi-provider, RGG) + the ACP plugin acceptance floor (12 LIVE smokes: socket-citizen/raw-turn/overlay/provider/session-reuse/carrier-augment/memory-containment/rgg/mcp/skill/bundled-mcp/v2-send) + the one surviving axis the aggregate used to omit silently (claude-native-resume; Cortex stays a documented on-demand direct call) + the cross-harness delivery chain (smoke-entwurf-chain-live). TWO-TIER summary: MUST (release-blocking, owns the exit code — "green" applies here) + BEHAVIOR (advisory, non-blocking: RGG positives model-in-loop turn). STEP OUTCOME protocol: every step is INVOKED and reports its own PASS / SKIP (exit 97, a prerequisite it does not have) / FAIL — a skip is never counted as a pass. Without --cut this is the unattended diagnostic (SKIPs reported, exit 0). WITH --cut it is read as release acceptance and ANY MUST SKIP is red, which is what makes "a CUT needs LIVE=1, SKIP=0" executable instead of prose. --allow-skip-gemini accepted-but-ignored (back-compat). final cut authorization is GLG's.
   ./run.sh check-bridge               # entwurf-bridge direct MCP smoke + protocol/negative-path test.sh (live substrate = v2 live smokes)
   ./run.sh check-entwurf-bridge-boot # deterministic gate (5d-5-pre, G1a/G1b/G1e/G1f, IN pnpm run check:full): boot start.sh under strip-types + assert v2 fence graph loads + entwurf_v2 and entwurf_resume_call registered/schema + the tools/list surface is EXACTLY the seven shipped garden verbs; tools/list only, no auth/side-effect
@@ -218,6 +218,8 @@ Usage:
   ./run.sh install-copilot-mcp        # #82 RAIL 5: register ONE entwurf-bridge server in ~/.copilot/mcp-config.json (adopt / create / REFUSE symlink), type:local, install-state under $XDG_DATA_HOME/entwurf/copilot-mcp/
   ./run.sh uninstall-copilot-mcp      # honest inverse of install-copilot-mcp from install-state
   ./run.sh doctor-copilot-mcp         # static ownership/config/boot doctor; RED only when install-state exists
+  ./run.sh install-omp-config         # #87 follow-on: write the ONE operator setting omp's tool hand requires — `tools.xdev: false` in <omp agent dir>/config.yml. Owns exactly the line(s) it adds (recorded in install-state), refuses a symlinked config, refuses a config it cannot parse, and refuses an EXPLICIT operator `xdev: true` by name rather than overwriting a decision. Without it the vendor default wraps every MCP tool behind `xd://` and the doorbell announces a tool the model cannot call
+  ./run.sh uninstall-omp-config       # honest inverse from install-state: takes back exactly the recorded line(s), removes the file only when entwurf created it, REFUSES when the config changed since install
   ./run.sh install-omp-bridge         # #87: install the OMP BIRTH extension into <omp agent dir>/extensions/entwurf-meta-omp (index.ts|js + lib + capability registry). No launcher and no bake — an omp hook is an in-process extension. Refuses when an inherited PI_CODING_AGENT_DIR/PI_CONFIG_DIR/PI_PROFILE makes the target agent dir ambiguous (ledger M6), and refuses ANY pre-existing artifact at the unit path that entwurf holds no ownership state for — a shape is not a proof of ownership
   ./run.sh uninstall-omp-bridge       # honest inverse from install-state (exact unit dir + recorded entry; no-state host REFUSES; state deleted LAST). Records already minted are preserved
   ./run.sh doctor-omp-bridge          # #87: runtime axis (importable unit, writer/registry parity, mint vs sender-marker errors on SEPARATE axes, scope-fence receipts, a root-grammar preflight that goes RED on a relative ENTWURF_META_* override instead of reporting on some other directory, CERTIFIED omp record count via meta-facts under the omp root policy — never a text grep, live omp processes carrying inherited PI_SESSION_ID/PI_AGENT_ID) + ownership axis. PI_CODING_AGENT_DIR is the vendor's own agent dir here and is reported as ignored, never as contamination. Zero records = NOT-YET, never red
@@ -250,7 +252,7 @@ Usage:
   ./run.sh check-dep-versions         # local deterministic check that the pi pin agrees across package.json (devDeps + peer range), run.sh (peer-install pins), and the baseline docs (AGENTS/README/ROADMAP/setup-clean-host/demo)
   ./run.sh check-node-floor-coherence # binds the Node floor (24+, single axis) across engines.node, run.sh setup preflight, meta-bridge install/doctor judgment logic, clean-host docs, the bridge launcher header, and the CI runner node-version — engines.node is the SSOT, everything else is derived; sweeps tracked contract text for an unregistered declaration
   ./run.sh check-pack                 # publish gate (dry-run): npm pack --dry-run + tarball invariants (runtime-critical present, dev residue absent)
-  ./run.sh check-pack-pin-matcher     # pure self-test of check-pack-install's pin-leak matcher against synthetic .pnpm lookalikes (version boundary: @0.84.30 must leak, @0.84.3 bare/peer-hash must pass); snapshot-safe qualification oracle, also run first inside check-pack-install
+  ./run.sh check-pack-pin-matcher     # pure self-test of check-pack-install's pin-leak matcher against synthetic .pnpm lookalikes (version boundary: @0.84.40 must leak, @0.84.4 bare/peer-hash must pass); snapshot-safe qualification oracle, also run first inside check-pack-install
   ./run.sh check-fresh-cut-gate       # SOURCE cell of the generation-boundary proof (IN pnpm run check:full): drives real install/setup/fresh-cut in a sandbox; certification refusal is pre-write, quiescence is fail-closed, archives preserve bytes, and the #54 exit matrix distinguishes complete / no-move / usage / incomplete transition / complete-with-cleanup-residue. No model/network/cost
   ./run.sh check-pack-install         # heavy publish gate (prepublishOnly): actual npm pack + tar -tf + fresh-temp install smoke with the pinned pi peers (pins derived from the package.json devDep; check-dep-versions binds them) + the npm-installed bridge BOOTS (tools/list) and DELIVERS (tools/call entwurf_v2 → .msg lands) + the installed all-absent and copilot-present (four-unit fake-vendor) `entwurf setup` rows + the INSTALLED generation lifecycle on a seeded previous-generation host (REFUSE before activation writes / zero Claude invocations → installed fresh-cut archives + opens empty → install-meta-bridge PASSES) + the INSTALLED-PACKAGE branch of the Copilot and OMP birth installers actually RUN (compiled entry selected, no raw .ts, and a real birth edge mints a citizen — the half a required-artifact list can never stand in for)
   ./run.sh check-install-container    # 0.12.8 (#51 C): Linux artifact-CONSUMER gate — one candidate .tgz handed read-only to a checkout-invisible node:<engines-major>-bookworm cell. Default packs once to temp; ENTWURF_CANDIDATE_TGZ=/absolute/preserved.tgz consumes those exact bytes with no re-pack and prints canonical path+sha256 for release. Non-root global PATH install, frozen package, MCP tools/list, fake-Claude install-meta-bridge, path+sha256 fence, strict doctor, and the GENERATION host-state matrix (clean / v3-only store bytes unchanged / previous-generation REFUSE→fresh-cut→retry PASS) seeded inline. Docker missing = honest SKIP; ENTWURF_REQUIRE_DOCKER=1 makes that RED (required CI)
@@ -1825,13 +1827,13 @@ assert.equal(peerTui, piAi,
 // floor tracks the devDep pin so a consumer can't install against a pi lacking
 // the public trust exports the bridge imports at the pinned minor, AND an upper
 // bound at the next minor stops a fresh install from silently pulling a future
-// pi (past the declared ceiling — 0.85+ at the current 0.84.3 pin) whose
+// pi (past the declared ceiling — 0.85+ at the current 0.84.4 pin) whose
 // internal export surface has drifted from the one we typecheck against.
 // pi moves its public surface every minor (the 0.79→0.80 getModels→provider-
 // factory churn is exactly this), so an open `>=` floor is exactly how the next
 // installer re-acquires the drift. The floor is also the HARD MINIMUM a consumer
-// install resolves: at `>=0.84.3` an existing 0.83.x host is upgraded, not kept.
-// Expected shape: `>=<devDep> <0.<minor+1>` (e.g. `>=0.84.3 <0.85`).
+// install resolves: at `>=0.84.4` an existing 0.84.3 host is upgraded, not kept.
+// Expected shape: `>=<devDep> <0.<minor+1>` (e.g. `>=0.84.4 <0.85`).
 const [piMaj, piMin] = piAi.split('.').map(Number);
 assert.equal(piMaj, 0,
   `pi pin major must stay 0 for the next-minor ceiling rule (got ${piAi}); revisit check-dep-versions when pi reaches 1.x`);
@@ -2698,6 +2700,24 @@ check_acp_event_mapper() {
   run_ts scripts/check-acp-event-mapper.ts
 }
 
+check_acp_usage_accounting() {
+  # Deterministic gate for the ACP USAGE ACCOUNTING contract (#93). A long-lived
+  # Claude ACP session's dashboard read 10-18x high on three live ledgers,
+  # because the per-turn token partition was dropped at the type boundary while
+  # the backend's RUNNING SESSION TOTAL was assigned to a per-turn cost field pi
+  # then summed. Drives streamAcpTurn against a fake ACP child + connection whose
+  # turns are scripted (usage_update notification + PromptResponse.usage) for
+  # five cells: the four-way token partition reaches the pi message; per-turn
+  # costs are adjacent diffs of the running total and sum back to it across a
+  # reused session; a turn with no cost notification attributes $0 and HOLDS the
+  # baseline; a decreasing total rebaselines, attributes $0 and tells the
+  # operator; totalTokens stays CONTEXT OCCUPANCY (asserted through pi's own
+  # calculateContextTokens) and carries forward; and cortex — no measured
+  # extractor — keeps its pre-#93 output untouched.
+  section "ACP usage accounting (turn partition + adjacent-diff cost)"
+  run_ts scripts/check-acp-usage-accounting.ts
+}
+
 check_acp_stop_reason() {
   # Deterministic gate for the ACP stop-reason contract. Drives every member of
   # the closed ACP terminal set (end_turn / max_tokens / max_turn_requests /
@@ -2729,6 +2749,17 @@ check_acp_prompt_lifecycle() {
   run_ts scripts/check-acp-prompt-lifecycle.ts
 }
 
+check_acp_launch_namespace() {
+  # #72: the Claude ACP child must launch under a name entwurf OWNS. A janitor
+  # installed on the host for ANOTHER harness selects the vendor process name
+  # `claude-agent-acp` by argv substring and SIGTERMs it by age; entwurf retains
+  # its child across turns, so its age is the session's. This gate holds the
+  # name split, holds the launcher transparent (the vendor still answers
+  # --version through it), and keeps an explicit operator override verbatim.
+  section "ACP launch namespace (#72 — no vendor process name in our argv)"
+  run_ts scripts/check-acp-launch-namespace.ts
+}
+
 check_acp_stream_hooks() {
   # Deterministic gate for the pi 0.84 streamSimple hook contract on the ACP rail
   # (#63; upstream pi-mono #7372 → doc-only #7576). before_provider_request
@@ -3067,15 +3098,15 @@ check_pack() {
 # The pin-leak filter for the install tree's .pnpm listing, shared by the real scan and its
 # self-test below. The version BOUNDARY is load-bearing: a pnpm .pnpm entry is
 # `<name>@<version>` followed by either `_<peer-hash>` or end-of-name (measured pnpm 11.20.0
-# on this tree), so an unbounded substring match would bless a lookalike such as `@0.84.30`
+# on this tree), so an unbounded substring match would bless a lookalike such as `@0.84.40`
 # while announcing the pinned floor — a false-green oracle (found by independent review,
 # 2026-08-25).
 pack_install_leaked_pi() {
-  grep '^@earendil-works+pi-' | grep -Ev '@0\.84\.3(_|$)' || true
+  grep '^@earendil-works+pi-' | grep -Ev '@0\.84\.4(_|$)' || true
 }
 
 # Matcher self-test on SYNTHETIC lookalikes: a healthy install tree cannot exercise the
-# false-green shape (it contains no 0.84.30), so the oracle is proven against a fixture
+# false-green shape (it contains no 0.84.40), so the oracle is proven against a fixture
 # listing. Expected: the two lookalikes leak, the pinned version passes bare and with a
 # peer-hash suffix. Exposed as its own snapshot-safe subcommand because the heavy
 # check-pack-install cannot run inside the qualification snapshot (no install environment),
@@ -3084,13 +3115,13 @@ pack_install_leaked_pi() {
 check_pack_pin_matcher() {
   local matcher_probe
   matcher_probe=$(printf '%s\n' \
-    '@earendil-works+pi-ai@0.84.3' \
-    '@earendil-works+pi-ai@0.84.3_@modelcontextprotocol+sdk@1.29.0_zod@4.3.6' \
-    '@earendil-works+pi-ai@0.84.30' \
-    '@earendil-works+pi-agent-core@0.84.2' | pack_install_leaked_pi)
-  if [ "$matcher_probe" != '@earendil-works+pi-ai@0.84.30
-@earendil-works+pi-agent-core@0.84.2' ]; then
-    fail "[QK:PACK-INSTALL-PIN-MATCHER-BOUNDED] the pin-leak matcher must flag the 0.84.30/0.84.2 lookalikes and pass 0.84.3 bare or with a peer-hash — got: ${matcher_probe:-<nothing leaked>}"
+    '@earendil-works+pi-ai@0.84.4' \
+    '@earendil-works+pi-ai@0.84.4_@modelcontextprotocol+sdk@1.29.0_zod@4.3.6' \
+    '@earendil-works+pi-ai@0.84.40' \
+    '@earendil-works+pi-agent-core@0.84.3' | pack_install_leaked_pi)
+  if [ "$matcher_probe" != '@earendil-works+pi-ai@0.84.40
+@earendil-works+pi-agent-core@0.84.3' ]; then
+    fail "[QK:PACK-INSTALL-PIN-MATCHER-BOUNDED] the pin-leak matcher must flag the 0.84.40/0.84.3 lookalikes and pass 0.84.4 bare or with a peer-hash — got: ${matcher_probe:-<nothing leaked>}"
     return 1
   fi
   echo "[check-pack-pin-matcher] ok — the pin-leak matcher is version-bounded (lookalikes leak, pinned version passes bare and with a peer-hash)"
@@ -3320,7 +3351,7 @@ _check_pack_install_impl() {
   printf '%s\n' '{ "name": "entwurf-install-smoke", "version": "0.0.0", "private": true }' > "$tmp/package.json"
 
   # pi-agent-core is pinned even though we never import it: pi-coding-agent depends
-  # on it by CARET (`^0.84.3`), so with no lockfile in this fresh temp project it
+  # on it by CARET (`^0.84.x`), so with no lockfile in this fresh temp project it
   # floats to whatever pi published last — and that newer core then drags a NESTED
   # pi-ai of its own. Measured 2026-07-21: pinning only the three we import left
   # pi-agent-core@0.80.10 + pi-ai@0.80.10 in the tree while the gate still announced
@@ -3335,24 +3366,24 @@ _check_pack_install_impl() {
   # first time. Unpinned they would float exactly like pi-agent-core did in the
   # 2026-07-21 incident above. pi-telemetry joined the explicit pin list on
   # 2026-08-31: it arrives transitively (pi-agent-core and pi-ai both carry
-  # `^0.84.3` carets on it), and upstream's 0.84.4 patch publish (2026-08-28
+  # `^0.84.x` carets on it), and upstream's 0.84.4 patch publish (2026-08-28
   # 22:04Z) floated that caret in this lockfile-less temp install, turning CI
-  # red through the leak assertion below. The bump itself stays a separate
-  # hard-cut lane (#87 thread / NEXT "Do not touch: Pi 0.84.4") — pinning the
-  # drift shut is how the verified 0.84.3 runtime stays OURS to hold. The leak
+  # red through the leak assertion below. That explicit pin is what held the
+  # line until the bump lane ran; the verified floor is 0.84.4 as of
+  # 2026-09-01, and the pin moved WITH it rather than being retired. The leak
   # assertion below still covers every other pi package, including any package
   # a future pi bump adds to the closure.
   echo "[check-pack-install] pnpm add into $tmp (with 0.84.x peers + typebox)"
   local install_log
   install_log=$(cd "$tmp" && pnpm add \
     "$tgz_path" \
-    "@earendil-works/pi-ai@0.84.3" \
-    "@earendil-works/pi-coding-agent@0.84.3" \
-    "@earendil-works/pi-tui@0.84.3" \
-    "@earendil-works/pi-agent-core@0.84.3" \
-    "@earendil-works/pi-client@0.84.3" \
-    "@earendil-works/pi-protocol@0.84.3" \
-    "@earendil-works/pi-telemetry@0.84.3" \
+    "@earendil-works/pi-ai@0.84.4" \
+    "@earendil-works/pi-coding-agent@0.84.4" \
+    "@earendil-works/pi-tui@0.84.4" \
+    "@earendil-works/pi-agent-core@0.84.4" \
+    "@earendil-works/pi-client@0.84.4" \
+    "@earendil-works/pi-protocol@0.84.4" \
+    "@earendil-works/pi-telemetry@0.84.4" \
     "typebox@latest" \
     --ignore-workspace --ignore-scripts 2>&1) || {
     fail "[check-pack-install] pnpm add failed:"
@@ -3362,17 +3393,17 @@ _check_pack_install_impl() {
 
   # A pin is a wish until the resolved tree is read back. Assert it: EVERY
   # @earendil-works pi package present — direct or transitive, top level or nested —
-  # must be the pinned 0.84.3. Anything else means an unpinned caret floated and the
+  # must be the pinned 0.84.4. Anything else means an unpinned caret floated and the
   # rest of this gate would be exercising a runtime nobody verified, while still
-  # printing "pinned pi 0.84.3". Fail loud instead of proving the wrong floor.
+  # printing "pinned pi 0.84.4". Fail loud instead of proving the wrong floor.
   local leaked_pi
   leaked_pi=$(ls "$tmp/node_modules/.pnpm" 2>/dev/null | pack_install_leaked_pi)
   if [ -n "$leaked_pi" ]; then
-    fail "[check-pack-install] UNVERIFIED pi runtime resolved into the install tree (expected only 0.84.3):"
+    fail "[check-pack-install] UNVERIFIED pi runtime resolved into the install tree (expected only 0.84.4):"
     printf '%s\n' "$leaked_pi" | sed 's/^/    /' >&2
     return 1
   fi
-  echo "[check-pack-install] pi runtime tree pin verified: every @earendil-works pi package is 0.84.3"
+  echo "[check-pack-install] pi runtime tree pin verified: every @earendil-works pi package is 0.84.4"
 
   # Resolve the installed package.json and confirm pi.extensions
   # arrived intact. If pi.extensions is empty or missing, the
@@ -4983,6 +5014,52 @@ setup_all() {
     fi
   fi
 
+  # ── omp (oh-my-pi) ── presence-driven composition, same shape as copilot. OMP
+  # was admitted as a garden citizen in v0.16.0 with installers, doctors and
+  # inverses for every unit — but it was never composed HERE, so the one-command
+  # surface left the fifth backend to a hand-run verb list and the operator setting
+  # to a documentation step. That gap is what `docs/adding-a-harness.md` step 10
+  # now closes for every future harness: an onboarding is not finished until setup
+  # composes it. Four units, each independent: birth (who the citizen is) → MCP
+  # hand (what it can call) → the tools.xdev operator setting (whether those calls
+  # are REACHABLE) → receiver (whether a reply can land). OMP_BIN pins the PROBE
+  # for hermetic gates; the unit scripts address `omp` on PATH.
+  local omp_rc
+  if ! command -v "${OMP_BIN:-omp}" >/dev/null 2>&1; then
+    setup_result omp SKIP "omp not on PATH — zero OMP wiring written"
+  else
+    section "omp units (native harness detected: oh-my-pi)"
+    omp_rc=0; (cd "$REPO_DIR" && bash scripts/omp-bridge-install.sh) || omp_rc=$?
+    if [ "$omp_rc" -eq 0 ]; then
+      setup_result omp-birth PASS "birth extension installed — verify: ./run.sh doctor-omp-bridge"
+    else
+      setup_result omp-birth FAIL "detected omp, but the birth extension install did not complete (see above) — repair, then re-run setup"
+    fi
+    omp_rc=0; (cd "$REPO_DIR" && bash scripts/omp-mcp-bridge.sh install) || omp_rc=$?
+    if [ "$omp_rc" -eq 0 ]; then
+      setup_result omp-mcp PASS "MCP server registered — verify: ./run.sh doctor-omp-mcp"
+    else
+      setup_result omp-mcp FAIL "detected omp, but the MCP registration did not complete (see above) — repair, then re-run setup"
+    fi
+    # The operator setting is a component of its own because its FAIL is a real
+    # disagreement, not a broken install: an explicit `tools.xdev: true` is the
+    # operator's decision and the writer refuses it by name. Naming that as a
+    # component FAIL puts the choice in front of the operator instead of silently
+    # shipping a citizen whose tools nobody can call.
+    omp_rc=0; (cd "$REPO_DIR" && bash scripts/omp-config-xdev.sh install) || omp_rc=$?
+    if [ "$omp_rc" -eq 0 ]; then
+      setup_result omp-config PASS "tools.xdev: false written — verify: ./run.sh doctor-omp-mcp"
+    else
+      setup_result omp-config FAIL "detected omp, but the tools.xdev operator setting did not land (see above) — resolve it, then re-run setup"
+    fi
+    omp_rc=0; (cd "$REPO_DIR" && bash scripts/omp-receive-install.sh) || omp_rc=$?
+    if [ "$omp_rc" -eq 0 ]; then
+      setup_result omp-receive PASS "receiver extension installed — verify: ./run.sh doctor-omp-receive"
+    else
+      setup_result omp-receive FAIL "detected omp, but the receiver extension install did not complete (see above) — repair, then re-run setup"
+    fi
+  fi
+
   # ── core bridge boundary ── deterministic preflight lives in `pnpm run
   # check:full`; live substrate acceptance lives in `LIVE=1 ./run.sh
   # release-gate <scratch> --cut`. Setup is the install path, so it verifies the
@@ -5003,7 +5080,7 @@ setup_all() {
   local entry rest s_name s_verdict s_fails=""
   for entry in "${SETUP_RESULTS[@]}"; do
     s_name="${entry%%|*}"; rest="${entry#*|}"; s_verdict="${rest%%|*}"
-    printf '  %-14s %-4s %s\n' "$s_name" "$s_verdict" "${rest#*|}"
+    printf '  %-18s %-4s %s\n' "$s_name" "$s_verdict" "${rest#*|}"
     if [ "$s_verdict" = "FAIL" ]; then s_fails="$s_fails $s_name"; fi
   done
   echo ""
@@ -6121,6 +6198,20 @@ case "$cmd" in
   smoke-omp-mcp-state)
     (cd "$REPO_DIR" && bash scripts/smoke-omp-mcp-state.sh)
     ;;
+  install-omp-config)
+    # #87 follow-on: the ONE operator setting omp's tool hand requires (`tools.xdev: false`).
+    # A separate unit from install-omp-mcp because it answers a different question — the MCP
+    # hand registers the server, this decides whether the registered tools are REACHABLE. It
+    # owns exactly the line it adds and refuses an explicit operator `xdev: true` by name.
+    shift || true
+    (cd "$REPO_DIR" && bash scripts/omp-config-xdev.sh install "$@")
+    ;;
+  uninstall-omp-config)
+    # honest inverse from install-state: takes back exactly the recorded line(s), removes the
+    # file only when entwurf created it, and REFUSES when the config changed since install.
+    shift || true
+    (cd "$REPO_DIR" && bash scripts/omp-config-xdev.sh uninstall "$@")
+    ;;
   install-omp-bridge)
     # #87: the OMP BIRTH install. Not a mode of the Claude or Copilot installer, and for a
     # structural reason rather than a stylistic one: an omp "hook" IS an in-process
@@ -6447,12 +6538,18 @@ case "$cmd" in
   check-acp-event-mapper)
     check_acp_event_mapper
     ;;
+  check-acp-usage-accounting)
+    check_acp_usage_accounting
+    ;;
   check-acp-stop-reason)
     check_acp_stop_reason
     ;;
   check-acp-prompt-lifecycle)
     check_acp_prompt_lifecycle
     ;;
+  check-acp-launch-namespace)
+    check_acp_launch_namespace
+    ;;
   check-acp-stream-hooks)
     check_acp_stream_hooks
     ;;

package/scripts/check-acp-launch-namespace.ts

@@ -0,0 +1,127 @@
+// Deterministic gate — the Claude ACP child launches under a name entwurf OWNS.
+//
+// WHY THIS IS A GATE AND NOT A COMMENT (#72). The vendor bin is called
+// `claude-agent-acp`, and that name belongs to the package, not to us: any
+// harness on the host spawning the same package produces a process with the
+// same name. On GLG's oracle host a janitor installed for a DIFFERENT harness
+// selects `claude-agent-acp` by argv SUBSTRING and SIGTERMs anything older than
+// 900s. Because entwurf RETAINS its child across turns, its age is the age of
+// the session — 12 of 12 anomalous terminations across two boots were that
+// janitor (receipts: scripts/raw-acp-child-exit-measure/README.md §ANSWERED).
+//
+// The defense is a launcher whose own name carries no vendor substring. That is
+// a property of a STRING, which is exactly the kind of thing that rots silently
+// under a rename or a "harmless" revert — hence a gate that fails loudly.
+//
+// The second half matters as much: the launcher must remain TRANSPARENT. The
+// vendor reads `--cli` / `--version` from `process.argv` and builds its own
+// re-invocation command from `process.argv.slice(1)`. A launcher that consumed
+// a flag of its own, or failed to start the vendor at all, would trade one
+// silent breakage for another — so we RUN it and require the vendor to answer.
+
+import { strict as assert } from "node:assert";
+import { execFileSync } from "node:child_process";
+import { rmdirSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** The substring the janitor matches on — the thing our launch argv must not contain. */
+const VENDOR_PROCESS_MATCHER = "claude-agent-acp";
+
+const TMP_EMIT = ".tmp-verify/acp-launch-namespace";
+rmSync(TMP_EMIT, { recursive: true, force: true });
+try {
+	execFileSync("node_modules/.bin/tsc", ["--outDir", TMP_EMIT, "--rootDir", ".", "--noEmit", "false"], {
+		stdio: "pipe",
+	});
+	const adapterUrl = pathToFileURL(resolve(TMP_EMIT, "pi-extensions/lib/acp/backend-adapter.js")).href;
+	const mod = (await import(adapterUrl)) as {
+		claudeAdapter: {
+			resolveLaunch: (p: { cwd: string; modelId: string; nativeModelId: string; config: unknown }) => {
+				command: string;
+				args: string[];
+			};
+		};
+	};
+
+	const launch = mod.claudeAdapter.resolveLaunch({
+		cwd: process.cwd(),
+		modelId: "claude-sonnet-5",
+		nativeModelId: "claude-sonnet-5",
+		config: {},
+	});
+
+	// ----------------------------------------------------------------------
+	// The claim: nothing a name-matching janitor scans contains the vendor name.
+	// We check the WHOLE argv the way `ps` presents it, because that is what the
+	// janitor's awk actually reads — not just the basename.
+	// ----------------------------------------------------------------------
+	const psLine = [launch.command, ...launch.args].join(" ");
+	assert.ok(
+		!psLine.includes(VENDOR_PROCESS_MATCHER),
+		`[QK:CLAUDE-LAUNCH-IS-NAMESPACED] the default Claude ACP launch must not put "${VENDOR_PROCESS_MATCHER}" anywhere ` +
+			"in its argv: a janitor installed for another harness selects that substring by age and SIGTERMs it, which is " +
+			`the whole of #72. Got: ${JSON.stringify(psLine)}`,
+	);
+	assert.ok(
+		launch.args.length === 1 && launch.args[0].endsWith("claude-acp-launch.js"),
+		"the default launch is the entwurf-owned launcher and NOTHING else — an extra argv entry would be a flag of our " +
+			`own, which the vendor's argv.slice(1) self-reinvocation cannot survive. Got: ${JSON.stringify(launch.args)}`,
+	);
+
+	// ----------------------------------------------------------------------
+	// The launcher must still BE the vendor. A name split that stopped starting
+	// the agent would pass every string assertion above and ship a dead backend,
+	// so run it and make the vendor answer through it.
+	// ----------------------------------------------------------------------
+	const version = execFileSync(process.execPath, [...launch.args, "--version"], {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+		timeout: 60_000,
+	}).trim();
+	assert.match(
+		version,
+		/^\d+\.\d+\.\d+/,
+		"[QK:CLAUDE-LAUNCH-IS-TRANSPARENT] the launcher must pass argv through untouched and start the real vendor — " +
+			`\`--version\` has to reach it and answer. Got: ${JSON.stringify(version)}`,
+	);
+
+	// ----------------------------------------------------------------------
+	// The debug override is an EXPLICIT operator choice and must stay literal:
+	// an operator who names their own command owns the result, including losing
+	// the name split. Routing it through the launcher would silently overrule them.
+	// ----------------------------------------------------------------------
+	process.env.CLAUDE_AGENT_ACP_COMMAND = "echo overridden";
+	try {
+		const overridden = mod.claudeAdapter.resolveLaunch({
+			cwd: process.cwd(),
+			modelId: "claude-sonnet-5",
+			nativeModelId: "claude-sonnet-5",
+			config: {},
+		});
+		assert.deepEqual(
+			[overridden.command, ...overridden.args],
+			["bash", "-lc", "echo overridden"],
+			"CLAUDE_AGENT_ACP_COMMAND must stay verbatim — the launcher is the DEFAULT, never an override of the operator",
+		);
+	} finally {
+		delete process.env.CLAUDE_AGENT_ACP_COMMAND;
+	}
+} finally {
+	rmSync(TMP_EMIT, { recursive: true, force: true });
+	try {
+		// A leftover EMPTY parent dir reads as IMPURE tree drift in the
+		// qualification harness; a concurrent sibling gate's emit keeps it alive
+		// and this rmdir simply fails.
+		rmdirSync(".tmp-verify");
+	} catch {
+		// non-empty or already gone — fine either way
+	}
+}
+
+console.log(
+	"[check-acp-launch-namespace] ok — the default Claude ACP launch carries no vendor process name in its argv (so a " +
+		"name-matching janitor installed for another harness cannot select it), is exactly the entwurf-owned launcher " +
+		"with no flag of its own, still starts the real vendor through argv passed untouched, and leaves an explicit " +
+		"CLAUDE_AGENT_ACP_COMMAND override verbatim",
+);