Worktree Base Refresh Requirements

Overview

The workspace system owns repository state and the base ref used to create a task worktree. When a workspace enables pull-before-worktree behavior, users expect each new or recreated worktree to start from verified remote state. Kandev must not start an agent on an unverified local copy after a required refresh fails.

Terminology

Required refresh: The remote synchronization gate enabled by a repository's pull-before-worktree setting.
Fetched remote base: The remote-tracking ref produced by the successful fetch for the requested base branch.
Comparable refs: Two refs where either ref contains every commit in the other ref.

Requirements

REQ-WORKSPACES-WORKTREE-BASE-REFRESH-001: Verified Worktree Base

Intent: Prevent an agent from starting on stale repository state when the workspace requires a remote refresh before worktree creation.

User story: As a workspace user, I want a required repository refresh to stop task launch when it fails, so that an agent cannot edit and push from an old copy without my knowledge.

Acceptance criteria

AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.1: When pull-before-worktree is disabled, Kandev shall allow a new or recreated worktree to use available local refs without requiring remote access.
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.2: When pull-before-worktree is enabled, Kandev shall complete the remote refresh through the repository's configured transport and credential route before it starts an agent in a new or recreated worktree.
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.3: When a required fetch fails because of authentication, network access, timeout, cancellation, or another Git error, Kandev shall stop worktree preparation and shall not use a stale local fallback ref.
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.4: When the required fetch succeeds, Kandev shall choose a start ref that contains the fetched remote base. It can preserve local-only commits only when the local base also contains the fetched remote base.
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.5: When the local base and fetched remote base have diverged, or Kandev cannot prove their ancestry, Kandev shall stop worktree preparation without resetting, deleting, or hiding either ref.
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.6: When required refresh fails for any repository in a multi-repository task, Kandev shall not start the task agent and shall identify the affected repository in a credential-safe launch error.
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.7: When required refresh fails during initial launch or a resume that creates or recreates a worktree, Kandev shall expose the failure through the existing durable task launch-error projection.

Out of scope

Making setup-script failures fatal.
Refreshing a worktree that Kandev reuses without creating or recreating it.
Adding a background repository-refresh service.
Automatically resetting, rebasing, merging, or deleting local refs.
Changing agent Git transport after the agent starts.

System design

Worktree Base Refresh System Design

3.3 KiB Raw Blame History