docs(worktrees): name the repo-level preservation proxy as a trade-off

hasWorktreeRemovalRepoOwnerOnOtherHost asks "is this REPO on another host",
not "is this WORKTREE id on another host", so it over-fires: deleting a
single-host workspace inside a two-host repo preserves state it could have
torn down. Mutating it to `false` turns only the two-host preservation tests
red, which confirms nothing covers that cost.

The precise question is unanswerable here — worktreeMeta holds one entry per
bare `repoId::path`, so main cannot enumerate per-host rows for an id.
Narrowing it needs host-qualified worktree metadata, a storage change well
outside this PR. Documenting it as a deliberate, fail-safe-direction proxy so
the next reader does not mistake it for precision.
This commit is contained in:
Brennan Benson
2026-08-16 21:59:43 -07:00
parent c0faa7c41d
commit ddbf88cc82
+18
View File
@@ -39,6 +39,24 @@ export function resolveWorktreeRemovalRepoOwner(
: { kind: 'missing' }
}
/**
* Whether this REPO is registered on a host other than the removal's.
*
* Deliberately a proxy, and it over-fires. The precise question is "does this
* WORKTREE id exist on another host", but `worktreeMeta` holds one entry per bare
* `repoId::path`, so main cannot enumerate per-host rows for an id — repo-level
* registration is the closest signal available.
*
* The cost, accepted knowingly: deleting a workspace that exists on ONE host,
* inside a repo that happens to be registered on two, preserves state it could
* have torn down (terminal history, advertised-URL watcher, PR-refresh aliases,
* the local session partition). Worktree ids are path-derived and reusable, so a
* workspace recreated at that path can inherit it. Narrowing this needs
* host-qualified worktree metadata, which is a storage change, not a fix here.
*
* Fail-safe direction: over-preserving leaves stale records, under-preserving
* destroys another host's live state. Prefer this way round.
*/
export function hasWorktreeRemovalRepoOwnerOnOtherHost(
store: Pick<WorktreeRemovalRepoSource, 'getRepos'>,
repoId: string,