3.7 KiB
3.7 KiB
id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design
| id | title | status | wave | depends_on | plan | requirements | acceptance_criteria | system_design | ||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 01-recover-dead-ssh-runtime | Recover from a dead SSH runtime | done | 1 | plan.md |
|
|
|
Task 01: Recover from a Dead SSH Runtime
Summary
Make SSH session resume replace a confirmed-dead remote controller while preserving the task workspace and ACP conversation. Keep indeterminate SSH probe failures fail-closed.
In scope
- Classify remote controller liveness probe outcomes.
- Clear only stale session-runtime metadata after confirmed absence.
- Continue through normal SSH controller creation with the preserved resume token and task workspace.
- Add focused lifecycle regression tests.
Out of scope
- Automatic runtime eviction.
- Provider retry-policy changes.
- Other executor implementations or user-interface changes.
Acceptance
- A completed remote liveness probe that reports the old PID absent permits normal fresh controller creation and retains task-directory metadata.
- An SSH session or transport error aborts resume before controller creation.
- Existing live-controller reattachment behavior remains unchanged.
Verification
cd apps/backend && go test -race ./internal/agent/runtime/lifecycle -run 'Test(SSHExecutorResumeRemoteInstance|ProbeRemoteAgentctlLiveness)$' -count=1
python3 scripts/lint-spec-files.test.py
python3 scripts/lint-spec-files.py --all
git diff --check
Files likely touched
apps/backend/internal/agent/runtime/lifecycle/executor_ssh.goapps/backend/internal/agent/runtime/lifecycle/executor_ssh_operations.goapps/backend/internal/agent/runtime/lifecycle/executor_ssh_stop_resume_test.goapps/backend/internal/agent/runtime/lifecycle/executor_ssh_operations_remote_test.godocs/specs/executors/requirements/ssh-executor.mddocs/specs/executors/system-design/ssh-executor.mddocs/plans/ssh-dead-runtime-resume/plan.mddocs/plans/ssh-dead-runtime-resume/task-01-recover-dead-ssh-runtime.md
Dependencies
None.
Risks
- Misclassifying a transport failure as a dead process can create a competing controller.
Parallelism
sequential
Inputs
- Issue #3330.
REQ-EXECUTORS-SSH-EXECUTOR-001and its SSH recovery criteria.- The recovery section in the SSH executor system design.
- Existing SSH stop, resume, process-probe, and metadata-clear tests.
Results
- RED: the dead-runtime regression failed because
ResumeRemoteInstancereturnedssh resume: agentctl pid 4242 not alive on remoteinstead of yielding to fresh instance creation. - RED: the malformed-PID regression caught an intermediate implementation that treated invalid persisted identity as confirmed process absence.
- GREEN: the SSH resume preflight now treats only a completed remote non-zero process probe as confirmed absence. It closes the stale connection, clears session-runtime metadata, preserves the task directory and resume intent, and returns to normal instance creation.
- SSH connection, session, and malformed-PID failures retain their metadata and fail closed.
cd apps/backend && go test -race ./internal/agent/runtime/lifecycle -run 'Test(SSHExecutorResumeRemoteInstance|ProbeRemoteAgentctlLiveness)$' -count=1passed with 12 tests.cd apps/backend && go test ./internal/agent/runtime/lifecycle -run 'Test(IsRemoteAgentctlAlive|CreateExecution.*RemoteResumePreflight)$' -count=1passed with 4 tests.- Both specification lint commands,
git diff --check, andgofmt -lpassed.