Problem
Agent Spec can describe task restart policy and st2 can adopt or recreate a task, but it cannot currently express the session intent of that recreation:
- start with fresh durable harness state; or
- resume one exact prior session state.
Authors can encode provider-specific resume flags directly in command or argv, but that leaves st2 unable to validate the state store, distinguish fresh from resume intent, preserve an exact session identity, or coordinate ownership during a machine move.
This becomes more important if resumable harness state is stored inside the st2 catalog. A catalog-relative store could be synchronized by Fabric and make an explicit cross-machine move possible, provided the old writer is fenced before the new writer resumes.
This issue tracks discovery for the overall contract. It does not ratify syntax, defaults, renderer ownership, or a Fabric protocol.
Design boundary: provider-neutral st2 lifecycle
The core Agent Spec and st2 up should not understand Codex, Claude Code, provider-native flags, or provider session-file layouts.
A higher-level authoring/render layer may understand those details. It should lower them completely into ordinary rendered directories, files, exact argv, and environment. The normalized Agent Spec should expose only provider-neutral lifecycle capabilities and state locations.
Under this boundary:
- the renderer owns provider-specific session discovery, layout, compatibility, and launch translation;
- rendered executables or adapter payloads contain the provider-specific behavior;
- st2 owns generic lifecycle selection, fencing, receipts, ownership, and reconciliation;
- st2 fingerprints the normalized lifecycle inputs it is responsible for; and
- st2 never parses provider transcripts or synthesizes provider-native resume flags.
One non-normative fully expanded render target could resemble:
agent "cos" {
pty "agent" {
state-store "$CATALOG/sessions/cos"
lifecycle {
method "fresh" {
argv "$CATALOG/rendered/cos/fresh"
}
method "resume" {
argv "$CATALOG/rendered/cos/resume"
}
recovery "resume"
}
}
}An alternative normalized shape uses one exact rendered adapter command and passes it a closed generic action such as create, fresh, or resume. The VRS must decide whether lifecycle methods are fully expanded into the normalized Agent Spec or dispatched inside that rendered adapter.
The example is deliberately provider-neutral and non-normative. Field names, nesting, defaults, and method vocabulary remain open.
Desired properties
Separate the identities
The design should distinguish:
- durable Agent Spec / agent identity;
- one runtime task incarnation;
- a stable logical session-state store;
- the provider-native session identifier inside that store; and
- the host that currently owns write authority.
A PTY ID, PID, cwd-based “last session,” or host-qualified placement path must not silently become the portable session identity.
Make storage explicit and portable
Explore a first-class normalized declaration for a catalog-relative session-state store. Open alternatives include a core lifecycle field, a typed Resource referenced by lifecycle policy, or another normalized shape.
The path must remain portable when different machines mount the same logical catalog at different absolute paths. Store identity should not be derived accidentally from host-qualified agent placement.
The store should contain only the resumable provider bundle plus generic receipts. It must not require synchronizing an entire provider home containing credentials, configuration, caches, plugins, logs, or unrelated sessions.
Keep continuity layered
Provider-native transcript resume is useful but must not be the only continuity authority. Durable workspace state, Agent Context, inbox/archive state, and the declared launch contract must remain sufficient to recover when:
- the provider session is missing;
- its format is incompatible with the selected renderer/runtime version;
- the exact native ID is not durable or cannot be resolved; or
- policy explicitly selects a fresh session.
The contract must define whether a failed requested resume refuses, falls back to fresh only with explicit authority, or exposes another state. It must never silently resume a different “last” session.
Fence cross-machine movement
Fabric currently converges files independently; it does not make two concurrent appenders one safe session. Moving a session therefore needs an ownership protocol resembling:
- fence and stop the old writer;
- record the exact provider session ID and a clean/closed store receipt;
- wait for the selected store generation to converge;
- claim write authority on the destination host; and
- resume the exact session there.
Concurrent writers, stale ownership, incomplete synchronization, or a changed store generation must fail closed. Ordinary control-plane restart and adoption of a still-live task remain separate from this move operation.
Preserve sensitive-data and size boundaries
Harness transcripts may contain prompts, tool arguments, command output, source text, and other sensitive data. The VRS must define trust scope, permissions, retention, deletion, and observability before encouraging synchronization.
The implementation and evals must also cover very large or rapidly mutating session files without assuming that every provider persists one small atomic file.
Questions to resolve
- Are lifecycle methods fully expanded into normalized Agent Spec argv/env, or dispatched inside one rendered adapter?
- Is session-store identity a core Agent Spec field or a typed Resource referenced by a core lifecycle field?
- Is the store path explicit, derived from a stable logical key, or both?
- Does automatic task recovery default to fresh, resume, or a separately declared policy?
- Can an operator override the declared recovery mode for one exact lifecycle action?
- What receipt proves that a provider-native session ID and its files are durably resumable?
- Which renderer or adapter owns the mapping to Codex, Claude Code, and other provider-specific layouts?
- What must st2 validate about rendered lifecycle methods before a disruptive action?
- What exact state machine transfers single-writer ownership between hosts?
- Which session data is synchronized, and which provider-home data is categorically excluded?
- How are fork, compaction, retention, archive, and deletion represented?
- What compatibility check binds stored state to its renderer, provider family, and format version?
Evidence and evaluation direction
A paired eval effort should eventually distinguish at least:
- explicit fresh restart creates a new native transcript while durable work continues;
- explicit resume continues the exact native session, not a cwd/name/last-session neighbor;
- missing, partial, stale, and incompatible stores fail according to the ratified policy;
- session creation does not publish a native ID before the resumable bundle is durable;
- simultaneous first launch for one logical store produces at most one authoritative native ID;
- a cross-machine move cannot resume until the old writer is fenced and the exact store generation converges;
- a stale source host cannot write after destination ownership is committed;
- auth/config/cache data is absent from the synchronized bundle; and
- existing fresh-session restorability remains a positive control rather than being deleted or rewritten as historical evidence.
Provider-specific behavior should be tested for at least Codex and Claude Code. Model-free structural controls should carry the normalized rendering, storage, receipt, ownership, and refusal claims; paid harness runs should test the native behavior they alone can prove.
Related work
Problem
Agent Spec can describe task restart policy and st2 can adopt or recreate a task, but it cannot currently express the session intent of that recreation:
Authors can encode provider-specific resume flags directly in
commandorargv, but that leaves st2 unable to validate the state store, distinguish fresh from resume intent, preserve an exact session identity, or coordinate ownership during a machine move.This becomes more important if resumable harness state is stored inside the st2 catalog. A catalog-relative store could be synchronized by Fabric and make an explicit cross-machine move possible, provided the old writer is fenced before the new writer resumes.
This issue tracks discovery for the overall contract. It does not ratify syntax, defaults, renderer ownership, or a Fabric protocol.
Design boundary: provider-neutral st2 lifecycle
The core Agent Spec and
st2 upshould not understand Codex, Claude Code, provider-native flags, or provider session-file layouts.A higher-level authoring/render layer may understand those details. It should lower them completely into ordinary rendered directories, files, exact argv, and environment. The normalized Agent Spec should expose only provider-neutral lifecycle capabilities and state locations.
Under this boundary:
One non-normative fully expanded render target could resemble:
An alternative normalized shape uses one exact rendered adapter command and passes it a closed generic action such as
create,fresh, orresume. The VRS must decide whether lifecycle methods are fully expanded into the normalized Agent Spec or dispatched inside that rendered adapter.The example is deliberately provider-neutral and non-normative. Field names, nesting, defaults, and method vocabulary remain open.
Desired properties
Separate the identities
The design should distinguish:
A PTY ID, PID, cwd-based “last session,” or host-qualified placement path must not silently become the portable session identity.
Make storage explicit and portable
Explore a first-class normalized declaration for a catalog-relative session-state store. Open alternatives include a core lifecycle field, a typed Resource referenced by lifecycle policy, or another normalized shape.
The path must remain portable when different machines mount the same logical catalog at different absolute paths. Store identity should not be derived accidentally from host-qualified agent placement.
The store should contain only the resumable provider bundle plus generic receipts. It must not require synchronizing an entire provider home containing credentials, configuration, caches, plugins, logs, or unrelated sessions.
Keep continuity layered
Provider-native transcript resume is useful but must not be the only continuity authority. Durable workspace state, Agent Context, inbox/archive state, and the declared launch contract must remain sufficient to recover when:
The contract must define whether a failed requested resume refuses, falls back to fresh only with explicit authority, or exposes another state. It must never silently resume a different “last” session.
Fence cross-machine movement
Fabric currently converges files independently; it does not make two concurrent appenders one safe session. Moving a session therefore needs an ownership protocol resembling:
Concurrent writers, stale ownership, incomplete synchronization, or a changed store generation must fail closed. Ordinary control-plane restart and adoption of a still-live task remain separate from this move operation.
Preserve sensitive-data and size boundaries
Harness transcripts may contain prompts, tool arguments, command output, source text, and other sensitive data. The VRS must define trust scope, permissions, retention, deletion, and observability before encouraging synchronization.
The implementation and evals must also cover very large or rapidly mutating session files without assuming that every provider persists one small atomic file.
Questions to resolve
Evidence and evaluation direction
A paired eval effort should eventually distinguish at least:
Provider-specific behavior should be tested for at least Codex and Claude Code. Model-free structural controls should carry the normalized rendering, storage, receipt, ownership, and refusal claims; paid harness runs should test the native behavior they alone can prove.
Related work