Add fail-closed task inventory

Author: myobie

INVARIANTS.md

@@ -6,6 +6,7 @@ materialization, messaging, DING, or presence must preserve them.
 | Invariant | Guarantee | Proof |
 |---|---|---|
 | **R11 control-plane replacement safety** | Normal stop or SIGKILL of `st2 up`, atomic binary replacement, and control-plane restart leave live PTY and exec agents usable with the same PID and creation identity. The replacement adopts each survivor exactly once, launches only genuinely missing work, and never duplicates a survivor; only explicit teardown kills an agent. | `tests/nomad_survival.rs::normal_stop_and_binary_replacement_adopt_exec_unchanged_without_duplicate`; `tests/nomad_survival.rs::forced_kill_and_binary_replacement_adopt_exec_unchanged_without_duplicate`; `tests/nomad_survival.rs::normal_stop_and_binary_replacement_adopt_pty_unchanged_without_duplicate`; `tests/nomad_survival.rs::forced_kill_and_binary_replacement_adopt_pty_unchanged_without_duplicate`; `tests/nomad_survival.rs::explicit_teardown_kills_exec_but_plain_stop_does_not`; `tests/nomad_survival.rs::explicit_teardown_kills_pty_but_plain_stop_does_not` |
+| **R23 fail-closed diagnostic inventory** | `st2 tasks --json` joins a semantically stable desired-catalog observation to exact PTY and conservatively proven exec generations without writes or reconciliation. Missing roots are positively absent without creation; declaration drift, malformed, unreadable, duplicate, PID-reused, or incomplete evidence is indeterminate, makes the typed envelope incomplete, and exits non-zero. The observational boundary does not serialize catalog writers or authorize cutover. | `src/task_inventory.rs::stable_wire_shape_maps_pty_exec_explicit_default_and_ignores_foreign_host`; `src/task_inventory.rs::complete_missing_runtime_is_absent_but_incomplete_is_indeterminate`; `src/exec_backend.rs::legacy_plain_pid_is_observed_without_rewriting_it`; `src/exec_backend.rs::record_older_than_current_process_generation_cannot_be_promoted`; `tests/task_inventory_cli.rs` |
 | **Transport-decoupled lifecycle** | Each task is isolated from a supervisor/transport process-group or cgroup cascade. | `tests/transport_isolation.rs`; `tests/transport_isolation_macos.rs` |
 | **Clean exec teardown** | Killing an exec task reaps its whole process group. | `tests/exec_backend.rs::exec_kill_reaps_the_whole_process_group_not_just_the_leader` |
 | **Bounded restart diagnostics** | Relaunching an exec task preserves the just-finished log as one prior generation while bounding retained diagnostics to current plus prior. Final retirement removes the PID and both logs. | `tests/exec_backend.rs::exec_restart_reap_keeps_bounded_diagnostics_and_final_remove_cleans_them`; `tests/run.rs::up_once_finally_removes_dead_retired_tasks_without_restarting_them` |

README.md

@@ -250,6 +250,25 @@ For a foreground supervisor on any host:
 st2 up --catalog "$CATALOG" --host <host>
 ```
 
+### Typed task inventory (diagnostic only)
+
+Use the typed inventory instead of parsing `doctor` prose:
+
+```sh
+st2 tasks --catalog "$CATALOG" --host <host> --json
+```
+
+The `st2.task-inventory.v1` envelope joins the selected host's desired PTY and exec tasks to
+read-only runtime evidence. A complete observation exits zero. Catalog parse errors, declaration
+drift during observation, duplicate runtime IDs, timeouts, malformed output, PID reuse, and
+otherwise unprovable generations emit `complete: false` and exit non-zero. Missing runtime rows
+become `absent` only when the corresponding backend observation is complete; uncertainty remains
+`indeterminate`.
+
+Observation never creates a missing PTY or exec state root and never rewrites an existing exec PID
+record. It also does not serialize catalog writers, reconcile tasks, or authorize a control-plane
+cutover. Consumers that require a transactional declaration boundary need a separate protocol.
+
 ### Staged control-plane replacement gate
 
 `st2 up` is a replaceable control plane, not the lifetime owner of an agent. Stopping it normally

docs/vrs/requirements.md

@@ -122,3 +122,14 @@ accepted.
   inspection exposes every Resource binding without interpreting its type or URI.
   Resource-only declaration changes do not alter a task's effective launch
   definition and do not stop, replace, or relaunch healthy work.
+- **R23 Fail-closed task inventory:** One read-only machine command exposes
+  every desired local PTY and exec task by agent identity, task name, runtime
+  id, kind, lifecycle, retirement, desired state, runtime state, PID, creation
+  time, and opaque runtime-generation id. Unknown, duplicate, malformed,
+  unreadable, timed-out, PID-reused, or otherwise unprovable evidence is
+  indeterminate and makes the versioned envelope incomplete and the command
+  unsuccessful; it is never reported as absence. Observation detects semantic
+  declaration drift across its runtime probe, does not create a missing runtime
+  root, and performs no reconciliation, cleanup, lifecycle change, or state
+  rewrite. This diagnostic boundary is not transactionally serialized with
+  catalog writers and is not control-plane cutover authority.

docs/vrs/spec.md

@@ -167,6 +167,28 @@ validate ──► materialize ──► host-local st2 scheduler/reconciler
   lifecycle is the explicit authority to resume ordinary replacement.
   `retired #true` remains the separate explicit teardown path.
 
+- **R23:** `st2 tasks --json` is a read-only diagnostic boundary. It emits one
+  `st2.task-inventory.v1` envelope for the selected host. Rows are sorted by
+  agent, task, and runtime id and cover both PTY and terminal-free exec tasks.
+  `complete=false` plus a non-zero exit is a closed result: a consumer must not
+  turn a missing row into absence. A running row always carries a PID, creation
+  time, and opaque generation id derived from stable backend evidence.
+
+  Discovery runs before and after runtime observation. A semantic declaration
+  change across those passes makes the result incomplete. This detects
+  observed drift but does not serialize catalog writers or claim a
+  transactional snapshot. A missing runtime root is positively empty and
+  remains absent on disk; malformed state, PID reuse, timeouts, duplicate ids,
+  and observer failures are indeterminate. Existing plain-PID exec records are
+  verified against the process start token and record mtime without rewriting
+  them. If that proof is unavailable on a supported OS, the generation remains
+  indeterminate.
+
+  Inventory performs no reconciliation, launch, teardown, cleanup, lifecycle
+  edit, state migration, or catalog write. It does not authorize a staged
+  supervisor replacement; any cutover requiring transactional declaration
+  authority needs a separate protocol.
+
 - **Session registry:** A catalog owns the `pty` registry holding its tasks.
   `<catalog>/pty` is the default; a catalog may declare another so that one host
   can share a single registry across catalogs. Resolution is an exported