Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

137 KB
Raw Blame
/**
 * Git Worktree Manager
 *
 * Creates and cleans up git worktrees for CoS agents that need isolated
 * workspaces to avoid file conflicts with concurrent agents.
 *
 * Worktrees are created under data/cos/worktrees/<agentId>/ with a
 * unique branch name. On agent completion, the worktree is removed
 * and the branch cleaned up.
 */

import { claimBranchAdmission, claimCheckoutOwnerReason } from '../lib/claimContinuation.js';
import { existsSync, realpathSync } from 'fs';
import { lstat, readlink, readdir, rm, stat, symlink, unlink } from 'fs/promises';
import { dirname, isAbsolute, join, resolve } from 'path';
import { ensureDir, isPathInsideDir, PATHS, sleep, tryReadFile } from '../lib/fileUtils.js';
import { DONE_SENTINEL_NAME, doneSentinelCandidateNames } from '../lib/agentSentinel.js';
import { AGENT_SCRATCH_PATHS, matchesScratchRoot } from '../lib/agentScratchPaths.js';
import { execGit } from '../lib/execGit.js';
import { hasProcessCwdInside } from '../lib/processCwdProbe.js';
import { PROTECTED_BRANCHES } from '../lib/gitArgs.js';
import { clearStaleGitLock } from '../lib/gitStaleLock.js';
import { createKeyCachedQueue } from '../lib/createKeyCachedQueue.js';
import { enforceSafeBranchUpstream } from '../lib/branchUpstreamGuard.js';
import { forkRemoteName, normalizeForkHead, forkLocalBranch } from '../lib/forkHead.js';
import { isHumanClaimWorktree, worktreeAgentId, worktreeOwnershipReason } from '../lib/worktreeOwnership.js';
import { ensureInstanceId } from './instanceIdentity.js';
import { provisionWorkspaceNodeModules, removeProvisionedNodeModules } from '../lib/worktreeNodeModules.js';

export { isHumanClaimWorktree } from '../lib/worktreeOwnership.js';

const WORKTREES_DIR = PATHS.worktrees;
const CACHE_ENTRIES = new Set(['.vite', '.vitest-cache', '.cache']);
// `git worktree list --porcelain` reports POSIX separators on every platform —
// `H:/repo/data/cos/worktrees/agent-x` — while WORKTREES_DIR is built with
// `join` and is backslash-separated on Windows. So a git-reported path is never
// compared with a bare `startsWith`/`split('/')`: `isPathInsideDir` resolves
// both sides first (and rejects a sibling like `worktrees-old`), and
// `worktreeAgentId()` treats either separator as one. Before this, every CoS
// worktree failed the containment check on Windows — `cleanupOrphanedWorktrees`
// skipped them all and `reapMergedWorktrees` filed them as `unmanaged-location`,
// so the daily line read "reaped 0 merged + 0 orphaned" with orphans on disk.
// Lockfiles that npm/yarn/pnpm modify as a side-effect — safe to discard during worktree cleanup
const AUTO_GENERATED_LOCKFILES = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'];
// Cap the dirty paths named in a "worktree preserved" warning — the message ends
// up in a notification and on the agent card, and a broad sweep can dirty
// hundreds of files. Enough to identify the work, short enough to read.
const DIRT_PATHS_IN_WARNING = 5;

// Dependencies are linked from the source checkout for ordinary ephemeral
// worktrees. Dependency-update tasks opt out so package managers cannot mutate
// the source checkout's installed tree through these links.
async function worktreeDependencyPaths(sourceWorkspace, worktreePath, { cleanup = false } = {}) {
  const entries = await readdir(worktreePath, { withFileTypes: true });
  const children = await Promise.all(entries
    .filter(entry => entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules')
    .map(async ({ name }) => {
      // Cleanup must still find owned links after a package or its source is removed.
      if (cleanup) return join(name, 'node_modules');
      const sourceDirectory = await lstat(join(sourceWorkspace, name)).catch(() => null);
      if (!sourceDirectory?.isDirectory()) return null;
      if (existsSync(join(sourceWorkspace, name, '.git')) || existsSync(join(worktreePath, name, '.git'))) return null;
      const manifest = await lstat(join(worktreePath, name, 'package.json')).catch(() => null);
      if (!manifest?.isFile()) return null;
      return join(name, 'node_modules');
    }));
  return ['node_modules', ...children.filter(Boolean)];
}

/**
 * Make installed dependencies available to a fresh worktree without copying
 * or reinstalling them. Missing source directories are skipped so this also
 * works for managed repositories that do not use PortOS's client/server
 * layout. Existing paths are preserved, including real directories and links.
 * A root node_modules holding workspace links is rebuilt as a real directory
 * so those links resolve inside the worktree, not the source (#12633).
 */
export async function linkWorktreeDependencies(sourceWorkspace, worktreePath) {
  const dependencyPaths = await worktreeDependencyPaths(sourceWorkspace, worktreePath);
  await Promise.all(dependencyPaths.map(async (relativePath) => {
    const sourcePath = join(sourceWorkspace, relativePath);
    const targetPath = join(worktreePath, relativePath);
    const sourceExists = await stat(sourcePath).then(info => info.isDirectory()).catch(() => false);
    if (!sourceExists) return;
    const targetStat = await lstat(targetPath).catch(() => null);
    if (targetStat) {
      const isSymlink = targetStat.isSymbolicLink?.() ?? false;
      const isDir = targetStat.isDirectory?.() ?? !isSymlink;
      if (!isSymlink && isDir) {
        const entries = await readdir(targetPath).catch(() => null);
        if (entries !== null && entries.length > 0 && entries.every(name => CACHE_ENTRIES.has(name))) {
          await rm(targetPath, { recursive: true, force: true });
        } else {
          console.warn(`⚠️ linkWorktreeDependencies: skipping existing ${targetPath} (not a cache-only directory)`);
          return;
        }
      } else {
        return;
      }
    }
    if (relativePath === 'node_modules' && await provisionWorkspaceNodeModules(sourceWorkspace, worktreePath)) return;
    await symlink(sourcePath, targetPath, 'dir');
  }));
}

/**
 * Remove only dependency symlinks that point back into the source checkout,
 * plus a root node_modules this module provisioned as a link farm. Real
 * dependency directories and links managed by another tool stay intact.
 */
export async function unlinkWorktreeDependencies(sourceWorkspace, worktreePath) {
  const dependencyPaths = await worktreeDependencyPaths(sourceWorkspace, worktreePath, { cleanup: true });
  await Promise.all(dependencyPaths.map(async (relativePath) => {
    const sourcePath = join(sourceWorkspace, relativePath);
    const targetPath = join(worktreePath, relativePath);
    const targetStat = await lstat(targetPath).catch((err) => {
      if (err.code === 'ENOENT') return null;
      throw err;
    });
    if (!targetStat) return;
    if (!targetStat.isSymbolicLink()) {
      if (relativePath === 'node_modules') await removeProvisionedNodeModules(sourceWorkspace, worktreePath);
      return;
    }

    const linkTarget = await readlink(targetPath);
    const linkedPath = isAbsolute(linkTarget) ? linkTarget : resolve(dirname(targetPath), linkTarget);
    if (pathsEqual(linkedPath, sourcePath)) await unlink(targetPath);
  }));
}

// `git worktree add` lock-contention retry (#2193). Git guards a repo's
// worktree bookkeeping (`.git/worktrees`, `.git/index.lock`) with a per-repo
// lock, so two adds fired in the same evaluation tick race — the loser fails
// with a lock error. Serialization (queueWorktreeCreate) removes the common
// same-process race; retry handles residual external contention (a human
// `git` command, another install's tool touching a shared checkout).
const WORKTREE_ADD_MAX_ATTEMPTS = 4;
const WORKTREE_ADD_RETRY_DELAY_MS = 250;

// `git worktree add` materializes a FULL checkout, so it is nothing like the
// metadata reads execGit's 30s default was sized for: ~5.8k files here, and on
// Windows every one of them is written through the AV filter driver, which puts
// a cold add well past 30s. Worse, the timeout doesn't stop git — the checkout
// keeps running and lands — so PortOS blocks the task with `worktree-failed`
// while the worktree and branch it just gave up on exist on disk, which then
// defeats the orphan-branch cleanup ("Cannot delete branch … checked out at …").
// Ten minutes is far above any healthy add and still bounded. Applies to
// `worktree move` too — it routes through this same wrapper. Removal also
// deletes the full checkout (including ignored output), so it uses this ceiling
// to avoid leaving a partially deleted tree when the metadata timeout expires.
//
// EXPORTED because it is the ceiling `STALE_GIT_LOCK_MIN_AGE_MS` is sized
// against: the longest a git command PortOS launches can legitimately still be
// holding its lock. Raising this without raising that one would let the
// stale-lock sweep delete a live checkout's lock — the test below pins it.
export const WORKTREE_ADD_TIMEOUT_MS = 10 * 60 * 1000;

/**
 * True when a git error message indicates lock/contention on the worktree or
 * index lock (as opposed to a genuine, non-retryable failure like a bad ref,
 * a pre-existing branch, or an existing worktree path — retrying those just
 * wastes the retry budget and spams misleading "lock contention" logs, #2193).
 * Deliberately does NOT match bare "File exists" / "already exists": the
 * canonical lock error is `Unable to create '…/index.lock': File exists`
 * (caught by `index.lock`), whereas `a branch named 'X' already exists` and
 * `'<path>' already exists` are permanent. Exported for unit testing against
 * real git lock-error wording.
 *
 * The "unable to create" alternative is anchored to a quoted `.lock` path on
 * purpose. A bare `unable to create` also matches git's PER-FILE checkout
 * failure, `error: unable to create file <path>: Permission denied` — exactly
 * what a Windows AV filter driver produces mid-checkout. That is not lock
 * contention and does not clear on retry, but it IS reached only after git has
 * written most of the tree, so matching it spent the whole retry budget on
 * repeated full checkouts: with WORKTREE_ADD_TIMEOUT_MS that is 4 × 10 min of
 * head-of-line blocking on the per-repo queue for a permanent failure. The
 * retry budget is sized for bookkeeping-lock failures, which fail in
 * milliseconds.
 */
export function isGitLockError(message) {
  return /index\.lock|cannot lock|could not lock|unable to create '[^']*\.lock'|unable to (?:write|lock)|already locked|another git process/i.test(message || '');
}

/**
 * True when `git worktree add` refused because the branch is ALREADY checked out
 * in some other worktree — `fatal: '<branch>' is already used by worktree at
 * '<path>'` on current git, `is already checked out at '<path>'` on older ones.
 *
 * This is a TRANSIENT condition, not a misconfiguration: the only routine
 * producer is a cleanup still tearing down the previous agent's worktree while
 * the follow-up spawned to land its PR is already prepping (the two ran ~0.7s
 * apart in the incident that motivated this). Callers use it to pause and retry
 * rather than blocking the task, which stranded the pull request the follow-up
 * existed to merge.
 *
 * Deliberately NOT folded into `isGitLockError`: that predicate drives the
 * in-process add retry, whose budget is sized in milliseconds for bookkeeping
 * locks. Waiting out another worktree's teardown belongs at the task level.
 */
export function isBranchCheckedOutElsewhereError(message) {
  return /already (?:used by worktree|checked out) at/i.test(message || '');
}

/**
 * Run `git worktree add …` with retry on lock contention. Promise-chained
 * (no try/catch) so it stays idiomatic with the rest of the module: on a lock
 * error it backs off and recurses until WORKTREE_ADD_MAX_ATTEMPTS, then lets
 * the final error reject. Non-lock errors (bad base ref, etc.) reject
 * immediately — retrying them just wastes time.
 *
 * The FIRST attempt's error is preserved on the final rejection as
 * `err.firstAttemptError` so orphan-branch cleanup can reason about the
 * ORIGINAL failure cause: a `-b` add that created the branch and then hit a
 * lock error would fail attempt 2 with a retry-induced `branch already
 * exists`, and cleanup must NOT mistake that for "the branch pre-dated us"
 * (#2193) — the branch is exactly the orphan it needs to delete.
 */
export async function addWorktreeWithRetry(args, repo, attempt = 1, firstError = null) {
  const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
  return withCheckoutPublication(repo, () => addWorktreeAdmitted(args, repo, attempt, firstError));
}

function addWorktreeAdmitted(args, repo, attempt, firstError) {
  return execGit(args, repo, { timeout: WORKTREE_ADD_TIMEOUT_MS }).catch((err) => {
    const originalError = firstError || err;
    if (attempt >= WORKTREE_ADD_MAX_ATTEMPTS || !isGitLockError(err.message)) {
      err.firstAttemptError = originalError;
      throw err;
    }
    // The retry budget above assumes CONTENTION — a live competitor that will
    // release the lock within a second. An ABANDONED lock (a killed git process
    // never removed it) releases never, so all four attempts fail and the task
    // blocks with `worktree-failed` on a repo nothing is actually using. Clear
    // it before backing off; `clearStaleGitLock` refuses anything young enough
    // to still belong to a running command, so a real competitor is untouched.
    clearStaleGitLock(err.message);
    console.log(`🌳 Worktree ${args[1] || 'add'} lock contention (attempt ${attempt}/${WORKTREE_ADD_MAX_ATTEMPTS}), retrying in ${WORKTREE_ADD_RETRY_DELAY_MS}ms: ${err.message}`);
    return sleep(WORKTREE_ADD_RETRY_DELAY_MS)
      .then(() => addWorktreeWithRetry(args, repo, attempt + 1, originalError));
  });
}

// Per-source-repo serialization tail for worktree-creating git operations —
// the createKeyCachedQueue pattern (see server/services/pipeline/issuesShared.js). Git
// serializes its own worktree bookkeeping behind a per-repo lock, so two
// `git worktree add` calls in the same evaluation tick race and the loser is
// blocked with `blockedCategory: worktree-failed` (#2193). A single promise
// tail per repo collapses that race: each create awaits the previous one to
// settle before touching the shared `.git/worktrees` state. Keyed by
// realpath-resolved repo path so /var vs /private/var (macOS) don't split the
// tail into two lanes that can still collide.
const queueWorktreeCreateForKey = createKeyCachedQueue();
async function queueWorktreeCreate(repo, fn) {
  // Linked checkouts share branch refs even when their working paths differ.
  // Resolve that common identity before entering the mutation lane.
  const common = await execGit(['rev-parse', '--path-format=absolute', '--git-common-dir'], repo)
    .then(result => result.stdout.trim()).catch(() => null);
  let key = common && isAbsolute(common) ? common : repo;
  try { key = realpathSync(key); } catch { /* invalid repositories fail in the operation itself */ }
  if (!key) key = '__unknown__';
  return queueWorktreeCreateForKey(key, async () => {
    const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
    return withCheckoutPublication(repo, () => fn(common));
  });
}

/** Delete one completed local ref through Git's receiver. Unlike update-ref,
 * receive-pack checks all registered worktree holders; unlike branch -D, its
 * transaction also compares the old object id. The local absolute destination
 * cannot resolve through an origin push URL. Existing hooks and denyDeletes
 * policy still apply. Share the creation lane so managed attachments cannot
 * enter between the receiver's holder check and ref transaction. After the ref
 * is gone, the local branch section is removed so a reused name does not
 * inherit retired settings. Nothing is copied under branch-retirement-archives.
 * `onRetired` runs only after that deletion.
 */
export function deleteCompletedLocalBranch(repoPath, branch, expectedHead, { beforeMutation = async () => {}, onRetired = async () => {} } = {}) {
  let callbackError;
  return queueWorktreeCreate(repoPath, async (commonDir) => {
    if (PROTECTED_BRANCHES.includes(branch)) return false;
    const { getDefaultBranch } = await import('./git.js');
    const defaultBranch = await getDefaultBranch(repoPath, { strict: true }).catch(() => null);
    if (!defaultBranch || branch === defaultBranch) return false;
    if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(expectedHead || '')) return false;
    const ref = `refs/heads/${branch}`;
    if ((await execGit(['check-ref-format', ref], repoPath, { ignoreExitCode: true })).exitCode !== 0) return false;
    const common = (commonDir && isAbsolute(commonDir)) ? commonDir
      : (await execGit(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoPath)).stdout.trim();
    if (!isAbsolute(common)) return false;
    const head = (await execGit(['rev-parse', '--verify', ref], repoPath).catch(() => null))?.stdout?.trim();
    if (head !== expectedHead) return false;
    await Promise.resolve().then(beforeMutation).catch(error => { callbackError = error; throw error; });
    const result = await execGit(['push',
      '--receive-pack=git -c receive.denyCurrentBranch=refuse -c receive.denyDeleteCurrent=refuse -c receive.autogc=false receive-pack',
      `--force-with-lease=${ref}:${expectedHead}`, '--', common, `:${ref}`], repoPath, { ignoreExitCode: true });
    if (result.exitCode !== 0) return false;
    const absent = await execGit(['show-ref', '--verify', '--quiet', ref], repoPath, { ignoreExitCode: true });
    if (absent.exitCode !== 1) return false;
    await execGit(['config', '--local', '--remove-section', `branch.${branch}`], repoPath, { ignoreExitCode: true }).catch(() => {});
    await Promise.resolve().then(() => onRetired({ branchDeleted: true })).catch(error => { callbackError = error; throw error; });
    return true;
  }).catch(error => { if (error === callbackError) throw error; return false; });
}

