@junghanacs/entwurf 0.15.1 → 0.16.1

package/pi-extensions/lib/mux-fresh-call.ts

@@ -70,10 +70,14 @@ import {
 	runTmux,
 	type WindowHandle,
 } from "./mux-placement.ts";
+import { OMP_PREFLIGHT_HINT, type OmpPreflightRejectReason, ompFreshPreflight } from "./omp-fresh-preflight.ts";
 
 /** The backends this rail can open. Fixed set, not a profile — a further one is a decision,
- * not a config entry. `copilot` was added by #82 RAIL 9 under the step 9 admission contract. */
-export const FRESH_CALL_BACKENDS = ["pi", "claude-code", "copilot"] as const;
+ * not a config entry. `copilot` was added by #82 RAIL 9 under the step 9 admission contract, and
+ * `omp` by #87 Bundle C under the same one. The set is joined to the citizen backends by
+ * `check-harness-admission-parity`: a harness that mints records but is missing HERE is not an
+ * unwired convenience, it is a release blocker. */
+export const FRESH_CALL_BACKENDS = ["pi", "claude-code", "copilot", "omp"] as const;
 export type FreshCallBackend = (typeof FRESH_CALL_BACKENDS)[number];
 
 /**
@@ -89,11 +93,20 @@ export type FreshCallBackend = (typeof FRESH_CALL_BACKENDS)[number];
  * flag, its recursion fence and its receiver precondition; fresh call reaches Copilot only
  * through it. The cost is named: a Copilot fresh call needs a current `entwurf` on PATH, the
  * way a pi fresh call needs `pi`.
+ *
+ * `omp` resolves the BARE vendor, and that difference is a measured one rather than an
+ * inconsistency. Copilot needs a managed wrapper because the bare CLI starts without
+ * `COPILOT_CLI_ENABLED_FEATURE_FLAGS=EXTENSIONS` and skips its extension scan silently — there
+ * is a flag only a launcher can carry. omp has no such flag: it always scans its extensions
+ * directory, and the one thing it needs beyond that (`tools.xdev: false`) lives in the operator
+ * config, which is a PREFLIGHT fact and not something a launcher could supply. Inventing an
+ * `entwurf omp` verb here would add a managed surface with nothing to manage.
  */
 export const FRESH_CALL_RUNTIME: Record<FreshCallBackend, string> = {
 	pi: "pi",
 	"claude-code": "claude",
 	copilot: "entwurf",
+	omp: "omp",
 };
 
 /**
@@ -107,11 +120,21 @@ export const FRESH_CALL_RUNTIME: Record<FreshCallBackend, string> = {
  * `tool.execution_start.toolName` both carry `entwurf-bridge-entwurf_v2`, with
  * `mcpServerName`/`mcpToolName` beside them as the parts. Derive-and-measure, never copy a
  * sibling's spelling (`docs/adding-a-harness.md` step 5).
+ *
+ * `[측정]` omp 18.0.0 is the sharpest case for that rule: it mints
+ * `mcp__${sanitizedServerName}_${normalizedToolName}` with a sanitizer whose charset is
+ * `[a-z_]` (`mcp/tool-bridge.ts:351-357`, `:396`), so the DIGIT IN `entwurf_v2` IS EATEN and the
+ * hyphen in the server key becomes an underscore — the model-facing name is
+ * `mcp__entwurf_bridge_entwurf_v`, not `..._entwurf_v2` and not Claude's double-underscore form.
+ * Confirmed against a live tool dump of all seven bridge tools and a real session transcript
+ * (`scripts/raw-omp-measure/README.md` "Tool-name dialect"). Unlike Copilot there is no second
+ * permission dialect: omp's approval layer consults the same minted string (`source-audit.md`).
  */
 export const FRESH_CALL_CALLBACK_TOOL: Record<FreshCallBackend, string> = {
 	pi: "entwurf_v2",
 	"claude-code": "mcp__entwurf-bridge__entwurf_v2",
 	copilot: "entwurf-bridge-entwurf_v2",
+	omp: "mcp__entwurf_bridge_entwurf_v",
 };
 
 /** Mirrors the `entwurf_v2` message bound. This is an INTERFACE cap for symmetry with the
@@ -119,7 +142,7 @@ export const FRESH_CALL_CALLBACK_TOOL: Record<FreshCallBackend, string> = {
  * that the OS refuses is a launch failure and fails loud — it never reads as a delivered task. */
 export const TASK_MAX_CHARS = 16000;
 export const MODEL_MAX_CHARS = 200;
