feat(agent-spec): add explicit start/resume launch methods

[schickling-assistant]

Problem

Agent Spec currently gives a compact agent one launch payload, so fresh-start and exact-resume intent are encoded inside provider-specific argv. That prevents st2 from validating a closed lifecycle selection policy while keeping provider details outside core.

Goal

Implement the concrete start / resume / launch proposal requested from #124, while preserving legacy top-level command / argv behavior. This PR is a proposal implementation, not a claim that the broader session-store, ownership, or provider boundary in #124 is ratified.

Decisions

• Each declared start or resume method owns one complete, non-empty argv.
• resume may preserve one optional opaque exact provider-native session ID.
• Method availability is declaration-level: core st2 selects the declared default, then an explicitly declared on-unavailable fallback, or refuses the agent.
• Core st2 does not inspect provider transcripts or synthesize provider-native flags; the renderer owns complete method availability.
• Both methods and the policy remain observable in the public agent-spec model, while only the selected argv lowers to exactly one generated pty "agent" successor.
• Explicit methods cannot be mixed with legacy compact launch fields or an authored pty "agent".
• A one-shot catalog reconcile exits nonzero when discovery rejects a declaration. Ordinary execution errors retain their existing collected-error behavior.

Verification

• cargo test -q --offline --workspace --lib --bins --test discovery --test codex_hooks --test hooks --test validate --test up_once_exit -- --test-threads=1
  • 7 agent-spec unit tests
  • 42 discovery tests
  • 214 st2 unit tests
  • 5 Codex-hook tests
  • 11 hook tests
  • 3 one-shot exit tests
  • 38 validation tests
• cargo test --offline -p st2 --test run up_once_ -- --test-threads=1 — 12/12 passed.
• cargo clippy --offline -p agent-spec --all-targets -- -D warnings — passed.
• Mutation control: forcing start selection made the exact-resume selection test fail (start-program versus resume-program), then the unmodified implementation passed.
• Independent held-out behavior proof against add6139 and its exact binary:
  • explicit fresh start: PASS, new native ID
  • explicit exact resume: PASS, only the declared session appended
  • unavailable default without fallback: PASS, exact diagnostic, nonzero exit, no mutation
  • unavailable default with start fallback: PASS
  • legacy single argv: PASS
  • summary: 5 pass, 0 red, zero residual PTYs/processes

Complexity

The change adds parser/raw/public model types, selection lowering, validation diagnostics, tests, and VRS/README documentation. It adds no dependency and no provider-specific runtime logic. The one-shot exit correction adds one typed UpReport signal so declaration errors are not conflated with execution errors.

Concerns

• Older st2 binaries ignore the new KDL blocks and see a method-only declaration as not runnable; binary activation must precede catalog publication.
• Full method payloads duplicate shared adapter axes such as model, effort, persona, mode, and boot contract. Those copies can drift and must be updated together.
• The broader native suite is not a clean baseline on this NixOS host: unchanged tests assume /usr/bin/git and /bin/sleep, one retired-name scan matches the pre-existing phrase “st2 removes”, and one unchanged live-PTY targeted-reconcile test reproducibly reports an unexpected restart. None was changed or skipped in the focused/official gate above.
• Repo-wide format and clippy -D warnings are also not clean baselines; relevant agent-spec Clippy and diff checks pass.

Friction & bottlenecks

• The repository dev shell currently provides Rust 1.94, while locked kdl 6.7.1 requires Rust 1.95. Verification used an already available Rust 1.97 toolchain; no dependency or flake change is included.
• Shared host load was high, so expensive test runs used one build job and one test thread.

Follow-ups

Session stores, receipts, cross-host fencing, ownership transfer, and portable logical session identity remain outside this proposal and belong to the broader work tracked by #124 and #145.

References

References #124.

[schickling]

Closing this draft as superseded by the renderer-first ownership decision consolidated in #124.

The implementation and its tests remain useful evidence: they prove that distinct fresh/resume payloads can be validated and selected without parsing provider transcripts. The API boundary is the part being superseded. Core Agent Spec and the st2 up daemon should remain command-oriented and harness-agnostic; Axe and harness-specific drivers should allocate/resolve session identity and compile one complete launch contract before st2 reconciliation.

Follow-up work is now separated as:

• Define renderer-owned harness sessions and the generic st2 lifecycle boundary #124: renderer-owned logical/native session identity and compilation boundary;
• Expose desired versus observed launch generation for adopted tasks #40: desired-versus-observed launch generation;
• Add an exact generation-fenced recreate operation for one live task #110: exact generation-fenced recreation from the compiled declaration; and
• Model Agent Run identity in task inventory #145: Agent Run identity plus propagation of independently supplied session correlation.

The branch and verification record are intentionally retained. No claim is made that the experiments or implementation were invalid; only that the proposed core API no longer matches the agreed ownership boundary.