kandev/docs/plans/ssh-workspace-preparation/task-01-ssh-workspace-lifecycle.md

id, title, status, wave, depends_on, plan, spec

id	title	status	wave	depends_on	plan	spec
01-ssh-workspace-lifecycle	SSH workspace lifecycle	done	1		plan.md	../../specs/executors/requirements/ssh-executor.md

Task 01: SSH Workspace Lifecycle

Acceptance

• An ordinary provider-backed SSH task resolves and runs the default or stored prepare script on the target before agentctl, then starts the controller with the verified primary checkout as its workspace.
• Preparation failure, timeout, cancellation, missing checkout, or conflicting origin fails closed without a controller/forwarder leak; a matching existing checkout preserves local work.
• Terminal archive/delete runs the stored cleanup script before controller teardown; ordinary Stop and backend restart skip cleanup, and cleanup failure remains best-effort.
• Existing remote-contribution identity, exact-SHA, upstream, credential-redaction, and resume guarantees remain intact.

Verification

cd apps/backend
rtk go test ./internal/agent/runtime/lifecycle -run 'Test.*SSH.*(Prepare|Workspace|Cleanup|Contribution|Origin|Checkout)'

Files likely touched

• apps/backend/internal/agent/runtime/lifecycle/default_scripts.go
• apps/backend/internal/agent/runtime/lifecycle/default_scripts_test.go
• apps/backend/internal/agent/runtime/lifecycle/executor_ssh.go
• apps/backend/internal/agent/runtime/lifecycle/executor_ssh_operations.go
• apps/backend/internal/agent/runtime/lifecycle/executor_ssh_remote_contribution.go
• apps/backend/internal/agent/runtime/lifecycle/executor_ssh_connection_test.go
• apps/backend/internal/agent/runtime/lifecycle/executor_ssh_scripts.go (new)
• apps/backend/internal/agent/runtime/lifecycle/executor_ssh_scripts_test.go (new)

Dependencies

None.

Parallelism

Sequential. Preparation and cleanup share SSH lifecycle ordering, metadata, command execution, and security tests.

Inputs

• SSH spec sections Workspace lifecycle on the remote, Telemetry & errors, and the new preparation/cleanup scenarios.
• Sprites patterns in executor_sprites_operations.go, executor_sprites.go, and executor_sprites_lifecycle.go.
• Existing SSH contribution materialization and credential-stdin handling.

Risks

• Never put environment secrets into remote argv, persisted metadata, progress output, or returned errors.
• Keep prepare/cleanup environment access distinct from the existing narrow agent-subprocess allowlist; cache cleanup values only in live SSH session state and reconstruct them on resume.
• Do not reset a reused task branch or delete local/untracked work.
• Do not allow a custom prepare script to start a duplicate controller through agentctl placeholders.
• Preserve SSH client/forwarder cleanup on every failure edge.

Output contract

Report root-cause path replaced, files changed, RED/GREEN evidence, exact targeted test result, credential and cleanup boundaries, blockers/risks, and synchronized task/plan status.

Results

• Implemented the SSH default prepare script and pre-agentctl lifecycle ordering.
• Added workspace/repository/script-engine resolution, fail-closed checkout verification, bounded/redacted prepare output, and terminal cleanup execution.
• Added explicit archive/delete tree stop reasons so handoff teardown invokes SSH cleanup before the later durable cascade stop.
• Targeted SSH lifecycle tests: 23 passed; full lifecycle package: 1,141 passed; race-focused SSH run: 47 passed.