/**
 * A git error saying the target BRANCH already exists (`fatal: a branch named
 * 'X' already exists`) — a permanent precondition failure meaning the ref
 * PRE-DATED this add and git created nothing, so it is NOT an orphan this add
 * left behind. cleanupOrphanBranch keys off this to avoid `git branch -D`-ing
 * a branch it didn't create (#2193).
 *
 * Deliberately NARROW: it must NOT match `'<path>' already exists` (the
 * worktree DIRECTORY was occupied), because in that case `git worktree add -b`
 * has ALREADY created the branch before failing on the path — so that branch
 * IS an orphan and must be cleaned up. Only the branch-named wording is safe
 * to skip on.
 */
export function isPreexistingRefError(message) {
  return /branch (?:named )?['`]?[^'`\n]*['`]? ?already exists/i.test(message || '');
}

/**
 * Delete a branch a failed `git worktree add -b/-B` left orphaned (a ref with
 * no worktree), so failed adds don't accumulate orphan branches (#2193).
 * Best-effort: every step swallows its own error. Only call for NEW-branch
 * adds — never for attach-to-existing-branch, which would delete a branch we
 * didn't create.
 *
 * Takes the causing error so it can:
 *   - SKIP entirely when the add failed because the branch already existed
 *     (`isPreexistingRefError`) — that branch pre-dated us and may hold real
 *     commits; deleting it would be data loss. This keys off the FIRST
 *     attempt's error (`err.firstAttemptError`), not the final one: a retried
 *     `-b` add that created the branch on attempt 1 then failed with a
 *     retry-induced `branch already exists` on attempt 2 must still clean up
 *     the orphan branch it created (#2193).
 *   - PRUNE before deleting: a partial add can register a stale worktree AND
 *     create the branch, so a bare `git branch -D` fails with "used by
 *     worktree". `worktree prune` first clears that registration so the delete
 *     succeeds.
 */
async function cleanupOrphanBranch(repo, branchName, err) {
  if (!branchName) return;
  // The original failure cause decides whether the branch pre-dated us — a
  // later attempt's `already exists` can be self-inflicted by attempt 1.
  const causeError = err?.firstAttemptError || err;
  if (isPreexistingRefError(causeError?.message)) return;
  await execGit(['worktree', 'prune'], repo).catch(() => {});
  await execGit(['branch', '-D', branchName], repo).catch(pruneErr => {
    console.log(`⚠️ Orphan branch cleanup failed for ${branchName}: ${pruneErr.message}`);
  });
}

/** Longest error excerpt a removal warning carries — warnings reach cards and task context. */
const REMOVAL_ERROR_EXCERPT_CHARS = 200;

/** First line of an error, bounded, for a one-line warning. */
function errorExcerpt(err) {
  return String(err?.message ?? err ?? '').split('\n')[0].slice(0, REMOVAL_ERROR_EXCERPT_CHARS);
}

/**
 * Realpath of `p` even when `p` itself is gone: resolve the deepest existing
 * ancestor and re-append the missing tail, so a removed worktree compares equal
 * to the form git registered it under (macOS /var → /private/var).
 */
function canonicalPath(p) {
  try { return realpathSync.native(p); } catch { /* fall through to the ancestor walk */ }
  const parent = dirname(p);
  return parent === p ? p : join(canonicalPath(parent), p.slice(parent.length).replace(/^[\\/]+/, ''));
}

/**
 * Observe whether a worktree's directory and Git registration are really gone.
 * Each probe answers `'unknown'` when it could not be read — an unverifiable
 * state is NOT absence, so callers never report cleanup they did not establish.
 *
 * @returns {Promise<{directory: 'present'|'absent'|'unknown', registration: 'registered'|'absent'|'unknown'}>}
 */
async function probeWorktreeRemoval(repo, worktreePath) {
  const directory = await lstat(worktreePath).then(
    () => 'present',
    (err) => (err?.code === 'ENOENT' || err?.code === 'ENOTDIR' ? 'absent' : 'unknown'),
  );
  const target = canonicalPath(worktreePath);
  let entries = null;
  const registration = await listWorktrees(repo).then(
    (list) => {
      entries = list;
      return list.some(wt => canonicalPath(wt.path) === target) ? 'registered' : 'absent';
    },
    () => 'unknown',
  );
  return { directory, registration, entries };
}

/**
 * Fold a probe into the removal outcome every caller consumes. `removed` is true
 * only when BOTH the directory and the registration were observed absent;
 * `warning` is a bounded, retryable one-liner when they were not.
 */
function removalOutcome(worktreePath, { directory, registration }, failure = null) {
  const removed = directory === 'absent' && registration === 'absent';
  const state = `directory ${directory === 'absent' ? 'removed' : directory === 'present' ? 'still present' : 'unverified'}, `
    + `git registration ${registration === 'absent' ? 'removed' : registration === 'registered' ? 'still registered' : 'unverified'}`;
  return {
    removed,
    directory,
    registration,
    warning: removed ? null : `Worktree cleanup incomplete for ${worktreePath} (${state})${failure ? `: ${failure}` : ''} — retryable`,
  };
}

/**
 * Remove a worktree directory robustly: try `git worktree remove --force`, and
 * if git refuses, preserve surviving contents and only prune an absent tree.
 * Git's lock-aware remove is the only operation allowed to delete a checkout.
 * Never throws — cleanup is best-effort and must never throw into a
 * completion/reap path — but it DOES report what it achieved: after every
 * attempt it re-reads the exact directory and its Git registration, and
 * `removed` is true only when both are observed gone. A caller that releases a
 * branch, counts a reap or queues a follow-up must gate on `removed`; swallowing
 * the failure is how a checkout that survived read as a completed cleanup.
 * Shared by removeWorktree, removePersistentWorktree, reapMergedWorktrees,
 * branch reconciliation and the worktree-add rollback.
 *
 * @param {string} repo - the git workspace to run worktree commands in (the
 *   parent repo for the worktree, NOT the worktree dir itself).
 * @param {string} worktreePath - absolute path of the worktree dir to remove.
 * @param {object} [opts]
 * @param {string} [opts.label] - traceability tag for the fallback log line
 *   (`⚠️ <label>: <err>`). Required for any logging; omit for a fully silent
 *   cleanup (background paths that must not spam on the common case).
 * @param {'remove'|'all'} [opts.log='remove'] - how much to log when `label` is
 *   set: `'remove'` logs only the `worktree remove` failure (the operator-
 *   facing signal); `'all'` also logs a prune failure. Ignored when
 *   `label` is absent (nothing logs). The two flags the four callers needed —
 *   "label + log everything" and "label + log remove only" and "silent" — are
 *   the three states here; there was never a "log without a label" caller.
 * @param {string} [opts.subject] - identifier embedded in prune
 *   failure messages (only used when `log:'all'`). Defaults to
 *   `worktreePath`; the agent-cleanup callers pass their agent id so the
 *   message wording stays byte-identical to the pre-extraction logs an operator
 *   may grep for (e.g. `… for worktree <agentId>`).
 * @param {(holder: object|null) => Promise<string|null>} [opts.verifyRemoval] -
 *   caller's fresh ownership/content gate, run before Git removal and rechecked
 *   after a refusal to report the current hold.
 *   Callers that share claim ownership hold its lock through this operation.
 * @returns {Promise<{removed: boolean, directory: string, registration: string, warning: string|null}>}
 *   `warning` is set exactly when `removed` is false.
 */
export async function forceRemoveWorktreeDir(repo, worktreePath, opts = {}) {
  const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
  return withCheckoutPublication(repo, () => forceRemoveWorktreeDirAdmitted(repo, worktreePath, opts))
    .catch(error => ({ removed: false, reason: error.message, warning: 'Checkout retained: repository reservation unavailable' }));
}

// Hold reasons that mean the cleanup could not even decide, rather than a gate declining.
const REMOVAL_FAULT_HOLDS = new Set(['worktree-ownership-unreadable', 'worktree-removal-refused']);

async function forceRemoveWorktreeDirAdmitted(repo, worktreePath, { label, log = 'remove', subject = worktreePath, verifyRemoval, beforeMutation = async () => {} } = {}) {
  const logAll = label && log === 'all';
  let lastFailure = null;
  let heldReason = null;
  const check = async () => {
    const entries = await listWorktrees(repo).catch(() => null);
    if (!entries) return 'worktree-ownership-unreadable';
    const holder = entries.find(wt => canonicalPath(wt.path) === canonicalPath(worktreePath)) || null;
    if (holder?.locked) return 'worktree-locked';
    if (!verifyRemoval) return null;
    const reason = await verifyRemoval(holder, entries).catch(() => 'worktree-ownership-unreadable');
    if (reason) return reason;
    // Ownership/content checks await I/O. Refresh their registration afterward;
    // Git's own removal still honors locks acquired after this final read.
    const fresh = await listWorktrees(repo).catch(() => null);
    if (!fresh) return 'worktree-ownership-unreadable';
    const current = fresh.find(wt => canonicalPath(wt.path) === canonicalPath(worktreePath)) || null;
    if (current?.locked) return 'worktree-locked';
    if (current?.branch !== holder?.branch || current?.head !== holder?.head) return 'worktree-holder-changed';
    return null;
  };
  heldReason = await check();
  if (!heldReason) await beforeMutation();
  if (!heldReason) await execGit(['worktree', 'remove', worktreePath, '--force'], repo, { timeout: WORKTREE_ADD_TIMEOUT_MS }).catch(async (err) => {
    lastFailure = errorExcerpt(err);
    if (label) console.log(`⚠️ ${label}: ${err.message}`);
    heldReason = await check();
    if (heldReason) return;
    // A refusal is not authority to erase a surviving checkout. A raw rm could
    // bypass a lock acquired after our last read, even with a caller guard.
    const directory = await lstat(worktreePath).then(() => 'present', err => err.code === 'ENOENT' ? 'absent' : 'unknown');
    if (directory !== 'absent') { heldReason = 'worktree-removal-refused'; return; }
    await beforeMutation();
    await execGit(['worktree', 'prune'], repo).catch((pruneErr) => {
      lastFailure = errorExcerpt(pruneErr);
      if (logAll) console.log(`⚠️ Worktree prune failed for ${subject}: ${pruneErr.message}`);
    });
  });
  const probe = await probeWorktreeRemoval(repo, worktreePath);
  const outcome = removalOutcome(worktreePath, probe, heldReason || lastFailure);
  if (probe.entries) outcome.entries = probe.entries;
  if (heldReason) outcome.reason = heldReason;
  if (!outcome.removed && label) {
    // A gate keeping the checkout is the cleanup working as designed (the warning
    // says "retryable"); an unreadable registry or a removal Git refused is a fault.
    const designedHold = heldReason && !REMOVAL_FAULT_HOLDS.has(heldReason);
    if (designedHold) console.log(`⏸️ ${outcome.warning}`);
    else console.warn(`⚠️ ${outcome.warning}`);
  }
  return outcome;
}

/**
 * Run the upstream guard on a branch whose worktree ALREADY exists, undoing the
 * add if the guard refuses (#4172).
 *
 * `enforceSafeBranchUpstream` throws when a branch's upstream still aims at a
 * foreign ref after repair — correct, because every downstream push helper would
 * land there. But the throw happens AFTER `git worktree add` succeeded, so
 * without this the caller gets a failed create while a registered worktree (and,
 * for a fresh `-b` add, an orphan branch) stays on disk: exactly the debris
 * `cleanupOrphanBranch` already prevents on the add itself.
 *
 * `deleteBranch` is false on the attach paths — that branch pre-dates this add
 * and may hold real commits, the same distinction `cleanupOrphanBranch` makes.
 */
async function enforceUpstreamOrUndoAdd(sourceWorkspace, branchName, worktreePath, { deleteBranch, remoteBranch = branchName, forkRemote = null }) {
  const configure = async () => {
    if (forkRemote) {
      await execGit(['config', `branch.${branchName}.remote`, forkRemote], worktreePath);
      await execGit(['config', `branch.${branchName}.merge`, `refs/heads/${remoteBranch}`], worktreePath);
      await execGit(['config', `branch.${branchName}.pushRemote`, forkRemote], worktreePath);
    }
    return enforceSafeBranchUpstream(sourceWorkspace, branchName, { remoteBranch });
  };
  return configure().catch(async (err) => {
    const undone = await forceRemoveWorktreeDir(sourceWorkspace, worktreePath, {
      label: `Undoing worktree add for ${branchName} after an unsafe upstream`,
      log: 'all',
      subject: branchName,
    });
    // A branch still held by the surviving checkout cannot be deleted; leave it
    // rather than attempt a `branch -D` that fails. The ORIGINAL error is what
    // the caller sees either way — the rollback outcome never replaces it.
    if (deleteBranch && undone.removed) await cleanupOrphanBranch(sourceWorkspace, branchName, err);
    throw err;
  });
}

/**
 * Classify a `git status --porcelain` blob into real changes vs auto-generated
 * lockfile churn. Pure (testable) — callers decide what to do with the result.
 *
 * PortOS's own runtime scratch (`AGENT_SCRATCH_PATHS` — the public-review input
 * bundle and its patch directory) is subtracted for EVERY caller, not passed in
 * per call. It is written by PortOS into the worktree and never committed, so a
 * tree holding only that is finished work by every consumer's definition; making
 * each one learn the names is how two `pr-reviewer` worktrees survived
 * `removeWorktree`, `reapMergedWorktrees` and branch-reconcile in turn.
 *
 * @param {string} porcelain - raw `git status --porcelain` stdout
 * @param {object} [options]
 * @param {string[]} [options.ignoredPaths] - ADDITIONAL runtime-only paths that
 *   must not preserve a completed worktree — for names this module cannot know
 *   statically, notably one run's own `.agent-done-<agentId>` sentinel. Matched
 *   as roots: a directory entry also covers everything under it. They are still
 *   removed only when the rest of the tree is safe to remove.
 * @param {{ ignoredPaths?: string[], preserveLockfiles?: boolean }} [opts] - `preserveLockfiles` classifies lockfiles as real changes
 * @returns {{ clean: boolean, lockfileOnly: boolean, lockfilePaths: string[], untrackedLockfilePaths: string[], realChangePaths: string[], hasRealChanges: boolean }}
 *   - clean: no changes at all
 *   - lockfileOnly: every change is an auto-generated lockfile (safe to discard)
 *   - lockfilePaths: paths of those lockfiles (strip the porcelain `XY ` status prefix)
 *   - untrackedLockfilePaths: the subset of lockfilePaths that is untracked (`??`)
 *   - realChangePaths: paths of the NON-lockfile changes, same prefix stripping.
 *     Branch reconciliation intersects these with what the default branch has
 *     touched since the branch diverged, to spot work that may have been
 *     superseded while it sat uncommitted.
 *   - hasRealChanges: at least one non-lockfile change (worktree must be preserved)
 */
export function classifyWorktreeDirt(porcelain, { ignoredPaths = [], preserveLockfiles = false } = {}) {
  const ignored = [...AGENT_SCRATCH_PATHS, ...ignoredPaths];
  // Git's porcelain v1 output C-quotes paths with spaces and several other
  // characters. Decode those paths before comparing them with scratch roots or
  // lockfile names. Octal escapes represent bytes, so collect them as bytes and
  // decode UTF-8 only after the whole quoted path has been read.
  const unquoteGitPath = (path) => {
    if (!path.startsWith('"') || !path.endsWith('"')) return path;
    const bytes = [];
    for (let i = 1; i < path.length - 1; i += 1) {
      const char = path[i];
      if (char !== '\\') {
        const codePoint = String.fromCodePoint(path.codePointAt(i));
        bytes.push(...Buffer.from(codePoint));
        i += codePoint.length - 1;
        continue;
      }
      const escaped = path[++i];
      if (/[0-7]/.test(escaped || '')) {
        const octal = path.slice(i, i + 3);
        if (!/^[0-7]{3}$/.test(octal)) {
          bytes.push(...Buffer.from(`\\${escaped}`));
          continue;
        }
        bytes.push(parseInt(octal, 8));
        i += 2;
        continue;
      }
      const controls = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13 };
      if (Object.hasOwn(controls, escaped)) bytes.push(controls[escaped]);
      else bytes.push(...Buffer.from(escaped || ''));
    }
    return Buffer.from(bytes).toString('utf8');
  };
  const splitRename = (path) => {
    let quoted = false;
    let escaped = false;
    for (let i = 0; i <= path.length - 4; i += 1) {
      const char = path[i];
      if (escaped) { escaped = false; continue; }
      if (quoted && char === '\\') { escaped = true; continue; }
      if (char === '"') { quoted = !quoted; continue; }
      if (!quoted && path.startsWith(' -> ', i)) return [path.slice(0, i), path.slice(i + 4)];
    }
    return [path];
  };
  const toPath = (line) => {
    const statusless = line.replace(/^\s*\S+\s+/, '');
    return splitRename(statusless).map(unquoteGitPath).at(-1);
  };
  const lines = (porcelain || '').split('\n')
    .filter(l => l.trim())
    .filter(line => !matchesScratchRoot(toPath(line), ignored));
  if (lines.length === 0) {
    return { clean: true, lockfileOnly: false, lockfilePaths: [], untrackedLockfilePaths: [], realChangePaths: [], hasRealChanges: false };
  }
  // `dependency-updates` can legitimately deliver a lockfile-only diff (`npm audit
  // fix`, a transitive bump), so there a lockfile is work, never churn.
  const isLockfile = (line) => !preserveLockfiles && AUTO_GENERATED_LOCKFILES.some(f => toPath(line).endsWith(f));
  // `R old -> new` (rename) names two paths; the post-rename path is the one
  // that exists on disk and the one a diff against the default branch reports.
  const lockfileLines = lines.filter(isLockfile);
  const lockfileOnly = lockfileLines.length === lines.length;
  return {
    clean: false,
    lockfileOnly,
    lockfilePaths: lockfileLines.map(toPath),
    // Untracked (`??`) lockfiles have no index entry, so `git checkout --` cannot
    // restore them; discardLockfileChanges deletes these instead.
    untrackedLockfilePaths: lockfileLines.filter(line => line.startsWith('??')).map(toPath),
    realChangePaths: lines.filter((line) => !isLockfile(line)).map(toPath),
    hasRealChanges: !lockfileOnly
  };
}

