kandev/docs/plans/setup-launch-timeout/task-01-unify-setup-timeout-paths.md

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

id	title	status	wave	depends_on	plan	spec
01-unify-setup-timeout-paths	Unify setup timeout paths	done	1		plan.md	../../specs/platform/setup-launch-timeout.md

Task 01: Unify Setup Timeout Paths

Acceptance

• KANDEV_TASK_PREPARATION_TIMEOUT is read once at process start, defaults to 10 minutes, and accepts only positive Go duration values.
• AgentLaunchTimeout is always the resolved setup value plus five minutes.
• Repository, Local, Worktree, Docker, Sprite, and SSH setup paths use the common setup value without changing their failure semantics.

Verification

cd apps/backend && go test ./internal/common/constants ./internal/agent/runtime/lifecycle ./internal/backendapp

Files likely touched

• apps/backend/internal/common/constants/timeouts.go
• apps/backend/internal/common/constants/timeouts_test.go
• apps/backend/internal/backendapp/worktree.go
• apps/backend/internal/agent/runtime/lifecycle/env_preparer_local.go
• apps/backend/internal/agent/runtime/lifecycle/env_preparer_setup_script_test.go
• apps/backend/internal/agent/runtime/lifecycle/container.go
• apps/backend/internal/agent/runtime/lifecycle/container_health_test.go
• apps/backend/internal/agent/runtime/lifecycle/executor_sprites.go
• apps/backend/internal/agent/runtime/lifecycle/executor_sprites_operations.go
• apps/backend/internal/agent/runtime/lifecycle/executor_ssh_scripts.go

Dependencies

None.

Parallelism

sequential. Task 02 consumes the timeout values and lifecycle behavior from this task.

Inputs

• Setup and Launch Timeout spec, especially the default, override, and failure scenarios.
• ADR-2026-08-12-setup-timeout-owns-launch-budget.
• Existing getEnvDuration fallback pattern in internal/agentctl/server/config/config.go.
• Existing detached repository setup handling in internal/worktree/script_message_handler.go.

Output contract

Report the RED tests, resolved timeout policy, each setup path changed, exact verification results, residual risks, and update this task plus plan.md status.

Results

• Added the process-start setup timeout policy with a 10-minute default, positive-duration parsing, and fallback for unset, malformed, zero, or negative values.
• Applied the policy to local/worktree setup scripts, Docker bootstrap preparation, Sprites preparation, and SSH preparation while preserving each executor's existing failure semantics; Docker readiness uses the derived launch budget after the bounded prepare command.
• RED verification first demonstrated that setup-script and container-health operations ignored the configured timeout; the focused regressions now pass.
• Verification: cd apps/backend && go test ./internal/common/constants ./internal/agent/runtime/lifecycle ./internal/backendapp passed with 1,844 tests across 3 packages.
• The environment value is read when the backend process starts. Changing it requires a backend restart, as specified.