@junghanacs/entwurf 0.22.0 → 0.23.0

package/scripts/register-pi-provider.py

@@ -76,6 +76,14 @@ import sys
 # `install` — semantically a no-op, byte-wise a RED `pnpm check`. sys.path[0] already
 # holds this directory when the script is run by path (how run.sh and the gates invoke
 # it); the explicit insert keeps the import true under any other invocation form.
+# The sibling import below would otherwise leave `scripts/__pycache__/pi_settings_io.*.pyc`
+# behind — a write into the checkout this script was merely READ from. It is git-ignored, so
+# `git status --porcelain` never shows it, and on a host where the cache already exists nothing
+# changes; but in the gate-qualification snapshot the file is NEW, and the tree manifest that
+# certifies "the runner never wrote the tree" reads bytes, not porcelain. Measured on the #116
+# M3-b3 candidate: that one path was the whole of `IMPURE: treeClean=false porcelainClean=true`.
+# Same guard, same reason as codex-mcp-config.py / codex-statusline-config.py.
+sys.dont_write_bytecode = True
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from pi_settings_io import classify_installer_root, detect_indent, dumps, unchanged  # noqa: E402
 
@@ -170,11 +178,49 @@ def _now() -> str:
     return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
-def _classify(existing_cmd, repo_dir: str) -> str:
+# #116 M3-b2 — the ONE alternative managed command, and it is DERIVED, never supplied.
+# A Herdr plugin activates on a host where nothing entwurf is on PATH, so the bare bin cannot
+# resolve. The plugin mode therefore names the bridge by its absolute path under the certified
+# stable active runtime — and that is the whole freedom it gets: the caller passes the runtime ROOT,
+# this function appends the fixed suffix, and any other string is refused. There is deliberately no
+# flag or environment variable that accepts an arbitrary command or path: that would be a generic
+# "write whatever you like into the operator's pi settings" authority wearing a plugin's clothes.
+PLUGIN_BIN_SUFFIX = os.path.join("node_modules", ".bin", SERVER_KEY)
+
+
+def stable_active_root() -> str:
+    """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
+    implementations equal; nothing here reads a caller-supplied root as authority."""
+    data_home = os.environ.get("XDG_DATA_HOME") or os.path.join(os.path.expanduser("~"), ".local", "share")
+    return os.path.join(data_home, "entwurf", "herdr-plugin", "runtime", "active")
+
+
+def plugin_command_for(runtime_root: str) -> str:
+    # The caller may NAME the root, but it is only accepted when it IS this host's stable root. An
+    # absolute path was never the contract — "the stable runtime" was — and a mode that takes any
+    # absolute directory is a way to point every pi session at an executable of the caller's choice.
+    if not isinstance(runtime_root, str) or not os.path.isabs(runtime_root):
+        _die(2, f"register-pi-provider: --plugin-runtime must be an ABSOLUTE stable runtime root, got {runtime_root!r}")
+    if runtime_root != os.path.normpath(runtime_root) or runtime_root.endswith(os.sep):
+        _die(2, f"register-pi-provider: --plugin-runtime must be a normalised path, got {runtime_root!r}")
+    expected = stable_active_root()
+    if runtime_root != expected:
+        _die(2, f"register-pi-provider: --plugin-runtime must be this host's stable runtime root {expected!r}, "
+                f"got {runtime_root!r} — an arbitrary absolute directory is not a plugin runtime.")
+    return os.path.join(runtime_root, PLUGIN_BIN_SUFFIX)
+
+
+def _classify(existing_cmd, repo_dir: str, managed_command: str = BARE_COMMAND) -> str:
     if existing_cmd is None:
         return "absent"
-    if existing_cmd == BARE_COMMAND:
+    if existing_cmd == managed_command:
         return "managed-current"
