Harden PTY resource target observation

agent-identity: mbp2025.direct.omp.5tek2r48
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.0.11
agent-runtime: OMP 18.0.11
tooling-profile: dotfiles@4cc7b25

Author: schickling-assistant

docs/vrs/.decisions/0017-task-resource-targets-are-strict-observations.md

@@ -36,11 +36,12 @@ process-generation fence. One exact unified `0::` entry preserved its
 slash-prefixed path, including spaces and colons, while absent, duplicate,
 relative, repeated-separator, trailing-separator, and traversal-capable shapes
 were rejected. Stable start-token observations admitted the candidate target.
-A deterministic PTY regression replaced the PID generation between the first
-backend snapshot and start-token capture; the second snapshot's changed
-creation generation rejected that token. A token mismatch before target read,
-a token change after it, and process exit each emitted only a bounded
-unavailable result and never the candidate locator.
+A deterministic PTY regression replaced the PID generation between the
+registry snapshot and start-token capture; the socket-backed stats row's
+changed creation generation rejected that token. A two-live-task fixture
+proved one unscoped stats snapshot serves the whole inventory. A token mismatch
+before target read, a token change after it, and process exit each emitted only
+a bounded unavailable result and never the candidate locator.
 
 A live Darwin exec observation joined the current PID as
 `darwinProcessTree.rootPid` without rewriting its retained generation record,
@@ -70,13 +71,14 @@ Unavailable reasons are exactly `notRunning`, `runtimeIndeterminate`,
 
 On Linux, st2 reads exactly one unified `0::<path>` entry from the observed
 process's `/proc/<pid>/cgroup`. Exec compares the target fence to the token in
-its generation record. PTY captures a token after its first backend snapshot
-and admits it only after a second snapshot confirms the same task, running
-state, PID, and backend creation generation; that admitted token then fences
-the target read. A missing, exited, or recycled process never publishes the
-candidate locator. Darwin fences the current process in the same way before
-exposing its PID as a best-effort tree root. All targets are rediscovered on
-each inventory command.
+its generation record. PTY captures each candidate daemon token after the
+registry snapshot, then takes one unscoped, socket-backed `pty stats --json`
+snapshot for the entire inventory. A candidate is admitted only when its named
+live stats row reports the same daemon PID and creation generation and a second
+token read is unchanged; that admitted token then fences the target read. A
+missing, exited, or recycled process never publishes the candidate locator.
+Darwin fences the current process in the same way before exposing its PID as a
+best-effort tree root. All targets are rediscovered on each inventory command.
 
 Runtime ID remains stable task identity. PID, creation time, generation ID,
 cgroup path, root PID, unit, and incarnation remain observation locators only.

docs/vrs/.experiments/2026-09-05-task-resource-target-observation.md

@@ -16,9 +16,12 @@ The inventory resource-target boundary was split into two narrow operations:
 strict parsing of the Linux `/proc/<pid>/cgroup` payload and a process-start
 fence around target acquisition. Deterministic unit fixtures supplied stable,
 changed, and disappearing start tokens around a candidate target. A PTY fixture
-then reused the same numeric PID with a different backend creation generation
-between the first snapshot and token capture; a confirming second snapshot
-tested that exact pre-fence window. Parser
+then reused the same numeric daemon PID with a different creation generation
+between the registry snapshot and token capture; the live socket-backed stats
+row tested that exact pre-fence window. A second fixture gave one inventory two
+live candidates, recorded the single unscoped stats invocation, and changed
+target proof from unavailable to available without changing either PTY
+generation ID. Parser
 fixtures covered a unified-only record, a hybrid record, root membership,
 spaces and colons, duplicate unified entries, missing v2 entries, malformed
 fields, carriage returns, repeated/trailing separators, and traversal
@@ -37,7 +40,8 @@ Focused commands:
 
 ```sh
 nix develop -c cargo test --lib task_inventory::tests
-nix develop -c cargo test --lib run::tests::pty_pid_reuse_between_snapshot_and_start_token_capture_is_rejected
+nix develop -c cargo test --lib run::tests::pty_stats_rejects_pid_reuse_between_registry_snapshot_and_start_token_capture
+nix develop -c cargo test --lib run::tests::pty_resource_observation_uses_one_stats_snapshot_and_preserves_generation_id
 nix develop -c cargo test --test task_inventory_cli
 ```
 
@@ -48,7 +52,8 @@ nix develop -c cargo test --test task_inventory_cli
 | Unified cgroup parser | Preserved one exact slash-prefixed `0::` path, including spaces and colons; rejected ambiguous, absent, relative, or traversal-capable shapes. |
 | Stable start token | Published the candidate resource target. |
 | Changed start token | Published only `unavailable/generationChanged`; the candidate locator was discarded. |