/**
 * Discard the auto-generated lockfile churn that `classifyWorktreeDirt` reported.
 * Untracked lockfiles are deleted (git cannot restore what it does not track);
 * tracked ones are restored from the index. Rejects if either step fails, so the
 * caller decides whether the tree is still safe to remove.
 */
async function discardLockfileChanges(worktreePath, dirt) {
  const untracked = new Set(dirt.untrackedLockfilePaths);
  for (const path of untracked) {
    await rm(join(worktreePath, path), { force: true });
  }
  const tracked = dirt.lockfilePaths.filter(path => !untracked.has(path));
  if (tracked.length) await execGit(['checkout', '--', ...tracked], worktreePath);
}

/** A proven-absent directory is empty; an existing tree must identify itself.
 * Git can otherwise walk out of a broken linked checkout and report its parent
 * clean. null means unknown, including unreadable directories or status errors.
 */
export async function readWorktreeStatus(worktreePath) {
  const present = await lstat(worktreePath).then(() => true,
    err => err.code === 'ENOENT' || err.code === 'ENOTDIR' ? false : null);
  if (present === false) return '';
  if (present === null) return null;
  const top = await execGit(['rev-parse', '--show-toplevel'], worktreePath).then(r => r.stdout.trim()).catch(() => null);
  if (!top || !pathsEqual(top, worktreePath)) return null;
  const status = await execGit(['status', '--porcelain', '--untracked-files=all', '--ignore-submodules=none'], worktreePath,
    { ignoreExitCode: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } }).catch(() => null);
  return status?.exitCode === 0 ? status.stdout : null;
}

/**
 * Compare two filesystem paths for equality, resolving symlinks (e.g. macOS
 * /var → /private/var) and Windows short-name aliases. Native realpath resolves
 * the latter where the JavaScript implementation can retain the input spelling.
 */
function pathsEqual(a, b) {
  if (!a || !b) return false;
  if (a === b) return true;
  const resolved = (p) => { try { return realpathSync.native(p); } catch { return p; } };
  return resolved(a) === resolved(b);
}

/**
 * Decide whether an auto-merge into `currentBranch` should be refused.
 *
 * Pure helper for the defense-in-depth gate in `removeWorktree`: an agent's
 * branch must NEVER be merged into a feature/claim branch — only into the
 * source repo's configured default (`main`, `master`, etc.). When the user
 * is mid-claim on `claim/foo`, a CoS task finishing its work must not
 * fast-forward `claim/foo` onto the agent's branch. The PR flow
 * (`gh pr merge`) is the only sanctioned integration path for non-default
 * targets.
 *
 * Returns `true` when the caller must skip the merge and preserve the
 * agent's branch for manual / PR-driven integration. Falsy default branch
 * means detection failed — refuse rather than guess, since the worst-case
 * cost of a refusal (preserved branch) is much smaller than the worst-case
 * cost of a wrong merge (clobbered user work).
 */
export function shouldRefuseDefaultBranchMerge(currentBranch, defaultBranch) {
  if (!currentBranch) return true;
  if (!defaultBranch) return true;
  return currentBranch !== defaultBranch;
}

/**
 * Point a deterministic remote at the fork that holds a cross-repository PR's
 * head branch, fetch that branch, and hand back the remote's name.
 *
 * A fork PR's branch has no `origin/<branch>` — the forge exposes its tip only
 * as the read-only `refs/pull/<n>/head`, which cannot be pushed back to — so a
 * worktree attach needs a second address for it. The coordinates arrive from a
 * caller that already read the PR (`normalizeForkHead`); this layer never calls
 * a forge, which is why it takes a URL rather than a PR number.
 *
 * The remote is named from the OWNER, not from the run, so a second review
 * round or a retried remediation reuses it instead of accumulating one remote
 * per attach — and so teardown can leave it alone, which is what makes that
 * reuse free. An existing remote pointing somewhere else is re-pointed rather
 * than treated as a conflict.
 *
 * Returns `null` for every unusable outcome (no coordinates, remote wouldn't
 * take, fetch failed, ref still missing afterwards) so the caller falls through
 * to its existing origin-only error instead of attaching to a ref it cannot
 * verify.
 *
 * @param {string} sourceWorkspace - the parent git repository
 * @param {unknown} forkHead - `{ remoteUrl, ownerLogin }` from the PR read
 * @param {string} branchName - the PR's head branch, as named in the fork
 * @param {{requireRef?: boolean}} options - existing local recovery needs only the remote configuration
 * @returns {Promise<string|null>} the fork remote's name, or null
 */
async function ensureForkRemote(sourceWorkspace, forkHead, branchName, { requireRef = true } = {}) {
  const remoteName = await pointForkRemote(sourceWorkspace, forkHead, branchName);
  if (!remoteName) return null;

  await execGit(['fetch', remoteName, branchName], sourceWorkspace).catch(err => {
    console.log(`⚠️ Fork fetch of ${remoteName}/${branchName} failed: ${err.message}`);
  });
  // Verify rather than trust the fetch's exit code: a fetch that reported
  // success but left no remote-tracking ref would otherwise send `worktree add`
  // at a start point git resolves somewhere else entirely.
  const refExists = await execGit(['rev-parse', '--verify', `${remoteName}/${branchName}`], sourceWorkspace, { ignoreExitCode: true })
    .then(r => r.exitCode === 0)
    .catch(() => false);
  return refExists || !requireRef ? remoteName : null;
}

/** Add or re-point the deterministic fork remote; its name, or null. */
async function pointForkRemote(sourceWorkspace, forkHead, branchName) {
  const coordinates = normalizeForkHead(forkHead);
  if (!coordinates) return null;
  const remoteName = forkRemoteName(coordinates.ownerLogin);
  if (!remoteName) return null;

  // Three outcomes, not two: `null` is "no such remote" (add it), an equal URL
  // is "already correct" (touch nothing), and a different URL is a stale remote
  // from a contributor who renamed or moved their fork (re-point it).
  const existingUrl = await execGit(['remote', 'get-url', remoteName], sourceWorkspace, { ignoreExitCode: true })
    .then(r => (r.exitCode === 0 ? (r.stdout || '').trim() : null))
    .catch(() => null);
  const remoteOp = existingUrl === null
    ? ['remote', 'add', remoteName, coordinates.remoteUrl]
    : (existingUrl === coordinates.remoteUrl ? null : ['remote', 'set-url', remoteName, coordinates.remoteUrl]);
  if (remoteOp) {
    const pointed = await execGit(remoteOp, sourceWorkspace).then(() => true).catch(err => {
      console.log(`⚠️ Could not point ${remoteName} at the fork holding ${branchName}: ${err.message}`);
      return false;
    });
    if (!pointed) return null;
  }
  return remoteName;
}

/** `err.code` when a pinned attach finds the branch tip is not the reviewed commit. */
export const PINNED_HEAD_MOVED = 'PINNED_HEAD_MOVED';

function requirePinnedHeadSha(value) {
  const sha = typeof value === 'string' ? value.trim().toLowerCase() : '';
  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(sha)) throw new Error('Invalid pinned head commit');
  return sha;
}

function pinnedHeadMoved(branchName, pinnedHead, actual) {
  const err = new Error(`Cannot attach worktree to ${branchName}: the branch is ${actual ? `at ${actual}` : 'gone'}, not the reviewed head ${pinnedHead}`);
  err.code = PINNED_HEAD_MOVED;
  err.actualHeadSha = actual || null;
  return err;
}

/**
 * Attach `branchName` from `remote` at exactly `pinnedHead`, the commit that was
 * reviewed — the attached code is then executed, so nothing else may land.
 *
 * The tip comes from the remote itself (`ls-remote`), never a cached tracking
 * ref, and a branch the remote no longer has is a moved head too. The fetch
 * names its destination so the tracking ref cannot stay stale under a narrow
 * refspec. The checkout uses the SHA, so a ref update after the check cannot
 * swap code in; an existing local branch must already name that exact commit.
 * `detach` checks the commit out with no branch at all (see `holdsCheckedOutBranch`).
 */
async function attachPinnedHead(sourceWorkspace, worktreePath, branchName, remoteBranch, remote, pinnedHead, localExists, { detach = false } = {}) {
  const listed = await execGit(['ls-remote', '--exit-code', remote, `refs/heads/${remoteBranch}`], sourceWorkspace, { ignoreExitCode: true });
  // `--exit-code` answers 2 for "no such ref"; anything else non-zero is a
  // transport failure, which proves nothing about the branch.
  if (listed.exitCode === 2) throw pinnedHeadMoved(branchName, pinnedHead, null);
  if (listed.exitCode !== 0) throw new Error(`Cannot attach worktree to ${branchName}: could not read ${remote}: ${(listed.stderr || '').trim()}`);
  const remoteTip = (listed.stdout || '').trim().split(/\s+/)[0];
  if (remoteTip !== pinnedHead) throw pinnedHeadMoved(branchName, pinnedHead, remoteTip);

  const trackingRef = `refs/remotes/${remote}/${remoteBranch}`;
  await execGit(['fetch', remote, `+refs/heads/${remoteBranch}:${trackingRef}`], sourceWorkspace);
  const fetched = (await execGit(['rev-parse', '--verify', `${trackingRef}^{commit}`], sourceWorkspace)).stdout.trim();
  if (fetched !== pinnedHead) throw pinnedHeadMoved(branchName, pinnedHead, fetched);

  if (detach) {
    await addWorktreeWithRetry(['worktree', 'add', '--detach', worktreePath, pinnedHead], sourceWorkspace);
  } else if (localExists) {
    const localHead = (await execGit(['rev-parse', '--verify', `refs/heads/${branchName}`], sourceWorkspace)).stdout.trim();
    if (localHead !== pinnedHead) {
      throw new Error(`Cannot attach worktree to ${branchName}: the local branch differs from the reviewed head; preserving it without reset`);
    }
    await addWorktreeWithRetry(['worktree', 'add', worktreePath, branchName], sourceWorkspace);
  } else {
    await addWorktreeWithRetry(['worktree', 'add', '--no-track', '-b', branchName, worktreePath, pinnedHead], sourceWorkspace);
  }
  // A concurrent external ref write must not hand unreviewed code to the agent.
  const attached = (await execGit(['rev-parse', '--verify', 'HEAD'], worktreePath)).stdout.trim();
  if (attached !== pinnedHead) throw pinnedHeadMoved(branchName, pinnedHead, attached);
}

/**
 * Is `branch` one a second worktree must never attach to by name: the repository's
 * default branch, or whatever the primary checkout has checked out? Git refuses the
 * second case outright, and the first is the branch a review fix must never be
 * pushed to without its own pull request (a release PR's head IS the default branch).
 */
async function holdsCheckedOutBranch(sourceWorkspace, branch, baseBranch) {
  const { getDefaultBranch } = await import('./git.js');
  const defaultBranch = baseBranch || await getDefaultBranch(sourceWorkspace, { allowRemote: false }).catch(() => null);
  if (branch === defaultBranch) return { held: true, isDefault: true };
  const current = (await execGit(['rev-parse', '--abbrev-ref', 'HEAD'], sourceWorkspace, { ignoreExitCode: true }).catch(() => null))?.stdout?.trim();
  return { held: current === branch, isDefault: false };
}

/**
 * Detached worktree at the reviewed head of a branch the primary checkout owns.
 * The follow-up can read, test and gate that exact commit; with no branch checked
 * out there is nothing for `git push` to default to and nothing for another
 * worktree to collide with. Fork heads never come here: they attach under their
 * own `fork/<owner>/<branch>` name.
 */
async function attachDetachedHead(sourceWorkspace, worktreePath, branch, pinnedHead, fetchSucceeded) {
  if (pinnedHead) {
    await attachPinnedHead(sourceWorkspace, worktreePath, branch, branch, 'origin', pinnedHead, false, { detach: true });
    return pinnedHead;
  }
  const head = await execGit(['rev-parse', '--verify', `refs/remotes/origin/${branch}^{commit}`], sourceWorkspace, { ignoreExitCode: true })
    .then(r => (r.exitCode === 0 ? r.stdout.trim() : ''), () => '');
  if (!head) throw new Error(`Cannot attach worktree to ${branch}: origin/${branch} unavailable${fetchSucceeded ? '' : ' (fetch failed)'}`);
  await addWorktreeWithRetry(['worktree', 'add', '--detach', worktreePath, head], sourceWorkspace);
  return head;
}

/**
 * Create a git worktree for an agent.
 *
 * Creates a new branch and worktree directory that the agent can work in
 * without disturbing the main workspace.
 *
 * For managed apps, the worktree is based on the latest remote default branch
 * (main/master) to ensure a clean starting point free from other agents' changes.
 *
 * When `options.existingBranch` is provided, the worktree tracks that pre-existing
 * branch instead of creating a new one — used for the Copilot review-loop follow-up
 * agent that needs to address comments on a PR branch the previous agent just pushed.
 *
 * Fork heads resolve only through their fork and use a namespaced local branch.
 * Same-repository heads retain local → origin resolution.
 *
 * @param {string} agentId - The agent identifier (used for branch/directory naming)
 * @param {string} sourceWorkspace - The original git repository path
 * @param {string} taskId - Task identifier (included in branch name for traceability)
 * @param {object} options - Optional configuration
 * @param {string} options.baseBranch - Branch to base the worktree on (auto-detected if omitted)
 * @param {string} options.baseCommit - Exact server-owned source commit for a fresh Deep resume
 * @param {string} options.existingBranch - Pre-existing branch to attach (creates from origin/<branch> if no local copy). When it is the default branch or the primary checkout's own branch the worktree is DETACHED at the branch's reviewed head instead (`detached: true` in the result).
 * @param {string} options.resumeBranch - Exact preserved local branch from a retry, including pre-namespace fork branches
 * @param {{remoteUrl: string, ownerLogin: string}} options.forkHead - Where `existingBranch` lives for a fork PR; checked out as fork/<owner>/<branch>.
 * @param {string} options.expectedHeadSha - Attach only at the reviewed remote tip; existing local work is never reset.
 * @param {string} options.planId - PLAN.md item slug ID — when provided, spliced into the branch name as `cos/<taskId>/<planId>/<agentId>` so other agents can detect this item is in flight by scanning branches/PRs
 * @param {boolean} options.linkDependencies - Link source dependencies unless explicitly false
 * @returns {{ worktreePath: string, branchName: string, baseBranch: string|null, existingBranch?: boolean }} paths for the new worktree
 */
export async function createWorktree(agentId, sourceWorkspace, taskId, options = {}) {
  // Serialize per source repo so two adds in the same evaluation tick can't
  // race on git's per-repo worktree lock (#2193). The whole body runs inside
  // the tail — not just the add — because the leading `git fetch origin` also
  // touches the shared ref store and two concurrent fetches on the same repo
  // can themselves hit `cannot lock ref` contention. Same-repo spawn prep is
  // low-frequency (a handful of tasks per tick), so serializing the fetch is a
  // cheap, safe trade for the race guarantee. See queueWorktreeCreate.
  return queueWorktreeCreate(sourceWorkspace, () => createWorktreeUnlocked(agentId, sourceWorkspace, taskId, options));
}

