@junghanacs/entwurf 0.22.0 → 0.23.0

package/scripts/install-herdr-ci.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# install-herdr-ci — put the MEASURED herdr binary on PATH for one CI job, and nothing else.
+#
+# This is not an installer for people. `entwurf setup` does not call it, the package does not
+# ship it as a command, and it never writes outside the runner's temp dir: Hard Rule 17 says
+# Entwurf supplies Entwurf's bytes, never a harness or a placement owner's. A CI job that wants
+# the herdr rail proven fetches the exact asset this repository has measured, checks its digest
+# BEFORE the file is ever made executable, and exposes only that one directory to later steps.
+#
+# What is deliberately NOT here, each for a reason:
+#   - no `curl … | sh`. A pipe to a shell has no version and no digest to check; whatever the
+#     upstream script does today it can do something else tomorrow, and the whole point of this
+#     file is that CI runs a byte we have named.
+#   - no package manager (brew/mise/nix). Each adds a layer whose contents we would then be
+#     asserting about without measuring.
+#   - no `latest`. A mutable URL turns a green run into a claim about a binary nobody chose.
+#   - no `gh attestation verify`. `[측정 2026-09-14, gh 2.97.0]` it cannot close herdr's
+#     predicate (`in-toto release/v0.2`) — default is 404, explicit is "no attestations found",
+#     while the REST API returns the attestation. A check we cannot run is not a check.
+#   - no global install, no ~/.local/bin, no sudo. The binary lives and dies with the job.
+#
+# Every version and digest comes from scripts/fixtures/herdr-supply.json. This file contains
+# none of its own, on purpose: two copies of a digest is how a pin drifts.
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+manifest="${repo_dir}/scripts/fixtures/herdr-supply.json"
+
+fail() {
+	echo "[install-herdr-ci] FAIL — $1" >&2
+	exit 1
+}
+
+[ -f "$manifest" ] || fail "the supply manifest is missing: ${manifest}"
+
+# The runner's temp dir in CI; a private mktemp when someone runs this by hand. Never a
+# directory that outlives the job.
+dest_dir="${RUNNER_TEMP:-}"
+if [ -z "$dest_dir" ]; then
+	dest_dir="$(mktemp -d)"
+fi
+mkdir -p "$dest_dir"
+
+read_manifest() {
+	node -e '
+		const fs = require("node:fs");
+		const m = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+		const arch = process.argv[2];
+		const asset = m.assets[arch];
+		if (!asset) {
+			// Fail closed. A machine architecture we have never measured does not get a
+			// "closest" binary — there is no such thing.
+			process.stderr.write(`unsupported architecture ${arch}; measured: ${Object.keys(m.assets).join(", ")}\n`);
+			process.exit(3);
+		}
+		process.stdout.write([m.version, m.releaseUrlPrefix, m.tag, asset.name, asset.sha256].join("\n"));
+	' "$manifest" "$1"
+}
+
+arch="$(uname -m)"
+if ! fields="$(read_manifest "$arch")"; then
+	fail "no measured herdr asset for $(uname -m) — the supply manifest owns that set"
+fi
+version="$(echo "$fields" | sed -n 1p)"
+url_prefix="$(echo "$fields" | sed -n 2p)"
+tag="$(echo "$fields" | sed -n 3p)"
+asset_name="$(echo "$fields" | sed -n 4p)"
+expected_sha="$(echo "$fields" | sed -n 5p)"
+
+url="${url_prefix}/${tag}/${asset_name}"
+target="${dest_dir}/herdr"
+
+echo "[install-herdr-ci] fetching ${asset_name} (${tag}) for ${arch}"
+curl -fsSL --retry 3 --retry-delay 2 -o "$target" "$url" || fail "download failed: ${url}"
+
+# ORDER IS THE SAFETY ARGUMENT: the digest is checked while the file is still inert data.
+# chmod comes after, so a byte we did not choose never becomes a thing this job can run.
+actual_sha="$(sha256sum "$target" | cut -d' ' -f1)"
+if [ "$actual_sha" != "$expected_sha" ]; then
+	rm -f "$target"
+	fail "digest mismatch for ${asset_name}: expected ${expected_sha}, got ${actual_sha}"
+fi
+chmod +x "$target"
+
+reported="$("$target" --version 2>/dev/null || true)"
+case "$reported" in
+*"herdr ${version}"*) ;;
+*) fail "the verified binary reports '${reported}', not 'herdr ${version}' — the manifest and the artifact disagree" ;;
+esac
+
+# Only this directory reaches later steps. Nothing is copied into a shared bin dir.
+if [ -n "${GITHUB_PATH:-}" ]; then
+	echo "$dest_dir" >>"$GITHUB_PATH"
+fi
+echo "[install-herdr-ci] ok — ${reported} at ${target} (sha256 ${expected_sha})"
+echo "$dest_dir"

