fix: recover pathless worktree failures (#3335) (#3351)

This commit is contained in:
Carlos Florêncio
2026-09-03 23:16:44 +00:00
committed by GitHub
parent 34b8eafabf
commit 5d94990f4b
8 changed files with 352 additions and 8 deletions
@@ -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)
@@ -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)
@@ -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", () => {
@@ -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<string | null>(null);
const previousTaskIdRef = useRef<string | null>(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 () => {
@@ -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.
@@ -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.
@@ -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.
@@ -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