Merge pull request #56 from compoundingtech/schickling-assistant/2026-07-29-nix-build-identity

fix: unify hook receipts with build identity

Author: schickling

README.md

@@ -21,7 +21,8 @@ Prerequisites:
 - Rust and Cargo;
 - `pty` on `PATH`;
 - at least one supported harness on `PATH`: `codex` or `claude`;
-- Git when a declaration materializes workspace files.
+- Git when a declaration materializes workspace files;
+- Bash and `jq` on `PATH` when lifecycle hooks are enabled.
 
 From a checkout:
 
@@ -44,15 +45,18 @@ location.
 
 Lifecycle hooks are installed only by the explicit `st2 hooks install` command. The installer
 publishes an immutable content-addressed set, then atomically selects it with a receipt. `st2 up`
-verifies that receipt for Codex launches; any local workspace render that actually references
-`$ST_HOOKS` verifies it before writing. Hook-free materialization does not require an installed
-set. These checks never create, refresh, or rewrite hooks. An intentional rollback to an older set
-requires `st2 hooks install --allow-downgrade`.
+verifies its own immutable set for Codex launches; any local workspace render that actually
+references `$ST_HOOKS` verifies that set before writing. Selecting a successor does not invalidate
+an older running binary's installed set during cutover. Hook-free materialization does not require
+an installed set. These checks never create, refresh, or rewrite hooks. To select this binary's
+exact hook set when the installed and candidate builds are older or cannot be ordered, use `st2
+hooks install --replace`. `st2 hooks verify-own` is the read-only cutover probe for an installed
+binary that may no longer be selected.
 
 `ST_HOOKS` overrides the machine-local hook root for installation, verification, and managed tasks.
-During materialization, hook commands such as `$ST_HOOKS/codex-stop.sh` resolve to the selected
-immutable set, so rendered settings are versioned without embedding a machine-specific root in the
-declaration.
+During materialization, hook commands such as `$ST_HOOKS/codex-stop.sh` resolve to the invoking
+binary's immutable set, so rendered settings are versioned without embedding a machine-specific
+root in the declaration.
 
 The hooks have a small operational purpose: session-start restores durable context and exposes the
 current inbox; pre-compact preserves a recovery breadcrumb when no context was written; stop and

build.rs

@@ -4,9 +4,6 @@
 //! NixStamp can never be overridden by this (see src/version.rs). A hermetic Nix
 //! build has no `.git`, so this yields nothing there and the NixStamp is used.
 //!