package/scripts/lib/codex-fresh-live-protocol.ts

@@ -55,11 +55,11 @@ export function buildCodexInstruction(input: CodexInstructionInput): string {
 		'NO cwd parameter and NO placement parameter, and task "After your automatic callback succeeds, answer ACK and ' +
 		'stop. Do not open another sibling."\n' +
 		"2. Stop and wait for the Pi callback delivered into this Codex thread. Accept only a callback whose body " +
-		"repeats the exact nonce from your LAUNCH receipt and whose sender envelope names a garden id.\n" +
+		"repeats the exact nonce from your LAUNCH receipt and whose sender envelope carries a garden id on its `session:` line.\n" +
 		`3. Only after that match, call public mcp__entwurf_bridge__entwurf_v2 once with target ${input.callerGid}, ` +
 		"intent fire-and-forget, wants_reply false, and message:\n" +
 		`${input.finalToken}\nPI_LAUNCH_NONCE=<exact launch nonce>\nPI_CALLBACK_NONCE=<same exact nonce>\n` +
-		"PI_CALLBACK_FROM=<sender-envelope garden id>\nPI_SESSION_ID=<exact $session id from the LAUNCH receipt>\n" +
+		"PI_CALLBACK_FROM=<the garden id on the callback envelope's `session:` line — NOT the model name on its `from:` line>\nPI_SESSION_ID=<exact $session id from the LAUNCH receipt>\n" +
 		"PI_WINDOW_ID=<exact @window id from the LAUNCH receipt>\nDo not claim completion in prose."
 	);
 }

package/scripts/lib/tree-digest.ts