async function createWorktreeUnlocked(agentId, sourceWorkspace, taskId, options = {}) {
  if (!existsSync(WORKTREES_DIR)) {
    await ensureDir(WORKTREES_DIR);
  }

  const worktreePath = join(WORKTREES_DIR, agentId);

  // Stamp the producing machine's federation identity onto the worktree
  // metadata (issue #1563, acceptance criterion 1). The branch is named
  // `cos/<taskId>/<agentId>`, so recording which instance created it lets a
  // federated node pair attribute every worktree/branch to its origin instance
  // once CoS history federates. `ensureInstanceId()` creates the identity on the
  // cold path so the worktree is never tagged `unknown`.
  const instanceId = await ensureInstanceId();

  // Fetch latest from origin so we base off up-to-date refs
  const fetchSucceeded = await execGit(['fetch', 'origin'], sourceWorkspace)
    .then(() => true)
    .catch(err => {
      console.log(`⚠️ Worktree fetch failed (will use local refs): ${err.message}`);
      return false;
    });

  // Existing-branch path: attach the worktree to a branch that already lives on
  // the remote (e.g. the PR branch from the previous agent in a review loop).
  if (options.existingBranch) {
    const remoteBranch = options.existingBranch;
    const pinnedHead = options.expectedHeadSha === undefined ? null : requirePinnedHeadSha(options.expectedHeadSha);
    const forkHead = normalizeForkHead(options.forkHead);
    if (options.forkHead && !forkHead) throw new Error('Invalid fork head coordinates');
    const checkedOut = forkHead || options.resumeBranch
      ? { held: false, isDefault: false }
      : await holdsCheckedOutBranch(sourceWorkspace, remoteBranch, options.baseBranch);
    if (checkedOut.held) {
      const headSha = await attachDetachedHead(sourceWorkspace, worktreePath, remoteBranch, pinnedHead, fetchSucceeded);
      if (options.linkDependencies === false) {
        await unlinkWorktreeDependencies(sourceWorkspace, worktreePath);
      } else {
        await linkWorktreeDependencies(sourceWorkspace, worktreePath);
      }
      console.log(`🌳 Created detached worktree for ${agentId} at ${worktreePath} on ${remoteBranch}@${headSha.slice(0, 12)} (primary checkout holds the branch)`);
      return {
        worktreePath, branchName: remoteBranch, baseBranch: null, existingBranch: true, instanceId,
        detached: true, headSha, headIsDefaultBranch: checkedOut.isDefault,
      };
    }
    const branchName = options.resumeBranch || forkLocalBranch(remoteBranch, forkHead);
    const localExists = (await execGit(['branch', '--list', branchName], sourceWorkspace, { ignoreExitCode: true })).stdout.trim();
    if (options.resumeBranch && !localExists) throw new Error(`Cannot resume missing local branch ${branchName}`);
    // A pin must be verified against the fork itself, never origin's same-named branch.
    const forkRemote = forkHead ? await (pinnedHead ? pointForkRemote(sourceWorkspace, forkHead, remoteBranch)
      : ensureForkRemote(sourceWorkspace, forkHead, remoteBranch, { requireRef: !localExists })) : null;
    if (forkHead && !forkRemote) throw new Error(`Cannot attach worktree to fork branch ${remoteBranch}: fork ref unavailable`);
    if (pinnedHead) {
      await attachPinnedHead(sourceWorkspace, worktreePath, branchName, remoteBranch, forkRemote || 'origin', pinnedHead, !!localExists);
    } else if (localExists) {
      // Preserve unpublished local work. Never reset an existing checkout branch.
      await addWorktreeWithRetry(['worktree', 'add', worktreePath, branchName], sourceWorkspace);
    } else {
      const startPoint = forkRemote ? `${forkRemote}/${remoteBranch}` : `origin/${remoteBranch}`;
      const remoteExists = forkRemote || await execGit(['rev-parse', '--verify', startPoint], sourceWorkspace, { ignoreExitCode: true })
        .then(r => r.exitCode === 0).catch(() => false);
      if (!remoteExists) throw new Error(`Cannot attach worktree to ${branchName}: branch missing locally and origin/${branchName} unavailable${fetchSucceeded ? '' : ' (fetch failed)'}`);
      await addWorktreeWithRetry(['worktree', 'add', ...(forkRemote ? ['--no-track', '-b'] : ['-B']), branchName, worktreePath, startPoint], sourceWorkspace);
    }
    await enforceUpstreamOrUndoAdd(sourceWorkspace, branchName, worktreePath, {
      deleteBranch: false, remoteBranch, forkRemote: forkRemote || (pinnedHead ? 'origin' : null),
    });
    if (options.linkDependencies === false) {
      await unlinkWorktreeDependencies(sourceWorkspace, worktreePath);
    } else {
      await linkWorktreeDependencies(sourceWorkspace, worktreePath);
    }
    console.log(`🌳 Created worktree for ${agentId} at ${worktreePath} on existing branch ${branchName}`);
    return { worktreePath, branchName, baseBranch: null, existingBranch: true, instanceId };
  }

  const branchName = options.planId
    ? `cos/${taskId}/${options.planId}/${agentId}`
    : `cos/${taskId}/${agentId}`;

  // Determine the base: explicit option > remote default branch > current HEAD
  let baseBranch = options.baseBranch;
  if (!baseBranch) {
    const { getDefaultBranch } = await import('./git.js');
    baseBranch = await getDefaultBranch(sourceWorkspace, { allowRemote: fetchSucceeded }).catch(() => null);
    if (!baseBranch) {
      baseBranch = (await execGit(['rev-parse', '--abbrev-ref', 'HEAD'], sourceWorkspace)).stdout.trim();
    }
  }

  // Prefer the remote ref (freshest state) if available
  let baseRef;
  if (options.baseCommit) {
    if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(options.baseCommit)) throw new Error('Invalid pinned source commit');
    // Missing pins fail closed; falling back to moving main would erase coverage.
    baseRef = (await execGit(['rev-parse', '--verify', `${options.baseCommit}^{commit}`], sourceWorkspace)).stdout.trim();
  } else {
    baseRef = await execGit(['rev-parse', `origin/${baseBranch}`], sourceWorkspace)
      .then(() => `origin/${baseBranch}`)
      .catch(() => baseBranch);
  }

  // Create worktree with a new branch based on the latest default branch.
  // `--no-track` is load-bearing, not tidiness (#4172): `baseRef` is normally the
  // remote-tracking `origin/<default>`, and git's default `branch.autoSetupMerge`
  // would record `branch.<name>.merge = refs/heads/main` on the new branch. Push
  // helpers derive their destination from that config — `/do:pr` pushes
  // `HEAD:$(git config branch.<name>.merge)` — so the agent's work lands straight
  // on main, skipping the PR. Untracked is what makes `git push -u origin <branch>`
  // the correct path. See lib/branchUpstreamGuard.js.
  // On final failure, delete the partially-created branch so a failed add
  // doesn't leave an orphan branch with no worktree (#2193).
  await addWorktreeWithRetry(
    ['worktree', 'add', '--no-track', '-b', branchName, worktreePath, baseRef],
    sourceWorkspace
  ).catch(async (err) => {
    await cleanupOrphanBranch(sourceWorkspace, branchName, err);
    throw err;
  });

  // Backstop the flag above — an older git, or a repo-level `branch.autoSetupMerge`
  // setting, must not be able to hand an agent a branch aimed at the default branch.
  await enforceUpstreamOrUndoAdd(sourceWorkspace, branchName, worktreePath, { deleteBranch: true });
  if (options.linkDependencies === false) {
    await unlinkWorktreeDependencies(sourceWorkspace, worktreePath);
  } else {
    await linkWorktreeDependencies(sourceWorkspace, worktreePath);
  }

  console.log(`🌳 Created worktree for ${agentId} at ${worktreePath} (branch: ${branchName}, base: ${baseRef})`);

  return { worktreePath, branchName, baseBranch, instanceId };
}

/**
 * Locate the worktree that currently holds `branchName`, when it is one PortOS
 * may take over — i.e. a tree `adoptWorktree` could legitimately move.
 *
 * `git worktree add` refuses to attach a second tree to a checked-out branch, so
 * a task pointed at an existing branch (a review-loop/merge follow-up, a resume)
 * cannot start while another tree holds it. Usually that holder is the finished
 * run's own worktree, still there because `removeWorktree` won't delete a dirty
 * tree — and it IS that branch's workspace, so adopting it is both the fastest
 * path and the one that preserves the leftover work. Waiting for a teardown that
 * is never coming just strands the pull request the follow-up exists to land.
 *
 * Refuses (returns null) for every holder PortOS doesn't own outright, because
 * adoption MOVES the directory:
 *   - the primary checkout, or any tree outside `data/cos/worktrees/` — moving
 *     the user's own checkout out from under them is exactly the branch-jacking
 *     guarded against everywhere else;
 *   - a human `/claim` tree (`claim-*`), owned by the claim flow's cleanup —
 *     unless the caller passes `allowLiveClaim` (see below);
 *   - a tree whose agent is still running — it is mid-edit in that directory;
 *   - a locked worktree, whose lock means "don't touch" regardless of owner.
 *
 * @param {string} sourceWorkspace - the parent git repository
 * @param {string} branchName - branch to find a holder for (no `refs/heads/`)
 * @param {object} [options]
 * @param {Set<string>} [options.activeAgentIds] - agents currently running
 * @param {string} [options.preferredPath] - cached holder path to validate first
 * @param {boolean} [options.allowLiveClaim=false] - recover a claim holder only
 *   after the supplied full registry passes branch/repository owner admission.
 * @param {Array<object>|null} [options.agents] - required for claim recovery
 * @param {string|null} [options.requestingAgentId] - the requesting run, not its predecessor
 * @returns {Promise<{ path: string, agentId: string }|null>}
 */
export async function findAdoptableWorktreeForBranch(sourceWorkspace, branchName, {
  activeAgentIds = new Set(),
  preferredPath = null,
  allowLiveClaim = false,
  agents = null,
  requestingAgentId = null,
} = {}) {
  if (!sourceWorkspace || !branchName) return null;

  const worktrees = await listWorktrees(sourceWorkspace).catch(() => null);
  if (!worktrees) return null;
  if (allowLiveClaim && !claimBranchAdmission({
    branchName, preferredPath, agentId: requestingAgentId, sourceWorkspace, worktrees, agents,
  }).admit) return null;
  // Git permits one holder per branch. A resume pointer is merely a cache of that
  // answer, so validate it against the current worktree list first and then fall
  // back to discovery when the cached path went stale or was moved.
  const holders = worktrees.filter(wt => wt.branch?.replace('refs/heads/', '') === branchName);
  const holder = preferredPath
    ? holders.find(wt => pathsEqual(wt.path, preferredPath)) || holders[0]
    : holders[0];
  if (!holder?.path) return null;

  const agentId = worktreeAgentId(holder.path);
  const ownershipReason = worktreeOwnershipReason({
    path: holder.path,
    locked: holder.locked,
    activeAgentIds,
    roots: [{ path: WORKTREES_DIR, requireAgentId: true }],
    requireKnownLiveness: true,
    allowLiveClaim,
  });
  if (ownershipReason) return null;

  return { path: holder.path, agentId };
}

// How long a sibling `/do:next` tree must sit untouched before a follow-up may
// release its branch. An agent that finished and kept its tree (waiting on CI,
// say) goes quiet for far longer; owner admission must pass independently.
export const SIBLING_NEXT_HOLDER_IDLE_MS = 10 * 60 * 1000;

/**
 * Free `branchName` from an idle slashdo `/do:next` worktree that sits OUTSIDE
 * `data/cos/worktrees/`, by DETACHING that tree's HEAD in place.
 *
 * `/do:next` cuts `next/<slug>` into a sibling directory of the repo
 * (`../next-issue-<n>`). A run that finished but kept its tree still holds the
 * branch, and the review-loop follow-up for that PR then cannot `worktree add`
 * it — adoption refuses any tree outside the managed root, so the follow-up
 * waits out its whole `worktree-busy` budget and blocks. Unlike adoption this
 * never moves or deletes the directory: a detached HEAD at the same commit keeps
 * every file, and `git switch <branch>` restores it.
 *
 * Refuses (returns false) unless ALL hold: the branch is `next/…`; the holder is
 * a linked worktree (never the primary checkout) outside the managed root,
 * unlocked; the readable registry has no branch/repository owner or running/paused
 * agent inside it; nothing in it changed for `idleMs`; the tree is clean, untracked files included
 * (unless `allowUntracked`: a detach leaves untracked files exactly where they are, so a
 * coordinator follow-up may take over a tree whose only dirt is stray untracked files such as
 * Finder "name 2.js" duplicates — tracked or staged changes still refuse); and HEAD is already on
 * the remote, so nothing is left only in that tree.
 *
 * @param {string} sourceWorkspace
 * @param {string} branchName
 * @param {{ activeWorkspacePaths?: string[], agents?: object[], requestingAgentId?: string, idleMs?: number, nowMs?: number, allowUntracked?: boolean }} [options]
 * @returns {Promise<{ path: string }|null>} the released holder, or null
 */
export async function releaseIdleSiblingNextHolder(sourceWorkspace, branchName, options = {}) {
  if (!sourceWorkspace || !branchName?.startsWith('next/')) return null;
  const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
  return withCheckoutPublication(sourceWorkspace, () => releaseIdleSiblingNextHolderAdmitted(sourceWorkspace, branchName, options));
}

async function releaseIdleSiblingNextHolderAdmitted(sourceWorkspace, branchName, {
  activeWorkspacePaths = [],
  agents = null,
  requestingAgentId = null,
  idleMs = SIBLING_NEXT_HOLDER_IDLE_MS,
  nowMs = Date.now(),
  allowUntracked = false,
} = {}) {
  if (!sourceWorkspace || !branchName?.startsWith('next/')) return null;

  const worktrees = await listWorktrees(sourceWorkspace).catch(() => null);
  if (!claimBranchAdmission({
    branchName, agentId: requestingAgentId, sourceWorkspace, worktrees, agents,
  }).admit) return null;
  const holderIndex = worktrees.findIndex(wt => wt.branch?.replace('refs/heads/', '') === branchName);
  // Index 0 is the main worktree — the user's own checkout is never released.
  if (holderIndex <= 0) return null;
  const holder = worktrees[holderIndex];
  if (holder.locked || holder.prunable || !existsSync(holder.path)) return null;
  if (isPathInsideDir(WORKTREES_DIR, holder.path)) return null;
  if (activeWorkspacePaths.some(p => p && (pathsEqual(p, holder.path) || isPathInsideDir(holder.path, p)))) return null;

  const git = (args) => execGit(args, holder.path).then(r => r.stdout.trim());
  // Idleness first; `--no-optional-locks` keeps `status` from refreshing the
  // index and so resetting the very clock this reads on a refused attempt.
  const gitDir = await git(['rev-parse', '--absolute-git-dir']).catch(() => null);
  if (!gitDir) return null;
  const mtimes = await Promise.all(['index', 'HEAD', join('logs', 'HEAD')]
    .map(f => stat(join(gitDir, f)).then(s => s.mtimeMs, () => 0)));
  if (nowMs - Math.max(...mtimes) < idleMs) return null;

  if (!await detachCleanPushedHolder(holder.path, branchName, { allowUntracked })) return null;
  console.log(`🌳 Released ${branchName} from idle /do:next worktree ${holder.path} (HEAD detached in place)`);
  return { path: holder.path };
}

/**
 * Detach `holderPath`'s HEAD in place iff the tree holds nothing the branch ref
 * does not: tracked/staged state clean (untracked files too unless
 * `allowUntracked`; git-ignored caches never count) and HEAD already on the
 * remote. A detached HEAD keeps every file where it is and `git switch <branch>`
 * restores it. Any unreadable check refuses (false).
 */