-const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/:\[\]-]*$/;
+const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/:[\]-]*$/;
 
 /** A model is an explicit launch input, not ambient process state. The grammar admits canonical
  * pi provider/model ids, Claude model ids/aliases, and bracketed context variants, while refusing
@@ -140,6 +163,11 @@ export function isSafeFreshCallModel(model: string): boolean {
  *   copilot     — the managed VERB first, then the prompt as the value of `-i/--interactive`,
  *                 `--model`, value as two tokens, and the policy as the explicit `--yolo`
  *                 token. Measured from `copilot --help` (1.0.80).
+ *   omp         — NO positional prompt at all. The task rides `--entwurf-bootstrap`, a fixed
+ *                 flag the installed birth extension registers, then `--model`, value as two
+ *                 tokens, then the policy as `--approval-mode`, `yolo`. `-p/--print` remains
+ *                 the flag this argv must never carry — it processes a prompt and EXITS,
+ *                 closing the window on a sibling that has to stay open to be delivered to.
  *
  * Both pi/claude failures looked identical from outside: window open, record and socket minted,
  * no turn.
@@ -172,18 +200,108 @@ export function isSafeFreshCallModel(model: string): boolean {
  * `--allow-tool` takes `<mcp-server-name>(tool-name?)`, a different dialect from the
  * model-facing tool name — stays recorded in `docs/adding-a-harness.md` step 9's worked
  * example; it is a measured vendor fact even though this argv no longer uses it.
+ *
+ * OMP'S POLICY TOKEN IS THE ONE MOST EASILY ARGUED AWAY, SO READ THIS BEFORE DELETING IT.
+ * `[측정]` omp 18.0.0's schema default for `tools.approvalMode` IS ALREADY `yolo`
+ * (vendor doc `omp://approval-mode.md`; `omp config get tools.approvalMode` → `yolo` on the
+ * acceptance host). So dropping `--approval-mode yolo` changes NOTHING observable: the callback
+ * still fires, the LIVE smoke still passes, and the argv silently starts depending on a vendor
+ * default and on whatever the operator's config happens to say. That is exactly the drift step 9
+ * clause 2 forbids — "carry the chosen width as an explicit argv token rather than relying on a
+ * launcher's injected default" — and the reason the width is stated here even though the host
+ * would have granted it anyway. The width itself (task-wide, not callback-only) is a GLG
+ * operator decision of 2026-08-30, taken with the Copilot measurement in hand: a callback-only
+ * sibling names itself and then stops at the first tool its TASK needs. omp offers no argv
+ * grammar for a narrower grant at all — `tools.approval.<tool>` is a config axis, not a flag —
+ * so the honest choice was between `write` and `yolo`, and `yolo` matches what a human-typed
+ * `omp` gets on this host. `--approval-mode` takes both the space and equals form (measured);
+ * the space form is used for symmetry with `--model`.
+ *
+ * WHY OMP ALONE CARRIES NO PROMPT, AND WHY THAT IS A MEASUREMENT RATHER THAN A PREFERENCE.
+ * `[LIVE 2026-08-30]` the first public fresh call at omp DID pass the full framing as a bare
+ * positional. The window opened, the record minted (garden `20260830T181342-452167`), the
+ * prompt arrived byte-identical as a user message at `09:13:42.413Z` — and the model answered
+ * the literal text `ACK` with ZERO tool calls, because the callback tool did not exist yet.
+ * `[source]` the interactive UI defers MCP discovery and only refreshes the tool list once
+ * `discoverAndConnect()` settles (`sdk.ts:1847-1855`, `:1881-1905`), while the positional
+ * `initialMessage` prompts immediately after `await mode.init()` (`main.ts:540-565`,
+ * `595-610`). `[측정]` a `/tmp` observer on the same runtime: `turn_start` at +654ms with the
+ * entwurf tools ABSENT, callback tool present only at +1484ms — the turn began ~830ms before
+ * the tool it was told to call existed. No argv can close that gap, because the gap is a race
+ * inside the host. So the composition hands omp a PAYLOAD instead of a turn, and the
+ * in-process birth extension — which can see when the tool becomes callable — owns the first
+ * two messages (`pi-extensions/meta-bridge-omp.ts`, "THE TWO-STAGE FRESH BOOTSTRAP").
+ *
+ * The flag is fixed and one-purpose ON PURPOSE. `[측정 2026-08-30]` a normal discovered
+ * extension that registers a flag receives the operator's argv value byte-identical — quotes,
+ * `$VAR`, backticks and a semicolon all survived a 137-byte JSON payload — because extensions
+ * load before argv classification and the reparse writes the registered map
+ * (`main.ts:1799-1810`, `cli/extension-flags.ts:36-43`). An env carrier or a temp file would
+ * have needed its own quoting, its own lifetime and its own refusal rules; argv already owns
+ * all three. This is deliberately NOT a general `--flag value` passthrough — an arbitrary
+ * carrier would hand callers the launch-shaping power this rail exists to refuse.
  */
