git-workspace-bare 0.1.1 → 0.3.0

package/docs/hooks.md

@@ -0,0 +1,214 @@
+# Writing command hooks
+
+Hooks are independent executables. `git-workspace` supplies command results; packages such as
+a tmux integration or a notifier own their behavior, dependencies, and configuration.
+
+## Discovery and installation
+
+Put executable files or executable symlinks on `PATH` using these names:
+
+```text
+git-workspace-hook-add-post-<name>
+git-workspace-hook-remove-post-<name>
+git-workspace-hook-rename-post-<name>
+```
+
+The hook name starts with a lowercase letter or digit and may contain lowercase letters,
+digits, `_`, and `-`. A hook is enabled whenever it is discoverable. Discovery happens once
+per command invocation. For duplicate executable names, the first executable on `PATH`
+wins; a nonexecutable file does not hide a later executable. Distinct hooks for a command
+run sequentially in alphabetical order of their executable names.
+
+`git workspace hook list` lists command/phase, name, and resolved executable path in
+tab-separated columns. It needs no initialized workspace and never executes the hooks.
+
+Install and remove hooks using their package manager, or manage executables yourself. No
+cloning, registration, or installer is built into `git-workspace`. For example, a reusable
+npm package can expose one implementation under several names:
+
+```json
+{
+  "name": "git-workspace-hook-example",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "git-workspace-hook-add-post-example": "./hook.js",
+    "git-workspace-hook-remove-post-example": "./hook.js",
+    "git-workspace-hook-rename-post-example": "./hook.js"
+  }
+}
+```
+
+After publishing that package, `npm install -g git-workspace-hook-example` installs its bin
+links. The npm global bin directory must be on `PATH`. This is an example package name,
+not a bundled integration. The executable needs a shebang and executable permissions.
+It can use Bare, Node.js, Python, a shell, or another runtime supplied by the hook author.
+
+An example Node.js `hook.js` that reports results:
+
+```js
+#!/usr/bin/env node
+import fs from 'node:fs'
+
+const context = JSON.parse(fs.readFileSync(0, 'utf8'))
+if (context.version !== 1) throw new Error('Unsupported hook protocol')
+
+for (const { before, after } of context.result.data.checkouts) {
+  console.error(`${context.command}: ${before.name} -> ${after.name} (${context.result.status})`)
+}
+```
+
+## Execution
+
+The executable receives two arguments: the command (`add`, `remove`, or `rename`) and
+`post`. Its stdin contains one UTF-8 JSON document, followed by a newline and EOF. The
+working directory is the workspace root, normally `~/workspace`, so a removed checkout
+is never used as the working directory. The environment is inherited. Both hook stdout
+and stderr are forwarded to the CLI's stderr.
+
+Direct command hooks run after the checkout operations, the manifest commit and push
+attempt, and the local applied checkpoint attempt. A failed manifest push warns and keeps
+the successful local command result; it does not prevent hooks from running. A failed checkpoint only warns, as it does without hooks.
+Once an operation has been attempted, its hook also runs if the command fails, reporting
+the failure and any partial effects. Invalid command syntax, unresolved workspace configuration,
+help, completion, and dry runs do not trigger hooks.
+
+One logical command means one call to each matching hook. Adding `owner/repo@jobs` may
+create its root as well; both are included in one add payload. A root rename includes its
+worktrees. A successful repeated add still runs its hooks, allowing an integration to restore
+a missing session even when no checkout changed. `init`, `list`, `status`, `completion`,
+and `hook list` do not have hooks.
+
+Nonzero exit, a signal, or failure to launch a hook prints a warning. Remaining hooks still
+run; the original command's exit status is preserved. Hooks cannot veto or roll back an
+operation. Hook output is not interpreted as instructions. Execution waits for each hook;
+hooks should finish promptly or arrange their own background work.
+
+`--no-hooks` on `add`, `remove`, `rename`, or `pull` skips hooks for that invocation.
+Hook subprocesses receive `GIT_WORKSPACE_HOOK=1`; nested workspace commands inherit it and
+skip hook dispatch to prevent accidental recursion. Workspace mutations are still blocked
+while a pull is pending, including from its hooks.
+
+## JSON protocol, version 1
+
+The common envelope is:
+
+```json
+{
+  "version": 1,
+  "command": "rename",
+  "phase": "post",
+  "operation": {
+    "id": "42f9daef-e15f-4286-a7c9-0c6e93b75943",
+    "source": "cli",
+    "resumed": false
+  },
+  "workspace": {
+    "root": "/home/me/workspace",
+    "manifest": "/home/me/workspace/me/workspace/workspace.json"
+  },
+  "input": {
+    "from": "owner/repo@jobs",
+    "to": "owner/repo@fixes"
+  },
+  "result": {
+    "status": "ok",
+    "data": {
+      "changed": true,
+      "checkouts": []
+    },
+    "error": null
+  }
+}
+```
+
+The empty `checkouts` above abbreviates the payload: it contains a `{ before, after }`
+pair for each checkout involved. Each snapshot has this shape:
+
+```json
+{
+  "id": "e8375481-bac0-4e98-b035-599cbdf7ad4d",
+  "kind": "worktree",
+  "name": "owner/repo@fixes",
+  "path": "/home/me/workspace/owner/repo@fixes",
+  "repository": {
+    "id": "34a017c5-a0c4-43bb-a3e4-abeb5301c56a",
+    "name": "owner/repo",
+    "path": "/home/me/workspace/owner/repo"
+  },
+  "exists": true,
+  "registered": true,
+  "branch": "fixes",
+  "ref": "0123456789012345678901234567890123456789",
+  "origin": null
+}
+```
+
+- `operation.id` identifies this logical operation. Direct invocations get fresh IDs.
+  Pull retries retain an operation's ID. `source` is `cli` or `pull`; `resumed` identifies
+  delivery during a resumed pull.
+- `input` is `{ "repository": "owner/repo[@branch]" }` for add/remove, or `{ "from": "...",
+"to": "..." }` for rename. These are parsed names, not the original shell command line.
+- `status` is `ok` on success, `partial` on failure with an observed checkout/registration
+  change, or `error` on failure without one. `error` is either `null` or `{ "message": "...",
+"code": null }`; `code` is the error's code string when available.
+- `changed` compares the checkout snapshots. It is false for an unchanged repeated add.
+  It does not describe unrelated staged files, manifest commit metadata, or a history of
+  transient changes that were rolled back.
+- Snapshot `id` is the stable manifest ID when known, otherwise `null`. Removed entries
+  retain their ID in the after snapshot. New direct additions acquire IDs when registered;
+  pull additions already have IDs in the desired manifest. Never invent IDs from paths.
+- `kind` is `repository` or `worktree`. `repository` identifies the root and points to the
+  checkout itself for root entries. All paths are absolute.
+- `exists` describes the path on disk. A missing checkout still has a snapshot with its
+  name, path, and any known ID. `registered` describes the operation's manifest layout;
+  during pull this is the intermediate layout as operations are applied, since the manifest
+  file already contains the full desired layout.
+- `branch` is the currently checked-out branch, or `null` for a missing, detached, or
+  unreadable checkout. It may differ from the branch in `name` after a manual Git switch.
+  `ref` is the commit of the local branch named by `@branch`, or `null` if unavailable;
+  it is also `null` for a root. This distinguishes a removed worktree from a branch ref
+  whose deletion failed. `origin` is the root's origin URL, otherwise `null`.
+
+For renames, `after` follows a checkout that moved even if a later branch or manifest update
+failed. An occupied destination that caused a rename to be refused is not reported as the
+renamed checkout. Root renames include unregistered linked worktrees under the root's
+`@branch` naming layout, with null IDs. External linked worktrees whose paths stay unchanged
+are not included. Discovered unregistered worktrees can have suffix characters accepted by
+ordinary Git but unsupported as CLI input. Add payloads include the root first, then the requested
+worktree.
+
+For example, if removal deletes a worktree but cannot delete its branch, the result is
+`partial`: `after.exists` is false, `after.registered` is true, and `after.ref` still identifies
+the branch. If checkout creation succeeds but the manifest commit fails, the hook sees the
+created checkout and a `partial` result with the commit error. Consumers should examine the
+outcome and snapshots instead of assuming every post hook means success.
+
+Treat context as data, not shell source. Ignore unfamiliar JSON fields for forward
+compatibility. Command-specific data lives under `result.data`; a future command such as
+fetch can define its own result shape without adding notification logic to the core.
+This release implements neither fetch nor prune.
+
+## Pull and recovery
+
+Pull invokes add/remove/rename hooks for its individual operations, with `source: "pull"`.
+It records the filesystem operation as completed and saves its post-hook context together
+before running the hooks. It does not run a second set of top-level pull hooks. Pull's final
+applied checkpoint is recorded after all operations and hook delivery attempts.
+
+After a crash, the next pull resumes the saved target and delivers any saved post context
+without repeating completed filesystem operations. If the process died during hook delivery,
+the matching hooks can all run again, including ones that already succeeded. Use stable
+checkout IDs and idempotent operations, such as ensuring a session exists or removing it only
+if present. `operation.id` can help detect duplicate delivery. The same operation can first
+report a partial failure and later succeed, so do not discard a later success solely because
+its ID was seen before.
+
+Each retry resolves the currently installed hooks on `PATH`; executable paths are not saved
+in the progress journal. Hook failures count as attempted delivery and do not prevent pull
+from completing. A dry run never delivers or clears pending hooks. Resuming with `--no-hooks`
+discards pending delivery and skips hooks for the remaining operations; it does not defer them
+for a later invocation. It still finishes and verifies the workspace normally.
+
+Direct commands have no durable hook journal. A process crash can prevent their hooks from
+running, so the API provides no exactly-once delivery guarantee.