async function detachCleanPushedHolder(holderPath, branchName, { allowUntracked = false } = {}) {
  const git = (args) => execGit(args, holderPath).then(r => r.stdout.trim());
  // Stricter than `classifyWorktreeDirt` on purpose: this tree isn't PortOS's,
  // so no path counts as disposable scratch.
  const porcelain = await git(['--no-optional-locks', 'status', '--porcelain', '--untracked-files=all']).catch(() => null);
  if (porcelain === null) return false;
  if (allowUntracked ? porcelain.split('\n').some(l => l && !l.startsWith('?? ')) : porcelain !== '') return false;
  const remoteRef = await git(['rev-parse', '--verify', '--quiet', `${branchName}@{upstream}`])
    .catch(() => git(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branchName}`]))
    .catch(() => null);
  if (!remoteRef) return false;
  const pushed = await execGit(['merge-base', '--is-ancestor', 'HEAD', remoteRef], holderPath)
    .then(() => true, () => false);
  if (!pushed) return false;

  const detached = await execGit(['switch', '--detach', '--quiet'], holderPath).then(() => true, (err) => {
    console.warn(`⚠️ Could not detach ${holderPath} to release ${branchName}: ${err.message}`);
    return false;
  });
  return detached;
}

/**
 * Free `branchName` from a worktree PortOS did not create and nothing owns
 * anymore — typically one a terminal agent session cut under its own scratchpad
 * and left behind after pushing its PR (#12845). Detaches the holder in place
 * (never moves or deletes it), so no content can be lost; the caller then
 * retries `git worktree add`.
 *
 * Refuses (null) unless ALL hold, each failing closed when unreadable: the
 * holder is a linked worktree (never the primary checkout) OUTSIDE the managed
 * `data/cos/worktrees/` root, unlocked, with no branch/repository owner or
 * running/paused agent registered in or on it; no process has its cwd inside it
 * (`hasProcessInside`); it is clean (git-ignored caches excepted) and its HEAD
 * is already on the remote.
 *
 * @param {string} sourceWorkspace
 * @param {string} branchName
 * @param {{ activeWorkspacePaths?: string[], agents?: object[]|null, requestingAgentId?: string, hasProcessInside?: (dir: string) => Promise<boolean> }} [options]
 * @returns {Promise<{ path: string }|null>} the released holder, or null
 */
export async function releaseOwnerlessForeignHolder(sourceWorkspace, branchName, options = {}) {
  if (!sourceWorkspace || !branchName || PROTECTED_BRANCHES.includes(branchName)) return null;
  const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
  return withCheckoutPublication(sourceWorkspace, () => releaseOwnerlessForeignHolderAdmitted(sourceWorkspace, branchName, options));
}

async function releaseOwnerlessForeignHolderAdmitted(sourceWorkspace, branchName, {
  activeWorkspacePaths = [],
  agents = null,
  requestingAgentId = null,
  hasProcessInside = hasProcessCwdInside,
} = {}) {
  const worktrees = await listWorktrees(sourceWorkspace).catch(() => null);
  if (!claimBranchAdmission({
    branchName, agentId: requestingAgentId, sourceWorkspace, worktrees, agents,
  }).admit) return null;
  const holderIndex = worktrees.findIndex(wt => wt.branch?.replace('refs/heads/', '') === branchName);
  // Index 0 is the main worktree — the user's own checkout is never released.
  if (holderIndex <= 0) return null;
  const holder = worktrees[holderIndex];
  if (holder.locked || holder.prunable || !existsSync(holder.path)) return null;
  // Managed trees have their own owners and reapers (adoption, claim cleanup).
  if (isPathInsideDir(WORKTREES_DIR, holder.path)) return null;
  if (activeWorkspacePaths.some(p => p && (pathsEqual(p, holder.path) || isPathInsideDir(holder.path, p)))) return null;
  if (await hasProcessInside(holder.path).catch(() => true)) return null;
  if (!await detachCleanPushedHolder(holder.path, branchName)) return null;
  console.log(`🌳 Released ${branchName} from ownerless foreign worktree ${holder.path} (HEAD detached in place)`);
  return { path: holder.path };
}

/**
 * Adopt an INTERRUPTED agent's surviving worktree on behalf of the agent that is
 * retrying its task, instead of building a fresh one from the default branch.
 *
 * When an agent dies without completing (a server restart is the common case —
 * PM2 kills the PTY, so no completion hook ever runs), `removeWorktree` refuses to
 * delete a dirty tree and leaves the whole worktree in place. That tree holds the
 * dead run's uncommitted edits and untracked files, which no branch pointer can
 * carry: without adoption the retry starts from origin/main and redoes the work.
 *
 * The tree is MOVED to the retry's own `<worktrees>/<agentId>` directory rather
 * than adopted where it sits, because "directory name == the agent that owns this
 * tree" is the invariant `cleanupOrphanedWorktrees` reaps on — left at the dead
 * agent's path, the live retry's worktree would be reaped out from under it. The
 * move carries tracked edits, untracked files, and git's own bookkeeping intact.
 *
 * Returns null (never throws) whenever adoption isn't possible — the source tree
 * is gone, the target path is occupied, or git refuses the move (a locked worktree,
 * or one with initialized submodules), or its status suggests a partial removal.
 * The refused tree and branch stay intact for recovery: a fresh attachment to
 * that same branch will remain blocked while this checkout holds it.
 *
 * @param {string} agentId - the RETRYING agent (names the destination directory)
 * @param {string} sourceWorkspace - the parent git repository
 * @param {string} existingWorktreePath - absolute path of the dead agent's worktree
 * @param {string} branchName - the branch that worktree has checked out
 * @returns {Promise<{worktreePath: string, branchName: string, baseBranch: null, existingBranch: true, adopted: true, instanceId: string}|null>}
 */
export async function adoptWorktree(agentId, sourceWorkspace, existingWorktreePath, branchName, options = {}) {
  return queueWorktreeCreate(sourceWorkspace, () => adoptWorktreeUnlocked(agentId, sourceWorkspace, existingWorktreePath, branchName, options));
}

async function adoptWorktreeUnlocked(agentId, sourceWorkspace, existingWorktreePath, branchName, options) {
  if (!agentId || !sourceWorkspace || !existingWorktreePath || !branchName) return null;
  if (!existsSync(existingWorktreePath)) {
    console.log(`🌳 Cannot adopt worktree for ${agentId} — ${existingWorktreePath} no longer exists`);
    return null;
  }

  const targetPath = join(WORKTREES_DIR, agentId);
  const instanceId = await ensureInstanceId();
  const adopted = {
    worktreePath: targetPath, branchName, baseBranch: null,
    existingBranch: true, adopted: true, instanceId
  };

  if (!pathsEqual(existingWorktreePath, targetPath) && existsSync(targetPath)) {
    console.log(`🌳 Cannot adopt worktree for ${agentId} — ${targetPath} is already occupied`);
    return null;
  }

  // A killed removal can leave thousands of unstaged deletions. The resume
  // prompt attributes all surviving changes to the agent, so do not hand it a
  // likely damaged checkout. Keep intentional small deletions and staged work;
  // this conservative threshold requires operator recovery for ambiguous bulk
  // deletions instead of silently restoring or detaching somebody's work.
  const status = await execGit(['status', '--porcelain', '--untracked-files=no'], existingWorktreePath)
    .then(r => r.stdout)
    .catch(() => null);
  if (status === null) {
    console.warn(`⚠️ Cannot adopt worktree for ${agentId} — status unreadable; preserved for recovery`);
    return null;
  }
  const trackedChanges = status.split(/\r?\n/).filter(Boolean);
  const deletions = trackedChanges.filter(line => line.startsWith(' D ')).length;
  if (deletions >= 100 && deletions > trackedChanges.length / 2) {
    console.warn(`⚠️ Cannot adopt worktree for ${agentId} — ${deletions} unstaged tracked deletions suggest an interrupted removal; preserved for recovery`);
    return null;
  }

  // Re-entered prep still needs the damage check before resuming in place.
  if (pathsEqual(existingWorktreePath, targetPath)) return adopted;

  await ensureDir(WORKTREES_DIR);

  if (options.deepResume) {
    try {
      const entries = (await execGit(['ls-files', '--stage'], existingWorktreePath)).stdout;
      if (/^160000 /m.test(entries)) {
        // Git cannot move linked worktrees containing submodules, even after
        // deinit. Preserve the admitted inactive tree intact and transfer only
        // its clean branch attachment, all under the same repository queue.
        const currentBranch = (await execGit(['symbolic-ref', '--short', 'HEAD'], existingWorktreePath)).stdout.trim();
        const head = (await execGit(['rev-parse', 'HEAD'], existingWorktreePath)).stdout.trim();
        const status = (await execGit(['status', '--porcelain', '--untracked-files=all', '--ignore-submodules=none'], existingWorktreePath)).stdout.trim();
        const listed = await listWorktrees(sourceWorkspace);
        // Git and Node can spell the same Windows directory differently. Fall
        // back to filesystem identity, never case-fold or guess at ownership.
        const identity = await stat(existingWorktreePath, { bigint: true }).catch(() => null);
        const matches = [];
        for (const entry of listed) {
          if (pathsEqual(entry.path, existingWorktreePath)) { matches.push(entry); continue; }
          const other = await stat(entry.path, { bigint: true }).catch(() => null);
          if (identity?.isDirectory() && other?.isDirectory() && typeof identity.ino === 'bigint' && identity.ino > 0n &&
            identity.dev === other.dev && identity.ino === other.ino) matches.push(entry);
        }
        const holder = matches.length === 1 ? matches[0] : null;
        const refusal = currentBranch !== branchName ? 'branch identity changed'
          : !holder ? 'worktree registration could not be matched'
            : holder.locked ? 'worktree is locked' : status ? 'workspace has uncommitted or nested changes' : null;
        if (refusal) throw new Error(`Retained Deep submodule ${refusal}; preserve it for explicit recovery`);
        await execGit(['checkout', '--detach', head], existingWorktreePath);
        const branchHead = (await execGit(['rev-parse', `refs/heads/${branchName}`], sourceWorkspace)).stdout.trim();
        if (branchHead !== head) throw new Error('Deep resume branch changed during handoff; preserved old workspace');
        const replacement = await createWorktreeUnlocked(agentId, sourceWorkspace, null, { existingBranch: branchName });
        return { ...replacement, adopted: true };
      }
    } catch (error) {
      throw Object.assign(new Error(`Deep submodule handoff stopped; retained work is preserved: ${error.message}`, { cause: error }), { code: 'DEEP_RESUME_PRESERVED' });
    }
  }

  // Through the retry wrapper, not raw execGit: `worktree move` mutates the same
  // `.git/worktrees` bookkeeping whose per-repo lock motivated the retry (#2193).
  const moved = await addWorktreeWithRetry(['worktree', 'move', existingWorktreePath, targetPath], sourceWorkspace)
    .then(() => true)
    .catch(err => {
      console.log(`⚠️ Worktree adopt failed for ${agentId} (${existingWorktreePath} → ${targetPath}): ${err.message}`);
      return false;
    });
  if (!moved) return null;

  // Mirror removeWorktree's treatment of auto-generated lockfile churn: it discards
  // those changes rather than preserving them, so an adopted tree must not carry
  // them either. The resume prompt tells the retry that everything uncommitted is
  // its own in-progress work to finish and commit — which would ship a
  // `package-lock.json` bump from the dead run's `npm install` that nobody
  // intended. Only when the churn is ALL there is: a tree with real changes keeps
  // everything, exactly as removeWorktree preserves it.
  const porcelain = await execGit(['status', '--porcelain'], targetPath)
    .then(r => r.stdout.trim())
    .catch(() => '');
  const dirt = classifyWorktreeDirt(porcelain, { preserveLockfiles: options.preserveLockfiles === true });
  if (dirt.lockfileOnly) {
    console.log(`🧹 Discarding ${dirt.lockfilePaths.length} auto-generated lockfile change(s) in adopted worktree ${agentId}`);
    await discardLockfileChanges(targetPath, dirt).catch(err => {
      console.log(`⚠️ Lockfile discard failed in adopted worktree ${agentId}: ${err.message}`);
    });
  }

  console.log(`🌳 Adopted worktree for ${agentId} at ${targetPath} (branch: ${branchName}) — resuming interrupted work`);
  return adopted;
}

/**
 * The ref a "has this branch landed?" question should be asked against.
 *
 * NOT the local default branch. A PR merged on the forge moves ORIGIN's default
 * branch; this clone's `main` does not move until something fetches. So a branch
 * whose PR merged minutes ago reads as unmerged against the local ref, and a
 * caller that preserves on "unmerged" keeps an already-landed branch — which is
 * how a merged review-loop task was re-queued against work that had shipped.
 *
 * Refreshing first is best-effort: a fetch that fails (offline, no remote) falls
 * back to the local branch, which is strictly what the caller had before.
 *
 * @param {string} sourceWorkspace
 * @param {string} defaultBranch
 * @returns {Promise<string>} `origin/<default>` when resolvable, else `<default>`
 */
async function resolveMergeTarget(sourceWorkspace, defaultBranch) {
  await execGit(['fetch', 'origin', '--prune'], sourceWorkspace, { ignoreExitCode: true }).catch(() => {});
  const remote = await execGit(['rev-parse', '--verify', `origin/${defaultBranch}^{commit}`], sourceWorkspace, { ignoreExitCode: true })
    .then(r => (r.exitCode === 0 ? `origin/${defaultBranch}` : null))
    .catch(() => null);
  return remote || defaultBranch;
}

// Branch recovery is independent of checkout recovery. A second cleanup can
// arrive after the first removed the directory but preserved unpublished work;
// every successful removal path must apply the same branch-retention policy.
async function cleanupWorktreeBranch(sourceWorkspace, branchName, {
  hasUnmergedCommits = false, warnings, expectedHead, target: resolvedTarget,
}) {
  const present = await execGit(['show-ref', '--verify', '--quiet', `refs/heads/${branchName}`], sourceWorkspace, { ignoreExitCode: true }).catch(() => null);
  if (present?.exitCode === 1) return;
  if (present?.exitCode !== 0) {
    warnings.push(`Branch ${branchName} preserved — ref state unavailable`);
    return;
  }
  // Pin even a branch whose checkout was already removed. Unknown or changed
  // refs stay available for recovery instead of falling through to branch -D.
  const currentHead = (await execGit(['rev-parse', '--verify', `refs/heads/${branchName}`], sourceWorkspace).catch(() => null))?.stdout?.trim();
  expectedHead ||= currentHead;
  if (!expectedHead || currentHead !== expectedHead) {
    warnings.push(`Branch ${branchName} preserved — current head unavailable or changed`);
    return;
  }
  if (!hasUnmergedCommits) {
    // A prior cleanup may have already deleted a landed branch. Confirmed
    // absence is a clean no-op; an unreadable ref is still work to preserve.
    const localRef = await execGit(
      ['show-ref', '--verify', '--quiet', `refs/heads/${branchName}`],
      sourceWorkspace, { ignoreExitCode: true },
    ).catch(() => null);
    if (localRef?.exitCode === 1) return;
    const { getDefaultBranch, hasBranchMergeEvidence } = await import('./git.js');
    const defaultBranch = await getDefaultBranch(sourceWorkspace).catch(() => null) || 'main';
    // A caller holding the claim-ownership lock passes a target it resolved earlier:
    // the fetch must not run under that lock (#12764), and merge evidence against a
    // ref fetched moments ago stays valid.
    const target = resolvedTarget || await resolveMergeTarget(sourceWorkspace, defaultBranch);
    // Patch-equivalence recognizes squash/rebase merges; a failed probe keeps
    // the branch. Ask the refreshed remote target so a landed PR is not resumed
    // just because this install's local default branch has not advanced.
    const hasMergeEvidence = localRef?.exitCode === 0
      && await hasBranchMergeEvidence(sourceWorkspace, branchName, target).catch(() => false);
    if (!hasMergeEvidence) {
      hasUnmergedCommits = true;
      console.log(`🌳 Preserving branch ${branchName} — merge evidence into ${target} was not established, kept so a retry can resume from it`);
      warnings.push(`Branch ${branchName} preserved — merge evidence was not established; kept for a retry`);
    } else {
      const ahead = parseInt((await execGit(
        ['rev-list', '--count', `${target}..${branchName}`],
        sourceWorkspace,
      ).catch(() => ({ stdout: '' }))).stdout.trim(), 10);
      console.log(ahead === 0
        ? `🌳 Branch ${branchName} has no commits beyond ${target} — deleting it`
        : `🌳 Branch ${branchName} is already merged into ${target} — safe to delete`);
    }
  }
  if (hasUnmergedCommits) {
    console.warn(`⚠️ Preserving worktree branch ${branchName} for manual/automated recovery`);
  } else {
    const { readBranchCompletionHold } = await import('./branchCompletionPolicy.js');
    const policy = await readBranchCompletionHold({ repoPath: sourceWorkspace, branch: branchName, retirement: true }).catch(() => 'pr-completion-policy-unavailable');
    if (policy) { warnings.push(`Branch ${branchName} preserved — ${policy}`); return; }
    const recoveryRef = await execGit(['update-ref', `refs/portos/completed/${expectedHead}`, expectedHead], sourceWorkspace, { ignoreExitCode: true }).catch(() => null);
    if (recoveryRef?.exitCode !== 0 || !await deleteCompletedLocalBranch(sourceWorkspace, branchName, expectedHead)) {
      warnings.push(`Branch ${branchName} preserved — head changed, new holder, or deletion refused`);
    }
  }
}

/**
 * Remove a git worktree and its associated branch.
 *
 * Called during agent cleanup. Merges the worktree branch back
 * to the source branch if the agent made commits, then prunes.
 *
 * @param {string} agentId - The agent identifier
 * @param {string} sourceWorkspace - The original git repository path
 * @param {string} branchName - The worktree branch to clean up
 * @param {object} options
 * @param {boolean} [options.merge] - attempt to merge the branch back first
 * @param {boolean} [options.preserveLockfiles] - keep a lockfile-only change (a
 *   `dependency-updates` deliverable) instead of discarding it as install churn
 * @param {boolean} [options.discardDirt] - remove even when the tree is dirty.
 *   The dirty-abort exists to protect work that might still be wanted; the
 *   throwaway-worktree posture has already declared this tree's contents
 *   worthless (its own prompt invites scratch edits and forbids committing), so
 *   for it the abort protects nothing and instead strands a full checkout per
 *   run, forever. ONLY the discard path may pass this.
 */
export async function removeWorktree(agentId, sourceWorkspace, branchName, options = {}) {
  const { readClaimOwnershipAgents } = await import('./cosClaimOwnershipState.js');
  const ownershipHold = async () => claimCheckoutOwnerReason({
    branchName, holderPath: join(WORKTREES_DIR, agentId), sourceWorkspace,
    agents: await readClaimOwnershipAgents().catch(() => null), ignoreIds: [agentId],
  });
  const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
  return withCheckoutPublication(sourceWorkspace,
    () => removeWorktreeNow(agentId, sourceWorkspace, branchName, options, ownershipHold));
}

/**
 * Runs cleanup as claim-ownership critical sections with every archive between two
 * of them (#12748): each archive hashes and copies the whole checkout, and every
 * bind/release/reserve queues behind that lock on a 15 s budget. While an archive
 * runs this checkout is fenced; each section re-reads the owners before it acts.
 * `ownershipHold` reads registered owners only — this function owns the fence check.
 */
async function removeWorktreeNow(agentId, sourceWorkspace, branchName, options, ownershipHold) {
  const { withClaimOwnershipLock, checkoutRetirementFenceReason, retireWithUnlockedArchive } = await import('./cosClaimOwnershipState.js');
  const worktreePath = join(WORKTREES_DIR, agentId);
  const fence = { repoPath: sourceWorkspace, path: worktreePath, branch: branchName };
  const warnings = [];
  let merged = false;
  let commitsAhead = 0;
  let mergeRefused = false;
  const held = reason => {
    warnings.push(`Worktree preserved — ${reason}`);
    return { merged, removed: false, cleanupIncomplete: true, uncommittedSaved: false, warnings };
  };
  // Fetched with the lock released (archive phase, or before the first section) and
  // reused by every check under the lock: a branch merged into origin/<default> stays merged.
  let mergeTarget;
  const completionHold = async (expectedHead) => {
    const owner = await ownershipHold();
    if (owner) return owner;
    const { readBranchCompletionHold } = await import('./branchCompletionPolicy.js');
    const policy = await readBranchCompletionHold({ repoPath: sourceWorkspace, branch: branchName, retirement: true });
    if (policy) return policy;
    const { getDefaultBranch, hasBranchMergeEvidence } = await import('./git.js');
    const base = await getDefaultBranch(sourceWorkspace, { strict: true }).catch(() => null);
    if (!base) return 'default-branch-unavailable';
    if (PROTECTED_BRANCHES.includes(branchName) || branchName === base) return 'protected-branch';
    mergeTarget ||= await resolveMergeTarget(sourceWorkspace, base);
    const head = (await execGit(['rev-parse', '--verify', `refs/heads/${branchName}`], sourceWorkspace).catch(() => null))?.stdout?.trim();
    if (!head || (expectedHead && head !== expectedHead)) return 'branch-head-changed-or-unavailable';
    return await hasBranchMergeEvidence(sourceWorkspace, head, mergeTarget).catch(() => false) ? null : 'merge-evidence-unavailable';
  };
  // A follow-up on a branch the primary checkout owns runs DETACHED (createWorktree):
  // there is no branch to protect, merge or delete, so only its commits matter.
  // Probed lazily: every early refusal above the archive step is a pure-status exit.
  let detachedProbe = null;
  const detachedCheckout = () => detachedProbe ||= listWorktrees(sourceWorkspace)
    .then(trees => trees.find(wt => canonicalPath(wt.path) === canonicalPath(worktreePath) && wt.detached && !wt.branch) || null, () => null);
  const detachedHold = async (head) => {
    const owner = await ownershipHold();
    if (owner) return owner;
    const contained = await execGit(['branch', '-r', '--contains', head], sourceWorkspace, { ignoreExitCode: true }).catch(() => null);
    return contained?.exitCode === 0 && contained.stdout.trim() ? null : 'detached-head-unpublished';
  };
  const preserve = async () => {
    const { releaseCheckoutWithoutArchive } = await import('./heldCheckoutRecovery.js');
    return releaseCheckoutWithoutArchive({ repoPath: sourceWorkspace, path: worktreePath, branch: branchName }, async () => {
      const tree = (await listWorktrees(sourceWorkspace)).find(wt => canonicalPath(wt.path) === canonicalPath(worktreePath));
      const detached = Boolean(await detachedCheckout());
      if (!tree || (detached ? !tree.detached || tree.branch : tree.branch !== `refs/heads/${branchName}`)) throw new Error('worktree-holder-changed');
      const checkHold = detached ? detachedHold : completionHold;
      const hold = await checkHold(tree.head);
      if (hold) throw new Error(hold);
      const ignoredPaths = [DONE_SENTINEL_NAME, ...doneSentinelCandidateNames(agentId)];
      const { readRetirementCheckoutIdentity } = await import('../lib/retirementCheckoutObservation.js');
      const checkoutIdentity = await readRetirementCheckoutIdentity(tree.path).catch(() => null);
      return {
        head: tree.head, path: tree.path, branch: detached ? null : branchName,
        ...(checkoutIdentity && { checkoutIdentity }),
        verify: async holder => {
          if (!holder || holder.head !== tree.head || Boolean(holder.detached) !== Boolean(tree.detached)) return 'worktree-holder-changed';
          if (!detached && holder.branch !== tree.branch) return 'worktree-holder-changed';
          const again = await checkHold(tree.head);
          if (again) return again;
          if (!existsSync(tree.path)) return null;
          const status = await execGit(['status', '--porcelain'], tree.path).then(r => r.stdout, () => null);
          if (status === null) return 'worktree-status-unavailable';
          const dirt = classifyWorktreeDirt(status, { ignoredPaths, preserveLockfiles: options.preserveLockfiles === true });
          if (!dirt.clean && !options.discardDirt) return 'worktree-dirty';
          return null;
        },
      };
    });
  };
  // One archive between two critical sections. `admit` (under the lock, after the
  // owner re-read) returns a result to stop before fencing; `finish` runs under the
  // lock again with the fence still held.
  const retire = ({ admit = async () => null, onArchiveFailure, finish }) => retireWithUnlockedArchive({
    busy: () => held('checkout-retirement-reserved'),
    admit: async () => {
      const owner = await ownershipHold();
      if (owner) return { result: held(owner) };
      const stop = await admit();
      return stop ? { result: stop } : { fence };
    },
    archive: () => preserve().then(archive => ({ archive }), error => {
      warnings.push(`Worktree preserved — archive failed: ${error.message}`);
      return { result: onArchiveFailure() };
    }),
    finish: (_admitted, preservation) => finish(preservation),
  });
  const cleanupBranch = async (expectedHead) => {
    const finalOwner = await ownershipHold();
    if (finalOwner) {
      warnings.push(`Branch ${branchName} preserved — ${finalOwner}`);
      return false;
    }
    await cleanupWorktreeBranch(sourceWorkspace, branchName, {
      hasUnmergedCommits: options.merge && !merged && (commitsAhead > 0 || mergeRefused), warnings, expectedHead, target: mergeTarget,
    });
    return true;
  };

  if (!existsSync(worktreePath)) {
    // The already-gone path deletes the branch under the lock; fetch before taking it.
    const { getDefaultBranch } = await import('./git.js');
    const base = await getDefaultBranch(sourceWorkspace, { strict: true }).catch(() => null);
    if (base) mergeTarget = await resolveMergeTarget(sourceWorkspace, base);
  }

  const inspected = await withClaimOwnershipLock(async () => {
    const { getDefaultBranch } = await import('./git.js');
    const defaultBranch = await getDefaultBranch(sourceWorkspace, { strict: true }).catch(() => null);
    const protectedReason = PROTECTED_BRANCHES.includes(branchName) || branchName === defaultBranch
      ? 'protected-branch' : !defaultBranch ? 'default-branch-unavailable' : null;
    if (protectedReason && !await detachedCheckout()) return { result: held(protectedReason) };
    // A retirement archiving this checkout with the lock released owns it until removal.
    const owner = checkoutRetirementFenceReason(fence) || await ownershipHold();
    if (owner) return { result: held(owner) };

    if (!existsSync(worktreePath)) {
      // The directory is gone, but git may still register it (a stale entry pins the
      // branch). Verify rather than assume; prune when the registration survives.
      const gone = removalOutcome(worktreePath, await probeWorktreeRemoval(sourceWorkspace, worktreePath));
      if (!gone.removed) return { missing: true };
      console.log(`🌳 Worktree already removed for ${agentId}, cleaning up branch`);
      await cleanupBranch(undefined);
      return { result: { merged: false, removed: true, uncommittedSaved: false, warnings } };
    }

    // Verify the worktree still points to the correct repo before trusting git status.
    // If the .git file is missing (e.g., worktree was partially cleaned up), git walks up
    // the directory tree and may find a parent repo (e.g., PortOS) instead of the app repo.
    // In that case, even a successful git status describes the wrong checkout and
    // cannot prove this directory has no unique work.
    const detectedToplevel = await execGit(['rev-parse', '--show-toplevel'], worktreePath)
      .then(r => r.stdout.trim())
      .catch(() => null);
    // Compare realpath-resolved forms so symlinks (e.g. macOS /var → /private/var)
    // or normalization differences don't false-positive as a broken worktree.
    if (detectedToplevel && !pathsEqual(detectedToplevel, worktreePath)) {
      warnings.push('Worktree preserved — broken checkout identity prevents verifying its contents');
      console.warn(`⚠️ Worktree ${agentId} has a broken checkout identity; preserving its directory and branch`);
      return { result: { merged: false, removed: false, cleanupIncomplete: true, uncommittedSaved: false, warnings } };
    }

    // Safety check: abort removal when uncommitted changes are detected.
    // Also fail closed if git status itself fails — treat unknown state as dirty.
    let dirtyFiles;
    try {
      dirtyFiles = (await execGit(['status', '--porcelain'], worktreePath)).stdout.trim();
    } catch (err) {
      console.log(`⚠️ git status failed for worktree ${agentId}, preserving to avoid data loss: ${err.message}`);
      warnings.push(`Worktree preserved — git status failed: ${err.message}`);
      return { result: { merged: false, removed: false, uncommittedSaved: false, warnings } };
    }
    // The completion sentinel is not authored work: it has already been consumed
    // by finalizeAgent before this cleanup runs. Ignore it for the preservation
    // decision, while still preserving the tree if any real change remains; the
    // eventual forced worktree removal discards it with the rest of the completed
    // checkout. The run's canonical name and its bounded truncation-recovery
    // name, plus the legacy shared one a pre-upgrade run may have left — and no
    // other agent's.
    const dirt = classifyWorktreeDirt(dirtyFiles, {
      ignoredPaths: [DONE_SENTINEL_NAME, ...doneSentinelCandidateNames(agentId)],
      preserveLockfiles: options.preserveLockfiles === true
    });
    if (!dirt.clean && options.discardDirt) {
      // Throwaway posture: the caller has already established that nothing in this
      // tree is wanted. Log what is being dropped so a surprising loss is at least
      // traceable, then fall through to removal.
      const shown = dirt.realChangePaths.slice(0, DIRT_PATHS_IN_WARNING);
      if (shown.length) console.log(`🌳 Discarding uncommitted changes in throwaway worktree ${agentId}: ${shown.join(', ')}`);
    } else if (!dirt.clean) {
      // Auto-generated lockfile changes agents don't intend to commit (e.g. npm
      // install resolving ^version to an exact version) are discarded below.
      if (dirt.lockfileOnly) return { lockfile: { dirt, dirtyFiles } };
      // NAME the dirty paths. The bare message reads as "your work was left
      // behind" with no way to tell real uncommitted work from a transient
      // observation, and the worktree is usually gone by the time anyone looks —
      // which is exactly what made the duplicate-cleanup race in
      // `agentWorktreeCleanup.js` undiagnosable from the card alone.
      const shown = dirt.realChangePaths.slice(0, DIRT_PATHS_IN_WARNING);
      const more = dirt.realChangePaths.length - shown.length;
      const detail = `${shown.join(', ')}${more > 0 ? ` (+${more} more)` : ''}`;
      console.log(`⚠️ Preserving worktree for ${agentId} — uncommitted changes detected (${detail}), aborting cleanup to avoid data loss`);
      warnings.push(`Worktree preserved — uncommitted changes detected in ${worktreePath}: ${detail}`);
      return { result: { merged: false, removed: false, uncommittedSaved: false, warnings } };
    }
    return {};
  });
  if (inspected.result) return inspected.result;

  if (inspected.missing) {
    return retire({
      onArchiveFailure: () => ({ merged: false, removed: false, cleanupIncomplete: true, uncommittedSaved: false, warnings }),
      finish: async (preservation) => {
        const gone = await forceRemoveWorktreeDir(sourceWorkspace, worktreePath, { verifyRemoval: preservation.verify });
        if (!gone.removed) {
          warnings.push(gone.warning);
          return { merged: false, removed: false, cleanupIncomplete: true, uncommittedSaved: false, warnings };
        }
        console.log(`🌳 Worktree already removed for ${agentId}, cleaning up branch`);
        await cleanupBranch(preservation.head);
        return { merged: false, removed: true, uncommittedSaved: false, warnings };
      },
    });
  }

  if (inspected.lockfile) {
    const { dirt, dirtyFiles } = inspected.lockfile;
    // Preserve the original bytes before the intentional lockfile cleanup.
    // The second snapshot below guards the post-cleanup removal boundary.
    const discardFailure = await retire({
      onArchiveFailure: () => ({ merged: false, removed: false, uncommittedSaved: false, warnings }),
      finish: async () => {
        // The snapshot ran with the lock released; discard only the tree it captured.
        const current = await execGit(['status', '--porcelain'], worktreePath).then(r => r.stdout.trim(), () => null);
        if (current !== dirtyFiles) {
          warnings.push(`Worktree preserved — ${worktreePath} changed while its pre-cleanup snapshot was archived`);
          return { merged: false, removed: false, uncommittedSaved: false, warnings };
        }
        console.log(`🧹 Discarding ${dirt.lockfilePaths.length} auto-generated lockfile change(s) in worktree ${agentId}`);
        // Never throws past removeWorktree: an undiscardable lockfile keeps the tree.
        return discardLockfileChanges(worktreePath, dirt).then(() => null, err => {
          console.log(`⚠️ Lockfile discard failed in worktree ${agentId}, preserving to avoid data loss: ${err.message}`);
          warnings.push(`Worktree preserved — lockfile discard failed in ${worktreePath}: ${err.message}`);
          return { merged: false, removed: false, uncommittedSaved: false, warnings };
        });
      },
    });
    if (discardFailure) return discardFailure;
  }

  return retire({
    admit: async () => {
      if (!options.merge || await detachedCheckout()) return null;
      const currentBranch = (await execGit(
        ['rev-parse', '--abbrev-ref', 'HEAD'],
        sourceWorkspace
      )).stdout.trim();

      // Defense-in-depth: NEVER merge the agent branch into a non-default branch.
      // See shouldRefuseDefaultBranchMerge for the rationale.
      const { getDefaultBranch } = await import('./git.js');
      const defaultBranch = await getDefaultBranch(sourceWorkspace).catch(() => null);
      if (shouldRefuseDefaultBranchMerge(currentBranch, defaultBranch)) {
        console.log(`🌳 Refusing auto-merge of ${branchName} into '${currentBranch}' (default branch is '${defaultBranch || 'unknown'}'). Use \`gh pr merge\` for non-default targets.`);
        warnings.push(`Auto-merge skipped — source repo HEAD is on '${currentBranch}', not default '${defaultBranch || 'unknown'}'. Branch ${branchName} preserved for manual review.`);
        mergeRefused = true;
        return null;
      }
      const countResult = await execGit(
        ['rev-list', '--count', `${currentBranch}..${branchName}`],
        sourceWorkspace,
        { ignoreExitCode: true },
      ).catch(() => null);
      const countText = countResult?.stdout?.trim();
      const parsedCount = typeof countText === 'string' && /^\d+$/.test(countText)
        ? Number(countText)
        : NaN;

      // A failed or malformed preflight cannot prove that the branch is empty.
      // Keep both refs in place so retry can safely decide whether to merge.
      if (countResult?.exitCode !== 0 || !Number.isSafeInteger(parsedCount)) {
        console.warn(`⚠️ Could not determine commits ahead for ${branchName}; preserving its worktree and branch for retry`);
        warnings.push(`Worktree and branch ${branchName} preserved — could not read a valid commit count; retry cleanup when Git refs are available`);
        return { merged: false, removed: false, uncommittedSaved: false, warnings };
      }

      commitsAhead = parsedCount;

      if (commitsAhead > 0) {
        await execGit(['merge', branchName, '--no-edit'], sourceWorkspace)
          .then(() => { merged = true; })
          .catch(async (err) => {
            console.log(`⚠️ Could not auto-merge ${branchName}: ${err.message}`);
            await execGit(['merge', '--abort'], sourceWorkspace).catch(() => {});
            warnings.push(`Auto-merge failed for branch ${branchName} — branch preserved for manual recovery`);
          });
      }
      return null;
    },
    onArchiveFailure: () => ({ merged, removed: false, cleanupIncomplete: true, uncommittedSaved: false, warnings }),
    finish: async (preservation) => {
      const removal = await forceRemoveWorktreeDir(sourceWorkspace, worktreePath, {
        verifyRemoval: preservation.verify,
        label: `Worktree remove failed for ${agentId}, falling back to manual cleanup`,
        log: 'all',
        subject: agentId,
      });
      if (!removal.removed) {
        // The checkout (or its registration) survived: the branch is still held, so
        // deleting it would fail, and `removed: true` would tell the caller it may
        // queue work onto a branch the old worktree still owns. Report the truth with
        // a retryable warning; `merged` stays accurate for the publication outcome.
        // `forceRemoveWorktreeDir` above already reported why on the right stream.
        console.log(`⏸️ Worktree for ${agentId} was not removed — branch ${branchName} kept`);
        warnings.push(removal.warning);
        return { merged, removed: false, cleanupIncomplete: true, uncommittedSaved: false, warnings };
      }

      // Merge evidence and completion policy were checked before removal; the
      // branch helper checks them again before its leased local deletion.
      const branchCleaned = await detachedCheckout() || await cleanupBranch(preservation.head);
      if (branchCleaned) console.log(`🌳 Removed worktree for ${agentId}${merged ? ' (merged)' : ''}`);
      const { recordWorkspaceCheckoutRetirement } = await import('./taskSchedule.js');
      // A completed cleanup attempt may retain a moved or newly held branch.
      const ref = preservation.branch && await execGit(['show-ref', '--verify', '--quiet', `refs/heads/${preservation.branch}`],
        sourceWorkspace, { ignoreExitCode: true }).catch(() => null);
      await recordWorkspaceCheckoutRetirement(sourceWorkspace, {
        path: preservation.path, branch: preservation.branch, head: preservation.head,
        branchDeleted: ref?.exitCode === 1, ...(preservation.checkoutIdentity && { checkoutIdentity: preservation.checkoutIdentity }),
      }).catch(error => { warnings.push(`Retirement receipt not recorded: ${error.message}`); });
      return { merged, removed: true, uncommittedSaved: false, warnings };
    },
  });
}

