Merge pull request #84 from compoundingtech/schickling-assistant/2026-07-30-pty-fleet-contract

test: gate st2 against bounded PTY fleet observation

Author: myobie

flake.lock

@@ -4,13 +4,18 @@
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
     flake-utils.url = "github:numtide/flake-utils";
+    # Packaged PTY fleet-observation gate: the exact `pty list --json` producer revision with
+    # ambiguity-safe PID reads, EPERM handling, and one fleet-wide socket fallback budget.
+    pty.url = "github:compoundingtech/pty/afeb3b6234b7010b7db802fd029766ad17c14219";
+    pty.inputs.nixpkgs.follows = "nixpkgs";
   };
 
   outputs =
     {
       self,
       nixpkgs,
       flake-utils,
+      pty,
     }:
     flake-utils.lib.eachDefaultSystem (
       system:
@@ -118,6 +123,18 @@
           };
         };
 
+        # Narrow sandbox-safe integration gate for the atomic snapshot boundary. The main package
+        # deliberately omits the broad doctor suite because some doctor cases exercise facilities
+        # unavailable in the Nix sandbox. A dedicated target containing exactly one test makes the
+        # gate structurally non-vacuous: a missing target is a cargo error, never a zero-match pass.
+        st2AtomicPtySnapshot = st2.overrideAttrs (_: {
+          pname = "st2-atomic-pty-snapshot-check";
+          cargoTestFlags = [
+            "--test"
+            "atomic_pty_snapshot"
+          ];
+        });
+
         hookSuccessorSource = pkgs.runCommand "st2-hook-successor-source" { } ''
           cp -R ${self} $out
           chmod -R u+w $out
@@ -150,6 +167,62 @@
         # commits on every rebase. The devShell ships rustfmt + clippy for whoever
         # wants them.
         checks.st2 = st2;
+        checks.atomic-pty-snapshot = st2AtomicPtySnapshot;
+
+        # Real producer-consumer contract: st2 consumes `pty list --json` from the exact pty
+        # revision that owns fleet observation. Fake CLI fixtures below still cover malformed
+        # output and a wedged child; this check proves the healthy 0/75/100/500-session path crosses
+        # both packaged binaries within st2's short outer deadline.
+        checks.pty-fleet-contract = pkgs.runCommand "st2-pty-fleet-contract-${version}" {
+          nativeBuildInputs = [
+            pkgs.coreutils
+            pkgs.jq
+            pkgs.nodejs
+            pty.packages.${system}.default
+            st2
+          ];
+        } ''
+          export HOME=$(mktemp -d)
+          catalog=$(mktemp -d)
+          mkdir -p "$catalog/agents/contract/gone"
+          printf '%s\n' \
+            'agent "gone" { host "contract"; retired #true; command "true" }' \
+            > "$catalog/agents/contract/gone/agent.kdl"
+
+          # Run the exact packaged producer's deterministic fault seams. These prove EPERM avoids
+          # socket fallback and hundreds of indefinitely-hung ambiguous probes share one deadline.
+          test_config=$(mktemp --suffix=.mjs)
+          printf '%s\n' 'export default { test: {} }' > "$test_config"
+          node \
+            ${pty.packages.${system}.default}/lib/pty/node_modules/vitest/vitest.mjs \
+            run tests/list-liveness-budget.test.ts \
+            --config "$test_config" \
+            --root ${pty.packages.${system}.default}/lib/pty
+
+          for fleet_size in 0 75 100 500; do
+            root=$(mktemp -d)
+            i=0
+            while test "$i" -lt "$fleet_size"; do
+              session=$(printf 'session-%03d' "$i")
+              : > "$root/$session.sock"
+              printf '%s\n' "$$" > "$root/$session.pid"
+              i=$((i + 1))
+            done
+
+            PTY_ROOT="$root" timeout 2s pty list --json > "pty-$fleet_size.json"
+            jq -e --argjson size "$fleet_size" \
+              'length == $size and all(.status == "running")' \
+              "pty-$fleet_size.json" >/dev/null
+
+            PTY_ROOT="$root" timeout 2s \
+              st2 doctor --catalog "$catalog" --host contract \
+              > "doctor-$fleet_size.out"
+            grep -F 'contract.gone retirement complete' \
+              "doctor-$fleet_size.out" >/dev/null
+          done
+
+          touch $out
+        '';
 
         # Smoke test that the built binary actually runs and its command tree is
         # wired, independent of the in-tree `cargo test`.

flake.nix

@@ -0,0 +1,54 @@
+#![cfg(unix)]
+
+//! Hermetic producer-consumer boundary: a truncated `pty list --json` response is never consumed
+//! as a valid prefix. This is a dedicated single-test target so CI cannot pass on a vacuous libtest
+//! name filter.
+
+use std::fs;
+use std::os::unix::fs::PermissionsExt;
+use std::path::Path;
+use std::process::Command;
+
+fn executable(path: &Path, body: &str) {
+    fs::write(path, body).unwrap();
+    fs::set_permissions(path, fs::Permissions::from_mode(0o755)).unwrap();
+}
+
+#[test]
+fn doctor_rejects_a_partial_pty_snapshot_atomically() {
+    let tmp = tempfile::tempdir().unwrap();
+    let catalog = tmp.path().join("catalog");
+    let declaration = catalog.join("agents/h/gone/agent.kdl");
+    let bin = tmp.path().join("bin");
+    fs::create_dir_all(declaration.parent().unwrap()).unwrap();
+    fs::create_dir_all(&bin).unwrap();
+    fs::write(
+        declaration,
+        "agent \"gone\" { host \"h\"; retired #true; command \"true\" }\n",
+    )
+    .unwrap();
+    executable(
+        &bin.join("pty"),
+        "#!/bin/sh\nprintf '[{\"name\":\"h.gone.agent\",\"status\":\"running\"},'\n",
+    );
+
+    let output = Command::new(env!("CARGO_BIN_EXE_st2"))
+        .arg("doctor")
+        .arg("--catalog")
+        .arg(&catalog)
+        .args(["--host", "h"])
+        .env("PATH", &bin)
+        .env("XDG_STATE_HOME", tmp.path().join("state"))
+        .env("PTY_ROOT", tmp.path().join("pty"))
+        .output()
+        .unwrap();
+
+    assert!(!output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains("✗ task runtime readable"), "{stdout}");
+    assert!(stdout.contains("parsing `pty list --json`"), "{stdout}");
+    assert!(
+        !stdout.contains("retirement complete"),
+        "a valid prefix must never be consumed as a partial snapshot:\n{stdout}"
+    );
+}