Carlos Florêncio
6.6 KiB
status, system, requirements
| status | system | requirements | |
|---|---|---|---|
| draft | workspaces |
|
Worktree Base Refresh System Design
Purpose and boundaries
The workspace system owns the repository checkout and the worktree base ref. This design keeps host worktrees local-first while remote materialization stays strict.
The task system owns session launch state and error presentation. The integration system owns provider credentials. Executors own their Git transport and remote workspace preparation.
This design does not refresh a valid worktree that Kandev reuses. It does not change Git commands that an agent runs after launch.
Requirement mapping
| Acceptance criterion | Design section |
|---|---|
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.1 |
Refresh policy |
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.2 |
Refresh policy |
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.3 |
Local fallback |
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.4 |
Base-ref selection |
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.5 |
Base-ref selection |
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.6 |
Required materialization |
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.7 |
Multi-repository launch |
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.8 |
Required materialization |
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.9 |
Empty remote |
AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.10 |
Failure and recovery |
Components and responsibilities
internal/orchestrator/executorresolves repository paths, refresh routes, credentials, and executor capabilities.internal/worktree.Managerverifies local refs, attempts host refresh, and selects the worktree base.internal/repoclone.Clonermaterializes provider-managed repositories when no user-owned local checkout supplies the branch.internal/agent/runtime/lifecyclestops launch only when no usable base remains.- The task projection shows bounded warnings and required-materialization errors.
Data and contracts
repositories.pull_before_worktree remains a persisted user policy. No schema
change is necessary.
The preparation fields have these contracts:
| Field | Contract |
|---|---|
PullBeforeWorktree |
Kandev attempts remote refresh before local worktree creation. |
RemoteSyncHandled |
The configured remote route completed a refresh for this checkout. |
RefreshRepository |
An optional provider refresh for worktree materialization. |
PullBeforeWorktree is not a universal admission gate. Local-ref availability
determines whether a failed refresh is recoverable.
Refresh policy
If PullBeforeWorktree is false, Kandev uses the selected local base without a
remote request.
If PullBeforeWorktree is true, Kandev attempts the configured refresh before
new or recreated host worktrees. A valid reusable worktree bypasses this
attempt.
The refresh route still follows the task Git credential policy. A host checkout keeps its configured origin and transport. A provider-managed checkout keeps its exact credential scope.
Local fallback
Before refresh, the worktree manager verifies the selected local ref. If that ref exists, refresh is best effort.
Authentication, network, timeout, Git, and missing-remote-ref errors return the selected local ref. The manager emits a bounded warning and does not include raw credential output.
The fallback does not change local or remote refs. It does not push the local branch.
Base-ref selection
After a successful fetch, the worktree manager compares local base L and
remote base R:
| Relationship | Start ref | Result |
|---|---|---|
R contains L |
R |
The worktree includes current remote commits. |
L contains R |
L |
The worktree preserves local-only commits. |
| Refs diverge | L |
The worktree preserves the selected local history and shows a warning. |
| Ancestry is unknown | L |
The worktree preserves the selected local history and shows a warning. |
The manager never resets, rebases, merges, removes, or hides either ref during selection.
Required materialization
Remote access is required when Kandev cannot verify a usable local base. This case includes an explicit remote-only ref and an executor that must clone the repository.
If materialization fails, lifecycle stops launch. The task error identifies the repository and uses a bounded failure class.
Provider selection still follows the existing Git credential policy. A managed HTTPS route must not replace an executor-owned SSH route.
Empty remote
An authenticated remote with zero refs uses the marked local baseline from the Empty Remote Repository System Design.
This path creates no remote ref during launch. Publication remains an explicit user action.
Multi-repository launch
Each repository resolves its base independently before agent startup. A local fallback counts as a prepared repository.
If one repository needs remote materialization and has no usable base, the whole task stops before agent startup. The error names that repository.
Failure and recovery
- A refresh error with a valid local base produces a warning and continues.
- A missing local and remote base produces a launch error.
- Caller cancellation stops preparation without a fallback worktree.
- A retry repeats remote materialization only when the task still needs it.
- A valid reused worktree does not refresh or materialize its base again.
Security
Git stays non-interactive. Host refresh uses the host credential route. Provider refresh uses exact task and repository scope.
Warnings contain a failure class, branch name, and repository identity. They do not contain tokens, credential-helper output, or secret URLs.
Observability
Sync progress reports the refresh attempt and its result. Local fallback reports completion with a warning, not a launch error.
Structured logs record repository identity, refresh route, failure class, and selected fallback ref. Logs exclude credential material and raw remote URLs.