kandev/docs/plans/pathless-worktree-materialization-failure/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-09-03	done	REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001	../../specs/tasks/system-design/task-launch-failure-recovery.md

Implementation Plan: Pathless Worktree Materialization Failure

Overview

This change makes a failed worktree materialization terminal and visible. First, the repository stores the failed environment state without a worktree path. Then, the frontend waits for an explicit Retry action before it sends another request.

Scope

In scope

• Permit a worktree environment to enter failed before it has a worktree path.
• Keep the path requirement for reusable ready and stopped environments.
• Keep a failed session.ensure request latched until the user selects Retry.
• Preserve the current task-page and preview error surfaces on desktop and mobile.

Out of scope

• Automatic environment reset after a materialization error.
• Changes to Git refresh policy, timeout values, or error classification.
• Changes to error-card layout, copy, or recovery controls.
• A database migration or a new environment state.

Technical approach

Environment state persistence

Update UpdateTaskEnvironment in apps/backend/internal/task/repository/sqlite/task_environment.go. The validation will permit an empty workspace_path only for creating and failed. The validation will continue to reject other pathless worktree states.

Add a repository regression test in apps/backend/internal/task/repository/sqlite/task_environment_test.go. The test will store creating → failed with an empty path and reload the row.

Explicit frontend retry

Update useEnsureTaskSession in apps/web/hooks/domains/session/use-ensure-task-session.ts. The error branch will retain the current request key. Only retry() or a task change will permit another ensure request.

Add a hook regression test in apps/web/hooks/domains/session/use-ensure-task-session.test.ts. The test will change the session-loader identity after an error. The request count must remain one until the test calls retry().

Tests

• AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.2: the repository test proves that the terminal environment state persists.
• AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.8: the hook test proves that an error remains stable until explicit recovery.
• Existing component tests cover the task-page banner, preview empty state, and Retry control.

E2E tests

The change does not alter layout, touch behavior, scrolling, or navigation. Existing desktop coverage remains in apps/web/e2e/tests/task/launch-failure-recovery.spec.ts. Existing mobile coverage remains in apps/web/e2e/tests/task/mobile-launch-failure-recovery.spec.ts.

The hook regression test covers the changed request-scheduling behavior directly. No new mobile Playwright scenario is necessary for this state-only change.

Work orders

• Task 01: Persist a Pathless Failed Environment (done)
• Task 02: Latch Failed Session Ensure Requests (done)

Verification results

• The targeted SQLite command passed all five matching tests.
• The targeted frontend command passed all 22 hook tests.

Risks

• A broad validation change can permit an attachable state without a path.
• A stale frontend latch can block an explicit retry or a new task request.