package/lib/add.js

@@ -1,16 +1,39 @@
 import fs from 'bare-fs'
 import path from 'bare-path'
 import { spawnSync } from 'bare-subprocess'
-import { readRegistry, updateRegistry } from './registry.js'
+import { manifestDirectory, readRegistry, updateRegistry } from './registry.js'
 import repositoryPath from './repository-path.js'
+import commitManifest from './commit-manifest.js'
+import { refreshCheckpoint } from './checkpoint.js'
+import { assertNoPendingPull } from './pull-state.js'
+import { withPostHooks } from './hook-context.js'
+import cloneRepository, { emptyDestination } from './clone-repository.js'
 
-export default function add(repository) {
+export default function add(repository, options = {}) {
+  assertNoPendingPull()
+  return withPostHooks('add', { repository }, options, () => {
+    addCheckout(repository, { initialize: true })
+    try {
+      commitManifest(manifestDirectory(), `Add ${repository}`)
+    } catch (err) {
+      err.message = `Registered ${repository}, but could not commit the manifest: ${err.message}`
+      err.hint = `resolve the Git error, then rerun git workspace add ${repository}`
+      throw err
+    }
+    refreshCheckpoint()
+  })
+}
+
+export function addCheckout(
+  repository,
+  { registry = readRegistry, register = registerCheckout, initialize = false } = {}
+) {
   const directory = repositoryPath(repository)
-  readRegistry()
+  registry()
   const [base, branch] = repository.split('@')
   if (branch) {
     git(['check-ref-format', '--branch', branch])
-    add(base)
+    addCheckout(base, { registry, register, initialize })
     const root = repositoryPath(base)
     if (!exists(directory)) {
       const args = ['-C', root, 'worktree', 'add']
@@ -21,6 +44,13 @@ export default function add(repository) {
           stdio: 'inherit'
         })
       } else {
+        if (!hasCommit(root)) {
+          const err = new Error(
+            `${base} has no commits; create its first commit before adding a branch worktree`
+          )
+          err.hint = `the root is retained locally; commit in ${root}, then rerun git workspace add ${repository}`
+          throw err
+        }
         git([...args, '--no-track', '-b', branch, directory, 'HEAD'], { stdio: 'inherit' })
       }
     }
@@ -41,9 +71,9 @@ export default function add(repository) {
     return
   }
 
-  if (!exists(directory)) {
+  if (!exists(directory) || (initialize && emptyDestination(directory))) {
     fs.mkdirSync(path.dirname(directory), { recursive: true })
-    git(['clone', `git@github.com:${repository}.git`, directory], { stdio: 'inherit' })
+    cloneRepository(repository, directory, { initialize })
   }
 
   const worktree = fs.realpathSync(directory)
@@ -62,6 +92,24 @@ export default function add(repository) {
   register(repository, directory, worktree)
 }
 
+function hasCommit(directory) {
+  const result = spawnSync('git', [
+    '-C',
+    directory,
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    'HEAD^{commit}'
+  ])
+  if (result.error) throw result.error
+  if (result.signal) throw new Error(`Git was interrupted by signal ${result.signal}`)
+  if (result.status === 1) return false
+  if (result.status !== 0) {
+    throw new Error(result.stderr?.toString().trim() || 'Could not inspect Git HEAD')
+  }
+  return true
+}
+
 function exists(directory) {
   try {
     fs.lstatSync(directory)
@@ -82,7 +130,7 @@ function hasRef(directory, ref) {
   return true
 }
 
-function register(repository, directory, worktree) {
+function registerCheckout(repository, directory, worktree) {
   try {
     updateRegistry((worktrees) => {
       if (!worktrees.includes(worktree)) worktrees.push(worktree)

package/lib/apply-pull.js

@@ -0,0 +1,140 @@
+import fs from 'bare-fs'
+import { manifestNames } from './manifest.js'
+import repositoryPath from './repository-path.js'
+import { addCheckout } from './add.js'
+import { removeCheckout } from './remove.js'
+import { renameCheckout, finishBranchRename } from './rename.js'
+import { finishRootRename } from './rename-root.js'
+import planPull, { changes } from './plan-pull.js'
+import { writePullState } from './pull-state.js'
+import { verifyCheckouts } from './checkpoint.js'
+import { beginOperation, finishOperation, observe } from './hook-context.js'
+
+export function layoutAfter(previous, desired, actions) {
+  const layout = JSON.parse(JSON.stringify(previous))
+  for (const action of actions) {
+    const parent = layout.repositories.find((repo) => repo.id === (action.root || action.id))
+    if (action.kind === 'repository') {
+      if (action.type === 'remove') {
+        layout.repositories = layout.repositories.filter((repo) => repo.id !== action.id)
+      } else if (action.type === 'rename') parent.name = action.to
+      else {
+        const entry = desired.repositories.find((repo) => repo.id === action.id)
+        layout.repositories.push({ ...entry, worktrees: [] })
+      }
+    } else {
+      if (action.type === 'remove') {
+        parent.worktrees = parent.worktrees.filter((entry) => entry.id !== action.id)
+      } else if (action.type === 'rename') {
+        parent.worktrees.find((entry) => entry.id === action.id).branch = action.to.split('@')[1]
+      } else {
+        const entry = desired.repositories
+          .find((repo) => repo.id === action.root)
+          .worktrees.find((entry) => entry.id === action.id)
+        parent.worktrees.push({ ...entry })
+      }
+    }
+  }
+  return layout
+}
+
+export function pendingRename(action) {
+  if (action.type !== 'rename') return false
+  const from = exists(repositoryPath(action.from))
+  const to = exists(repositoryPath(action.to))
+  if (from && !to) return false
+  if (!from && to) return true
+  throw new Error(`Interrupted rename has ambiguous paths: ${action.from} and ${action.to}`)
+}
+
+export default function applyPull(directory, state, previous, desired, hooks, resumed = false) {
+  const { actions, blockers } = changes(previous, desired)
+  if (blockers.length) throw new Error(blockers.join('\n'))
+  let layout = layoutAfter(previous, desired, actions.slice(0, state.completed))
+  const paths = () => manifestNames(layout).map(repositoryPath)
+  const update = (fn) => fn(paths())
+  const apply = (action) => {
+    if (action.type === 'add') addCheckout(action.to, { registry: paths, register: () => {} })
+    else if (action.type === 'remove') {
+      const root = action.from.split('@')[0]
+      // A root already absent has no remaining branch refs to delete.
+      if (action.kind !== 'worktree' || exists(repositoryPath(root))) {
+        removeCheckout(action.from, { update })
+      }
+    } else renameCheckout(action.from, action.to, { update })
+  }
+  const deliver = () => {
+    if (!state.postHook) return
+    if (resumed) state.postHook.operation.resumed = true
+    hooks.run(state.postHook)
+    delete state.postHook
+    writePullState(directory, state)
+  }
+  const perform = (action, repair = false) => {
+    if (!state.hookOperation && hooks.has(action.type)) {
+      const input =
+        action.type === 'rename'
+          ? { from: action.from, to: action.to }
+          : { repository: action.from || action.to }
+      state.hookOperation = observe(() =>
+        beginOperation(action.type, input, layout, { source: 'pull', known: desired })
+      )
+    }
+    if (resumed && state.hookOperation) state.hookOperation.context.operation.resumed = true
+    state.pending = true
+    writePullState(directory, state)
+    try {
+      if (!repair) apply(action)
+      else if (action.kind === 'repository') finishRootRename(action.from, action.to, paths())
+      else {
+        const root = layout.repositories.find((repo) => repo.id === action.root)
+        verifyCheckouts({ repositories: [{ ...root, worktrees: [] }] })
+        finishBranchRename(action.from, action.to)
+      }
+    } catch (err) {
+      if (state.hookOperation) {
+        state.postHook = observe(() => finishOperation(state.hookOperation, layout, err))
+        writePullState(directory, state)
+        deliver()
+      }
+      throw err
+    }
+    layout = layoutAfter(previous, desired, actions.slice(0, state.completed + 1))
+    if (state.hookOperation) {
+      state.postHook = observe(() => finishOperation(state.hookOperation, layout))
+    }
+    delete state.hookOperation
+    state.completed++
+    state.pending = false
+    // Persist the completed filesystem step AND its pending post hook together.
+    // Recovery may redeliver a hook, but must never replay a completed removal.
+    writePullState(directory, state)
+    deliver()
+  }
+  try {
+    deliver()
+    // Only the action marked pending can have been partially performed.
+    const interrupted = state.pending ? actions[state.completed] : null
+    if (interrupted && pendingRename(interrupted)) perform(interrupted, true)
+    const plan = planPull(layout, desired, directory)
+    if (plan.blockers.length) throw new Error(plan.blockers.join('\n'))
+    while (state.completed < actions.length) {
+      perform(actions[state.completed])
+    }
+  } catch (err) {
+    err.message = `Workspace pull stopped after ${state.completed} of ${actions.length} changes: ${err.message}`
+    err.hint =
+      'completed changes are retained; resolve the error and rerun git workspace pull to resume'
+    throw err
+  }
+}
+
+function exists(directory) {
+  try {
+    fs.lstatSync(directory)
+    return true
+  } catch (err) {
+    if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') throw err
+    return false
+  }
+}

package/lib/checkpoint.js

@@ -0,0 +1,208 @@
+import fs from 'bare-fs'
+import path from 'bare-path'
+import { spawnSync } from 'bare-subprocess'
+import { manifestDirectory, readManifest } from './registry.js'
+import { validateManifest } from './manifest.js'
+import repositoryPath from './repository-path.js'
+import checkedOutBranch from './checked-out-branch.js'
+import { assertNoPendingPull } from './pull-state.js'
+
+const ref = 'refs/git-workspace/applied'
+
+export function readCheckpoint(directory = manifestDirectory()) {
+  return readCommitRef(directory, ref)
+}
+
+export function readCommitRef(directory, ref) {
+  const symbolic = run(directory, ['symbolic-ref', '--quiet', ref])
+  if (symbolic.status === 0) throw new Error('Applied checkpoint must not be a symbolic ref')
+  if (symbolic.status !== 1) fail(symbolic)
+  const result = run(directory, ['rev-parse', '--verify', '--quiet', ref])
+  if (result.status === 1) {
+    if (result.stderr?.toString().trim()) fail(result)
+    return null
+  }
+  if (result.status !== 0) fail(result)
+  const commit = result.stdout.toString().trim()
+  if (git(directory, ['cat-file', '-t', commit]) !== 'commit') {
+    throw new Error('Applied checkpoint does not point to a commit')
+  }
+  return commit
+}
+
+// Ordinary commands succeed even if some other checkout prevents full verification.
+// A checkpoint failure must never be mistaken for a failed commit or undo a rename.
+export function refreshCheckpoint(directory = manifestDirectory()) {
+  try {
+    return checkpoint(directory)
+  } catch (err) {
+    console.error(`warning: local workspace tracking unchanged: ${err.message}`)
+    return null
+  }
+}
+
+export default function checkpoint(directory = manifestDirectory()) {
+  assertNoPendingPull(directory)
+  const lock = path.join(directory, '.git', 'workspace.lock')
+  fs.mkdirSync(lock)
+  try {
+    return recordCheckpoint(directory)
+  } finally {
+    fs.rmdirSync(lock)
+  }
+}
+
+// Called by pull while it already holds the workspace lock. Confirmed replacements
+// come from completed local operations, not from guessing at occupied paths.
+export function recordCheckpoint(directory, { replacedPaths = new Set() } = {}) {
+  const previous = readCheckpoint(directory)
+  const head = git(directory, ['rev-parse', '--verify', 'HEAD^{commit}'])
+  const current = snapshot(directory, head)
+  cleanManifest(directory)
+  // Validate the actual manifest too, including refusing symlinks.
+  readManifest(path.join(directory, 'workspace.json'))
+  let retired = new Set()
+  if (previous) {
+    const ancestry = run(directory, ['merge-base', '--is-ancestor', previous, head])
+    if (ancestry.status === 1) {
+      throw new Error('HEAD does not descend from the applied checkpoint')
+    }
+    if (ancestry.status !== 0) fail(ancestry)
+    retired = verifyRetiredEntries(snapshot(directory, previous), current, replacedPaths)
+  }
+  verifyCheckouts(current, retired)
+  // Do not label another command's concurrent commit as applied.
+  if (git(directory, ['rev-parse', '--verify', 'HEAD^{commit}']) !== head) {
+    throw new Error('Manifest HEAD changed during verification; retry')
+  }
+  cleanManifest(directory)
+  if (head !== previous) {
+    git(directory, ['update-ref', '--no-deref', ref, head, previous || '0'.repeat(head.length)])
+  }
+  return head
+}
+
+function cleanManifest(directory) {
+  if (git(directory, ['status', '--porcelain', '--untracked-files=all', '--', 'workspace.json'])) {
+    throw new Error(
+      'workspace.json has uncommitted changes; commit it before local workspace tracking can advance'
+    )
+  }
+}
+
+export function snapshot(directory, commit) {
+  const manifest = JSON.parse(git(directory, ['show', `${commit}:workspace.json`]))
+  validateManifest(manifest)
+  return manifest
+}
+
+function entries(manifest) {
+  return manifest.repositories.flatMap(({ id, name, worktrees }) => [
+    { id, name },
+    ...worktrees.map((worktree) => ({ id: worktree.id, name: `${name}@${worktree.branch}` }))
+  ])
+}
+
+function verifyRetiredEntries(previous, current, replacedPaths) {
+  const retired = new Set()
+  const next = new Map(entries(current).map((entry) => [entry.id, entry.name]))
+  for (const entry of entries(previous)) {
+    if (next.get(entry.id) === entry.name) continue
+    if (replacedPaths.has(repositoryPath(entry.name))) continue
+    retired.add(repositoryPath(entry.name))
+    if (exists(repositoryPath(entry.name))) {
+      throw new Error(
+        `Previous checkout ${entry.name} still exists or its name has been reused; cannot verify its removal or rename`
+      )
+    }
+  }
+  return retired
+}
+
+export function verifyCheckouts(manifest, retired = new Set(), renames = new Map()) {
+  for (const repository of manifest.repositories) {
+    const root = repositoryPath(repository.name)
+    verifyDirectory(root, repository.name)
+    const canonical = fs.realpathSync(root)
+    const gitDirectory = path.join(canonical, '.git')
+    if (!fs.lstatSync(gitDirectory).isDirectory() || common(root) !== gitDirectory) {
+      throw new Error(`${repository.name} is not a standalone root repository`)
+    }
+    const origin = git(root, ['config', '--get', 'remote.origin.url'])
+    const match =
+      /^(?:git@github\.com:|ssh:\/\/git@github\.com\/|https:\/\/github\.com\/)([^/]+\/[^/]+?)\/?$/i.exec(
+        origin
+      )
+    const expected = [repository.name, renames.get(repository.id)?.to].filter(Boolean)
+    if (
+      !match ||
+      !expected.some((name) => match[1].replace(/\.git$/i, '').toLowerCase() === name.toLowerCase())
+    ) {
+      throw new Error(`${repository.name} has an unexpected origin`)
+    }
+    const listed = git(root, ['worktree', 'list', '--porcelain', '-z'])
+      .split('\0')
+      .filter((field) => field.startsWith('worktree '))
+      .map((field) => field.slice('worktree '.length))
+    for (const directory of listed) {
+      if (retired.has(directory)) {
+        throw new Error(`Previous worktree still has a Git record: ${directory}`)
+      }
+    }
+    for (const worktree of repository.worktrees) {
+      const name = `${repository.name}@${worktree.branch}`
+      const directory = repositoryPath(name)
+      verifyDirectory(directory, name)
+      if (common(directory) !== gitDirectory || !listed.includes(fs.realpathSync(directory))) {
+        throw new Error(`${name} is not a linked worktree of ${repository.name}`)
+      }
+      if (checkedOutBranch(directory) !== worktree.branch) {
+        throw new Error(`${name} is not on branch ${worktree.branch}`)
+      }
+    }
+  }
+}
+
+function verifyDirectory(directory, name) {
+  if (!exists(directory)) throw new Error(`Missing checkout: ${name}`)
+  if (fs.lstatSync(directory).isSymbolicLink()) {
+    throw new Error(`Checkout is a symbolic link: ${name}`)
+  }
+  if (
+    fs.realpathSync(git(directory, ['rev-parse', '--show-toplevel'])) !== fs.realpathSync(directory)
+  ) {
+    throw new Error(`${name} is not a Git worktree root`)
+  }
+}
+
+function common(directory) {
+  return fs.realpathSync(
+    git(directory, ['rev-parse', '--path-format=absolute', '--git-common-dir'])
+  )
+}
+
+function exists(directory) {
+  try {
+    fs.lstatSync(directory)
+    return true
+  } catch (err) {
+    if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') throw err
+    return false
+  }
+}
+
+function run(directory, args) {
+  const result = spawnSync('git', ['--no-optional-locks', '-C', directory, ...args])
+  if (result.error) throw result.error
+  return result
+}
+
+function fail(result) {
+  throw new Error(result.stderr?.toString().trim() || 'Git command failed')
+}
+
+function git(directory, args) {
+  const result = run(directory, args)
+  if (result.status !== 0) fail(result)
+  return result.stdout.toString().replace(/\r?\n$/, '')
+}