@junghanacs/entwurf 0.22.0 → 0.23.1

package/scripts/codex-birth-install.sh

@@ -3,7 +3,7 @@
 #
 # Three paths, all the operator's own:
 #
-#   $CODEX_HOME/hooks.json                          ONE complete file, ours or absent
+#   $CODEX_HOME/hooks.json                          ONE SessionStart group inside a SHARED file
 #   ${XDG_DATA_HOME:-~/.local/share}/entwurf/codex-birth/helper/
 #                                                   launcher + the TS payload closure
 #   .../entwurf/codex-birth/install-state.json      the digest inventory that licenses removal
@@ -23,6 +23,16 @@
 # give; forging it in a file we already own would be the one shortcut that turns a security
 # prompt into a silent install.
 #
+# WHAT THIS UNIT OWNS IN hooks.json, AND WHAT IT DOES NOT (#117). Until 0.22.0 this unit owned
+# that file WHOLE: it refused any file it had not written and recorded a whole-file sha256. That
+# was true only while entwurf was the only thing declaring a Codex hook. Herdr's official Codex
+# integration appends its own `SessionStart` group and the vendor keeps running both, because
+# `[source]` discovery.rs:664-665 keys trust by `<path>:<event>:<group_idx>:<handler_idx>` — trust
+# is DECLARATION-scoped and always was. So this unit now owns exactly one group holding exactly
+# one handler whose command is our quoted launcher path. Every other group is FOREIGN: reported,
+# never certified, never rewritten. Adding and removing our group is a TEXT SPLICE
+# (pi-extensions/lib/codex-declaration.js), so a neighbour's bytes come through untouched.
+#
 # THE TRUST IDENTITY IS THE LAUNCHER PATH. `[source]` discovery.rs:775-792 hashes a
 # normalized identity of (event name + matcher group + the single handler) — so `type`, the
 # quoted absolute `command`, `timeout` and the absent `matcher` ARE the operator's approval,
