From 5d94990f4b576830c7a9cc2e3a37ba60066c2f9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?= Date: Thu, 3 Sep 2026 23:16:44 +0000 Subject: [PATCH] fix: recover pathless worktree failures (#3335) (#3351) --- .../repository/sqlite/task_environment.go | 8 +- .../sqlite/task_environment_test.go | 34 +++++++ .../session/use-ensure-task-session.test.ts | 54 ++++++++++++ .../session/use-ensure-task-session.ts | 6 +- .../plan.md | 88 +++++++++++++++++++ ...-01-persist-pathless-failed-environment.md | 77 ++++++++++++++++ .../task-02-latch-failed-session-ensure.md | 80 +++++++++++++++++ .../task-launch-failure-recovery.md | 13 ++- 8 files changed, 352 insertions(+), 8 deletions(-) create mode 100644 docs/plans/pathless-worktree-materialization-failure/plan.md create mode 100644 docs/plans/pathless-worktree-materialization-failure/task-01-persist-pathless-failed-environment.md create mode 100644 docs/plans/pathless-worktree-materialization-failure/task-02-latch-failed-session-ensure.md diff --git a/apps/backend/internal/task/repository/sqlite/task_environment.go b/apps/backend/internal/task/repository/sqlite/task_environment.go index 269a3622ba..69099f9d06 100644 --- a/apps/backend/internal/task/repository/sqlite/task_environment.go +++ b/apps/backend/internal/task/repository/sqlite/task_environment.go @@ -160,10 +160,10 @@ func (r *Repository) GetTaskEnvironmentByTaskID(ctx context.Context, taskID stri // UpdateTaskEnvironment updates an existing task environment. // Per-repo rows are not touched; use the TaskEnvironmentRepo CRUD methods. func (r *Repository) UpdateTaskEnvironment(ctx context.Context, env *models.TaskEnvironment) error { - // Refuse to clear workspace_path on a worktree-mode env. Same rationale - // as CreateTaskEnvironment: empty workspace_path produces permanent 503 - // on shell terminal connect. - if env.ExecutorType == string(models.ExecutorTypeWorktree) && env.WorkspacePath == "" && env.Status != models.TaskEnvironmentStatusCreating { + // Creating and failed worktree environments can lack a path because + // materialization can fail before one exists. Reusable states require it. + if env.ExecutorType == string(models.ExecutorTypeWorktree) && env.WorkspacePath == "" && + env.Status != models.TaskEnvironmentStatusCreating && env.Status != models.TaskEnvironmentStatusFailed { return fmt.Errorf("update task environment: worktree-mode env requires workspace_path (id=%s)", env.ID) } tx, err := r.db.BeginTxx(ctx, nil) diff --git a/apps/backend/internal/task/repository/sqlite/task_environment_test.go b/apps/backend/internal/task/repository/sqlite/task_environment_test.go index ecb4c95550..dbce6ec6b4 100644 --- a/apps/backend/internal/task/repository/sqlite/task_environment_test.go +++ b/apps/backend/internal/task/repository/sqlite/task_environment_test.go @@ -527,6 +527,40 @@ func TestUpdateTaskEnvironmentMissingReturnsSentinel(t *testing.T) { } } +// @covers AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.2 +// @covers AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.8 +func TestUpdateTaskEnvironmentAllowsFailedMaterializationWithoutWorkspacePath(t *testing.T) { + repo := newRepoForHealTests(t) + ctx := context.Background() + insertTask(t, repo.db, "task-pathless-failed-materialization") + + environment := &models.TaskEnvironment{ + ID: "env-pathless-failed-materialization", + TaskID: "task-pathless-failed-materialization", + ExecutorType: string(models.ExecutorTypeWorktree), + Status: models.TaskEnvironmentStatusCreating, + MaterializationSessionID: "session-materializer", + } + if err := repo.CreateTaskEnvironment(ctx, environment); err != nil { + t.Fatalf("CreateTaskEnvironment: %v", err) + } + + environment.Status = models.TaskEnvironmentStatusFailed + environment.MaterializationSessionID = "" + if err := repo.UpdateTaskEnvironment(ctx, environment); err != nil { + t.Fatalf("UpdateTaskEnvironment: %v", err) + } + + persisted, err := repo.GetTaskEnvironment(ctx, environment.ID) + if err != nil { + t.Fatalf("GetTaskEnvironment: %v", err) + } + if persisted.Status != models.TaskEnvironmentStatusFailed || + persisted.WorkspacePath != "" || persisted.MaterializationSessionID != "" { + t.Fatalf("persisted environment = %+v, want pathless failed state without materialization claim", persisted) + } +} + func TestTransferTaskEnvironmentMissingReturnsSentinel(t *testing.T) { repo := newRepoForHealTests(t) diff --git a/apps/web/hooks/domains/session/use-ensure-task-session.test.ts b/apps/web/hooks/domains/session/use-ensure-task-session.test.ts index 5b534d863b..977c4f32a1 100644 --- a/apps/web/hooks/domains/session/use-ensure-task-session.test.ts +++ b/apps/web/hooks/domains/session/use-ensure-task-session.test.ts @@ -151,6 +151,60 @@ describe("useEnsureTaskSession", () => { await flushMicrotasks(); expect(result.current.status).toBe("idle"); }); + + // @covers AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.7 + // @covers AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.8 + it("keeps a failed ensure latched until the user retries", async () => { + mockEnsureTaskSession.mockRejectedValue(new Error("workspace is not attachable")); + const { result, rerender } = renderHook(() => useEnsureTaskSession(TASK)); + + await flushMicrotasks(); + expect(mockEnsureTaskSession).toHaveBeenCalledTimes(1); + + mockSessionsResult = { + ...mockSessionsResult, + loadSessions: vi.fn().mockResolvedValue(undefined), + }; + rerender(); + await flushMicrotasks(); + expect(mockEnsureTaskSession).toHaveBeenCalledTimes(1); + + act(() => result.current.retry()); + expect(mockEnsureTaskSession).toHaveBeenCalledTimes(2); + }); +}); + +describe("useEnsureTaskSession failed gate changes", () => { + beforeEach(resetEnsureTaskSessionMocks); + + it("keeps a failed ensure latched when the final-step gate changes", async () => { + mockStoreState = { + userSettings: { preventAutoStartAgentOnOpen: true }, + kanban: { + workflowId: "wf-active", + steps: [ + { id: "step-1", position: 0 }, + { id: "step-done", position: 1 }, + ], + isLoading: false, + }, + kanbanMulti: { snapshots: {} }, + }; + mockEnsureTaskSession.mockRejectedValue(new Error("workspace is not attachable")); + const { rerender } = renderHook(() => + useEnsureTaskSession({ id: "task-1", workflowStepId: "step-1", workflowId: "wf-active" }), + ); + + await flushMicrotasks(); + expect(mockEnsureTaskSession).toHaveBeenCalledTimes(1); + expect(mockEnsureTaskSession).toHaveBeenCalledWith("task-1", undefined); + + mockStoreState.kanban.steps = [{ id: "step-1", position: 0 }]; + rerender(); + await flushMicrotasks(); + + expect(mockEnsureTaskSession).toHaveBeenCalledTimes(1); + }); }); describe("useEnsureTaskSession — task changes", () => { diff --git a/apps/web/hooks/domains/session/use-ensure-task-session.ts b/apps/web/hooks/domains/session/use-ensure-task-session.ts index 6bf0ab1a4e..2f9ee24135 100644 --- a/apps/web/hooks/domains/session/use-ensure-task-session.ts +++ b/apps/web/hooks/domains/session/use-ensure-task-session.ts @@ -163,7 +163,7 @@ export function useEnsureTaskSession( [preventAutoStart, task, kanbanWorkflowId, kanbanSteps, kanbanLoading, snapshots], ); - // Latch keyed by `${taskId}:${retryToken}` so a re-mount on the same task + // Latch keyed by `${taskId}:${retryToken}` so a re-render on the same task // doesn't refire, but switching tasks or calling retry() does. const launchedKeyRef = useRef(null); const previousTaskIdRef = useRef(taskId); @@ -186,7 +186,7 @@ export function useEnsureTaskSession( // branch does NOT latch, so a later steps hydration re-runs the effect // with the correct isFinalStep value (fixes late-hydration auto-start). if (preventAutoStart && !stepsKnown) return; - const key = `${taskId}:${retryToken}:${isFinalStep ? "gated" : "plain"}`; + const key = `${taskId}:${retryToken}`; if (launchedKeyRef.current === key) return; launchedKeyRef.current = key; @@ -209,7 +209,7 @@ export function useEnsureTaskSession( if (cancelled || launchedKeyRef.current !== key) return; setStatus("error"); setError(err instanceof Error ? err : new Error(String(err))); - launchedKeyRef.current = null; + // Keep the key latched. The retry token or a task change owns the next attempt. }); return () => { diff --git a/docs/plans/pathless-worktree-materialization-failure/plan.md b/docs/plans/pathless-worktree-materialization-failure/plan.md new file mode 100644 index 0000000000..82c0a4609d --- /dev/null +++ b/docs/plans/pathless-worktree-materialization-failure/plan.md @@ -0,0 +1,88 @@ +--- +created: 2026-09-03 +status: done +requirements: + - REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001 +system_design: + - ../../specs/tasks/system-design/task-launch-failure-recovery.md +legacy_specs: [] +--- + +# 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 + +- [x] [Task 01: Persist a Pathless Failed Environment](task-01-persist-pathless-failed-environment.md) (`done`) +- [x] [Task 02: Latch Failed Session Ensure Requests](task-02-latch-failed-session-ensure.md) (`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. diff --git a/docs/plans/pathless-worktree-materialization-failure/task-01-persist-pathless-failed-environment.md b/docs/plans/pathless-worktree-materialization-failure/task-01-persist-pathless-failed-environment.md new file mode 100644 index 0000000000..464c2f37cd --- /dev/null +++ b/docs/plans/pathless-worktree-materialization-failure/task-01-persist-pathless-failed-environment.md @@ -0,0 +1,77 @@ +--- +id: "01-persist-pathless-failed-environment" +title: "Persist a Pathless Failed Environment" +status: done +wave: 1 +depends_on: [] +plan: "plan.md" +requirements: + - REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001 +acceptance_criteria: + - AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.2 + - AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.8 +system_design: + - ../../specs/tasks/system-design/task-launch-failure-recovery.md +--- + +# Task 01: Persist a Pathless Failed Environment + +## Summary + +The repository must store a failed worktree environment when materialization creates no path. +Reusable environment states must keep the non-empty path requirement. + +## In scope + +- Add a failing repository regression test for `creating → failed` with an empty path. +- Update the worktree path validation for the `failed` state. +- Reload the row and make sure that the failed state and empty claim persist. + +## Out of scope + +- Changes to worktree creation or Git refresh behavior. +- Automatic removal of the failed environment. +- Changes to ready-state inventory validation. + +## Acceptance + +- `UpdateTaskEnvironment` stores a pathless worktree environment in `failed`. +- The stored materialization-session claim is empty. +- Pathless reusable worktree states remain invalid. + +## Verification + +Run this command from `apps/backend`: + +```bash +go test -tags fts5 ./internal/task/repository/sqlite -run 'TestUpdateTaskEnvironment' -count=1 +``` + +## Files likely touched + +- `apps/backend/internal/task/repository/sqlite/task_environment.go` +- `apps/backend/internal/task/repository/sqlite/task_environment_test.go` + +## Dependencies + +None. + +## Risks + +- The validation must not permit `ready` or `stopped` without a path. + +## Parallelism + +`sequential` + +## Inputs + +- `AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.2` +- `AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.8` +- `docs/specs/tasks/system-design/task-launch-failure-recovery.md` +- Issue `https://github.com/kdlbs/kandev/issues/3335` + +## Results + +- RED: the targeted command failed because `UpdateTaskEnvironment` rejected the pathless `failed` state. +- GREEN: the targeted command passed all five matching repository tests. diff --git a/docs/plans/pathless-worktree-materialization-failure/task-02-latch-failed-session-ensure.md b/docs/plans/pathless-worktree-materialization-failure/task-02-latch-failed-session-ensure.md new file mode 100644 index 0000000000..73ea22be3c --- /dev/null +++ b/docs/plans/pathless-worktree-materialization-failure/task-02-latch-failed-session-ensure.md @@ -0,0 +1,80 @@ +--- +id: "02-latch-failed-session-ensure" +title: "Latch Failed Session Ensure Requests" +status: done +wave: 2 +depends_on: + - "01-persist-pathless-failed-environment" +plan: "plan.md" +requirements: + - REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001 +acceptance_criteria: + - AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.2 + - AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.7 + - AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.8 +system_design: + - ../../specs/tasks/system-design/task-launch-failure-recovery.md +--- + +# Task 02: Latch Failed Session Ensure Requests + +## Summary + +The session hook must keep a failed ensure request latched. +The user can start the next request with the existing Retry control. + +## In scope + +- Add a failing hook test that changes the session-loader identity after an ensure error. +- Keep the request count at one after state-driven rerenders. +- Preserve explicit retry and task-change behavior. + +## Out of scope + +- Changes to the error banner or preview empty-state markup. +- Changes to WebSocket request timeouts. +- Automatic retry or backoff logic. + +## Acceptance + +- Loader identity changes do not repeat a failed `session.ensure` request. +- The existing Retry control starts one new request. +- A task change clears the prior error and permits the new task request. + +## Verification + +Run this command from `apps/web`: + +```bash +pnpm exec vitest run hooks/domains/session/use-ensure-task-session.test.ts +``` + +## Files likely touched + +- `apps/web/hooks/domains/session/use-ensure-task-session.ts` +- `apps/web/hooks/domains/session/use-ensure-task-session.test.ts` + +## Dependencies + +- Task 01 must preserve the terminal environment state that this hook displays. + +## Risks + +- The hook can suppress a valid retry if task changes do not clear its latch. + +## Parallelism + +`sequential` + +## Inputs + +- `AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.2` +- `AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.7` +- `AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001.8` +- `docs/specs/tasks/system-design/task-launch-failure-recovery.md` +- `apps/web/components/task/ensure-session-error.tsx` + +## Results + +- RED: the focused test observed two ensure requests after the loader identity changed. +- GREEN: the full hook test file passed all 22 tests. diff --git a/docs/specs/tasks/system-design/task-launch-failure-recovery.md b/docs/specs/tasks/system-design/task-launch-failure-recovery.md index 4d3210f2c0..c16ad0dd31 100644 --- a/docs/specs/tasks/system-design/task-launch-failure-recovery.md +++ b/docs/specs/tasks/system-design/task-launch-failure-recovery.md @@ -4,7 +4,7 @@ system: tasks requirements: - REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001 created: 2026-08-24 -updated: 2026-09-01 +updated: 2026-09-03 owners: - cfl12 --- @@ -90,6 +90,13 @@ state. A successor execution or prompt remains unchanged. Backend shutdown keeps its existing stopped-session behavior. A shutdown error does not create a durable user-visible launch failure. +The task environment has `creating`, `ready`, `stopped`, and `failed` states. +A worktree path is optional when the state is `creating` or `failed`. +The `ready` and `stopped` states require a non-empty worktree path. + +After a materialization error, the materialization owner clears its claim and +stores the `failed` state. This update remains valid when no worktree path exists. + ## Branch resolution and persistence Local default detection remains a pure helper and returns empty when only a @@ -117,6 +124,10 @@ projection. Desktop actions are inline; mobile actions wrap and branch selection uses the existing mobile picker. Both surfaces use the same action authorization and remain free of horizontal overflow. +`useEnsureTaskSession` keeps one request latch after an error. Store updates and +loader identity changes do not start another request. The Retry control starts +the next request explicitly. A task change clears the prior task's error state. + ## Verification - Test relevant-PR selection, terminal/open precedence, lookup failures, and