/**
 * Create a persistent worktree for a feature agent.
 * Unlike regular worktrees, these persist across runs.
 */
export async function createPersistentWorktree(featureAgentId, sourceWorkspace, branchName, baseBranch) {
  // Share the per-repo serialization tail with createWorktree so a persistent
  // feature-agent add and a CoS agent add in the same tick can't race git's
  // per-repo worktree lock (#2193).
  return queueWorktreeCreate(sourceWorkspace, () => createPersistentWorktreeUnlocked(featureAgentId, sourceWorkspace, branchName, baseBranch));
}

async function createPersistentWorktreeUnlocked(featureAgentId, sourceWorkspace, branchName, baseBranch) {
  const FA_WORKTREES = join(WORKTREES_DIR, '..', 'feature-agents', featureAgentId, 'worktree');

  await ensureDir(join(WORKTREES_DIR, '..', 'feature-agents', featureAgentId));

  const fetchOk = await execGit(['fetch', 'origin'], sourceWorkspace)
    .then(() => true)
    .catch(err => {
      console.log(`⚠️ Persistent worktree fetch failed: ${err.message}`);
      return false;
    });

  if (!baseBranch) {
    const { getDefaultBranch } = await import('./git.js');
    baseBranch = await getDefaultBranch(sourceWorkspace, { allowRemote: fetchOk }).catch(() => null) || 'main';
  }

  // Verify the base branch exists locally or on the remote; re-detect if stale
  const baseRef = await execGit(['rev-parse', `origin/${baseBranch}`], sourceWorkspace)
    .then(() => `origin/${baseBranch}`)
    .catch(async () => {
      const localExists = (await execGit(['branch', '--list', baseBranch], sourceWorkspace, { ignoreExitCode: true })).stdout.trim();
      if (localExists) return baseBranch;
      // Provided baseBranch doesn't exist — re-detect the actual default
      const { getDefaultBranch } = await import('./git.js');
      const detected = await getDefaultBranch(sourceWorkspace, { allowRemote: false }).catch(() => null);
      if (detected && detected !== baseBranch) {
        baseBranch = detected;
        const remoteOk = await execGit(['rev-parse', `origin/${detected}`], sourceWorkspace, { ignoreExitCode: true })
          .then(r => r.exitCode === 0).catch(() => false);
        if (remoteOk) return `origin/${detected}`;
        const localOk = (await execGit(['branch', '--list', detected], sourceWorkspace, { ignoreExitCode: true })).stdout.trim();
        if (localOk) return detected;
      }
      // All detection failed — use HEAD and update baseBranch to reflect reality
      const headBranch = (await execGit(['rev-parse', '--abbrev-ref', 'HEAD'], sourceWorkspace, { ignoreExitCode: true })).stdout.trim();
      baseBranch = headBranch && headBranch !== 'HEAD' ? headBranch : baseBranch;
      return 'HEAD';
    });

  // Check if branch already exists (local or remote)
  const localBranchExists = (await execGit(['branch', '--list', branchName], sourceWorkspace)).stdout.trim();
  const remoteBranchExists = (await execGit(['branch', '-r', '--list', `origin/${branchName}`], sourceWorkspace)).stdout.trim();

  if (localBranchExists) {
    // Local branch exists - create worktree from existing branch (no orphan
    // cleanup: the branch pre-dates this add).
    await addWorktreeWithRetry(['worktree', 'add', FA_WORKTREES, branchName], sourceWorkspace);
  } else if (remoteBranchExists) {
    // Remote branch exists but no local - track it. On final failure, drop the
    // partially-created local tracking branch (it re-creates from origin next run).
    await addWorktreeWithRetry(['worktree', 'add', '--track', '-b', branchName, FA_WORKTREES, `origin/${branchName}`], sourceWorkspace)
      .catch(async (err) => { await cleanupOrphanBranch(sourceWorkspace, branchName, err); throw err; });
  } else {
    // New branch - create from base. `--no-track` for the same reason as createWorktree:
    // `baseRef` is usually `origin/<default>`, and an auto-configured
    // `branch.<name>.merge = refs/heads/main` turns a config-derived push into a push
    // onto the default branch (#4172). Clean up the orphan branch on final failure (#2193).
    await addWorktreeWithRetry(['worktree', 'add', '--no-track', '-b', branchName, FA_WORKTREES, baseRef], sourceWorkspace)
      .catch(async (err) => { await cleanupOrphanBranch(sourceWorkspace, branchName, err); throw err; });
  }

  // Covers all three arms above, including a branch a prior run left mis-tracked.
  await enforceUpstreamOrUndoAdd(sourceWorkspace, branchName, FA_WORKTREES, { deleteBranch: !localBranchExists });

  console.log(`🌳 Created persistent worktree for feature agent ${featureAgentId} at ${FA_WORKTREES} (branch: ${branchName})`);
  return { worktreePath: FA_WORKTREES, branchName, baseBranch };
}