@@ -0,0 +1,97 @@
+/**
+ * tree-digest — one deterministic digest of a whole directory tree, for gates that claim a tree is
+ * UNCHANGED.
+ *
+ * WHY THIS EXISTS. Two #116 M3-b3 oracles compared a sorted list of relative paths (one of them with
+ * sizes) and called the result "byte-identical". A same-length content edit passes both — which is
+ * precisely the shape a refusal-must-not-mutate claim needs to catch, because a transaction that
+ * rewrites a file in place rarely changes its length. So the digest here reads the actual bytes.
+ *
+ * WHAT IS IN IT: every entry's relative path, its node TYPE, and for a regular file its permission
+ * bits, its size and its whole content; for a symlink its target; for a directory its own entry
+ * count, so an emptied directory and a removed one are different facts. That makes the honest claim
+ * "content + mode + topology", which is what the callers now say.
+ *
+ * FRAMING IS LENGTH-PREFIXED. A digest built by concatenating names cannot tell `a/b` + `c` from
+ * `a` + `b/c`; every field is therefore written as `label:<byteLength>:<bytes>\0`, so no boundary
+ * between two fields can be spelled by the contents of one.
+ *
+ * MEMORY IS BOUNDED. A runtime tree here is hundreds of megabytes, so files are hashed in 64 KiB
+ * chunks through one reused buffer rather than read whole. No `sha256sum`, no shell: a gate that
+ * shells out to hash acquires a dependency the hosts it runs on do not owe it.
+ */
+
+import { createHash, type Hash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const CHUNK_BYTES = 64 * 1024;
+
+function field(hash: Hash, label: string, value: string | number): void {
+	const bytes = Buffer.from(String(value), "utf8");
+	hash.update(`${label}:${bytes.length}:`);
+	hash.update(bytes);
+	hash.update("\0");
+}
+
+function hashFileContent(hash: Hash, file: string): void {
+	const fd = fs.openSync(file, "r");
+	try {
+		const buf = Buffer.allocUnsafe(CHUNK_BYTES);
+		let read = fs.readSync(fd, buf, 0, CHUNK_BYTES, null);
+		while (read > 0) {
+			hash.update(buf.subarray(0, read));
+			read = fs.readSync(fd, buf, 0, CHUNK_BYTES, null);
+		}
+	} finally {
+		fs.closeSync(fd);
+	}
+	hash.update("\0");
+}
+
+/**
+ * The digest of `root`, or the literal `"absent"` when nothing is there.
+ *
+ * @returns `sha256-<hex>` over content + mode + topology, or `absent`.
+ */
+export function treeDigest(root: string): string {
+	const top = fs.lstatSync(root, { throwIfNoEntry: false });
+	if (top === undefined) return "absent";
+	const hash = createHash("sha256");
+	if (!top.isDirectory()) {
+		field(hash, top.isSymbolicLink() ? "root-symlink" : "root-nondir", path.basename(root));
+		if (top.isSymbolicLink()) field(hash, "target", fs.readlinkSync(root));
+		else if (top.isFile()) hashFileContent(hash, root);
+		return `sha256-${hash.digest("hex")}`;
+	}
+	const walk = (dir: string): void => {
+		const entries = fs
+			.readdirSync(dir, { withFileTypes: true })
+			.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+		field(hash, "dir", path.relative(root, dir) || ".");
+		field(hash, "entries", entries.length);
+		for (const entry of entries) {
+			const abs = path.join(dir, entry.name);
+			const rel = path.relative(root, abs);
+			if (entry.isSymbolicLink()) {
+				field(hash, "symlink", rel);
+				field(hash, "target", fs.readlinkSync(abs));
+			} else if (entry.isDirectory()) {
+				field(hash, "subdir", rel);
+			} else if (entry.isFile()) {
+				const stat = fs.statSync(abs);
+				field(hash, "file", rel);
+				field(hash, "mode", (stat.mode & 0o7777).toString(8));
+				field(hash, "size", stat.size);
+				hashFileContent(hash, abs);
+			} else {
+				field(hash, "other", rel);
+			}
+		}
+		for (const entry of entries) {
+			if (entry.isDirectory() && !entry.isSymbolicLink()) walk(path.join(dir, entry.name));
+		}
+	};
+	walk(root);
+	return `sha256-${hash.digest("hex")}`;
+}

package/scripts/meta-bridge-install.sh

@@ -170,7 +170,13 @@ echo "[meta-bridge-install] platform=$(uname -s) node=$NODE_VER ($NODE_BIN) clau
 # settings.json / ~/.claude.json. Re-runs preserve the first snapshot, so
 # uninstall restores the true pre-entwurf state rather than the last install
 # run's already-managed values.
-python3 "$REPO/scripts/meta-bridge-state.py" prepare --repo "$REPO" --asm "$ASM"
+# #116 M3-b2 — decide before writing. An aggregate activation has to be able to say "nothing will
+# fail once I start" before it starts, and that promise is only real if this half can be checked
+# without mutating.
+python3 "$REPO/scripts/meta-bridge-state.py" preflight-install --repo "$REPO" --asm "$ASM" \
+  ${ENTWURF_PLUGIN_RUNTIME:+--plugin-runtime "$ENTWURF_PLUGIN_RUNTIME"}
+python3 "$REPO/scripts/meta-bridge-state.py" prepare --repo "$REPO" --asm "$ASM" \
+  ${ENTWURF_PLUGIN_RUNTIME:+--plugin-runtime "$ENTWURF_PLUGIN_RUNTIME"}
 
 # --- 1. assemble a self-contained, node-baked plugin ------------------------
 rm -rf "$ASM"
@@ -251,6 +257,15 @@ claude mcp remove pi-tools-bridge -s user >/dev/null 2>&1 || true
 # in node_modules/@junghanacs/entwurf) wires the STABLE `entwurf-bridge` bin shim; baking
 # the pnpm store path here would go stale on any peer/version bump. A dev clone pins to
 # this clone's start.sh. Both branches carry the same env desired_mcp() writes.
+# #116 M3-b2 — the explicit plugin mode comes FIRST, and it is derived, not supplied. A Herdr
+# plugin activates where nothing entwurf is on PATH, so the bare shim cannot resolve; the absolute
+# bridge under the certified stable runtime can. `desired_mcp()` above is still the SSOT — this
+# branch mirrors it, as the comment on the block already demanded.
+if [ -n "${ENTWURF_PLUGIN_RUNTIME:-}" ]; then
+  claude mcp add -s user entwurf-bridge \
+    -e ENTWURF_BRIDGE_EXTERNAL_AGENT_ID=external-mcp/claude-code \
+    -- "$ENTWURF_PLUGIN_RUNTIME/node_modules/.bin/entwurf-bridge" >/dev/null
+else
 case "$REPO" in
   */node_modules/@junghanacs/entwurf)
     claude mcp add -s user entwurf-bridge \
