Problem
The Agent Spec defines how an exec "name" { … } task starts and is reconciled, but it does not let an author declare how that exact task generation should be shut down or how long graceful shutdown may take.
This issue is for Agent Spec semantics and acceptance evidence. It does not authorize an st2-specific design, implementation, or Agent Spec edit yet.
Proposed semantic contract
Each explicit exec {} declaration should be able to select:
- a first, graceful termination action; and
- a bounded shutdown timeout.
On platforms with POSIX signals, a graceful action could be SIGTERM. On platforms without POSIX signals, the implementation must provide the documented platform-equivalent graceful action or reject an unsupported authored choice before mutating task lifecycle state.
The timeout begins only after the graceful action has been issued to the exact proved process generation. If that generation exits before the timeout, shutdown is complete and no force action occurs. When the timeout expires, the runtime may use a forceful platform action such as SIGKILL only if it re-observes the same exact process generation.
A PID, process handle, or task ID alone is insufficient. Neither the graceful nor forceful action may target:
- a stale PID;
- a reused PID;
- a replacement generation;
- an ambiguous or unreadable runtime observation; or
- an unrelated task.
The runtime must bind both actions to the same declared task ID and stable generation evidence. If that proof changes or becomes incomplete at either action boundary, it must hold/refuse instead of signaling.
Compatibility default
Omitting the new policy must preserve the current effective shutdown behavior unless the current Agent Spec already states a different rule. Before adoption, the proof must record that baseline behavior rather than infer it from one implementation.
The exact field names, nesting, duration grammar, and portable action vocabulary remain open. The current explicit task syntax supports id, command, cwd, keep, tags, and env; this issue does not prescribe whether shutdown policy becomes sibling fields or a nested block.
Observable acceptance cases
A model-free public-behavior matrix should prove:
- Compatibility default: an
exec {} with no authored shutdown policy retains the recorded baseline behavior.
- Graceful success: the configured first action reaches the exact intended generation; an exit before the timeout prevents any force action.
- Bounded escalation: a generation that remains alive receives no force action before the deadline and exactly one force action after expiry.
- Generation recheck: replacing or exiting the process between graceful action and timeout prevents force action against the old PID or the replacement.
- Pre-action race: a generation change between planning and the first action causes hold/refusal and sends no action.
- PID reuse: a new process reusing the numeric PID is never treated as the proved old generation.
- Portable equivalent: a non-POSIX backend demonstrates its documented graceful/force equivalents with the same timing and generation rules.
- Unsupported policy: an unavailable action or invalid timeout fails closed before lifecycle mutation.
- Isolation: shutdown of one task does not act on sibling or unrelated task generations.
- Receipts: status/reporting names the exact task ID, generation evidence, chosen action class, timeout/deadline, whether escalation occurred, and the reason for any hold/refusal.
Tests must avoid relying on PID-only assertions or implementation-private unit tests as conformance evidence.
Separation from st2 implementation
The Agent Spec owns the portable authored meaning and proof cases. st2 may later implement that contract through its exec backend, but st2 field names, operating-system APIs, process-group behavior, and internal timers belong in a separate implementation issue/PR after the Agent Spec shape is accepted.
Non-goals
- changing
pty {} shutdown behavior;
- defining restart/backoff policy;
- selecting exact syntax in this issue;
- implementing or editing the Agent Spec now.
Problem
The Agent Spec defines how an
exec "name" { … }task starts and is reconciled, but it does not let an author declare how that exact task generation should be shut down or how long graceful shutdown may take.This issue is for Agent Spec semantics and acceptance evidence. It does not authorize an st2-specific design, implementation, or Agent Spec edit yet.
Proposed semantic contract
Each explicit
exec {}declaration should be able to select:On platforms with POSIX signals, a graceful action could be
SIGTERM. On platforms without POSIX signals, the implementation must provide the documented platform-equivalent graceful action or reject an unsupported authored choice before mutating task lifecycle state.The timeout begins only after the graceful action has been issued to the exact proved process generation. If that generation exits before the timeout, shutdown is complete and no force action occurs. When the timeout expires, the runtime may use a forceful platform action such as
SIGKILLonly if it re-observes the same exact process generation.A PID, process handle, or task ID alone is insufficient. Neither the graceful nor forceful action may target:
The runtime must bind both actions to the same declared task ID and stable generation evidence. If that proof changes or becomes incomplete at either action boundary, it must hold/refuse instead of signaling.
Compatibility default
Omitting the new policy must preserve the current effective shutdown behavior unless the current Agent Spec already states a different rule. Before adoption, the proof must record that baseline behavior rather than infer it from one implementation.
The exact field names, nesting, duration grammar, and portable action vocabulary remain open. The current explicit task syntax supports
id,command,cwd,keep,tags, andenv; this issue does not prescribe whether shutdown policy becomes sibling fields or a nested block.Observable acceptance cases
A model-free public-behavior matrix should prove:
exec {}with no authored shutdown policy retains the recorded baseline behavior.Tests must avoid relying on PID-only assertions or implementation-private unit tests as conformance evidence.
Separation from st2 implementation
The Agent Spec owns the portable authored meaning and proof cases. st2 may later implement that contract through its exec backend, but st2 field names, operating-system APIs, process-group behavior, and internal timers belong in a separate implementation issue/PR after the Agent Spec shape is accepted.
Non-goals
pty {}shutdown behavior;