/**
 * Remove a persistent feature agent worktree
 */
export async function removePersistentWorktree(featureAgentId, sourceWorkspace, branchName) {
  const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
  return withCheckoutPublication(sourceWorkspace, () => removePersistentWorktreeAdmitted(featureAgentId, sourceWorkspace, branchName));
}

async function removePersistentWorktreeAdmitted(featureAgentId, sourceWorkspace, branchName) {
  const worktreePath = join(WORKTREES_DIR, '..', 'feature-agents', featureAgentId, 'worktree');

  if (!existsSync(worktreePath)) return { removed: false };

  const removal = await forceRemoveWorktreeDir(sourceWorkspace, worktreePath, {
    label: `Persistent worktree remove failed for ${featureAgentId}, falling back`,
    log: 'all',
    subject: featureAgentId,
  });
  if (!removal.removed) return { removed: false, cleanupIncomplete: true, warnings: [removal.warning] };

  await execGit(['branch', '-D', branchName], sourceWorkspace).catch(err => {
    console.log(`⚠️ Branch delete failed for ${branchName}: ${err.message}`);
  });

  console.log(`🌳 Removed persistent worktree for feature agent ${featureAgentId}`);
  return { removed: true, warnings: [] };
}

/**
 * Merge base branch into a persistent feature agent worktree before a run
 */
export async function mergeBaseIntoFeatureWorktree(featureAgentId, baseBranch) {
  const worktreePath = join(WORKTREES_DIR, '..', 'feature-agents', featureAgentId, 'worktree');
  if (!existsSync(worktreePath)) return { merged: false, reason: 'worktree-missing' };

  const fetchOk = await execGit(['fetch', 'origin'], worktreePath)
    .then(() => true)
    .catch(err => {
      console.log(`⚠️ Fetch failed for feature agent ${featureAgentId}: ${err.message}`);
      return false;
    });

  if (!baseBranch) {
    const { getDefaultBranch } = await import('./git.js');
    baseBranch = await getDefaultBranch(worktreePath, { allowRemote: fetchOk }).catch(() => null) || 'main';
  }
  // Verify origin/<baseBranch> exists; if not, re-detect before giving up
  let remoteBranchValid = await execGit(['rev-parse', `origin/${baseBranch}`], worktreePath, { ignoreExitCode: true })
    .then(r => r.exitCode === 0)
    .catch(() => false);
  if (!remoteBranchValid) {
    const { getDefaultBranch } = await import('./git.js');
    const detected = await getDefaultBranch(worktreePath, { allowRemote: false }).catch(() => null);
    if (detected && detected !== baseBranch) {
      remoteBranchValid = await execGit(['rev-parse', `origin/${detected}`], worktreePath, { ignoreExitCode: true })
        .then(r => r.exitCode === 0).catch(() => false);
      if (remoteBranchValid) {
        baseBranch = detected;
      }
    }
    if (!remoteBranchValid) {
      return { merged: false, reason: `origin/${baseBranch} not found` };
    }
  }
  const result = await execGit(['merge', `origin/${baseBranch}`, '--no-edit'], worktreePath)
    .then(() => ({ merged: true }))
    .catch(async (err) => {
      // Abort failed merge
      await execGit(['merge', '--abort'], worktreePath).catch(abortErr => {
        console.log(`⚠️ Merge abort failed for ${featureAgentId}: ${abortErr.message}`);
      });
      return { merged: false, reason: err.message };
    });

  if (result.merged) {
    console.log(`🌳 Merged origin/${baseBranch} into feature agent ${featureAgentId}`);
  }
  return result;
}

/**
 * List all active worktrees for the repository.
 *
 * Split on CRLF as well as LF. On Windows git's porcelain output is CRLF, and a
 * bare `split('\n')` leaves a trailing \r on every value: `path` and `branch`
 * silently carry it, so containment checks and path equality match nothing, and
 * the flag lines never compare equal (`'bare\r' !== 'bare'`) so `bare`,
 * `detached`, `locked` and `prunable` all read as false. That is what made the
 * reaper report a managed worktree as `worktree-unmanaged-location` on Windows
 * and skip it forever, while every Linux run stayed green.
 */
export async function listWorktrees(sourceWorkspace) {
  const { stdout } = await execGit(['worktree', 'list', '--porcelain'], sourceWorkspace);
  const worktrees = [];
  let current = {};

  for (const line of stdout.split(/\r?\n/)) {
    if (line.startsWith('worktree ')) {
      if (current.path) worktrees.push(current);
      current = { path: line.slice(9) };
    } else if (line.startsWith('HEAD ')) {
      current.head = line.slice(5);
    } else if (line.startsWith('branch ')) {
      current.branch = line.slice(7);
    } else if (line === 'bare') {
      current.bare = true;
    } else if (line === 'detached') {
      current.detached = true;
    } else if (line === 'locked' || line.startsWith('locked ')) {
      // `git worktree list --porcelain` emits a bare `locked` line, or `locked <reason>`.
      current.locked = true;
      current.lockReason = line.startsWith('locked ') ? line.slice(7) : null;
    } else if (line === 'prunable' || line.startsWith('prunable ')) {
      // Same two spellings. Set when git considers the registration disposable —
      // its directory is gone, or its .git pointer no longer resolves.
      current.prunable = true;
    }
  }
  if (current.path) worktrees.push(current);

  return worktrees;
}

// Registry the destructive passes re-read under the claim-ownership lock.
// Omitted reads state.json; `{ agents }` / `{ readAgents }` inject owners.
function claimOwnerReader(claimOwners, readClaimOwnershipAgents) {
  return claimOwners === undefined ? readClaimOwnershipAgents
    : async () => claimOwners?.readAgents ? claimOwners.readAgents().catch(() => null) : claimOwners?.agents;
}

// A liveness snapshot ages while the caller's earlier passes run, so the orphan
// passes re-read it per tree (#11858). A bare Set/null is a fixed snapshot.
function activeIdsReader(activeIds) {
  return typeof activeIds === 'function' ? activeIds : () => activeIds;
}

/**
 * Clean up any orphaned worktrees (worktrees whose agent no longer exists)
 *
 * @param {string} sourceWorkspace - The original git repository path
 * @param {(() => Set<string>|null)|Set<string>|null} getActiveIds - live agent ids, re-read
 *   for every worktree. Anything but a Set reads as "liveness unknown" and holds every `agent-*` tree.
 * @param {object} [options]
 * @param {{agents?: object[]|null, readAgents?: () => Promise<object[]|null>}} [options.claimOwners] -
 *   agent registry override (tests); omitted reads state.json
 * @param {Set<string>} [options.retainedPaths] - registered paths held by an earlier cleanup pass
 */
export async function cleanupOrphanedWorktrees(sourceWorkspace, getActiveIds, { claimOwners, retainedPaths = new Set() } = {}) {
  if (!existsSync(WORKTREES_DIR)) return 0;

  const readActiveIds = activeIdsReader(getActiveIds);
  const { readClaimOwnershipAgents } = await import('./cosClaimOwnershipState.js');
  const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
  const readOwners = claimOwnerReader(claimOwners, readClaimOwnershipAgents);
  const worktrees = await listWorktrees(sourceWorkspace).catch(() => []);
  let cleaned = 0;

  // Track which agent dirs we handle via git worktree list (PortOS-owned worktrees)
  const handledAgentIds = new Set();

  for (const wt of worktrees) {
    const ownershipReason = () => worktreeOwnershipReason({
      path: wt.path,
      locked: wt.locked,
      activeAgentIds: readActiveIds(),
      roots: [{ path: WORKTREES_DIR, requireAgentId: true }],
      requireKnownLiveness: true,
    });
    const initialReason = ownershipReason();
    if (initialReason === 'worktree-unmanaged-location') continue;
    const agentId = worktreeAgentId(wt.path);
    handledAgentIds.add(agentId);
    if (retainedPaths.has(wt.path)) continue;
    if (initialReason) continue;
    // A detached HEAD has no branch to merge or measure; force-removing it would drop commits only its reflog holds.
    if (wt.detached || !wt.branch) continue;

    const branchName = wt.branch.replace('refs/heads/', '');
    // Attempt merge so committed work from preserved worktrees (e.g., PR/push failures) isn't lost.
    // If merge fails, the branch is preserved for manual recovery. Every critical
    // section re-reads liveness and the registry, so neither an agent dispatched
    // since the check above nor a registered claim owner loses its checkout.
    const result = await withCheckoutPublication(sourceWorkspace,
      () => removeWorktreeNow(agentId, sourceWorkspace, branchName, { merge: true }, async () =>
        ownershipReason() || claimCheckoutOwnerReason({ branchName, holderPath: wt.path, sourceWorkspace, agents: await readOwners() })),
    ).catch(err => {
      console.log(`⚠️ Failed to clean orphaned worktree ${agentId}: ${err.message}`);
      return { removed: false };
    });
    if (result?.removed) cleaned++;
  }

  // Scan for external-repo worktrees (directories whose .git points to a different repo).
  // These are invisible to `git worktree list` run against PortOS.
  cleaned += await cleanupExternalRepoWorktrees(readActiveIds, handledAgentIds, readOwners, retainedPaths);

  if (cleaned > 0) {
    console.log(`🌳 Cleaned ${cleaned} orphaned worktree(s)`);
  }

  return cleaned;
}