-//! A full revision and commit timestamp are also exposed privately to the
-//! receipt-bearing lifecycle-hook installer. They do not affect the shared
-//! human/machine version contract.
 use std::process::Command;
 
 fn git(args: &[&str]) -> Option<String> {
@@ -29,14 +26,6 @@ fn main() {
         let stamp =
             format!(r#"{{"type":"local","rev":"{rev}","commitTs":{commit_ts},"dirty":{dirty}}}"#);
         println!("cargo:rustc-env=ST2_BUILD_STAMP_LOCAL={stamp}");
-        println!(
-            "cargo:rustc-env=ST2_GIT_SHA_FULL={}",
-            git(&["rev-parse", "HEAD"]).unwrap_or(rev)
-        );
-        println!("cargo:rustc-env=ST2_GIT_COMMIT_UNIX={commit_ts}");
-    } else {
-        println!("cargo:rustc-env=ST2_GIT_SHA_FULL=unknown");
-        println!("cargo:rustc-env=ST2_GIT_COMMIT_UNIX=0");
     }
     // Rebuild the stamp when HEAD moves or the working tree changes (dirty flag).
     println!("cargo:rerun-if-changed=.git/HEAD");

docs/vrs/requirements.md

@@ -55,7 +55,13 @@ accepted.
   complete effective launch definition, including environment and supported
   launch fields.
 - **R07 Verified hooks:** Required hook content is installed explicitly and
-  verified before a rendered agent depends on it.
+  verified before a rendered agent depends on it. The selected receipt carries
+  the binary's real source identity regardless of build system. Ordered
+  upgrades are automatic; selecting an older, unorderable, or unreadable exact
+  hook set requires explicit replacement authority. A selection change does not
+  invalidate another running binary's previously installed immutable set. Hook
+  interpreters and runtime dependencies are portable and explicit on every
+  supported package environment.
 - **R11 Control-plane replacement safety:** Stopping or killing `st2 up` must
   not stop, restart, or replace any agent it launched. st2 can be reinstalled
   and restarted while running agents continue unchanged; the replacement

docs/vrs/spec.md

@@ -46,7 +46,17 @@ validate ──► materialize ──► host-local st2 scheduler/reconciler
 - **R06:** st2 passes the complete effective task definition to the underlying
   launcher so manual and supervised restarts are equivalent.
 - **R07:** Hook bundles are explicit, content-addressed, installed separately,
-  and verified before materialization references them.
+  and verified before materialization references them. Their receipts use the
+  same resolved build identity as the binary's version surfaces for both
+  hermetic package builds and source builds. Installation automatically accepts
+  an ordered upgrade; `--replace` is the explicit exact-state authority for a
+  downgrade, an unorderable build, or an unreadable receipt. Shipped hooks
+  resolve Bash through `PATH`; the Nix package executes their integration gate
+  with Bash and `jq` declared. Runtime materialization verifies the invoking
+  binary's own content-addressed set, independent of which installed binary the
+  receipt currently selects, so old and new supervisors can overlap during
+  cutover. `hooks verify-own` exposes that read-only capability to package
+  activation tooling.
 - **R11:** `st2 up` is a replaceable control plane, not the lifetime owner of
   its agents. Normal exit, forced termination, binary replacement, and restart
   leave every running agent PID and creation identity unchanged. The new

flake.nix

@@ -28,12 +28,15 @@
         # reader) — `src/version.rs` reads it via `option_env!("CLI_BUILD_STAMP")`.
         # `self.shortRev`/`lastModified` are absent only for a dirty tree, where
         # `dirtyShortRev` and the working-tree mtime stand in and `dirty` is true.
+        sourceRev = self.shortRev or self.dirtyShortRev or "unknown";
+        sourceCommitUnix = self.lastModified or 0;
+        sourceDirty = !(self ? rev);
         buildStamp = builtins.toJSON {
           type = "nix";
           inherit version;
-          rev = self.shortRev or self.dirtyShortRev or "unknown";
-          commitTs = self.lastModified or 0;
-          dirty = !(self ? rev);
+          rev = sourceRev;
+          commitTs = sourceCommitUnix;
+          dirty = sourceDirty;
         };
 
         completionShells = [
@@ -59,11 +62,15 @@
           # src/version.rs). A derivation env var change rebuilds the crate.
           CLI_BUILD_STAMP = buildStamp;
 
-          # `git` is present for the tests below (they init throwaway repos);
-          # `installShellFiles` provides `installShellCompletion`.
+          # The hook integration test executes the shipped Bash scripts with
+          # their real jq dependency. `git` is present for tests that initialize
+          # throwaway repositories; `installShellFiles` provides
+          # `installShellCompletion`.
           nativeBuildInputs = [
+            pkgs.bash
             pkgs.git
             pkgs.installShellFiles
+            pkgs.jq
           ];
 
           # Completions are generated by the binary we just built (never
@@ -80,19 +87,18 @@
               --fish completions-fish
           '';
 
-          # Run only the hermetic **unit** tests (`--lib --bins`). The integration
-          # tests in `tests/*.rs` each assume a real environment the Nix build
-          # sandbox deliberately lacks — `/bin/bash` + `jq` (the shipped Codex
-          # hooks), `/usr/bin/git` on a hardcoded `PATH` (materialize's
-          # git-worktree safety check), and live PTY backends or a systemd
-          # `--user` manager (the survival + render-neutrality gates). Chasing
-          # those with per-test skips is unbounded as the suite grows, so they run
-          # on native CI (real runner) while the flake proves the package here:
-          # it builds, its ~150 pure unit tests pass, and `--help`/completions
-          # smoke-test the wired binary below.
+          # Run the hermetic unit tests plus the real lifecycle-hook integration
+          # test. The remaining integration tests assume facilities the Nix build
+          # sandbox deliberately lacks: `/usr/bin/git` on a hardcoded `PATH`,
+          # live PTY backends, or a systemd `--user` manager. They remain native
+          # gates, while the flake proves that its own packaged hooks execute.
           cargoTestFlags = [
             "--lib"
             "--bins"
+            "--test"
+            "codex_hooks"
+            "--test"
+            "hooks"
           ];
 
           # A few unit tests write under $HOME; the sandbox HOME is not writable.
@@ -105,6 +111,24 @@
             mainProgram = "st2";
           };
         };
+
+        hookSuccessorSource = pkgs.runCommand "st2-hook-successor-source" { } ''
+          cp -R ${self} $out
+          chmod -R u+w $out
+          printf '\n# Nix hook replacement acceptance probe.\n' >> $out/hooks/codex-stop.sh
+        '';
+
+        st2HookSuccessor = st2.overrideAttrs (_: {
+          pname = "st2-hook-successor";
+          src = hookSuccessorSource;
+          CLI_BUILD_STAMP = builtins.toJSON {
+            type = "nix";
+            inherit version;
+            rev = "hook-successor";
+            commitTs = sourceCommitUnix;
+            dirty = false;
+          };
+        });
       in
       {
         packages.st2 = st2;
@@ -147,6 +171,62 @@
           touch $out
         '';
 
+        # End-to-end receipt proof across two real Nix-built binaries. The
+        # synthetic successor changes embedded hook bytes while deliberately
+        # retaining the same source timestamp: replacement must be explicit,
+        # and must not be mislabeled as a downgrade.
+        checks.hooks-replacement = pkgs.runCommand "st2-hooks-replacement-${version}" {
+          nativeBuildInputs = [
+            pkgs.git
+            pkgs.jq
+          ];
+        } ''
+          export HOME=$(mktemp -d)
+          export ST_HOOKS=$HOME/hooks
+
+          ${st2}/bin/st2 hooks install
+          original_dir=$(jq -r '.directory' "$ST_HOOKS/current.json")
+          jq -e \
+            --arg rev ${pkgs.lib.escapeShellArg sourceRev} \
+            --argjson commit ${toString sourceCommitUnix} \
+            --argjson dirty ${builtins.toJSON sourceDirty} \
+            '.st2GitSha == $rev and .sourceCommitUnix == $commit and .sourceDirty == $dirty' \
+            "$ST_HOOKS/current.json" >/dev/null
+
+          if ${st2HookSuccessor}/bin/st2 hooks install 2>replacement.err; then
+            echo "same-order hook replacement unexpectedly succeeded" >&2
+            exit 1
+          fi
+          grep -F -- '--replace' replacement.err >/dev/null
+
+          ${st2HookSuccessor}/bin/st2 hooks install --replace
+          ${st2HookSuccessor}/bin/st2 hooks verify
+          ${st2}/bin/st2 hooks verify-own
+          jq -e \
+            --argjson commit ${toString sourceCommitUnix} \
+            '.st2GitSha == "hook-successor" and .sourceCommitUnix == $commit and .sourceDirty == false' \
+            "$ST_HOOKS/current.json" >/dev/null
+
+          # The old binary keeps using its own previously installed immutable
+          # set even though the successor is now selected globally.
+          mkdir -p "$HOME/catalog/agents/h/worker" "$HOME/workspace"
+          git init -q "$HOME/workspace"
+          cat > "$HOME/catalog/agents/h/worker/agent.kdl" <<EOF
+          agent "worker" {
+            host "h"
+            workspace "$HOME/workspace"
+            command "exec codex"
+            render { file "hook-path" "\$ST_HOOKS/codex-stop.sh" }
+          }
+          EOF
+          ${st2}/bin/st2 up "$HOME/catalog" --host h --materialize-only
+          grep -Fx \
+            "$ST_HOOKS/$original_dir/codex-stop.sh" \
+            "$HOME/workspace/hook-path" >/dev/null
+
+          touch $out
+        '';
+
         devShells.default = pkgs.mkShell {
           packages = [
             pkgs.cargo

hooks/claude-pre-compact.sh

@@ -1,9 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # The persistence behavior is harness-agnostic. Keep this entrypoint trivial and fail-open so a
 # parse/runtime error in the implementation can never block Claude compaction.
 
 impl="$(dirname "$0")/codex-pre-compact.sh"
 if [[ -r "$impl" ]]; then
-  /bin/bash "$impl" "$@" || true
+  bash "$impl" "$@" || true
 fi
 exit 0

hooks/claude-session-start.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # st2 Claude SessionStart hook. Claude treats exit 2 + stderr as a model-visible reminder; the hook
 # restores fresh durable context before that reminder. Missing state remains a valid cold start.
 

hooks/claude-stop-failure.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # st2 Claude StopFailure hook: surface infrastructure wedges through presence and, when declared,
 # the agent's supervisor inbox. Fail-open; lifecycle reporting must never wedge the harness.
 

hooks/codex-pre-compact.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # st2 Codex PreCompact hook. Never block compaction. If the agent has not captured any durable
 # working state, write a reconstruction stub; never overwrite non-whitespace state.
 

hooks/codex-session-start.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # st2 Codex SessionStart hook: restore fresh working state, expose the unread inbox, and remind the
 # model to complete its boot ritual. Fail-open: a missing dependency never prevents Codex startup.