-| PTY reuse before token capture | A second backend snapshot observed the changed creation generation and returned `unavailable/generationChanged`; the replacement token was never admitted. |
+| PTY reuse before token capture | The socket-backed stats row observed the changed creation generation and returned `unavailable/generationChanged`; the replacement token was never admitted. |
+| PTY stats fan-out and identity | Two live candidates used one `pty stats --json` invocation with no session argument; transient target-proof failure then success preserved each PTY generation ID. |
 | Process disappeared during read | Published only `unavailable/processUnavailable`; the candidate locator was discarded. |
 | Stable target read failed | Published the bounded degraded reason `unavailable/cgroupV2Unavailable`. |
 | Live Darwin process | Published `{"type":"darwinProcessTree","rootPid":<current-pid>}` for the proven current generation. |
@@ -57,8 +62,9 @@ nix develop -c cargo test --test task_inventory_cli
 
 ## Conclusion
 
-A resource target can remain a pure observation. PTY first captures the kernel
-token and then proves the backend generation unchanged before admitting it;
+A resource target can remain a pure observation. PTY captures the daemon token,
+then uses one socket-backed stats snapshot to prove every candidate's live
+daemon PID and creation generation before rereading and admitting the token;
 the token subsequently fences the target read. This prevents publication
 across the measured pre-fence reuse, exit, and generation-change races. Strict
 cgroup parsing supplies the exact kernel locator without scope-name

docs/vrs/requirements.md

@@ -291,13 +291,15 @@ accepted.
   exposes its exact unified cgroup-v2 path read from that process's
   `/proc/<pid>/cgroup`; unit and scope names are not locators. A proved live
   Darwin generation exposes its PID as a best-effort process-tree root. For
-  PTY, the kernel start token captured after the first backend snapshot becomes
-  admissible only when a second backend snapshot confirms the same PID and
-  creation generation. That token is then sampled around target observation,
-  as it is for exec. A changed, recycled, or exited process is never associated
-  with the target.
-  Non-running, indeterminate, degraded, and unsupported observations expose a bounded
-  explicit unavailable reason rather than a nullable or guessed locator.
+  PTY, st2 captures the candidate daemon's kernel start token, takes one
+  socket-backed `pty stats --json` snapshot for all candidates, and admits the
+  token only when the named live session reports the same daemon PID and
+  creation generation and a second token read is unchanged. That token fences
+  target observation, as the recorded token does for exec, but its transient
+  availability never changes the PTY generation ID. A changed, recycled, or
+  exited process is never associated with the target.
+  Non-running, indeterminate, degraded, and unsupported observations expose a
+  bounded explicit unavailable reason rather than a nullable or guessed locator.
   Resource-target unavailability is itself a complete observation and does not
   turn a trustworthy task inventory into an incomplete one.
   A proved non-routable retired subject has a null bus address without making

docs/vrs/spec.md

@@ -852,15 +852,18 @@ validate ──► materialize ──► host-local st2 scheduler/reconciler
   with no unified entry. It does not derive the path from a systemd unit,
   scope name, runtime ID, or naming convention.
 
-  PTY observation captures a kernel process-start token after its first backend
-  snapshot, then takes a second backend snapshot and admits that token only
-  when task ID, running state, PID, and backend creation time still identify
-  the same generation. Resource observation reads the token again before and
-  after reading the target. Exec compares those two reads directly to the start
-  token already bound into its generation record. A missing process is
-  `processUnavailable`; a backend or token mismatch, or a token that changes
-  across the read, is `generationChanged`. Neither result exposes the candidate
-  path or root PID. Darwin uses the same fence around its root PID. A bounded
+  PTY observation captures each candidate daemon's kernel process-start token
+  after the registry snapshot, then executes `pty stats --json` exactly once
+  without a session argument. The returned array is socket-backed live
+  evidence for every candidate. A token is admitted only when exactly one
+  stats row has the task name, `process.alive=true`, the same `daemon.pid`, and
+  the same `createdAt`, and a second kernel-token read equals the first.
+  Resource observation then reads the token before and after the target. Exec
+  compares those target-fence reads directly to the token already bound into
+  its generation record. A missing process is `processUnavailable`; a stats or
+  token mismatch, or a token that changes across a read, is
+  `generationChanged`. Neither result exposes the candidate path or root PID.
+  Darwin uses the same fence around its root PID. A bounded
   `unavailable` target is a truthful successful field and does not by itself
   make the envelope incomplete. Locators are sampled afresh on each command:
   st2 stores no scope registry, performs no resource sampling, and gives no