/**
 * Reap worktrees whose branch is fully merged into the default branch AND whose
 * working tree is clean. This is the SAFE counterpart to cleanupOrphanedWorktrees:
 * it never integrates unmerged work, never deletes anything with pending
 * changes, and honors worktree locks. A worktree is reaped only when BOTH hold:
 *   1. the working tree is completely clean, and
 *   2. every commit on the branch is already in the default branch — detected via
 *      `hasBranchMergeEvidence`, which covers normal AND squash/rebase merges.
 *
 * Because of gate (2) this works regardless of merge strategy, but a true merge
 * commit (see the `--merge`-preferring agent prompts) makes detection bulletproof.
 *
 * Covers both PortOS-managed CoS worktrees (`data/cos/worktrees/`) and the
 * `.claude/worktrees/` trees created by `/work`, `/claim`, and the superpowers
 * git-worktree skill (these share the PortOS repo, so they appear in
 * `git worktree list`). Active CoS agents and locked worktrees are never touched.
 *
 * Human `/claim` worktrees (`claim-*`) are ALWAYS skipped here, and deliberately
 * so — this reaper passes neither `allowStaleClaim` nor an age, which is not an
 * oversight to be fixed by handing it the same discriminator branch-reconcile
 * uses. Reclaiming a claim tree turns on how long it has been idle and on
 * whether its branch was provably SHIPPED (its upstream ref gone from origin),
 * and `branchReconcile` is the module that computes both, per branch, with the
 * remote-head listing to back it. This reaper knows only "merged + clean", which
 * is also true of a claim a human paused ten minutes ago. So the claim window
 * stays in ONE place: branch-reconcile reaps a shipped or abandoned claim on its
 * own pass, and the claim flow's Phase 7 self-cleans the ordinary case. (Under
 * `WORKTREES_DIR` the skip is doubly enforced: that root sets
 * `requireAgentId: true`, so a `claim-*` basename is refused as
 * `worktree-missing-agent-id` before the claim test is even reached.)
 *
 * @param {string} sourceWorkspace - repo root
 * @param {object} [options]
 * @param {Set<string>|(() => Set<string>)} [options.activeAgentIds] - CoS agents currently running
 *   (never reaped), or a getter re-read per tree and again before removal. Anything but a
 *   Set reads as "liveness unknown" and holds every `agent-*` tree.
 * @param {boolean} [options.includeClaudeTrees=true] - also reap `.claude/worktrees/`
 * @param {{agents?: object[]|null, readAgents?: () => Promise<object[]|null>}} [options.claimOwners] -
 *   trusted agent registry reader or snapshot; omitted reads state.json
 * @returns {Promise<{reaped: Array<{path,branch,locked,branchDeleted}>, skipped: Array<{path,branch,reason,warning?}>, defaultBranch: string, target: string}>}
 */
export async function reapMergedWorktrees(sourceWorkspace, {
  activeAgentIds = new Set(),
  claimOwners,
  includeClaudeTrees = true,
  appId = null
} = {}) {
  const { getDefaultBranch, hasBranchMergeEvidence } = await import('./git.js');
  const { readClaimOwnershipAgents, retireWithUnlockedArchive } = await import('./cosClaimOwnershipState.js');
  const { readBranchCompletionHold } = await import('./branchCompletionPolicy.js');
  // Every entry point (scheduled or reconcile) needs a trusted
  // registry. loadState/getAgents may default a corrupt file to empty state.
  const readOwners = claimOwnerReader(claimOwners, readClaimOwnershipAgents);
  const readActiveIds = activeIdsReader(activeAgentIds);

  const defaultBranch = await getDefaultBranch(sourceWorkspace).catch(() => null) || 'main';
  const target = await resolveMergeTarget(sourceWorkspace, defaultBranch);

  const currentBranch = await execGit(['rev-parse', '--abbrev-ref', 'HEAD'], sourceWorkspace, { ignoreExitCode: true })
    .then(r => r.stdout.trim())
    .catch(() => '');

  const protectedBranches = new Set([...PROTECTED_BRANCHES, defaultBranch]);
  const claudeTreesRoot = join(sourceWorkspace, '.claude', 'worktrees');
  const managedRoots = [
    { path: WORKTREES_DIR, requireAgentId: true },
    { path: claudeTreesRoot, requireAgentId: false },
  ];

  // An unreadable inventory is not an empty successful sweep: callers must
  // retain work rather than falling through to receipt-free orphan cleanup.
  const worktrees = await listWorktrees(sourceWorkspace);
  const reaped = [];
  const skipped = [];

  for (const wt of worktrees) {
    // Never touch the primary worktree (the main repo checkout).
    if (pathsEqual(wt.path, sourceWorkspace)) continue;
    if (wt.bare || wt.detached || !wt.branch) { skipped.push({ path: wt.path, reason: 'no-branch' }); continue; }

    const branchName = wt.branch.replace(/^refs\/heads\//, '');
    if (!branchName) { skipped.push({ path: wt.path, reason: 'no-branch' }); continue; }
    // Named so a caller can say WHICH branch a hold kept, not just which path.
    const hold = (reason) => skipped.push({ path: wt.path, branch: branchName, reason });
    if (protectedBranches.has(branchName) || branchName === currentBranch) {
      hold('protected');
      continue;
    }

    const isClaudeTree = isPathInsideDir(claudeTreesRoot, wt.path);
    const ownershipReason = worktreeOwnershipReason({
      path: wt.path,
      locked: wt.locked,
      activeAgentIds: readActiveIds(),
      roots: managedRoots,
      requireKnownLiveness: true,
    });
    if (ownershipReason) { hold(ownershipReason); continue; }
    if (isClaudeTree && !includeClaudeTrees) { hold('claude-tree-excluded'); continue; }

    // Gate 1: working tree must be completely clean. Unlike removeWorktree(),
    // the background reaper does not discard even lockfile-only edits: an
    // uncommitted fresh-from-main worktree may be an active agent that has not
    // made its first commit yet.
    //
    // Only a proven-absent directory is empty. A prunable registration may
    // instead be an existing checkout with a broken .git pointer and unique work.
    const status = await readWorktreeStatus(wt.path);
    if (status === null) { hold('status-failed'); continue; }
    if (!classifyWorktreeDirt(status).clean) { hold('uncommitted'); continue; }

    // Gate 2: branch fully merged into the default branch (regular, squash, or rebase).
    const hasMergeEvidence = await hasBranchMergeEvidence(sourceWorkspace, branchName, target).catch(() => false);
    if (!hasMergeEvidence) { hold('unmerged'); continue; }

    // The early reconcile pass must see the SAME registered owners and branch
    // reservations as later retirement. Binding stays excluded until removal and
    // branch deletion settle — by the lock, and by the checkout fence while the
    // archive runs between the two critical sections (#12682).
    const verifyRemoval = async (holder) => {
      if (!holder || holder.branch !== wt.branch) return 'worktree-holder-changed';
      const agents = await readOwners();
      const ownerReason = claimCheckoutOwnerReason({ branchName, holderPath: wt.path, sourceWorkspace, agents });
      if (ownerReason) return ownerReason;
      const policyHold = await readBranchCompletionHold({ repoPath: sourceWorkspace, branch: branchName, tip: wt.head, retirement: true });
      if (policyHold) return policyHold;
      const reason = worktreeOwnershipReason({ path: wt.path, locked: holder.locked, activeAgentIds: readActiveIds(), roots: managedRoots, requireKnownLiveness: true });
      if (reason) return reason;
      const freshStatus = await readWorktreeStatus(wt.path);
      if (freshStatus === null) return 'worktree-status-unavailable';
      if (!classifyWorktreeDirt(freshStatus).clean) return 'worktree-dirty';
      return await hasBranchMergeEvidence(sourceWorkspace, branchName, target).catch(() => false) ? null : 'unmerged';
    };
    await retireWithUnlockedArchive({
      busy: () => hold('checkout-retirement-reserved'),
      admit: async () => {
        const initialHold = await verifyRemoval(wt);
        if (initialHold) { hold(initialHold); return {}; }
        return { fence: { repoPath: sourceWorkspace, path: wt.path, branch: branchName } };
      },
      archive: async () => {
        const { releaseCheckoutWithoutArchive } = await import('./heldCheckoutRecovery.js');
        try {
          return await releaseCheckoutWithoutArchive({ repoPath: sourceWorkspace, path: wt.path, branch: branchName }, async () => {
            const hold = await verifyRemoval(wt);
            if (hold) {
              skipped.push({ path: wt.path, branch: branchName, reason: hold });
              return {};
            }
            return { archive: { verify: holder => verifyRemoval(holder) } };
          });
        } catch (error) {
          skipped.push({ path: wt.path, branch: branchName, reason: 'checkout-not-disposable', detail: error.message });
          return {};
        }
      },
      finish: async (_admitted, preservation) => {
        const { readRetirementCheckoutIdentity } = await import('../lib/retirementCheckoutObservation.js');
        const checkoutIdentity = await readRetirementCheckoutIdentity(wt.path).catch(() => null);
        const removal = await forceRemoveWorktreeDir(sourceWorkspace, wt.path, {
          label: `worktree remove failed for ${wt.path}`,
          verifyRemoval: async holder => await verifyRemoval(holder) || await preservation.verify(holder),
        });
        if (!removal.removed) {
          skipped.push({ path: wt.path, branch: branchName, reason: removal.reason || 'remove-failed', warning: removal.warning });
          return;
        }
        const holders = removal.entries || await listWorktrees(sourceWorkspace).catch(() => null);
        const branchDeleted = holders && !holders.some(holder => holder.branch === wt.branch)
          && await deleteCompletedLocalBranch(sourceWorkspace, branchName, wt.head);
        if (branchDeleted && appId) {
          const { recordHeldCheckoutRetirement } = await import('./taskSchedule.js');
          const recorded = await recordHeldCheckoutRetirement(appId, {
            path: wt.path, branch: branchName, head: wt.head, branchDeleted: true,
            ...(checkoutIdentity && { checkoutIdentity }),
          }).then(outcome => outcome?.retired?.some(row => row.path === wt.path && row.branch === branchName
            && row.head === wt.head && row.branchDeleted === true && row.archiveDir == null
            && (!checkoutIdentity || row.checkoutIdentity === checkoutIdentity)) === true, () => false);
          if (!recorded) { hold('retirement-receipt-unverified'); return; }
        }
        reaped.push({ path: wt.path, branch: branchName, locked: !!wt.locked, branchDeleted: Boolean(branchDeleted) });
        if (!branchDeleted) hold('branch-ref-changed-or-new-holder');
      },
    });
  }

  if (reaped.length > 0) {
    console.log(`🌳 Reaped ${reaped.length} merged worktree(s): ${reaped.map(r => r.branch).join(', ')}`);
  }

  return { reaped, skipped, defaultBranch, target };
}

/**
 * Clean up worktree directories that belong to external repos (managed apps).
 * These are created when agents work on apps outside PortOS but use the shared
 * worktrees directory. They're invisible to PortOS's `git worktree list`.
 */
async function cleanupExternalRepoWorktrees(readActiveIds, alreadyHandled, readOwners, retainedPaths) {
  const { getDefaultBranch, hasBranchMergeEvidence } = await import('./git.js');
  const { retireWithUnlockedArchive } = await import('./cosClaimOwnershipState.js');
  const entries = await readdir(WORKTREES_DIR, { withFileTypes: true }).catch(() => []);
  let cleaned = 0;

  for (const entry of entries) {
    if (!entry.isDirectory() || alreadyHandled.has(entry.name)) continue;
    const worktreePath = join(WORKTREES_DIR, entry.name);
    const ownership = (extra = {}) => worktreeOwnershipReason({
      path: worktreePath,
      activeAgentIds: readActiveIds(),
      roots: [{ path: WORKTREES_DIR, requireAgentId: true }],
      requireKnownLiveness: true,
      ...extra,
    });
    if (ownership()) continue;
    const gitFile = await lstat(join(worktreePath, '.git')).catch(() => null);
    if (!gitFile?.isFile()) continue;

    // Ask Git for its common directory and actual registration, rather than
    // inferring a parent from the spelling of a .git file. Relative pointers,
    // separate git directories and Windows separators are all valid.
    const commonDir = await execGit(['rev-parse', '--git-common-dir'], worktreePath)
      .then(r => r.stdout.trim() ? resolve(worktreePath, r.stdout.trim()) : null).catch(() => null);
    if (!commonDir) continue;
    // Git expands Windows short (8.3) aliases even where Node's realpath
    // keeps them. Compare Git's own spelling with its registration output.
    const gitWorktreePath = await execGit(['rev-parse', '--show-toplevel'], worktreePath)
      .then(r => r.stdout.trim()).catch(() => null);
    if (!gitWorktreePath || retainedPaths.has(gitWorktreePath)) continue;
    const registrations = await listWorktrees(worktreePath).catch(() => []);
    const wt = registrations.find(candidate => pathsEqual(candidate.path, gitWorktreePath));
    const primary = registrations[0];
    if (!wt || wt.bare || wt.detached || wt.prunable || !wt.branch) continue;
    if (!primary || primary.bare || pathsEqual(primary.path, gitWorktreePath)) continue;
    if (ownership({ locked: wt.locked })) continue;

    const parentRepo = primary.path;
    const parentCommonDir = await execGit(['rev-parse', '--git-common-dir'], parentRepo)
      .then(r => r.stdout.trim() ? resolve(parentRepo, r.stdout.trim()) : null).catch(() => null);
    if (!parentCommonDir || !pathsEqual(commonDir, parentCommonDir)) continue;

    const branchName = wt.branch.replace(/^refs\/heads\//, '');
    const defaultBranch = await getDefaultBranch(parentRepo, { strict: true }).catch(() => null);
    if (!defaultBranch || PROTECTED_BRANCHES.includes(branchName) || branchName === defaultBranch) continue;
    const status = await execGit(['status', '--porcelain'], worktreePath).then(r => r.stdout).catch(() => null);
    if (status === null || !classifyWorktreeDirt(status).clean) continue;
    const target = await resolveMergeTarget(parentRepo, defaultBranch);
    const merged = await hasBranchMergeEvidence(parentRepo, branchName, target).catch(() => false);
    if (!merged) continue;

    // Non-force removal is a final Git guard against newly dirty or locked
    // trees. A refusal must never fall through to recursive filesystem removal.
    // The archive runs between two ownership critical sections (#12748) with
    // this checkout fenced; both re-read liveness and the registry.
    const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
    const removed = await withCheckoutPublication(parentRepo, () => retireWithUnlockedArchive({
      busy: () => false,
      admit: async () => {
        if (ownership({ locked: wt.locked })
          || claimCheckoutOwnerReason({ branchName, holderPath: worktreePath, sourceWorkspace: parentRepo, agents: await readOwners() })) return { result: false };
        return { fence: { repoPath: parentRepo, path: worktreePath, branch: branchName } };
      },
      archive: async () => {
        const { readRetirementCheckoutIdentity } = await import('../lib/retirementCheckoutObservation.js');
        const checkoutIdentity = await readRetirementCheckoutIdentity(worktreePath).catch(() => null);
        const { releaseCheckoutWithoutArchive } = await import('./heldCheckoutRecovery.js');
        return releaseCheckoutWithoutArchive({ repoPath: parentRepo, path: worktreePath, branch: branchName }, async () => ({
          archive: {
            ...(checkoutIdentity && { checkoutIdentity }),
            verify: async (latest) => {
              if (!latest || latest.head !== wt.head || latest.branch !== wt.branch) return 'worktree-holder-changed';
              const status = await execGit(['status', '--porcelain'], worktreePath).then(r => r.stdout, () => null);
              if (status === null || !classifyWorktreeDirt(status).clean) return 'worktree-dirty';
              if (!await hasBranchMergeEvidence(parentRepo, wt.head, target).catch(() => false)) return 'unmerged';
              return null;
            },
          },
        }));
      },
      finish: async (_admitted, preservation) => {
        const latest = (await listWorktrees(parentRepo)).find(holder => pathsEqual(holder.path, worktreePath));
        if (ownership({ locked: latest?.locked }) || await preservation.verify(latest)
          || claimCheckoutOwnerReason({ branchName, holderPath: worktreePath, sourceWorkspace: parentRepo, agents: await readOwners() })
          || !await hasBranchMergeEvidence(parentRepo, wt.head, target).catch(() => false)) return false;
        const { readBranchCompletionHold } = await import('./branchCompletionPolicy.js');
        if (await readBranchCompletionHold({ repoPath: parentRepo, branch: branchName, retirement: true })) return false;
        const ok = await execGit(['worktree', 'remove', worktreePath], parentRepo).then(() => true).catch(err => {
          console.warn(`⚠️ Preserved external worktree ${entry.name}: ${err.message}`);
          return false;
        });
        const deleted = ok && await deleteCompletedLocalBranch(parentRepo, branchName, wt.head);
        if (ok && !deleted) {
          console.warn(`⚠️ External branch ${branchName} retained: head changed, new holder, or deletion refused`);
        }
        if (ok) {
          const { recordWorkspaceCheckoutRetirement } = await import('./taskSchedule.js');
          await recordWorkspaceCheckoutRetirement(parentRepo, {
            path: wt.path, branch: branchName, head: wt.head, branchDeleted: Boolean(deleted),
            ...(preservation?.checkoutIdentity && { checkoutIdentity: preservation.checkoutIdentity }),
          }).catch(error => { console.warn(`⚠️ External retirement receipt not recorded for ${entry.name}: ${error.message}`); });
        }
        return ok;
      },
    })).catch(err => {
      console.warn(`⚠️ Preserved external worktree ${entry.name}: ${err.message}`);
      return false;
    });
    if (removed) cleaned++;
  }

  return cleaned;
}