@junghanacs/entwurf 0.22.0 → 0.23.1

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]",

package/scripts/mutants/codex-native.json

@@ -46,7 +46,7 @@
 		{
 			"claim": "FRESHCALL-CODEX-ARGV",
 			"title": "Codex fresh launch drops the remote app-server attachment flag and opens an unrelated local session",
-			"subject": "pi-extensions/lib/mux-fresh-call.ts",
+			"subject": "pi-extensions/lib/fresh-call-composition.ts",
 			"find": ["\t\t\t\t\"--remote\","],
 			"replace": ["\t\t\t\t\"--resume\","],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
@@ -156,7 +156,7 @@
 		},
 		{
 			"claim": "FRESHCALL-CODEX-MCP-ENV-ORDER",
-			"title": "fresh preflight accepts the managed Codex MCP env_vars in any order, as long as the set matches — a reordered vendor-visible env manifest passes as exact",
+			"title": "fresh preflight accepts the managed Codex MCP env_vars in any order, as long as the set matches \u2014 a reordered vendor-visible env manifest passes as exact",
 			"subject": "pi-extensions/lib/codex-fresh-preflight.ts",
 			"find": ["\t\tenvVars.some((name, index) => name !== CODEX_MCP_ENV_VARS[index])"],
 			"replace": [
@@ -171,8 +171,8 @@
 			"claim": "FRESHCALL-CODEX-HOOKS-SAFE",
 			"title": "fresh preflight stops checking the operator-owned hooks.json for unsafe ownership/permissions/symlinks, so a world-writable or symlinked hooks.json is treated as a safe published birth unit",
 			"subject": "pi-extensions/lib/codex-fresh-preflight.ts",
-			"find": ["\tif (!isSafeOwnedFile(paths.hooksFile, expectedUid)) return true;"],
-			"replace": ["\tif (false) return true;"],
+			"find": ["\tif (!isSafeOwnedFile(paths.hooksFile, expectedUid)) return null;"],
+			"replace": ["\tif (false) return null;"],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
 			"timeoutSeconds": 120,
 			"signature": "[QK:FRESHCALL-CODEX-HOOKS-SAFE]",
@@ -217,14 +217,14 @@
 		},
 		{
 			"claim": "FRESHCALL-CODEX-HOOK-KEYS",
-			"title": "fresh preflight stops requiring the exact birth handler key set, so an async or extra-key hook — one the installer would never publish and one that lets the turn proceed before the record exists — reads as an installed birth unit",
-			"subject": "pi-extensions/lib/codex-fresh-preflight.ts",
-			"find": ["\t\tif (Object.keys(hook).sort().join(\",\") !== \"command,timeout,type\") return true;"],
-			"replace": ["\t\tif (false) return true;"],
-			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
-			"timeoutSeconds": 120,
+			"title": "the declaration leaf stops NAMING the extra handler key, so an async or extra-key hook \u2014 still refused by the normalized digest \u2014 arrives as an anonymous mismatch instead of a diagnosis that quotes the key. This claim owns the diagnosis, never the acceptance",
+			"subject": "pi-extensions/lib/codex-declaration.js",
+			"find": ["\tif (handlerKeys.join(\",\") !== \"command,timeout,type\") {"],
+			"replace": ["\tif (false) {"],
+			"gate": ["bash", "run.sh", "check-codex-birth-hook"],
+			"timeoutSeconds": 180,
 			"signature": "[QK:FRESHCALL-CODEX-HOOK-KEYS]",
-			"signatureSource": "test/codex-fresh-preflight.test.ts"
+			"signatureSource": "scripts/check-codex-birth-hook.ts"
 		},
 		{
 			"claim": "CODEX-TOML-STATE-BEFORE-CONFIG",
@@ -311,14 +311,14 @@
 			"signatureSource": "scripts/smoke-codex-config-state.sh"
 		},
 		{
-			"claim": "CODEX-BIRTH-FOREIGN-HOOKS-REFUSED",
-			"title": "the user-layer birth unit stops refusing a hooks.json no ownership state vouches for, so a declaration somebody else wrote is treated as one of ours",
+			"claim": "CODEX-BIRTH-JOINS-FOREIGN-FILE",
+			"title": "the birth unit refuses a hooks.json it did not write instead of joining it, so a host carrying a neighbouring integration can never be installed into",
 			"subject": "scripts/codex-birth-install.sh",
-			"find": ["  if [ \"$STATE_PRESENT\" = \"0\" ]; then"],
-			"replace": ["  if false; then  # mutant: treat a foreign hooks.json as ours"],
+			"find": ["    if (sel.code !== \"declaration-absent\") throw new Error(sel.code + \": \" + sel.detail);"],
+			"replace": ["    throw new Error(\"hooks.json already exists and no ownership state vouches for it\");"],
 			"gate": ["bash", "run.sh", "smoke-codex-birth"],
 			"timeoutSeconds": 120,
-			"signature": "[QK:CODEX-BIRTH-FOREIGN-HOOKS-REFUSED]",
+			"signature": "[QK:CODEX-BIRTH-JOINS-FOREIGN-FILE]",
 			"signatureSource": "scripts/smoke-codex-birth.sh"
 		},
 		{
@@ -380,10 +380,14 @@
 		},
 		{
 			"claim": "FRESHCALL-CODEX-PREMUTATION-MCP",
-			"title": "the MCP surface stops asking the Codex TARGET capability question before placement, so a host with no birth unit, no vendor trust receipt, no MCP hand or no app-server reaches tmux first — a window opens, and the operator is told about the missing capability only after something visible already exists",
+			"title": "the MCP public surface relabels a Codex request as pi at the shared dispatcher seam, so the one central capability preflight is bypassed and placement runs first",
 			"subject": "mcp/entwurf-bridge/src/index.ts",
-			"find": ["\t\t\tconst targetMissing = backend === \"codex\" ? await codexFreshPreflight(process.env) : null;"],
-			"replace": ["\t\t\tconst targetMissing = null;"],
+			"find": [
+				"\t\t\tconst dispatched = await dispatchFreshCall({\n\t\t\t\tbackend,\n\t\t\t\tmodel,\n\t\t\t\ttask,\n\t\t\t\tcwd,\n\t\t\t\tplacement,\n\t\t\t\tcallerGardenId,\n\t\t\t\tcallerNativeSessionId,\n\t\t\t\tcallerCwd,\n\t\t\t});"
+			],
+			"replace": [
+				"\t\t\tconst dispatched = await dispatchFreshCall({\n\t\t\t\tbackend: \"pi\",\n\t\t\t\tmodel,\n\t\t\t\ttask,\n\t\t\t\tcwd,\n\t\t\t\tplacement,\n\t\t\t\tcallerGardenId,\n\t\t\t\tcallerNativeSessionId,\n\t\t\t\tcallerCwd,\n\t\t\t});"
+			],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
 			"timeoutSeconds": 180,
 			"signature": "[QK:FRESHCALL-CODEX-PREMUTATION-MCP]",
@@ -391,10 +395,10 @@
 		},
 		{
 			"claim": "FRESHCALL-CODEX-PREMUTATION-PI",
-			"title": "the native pi public surface stops running the Codex capability preflight, so the same window opens from the other public door",
+			"title": "the native pi public surface relabels a Codex request as pi at the shared dispatcher seam, bypassing the same central preflight from the other public door",
 			"subject": "pi-extensions/entwurf-control.ts",
-			"find": ["\t\t\t\t\tparams.backend === \"codex\""],
-			"replace": ["\t\t\t\t\tfalse"],
+			"find": ["\t\t\t\t\tbackend: params.backend,"],
+			"replace": ["\t\t\t\t\tbackend: \"pi\","],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
 			"timeoutSeconds": 180,
 			"signature": "[QK:FRESHCALL-CODEX-PREMUTATION-PI]",
@@ -445,9 +449,7 @@
 			"claim": "FRESHCALL-CODEX-TRUST-RECEIPT",
 			"title": "fresh preflight opens a Codex sibling whose birth hook the vendor never agreed to run",
 			"subject": "pi-extensions/lib/codex-fresh-preflight.ts",
-			"find": [
-				"\tif (config === null || trustReceiptMissing(config, paths.hooksFile)) return \"codex-birth-trust-missing\";"
-			],
+			"find": ["\tif (config === null || trustReceiptMissing(config, key)) return \"codex-birth-trust-missing\";"],
 			"replace": ["\tif (config === null) return \"codex-birth-trust-missing\";"],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
 			"timeoutSeconds": 180,
@@ -458,8 +460,10 @@
 			"claim": "FRESHCALL-CODEX-STATE-DIGEST",
 			"title": "fresh preflight accepts a birth closure whose bytes no longer match the digests its own ownership state recorded",
 			"subject": "pi-extensions/lib/codex-fresh-preflight.ts",
-			"find": ["\treturn closureDriftedFromState(paths, expectedUid);"],
-			"replace": ["\treturn false;  // mutant: existence is enough"],
+			"find": [
+				"\t\tif (typeof member.sha256 !== \"string\" || digest(path.join(paths.helperDir, rel)) !== member.sha256) return null;"
+			],
+			"replace": ["\t\tif (typeof member.sha256 !== \"string\") return null;  // mutant: existence is enough"],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
 			"timeoutSeconds": 180,
 			"signature": "[QK:FRESHCALL-CODEX-STATE-DIGEST]",
@@ -518,7 +522,7 @@
 			"title": "fresh preflight compares only the digests a state happens to name, so a short inventory hides an unchecked closure member",
 			"subject": "pi-extensions/lib/codex-fresh-preflight.ts",
 			"find": [
-				"\tif (named.length !== expected.length) return true;\n\tif (expected.some((name) => !named.includes(name))) return true;\n\tif (named.some((name, index) => named.indexOf(name) !== index)) return true;"
+				"\tif (named.length !== expected.length) return null;\n\tif (expected.some((name) => !named.includes(name))) return null;\n\tif (named.some((name, index) => named.indexOf(name) !== index)) return null;"
 			],
 			"replace": ["\t// mutant: judge only the members a state happens to name"],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
@@ -554,7 +558,7 @@
 			"claim": "FRESHCALL-CODEX-STATE-PARENT-AUTHORITY",
 			"title": "fresh preflight trusts a digest inventory sitting in a directory anyone on the host can rewrite",
 			"subject": "pi-extensions/lib/codex-fresh-preflight.ts",
-			"find": ["\tif (!isSafeOwnedDir(path.dirname(paths.stateFile), expectedUid)) return true;"],
+			"find": ["\tif (!isSafeOwnedDir(path.dirname(paths.stateFile), expectedUid)) return null;"],
 			"replace": ["\t// mutant: the directory holding the receipt is nobody's business"],
 			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
 			"timeoutSeconds": 180,
@@ -833,6 +837,168 @@
 			"timeoutSeconds": 180,
 			"signature": "[QK:CODEX-LIVE-RECOVERY-SOURCE-ONLY]",
 			"signatureSource": "test/codex-fresh-live-protocol.test.ts"
+		},
+		{
+			"claim": "CODEX-DECL-CANONICAL-KEY-ORDER",
+			"title": "the declaration digest is taken over unsorted keys, so a neighbour re-serializing the document reads as an edited entwurf declaration",
+			"subject": "pi-extensions/lib/codex-declaration.js",
+			"find": ["\tconst keys = Object.keys(value).sort();"],
+			"replace": ["\tconst keys = Object.keys(value);"],
+			"gate": ["bash", "run.sh", "check-codex-birth-hook"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:CODEX-DECL-CANONICAL-KEY-ORDER]",
+			"signatureSource": "scripts/check-codex-birth-hook.ts"
+		},
+		{
+			"claim": "CODEX-DECL-SELECT-BY-COMMAND",
+			"title": "entwurf's declaration is selected by POSITION instead of by its launcher command, so a neighbour at index 0 is certified as ours",
+			"subject": "pi-extensions/lib/codex-declaration.js",
+			"find": [
+				"\t\t\tif (handler !== null && typeof handler === \"object\" && !Array.isArray(handler) && handler.command === want) {"
+			],
+			"replace": [
+				"\t\t\tif (handler !== null && typeof handler === \"object\" && !Array.isArray(handler) && h === 0) {"
+			],
+			"gate": ["bash", "run.sh", "check-codex-birth-hook"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:CODEX-DECL-SELECT-BY-COMMAND]",
+			"signatureSource": "scripts/check-codex-birth-hook.ts"
+		},
+		{
+			"claim": "CODEX-DECL-SPLICE-KEEPS-FOREIGN-BYTES",
+			"title": "a certified splice returns a RE-SERIALIZED document instead of the spliced text, rewriting every byte a neighbouring integration owns",
+			"subject": "pi-extensions/lib/codex-declaration.js",
+			"find": ["\treturn spliced;"],
+			"replace": ["\treturn JSON.stringify(reparsed, null, 2);"],
+			"gate": ["bash", "run.sh", "check-codex-birth-hook"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:CODEX-DECL-SPLICE-KEEPS-FOREIGN-BYTES]",
+			"signatureSource": "scripts/check-codex-birth-hook.ts"
+		},
+		{
+			"claim": "CODEX-DECL-SPLICE-CERTIFIED",
+			"title": "the span splice is written out on the span reader's word alone, with no re-parse proving it landed where the caller intended",
+			"subject": "pi-extensions/lib/codex-declaration.js",
+			"find": ["\tif (canonicalJson(reparsed) !== canonicalJson(expected)) {"],
+			"replace": ["\tif (false) {"],
+			"gate": ["bash", "run.sh", "check-codex-birth-hook"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:CODEX-DECL-SPLICE-CERTIFIED]",
+			"signatureSource": "scripts/check-codex-birth-hook.ts"
+		},
+		{
+			"claim": "CODEX-DECLARATION-DUPLICATED",
+			"title": "a duplicated entwurf declaration is first-match accepted, so the vendor runs the birth hook twice and only one position carries the receipt",
+			"subject": "pi-extensions/lib/codex-declaration.js",
+			"find": ["\tif (mine.length > 1) {"],
+			"replace": ["\tif (mine.length > 2) {"],
+			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:CODEX-DECLARATION-DUPLICATED]",
+			"signatureSource": "test/codex-fresh-preflight.test.ts"
+		},
+		{
+			"claim": "CODEX-DECLARATION-TRUST-INDEX",
+			"title": "fresh preflight reads the vendor trust receipt at the constant :0:0, so a neighbour's approval at index 0 admits a birth hook the vendor never agreed to run",
+			"subject": "pi-extensions/lib/codex-fresh-preflight.ts",
+			"find": ["\tconst key = trustReceiptKey(paths.hooksFile, declaration.groupIndex, declaration.handlerIndex);"],
+			"replace": ["\tconst key = trustReceiptKey(paths.hooksFile, 0, 0);"],
+			"gate": ["bash", "run.sh", "check-mux-fresh-call"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:CODEX-DECLARATION-TRUST-INDEX]",
+			"signatureSource": "test/codex-fresh-preflight.test.ts"
+		},
+		{
+			"claim": "CODEX-BIRTH-TRUST-INDEX-MEASURED",
+			"title": "the doctor reads the vendor trust receipt at the constant :0:0, reporting a neighbour's approval as entwurf's own",
+			"subject": "scripts/codex-birth-doctor.sh",
+			"find": ["  TRUST_KEY=\"$HOOKS_FILE:session_start:$DECL_GROUP_INDEX:$DECL_HANDLER_INDEX\""],
+			"replace": ["  TRUST_KEY=\"$HOOKS_FILE:session_start:0:0\""],
+			"gate": ["bash", "run.sh", "smoke-codex-birth"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:CODEX-BIRTH-TRUST-INDEX-MEASURED]",
+			"signatureSource": "scripts/smoke-codex-birth.sh"
+		},
+		{
+			"claim": "CODEX-BIRTH-SHARED-FILE-OWNERSHIP",
+			"title": "the shared ownership predicate stops seeing a group/world-writable file, so all four surfaces write into and certify bytes somebody else can rewrite",
+			"subject": "pi-extensions/lib/codex-declaration.js",
+			"find": ["\tif ((stat.mode & 0o022) !== 0) return \"writable-by-others\";"],
+			"replace": [""],
+			"gate": ["bash", "run.sh", "smoke-codex-birth"],
+			"timeoutSeconds": 300,
+			"signature": "[QK:CODEX-BIRTH-SHARED-FILE-OWNERSHIP]",
+			"signatureSource": "scripts/smoke-codex-birth.sh"
+		},
+		{
+			"claim": "CODEX-BIRTH-DOCTOR-SHARED-OWNERSHIP",
+			"title": "the doctor stops asking who owns the shared file and goes straight to the digest, so it reports green on a host every launch refuses",
+			"subject": "scripts/codex-birth-doctor.sh",
+			"find": ["    if (owned !== \"ok\") {"],
+			"replace": ["    if (false) {"],
+			"gate": ["bash", "run.sh", "smoke-codex-birth"],
+			"timeoutSeconds": 300,
+			"signature": "[QK:CODEX-BIRTH-DOCTOR-SHARED-OWNERSHIP]",
+			"signatureSource": "scripts/smoke-codex-birth.sh"
+		},
+		{
+			"claim": "CODEX-BIRTH-INVERSE-SHARED-OWNERSHIP",
+			"title": "the inverse stops asking and rewrites a shared file it cannot bind, instead of leaving it as found and counting the drift",
+			"subject": "scripts/codex-birth-uninstall.sh",
+			"find": ["  if [ \"$owned\" != \"ok\" ]; then"],
+			"replace": ["  if false; then"],
+			"gate": ["bash", "run.sh", "smoke-codex-birth"],
+			"timeoutSeconds": 300,
+			"signature": "[QK:CODEX-BIRTH-INVERSE-SHARED-OWNERSHIP]",
+			"signatureSource": "scripts/smoke-codex-birth.sh"
+		},
+		{
+			"claim": "CODEX-BIRTH-INVERSE-KEEPS-PRE-EXISTING-FILE",
+			"title": "the FILE verdict goes back to asking only whether our group was the last declaration, so a hooks.json that existed before this unit is deleted with its owners top-level bytes",
+			"subject": "scripts/codex-birth-uninstall.sh",
+			"find": [
+				"      if (createdByUs === \"yes\" && soleDeclaration && topLevel === \"description,hooks\" && ourDescription) {"
+			],
+			"replace": ["      if (soleDeclaration) {"],
+			"gate": ["bash", "run.sh", "smoke-codex-birth"],
+			"timeoutSeconds": 300,
+			"signature": "[QK:CODEX-BIRTH-INVERSE-KEEPS-PRE-EXISTING-FILE]",
+			"signatureSource": "scripts/smoke-codex-birth.sh"
+		},
+		{
+			"claim": "CODEX-BIRTH-DOCTOR-ORPHAN-RED",
+			"title": "the doctor stops looking for our own bytes when the receipt is gone, so a half-removed unit reads as a clean host and invites a reinstall over bytes the inverse will refuse",
+			"subject": "scripts/codex-birth-doctor.sh",
+			"find": ["  if [ \"$ORPHAN_DECLARATION\" = \"1\" ] || [ -e \"$HELPER_DIR\" ]; then"],
+			"replace": ["  if false; then"],
+			"gate": ["bash", "run.sh", "smoke-codex-birth"],
+			"timeoutSeconds": 300,
+			"signature": "[QK:CODEX-BIRTH-DOCTOR-ORPHAN-RED]",
+			"signatureSource": "scripts/smoke-codex-birth.sh"
+		},
+		{
+			"claim": "CODEX-BIRTH-INVERSE-KEEPS-FOREIGN",
+			"title": "the text splice takes a fixed group index instead of the one the selector measured, so the inverse reaches for a neighbours declaration and the post-condition is the only thing standing between that and a written file",
+			"subject": "scripts/codex-birth-uninstall.sh",
+			"find": ["      let spliced = m.certifySplice(m.removeSessionStartGroup(text, sel.groupIndex), want);"],
+			"replace": ["      let spliced = m.certifySplice(m.removeSessionStartGroup(text, 0), want);"],
+			"gate": ["bash", "run.sh", "smoke-codex-birth"],
+			"timeoutSeconds": 300,
+			"signature": "[QK:CODEX-BIRTH-INVERSE-KEEPS-FOREIGN]",
+			"signatureSource": "scripts/smoke-codex-birth.sh"
+		},
+		{
+			"claim": "CODEX-BIRTH-INVERSE-SOLE-OWNER",
+			"title": "the FILE arm drops the target from its own removal, so a hooks.json this unit created and was the sole declaration in survives an uninstall that reports it gone",
+			"subject": "scripts/codex-birth-uninstall.sh",
+			"find": [
+				"    FILE) rm -f -- \"$tmp\" \"$target\"; note \"removed $target (entwurf was its only declaration)\" ;;"
+			],
+			"replace": ["    FILE) rm -f -- \"$tmp\"; note \"removed $target (entwurf was its only declaration)\" ;;"],
+			"gate": ["bash", "run.sh", "smoke-codex-birth"],
+			"timeoutSeconds": 300,
+			"signature": "[QK:CODEX-BIRTH-INVERSE-SOLE-OWNER]",
+			"signatureSource": "scripts/smoke-codex-birth.sh"
 		}
 	]
 }