kandev/docs/plans/worktree-refresh-fail-closed/task-03-project-refresh-launch-failures.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
03-project-refresh-launch-failures	Project refresh launch failures	done	3	02-reject-stale-fallbacks	plan.md	REQ-WORKSPACES-WORKTREE-BASE-REFRESH-001	AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.6 AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.7	../../specs/workspaces/system-design/worktree-base-refresh.md

Task 03: Project Refresh Launch Failures

Summary

Carry a required-refresh failure through lifecycle and task launch boundaries. Prove that Kandev starts no agent and shows the durable repository-specific error on desktop and mobile.

In scope

• Add a failing multi-repository launch test where the second repository cannot complete required refresh.
• Preserve exact repository identity while wrapping refresh errors.
• Use the existing generic typed launch-failure category unless a focused test proves a new category is necessary for a valid recovery action.
• Bound and redact error detail through existing launch-error helpers.
• Prove that no agent runtime starts after a required refresh error.
• Extend existing desktop and mobile launch-failure recovery E2E fixtures with a stale-origin refresh failure and reload assertion.
• Prove that normal retry succeeds after the remote and credentials are fixed.

Out of scope

• A new recovery action, WebSocket schema, or task-error store.
• New UI components, responsive layout, or translations.
• Partial agent launch for multi-repository tasks.

Acceptance

• A required refresh error prevents runtime startup and names the exact failed repository without exposing credentials or an authenticated URL.
• The active task error survives reload and renders through the existing task error surface on desktop and mobile.
• A later normal retry reruns refresh and can launch after the underlying Git problem is corrected.

Verification

Start with the multi-repository no-start regression and confirm it fails before error propagation is complete. Then run:

# From apps/backend:
rtk go test ./internal/orchestrator/... ./internal/orchestrator/executor/... -run 'LaunchFailure|RepositoryRefresh|MultiRepo' -race
rtk go test ./internal/orchestrator/... ./internal/worktree/... -race

# From the repository root:
rtk make -C apps/backend build
rtk make -C apps/backend e2e-plugin-package

# From apps/web:
rtk pnpm run build:e2e
rtk pnpm e2e:raw --project=chromium e2e/tests/task/launch-failure-recovery.spec.ts
rtk pnpm e2e:raw --project=mobile-chrome e2e/tests/task/mobile-launch-failure-recovery.spec.ts

# From the repository root:
rtk make -C apps/backend lint

Files likely touched

• apps/backend/internal/orchestrator/executor/executor_resume.go
• apps/backend/internal/orchestrator/executor/executor_execute.go
• apps/backend/internal/orchestrator/executor/executor_launch_failure_classification_test.go
• apps/backend/internal/orchestrator/task_launch_failure_test.go
• apps/web/e2e/tests/task/launch-failure-recovery.spec.ts
• apps/web/e2e/tests/task/mobile-launch-failure-recovery.spec.ts

Dependencies

• Task 02 provides the required-refresh error from the worktree boundary.

Risks

• Raw Git output can contain a credential-bearing URL. Test redaction with a synthetic secret and assert that it is absent from logs and projected detail.
• An E2E fixture that fails clone instead of refresh does not prove this bug. Seed a valid cached checkout, make its origin fail, and request a new worktree.
• Backend E2E artifacts must be rebuilt before Playwright starts.

Parallelism

sequential

Inputs

• AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.6 and .7.
• REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001 as an adjacent task-system contract.
• Existing desktop and mobile launch-failure recovery E2E tests.

Results

• Multi-repository preparation preserves exact repository identity and rolls back preparation without starting an agent runtime.
• Launch error details use existing credential-safe sanitization while keeping repository-specific recovery actions.
• Desktop and mobile launch-failure fixtures cover a valid cached checkout with a failing origin, reload persistence, and successful retry after recovery.
• Verified with the focused and full orchestrator/worktree race suites, backend build, E2E plugin package, production E2E build, Chromium and mobile-chrome specs, and backend lint.