+    # The OTHER shape we own is adoptable, so bare↔plugin is a normalisation rather than a
+    # takeover. In DEFAULT mode this is exactly the historical set (the bare bin is
+    # managed-current above and never reaches here), so default bytes and verdicts are unchanged.
+    if managed_command != BARE_COMMAND and existing_cmd == BARE_COMMAND:
+        return "managed-legacy"
     if isinstance(existing_cmd, str) and (
         existing_cmd == f"{repo_dir}/mcp/{SERVER_KEY}/start.sh"
         or existing_cmd.endswith(f"/entwurf/mcp/{SERVER_KEY}/start.sh")
@@ -210,7 +256,8 @@ def _load_state_file(state_path: str) -> dict | None:
 
 
 def cmd_install(settings_path: str, repo_dir: str, scope: str, state_path: str, takeover: bool = False,
-                preflight: bool = False) -> None:
+                preflight: bool = False, plugin_runtime: str | None = None) -> None:
+    managed_command = plugin_command_for(plugin_runtime) if plugin_runtime else BARE_COMMAND
     if os.path.islink(settings_path):
         target = os.readlink(settings_path)
         _die(3, f"register-pi-provider: refusing to adopt {settings_path} — it is a symlink to {target} "
@@ -254,7 +301,7 @@ def cmd_install(settings_path: str, repo_dir: str, scope: str, state_path: str,
     _prune_legacy(servers, repo_dir)   # independent of entwurf-bridge ownership
     existing = servers.get(SERVER_KEY)
     existing_cmd = existing.get("command") if isinstance(existing, dict) else existing
-    ownership = _classify(existing_cmd, repo_dir)
+    ownership = _classify(existing_cmd, repo_dir, managed_command)
 
     if preflight:
         # Read-only half of the atomic user-scope operation: the ownership decision
@@ -282,8 +329,8 @@ def cmd_install(settings_path: str, repo_dir: str, scope: str, state_path: str,
             sys.stdout.write(f"install: no change — {settings_path} left untouched (bytes and mtime stable)\n")
         return
 
-    # absent / managed-current / managed-legacy → normalize to the bare stable bin.
-    newval = {"command": BARE_COMMAND}
+    # absent / managed-current / managed-legacy → normalize to the managed command for this mode.
+    newval = {"command": managed_command}
     # preserve non-empty custom args if the operator set them; else default [].
     if isinstance(existing, dict) and existing.get("args") not in (None, []):
         newval["args"] = existing["args"]
@@ -292,7 +339,8 @@ def cmd_install(settings_path: str, repo_dir: str, scope: str, state_path: str,
     servers[SERVER_KEY] = newval
     wrote = _persist(settings_path, before, data, raw)
     sys.stdout.write(
-        f"install: {ownership} → entwurfProvider.mcpServers.{SERVER_KEY} = {BARE_COMMAND} (bare stable bin)\n"
+        f"install: {ownership} → entwurfProvider.mcpServers.{SERVER_KEY} = {managed_command} "
+        f"({'stable plugin runtime' if plugin_runtime else 'bare stable bin'})\n"
     )
     # The desired value AND the legacy prune both already held: nothing to say to the
     # file. Reported so an operator (and the gate) can tell "already correct" from
@@ -317,7 +365,7 @@ def cmd_install(settings_path: str, repo_dir: str, scope: str, state_path: str,
                 "managedSettingsPath": os.path.abspath(settings_path),
                 "scope": "user",
                 "key": f"entwurfProvider.mcpServers.{SERVER_KEY}",
-                "command": BARE_COMMAND,
+                "command": managed_command,
                 "ownership": ownership,       # absent | managed-current | managed-legacy
                 "installerRoot": repo_dir,     # #86 C2: the root whose inverse may remove this key
                 "preimage": existing,          # raw prior value (audit only; NOT restored)
@@ -387,8 +435,23 @@ def cmd_remove(settings_path: str, repo_dir: str, scope: str, state_path: str, o
             before = _parse_settings(managed, raw)     # dies 4 on corrupt — preflight and writer alike
             data = _parse_settings(managed, raw)
             provider, servers = _provider_servers(data, create=False)
+        # #116 M3-b2 — DRIFT IS NOT OURS TO DELETE. The user-scope inverse is admitted by the
+        # ownership record, not by the command string, so without this it would remove whatever now
+        # sits at our key. The state records the exact command we wrote (bare bin, or the absolute
+        # bridge under a stable plugin runtime); if the live value is PRESENT and different, someone
+        # replaced our key after we installed it and the honest move is to refuse by name rather
+        # than delete their override. An ABSENT key stays an idempotent no-op.
+        recorded_cmd = state.get("command")
+        live = servers.get(SERVER_KEY) if isinstance(servers, dict) else None
+        live_cmd = live.get("command") if isinstance(live, dict) else live
+        if isinstance(recorded_cmd, str) and live_cmd is not None and live_cmd != recorded_cmd:
+            _die(6, f"register-pi-provider: the user-scope {SERVER_KEY} command drifted since install — "
+                    f"we wrote {recorded_cmd!r}, {managed} now holds {live_cmd!r}. That is somebody's override, "
+                    "not our key; zero settings bytes written and the ownership state is left intact.")
         if preflight:
-            sys.stdout.write("preflight: remove ok (owner verified; managed target bound and parseable)\n")
+            sys.stdout.write(
+                f"preflight: remove ok (owner verified; managed target bound and parseable; command={recorded_cmd!r})\n"
+            )
             return
         if os.path.exists(managed):
             # honest inverse: absent/managed-* → remove OUR key (a legacy repo path is NOT
@@ -442,6 +505,7 @@ def cmd_remove(settings_path: str, repo_dir: str, scope: str, state_path: str, o
 
 
 def _parse(argv: list):
+    plugin_runtime = None
     # positional: settings_path repo_dir ; flags: --scope <s> [--state <p>] [--takeover] [--orphan-cleanup] [--preflight]
     pos, scope, state_path = [], None, ""
     takeover, orphan, preflight = False, False, False
@@ -460,17 +524,24 @@ def _parse(argv: list):
             orphan = True
         elif a == "--preflight":
             preflight = True
+        elif a == "--plugin-runtime":
+            i += 1
+            # A flag with no value must NOT fall through to bare mode: the caller asked for the
+            # plugin runtime and would otherwise be told, silently, that it got it.
+            if i >= len(argv) or not argv[i]:
+                _die(5, "register-pi-provider.py: --plugin-runtime requires a value")
+            plugin_runtime = argv[i]
         else:
             pos.append(a)
         i += 1
-    return pos, scope, state_path, takeover, orphan, preflight
+    return pos, scope, state_path, takeover, orphan, preflight, plugin_runtime
 
 
 def main(argv: list) -> None:
     if len(argv) < 2:
         _die(5, "usage: register-pi-provider.py <install|remove> <settings_path> <repo_dir> --scope <user|project> [--state <path>]")
     sub = argv[1]
-    pos, scope, state_path, takeover, orphan, preflight = _parse(argv[2:])
+    pos, scope, state_path, takeover, orphan, preflight, plugin_runtime = _parse(argv[2:])
     if sub not in ("install", "remove"):
         _die(5, f"register-pi-provider.py: unknown subcommand {sub!r}")
     if len(pos) != 2:
@@ -486,8 +557,13 @@ def main(argv: list) -> None:
         _die(5, "register-pi-provider.py: --takeover is an install action")
     if orphan and sub != "remove":
         _die(5, "register-pi-provider.py: --orphan-cleanup is a remove action")
+    # The plugin mode is an INSTALL-side USER-scope decision only. `remove` needs no mode: it
+    # recognises every shape we own through the same classifier, so an inverse never has to be told
+    # which one it is undoing — and a mode flag on remove would be a way to aim a deletion.
+    if plugin_runtime is not None and (sub != "install" or scope != "user"):
+        _die(5, "register-pi-provider.py: --plugin-runtime is a user-scope install action")
     if sub == "install":
-        cmd_install(settings_path, repo_dir, scope, state_path, takeover, preflight)
+        cmd_install(settings_path, repo_dir, scope, state_path, takeover, preflight, plugin_runtime)
     else:
         cmd_remove(settings_path, repo_dir, scope, state_path, orphan, preflight)
 

package/scripts/smoke-codex-birth.sh

@@ -7,6 +7,10 @@
 #   1. the published declaration is the EXACT trust identity (matcher-less, type/command/
 #      timeout, quoted fixed launcher path) — because that identity is what an operator
 #      approves once, and any drift in it costs a second approval;
+#   1b. entwurf owns ONLY that declaration inside a file it SHARES (#117): a neighbouring
+#      integration's `SessionStart` group in either ordering leaves install/doctor green, is
+#      reported as foreign, is never certified, survives install and inverse byte-for-byte, and
+#      moves no verdict of ours when it is edited;
 #   2. config.toml is neither read nor written, so the vendor's [hooks.state] and entwurf's
 #      own two user atoms survive install AND inverse byte-for-byte;
 #   3. a foreign or edited hooks.json is a ZERO-WRITE refusal, never an adoption — this unit
@@ -76,9 +80,13 @@ want "the launcher is published and executable" "[ -f '$LAUNCHER' ] && [ -x '$LA
 want "the closure is published whole" "[ -f '$HELPER/meta-bridge-hook-codex.ts' ] && [ -f '$HELPER/lib/meta-session.ts' ] && [ -f '$HELPER/lib/native-push/codex-ws-client.ts' ] && [ -f '$HELPER/lib/session-id.js' ] && [ -f '$HELPER/entwurf-capabilities.json' ]"
 want "the state is a regular non-symlink file" "[ -f '$STATE' ] && [ ! -L '$STATE' ]"
 want "the state is bound to the fixed paths and finished publishing" \
-  "node -e 'const s=require(process.argv[1]); if(s.schema!==\"codex-birth-install-state/v1\")throw 0; if(s.status!==\"installed\")throw 0; if(s.hooksFile!==process.argv[2])throw 0; if(s.helperDir!==process.argv[3])throw 0;' '$STATE' '$HOOKS' '$HELPER'"
+  "node -e 'const s=require(process.argv[1]); if(s.schema!==\"codex-birth-install-state/v2\")throw 0; if(s.status!==\"installed\")throw 0; if(s.hooksFile!==process.argv[2])throw 0; if(s.helperDir!==process.argv[3])throw 0;' '$STATE' '$HOOKS' '$HELPER'"
+# The receipt is a DECLARATION digest, not a file digest. A state carrying a whole-file
+# `hooksSha256` would be claiming authority over bytes a neighbour owns — the #117 defect itself.
+want "[QK:CODEX-BIRTH-STATE-CERTIFIES-DECLARATION] the state records a declaration receipt and NO whole-file digest" \
+  "node -e 'const s=require(process.argv[1]); const hex=v=>/^[0-9a-f]{64}\$/.test(v); if(\"hooksSha256\" in s)throw new Error(\"the state still claims the whole file\"); if(s.declaration.event!==\"SessionStart\")throw 0; if(typeof s.declaration.command!==\"string\")throw 0; if(!hex(s.declaration.sha256))throw 0;' '$STATE'"
 want "the state records a digest for every published byte" \
-  "node -e 'const s=require(process.argv[1]); const hex=v=>/^[0-9a-f]{64}\$/.test(v); if(!hex(s.hooksSha256))throw 0; if(s.helperFiles.length!==6)throw 0; for(const f of s.helperFiles){if(!hex(f.sha256))throw 0;}' '$STATE'"
+  "node -e 'const s=require(process.argv[1]); const hex=v=>/^[0-9a-f]{64}\$/.test(v); if(s.helperFiles.length!==6)throw 0; for(const f of s.helperFiles){if(!hex(f.sha256))throw 0;}' '$STATE'"
 
 # The trust identity, asserted field by field. This is the cell that costs a second operator
 # approval if it ever drifts, so it is checked literally rather than by shape.
@@ -153,7 +161,7 @@ MT1="$(stat -c %Y "$HOOKS")"; sleep 1.1
 "$INSTALL" >"$SB/out" 2>&1 || die "reinstall failed: $(cat "$SB/out")"
 MT2="$(stat -c %Y "$HOOKS")"
 want "reinstall does not rewrite the declaration" "[ '$MT1' = '$MT2' ]"
-want "reinstall adopts its own published declaration by digest" "grep -q 'adopting the hooks.json this unit published' '$SB/out'"
+want "reinstall recognises its own declaration by normalized digest and rewrites nothing" "grep -q 'NOT REWRITTEN, not one byte' '$SB/out'"
 cmp -s "$SB/config.before.toml" "$CFG" && ok "reinstall still left config.toml byte-identical" || die "reinstall modified config.toml"
 
 ###############################################################################
@@ -198,31 +206,180 @@ ok "the unit axis is green again after the absent member was republished"
 # refusals — a foreign file, an edited file, a symlink; each ZERO-WRITE
 ###############################################################################
 "$UNINSTALL" >/dev/null 2>&1 || die "clean uninstall before the refusal cells failed"
-printf '{"hooks":{"SessionStart":[{"hooks":[{"type":"command","command":"/opt/operator/own-hook.sh","timeout":10}]}]}}\n' > "$HOOKS"
-cp "$HOOKS" "$SB/foreign-hooks.json"
-refuses "[QK:CODEX-BIRTH-FOREIGN-HOOKS-REFUSED] a foreign hooks.json is refused, not adopted" "already exists and this host has NO entwurf ownership state" "$INSTALL"
-cmp -s "$SB/foreign-hooks.json" "$HOOKS" && ok "the foreign declaration survives the refusal byte-for-byte" || die "the foreign hooks.json was overwritten"
-want "the foreign refusal wrote no state and no helper" "[ ! -e '$STATE' ] && [ ! -e '$HELPER' ]"
+
+###############################################################################
+# COEXISTENCE (#117) — the neighbour is joined, never adopted and never refused
+#
+# Until 0.22.0 this unit owned hooks.json WHOLE: a file it had not written was a zero-write
+# refusal, and its whole-file digest went red the moment anyone else appended. That is exactly
+# what Herdr's official Codex integration does, and the vendor keeps running both declarations
+# because `[source]` discovery.rs:664-665 keys trust per `<path>:<event>:<group>:<handler>`.
+# These cells are the new contract: one group is ours, everything else is foreign bytes we read
+# and never write.
+###############################################################################
+FOREIGN_GROUP='      {
+        "hooks": [
+          {
+            "command": "bash '"'"'/sandbox/.codex/herdr-agent-state.sh'"'"' session",
+            "timeout": 10,
+            "type": "command"
+          }
+        ]
+      }'
+neighbour_survives() { # <label>
+  printf '%s' "$FOREIGN_GROUP" > "$SB/foreign-block.txt"
+  grep -qF -f "$SB/foreign-block.txt" "$HOOKS" && ok "$1" || die "$1 (the foreign group's bytes changed)"
+}
+foreign_file() { # writes a hooks.json declaring ONLY the neighbour, in its own formatting AND
+  # its own mode — both are things this unit must carry over rather than normalise.
+  printf '{\n  "hooks": {\n    "SessionStart": [\n%s\n    ]\n  }\n}\n' "$FOREIGN_GROUP" > "$HOOKS"
+  chmod 0600 "$HOOKS"
+}
+
+# ORDER A — the neighbour is there first and entwurf joins it.
+foreign_file
+cp "$HOOKS" "$SB/foreign-only.json"
+want "[QK:CODEX-BIRTH-JOINS-FOREIGN-FILE] a foreign hooks.json is JOINED by text splice, never adopted and never refused" \
+  "'$INSTALL' >'$SB/out' 2>&1 && grep -q 'appended entwurf' '$SB/out' && grep -q 'byte-for-byte' '$SB/out'"
+neighbour_survives "the neighbour's declaration survives the install byte-for-byte"
+want "[QK:CODEX-BIRTH-SHARED-FILE-MODE-KEPT] the shared file keeps the mode it was found with — a file we only add a group to is not one whose permissions are ours to reset" \
+  "[ \"\$(stat -c %a '$HOOKS')\" = '0600' ] || [ \"\$(stat -c %a '$HOOKS')\" = '600' ]"
+want "entwurf's declaration was APPENDED, so the neighbour keeps index 0 and the trust receipt it already has" \
+  "node -e 'const s=JSON.parse(require(\"node:fs\").readFileSync(process.argv[1],\"utf8\")); const g=s.hooks.SessionStart; if(g.length!==2)throw new Error(\"groups \"+g.length); if(g[0].hooks[0].command.includes(\"entwurf\"))throw new Error(\"entwurf took index 0\"); if(g[1].hooks[0].command!==\"'\''\"+process.argv[2]+\"'\''\")throw new Error(\"ours is not at index 1\");' '$HOOKS' '$LAUNCHER'"
+want "[QK:CODEX-BIRTH-DOCTOR-COEXISTS] the doctor certifies entwurf's own declaration at its MEASURED index and stays green beside a neighbour" \
+  "'$DOCTOR' --unit-only >'$SB/out' 2>&1 && grep -q \"entwurf's declaration is certified at .* group 1 handler 0\" '$SB/out'"
+want "[QK:CODEX-BIRTH-DOCTOR-REPORTS-FOREIGN] the neighbour is reported as present-but-foreign, in its own section, and certified by nothing" \
+  "grep -q 'FOREIGN (what else declares' '$SB/out' && grep -q 'SessionStart group 0: bash' '$SB/out' && grep -q 'present-but-foreign' '$SB/out' && grep -q 'never overwritten, never absorbed' '$SB/out'"
+
+# THE VENDOR RECEIPT IS READ AT OUR MEASURED INDEX, and this is the cell that would have caught
+# the #117 false green: with the neighbour at index 0, a constant `:0:0` reads THEIR approval and
+# reports a birth hook the vendor was never asked to run.
+trust_receipt "$HOOKS:session_start:1:0"
+want "[QK:CODEX-BIRTH-TRUST-INDEX-MEASURED] the full doctor reads the vendor receipt at entwurf's MEASURED index (1:0 here), never at the constant :0:0" \
+  "'$DOCTOR' >'$SB/out' 2>&1"
+trust_receipt "$HOOKS:session_start:0:0"
+"$DOCTOR" >"$SB/out" 2>&1 && die "the doctor read the NEIGHBOUR's receipt at :0:0 as entwurf's own approval"
+want "a receipt at the neighbour's index is named as somebody else's approval, and the key looked for is ours" \
+  "grep -q \"NONE at this unit's key $HOOKS:session_start:1:0\" '$SB/out'"
+cp "$SB/config.before.toml" "$CFG"
+
+# A neighbour EDITED after our install moves nothing of ours — it is not ours to certify.
+python3 -c 'import json,sys
+p=sys.argv[1]; d=json.load(open(p))
+d["hooks"]["SessionStart"][0]["hooks"][0]["timeout"]=99
+open(p,"w").write(json.dumps(d,indent=2))' "$HOOKS"
+want "[QK:CODEX-BIRTH-FOREIGN-EDIT-NEUTRAL] a neighbour's declaration edited after our install is still reported and still certified by nothing — our verdict is unmoved" \
+  "'$DOCTOR' --unit-only >'$SB/out' 2>&1 && grep -q \"entwurf's declaration is certified\" '$SB/out' && grep -q 'SessionStart group 0: bash' '$SB/out'"
+"$INSTALL" >"$SB/out" 2>&1 || die "reinstall beside an edited neighbour failed: $(cat "$SB/out")"
+want "a reinstall beside an edited neighbour does not rewrite hooks.json at all" "grep -q 'NOT REWRITTEN, not one byte' '$SB/out'"
+
+# The inverse takes our group out and leaves the neighbour's bytes exactly where they were.
+cp "$HOOKS" "$SB/before-inverse.json"
+# The exit status rides INSIDE the claim: a splice aimed at the wrong group is caught by the
+# post-condition and comes back as DRIFT, which is a nonzero exit — and a separate `|| die` above
+# would swallow that with a line that cannot carry this claim's token.
+INVERSE_RC=0
+"$UNINSTALL" >"$SB/out" 2>&1 || INVERSE_RC=$?
+want "[QK:CODEX-BIRTH-INVERSE-KEEPS-FOREIGN] the inverse removes ONLY entwurf's group, by splice, and keeps the shared file — a splice that landed anywhere else would be refused by its own post-condition and reported as drift instead" \
+  "[ \"$INVERSE_RC\" -eq 0 ] && [ -f '$HOOKS' ] && grep -q 'by text splice' '$SB/out' && ! grep -q 'codex-birth-launch.sh' '$HOOKS'"
+want "the inverse left the neighbour as the file's only declaration" \
+  "node -e 'const s=JSON.parse(require(\"node:fs\").readFileSync(process.argv[1],\"utf8\")); if(s.hooks.SessionStart.length!==1)throw 0; if(!s.hooks.SessionStart[0].hooks[0].command.includes(\"herdr\"))throw 0;' '$HOOKS'"
+want "the inverse removed entwurf's own description and left no entwurf prose behind" "! grep -q 'entwurf codex-birth' '$HOOKS'"
+# The neighbour was re-indented by its own editor above; what must survive the SPLICE is every
+# byte of the group as it stood immediately before the inverse ran.
+node -e '
+  const fs = require("node:fs");
+  const before = JSON.parse(fs.readFileSync(process.argv[1], "utf8")).hooks.SessionStart.filter((g) => !JSON.stringify(g).includes("codex-birth-launch"));
+  const after = JSON.parse(fs.readFileSync(process.argv[2], "utf8")).hooks.SessionStart;
+  if (JSON.stringify(before) !== JSON.stringify(after)) throw new Error("foreign groups changed across the inverse");
+' "$SB/before-inverse.json" "$HOOKS" && ok "[QK:CODEX-BIRTH-INVERSE-FOREIGN-EXACT] every foreign group is value-identical across the inverse" || die "the inverse changed a foreign group"
 rm -f "$HOOKS"
 
+# ORDER B — entwurf is there first and the neighbour appends afterwards, re-serializing the
+# WHOLE document on its way past (measured: Herdr does exactly this, oracle 2026-09-17).
+"$INSTALL" >/dev/null 2>&1 || die "install before the order-B cell failed"
+python3 -c 'import json,sys
+p=sys.argv[1]; d=json.load(open(p))
+g=d["hooks"]["SessionStart"][0]["hooks"][0]
+d["hooks"]["SessionStart"][0]["hooks"][0]={"command":g["command"],"timeout":g["timeout"],"type":g["type"]}
+d["hooks"]["SessionStart"].append({"hooks":[{"command":"bash \x27/sandbox/.codex/herdr-agent-state.sh\x27 session","timeout":10,"type":"command"}]})
+open(p,"w").write(json.dumps(d,indent=2))' "$HOOKS"
+BEFORE_SHA="$(sha256sum "$HOOKS" | cut -d" " -f1)"
+want "[QK:CODEX-BIRTH-NORMALIZED-DIGEST] the certification is blind to key order and indentation a neighbour imposed — bytes changed, our declaration did not" \
+  "'$DOCTOR' --unit-only >'$SB/out' 2>&1 && grep -q \"entwurf's declaration is certified at .* group 0 handler 0\" '$SB/out' && grep -q 'NORMALIZED digest, not by file bytes' '$SB/out'"
+"$INSTALL" >"$SB/out" 2>&1 || die "reinstall after a neighbour re-serialized the file failed: $(cat "$SB/out")"
+want "that reinstall rewrote NOT ONE BYTE of the shared file" \
+  "grep -q 'NOT REWRITTEN, not one byte' '$SB/out' && [ \"\$(sha256sum '$HOOKS' | cut -d' ' -f1)\" = '$BEFORE_SHA' ]"
+
+# OUR OWN declaration edited is still a named refusal — the narrowing is about WHOSE bytes, not
+# about being lenient with ours. SHAPE catches it first: `timeout` is part of the identity the
+# operator approved, so a value the installer never writes is not a digest question at all.
+python3 -c 'import json,sys
+p=sys.argv[1]; d=json.load(open(p))
+d["hooks"]["SessionStart"][0]["hooks"][0]["timeout"]=31
+open(p,"w").write(json.dumps(d,indent=2))' "$HOOKS"
+refuses "[QK:CODEX-BIRTH-OWN-DECLARATION-DRIFT] an edit to entwurf's OWN handler is refused by name" "declaration-shape-drifted" "$INSTALL"
+"$DOCTOR" --unit-only >"$SB/out" 2>&1 && die "the doctor was green over an edited entwurf declaration"
+want "the doctor names our own drifted declaration and what about it drifted" "grep -q 'declaration is not certifiable' '$SB/out' && grep -q 'timeout must be 30' '$SB/out'"
+"$UNINSTALL" >"$SB/out" 2>&1 && die "the inverse removed an edited entwurf declaration"
+want "the inverse leaves our own drifted declaration in place" "grep -q 'DRIFT' '$SB/out' && grep -q 'declaration-shape-drifted' '$SB/out' && [ -f '$HOOKS' ]"
+
+# SHAPE and DIGEST are two different authorities and only one of them is the recorded receipt.
+# Shape asks "is this the declaration these fixed paths produce"; the digest asks "is this the
+# declaration the STATE recorded". Tampering with the receipt alone is the only way to separate
+# them, and it must be red: a receipt anyone can retune certifies nothing.
+rm -rf "$HOOKS" "$UNIT_ROOT"
+"$INSTALL" >/dev/null 2>&1 || die "install before the receipt-binding cell failed"
+python3 -c 'import json,sys
+p=sys.argv[1]; s=json.load(open(p))
+s["declaration"]["sha256"]="0"*64
+open(p,"w").write(json.dumps(s,indent=2))' "$STATE"
+want "[QK:CODEX-BIRTH-DECLARATION-RECEIPT-BINDS] the live declaration is compared to the RECORDED normalized digest, and a receipt that no longer names it is red" \
+  "! '$DOCTOR' --unit-only >'$SB/out' 2>&1 && grep -q 'declaration was EDITED after install' '$SB/out' && grep -q 'live normalized' '$SB/out' && grep -q 'recorded 0000' '$SB/out'"
+"$INSTALL" >/dev/null 2>&1 || die "install should re-record the receipt over a tampered one"
+"$DOCTOR" --unit-only >/dev/null 2>&1 || die "the unit axis should be green once the receipt is republished"
+ok "install re-records the declaration receipt, and the unit axis is green again"
+
+# ...and a SECOND copy of our declaration is a refusal too: the vendor would run the birth hook
+# twice per session, and only one of those positions can carry the operator's receipt.
+python3 -c 'import json,sys
+p=sys.argv[1]; d=json.load(open(p)); g=d["hooks"]["SessionStart"]
+g[0]["hooks"][0]["timeout"]=30
+g.append(json.loads(json.dumps(g[0])))
+open(p,"w").write(json.dumps(d,indent=2))' "$HOOKS"
+refuses "[QK:CODEX-BIRTH-DECLARATION-DUPLICATED] our declaration present twice is refused by name, never first-match accepted" "declaration-duplicated" "$INSTALL"
+"$DOCTOR" --unit-only >"$SB/out" 2>&1 && die "the doctor accepted a duplicated entwurf declaration"
+want "the doctor names the duplication and both positions" "grep -q 'declaration-duplicated' '$SB/out' && grep -qE 'group [0-9]+ handler [0-9]+, group [0-9]+ handler [0-9]+' '$SB/out'"
+rm -rf "$HOOKS" "$UNIT_ROOT"
+
+
 ln -s "$SB/foreign-hooks.json" "$HOOKS"
 refuses "a symlinked hooks.json is refused" "is a SYMLINK" "$INSTALL"
 want "the symlink refusal wrote no state" "[ ! -e '$STATE' ] && [ -L '$HOOKS' ]"
 rm -f "$HOOKS"
 
 "$INSTALL" >/dev/null 2>&1 || die "install before the edited-declaration cell failed"
+# WHITESPACE IS NOT DRIFT ANY MORE, and that is a contract change worth pinning: a normalized
+# digest is blind to formatting precisely so a neighbour's re-serialize cannot fake an edit.
 printf '\n' >> "$HOOKS"
+want "[QK:CODEX-BIRTH-WHITESPACE-NOT-DRIFT] reformatting alone is not drift — the digest is over the declaration, not the bytes" \
+  "'$DOCTOR' --unit-only >/dev/null 2>&1"
+# An edit to a FIELD of our handler still is.
+python3 -c 'import json,sys
+p=sys.argv[1]; d=json.load(open(p))
+d["hooks"]["SessionStart"][0]["hooks"][0]["timeout"]=7
+open(p,"w").write(json.dumps(d,indent=2))' "$HOOKS"
 cp "$HOOKS" "$SB/edited-hooks.json"
-refuses "an edited declaration is refused instead of republished" "was edited after install" "$INSTALL"
+refuses "an edited declaration is refused instead of republished" "declaration-shape-drifted" "$INSTALL"
 cmp -s "$SB/edited-hooks.json" "$HOOKS" && ok "the edited declaration survives the refusal byte-for-byte" || die "the edited hooks.json was overwritten"
 "$DOCTOR" --unit-only >"$SB/out" 2>&1 && die "the unit axis should be red while the declaration is edited"
-want "the doctor names the edited declaration" "grep -q 'was EDITED after install' '$SB/out'"
+want "the doctor names the edited declaration" "grep -q 'declaration is not certifiable' '$SB/out'"
 
 ###############################################################################
 # inverse — exact removal, and a refusal that leaves drift in place
 ###############################################################################
 "$UNINSTALL" >"$SB/out" 2>&1 && die "the inverse should refuse while the declaration is drifted"
-want "the inverse refuses the drifted declaration" "grep -q 'DRIFT: the declaration was edited after install' '$SB/out'"
+want "the inverse refuses the drifted declaration" "grep -q 'DRIFT' '$SB/out' && grep -q 'declaration-shape-drifted' '$SB/out'"
 want "the drifted declaration is LEFT IN PLACE" "[ -f '$HOOKS' ]"
 want "the inverse keeps the state so a later run can still license the path" "[ -f '$STATE' ]"
 cmp -s "$SB/edited-hooks.json" "$HOOKS" && ok "the drifted declaration is byte-identical after the refused inverse" || die "the refused inverse changed the drifted file"
@@ -234,7 +391,7 @@ printf '# operator edit\n' >> "$LAUNCHER"
 "$UNINSTALL" >"$SB/out" 2>&1 && die "the inverse should refuse while the launcher is drifted"
 want "the inverse refuses a drifted helper member by digest" "grep -q 'DRIFT: helper member was edited after install' '$SB/out'"
 want "the drifted launcher is LEFT IN PLACE" "[ -f '$LAUNCHER' ]"
-want "the declaration it already removed is gone, and the state remains" "[ ! -e '$HOOKS' ] && [ -f '$STATE' ]"
+want "[QK:CODEX-BIRTH-INVERSE-SOLE-OWNER] the declaration it already removed is GONE — the FILE arm deletes the file it was the sole declaration in — and the state remains, because a drifted helper is still owed a licence" "[ ! -e '$HOOKS' ] && [ -f '$STATE' ]"
 
 rm -f "$LAUNCHER"
 "$INSTALL" >/dev/null 2>&1 || die "reinstall before the exact-inverse cell failed"
@@ -249,6 +406,11 @@ cmp -s "$SB/config.before.toml" "$CFG" && ok "the full install/inverse cycle lef
 # empty unit on the strength of somebody else's approval — measured exactly that way once.
 "$DOCTOR" --unit-only >"$SB/out" 2>&1 && die "[QK:CODEX-BIRTH-DOCTOR-ABSENT-IS-RED] the unit axis was green with NOTHING installed"
 want "an absent unit is named as red, not as an informational note" "grep -q 'no Codex birth unit is installed here' '$SB/out'"
+# ...and with nothing installed the FOREIGN axis says NOT READ, never "none": the UNIT axis never
+# opened that file, and "none" would be this doctor asserting something about the operator's
+# hooks.json it never looked at.
+want "[QK:CODEX-BIRTH-FOREIGN-UNREAD-NOT-NONE] an unscanned FOREIGN axis reports NOT READ rather than claiming there are no neighbours" \
+  "grep -q 'NOT READ' '$SB/out' && ! grep -q 'none — entwurf is the only' '$SB/out'"
 trust_receipt "$HOOKS:session_start:0:0"
 "$DOCTOR" >"$SB/out" 2>&1 && die "a stale vendor receipt made an ABSENT unit green"
 want "a stale receipt cannot carry an absent unit" "grep -q 'no Codex birth unit is installed here' '$SB/out'"
@@ -314,6 +476,29 @@ python3 -c 'import json,sys; s=json.load(open(sys.argv[1])); s["status"]="publis
 "$INSTALL" >/dev/null 2>&1 || die "an interrupted `publishing` state should be finishable, not refused"
 want "the finished publish records installed" "grep -q '\"status\": \"installed\"' '$STATE'"
 
+# A v1 ownership receipt recorded a digest of the WHOLE hooks.json. Reading it leniently would
+# certify bytes a neighbour owns, so every reader refuses it by name — and the installer is the
+# one forward path, superseding it without removing anything or rewriting a foreign byte.
+rm -rf "$HOOKS" "$UNIT_ROOT"
+"$INSTALL" >/dev/null 2>&1 || die "install before the v1-supersede cell failed"
+python3 -c 'import json,sys
+p=sys.argv[1]; s=json.load(open(p))
+s["schema"]="codex-birth-install-state/v1"
+s["hooksSha256"]="1"*64
+del s["declaration"]
+open(p,"w").write(json.dumps(s,indent=2))' "$STATE"
+want "[QK:CODEX-BIRTH-STATE-V1-REFUSED] the doctor refuses a v1 receipt by name and names the one forward path" \
+  "! '$DOCTOR' --unit-only >'$SB/out' 2>&1 && grep -q 'codex-birth-install-state/v1' '$SB/out' && grep -q 'WHOLE hooks.json' '$SB/out' && grep -q 'install-codex-birth' '$SB/out'"
+"$UNINSTALL" >"$SB/out" 2>&1 && die "the inverse removed things on the word of a v1 receipt"
+want "the inverse refuses a v1 receipt and removes NOTHING" \
+  "grep -q 'codex-birth-install-state/v2' '$SB/out' && [ -f '$HOOKS' ] && [ -f '$LAUNCHER' ] && [ -f '$STATE' ]"
+HOOKS_BEFORE_V1="$(sha256sum "$HOOKS" | cut -d' ' -f1)"
+"$INSTALL" >"$SB/out" 2>&1 || die "the installer should supersede a v1 receipt: $(cat "$SB/out")"
+want "the installer supersedes v1 forward, says so, and rewrites not one byte of hooks.json" \
+  "grep -q 'superseding a v1 ownership receipt' '$SB/out' && grep -q 'NOT REWRITTEN, not one byte' '$SB/out' && [ \"\$(sha256sum '$HOOKS' | cut -d' ' -f1)\" = \"$HOOKS_BEFORE_V1\" ]"
+"$DOCTOR" --unit-only >/dev/null 2>&1 || die "the unit axis should be green once the receipt is v2"
+ok "the unit axis is green once the receipt has been superseded to v2"
+
 # The directory holding the receipt carries the receipt's authority. Children untouched: what
 # changed is only who may replace the inventory every digest is compared against.
 chmod 0777 "$UNIT_ROOT"
@@ -330,6 +515,90 @@ chmod 0755 "$UNIT_ROOT"
 ok "the unit axis is green again once the root is no longer writable"
 "$UNINSTALL" >/dev/null 2>&1 || die "cleanup uninstall after the parent-authority cell failed"
 
+# ── the FILE verdict has to EARN its delete (sol B2, 2026-09-18) ─────────────────────────────
+# The counterexample, derived from the source rather than imagined: a hooks.json that existed
+# BEFORE this unit, carrying a foreign top-level `description` and an EMPTY SessionStart array.
+# Our install appends one group, so afterwards there is no foreign GROUP, one event, and one
+# declaration — which is exactly what the old FILE test asked. It deleted the whole file, and the
+# neighbour's description with it, while the receipt had recorded `hooksExistedBefore: true` the
+# entire time and nothing read it.
+"$UNINSTALL" >/dev/null 2>&1 || true
+printf '{\n  "description": "a neighbour wrote this",\n  "note": "and this",\n  "hooks": {\n    "SessionStart": []\n  }\n}\n' > "$HOOKS"
+chmod 0600 "$HOOKS"
+PRE_EXISTING_SHA="$(sha256sum "$HOOKS" | cut -d' ' -f1)"
+"$INSTALL" >/dev/null 2>&1 || die "install into a pre-existing empty-declaration file failed"
+"$UNINSTALL" >"$SB/out" 2>&1 || die "uninstall after that install failed: $(cat "$SB/out")"
+want "[QK:CODEX-BIRTH-INVERSE-KEEPS-PRE-EXISTING-FILE] a file that existed BEFORE this unit survives the inverse whole — our group comes out by splice and the neighbour's top-level bytes come back byte-for-byte, because hooksExistedBefore is a removal authority and not a decoration" \
+  "[ -f '$HOOKS' ] && [ \"\$(sha256sum '$HOOKS' | cut -d' ' -f1)\" = \"$PRE_EXISTING_SHA\" ] && grep -q 'by text splice' '$SB/out'"
+# And the delete arm still exists for the case it was written for: a file this unit created,
+# holding nothing but its own description and its own group.
+rm -f "$HOOKS"
+"$INSTALL" >/dev/null 2>&1 || die "install into a host with no hooks.json failed"
+"$UNINSTALL" >"$SB/out" 2>&1 || die "uninstall of a file we created failed: $(cat "$SB/out")"
+want "a hooks.json this unit CREATED, holding only its own description and group, is still removed whole — the narrowing above added proofs to that delete, it did not retire it" \
+  "[ ! -e '$HOOKS' ] && grep -q 'entwurf was its only declaration' '$SB/out'"
+
+# ── the SHARED file's own ownership, decided ONCE for four surfaces (sol B3, 2026-09-18) ─────
+# The split this closes: install and uninstall asked only symlink-and-regular, the doctor asked
+# NOTHING about who owned hooks.json, and only the fresh-call preflight refused a foreign uid or a
+# group-writable mode. So a host could install clean, read GREEN, and have every Codex launch
+# refuse it as `codex-birth-unit-missing` — three surfaces saying yes about bytes the fourth said
+# no about. All four now decide with `classifyOwnedPath` in the shared declaration leaf.
+#
+# We still never chmod what we share. The cells below prove the mode we found is the mode left
+# behind: an unsafe shared file is a zero-write REFUSAL, not a file we normalise on the way past.
+"$INSTALL" >/dev/null 2>&1 || die "install before the shared-ownership cells failed"
+HOOKS_BEFORE_UNSAFE="$(sha256sum "$HOOKS" | cut -d' ' -f1)"
+chmod 0666 "$HOOKS"
+refuses "[QK:CODEX-BIRTH-SHARED-FILE-OWNERSHIP] install refuses a hooks.json anyone else can rewrite — a receipt cannot bind bytes somebody else controls" \
+  "group/world-writable" "$INSTALL"
+want "the refused install neither repaired the mode nor wrote a byte" \
+  "[ \"\$(stat -c %a '$HOOKS')\" = '666' ] && [ \"\$(sha256sum '$HOOKS' | cut -d' ' -f1)\" = \"$HOOKS_BEFORE_UNSAFE\" ]"
+# ONE assertion, because the exit code and the wording are one claim: a doctor that stayed green
+# would fail a separate negative line first, and that line could not carry the token (a manifest
+# may name its QK exactly once per gate source), so the mutant would die unattributable.
+DOCTOR_RC=0
+"$DOCTOR" --unit-only >"$SB/out" 2>&1 || DOCTOR_RC=$?
+want "[QK:CODEX-BIRTH-DOCTOR-SHARED-OWNERSHIP] the doctor asks the same ownership question BEFORE it measures any digest — a digest taken in a file somebody else can rewrite certifies nothing, and a green here would contradict the launcher" \
+  "[ \"$DOCTOR_RC\" -ne 0 ] && grep -q 'group/world-writable' '$SB/out' && grep -q 'every Codex fresh call refuses this host' '$SB/out'"
+"$UNINSTALL" >"$SB/out" 2>&1 || true   # drift is a nonzero exit; the WORDS and the bytes are the claim
+want "[QK:CODEX-BIRTH-INVERSE-SHARED-OWNERSHIP] the inverse asks it too and leaves an unsafe shared file exactly as found, counted as DRIFT — it used to rewrite a file it could not bind" \
+  "grep -q 'DRIFT: the declaration file writable-by-others' '$SB/out' && [ \"\$(sha256sum '$HOOKS' | cut -d' ' -f1)\" = \"$HOOKS_BEFORE_UNSAFE\" ]"
+chmod 0600 "$HOOKS"
+# That inverse removed the closure it COULD account for and left the shared file alone, so the
+# way back to green is an install — which is itself the claim: the refusal was about this file's
+# ownership and nothing else, and it lifts the moment the ownership does.
+"$INSTALL" >/dev/null 2>&1 || die "install should succeed again once the shared file is no longer writable by others"
+"$DOCTOR" --unit-only >/dev/null 2>&1 || die "the unit axis should be green again once the shared file is no longer writable by others"
+ok "all four surfaces agree again once the shared file is safe"
+ln -sf "$SB/foreign-only.json" "$SB/hooks-link.json"
+refuses "a symlinked hooks.json is refused with its OWN word — the repair is not a mode change, it is a different file" \
+  "SYMLINK" env CODEX_HOME="$CODEX_HOME" HOOKS_LINK=1 bash -c "cp '$HOOKS' '$SB/hooks-real.json'; rm '$HOOKS'; ln -s '$SB/hooks-real.json' '$HOOKS'; '$INSTALL'"
+rm -f "$HOOKS"; cp "$SB/hooks-real.json" "$HOOKS"; chmod 0600 "$HOOKS"
+"$UNINSTALL" >/dev/null 2>&1 || die "cleanup uninstall after the shared-ownership cells failed"
+
+# ── the ORPHAN verdict: our bytes with no receipt behind them (glm #2) ────────────────────────
+# `[glm 감사 2026-09-18]` this branch had no assertion and no mutant at all. It is the half-removed
+# state — a declaration commanding OUR launcher, or a closure directory, with the receipt that
+# licenses removing them gone — and the doctor must go RED rather than fall through to the
+# "nothing is installed here" arm, which reads as a clean host and invites a reinstall over bytes
+# the inverse will then refuse.
+"$INSTALL" >/dev/null 2>&1 || die "install before the orphan cell failed"
+ORPHAN_HOOKS_SHA="$(sha256sum "$HOOKS" | cut -d' ' -f1)"
+mv "$STATE" "$SB/state-parked.json"
+# ONE assertion, because red-for-the-wrong-reason is the failure mode here: with the orphan test
+# removed the doctor still exits nonzero, down the "nothing is installed here" arm, and a cell that
+# only checked the exit code would call that a kill. The WORDS are the claim.
+ORPHAN_RC=0
+"$DOCTOR" --unit-only >"$SB/out" 2>&1 || ORPHAN_RC=$?
+want "[QK:CODEX-BIRTH-DOCTOR-ORPHAN-RED] a declaration or closure with no receipt behind it is RED and NAMED as not provably ours — never the clean-host arm, which reads as nothing installed and invites a reinstall over bytes the inverse will then refuse" \
+  "[ \"$ORPHAN_RC\" -ne 0 ] && grep -q 'not provably ours' '$SB/out' && ! grep -q 'no Codex birth unit is installed here' '$SB/out'"
+want "the orphan doctor is READ-ONLY — it names those bytes and repairs nothing" \
+  "[ \"\$(sha256sum '$HOOKS' | cut -d' ' -f1)\" = \"$ORPHAN_HOOKS_SHA\" ] && [ ! -e '$STATE' ]"
+mv "$SB/state-parked.json" "$STATE"
+"$DOCTOR" --unit-only >/dev/null 2>&1 || die "the unit axis should be green again once the receipt is back"
+"$UNINSTALL" >/dev/null 2>&1 || die "cleanup uninstall after the orphan cell failed"
+
 # A relative root would make "the fixed launcher path" depend on the caller's cwd — and that
 # path is exactly what the vendor keys its trust receipt to.
 ( cd "$SB" && CODEX_HOME="relative/.codex" "$INSTALL" >"$SB/out" 2>&1 ) && die "[QK:CODEX-BIRTH-REFUSES-RELATIVE-ROOT] a relative CODEX_HOME was accepted"