@junghanacs/entwurf 0.21.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

@@ -39,7 +39,6 @@ export interface CodexInstructionInput {
 	finalToken: string;
 	callerGid: string;
 	piModel: string;
-	scratch: string;
 }
 
 /** The payload the initial Pi forwards verbatim. It names only Codex's own steps. */
@@ -47,14 +46,20 @@ export function buildCodexInstruction(input: CodexInstructionInput): string {
 	return (
 		`${input.waitToken}\nThis is the addressed instruction from the initial Pi caller. Execute once, with no shell, ` +
 		"terminal, screen inspection, or retry:\n" +
-		`1. Call public mcp__entwurf_bridge__entwurf_fresh_call once with backend pi, model ${input.piModel}, cwd ${input.scratch}, ` +
-		'NO placement, and task "After your automatic callback succeeds, answer ACK and stop. Do not open another sibling."\n' +
+		`1. Call public mcp__entwurf_bridge__entwurf_fresh_call once with backend pi, model ${input.piModel}, ` +
+		// NO placement AND NO cwd are both CLAIMS rather than conveniences, and they are two
+		// different ones. The seat must come from this Codex's own pane title (#95 lane B); the
+		// DIRECTORY must come from this Codex's own record (#95 lane C), which is a fact only
+		// because its thread now opens where its pane is rather than where the app-server sits.
+		// Omitting the parameter is the whole point — passing one would prove neither.
+		'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."
 	);
 }
@@ -71,6 +76,9 @@ export interface InitialPiPhaseOneInput {
 export function buildInitialPiPhaseOne(input: InitialPiPhaseOneInput): string {
 	return (
 		`${input.initialPiWaitToken}\nExecute this public-tool chain exactly once; do not use shell, terminal, screen text, or retries:\n` +
+		// NO placement on BOTH legs since #95 D1: an omitted seat is the caller's own session for
+		// every backend, so this Codex opens in S beside the Pi that called it — which is what
+		// puts its TUI somewhere the app-server's inherited `TMUX` does not point.
 		`1. Call entwurf_fresh_call with backend codex, model ${input.codexModel}, cwd ${input.scratch}, NO placement, and task ` +
 		`"After your required callback receipt, end the turn and wait passively for the addressed instruction containing ${input.codexWaitToken}. ` +
 		`Do not call shell, sleep, terminal, or any tool to wait."\n` +

package/scripts/lib/codex-fresh-source-receipts.ts

@@ -16,6 +16,33 @@ export interface ExpectedSourceToolCall {
 	arguments: Record<string, unknown>;
 }
 
+/**
+ * Compare source-call arguments by MEANING for the one key whose absence already means something,
+ * and byte-exactly for every other.
+ *
+ * `entwurf_v2`'s `wants_reply` is optional and absent IS false — the schema says so
+ * (`mcp/entwurf-bridge/src/index.ts:474`, `z.boolean().optional().describe("… (default false)")`)
+ * and the decider enforces it (`pi-extensions/lib/entwurf-v2-decider.ts:270`,
+ * `input.wantsReply ?? false`). So a model that reads "wants_reply false" in its instruction and
+ * simply omits the parameter has obeyed the instruction; nothing about the dispatch differs.
+ *
+ * `[측정 2026-09-16]` this cost a LIVE run at assertion 43: the initial Pi called `entwurf_v2`
+ * with byte-identical `target`, `intent` and `message` and no `wants_reply` key, and the
+ * `isDeepStrictEqual` oracle called it drift. The gate was reading a serialization shape where
+ * its claim is about the dispatch. Only THIS key is normalized — a `wants_reply: true` still
+ * mismatches an expected `false`, and `target`/`intent`/`message`/`placement`/`cwd` stay exact,
+ * because for those a difference is a difference.
+ */
+function normalizeSourceArguments(args: Record<string, unknown>): Record<string, unknown> {
+	if (!("wants_reply" in args)) return { ...args, wants_reply: false };
+	return args;
+}
+
+/** Arguments agree once the schema default above is filled in. */
+export function sourceArgumentsMatch(expected: Record<string, unknown>, actual: Record<string, unknown>): boolean {
+	return isDeepStrictEqual(normalizeSourceArguments(expected), normalizeSourceArguments(actual));
+}
+
 /** Select one source call in its backend/target scope, rejecting drift, errors, and duplicates. */
 export function selectExactSourceToolReceipt(
 	receipts: readonly SourceToolReceipt[],
@@ -32,7 +59,7 @@ export function selectExactSourceToolReceipt(
 	if (matchingScope.length > 1) throw new Error(`${label}: duplicate source tool calls (${matchingScope.length})`);
 	const receipt = matchingScope[0] ?? null;
 	if (receipt === null) return null;
-	if (!isDeepStrictEqual(receipt.arguments, expectedArguments))
+	if (!sourceArgumentsMatch(expectedArguments, receipt.arguments))
 		throw new Error(
 			`${label}: source tool arguments differ\nexpected=${JSON.stringify(expectedArguments)}\nactual=${JSON.stringify(receipt.arguments)}`,
 		);
@@ -68,7 +95,7 @@ export function assertExactSourceToolCalls(
 		if (receipt.status !== "completed") throw new Error(`${label}: ${receipt.toolName} remained ${receipt.status}`);
 		const index = remaining.findIndex(
 			(candidate) =>
-				candidate.toolName === receipt.toolName && isDeepStrictEqual(candidate.arguments, receipt.arguments),
+				candidate.toolName === receipt.toolName && sourceArgumentsMatch(candidate.arguments, receipt.arguments),
 		);
 		if (index < 0)
 			throw new Error(`${label}: unexpected source call ${receipt.toolName} ${JSON.stringify(receipt.arguments)}`);

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":