@@ -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.
|
||||
+77
@@ -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.
|
||||
+80
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user