45 lines
2.2 KiB
Markdown
45 lines
2.2 KiB
Markdown
---
|
|
status: draft
|
|
system: platform
|
|
created: 2026-08-26
|
|
owners:
|
|
- kandev
|
|
---
|
|
# Agent process exit and stderr drain Requirements
|
|
|
|
## Overview
|
|
|
|
The agent process manager reads child stderr while it supervises process exit.
|
|
The current order waits for stderr EOF before waiting for the child process. A
|
|
long-running agent therefore produces a false stderr-drain warning after one
|
|
second, even though the agent is still starting normally. This requirement keeps
|
|
exit diagnostics complete without making process shutdown unbounded.
|
|
|
|
## Terminology
|
|
|
|
- **stderr drain:** Completion of the generation-specific reader that consumes a
|
|
managed agent process's stderr pipe.
|
|
- **exit publication:** The process-manager state and update event that expose a
|
|
managed agent's final exit result.
|
|
|
|
## Requirements
|
|
|
|
### REQ-PLATFORM-AGENT-PROCESS-EXIT-DRAIN-001: Correct agent process exit drain sequencing
|
|
|
|
**Intent:** Make the stderr-drain warning describe a real post-exit cleanup delay,
|
|
while preserving safe recent-stderr diagnostics and a bounded shutdown path.
|
|
|
|
#### Acceptance criteria
|
|
|
|
- **AC-PLATFORM-AGENT-PROCESS-EXIT-DRAIN-001.1:** When a managed agent remains running longer than the stderr-drain timeout, the process manager shall not emit a stderr-drain timeout warning solely because the process is still running.
|
|
- **AC-PLATFORM-AGENT-PROCESS-EXIT-DRAIN-001.2:** When a managed agent exits, the process manager shall wait for its generation-specific stderr reader, up to the existing bounded timeout, before publishing the final exit result.
|
|
- **AC-PLATFORM-AGENT-PROCESS-EXIT-DRAIN-001.3:** When the stderr reader remains blocked after the managed process exits, the process manager shall emit a warning and continue exit handling within the existing bounded timeout.
|
|
- **AC-PLATFORM-AGENT-PROCESS-EXIT-DRAIN-001.4:** The exit code, error classification, safe recent-stderr content, process-group cleanup, and intentional-stop behavior shall remain unchanged.
|
|
|
|
## Out of scope
|
|
|
|
- Changing the stderr timeout duration.
|
|
- Changing stderr sanitization or the recent-stderr buffer contents.
|
|
- Changing ACP capability filtering, agent authentication, shell grace periods,
|
|
or process-group termination policy.
|