@@ -79,6 +89,9 @@ case "$NODE_BIN" in /*) : ;; *) die "resolved node path is not absolute: $NODE_B
 NODE_MAJOR="$("$NODE_BIN" -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0)"
 [ "$NODE_MAJOR" -ge 24 ] 2>/dev/null || die "node >= 24 is required (the payload is stripped, not compiled); $NODE_BIN reports major '$NODE_MAJOR'."
 
+DECLARATION_LIB="$REPO/pi-extensions/lib/codex-declaration.js"
+[ -f "$DECLARATION_LIB" ] || die "the declaration leaf is missing: $DECLARATION_LIB (reinstall the package, or check out the repo completely)."
+
 PAYLOAD_SRC="$REPO/pi-extensions/$PAYLOAD_NAME"
 LIB_SRC="$REPO/pi-extensions/lib/meta-session.ts"
 CODEX_CLIENT_SRC="$REPO/pi-extensions/lib/native-push/codex-ws-client.ts"
@@ -108,6 +121,38 @@ safe_own_dir() { # $1 = dir, $2 = label
   [ $((8#$mode & 0022)) -eq 0 ] || die "$2 ($1) is group/world-writable (mode $mode), so its contents are not provably ours. Nothing written."
 }
 
+# The SHARED file's own ownership, judged by the SHARED predicate (sol B3, 2026-09-18).
+# `classifyOwnedPath` lives in codex-declaration.js because four surfaces decide about this one
+# file — this installer, the inverse, the doctor and the fresh-call preflight — and they used to
+# decide differently: the two shells asked only symlink-and-regular, preflight asked owner and mode
+# too, and the doctor asked neither. An install could therefore succeed and a doctor go green on
+# bytes every Codex launch then refused as `codex-birth-unit-missing`.
+#
+# We still do NOT chmod what we share: a neighbour's mode is theirs, and the APPEND below carries
+# it over untouched. Writing into a file anyone else may rewrite is the different question, and the
+# answer to that one is a refusal, because a receipt cannot bind bytes somebody else controls.
+owned_path_verdict() { # $1 = path, $2 = file|directory
+  "$NODE_BIN" -e '
+    import(process.argv[1]).then((m) => {
+      const fs = require("node:fs");
+      process.stdout.write(m.classifyOwnedPath(m.statOwnedPath(fs, process.argv[2]), process.getuid(), { kind: process.argv[3] }));
+    }).catch((err) => { process.stderr.write(String(err && err.message ? err.message : err)); process.exit(1); });
+  ' "$DECLARATION_LIB" "$1" "${2:-file}"
+}
+
+require_writable_share() { # $1 = path, $2 = label — `missing` is fine; we are about to create it
+  local verdict
+  verdict="$(owned_path_verdict "$1" file)" || die "$2 ($1) could not be judged: $verdict. Nothing written."
+  case "$verdict" in
+    ok|missing) : ;;
+    symlink) die "$2 ($1) is a SYMLINK. This unit owns that path as ONE regular file and never publishes through a link. Refusing; nothing written." ;;
+    not-regular) die "$2 ($1) exists and is not a regular file. Refusing; nothing written." ;;
+    foreign-uid) die "$2 ($1) is owned by another user, so nothing this unit certifies in it can bind what it will say next. Refusing; nothing written." ;;
+    writable-by-others) die "$2 ($1) is group/world-writable, so anything certified in it can be rewritten by someone else afterwards. Its mode is not ours to change either. Refusing; nothing written." ;;
+    *) die "$2 ($1) returned an unknown ownership verdict '$verdict'. Refusing; nothing written." ;;
+  esac
+}
+
 # ── ownership preflight — READ-ONLY, and every refusal is zero-write ─────────
 # Three different facts, three different refusals, none of them silent:
 #   a foreign hooks.json (no state behind it), a hand-edited one (state disagrees), and a
@@ -120,7 +165,7 @@ safe_own_dir() { # $1 = dir, $2 = label
 [ -e "$UNIT_ROOT" ] && safe_own_dir "$UNIT_ROOT" "the unit root (it holds the ownership state)"
 
 STATE_PRESENT=0
-RECORDED_HOOKS_SHA=""
+RECORDED_SCHEMA=""
 if [ -e "$STATE_FILE" ] || [ -L "$STATE_FILE" ]; then
   [ -L "$STATE_FILE" ] && die "$STATE_FILE is a symlink — refusing to take replacement authority from a link. Nothing written."
   [ -f "$STATE_FILE" ] || die "$STATE_FILE is not a regular file. Nothing written."
@@ -131,14 +176,19 @@ if [ -e "$STATE_FILE" ] || [ -L "$STATE_FILE" ]; then
   STATE_READ="$("$NODE_BIN" -e '
     const s = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"));
     const path = require("node:path");
-    if (s.schema !== "codex-birth-install-state/v1") throw new Error("foreign state schema " + JSON.stringify(s.schema));
+    // v1 is READ HERE AND NOWHERE ELSE, and only to be SUPERSEDED. It recorded a whole-file
+    // hooksSha256 this installer no longer consults: whether hooks.json may be edited is now
+    // decided by reading the live document and selecting our own declaration, not by a receipt
+    // from a generation that claimed the whole file. What v1 still holds that this run needs is
+    // the CLOSURE inventory, whose shape is identical in both schemas. Every other reader —
+    // uninstall, doctor, preflight — refuses v1 by name and sends the operator here.
+    if (s.schema !== "codex-birth-install-state/v2" && s.schema !== "codex-birth-install-state/v1") throw new Error("foreign state schema " + JSON.stringify(s.schema));
     // A state this unit never wrote — or one left in a status it does not define — is not a
     // receipt, however well its digests happen to match. `publishing` is the one interrupted
     // generation this installer knows how to finish.
     if (s.status !== "installed" && s.status !== "publishing") throw new Error("unknown state status " + JSON.stringify(s.status));
     if (s.hooksFile !== process.argv[2]) throw new Error("state is bound to " + s.hooksFile + ", not " + process.argv[2]);
     if (s.helperDir !== process.argv[3]) throw new Error("state is bound to helper dir " + s.helperDir);
-    if (!/^[0-9a-f]{64}$/.test(s.hooksSha256)) throw new Error("hooksSha256 is not a digest");
     // The inventory is the removal/replacement authority, so it must be EXACTLY the closure
     // this unit publishes: a state naming fewer members would leave an unlisted file in the
     // helper directory that nothing can reclaim, and one naming more would license deleting
@@ -164,7 +214,7 @@ if [ -e "$STATE_FILE" ] || [ -L "$STATE_FILE" ]; then
           (duplicate.length ? "; duplicated " + duplicate.join(", ") : ""),
       );
     }
-    const lines = ["HOOKSSHA\t" + s.hooksSha256];
+    const lines = ["SCHEMA\t" + s.schema];
     for (const f of s.helperFiles) {
       if (typeof f?.path !== "string" || f.path.length === 0 || f.path.startsWith("/") || f.path.split("/").includes("..")) {
         throw new Error("unsafe helper path " + JSON.stringify(f?.path));
@@ -175,7 +225,7 @@ if [ -e "$STATE_FILE" ] || [ -L "$STATE_FILE" ]; then
     process.stdout.write(lines.join("\n"));
   ' "$STATE_FILE" "$HOOKS_FILE" "$HELPER_DIR" 2>&1)" || die "the ownership state is malformed or bound elsewhere, so replacement authority is UNKNOWN: $STATE_READ
 Move $STATE_FILE aside deliberately and re-run. Nothing written."
-  RECORDED_HOOKS_SHA="$(printf '%s\n' "$STATE_READ" | sed -n 's/^HOOKSSHA\t//p')"
+  RECORDED_SCHEMA="$(printf '%s\n' "$STATE_READ" | sed -n 's/^SCHEMA\t//p')"
   STATE_PRESENT=1
 
   # The closure is licensed by the SAME rule as the declaration, and for the same reason.
@@ -214,25 +264,9 @@ $STATE_READ
 EOF
 fi
 
-if [ -L "$HOOKS_FILE" ]; then
-  die "$HOOKS_FILE is a SYMLINK. This unit owns that path as ONE regular file and never publishes through a link. Refusing; nothing written."
-fi
-if [ -e "$HOOKS_FILE" ]; then
-  [ -f "$HOOKS_FILE" ] || die "$HOOKS_FILE exists and is not a regular file. Refusing; nothing written."
-  LIVE_HOOKS_SHA="$(sha_of "$HOOKS_FILE")"
-  if [ "$STATE_PRESENT" = "0" ]; then
-    die "$HOOKS_FILE already exists and this host has NO entwurf ownership state ($STATE_FILE).
-This unit owns hooks.json as ONE COMPLETE FILE, so adopting it would silently delete hook
-declarations somebody else wrote. Refusing; nothing written.
-Move it aside deliberately and re-run — or declare your own hooks in config.toml, which the
-vendor merges with this file (both sources load per layer)."
-  fi
-  if [ "$LIVE_HOOKS_SHA" != "$RECORDED_HOOKS_SHA" ]; then
-    die "$HOOKS_FILE was edited after install (live $LIVE_HOOKS_SHA, recorded $RECORDED_HOOKS_SHA).
-Republishing would throw away an edit this unit cannot read back. Refusing; nothing written.
-If the edit was yours, keep it and stop using this unit; otherwise run the inverse first."
-  fi
-  note "adopting the hooks.json this unit published (sha256 $LIVE_HOOKS_SHA) — it will be republished."
+require_writable_share "$HOOKS_FILE" "the declaration file"
+if [ "$STATE_PRESENT" = "1" ] && [ "$RECORDED_SCHEMA" = "codex-birth-install-state/v1" ]; then
+  note "superseding a v1 ownership receipt (it claimed the WHOLE hooks.json) with v2 (it certifies entwurf's own declaration) — no foreign byte is read as ours, and none is rewritten."
 fi
 
 if [ -e "$HELPER_DIR" ] || [ -L "$HELPER_DIR" ]; then
@@ -301,59 +335,113 @@ REGISTRY_SHA="$(sha_of "$STAGE/entwurf-capabilities.json")"
 #            identity from the record this hook writes.
 #   state    not a hooks.json key at all; `[hooks.state]` is the vendor's, in config.toml, and
 #            this unit neither reads nor writes that file.
-cat > "$HOOKS_TMP" <<HOOKSJSON
-{
-  "description": "entwurf codex-birth $UNIT_VERSION — mints one garden meta-record per top-level Codex thread on its first turn. Managed by scripts/codex-birth-install.sh; inverse: scripts/codex-birth-uninstall.sh. Do not edit: the exact bytes are recorded in $STATE_FILE. The vendor's trust decision for this declaration lives in config.toml and is the operator's alone.",
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "'$LAUNCHER'",
-            "timeout": 30
-          }
-        ]
+#
+# FOUR OUTCOMES, AND ONLY TWO OF THEM WRITE (#117). The declaration leaf decides, because it is
+# the same leaf the doctor and the fresh preflight judge with:
+#
+#   PRESENT+CERTIFIED  our group is there, shaped right, and its normalized digest is the one
+#                      this unit publishes -> hooks.json is NOT TOUCHED AT ALL. Not rewritten,
+#                      not re-serialized, mtime unchanged. This is the ordinary re-run on a host
+#                      where a neighbour has since re-serialized the document.
+#   ABSENT             our group is not there -> it is APPENDED by text splice. Every foreign
+#                      group comes through byte-for-byte, and appending (rather than inserting)
+#                      leaves a neighbour's index — and therefore their trust receipt — alone.
+#   CREATE             no file at all -> this unit writes the whole document, description and all.
+#                      A description is OURS only on a file we created; into a shared file this
+#                      unit adds no prose, because that member belongs to whoever made it.
+#   DRIFTED/DUPLICATED our group is there and edited, or there twice -> zero-write REFUSAL by
+#                      name. Republishing would throw away an edit nobody can read back, and
+#                      duplication is a birth hook the vendor would run twice.
+#
+# Every splice is re-parsed and deep-compared to the value it intended before it reaches a file
+# (`certifySplice`), so a span edit that lands anywhere else is a refusal, not a written file.
+HOOKS_DESCRIPTION="entwurf codex-birth $UNIT_VERSION — mints one garden meta-record per top-level Codex thread on its first turn. Managed by scripts/codex-birth-install.sh; inverse: scripts/codex-birth-uninstall.sh. This unit owns ONLY this SessionStart declaration; any other group in this file is foreign and is never read as ours. The vendor's trust decision for this declaration lives in config.toml and is the operator's alone."
+DECISION="$("$NODE_BIN" -e '
+  const fs = require("node:fs");
+  const [, lib, hooksFile, launcher, description, outTmp] = process.argv;
+  import(lib).then((m) => {
+    const group = m.entwurfDeclarationGroup(launcher);
+    const digest = m.declarationDigest(group);
+    const emit = (verdict, detail) => process.stdout.write([verdict, digest, detail ?? ""].join("\t"));
+    if (!fs.existsSync(hooksFile)) {
+      fs.writeFileSync(outTmp, JSON.stringify({ description, hooks: { SessionStart: [group] } }, null, 2) + "\n");
+      return emit("CREATE", "");
+    }
+    const text = fs.readFileSync(hooksFile, "utf8");
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch (err) {
+      throw new Error(hooksFile + " is not readable JSON (" + err.message + "). This unit edits only its own declaration inside that file and will not rewrite a document it cannot read.");
+    }
+    const sel = m.selectEntwurfDeclaration(parsed, launcher);
+    if (sel.ok) {
+      if (sel.digest !== digest) {
+        throw new Error(
+          "entwurf\u2019s own declaration in " + hooksFile + " was EDITED after install (group " + sel.groupIndex +
+            ": live " + sel.digest + ", this unit publishes " + digest + "). Republishing would throw away an edit this unit cannot read back. If the edit was yours, keep it and stop using this unit; otherwise run the inverse first.",
+        );
       }
-    ]
-  }
-}
-HOOKSJSON
+      return emit("UNCHANGED", String(sel.foreign.length));
+    }
+    if (sel.code !== "declaration-absent") throw new Error(sel.code + ": " + sel.detail);
+    const want = JSON.parse(text);
+    if (want.hooks === null || typeof want.hooks !== "object" || Array.isArray(want.hooks)) {
+      throw new Error(hooksFile + " carries no `hooks` object, so there is nowhere to declare a SessionStart group without rewriting somebody else\u2019s grammar.");
+    }
+    want.hooks.SessionStart = (Array.isArray(want.hooks.SessionStart) ? want.hooks.SessionStart : []).concat([group]);
+    fs.writeFileSync(outTmp, m.certifySplice(m.appendSessionStartGroup(m.ensureSessionStartArray(text), group), want));
+    return emit("APPEND", String(sel.foreign.length));
+  }).catch((err) => {
+    process.stderr.write(err && err.message ? err.message : String(err));
+    process.exit(1);
+  });
+' "$DECLARATION_LIB" "$HOOKS_FILE" "$LAUNCHER" "$HOOKS_DESCRIPTION" "$HOOKS_TMP" 2>&1)" || die "$DECISION
+Refusing; nothing written."
+HOOKS_ACTION="$(printf '%s' "$DECISION" | cut -f1)"
+DECL_SHA="$(printf '%s' "$DECISION" | cut -f2)"
+FOREIGN_COUNT="$(printf '%s' "$DECISION" | cut -f3)"
+# Exactly 64 hex, not "starts hex": this value is written into the ownership receipt and every
+# later reader compares the live declaration to it, so a truncated or warning-polluted capture
+# would record a receipt nothing can ever match.
+case "$DECL_SHA" in
+  ""|*[!0-9a-f]*) die "the declaration leaf returned no digest (got '$DECISION'). Nothing written." ;;
+esac
+[ "${#DECL_SHA}" -eq 64 ] || die "the declaration leaf returned a ${#DECL_SHA}-character digest, not 64 (got '$DECISION'). Nothing written."
+# `mktemp` made this file, so it always exists; chmod it unconditionally rather than behind a
+# test whose false branch would be the last command of a `set -e` line.
 chmod 0644 -- "$HOOKS_TMP"
 
-# Prove the bytes are the grammar we think they are BEFORE they are published: a broken
-# hooks.json is a hook nobody declared and nobody can see failing.
-"$NODE_BIN" -e '
-  const fs = require("node:fs");
-  const f = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
-  if (Object.keys(f).sort().join(",") !== "description,hooks") throw new Error("hooks.json top level must be exactly description+hooks");
-  const groups = f.hooks?.SessionStart;
-  if (Object.keys(f.hooks).join(",") !== "SessionStart") throw new Error("this unit declares SessionStart and nothing else");
-  if (!Array.isArray(groups) || groups.length !== 1) throw new Error("hooks.SessionStart must be a single matcher group");
-  if ("matcher" in groups[0]) throw new Error("the matcher group must carry no matcher key");
-  if (Object.keys(groups[0]).join(",") !== "hooks") throw new Error("the matcher group must carry no key other than hooks");
-  const hs = groups[0].hooks;
-  if (!Array.isArray(hs) || hs.length !== 1) throw new Error("the matcher group must hold exactly one handler");
-  if (Object.keys(hs[0]).sort().join(",") !== "command,timeout,type") throw new Error("the handler must carry exactly type+command+timeout — every extra key changes the trust identity");
-  if (hs[0].type !== "command") throw new Error("the handler type must be command");
-  if (hs[0].timeout !== 30) throw new Error("the handler timeout must be 30 — it is part of the hash the operator trusts");
-  if (hs[0].command !== "'"'"'" + process.argv[2] + "'"'"'") throw new Error("the command must be the single-quoted fixed launcher path, got " + hs[0].command);
-' "$HOOKS_TMP" "$LAUNCHER" || die "the staged hooks.json is not the exact declaration this unit publishes. Nothing written."
-HOOKS_SHA="$(sha_of "$HOOKS_TMP")"
-
+# Prove the staged bytes carry EXACTLY our declaration before they are published: a broken or
+# absorbed hooks.json is a hook nobody declared and nobody can see failing. The same leaf reads
+# it back, so what is asserted here is what the doctor and the preflight will assert later.
+if [ "$HOOKS_ACTION" != "UNCHANGED" ]; then
+  "$NODE_BIN" -e '
+    const fs = require("node:fs");
+    const [, lib, staged, launcher, wantDigest] = process.argv;
+    import(lib).then((m) => {
+      const sel = m.selectEntwurfDeclaration(JSON.parse(fs.readFileSync(staged, "utf8")), launcher);
+      if (!sel.ok) throw new Error("the staged document does not carry our declaration: " + sel.code + " " + sel.detail);
+      if (sel.digest !== wantDigest) throw new Error("the staged declaration digest is " + sel.digest + ", not " + wantDigest);
+    }).catch((err) => {
+      process.stderr.write(err && err.message ? err.message : String(err));
+      process.exit(1);
+    });
+  ' "$DECLARATION_LIB" "$HOOKS_TMP" "$LAUNCHER" "$DECL_SHA" || die "the staged hooks.json is not the exact declaration this unit publishes. Nothing written."
+fi
 write_state() { # $1 = status
   # Created here only when absent — the safe umask floors it and the explicit mode removes any
   # doubt. An EXISTING root was judged above and is left exactly as it was found.
   if [ ! -e "$UNIT_ROOT" ]; then mkdir -p -- "$UNIT_ROOT" && chmod 0755 -- "$UNIT_ROOT"; fi
   cat > "$STATE_TMP" <<STATE
 {
-  "schema": "codex-birth-install-state/v1",
+  "schema": "codex-birth-install-state/v2",
   "status": "$1",
   "unitVersion": "$UNIT_VERSION",
   "writtenAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
   "nodeBin": "$NODE_BIN",
   "hooksFile": "$HOOKS_FILE",
-  "hooksSha256": "$HOOKS_SHA",
+  "declaration": { "event": "SessionStart", "command": "'$LAUNCHER'", "sha256": "$DECL_SHA" },
   "hooksExistedBefore": $HOOKS_EXISTED,
   "helperDir": "$HELPER_DIR",
   "helperFiles": [
@@ -396,18 +484,36 @@ chmod 0755 -- "$LAUNCHER"
 chmod 0644 -- "$HELPER_DIR/$PAYLOAD_NAME" "$HELPER_DIR/lib/meta-session.ts" "$HELPER_DIR/lib/native-push/codex-ws-client.ts" "$HELPER_DIR/lib/session-id.js" "$HELPER_DIR/entwurf-capabilities.json"
 
 if [ ! -e "$CODEX_HOME" ]; then mkdir -p -- "$CODEX_HOME" && chmod 0755 -- "$CODEX_HOME"; fi
-# Strongest idempotence is an untouched file: identical bytes are not rewritten, so a
-# re-run leaves mtime — and any vendor state keyed off it — alone.
-if [ -f "$HOOKS_FILE" ] && [ "$(sha_of "$HOOKS_FILE")" = "$HOOKS_SHA" ]; then
-  note "hooks.json is already the exact declaration — not rewritten"
-else
-  cp -- "$HOOKS_TMP" "$HOOKS_FILE.tmp" && mv -f -- "$HOOKS_FILE.tmp" "$HOOKS_FILE"
-fi
+# Strongest idempotence is an UNTOUCHED file, and on a shared hooks.json that is also the only
+# honest one: re-serializing a document to reproduce bytes we already agree with would rewrite
+# every neighbouring declaration for no reason at all.
+case "$HOOKS_ACTION" in
+  UNCHANGED)
+    note "hooks.json already carries entwurf's declaration (normalized sha256 $DECL_SHA) — NOT REWRITTEN, not one byte"
+    ;;
+  APPEND)
+    # The file was somebody else's before this line and is shared after it, so its MODE is
+    # carried over from what we found rather than reset to the one a fresh publish would use.
+    chmod "$(stat -c %a -- "$HOOKS_FILE")" -- "$HOOKS_TMP"
+    cp -- "$HOOKS_TMP" "$HOOKS_FILE.tmp" && mv -f -- "$HOOKS_FILE.tmp" "$HOOKS_FILE"
+    note "appended entwurf's declaration to the existing hooks.json by text splice — every foreign group came through byte-for-byte"
+    ;;
+  CREATE)
+    cp -- "$HOOKS_TMP" "$HOOKS_FILE.tmp" && mv -f -- "$HOOKS_FILE.tmp" "$HOOKS_FILE"
+    ;;
+  *)
+    die "unknown declaration decision '$HOOKS_ACTION'. Nothing more written."
+    ;;
+esac
 
 write_state installed
 
 note "installed"
-note "  declaration : $HOOKS_FILE (sha256 $HOOKS_SHA)"
+note "  declaration : $HOOKS_FILE (normalized sha256 $DECL_SHA)"
+case "$FOREIGN_COUNT" in
+  ""|0) note "  neighbours  : none — entwurf is the only SessionStart declaration in that file" ;;
+  *) note "  neighbours  : $FOREIGN_COUNT foreign SessionStart group(s) in that file, neither certified nor touched" ;;
+esac
 note "  launcher    : $LAUNCHER"
 note "  state       : $STATE_FILE"
 note "The vendor will ask the operator to trust this declaration ONCE, in the Codex TUI."

package/scripts/codex-birth-uninstall.sh

@@ -1,9 +1,16 @@
 #!/usr/bin/env bash
 # codex-birth-uninstall — the inverse of codex-birth-install.sh.
 #
-# The ownership state is the ONLY input. Every removal is licensed per-byte by a digest it
-# recorded, so this inverse can say three different things about every path it published and
-# never guesses at a fourth:
+# WHAT IT REMOVES FROM hooks.json, AND WHAT IT LEAVES (#117). Not the file: ONE `SessionStart`
+# group, the one whose handler commands our launcher, taken out by TEXT SPLICE so every
+# neighbouring declaration comes out byte-for-byte identical. The file itself is removed only
+# when our group was the only group in it and no other event is declared — the case where
+# removing our declaration leaves a document with nothing in it but our own prose. A top-level
+# `description` is removed only when it is entwurf's own; anybody else's is a foreign byte.
+#
+# The ownership state is the ONLY input for the CLOSURE. Every removal there is licensed
+# per-byte by a digest it recorded, so this inverse can say three different things about every
+# path it published and never guesses at a fourth:
 #
 #   * already absent        -> done, not drift.
 #   * bytes match the state -> removed.
@@ -11,6 +18,10 @@
 #                              edited it, and deleting an edit nobody can read back is worse
 #                              than leaving a file behind.
 #
+# The DECLARATION is licensed the same way but by its NORMALIZED digest rather than by file
+# bytes, because a neighbour re-serializing the document (measured: Herdr does) changes every
+# byte of that file and nothing about what entwurf declared.
+#
 # It never reads or writes config.toml, so the vendor's `[hooks.state]` trust record survives
 # this inverse untouched. Removing the declaration does not un-trust it; re-publishing the
 # SAME declaration later reuses the operator's original approval, because the trust identity
@@ -42,6 +53,21 @@ command -v sha256sum >/dev/null 2>&1 || die "sha256sum is required (removal is l
 NODE_BIN="$(command -v node)" || die "node is not on PATH — it parses the ownership state."
 sha_of() { sha256sum -- "$1" | cut -d' ' -f1; }
 
+REPO="$(cd -P -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+DECLARATION_LIB="$REPO/pi-extensions/lib/codex-declaration.js"
+
+# One shared ownership predicate for the file this unit SHARES — see the installer's copy of this
+# comment for why four surfaces had to stop deciding it three different ways.
+owned_path_verdict() { # $1 = path, $2 = file|directory
+  "$NODE_BIN" -e '
+    import(process.argv[1]).then((m) => {
+      const fs = require("node:fs");
+      process.stdout.write(m.classifyOwnedPath(m.statOwnedPath(fs, process.argv[2]), process.getuid(), { kind: process.argv[3] }));
+    }).catch((err) => { process.stderr.write(String(err && err.message ? err.message : err)); process.exit(1); });
+  ' "$DECLARATION_LIB" "$1" "${2:-file}"
+}
+[ -f "$DECLARATION_LIB" ] || die "the declaration leaf is missing: $DECLARATION_LIB — without it this inverse cannot tell entwurf's declaration from a neighbour's. Nothing removed."
+
 # Judged BEFORE anything is removed: a state sitting in a directory somebody else can write
 # is a removal licence somebody else can forge.
 safe_parent() { # $1 = dir, $2 = label
@@ -72,11 +98,21 @@ PLAN="$("$NODE_BIN" -e '
   const path = require("node:path");
   const s = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
   const hex = (v) => typeof v === "string" && /^[0-9a-f]{64}$/.test(v);
-  if (s.schema !== "codex-birth-install-state/v1") throw new Error("foreign state schema " + JSON.stringify(s.schema));
+  if (s.schema !== "codex-birth-install-state/v2") {
+    throw new Error(
+      "the ownership state is " + JSON.stringify(s.schema) + ". This inverse reads codex-birth-install-state/v2, " +
+        "which certifies entwurf\u2019s own declaration; v1 claimed the WHOLE hooks.json and removing on its word " +
+        "would delete a neighbour\u2019s. Run `entwurf install-codex-birth` once to supersede the receipt, then this inverse.",
+    );
+  }
   if (s.status !== "installed" && s.status !== "publishing") throw new Error("unknown status " + JSON.stringify(s.status));
   if (typeof s.hooksFile !== "string" || !s.hooksFile.startsWith("/")) throw new Error("hooksFile is not an absolute path");
   if (typeof s.helperDir !== "string" || !s.helperDir.startsWith("/")) throw new Error("helperDir is not an absolute path");
-  if (!hex(s.hooksSha256)) throw new Error("hooksSha256 is not a sha256 hex digest");
+  const decl = s.declaration;
+  if (decl === null || typeof decl !== "object" || Array.isArray(decl)) throw new Error("the state records no declaration receipt");
+  if (decl.event !== "SessionStart") throw new Error("the recorded declaration event is " + JSON.stringify(decl.event));
+  if (typeof decl.command !== "string" || decl.command.length === 0) throw new Error("the recorded declaration command is not a string");
+  if (!hex(decl.sha256)) throw new Error("the recorded declaration digest is not a sha256 hex digest");
   if (!Array.isArray(s.helperFiles) || s.helperFiles.length === 0) throw new Error("helperFiles is empty");
   // Exactly the closure this unit publishes. Removing on a SHORT inventory would leave a file
   // behind and then delete the directory that held it; a LONG one would license deleting
@@ -101,7 +137,17 @@ PLAN="$("$NODE_BIN" -e '
         (duplicate.length ? "; duplicated " + duplicate.join(", ") : ""),
     );
   }
-  const lines = [["STATUS", s.status, s.unitVersion ?? ""].join("\t"), ["HOOKS", s.hooksSha256, s.hooksFile].join("\t")];
+  // WHO CREATED THE FILE is a removal authority, and the receipt has always recorded it — the
+  // inverse simply never read it (sol B2, 2026-09-18). Anything other than an explicit `false`
+  // reads as "it was already there", which is the safe direction: an old receipt that predates
+  // this field licenses a splice, never a delete.
+  const createdByUs = s.hooksExistedBefore === false;
+  const lines = [
+    ["STATUS", s.status, s.unitVersion ?? ""].join("\t"),
+    ["DECLCMD", "-", decl.command].join("\t"),
+    ["HOOKSCREATED", "-", createdByUs ? "yes" : "no"].join("\t"),
+    ["DECLARATION", decl.sha256, s.hooksFile].join("\t"),
+  ];
   const seen = new Set();
   for (const f of s.helperFiles) {
     if (typeof f?.path !== "string" || f.path.length === 0 || f.path.startsWith("/") || f.path.split("/").includes("..")) {
@@ -118,6 +164,111 @@ PLAN="$("$NODE_BIN" -e '
 Inspect it and remove the unit deliberately. Nothing removed."
 
 DRIFTED=0
+
+# The declaration is not a file this inverse deletes — it is ONE GROUP inside a file it shares.
+# Four verdicts, and only two of them touch a byte: already absent (done, not drift), drifted
+# (named, left exactly as found), sole-owner (the file was ours whole, so the file goes), and
+# shared (our group is spliced out and every neighbouring group comes through byte-for-byte).
+REMOVE_DECLARATION() { # $1 = recorded normalized digest, $2 = hooks.json path
+  local want="$1" target="$2" verdict kind detail tmp owned
+  # THE SAME PREDICATE THE INSTALLER AND THE DOCTOR USE (sol B3, 2026-09-18). This inverse used to
+  # ask only symlink-and-regular, so it would happily rewrite a hooks.json owned by another user or
+  # writable by a group — a file whose next state nothing here can bind. Every non-`ok` verdict is
+  # DRIFT: named, counted, and zero-write.
+  owned="$(owned_path_verdict "$target" file)" || {
+    printf '[codex-birth-uninstall] DRIFT: %s could not be judged for ownership (%s) — leaving it exactly as found.\n' "$target" "$owned" >&2
+    DRIFTED=$((DRIFTED + 1)); return
+  }
+  if [ "$owned" = "missing" ]; then
+    note "already absent: $target"; return
+  fi
+  if [ "$owned" != "ok" ]; then
+    printf '[codex-birth-uninstall] DRIFT: the declaration file %s (%s) — refusing to edit it.\n' "$owned" "$target" >&2
+    DRIFTED=$((DRIFTED + 1)); return
+  fi
+  tmp="$(mktemp)"
+  verdict="$("$NODE_BIN" -e '
+    const fs = require("node:fs");
+    const [, lib, hooksFile, launcherCommand, wantDigest, outTmp, createdByUs] = process.argv;
+    import(lib).then((m) => {
+      const text = fs.readFileSync(hooksFile, "utf8");
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch (err) {
+        return process.stdout.write("DRIFT\t" + hooksFile + " is not readable JSON (" + err.message + ") — this inverse edits only its own group and will not rewrite a document it cannot read");
+      }
+      // The launcher the RECEIPT names, not one rebuilt from paths: the receipt is the authority.
+      const launcher = launcherCommand.replace(/^\x27|\x27$/g, "");
+      const sel = m.selectEntwurfDeclaration(parsed, launcher);
+      if (!sel.ok) {
+        if (sel.code === "declaration-absent") return process.stdout.write("ABSENT\t");
+        return process.stdout.write("DRIFT\t" + sel.code + ": " + sel.detail);
+      }
+      if (sel.digest !== wantDigest) {
+        return process.stdout.write(
+          "DRIFT\tentwurf\u2019s declaration was edited after install (group " + sel.groupIndex + ": live " + sel.digest + ", recorded " + wantDigest + ")",
+        );
+      }
+      // FILE — deleting the whole file — is the ONE verdict that can destroy a byte nobody here
+      // wrote, so it takes three proofs and not one (sol B2, 2026-09-18). "Our group is the last
+      // declaration" was the only one it used to take, and that is true of a file we merely
+      // APPENDED to: `{"description":"foreign","hooks":{"SessionStart":[]}}` has no foreign GROUP,
+      // so after our install the old shape classified it FILE and deleted top-level bytes
+      // belonging to a neighbour.
+      //   1. the receipt says this unit created the file (hooksExistedBefore === false),
+      //   2. nothing but our own two top-level keys is in it, and the description is OURS,
+      //   3. our group is the only declaration, under the only event.
+      // Anything else SPLICES: our group comes out, every other byte stays.
+      const events = Object.keys(parsed.hooks);
+      const topLevel = Object.keys(parsed).sort().join(",");
+      const ourDescription =
+        typeof parsed.description === "string" && parsed.description.startsWith(m.CODEX_BIRTH_DESCRIPTION_PREFIX);
+      const soleDeclaration = sel.foreign.length === 0 && events.length === 1 && events[0] === m.CODEX_BIRTH_EVENT;
+      if (createdByUs === "yes" && soleDeclaration && topLevel === "description,hooks" && ourDescription) {
+        return process.stdout.write("FILE\t");
+      }
+      const want = JSON.parse(text);
+      want.hooks[m.CODEX_BIRTH_EVENT].splice(sel.groupIndex, 1);
+      const description = want.description;
+      let spliced = m.certifySplice(m.removeSessionStartGroup(text, sel.groupIndex), want);
+      if (typeof description === "string" && description.startsWith(m.CODEX_BIRTH_DESCRIPTION_PREFIX)) {
+        delete want.description;
+        spliced = m.certifySplice(m.removeEntwurfDescription(spliced), want);
+      }
+      fs.writeFileSync(outTmp, spliced);
+      process.stdout.write("SPLICE\t" + String(sel.foreign.length));
+    }).catch((err) => {
+      process.stderr.write(err && err.message ? err.message : String(err));
+      process.exit(1);
+    });
+  ' "$DECLARATION_LIB" "$target" "$DECLARATION_COMMAND" "$want" "$tmp" "$HOOKS_CREATED_BY_US" 2>&1)" || {
+    rm -f -- "$tmp"
+    printf '[codex-birth-uninstall] DRIFT: the declaration could not be judged (%s) — leaving %s exactly as found.\n' "$verdict" "$target" >&2
+    DRIFTED=$((DRIFTED + 1)); return
+  }
+  kind="$(printf '%s' "$verdict" | cut -f1)"
+  detail="$(printf '%s' "$verdict" | cut -f2-)"
+  case "$kind" in
+    ABSENT) rm -f -- "$tmp"; note "already absent: entwurf declares nothing in $target" ;;
+    DRIFT)
+      rm -f -- "$tmp"
+      printf '[codex-birth-uninstall] DRIFT: %s — LEFT IN PLACE (%s).\n' "$detail" "$target" >&2
+      DRIFTED=$((DRIFTED + 1))
+      ;;
+    FILE) rm -f -- "$tmp" "$target"; note "removed $target (entwurf was its only declaration)" ;;
+    SPLICE)
+      # The file survives this inverse, so its MODE is one more thing that is not ours to
+      # change: it is carried over from what we found rather than reset to what we publish.
+      chmod "$(stat -c %a -- "$target")" -- "$tmp"
+      cp -- "$tmp" "$target.tmp" && mv -f -- "$target.tmp" "$target"
+      rm -f -- "$tmp"
+      note "removed entwurf's declaration from $target by text splice — $detail foreign group(s) preserved byte-for-byte"
+      ;;
+    *) rm -f -- "$tmp"; die "the declaration reader returned '$verdict'. Nothing else removed." ;;
+  esac
+}
+
 REMOVE_ONE() { # $1 = recorded digest, $2 = absolute path, $3 = label
   local want="$1" target="$2" label="$3" live
   if [ -L "$target" ]; then
@@ -141,10 +292,14 @@ REMOVE_ONE() { # $1 = recorded digest, $2 = absolute path, $3 = label
 }
 
 HELPER_DIR=""
+DECLARATION_COMMAND=""
+HOOKS_CREATED_BY_US="no"
 while IFS="$(printf '\t')" read -r kind digest target; do
   case "$kind" in
     STATUS) note "state: status=$digest unitVersion=$target" ;;
-    HOOKS) REMOVE_ONE "$digest" "$target" "the declaration" ;;
+    DECLCMD) DECLARATION_COMMAND="$target" ;;
+    HOOKSCREATED) HOOKS_CREATED_BY_US="$target" ;;
+    DECLARATION) REMOVE_DECLARATION "$digest" "$target" ;;
     HELPER) REMOVE_ONE "$digest" "$target" "helper member" ;;
     HELPERDIR) HELPER_DIR="$target" ;;
   esac

package/scripts/fixtures/herdr-supply.json

@@ -0,0 +1,29 @@
+{
+	"$comment": "SSOT for the herdr binary this repository has MEASURED against. Nothing else may carry a version or a digest: the CI installer, the sandbox gate's boundary check and the launch-rail document all read or cite this file. Re-measuring a new herdr means running check-herdr-sandbox against it FIRST, then editing this file, then repairing the measured sentences in docs/herdr-launch-rail.md in the same commit — miss one and the gate fails on version mismatch, which is the point.",
+	"version": "0.9.1",
+	"tag": "v0.9.1",
+	"tagCommit": "065ef9d6a531c49fb8bee7e818ef837065b21ee9",
+	"socketProtocol": 22,
+	"measuredOn": "2026-09-17",
+	"measuredArch": "aarch64",
+	"releaseUrlPrefix": "https://github.com/herdrdev/herdr/releases/download",
+	"integrity": {
+		"kind": "github-immutable-release-attestation",
+		"predicateType": "https://in-toto.io/attestation/release/v0.2",
+		"note": "GitHub signs that these digests are this tag's assets. It is NOT a SLSA build provenance authored by herdr and NOT a reproducible-build claim. Corroborate with `gh api repos/herdrdev/herdr/attestations/sha256:<digest>`; `gh attestation verify` 2.97.0 cannot close this predicate and must not be depended on."
+	},
+	"assets": {
+		"x86_64": {
+			"name": "herdr-linux-x86_64",
+			"sha256": "2a02fed16beb651ef006e1d43f048f652ca4dc58ad053cd2d44450563d5c54b7",
+			"executed": false,
+			"executedNote": "pending the first CI run on an x86_64 runner — the digest is pinned, but no cell of this rail has ever run on this binary"
+		},
+		"aarch64": {
+			"name": "herdr-linux-aarch64",
+			"sha256": "f4ccf4de745f2cb9a39a983e9ba3703dad50ec2a58dea83026ceab721bbd8d9e",
+			"executed": true,
+			"executedNote": "the #116 rail was re-measured on this exact binary on 2026-09-17: `check-herdr-sandbox` green, `herdr status client` reports protocol 22 (unchanged from 0.9.0), and `integration status` adds exactly one row — `letta (experimental)` — with every other row byte-identical to 0.9.0. The operator host still runs the 0.9.0 asset at that date; the binary measured here was fetched by digest into a temp dir"
+		}
+	}
+}