@@ -261,6 +276,7 @@ case "$REPO" in
       -e ENTWURF_BRIDGE_EXTERNAL_AGENT_ID=external-mcp/claude-code \
       -- bash "$REPO/mcp/entwurf-bridge/start.sh" >/dev/null ;;
 esac
+fi
 # Capture, THEN match — and require BOTH the exit code and the content.
 # `<cli> | grep -q` under `set -o pipefail` is a race, not a test: grep exits at the
 # first match and closes the pipe, the still-writing CLI dies of SIGPIPE (141), and
@@ -283,7 +299,8 @@ echo "[meta-bridge-install] installed entwurf-bridge MCP (scope: user = global r
 # Re-assert the repo-owned keyset through our stateful manager. The Claude CLI
 # calls above are allowed to maintain their cache/registry files, but the
 # operator-facing JSON keys are owned here so uninstall can be honest.
-python3 "$REPO/scripts/meta-bridge-state.py" apply --repo "$REPO" --asm "$ASM"
+python3 "$REPO/scripts/meta-bridge-state.py" apply --repo "$REPO" --asm "$ASM" \
+  ${ENTWURF_PLUGIN_RUNTIME:+--plugin-runtime "$ENTWURF_PLUGIN_RUNTIME"}
 
 # --- evidence ---------------------------------------------------------------
 echo "--- claude plugin list ---"

package/scripts/meta-bridge-state.py

@@ -21,6 +21,9 @@ MARKETPLACE = "meta-bridge-local"
 PLUGIN_REF = f"{PLUGIN}@{MARKETPLACE}"
 STATE_VERSION = 1
 OWNER = "entwurf meta-bridge"