-export function buildBackendArgs(backend: FreshCallBackend, prompt: string, model: string): string[] {
+export function buildBackendArgs(
+	backend: FreshCallBackend,
+	composition: FreshCallComposition,
+	model: string,
+): string[] {
 	switch (backend) {
 		case "pi":
-			return [prompt, "--entwurf-control", "--model", model];
+			return [composition.prompt, "--entwurf-control", "--model", model];
 		case "claude-code":
-			return [prompt, `--allowedTools=${FRESH_CALL_CALLBACK_TOOL["claude-code"]}`, `--model=${model}`];
+			return [composition.prompt, `--allowedTools=${FRESH_CALL_CALLBACK_TOOL["claude-code"]}`, `--model=${model}`];
 		case "copilot":
-			return ["copilot", "--interactive", prompt, "--model", model, "--yolo"];
+			return ["copilot", "--interactive", composition.prompt, "--model", model, "--yolo"];
+		case "omp":
+			return [`--${OMP_BOOTSTRAP_FLAG}`, composition.bootstrapPayload, "--model", model, "--approval-mode", "yolo"];
 	}
 }
 
+/**
+ * What a launch has to say, in the two shapes the four backends need. Three of them are
+ * handed a first-turn PROMPT; omp is handed a bootstrap PAYLOAD its own installed extension
+ * unpacks. Both are always built, because building one is cheap and a backend switch must
+ * never be able to reach a field that was not composed.
+ */
+export interface FreshCallComposition {
+	prompt: string;
+	bootstrapPayload: string;
+}
+
+/**
+ * The omp bootstrap flag, spelled WITHOUT dashes — the vendor's flag map is keyed by bare
+ * name (`extensions/loader.ts:221-228`) and this composition adds the `--` itself.
+ *
+ * Held equal to the installed extension's own constant by
+ * `test/omp-fresh-bootstrap.contract.test.ts`. The two copies exist because the extension
+ * ships INSIDE the omp agent dir carrying only its own small closure and cannot import this
+ * module; the gate is what keeps the duplication from becoming drift.
+ */
+export const OMP_BOOTSTRAP_FLAG = "entwurf-bootstrap";
+
+/** Payload grammar version, matched exactly by the decoder. A bump means a stale installed
+ * unit, which is the one thing `doctor-omp-bridge` exists to say out loud. */
+export const OMP_BOOTSTRAP_VERSION = 1;
+
+/**
+ * The whole of what a fresh omp sibling is launched with.
+ *
+ * THREE FIELDS, CLOSED. The decoder refuses an unknown key, so this object is the entire
+ * contract: who to call back, the nonce that proves it is this call, and the task that is
+ * released only after that callback succeeds. There is no command here, no path, no env name
+ * and no model — the model is already an explicit argv token, and a second copy of it inside
+ * a payload would be a second place for it to disagree with the launch.
+ */
+export function buildOmpBootstrapPayload(params: { callerGardenId: string; nonce: string; task: string }): string {
+	return JSON.stringify({
+		v: OMP_BOOTSTRAP_VERSION,
+		target: params.callerGardenId,
+		nonce: params.nonce,
+		task: params.task,
+	});
+}
+
 /**
  * The first-turn framing. Order is the contract: the callback is the FIRST action and the task
  * follows it, so a sibling that gets stuck in the task has already told the caller who it is.
@@ -224,6 +342,7 @@ export type FreshCallRejectReason =
 	| LaunchRejectReason
 	| TmuxCwdRejectReason
 	| CopilotPreflightRejectReason
+	| OmpPreflightRejectReason
 	| "caller-identity-unavailable"
 	| "model-empty"
 	| "model-invalid"
@@ -256,9 +375,35 @@ function defaultRandomHex(): string {
 	return randomBytes(12).toString("hex");
 }
 
-/** Launch argv: the leaf's detached-append shape, optionally `-c` at the resume-symmetric token
- * position (after `-t`, before `-P -F`), the runtime, then the backend's dialect. An omitted cwd
- * yields the exact pre-#73 argv — no carrier at all. */
+/**
+ * The pi identity carrier, scrubbed at the launch seam for EVERY backend (#87 Bundle C).
+ *
+ * `[측정]` 2026-08-30, private tmux server: a `new-window` pane inherits the tmux SERVER's
+ * environment, not the caller's. A server started from a shell that exported `PI_SESSION_ID`
+ * hands that value to every window it will ever open — the control run printed
+ * `SID=[leaked-uuid]` in a pane the caller never touched. Nothing about the fresh call creates
+ * that leak and nothing about it notices: the sibling's own MCP child would read the STALE pair
+ * as its authoritative identity and call home as a citizen it is not (`mcp/entwurf-bridge/
+ * src/index.ts:692-698` keeps the measured incident — a fresh cell answering with the uuidv7 it
+ * found in the environment, confidently and wrong).
+ *
+ * `-e VAR=` sets the variable EMPTY rather than unsetting it, which tmux has no per-window form
+ * for. That is sufficient and not a compromise: every reader of the carrier trims and tests
+ * truthiness (`index.ts:212-217`), so empty and absent are the same answer by construction.
+ *
+ * It is applied to all four backends because the leak is a property of tmux, not of a vendor. A
+ * scrub only on the backend whose measurement surfaced it would encode the claim that the other
+ * three are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
+ * authoritative when the process that owns it exported it ITSELF, and a fresh `pi` sibling does
+ * exactly that after this argv has run. This is a fixed two-variable seam and deliberately NOT a
+ * general env carrier — an arbitrary `-e` passthrough would hand callers the environment-shaping
+ * power this rail exists to refuse.
+ */
+const SCRUBBED_INHERITED_ENV = ["PI_SESSION_ID=", "PI_AGENT_ID="] as const;
+
+/** Launch argv: the leaf's detached-append shape, the identity scrub, optionally `-c` at the
+ * resume-symmetric token position (after `-t`, before `-P -F`), the runtime, then the backend's
+ * dialect. An omitted cwd adds no `-c` carrier at all. */
 export function buildFreshCallArgs(
 	placement: Placement,
 	runtimePath: string,
@@ -275,6 +420,7 @@ export function buildFreshCallArgs(
 		"new-window",
 		"-d",
 		"-a",
+		...SCRUBBED_INHERITED_ENV.flatMap((assignment) => ["-e", assignment]),
 		"-t",
 		`${placement.sessionId}:{end}`,
 		...(cwd === undefined ? [] : ["-c", cwd]),
@@ -337,20 +483,27 @@ export function freshCall(
 		const missing = copilotFreshPreflight(env);
 		if (missing) return { ok: false, reason: missing };
 	}
+	if (params.backend === "omp") {
+		const missing = ompFreshPreflight(env);
+		if (missing) return { ok: false, reason: missing };
+	}
 
 	const inspected = inspectPlacement(env);
 	if (!inspected.ok) return { ok: false, reason: inspected.reason };
 	const placement = inspected.placement;
 	requireSameContext("freshCall", placement, env);
 
-	const prompt = buildFreshCallPrompt({
-		backend: params.backend,
-		task,
-		callerGardenId: params.callerGardenId,
-		nonce,
-	});
+	const composition: FreshCallComposition = {
+		prompt: buildFreshCallPrompt({
+			backend: params.backend,
+			task,
+			callerGardenId: params.callerGardenId,
+			nonce,
+		}),
+		bootstrapPayload: buildOmpBootstrapPayload({ callerGardenId: params.callerGardenId, nonce, task }),
+	};
 	const run = runTmux(
-		buildFreshCallArgs(placement, runtimePath, buildBackendArgs(params.backend, prompt, model), cwd),
+		buildFreshCallArgs(placement, runtimePath, buildBackendArgs(params.backend, composition, model), cwd),
 		env,
 	);
 	assertTmuxOk("new-window", run);
@@ -390,6 +543,7 @@ const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 	// The Copilot capability reasons keep their repair text on the leaf that decides them, so
 	// the sentence an operator reads cannot drift away from the predicate that produced it.
 	...COPILOT_PREFLIGHT_HINT,
+	...OMP_PREFLIGHT_HINT,
 	"no-tmux-context": "this agent is not running inside tmux, so there is no session to open a sibling beside",
 	"anchor-malformed": "TMUX_PANE is not a native pane id",
 	"anchor-unresolved": "tmux resolved no pane for this agent's anchor",

package/pi-extensions/lib/omp-fresh-preflight.ts

@@ -0,0 +1,275 @@
+/**
+ * omp-fresh-preflight — the pre-mutation capability check an OMP fresh call needs
+ * (#87 Bundle C, `docs/adding-a-harness.md` step 9 clauses 3, 4 and 5).
+ *
+ * Same shape and the same reasons as `copilot-fresh-preflight.ts`: a doctor answers "is this
+ * host correctly wired?" and may be slow, spawn the vendor and read live processes. This is not
+ * that. It answers ONE narrower question at ONE moment — before `mux-fresh-call` mutates the
+ * operator's tmux session, are the things the fresh contract requires actually in place on this
+ * filesystem?
+ *
+ * ── Why OMP has FIVE axes where Copilot has four ──
+ *
+ *   birth            — without the birth extension the session mints no record, so the callback
+ *                      carries no garden id and the sibling never becomes addressable.
+ *   MCP hand         — without the native `entwurf-bridge` server the callback tool does not
+ *                      exist in that session and the first turn has nothing to call.
+ *   receive          — without the receiver extension the sibling can be launched and can call
+ *                      home, and then nothing can ever be delivered TO it.
+ *   visible identity — the garden id must be on the harness's own persistent surface.
+ *   callback callable — THE OMP-SPECIFIC ONE. `tools.xdev` defaults to TRUE, which mounts MCP
+ *                      tools as `xd://` devices whose schemas never reach the prompt. The tool
+ *                      would be configured, the bridge would be running, and the model still
+ *                      could not call `mcp__entwurf_bridge_entwurf_v`. Step 9 clause 5 makes the
+ *                      callback the FIRST action, so a fresh call onto a default-config host
+ *                      opens a window that can never name itself. `[측정]` #87 A-lane: the
+ *                      vendor default wrapped the send tool and produced a false delivery report.
+ *
+ * Copilot's fourth axis is a statusline COMMAND that must resolve on PATH. OMP has no such
+ * surface: `ctx.ui.setStatus` inside the birth extension is the only thing that renders
+ * extension-owned text on a v18 TUI (`pi-extensions/meta-bridge-omp.ts:163-169`), and the
+ * vendor gates it on `statusLine.showHookStatus` (default true). So visible identity here is
+ * "the birth extension is installed AND the operator has not turned hook status off" — a
+ * different predicate for the same clause, derived rather than copied.
+ *
+ * ── What this deliberately does NOT claim ──
+ *
+ * Ownership/configuration truth only. It does NOT prove omp loaded the extensions, connected
+ * the MCP server, or rendered a garden id — that is runtime truth and belongs to
+ * `doctor-omp-bridge` / `doctor-omp-receive` / `doctor-omp-mcp` and to the clause 7 LIVE
+ * receipt. A green preflight is a statement about this filesystem, not a prediction about the
+ * next process.
+ *
+ * No vendor spawn, no network, no await, no mutation.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import * as path from "node:path";
+
+/** One reason per axis, plus the environment refusal. These strings are stable contract — they
+ * cross the public surfaces as `entwurf_fresh_call` refusals, so a caller can act on them. */
+export type OmpPreflightRejectReason =
+	| "omp-agent-dir-ambiguous"
+	| "omp-birth-unit-missing"
+	| "omp-mcp-hand-missing"
+	| "omp-receive-unit-missing"
+	| "omp-visible-identity-missing"
+	| "omp-callback-tool-uncallable";
+
+const BIRTH_UNIT = "entwurf-meta-omp";
+const RECEIVE_UNIT = "entwurf-receive-omp";
+const MCP_SERVER_KEY = "entwurf-bridge";
+/** Vendor load order, `utils/src/dirs.ts` MAIN_CONFIG_FILENAMES. */
+const MAIN_CONFIG_FILENAMES = ["config.yml", "config.yaml"] as const;
+/** `utils/src/dirs.ts` PROFILE_NAME_RE, reproduced from `scripts/omp-bridge-oracle.sh`. */
+const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
+
+/**
+ * The agent directory omp itself would read, or `null` for REFUSE.
+ *
+ * This is `omp_agent_dir` from `scripts/omp-bridge-oracle.sh`, expressed in the language this
+ * half is written in. It is a reproduction on purpose and not a spawn of that script: the fresh
+ * lane runs inside the pi extension and inside the bundled MCP child, and resolving a sibling
+ * shell script by relative path from two different emit depths is the exact arithmetic
+ * `check-capability-bundle-reach` exists to catch. The AGREEMENT of the two implementations is
+ * pinned by `check-omp-fresh-preflight`, which drives both over the same environments.
+ *
+ * A `PI_*` knob is a refusal and never a lookup (#87 ledger M6): omp is a pi fork that kept pi's
+ * env vocabulary, so `PI_CODING_AGENT_DIR` steers TWO harnesses and a value in the environment
+ * does not say which one it is addressing. Guessing here would aim the preflight at a directory
+ * no live omp reads, and it would report green off an empty one.
+ */
+export function ompAgentDir(env: NodeJS.ProcessEnv): string | null {
+	const explicit = env.ENTWURF_OMP_AGENT_DIR;
+	if (typeof explicit === "string" && explicit.length > 0) {
+		const home = env.HOME;
+		const expanded =
+			explicit === "~" || explicit.startsWith("~/")
+				? typeof home === "string" && home.length > 0
+					? path.join(home, explicit.slice(1))
+					: null
+				: explicit;
+		return expanded === null ? null : path.resolve(expanded);
+	}
+	if (typeof env.PI_CODING_AGENT_DIR === "string" && env.PI_CODING_AGENT_DIR.length > 0) return null;
+	if (typeof env.PI_CONFIG_DIR === "string" && env.PI_CONFIG_DIR.length > 0) return null;
+	const ompProfile = env.OMP_PROFILE;
+	const hasOmpProfile = typeof ompProfile === "string" && ompProfile.length > 0;
+	if (typeof env.PI_PROFILE === "string" && env.PI_PROFILE.length > 0 && !hasOmpProfile) return null;
+	const home = env.HOME;
+	if (typeof home !== "string" || home.length === 0) return null;
+	if (hasOmpProfile) {
+		if (!PROFILE_NAME_RE.test(ompProfile)) return null;
+		return path.join(home, ".omp", "profiles", ompProfile, "agent");
+	}
+	return path.join(home, ".omp", "agent");
+}
+
+function isDir(p: string): boolean {
+	try {
+		return statSync(p).isDirectory();
+	} catch {
+		// Bounded environment probing, Hard Rule 15's stated exception.
+		return false;
+	}
+}
+
+/** A JSON object or nothing. Unreadable, unparseable and not-an-object are the SAME answer,
+ * because the caller's next move is identical in all three: run the installer. */
+function readJsonObject(file: string): Record<string, unknown> | null {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+		return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+			? (parsed as Record<string, unknown>)
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The effective value of one TOP-LEVEL-then-one-key path in omp's config, as a tri-state:
+ * `true` / `false` / `null` for "not stated, or not readable with confidence".
+ *
+ * A deliberately NARROW block-YAML reader — it understands exactly the shape these two settings
+ * are written in (`tools:` newline, two-space `xdev: false`) and answers `null` for everything
+ * else. It mirrors `scripts/omp-tool-surface.py`'s scalar vocabulary for booleans, including its
+ * `true/yes/on/y` word set and its comment stripping, but it does NOT try to be that parser: the
+ * Python leaf reports a full verdict for a doctor, this one answers one question for a refusal.
+ *
+ * The tri-state is what makes both callers able to fail in the direction their axis needs, so
+ * neither has to invent a default here.
+ */
+export function readOmpConfigFlag(agentDir: string, section: string, key: string): boolean | null {
+	let text: string | null = null;
+	for (const name of MAIN_CONFIG_FILENAMES) {
+		const candidate = path.join(agentDir, name);
+		if (!existsSync(candidate)) continue;
+		try {
+			if (statSync(candidate).isDirectory()) return null;
+			text = readFileSync(candidate, "utf8");
+		} catch {
+			return null;
+		}
+		break;
+	}
+	if (text === null) return null;
+	// A tab anywhere in the body makes this not-YAML for the vendor's own reader; refuse rather
+	// than guess which indentation the vendor would have seen.
+	let inSection = false;
+	// The indent of the section's IMMEDIATE children, learned from the first one. Matching a key
+	// at any deeper indent would read `tools.nested.xdev` as `tools.xdev` — a fail-OPEN misread
+	// that would preflight green off a config which never set the flag. Caught by
+	// `check-omp-fresh-preflight` when this reader was first compared against the python leaf.
+	let childIndent = -1;
+	for (const raw of text.split("\n")) {
+		const body = stripComment(raw);
+		if (body.trim() === "") continue;
+		if (body.includes("\t")) return null;
+		const indent = body.length - body.trimStart().length;
+		const trimmed = body.trim();
+		if (!inSection) {
+			if (indent === 0 && trimmed === `${section}:`) inSection = true;
+			continue;
+		}
+		if (indent === 0) break; // the section ended at the next top-level key
+		if (childIndent === -1) childIndent = indent;
+		if (indent !== childIndent) continue; // a grandchild, or a mis-indented line: not our key
+		const colon = trimmed.indexOf(":");
+		if (colon <= 0) continue;
+		if (trimmed.slice(0, colon).trim() !== key) continue;
+		return parseBool(trimmed.slice(colon + 1).trim());
+	}
+	return null;
+}
+
+/** Comment stripping with the same quote awareness as `omp-tool-surface.py:strip_comment`. */
+function stripComment(raw: string): string {
+	let inSingle = false;
+	let inDouble = false;
+	let escaped = false;
+	for (let i = 0; i < raw.length; i++) {
+		const ch = raw[i];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (ch === "\\" && inDouble) {
+			escaped = true;
+			continue;
+		}
+		if (ch === "'" && !inDouble) inSingle = !inSingle;
+		else if (ch === '"' && !inSingle) inDouble = !inDouble;
+		else if (ch === "#" && !inSingle && !inDouble) return raw.slice(0, i).trimEnd();
+	}
+	return raw.trimEnd();
+}
+
+/** `omp-tool-surface.py:parse_scalar`'s boolean vocabulary; anything else is "not a boolean". */
+function parseBool(text: string): boolean | null {
+	const folded = text.toLowerCase();
+	if (["true", "yes", "on", "y"].includes(folded)) return true;
+	if (["false", "no", "off", "n"].includes(folded)) return false;
+	return null;
+}
+
+/**
+ * The five axes, decided in the order an operator should repair them. Returns the FIRST missing
+ * capability, or `null` when every one is in place.
+ *
+ * Order is not cosmetic. The agent dir comes first because every other predicate is a path under
+ * it — reporting "birth unit missing" while the directory itself is ambiguous would send the
+ * operator to reinstall into a directory omp may never read. Birth precedes the rest because a
+ * host with no birth unit has nothing else worth checking, and visible identity depends on the
+ * same unit.
+ */
+export function ompFreshPreflight(env: NodeJS.ProcessEnv): OmpPreflightRejectReason | null {
+	const agentDir = ompAgentDir(env);
+	if (agentDir === null) return "omp-agent-dir-ambiguous";
+
+	const extensions = path.join(agentDir, "extensions");
+	if (!isDir(path.join(extensions, BIRTH_UNIT))) return "omp-birth-unit-missing";
+
+	// The native MCP entry omp reads, at the ONE non-configurable path the installer owns
+	// (`scripts/omp-mcp-bridge.sh`: `<resolved omp agent dir>/mcp.json`).
+	const mcp = readJsonObject(path.join(agentDir, "mcp.json"));
+	const servers = mcp?.mcpServers;
+	const hand =
+		typeof servers === "object" && servers !== null && !Array.isArray(servers)
+			? (servers as Record<string, unknown>)[MCP_SERVER_KEY]
+			: undefined;
+	if (typeof hand !== "object" || hand === null || Array.isArray(hand)) return "omp-mcp-hand-missing";
+
+	if (!isDir(path.join(extensions, RECEIVE_UNIT))) return "omp-receive-unit-missing";
+
+	// Visible identity: the vendor default is TRUE, so only an explicit false refuses. An
+	// unreadable config is not a refusal HERE — it is one on the axis below, which needs proof
+	// rather than absence, and reporting the same file twice under two names would send an
+	// operator looking for two problems.
+	if (readOmpConfigFlag(agentDir, "statusLine", "showHookStatus") === false) return "omp-visible-identity-missing";
+
+	// Callback callable: the vendor default is TRUE and true is the BROKEN state, so this axis
+	// requires positive proof of `false`. Absent file, absent key and unparseable config all
+	// refuse — that is the fail-closed direction, and it is the opposite of the axis above for
+	// the same reason: each fails toward the value the vendor would actually apply.
+	if (readOmpConfigFlag(agentDir, "tools", "xdev") !== false) return "omp-callback-tool-uncallable";
+
+	return null;
+}
+
+/** Repair text lives on the leaf that decides the predicate, so the sentence an operator reads
+ * cannot drift away from the check that produced it. */
+export const OMP_PREFLIGHT_HINT: Record<OmpPreflightRejectReason, string> = {
+	"omp-agent-dir-ambiguous":
+		"an inherited PI_CODING_AGENT_DIR / PI_CONFIG_DIR / PI_PROFILE makes it ambiguous which agent directory omp would read (omp is a pi fork and shares those names) — unset it, or set ENTWURF_OMP_AGENT_DIR explicitly; guessing would preflight a directory no live omp reads",
+	"omp-birth-unit-missing":
+		"this host has no OMP birth extension, so the sibling would mint no record and its callback would carry no garden id — run `entwurf install-omp-bridge`",
+	"omp-mcp-hand-missing":
+		"this host has no entwurf-bridge server in omp's own mcp.json, so the callback tool would not exist in that session — run `entwurf install-omp-mcp`",
+	"omp-receive-unit-missing":
+		"this host has no OMP receiver extension, so the sibling could call home and nothing could ever be delivered to it — run `entwurf install-omp-receive`",
+	"omp-visible-identity-missing":
+		"omp's statusLine.showHookStatus is set to false, so the citizen's garden id would render nowhere on its own TUI — remove that setting from the omp config",
+	"omp-callback-tool-uncallable":
+		"omp's tools.xdev is not set to false, so MCP tools mount as xd:// devices whose schemas never reach the prompt and the model cannot call the callback tool — set `tools: xdev: false` in the omp agent config",
+};