kandev/docs/plans/worktree-refresh-fail-closed/task-01-route-required-refresh.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
01-route-required-refresh	Route required repository refresh	done	1		plan.md	REQ-WORKSPACES-WORKTREE-BASE-REFRESH-001	AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.2 AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.3	../../specs/workspaces/system-design/worktree-base-refresh.md

Task 01: Route Required Repository Refresh

Summary

Choose the strict refresh boundary from repository provider and task Git credential policy. Preserve executor-inherited SSH origins and use exact-scope backend credentials only for managed provider routes.

In scope

• Add failing tests for GitHub managed mode, GitHub executor mode, plugin providers, GitLab, and Azure DevOps.
• Resolve the route before lifecycle preparation in initial launch and resume; defer a managed refresh until the lifecycle actually materializes or recreates a worktree so valid reuse performs no refresh.
• Generalize the existing plugin strict-refresh helper into a provider-credential-aware helper.
• Reuse the clone credential path for strict GitLab and Azure DevOps refresh.
• Set RemoteSyncHandled only after the deferred strict provider refresh succeeds.
• Leave PullBeforeWorktree enabled for executor-inherited and local routes so the worktree manager owns their fetch.
• Preserve the SSH origin selected by gitHubCheckoutOriginURL in executor mode.

Out of scope

• Worktree fallback and ancestry behavior.
• Task error projection or frontend changes.
• New credential sources, provider settings, or schema.
• Changing repository clone behavior when no existing checkout is present.

Acceptance

• A managed provider checkout runs one authenticated strict refresh when a worktree is materialized or recreated, and does not run an unauthenticated follow-up fetch. A valid reusable worktree bypasses the refresh.
• An executor-inherited GitHub checkout retains its reconciled origin and delegates required fetch to the worktree manager.
• A strict provider refresh error returns from initial launch and resume with exact task, session, and repository scope.

Verification

Start with a regression that proves a managed first-party checkout stops after its authenticated refresh fails. Confirm that it fails before the production change. Then run:

# From apps/backend:
rtk go test ./internal/repoclone ./internal/orchestrator/executor -run 'RefreshWorkspaceRepository|ResolveTaskRepoInfo|CloneTransport' -race
rtk go test ./internal/orchestrator/executor/... -run 'Fresh|Resume|Repository' -race

Files likely touched

• apps/backend/internal/orchestrator/executor/executor.go
• apps/backend/internal/orchestrator/executor/executor_resume.go
• apps/backend/internal/orchestrator/executor/executor_resume_clone_transport_test.go
• apps/backend/internal/repoclone/clone.go
• apps/backend/internal/repoclone/clone_auth_test.go

Dependencies

None.

Risks

• Provider-specific clone credentials can drift from refresh credentials. Use the same resolver and redaction path for both operations.
• Executor mode must not call a backend-managed GitHub refresh because that can rewrite the SSH origin to HTTPS.
• Exact credential scope must include task ID, session ID, and repository ID.

Parallelism

sequential

Inputs

• REQ-WORKSPACES-WORKTREE-BASE-REFRESH-001.
• docs/specs/workspaces/system-design/worktree-base-refresh.md.
• ADR-2026-07-27-task-git-credential-policy.
• Existing plugin strict-refresh tests and GitHub origin-reconciliation tests.

Results

• Added managed-provider refresh routing for GitHub, GitLab, Azure DevOps, and plugin repositories while preserving executor-inherited GitHub transport.
• Deferred managed refresh until worktree materialization or recreation, while preserving exact repository identity through multi-repository preparation and bypassing refresh for valid worktree reuse.
• Added authenticated pull-request-head fetching into origin/pr/<N> for managed checkouts, including fork pull requests.
• Added strict Azure DevOps basic-auth refresh support that reuses the clone credential boundary and validates the exact workspace checkout path.
• Verified with:
  • rtk go test ./internal/repoclone ./internal/orchestrator/executor -run 'RefreshWorkspaceRepository|ResolveTaskRepoInfo|CloneTransport' -race
  • rtk go test ./internal/orchestrator/executor/... -run 'Fresh|Resume|Repository' -race