+# The only suffix an assembled marketplace path may end in — the inverse acts on that address, and
+# the doctor already refuses anything else, so the preflight uses the SAME shape (not a looser one).
+ASSEMBLED_SUFFIX = "/entwurf/meta-bridge/.assembled"
 
 PERMISSION_ALLOW = [
     "Bash",
@@ -304,6 +307,44 @@ def is_installed_package(repo: Path) -> bool:
     return parts[-3:] == ("node_modules", "@junghanacs", "entwurf")
 
 
+# #116 M3-b2 — the explicit plugin mode. A Herdr plugin activates on a host where nothing entwurf is
+# on PATH, so the bare bin shim cannot resolve. In that mode the commands are DERIVED from the
+# certified stable active runtime root: the caller passes the root, these helpers append the fixed
+# suffixes, and nothing accepts an arbitrary command. The default installed branch below is
+# untouched — mode is an explicit input, never a path heuristic, because a stable-runtime install
+# lives at `.../active/node_modules/@junghanacs/entwurf` and already satisfies every layout test.
+PLUGIN_RUNTIME: Path | None = None
+
+
+def stable_active_root() -> Path:
+    """The ONE runtime address, derived from this process's XDG/HOME exactly as the runtime owner
+    derives it (`scripts/herdr-runtime.mjs` resolveRuntimeLayout). A gate pins the two equal."""
+    data_home = os.environ.get("XDG_DATA_HOME") or os.path.join(os.path.expanduser("~"), ".local", "share")
+    return Path(data_home) / "entwurf" / "herdr-plugin" / "runtime" / "active"
+
+
+def set_plugin_runtime(root: Path | None) -> None:
+    global PLUGIN_RUNTIME
+    if root is None:
+        PLUGIN_RUNTIME = None
+        return
+    if not root.is_absolute():
+        die(f"--plugin-runtime must be an ABSOLUTE stable runtime root, got {root}")
+    normalised = Path(os.path.normpath(str(root)))
+    # Named, not chosen: the caller may say which root, and it is accepted only when it IS this
+    # host's stable one. Any absolute directory would let a mode flag point Claude's MCP command at
+    # an executable of the caller's choosing.
+    expected = stable_active_root()
+    if normalised != expected:
+        die(f"--plugin-runtime must be this host's stable runtime root {expected}, got {normalised}")
+    PLUGIN_RUNTIME = normalised
+
+
+def plugin_bin(name: str) -> str:
+    assert PLUGIN_RUNTIME is not None
+    return str(PLUGIN_RUNTIME / "node_modules" / ".bin" / name)
+
+
 def desired_mcp(repo: Path) -> dict[str, Any]:
     env = {
         # #50 C4: anonymous sends are refused by the BRIDGE DEFAULT now — the
@@ -313,6 +354,8 @@ def desired_mcp(repo: Path) -> dict[str, Any]:
         # session always has an authoritative garden-id sender.
         "ENTWURF_BRIDGE_EXTERNAL_AGENT_ID": "external-mcp/claude-code",
     }
+    if PLUGIN_RUNTIME is not None:
+        return {"type": "stdio", "command": plugin_bin("entwurf-bridge"), "args": [], "env": env}
     if is_installed_package(repo):
         # Installed package: wire the STABLE `entwurf-bridge` bin shim that npm/pnpm
         # place on PATH. Baking repo/mcp/entwurf-bridge/start.sh would embed the pnpm
@@ -333,6 +376,8 @@ def desired_mcp(repo: Path) -> dict[str, Any]:
 
 
 def desired_statusline(repo: Path) -> dict[str, Any]:
+    if PLUGIN_RUNTIME is not None:
+        return {"type": "command", "command": plugin_bin("entwurf-statusline")}
     if is_installed_package(repo):
         # Installed package: mirror the MCP stable-bin pattern. The statusLine is
         # executed at render time, so a bare bin shim lets npm/pnpm update the
@@ -342,20 +387,23 @@ def desired_statusline(repo: Path) -> dict[str, Any]:
     return {"type": "command", "command": str((repo / "scripts" / "meta-bridge-statusline.sh").resolve())}
 
 
-def prepare(repo: Path, asm: Path) -> None:
-    existing = load_state(required=False)
-    state = existing if existing is not None else init_state(repo, asm)
-    state["updatedAt"] = iso_now()
-    state["repo"] = str(repo.resolve())
-    state["assembledMarketplacePath"] = str(asm.resolve())
-
+def read_live_documents() -> tuple[dict[str, Any], dict[str, Any]]:
     settings = read_json(settings_path(), {})
     root = read_json(claude_root_config_path(), {})
     if not isinstance(settings, dict):
         die(f"{settings_path()} root must be a JSON object")
     if not isinstance(root, dict):
         die(f"{claude_root_config_path()} root must be a JSON object")
+    return settings, root
+
 
+def plan_snapshots(state: dict[str, Any], repo: Path, asm: Path, settings: dict[str, Any], root: dict[str, Any]) -> None:
+    """Every snapshot decision `prepare` makes, in one place.
+
+    #116 M3-b2 amendment. `preflight-install` runs this against DEEP COPIES so the forward promise
+    is the real plan and not a JSON-object smoke test: a preflight that only checked the documents
+    parse would go green and then let `prepare` die on an array-type mismatch it never looked at.
+    """
     snapshot_value(
         state,
         "settings",
@@ -397,6 +445,15 @@ def prepare(repo: Path, asm: Path) -> None:
         legacy_absent_if_equal=desired_mcp(repo),
     )
 
+
+def prepare(repo: Path, asm: Path) -> None:
+    existing = load_state(required=False)
+    state = existing if existing is not None else init_state(repo, asm)
+    state["updatedAt"] = iso_now()
+    state["repo"] = str(repo.resolve())
+    state["assembledMarketplacePath"] = str(asm.resolve())
+    settings, root = read_live_documents()
+    plan_snapshots(state, repo, asm, settings, root)
     write_json(state_path(), state, mode=0o600)
     print(f"[meta-bridge-state] prepared {state_path()}")
 
@@ -446,10 +503,41 @@ def apply(repo: Path, asm: Path) -> None:
     print("[meta-bridge-state] applied managed keyset (settings.json + user MCP)")
 
 
-def restore_entry(obj: dict[str, Any], entry: dict[str, Any]) -> None:
+def certify_entry(obj: dict[str, Any], entry: dict[str, Any], where: str = "state entry") -> str:
+    """Prove this entry COULD be restored, and write nothing.
+
+    #116 M3-b2 amendment. This is the read-only twin of `restore_entry`, and it exists as one
+    function rather than two because the first cut of the uninstall preflight re-implemented the
+    checks and knew only ONE of the three entry shapes: it demanded `original` on every entry, while
+    `snapshot_array_items` writes `{originalExisted, added}`. Every real Claude activation therefore
+    failed its own preflight. A preflight that re-derives the restore rules will drift from them
+    again the next time a kind is added — so `restore_entry` calls THIS, and so does the preflight.
+    """
     path = entry.get("path")
     if not isinstance(path, list) or not all(isinstance(p, str) for p in path):
-        die("bad state entry path")
+        die(f"{where}: bad state entry path")
+    kind = entry.get("kind")
+    if kind in ("map-entry", "scalar"):
+        original = entry.get("original")
+        if not isinstance(original, dict) or "existed" not in original:
+            die(f"{where}: bad scalar/map original in state")
+        return kind
+    if kind == "array-items":
+        if "originalExisted" not in entry:
+            die(f"{where}: array-items entry records no originalExisted")
+        if not isinstance(entry.get("added", []), list):
+            die(f"{where}: bad array added list in state")
+        existed, value = get_nested(obj, path)
+        if existed and not isinstance(value, list):
+            die(f"{where}: {'.'.join(path)} exists but is not an array; restoration is not applicable")
+        return kind
+    die(f"{where}: unknown state entry kind {kind!r}")
+    raise AssertionError("unreachable")
+
+
+def restore_entry(obj: dict[str, Any], entry: dict[str, Any]) -> None:
+    certify_entry(obj, entry)
+    path = entry.get("path")
     kind = entry.get("kind")
     if kind in ("map-entry", "scalar"):
         original = entry.get("original")
@@ -525,8 +613,71 @@ def relinquish_retired_scalar(
 
 
 def preflight_uninstall() -> None:
-    load_state(required=True)
-    print(f"[meta-bridge-state] uninstall preflight ok ({state_path()})")
+    """Prove the ENTIRE restoration plan is applicable, writing nothing.
+
+    #116 M3-b2. This used to be `load_state(required=True)` and a print — it proved the ledger
+    existed and nothing else. An aggregate deactivate that calls it and then claims "every inverse
+    was preflighted" would be asserting a check that had not run, and a teardown that starts
+    mutating on that promise is how a Claude failure strands a Pi half. Every entry is certified
+    through the SAME function `restore_entry` uses, so the two cannot drift.
+    """
+    state = load_state(required=True)
+    assert state is not None
+    owner = state.get("owner")
+    if owner != OWNER:
+        die(f"{state_path()} is not ours: owner={owner!r} (expected {OWNER!r})")
+    settings, root = read_live_documents()
+    certified = 0
+    for path_key, doc in (("settings", settings), ("claudeRoot", root)):
+        entries = state.get("files", {}).get(path_key, {}).get("keys", {})
+        if not isinstance(entries, dict):
+            die(f"{state_path()} has no {path_key} key map")
+        for name, entry in entries.items():
+            if not isinstance(entry, dict):
+                die(f"{state_path()} {path_key} entry {name!r} is not a record")
+            certify_entry(doc, entry, f"{path_key} entry {name!r}")
+            certified += 1
+    certify_assembled_path(state.get("assembledMarketplacePath"))
+    print(
+        f"[meta-bridge-state] uninstall preflight ok ({state_path()}): owner={owner}, "
+        f"settings+claudeRoot parse, {certified} restore entries applicable, "
+        f"assembled={state.get('assembledMarketplacePath')}"
+    )
+
+
+def certify_assembled_path(recorded: Any) -> None:
+    """The recorded marketplace path is an address the inverse acts on, so its SHAPE is checked."""
+    if not isinstance(recorded, str) or not recorded:
+        die(f"{state_path()} records no assembledMarketplacePath")
+    if not os.path.isabs(recorded):
+        die(f"{state_path()} assembledMarketplacePath is not absolute: {recorded}")
+    if not recorded.endswith(ASSEMBLED_SUFFIX):
+        die(f"{state_path()} assembledMarketplacePath does not end in {ASSEMBLED_SUFFIX}: {recorded}")
+
+
+def preflight_install(repo: Path, asm: Path) -> None:
+    """The forward half of the same promise: run the REAL plan on copies, write nothing.
+
+    An aggregate activation has to be able to say "nothing will fail once I start" before it starts.
+    A preflight that only checked the documents parse would go green and then let `prepare` die on
+    an array-type mismatch it never looked at, so this walks `plan_snapshots` — the very function
+    `prepare` calls — against deep copies and certifies every entry it produces.
+    """
+    settings, root = read_live_documents()
+    existing = load_state(required=False)
+    state = copy.deepcopy(existing) if existing is not None else init_state(repo, asm)
+    plan_snapshots(state, repo, asm, copy.deepcopy(settings), copy.deepcopy(root))
+    planned = 0
+    for path_key, doc in (("settings", settings), ("claudeRoot", root)):
+        for name, entry in state["files"][path_key]["keys"].items():
+            certify_entry(doc, entry, f"planned {path_key} entry {name!r}")
+            planned += 1
+    certify_assembled_path(str(asm.resolve()))
+    mode = "plugin-runtime" if PLUGIN_RUNTIME is not None else ("installed" if is_installed_package(repo) else "clone")
+    print(
+        f"[meta-bridge-state] install preflight ok (mode={mode}, {planned} planned entries certified, "
+        f"mcp={desired_mcp(repo)['command']}, statusline={desired_statusline(repo)['command']}, asm={asm})"
+    )
 
 
 def uninstall() -> None:
@@ -667,6 +818,7 @@ def main() -> int:
         choices=[
             "prepare",
             "apply",
+            "preflight-install",
             "preflight-uninstall",
             "uninstall",
             "assembled-path",
@@ -678,6 +830,7 @@ def main() -> int:
     )
     parser.add_argument("--repo", default=Path(__file__).resolve().parents[1], type=Path)
     parser.add_argument("--asm", default=None, type=Path)
+    parser.add_argument("--plugin-runtime", default=None, type=Path)
     args = parser.parse_args()
     repo = args.repo.resolve()
     # The live artifact always lives under the XDG data dir — dev clone and
@@ -688,10 +841,13 @@ def main() -> int:
     default_asm = xdg_data / "entwurf" / "meta-bridge" / ".assembled"
     asm = (args.asm or default_asm).resolve()
     try:
+        set_plugin_runtime(args.plugin_runtime)
         if args.command == "prepare":
             prepare(repo, asm)
         elif args.command == "apply":
             apply(repo, asm)
+        elif args.command == "preflight-install":
+            preflight_install(repo, asm)
         elif args.command == "preflight-uninstall":
             preflight_uninstall()
         elif args.command == "uninstall":

package/scripts/mutants/codex-caller-seat.json

@@ -157,10 +157,8 @@
 			"claim": "CODEX-SEAT-TITLE-BECOMES-DELIVERY-TARGET",
 			"title": "the caller's own garden address is replaced by the thread id the PANE TITLE matched, so a forgeable title decides who the fresh sibling is told to call back to. The sibling's first message would then be delivered against an identity nobody vouched for — the exact Hard Rule 16 crossing this lane is built to make impossible: the title is a placement input and may never become an address",
 			"subject": "pi-extensions/lib/mux-fresh-call.ts",
-			"find": ["\t\t\tcallerGardenId: params.callerGardenId,\n\t\t\tnonce,\n\t\t}),"],
-			"replace": [
-				"\t\t\tcallerGardenId: params.callerNativeSessionId ?? params.callerGardenId,\n\t\t\tnonce,\n\t\t}),"
-			],
+			"find": ["\t\t\tcallerGardenId,\n\t\t\tnonce,\n\t\t}),"],
+			"replace": ["\t\t\tcallerGardenId: params.callerNativeSessionId ?? callerGardenId,\n\t\t\tnonce,\n\t\t}),"],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
 			"timeoutSeconds": 120,
 			"signature": "[QK:CODEX-SEAT-TITLE-BECOMES-DELIVERY-TARGET]",
@@ -203,12 +201,12 @@
 		},
 		{
 			"claim": "CODEX-CALLER-PREFLIGHT-SURFACE-WIRED",
-			"title": "the bridge stops running the caller-side preflight, so a Codex caller with no `thread-id` in its terminal title gets the generic `unresolved` seat refusal instead of the installer that repairs it — a capability gap reported as an operator's missing TUI",
-			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"title": "the shared dispatcher stops running the caller-side preflight, so a Codex caller with no `thread-id` in its terminal title gets the generic `unresolved` seat refusal instead of the capability repair — and the MCP surface, its only supplier, cannot tell the two apart",
+			"subject": "pi-extensions/lib/fresh-call-dispatch.ts",
 			"find": [
-				"\t\t\t\ttargetMissing === null && callerNativeSessionId !== undefined && placement === undefined\n\t\t\t\t\t? codexCallerFreshPreflight(process.env)\n\t\t\t\t\t: null;"
+				"\t\ttargetMissing === null && request.callerNativeSessionId !== undefined && request.placement === undefined\n\t\t\t? codexCallerFreshPreflight(env)\n\t\t\t: null;"
 			],
-			"replace": ["\t\t\t\tnull;"],
+			"replace": ["\t\tnull;"],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
 			"timeoutSeconds": 120,
 			"signature": "[QK:CODEX-CALLER-PREFLIGHT-SURFACE-WIRED]",