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

106 KB
Raw Blame
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
// Git/filesystem are synthetic in this suite; real durable admission has its own boundary tests.
const publicationMock = vi.hoisted(() => vi.fn((_repo, work) => work()));
vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (...args) => publicationMock(...args) }));
import { dirname, join } from 'path';

// Stub every git operation; lifecycle tests exercise the real service without
// creating, changing or removing a live repository.
const releaseCheckoutMock = vi.fn(async (_context, prepare) => prepare());
const preserveCheckoutMock = vi.fn(async () => ({ archiveDir: '/archive', verify: async () => null }));
const preservedBranch = () => ({ archiveDir: '/branch-archive', verify: async () => true, retire: work => work() });
const preserveBranchMock = vi.fn(async () => preservedBranch());
vi.mock('../lib/branchRetirementArchive.js', () => ({ preserveBranchRetirement: (...args) => preserveBranchMock(...args) }));
vi.mock('./heldCheckoutRecovery.js', () => ({
  preserveMergedCheckout: (...args) => preserveCheckoutMock(...args),
  releaseCheckoutWithoutArchive: (...args) => releaseCheckoutMock(...args),
}));
const retirementReceiptMock = vi.hoisted(() => vi.fn(async () => null));
vi.mock('./taskSchedule.js', () => ({ recordWorkspaceCheckoutRetirement: retirementReceiptMock }));
const completionOwnersMock = vi.fn(async () => []);
vi.mock('./cosClaimOwnershipState.js', async importOriginal => ({ ...await importOriginal(), readClaimOwnershipAgents: (...args) => completionOwnersMock(...args) }));
const completionHoldMock = vi.fn(async () => null);
vi.mock('./branchCompletionPolicy.js', () => ({ readBranchCompletionHold: (...args) => completionHoldMock(...args) }));
const execGitMock = vi.fn();
vi.mock('../lib/execGit.js', () => ({ execGit: (...args) => execGitMock(...args) }));

// Stub filesystem effects as well as git so destructive cleanup stays in fixtures.
vi.mock('fs', () => {
  const realpathSync = vi.fn(p => p);
  realpathSync.native = realpathSync;
  return { existsSync: vi.fn().mockReturnValue(true), realpathSync };
});
vi.mock('fs/promises', () => ({
  lstat: vi.fn().mockResolvedValue({}),
  readdir: vi.fn().mockResolvedValue([]),
  rm: vi.fn().mockResolvedValue(undefined),
  stat: vi.fn().mockResolvedValue({ isDirectory: () => true }),
  readlink: vi.fn().mockResolvedValue(''),
  symlink: vi.fn().mockResolvedValue(undefined),
  unlink: vi.fn().mockResolvedValue(undefined),
  // lib/worktreeNodeModules.js (workspace-link farm); its behavior has a real-filesystem suite.
  rmdir: vi.fn().mockResolvedValue(undefined),
  writeFile: vi.fn().mockResolvedValue(undefined),
  // adoptWorktree ensures the worktrees root exists before moving a tree into it.
  mkdir: vi.fn().mockResolvedValue(undefined),
}));
// The retry path asks whether the lock it just hit was abandoned. Mocked here
// (the `fs` stub above has no `statSync`, and real mtimes would make this a
// clock test); `lib/gitStaleLock.test.js` owns which locks it agrees to remove.
const clearStaleGitLockMock = vi.fn().mockReturnValue(null);
vi.mock('../lib/gitStaleLock.js', () => ({ clearStaleGitLock: (...args) => clearStaleGitLockMock(...args) }));
vi.mock('./instanceIdentity.js', () => ({ ensureInstanceId: vi.fn().mockResolvedValue('instance-1') }));
const getDefaultBranchMock = vi.fn().mockResolvedValue('main');
const hasBranchMergeEvidenceMock = vi.fn().mockResolvedValue(false);
vi.mock('./git.js', () => ({
  getDefaultBranch: (...args) => getDefaultBranchMock(...args),
  hasBranchMergeEvidence: (...args) => hasBranchMergeEvidenceMock(...args),
}));

const {
  shouldRefuseDefaultBranchMerge,
  deleteCompletedLocalBranch,
  forceRemoveWorktreeDir,
  isHumanClaimWorktree,
  classifyWorktreeDirt,
  isGitLockError,
  addWorktreeWithRetry,
  isPreexistingRefError,
  isBranchCheckedOutElsewhereError,
  removeWorktree,
  removePersistentWorktree,
  adoptWorktree,
  findAdoptableWorktreeForBranch,
  createWorktree,
  createPersistentWorktree,
  linkWorktreeDependencies,
  unlinkWorktreeDependencies,
  listWorktrees,
  cleanupOrphanedWorktrees,
  WORKTREE_ADD_TIMEOUT_MS,
} = await import('./worktreeManager.js');
const { isPathInsideDir } = await import('../lib/fileUtils.js');
const { win32 } = await import('path');
const { existsSync, realpathSync } = await import('fs');
const { lstat, readdir, rm, stat, readlink, symlink, unlink } = await import('fs/promises');
const { PATHS } = await import('../lib/fileUtils.js');

describe('completed branch archival boundary', () => {
  const head = 'a'.repeat(40);
  beforeEach(() => {
    execGitMock.mockReset().mockImplementation(async args => ({
      stdout: args.includes('--git-common-dir') ? '/repo/.git' : '', exitCode: 0,
    }));
    getDefaultBranchMock.mockResolvedValue('main');
    preserveBranchMock.mockReset().mockResolvedValue(preservedBranch());
  });
  afterEach(() => {
    preserveBranchMock.mockReset().mockResolvedValue(preservedBranch());
  });
  it('runs the trusted receiver guard before deletion and preserves its refusal reason without pushing', async () => {
    execGitMock.mockImplementation(async args => {
      if (args.includes('--git-common-dir')) return { stdout: '/repo/.git', exitCode: 0 };
      if (args[0] === 'rev-parse' && args[1] === '--verify') return { stdout: `${head}\n`, exitCode: 0 };
      return { stdout: '', exitCode: 0 };
    });
    const beforeMutation = vi.fn(async () => { throw new Error('daemon-paused'); });
    await expect(deleteCompletedLocalBranch('/repo', 'done', head, { beforeMutation })).rejects.toThrow('daemon-paused');
    expect(beforeMutation).toHaveBeenCalledOnce();
    expect(preserveBranchMock).not.toHaveBeenCalled();
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push')).toBe(false);
  });
  it('checks automatic permission after final registration refresh before checkout removal', async () => {
    let reads = 0, verified = false;
    execGitMock.mockImplementation(async args => {
      if (args[0] === 'worktree' && args[1] === 'list') {
        reads++;
        return { stdout: `worktree /checkout\nHEAD ${head}\nbranch refs/heads/done\n\n`, exitCode: 0 };
      }
      return { stdout: '', exitCode: 0 };
    });
    const beforeMutation = vi.fn(async () => {
      expect(verified).toBe(true); expect(reads).toBe(2);
      throw new Error('daemon-paused');
    });
    expect(await forceRemoveWorktreeDir('/repo', '/checkout', {
      verifyRemoval: async () => { verified = true; return null; }, beforeMutation,
    })).toMatchObject({ removed: false, reason: 'daemon-paused' });
    expect(beforeMutation).toHaveBeenCalledOnce();
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'worktree' && ['remove', 'prune'].includes(args[1]))).toBe(false);
  });
  it('rechecks automatic permission before pruning an already absent checkout after a failed removal', async () => {
    execGitMock.mockImplementation(async args => {
      if (args[0] === 'worktree' && args[1] === 'remove') throw new Error('remove interrupted');
      return { stdout: '', exitCode: 0 };
    });
    lstat.mockRejectedValueOnce(Object.assign(new Error('missing'), { code: 'ENOENT' }));
    const beforeMutation = vi.fn().mockResolvedValueOnce(undefined).mockRejectedValueOnce(new Error('daemon-stopped'));
    expect(await forceRemoveWorktreeDir('/repo', '/checkout', { verifyRemoval: async () => null, beforeMutation }))
      .toMatchObject({ removed: false, reason: 'daemon-stopped' });
    expect(beforeMutation).toHaveBeenCalledTimes(2);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'worktree' && args[1] === 'prune')).toBe(false);
  });
  it('reports a caller gate that keeps the checkout on stdout, since that cleanup is retryable by design', async () => {
    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    expect(await forceRemoveWorktreeDir('/repo', '/checkout', { label: 'cleanup', verifyRemoval: async () => 'retirement-forge-unavailable' }))
      .toMatchObject({ removed: false, reason: 'retirement-forge-unavailable' });
    expect(log).toHaveBeenCalledWith(expect.stringContaining('Worktree cleanup incomplete'));
    expect(warn).not.toHaveBeenCalled();
  });
  it('warns when Git itself refused to remove a checkout that survives', async () => {
    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    execGitMock.mockImplementation(async args => {
      if (args[0] === 'worktree' && args[1] === 'remove') throw new Error('Permission denied');
      return { stdout: '', exitCode: 0 };
    });
    expect(await forceRemoveWorktreeDir('/repo', '/checkout', { label: 'cleanup', verifyRemoval: async () => null }))
      .toMatchObject({ removed: false, reason: 'worktree-removal-refused' });
    expect(warn).toHaveBeenCalledWith(expect.stringContaining('Worktree cleanup incomplete'));
    expect(log).not.toHaveBeenCalledWith(expect.stringContaining('Worktree cleanup incomplete'));
  });
  it('deletes a completed ref without archiving it once the receiver drops the ref', async () => {
    execGitMock.mockImplementation(async args => {
      if (args.includes('--git-common-dir')) return { stdout: '/repo/.git', exitCode: 0 };
      if (args[0] === 'rev-parse' && args[1] === '--verify') return { stdout: `${head}\n`, exitCode: 0 };
      if (args[0] === 'show-ref') return { stdout: '', exitCode: 1 };
      return { stdout: '', exitCode: 0 };
    });
    expect(await deleteCompletedLocalBranch('/repo', 'done', head)).toBe(true);
    expect(preserveBranchMock).not.toHaveBeenCalled();
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push')).toBe(true);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'config' && args.includes('--remove-section'))).toBe(true);
  });
});

describe('Worktree dependency preparation', () => {
  const directories = ['client', 'server', 'admin', 'uninstalled', 'assets', '.hidden', 'node_modules', 'nested'];
  const missing = () => Promise.reject(Object.assign(new Error('missing'), { code: 'ENOENT' }));
  const normalize = path => path.replaceAll('\\', '/');

  beforeEach(() => {
    lstat.mockReset();
    readlink.mockReset();
    symlink.mockClear();
    unlink.mockClear();
    existsSync.mockImplementation(path => normalize(path) === '/repo/nested/.git');
    // The source's node_modules holds no workspace links, so the plain directory symlink applies.
    readdir.mockImplementation(async path => normalize(path).endsWith('/repo/node_modules') ? [] : [
      ...directories.map(name => ({ name, isDirectory: () => true })),
      { name: 'linked-package', isDirectory: () => false },
    ]);
    stat.mockImplementation(path => normalize(path) === '/repo/uninstalled/node_modules'
      ? missing() : Promise.resolve({ isDirectory: () => true }));
    lstat.mockImplementation(path => {
      const normalized = normalize(path);
      if (directories.filter(name => name !== 'node_modules').some(name => normalized === `/repo/${name}`)) {
        return Promise.resolve({ isDirectory: () => true });
      }
      if (normalized.endsWith('/package.json') && normalized !== '/worktree/assets/package.json') {
        return Promise.resolve({ isFile: () => true });
      }
      return missing();
    });
  });

  afterEach(() => {
    lstat.mockReset().mockResolvedValue({});
    readdir.mockReset().mockResolvedValue([]);
    stat.mockReset().mockResolvedValue({ isDirectory: () => true });
    existsSync.mockReset().mockReturnValue(true);
  });

  it('links installed immediate packages including admin and skips non-packages, hidden and nested repos', async () => {
    await linkWorktreeDependencies('/repo', '/worktree');

    expect(symlink.mock.calls.map(([source, target]) => [normalize(source), normalize(target)]))
      .toEqual(expect.arrayContaining(['', '/client', '/server', '/admin'].map(part => [
        `/repo${part}/node_modules`, `/worktree${part}/node_modules`,
      ])));
    expect(symlink).toHaveBeenCalledTimes(4);
  });

  it('preserves existing real directories and foreign links', async () => {
    const original = lstat.getMockImplementation();
    lstat.mockImplementation(path => normalize(path).endsWith('/node_modules')
      ? Promise.resolve({ isSymbolicLink: () => normalize(path).includes('/admin/') })
      : original(path));

    await linkWorktreeDependencies('/repo', '/worktree');
    expect(symlink).not.toHaveBeenCalled();
  });

  it('removes only owned links including admin, even if source dependencies were removed', async () => {
    lstat.mockImplementation(path => {
      const normalized = normalize(path);
      if (['/worktree/node_modules', '/worktree/admin/node_modules', '/worktree/client/node_modules', '/worktree/server/node_modules'].includes(normalized)) {
        return Promise.resolve({ isSymbolicLink: () => normalized !== '/worktree/client/node_modules' });
      }
      return missing();
    });
    stat.mockImplementation(missing);
    readlink.mockImplementation(path => Promise.resolve(normalize(path).includes('/server/')
      ? join('/foreign', 'node_modules')
      : path.replace('worktree', 'repo')));

    await unlinkWorktreeDependencies('/repo', '/worktree');

    expect(unlink.mock.calls.map(([path]) => normalize(path)).sort()).toEqual([
      '/worktree/admin/node_modules', '/worktree/node_modules',
    ]);
  });
});

describe('classifyWorktreeDirt (real exported helper)', () => {
  it('reports clean for empty / whitespace-only porcelain', () => {
    expect(classifyWorktreeDirt('')).toEqual({ clean: true, lockfileOnly: false, lockfilePaths: [], untrackedLockfilePaths: [], realChangePaths: [], hasRealChanges: false });
    expect(classifyWorktreeDirt('  \n  ').clean).toBe(true);
    expect(classifyWorktreeDirt(null).clean).toBe(true);
  });

  it('flags real (non-lockfile) changes', () => {
    const r = classifyWorktreeDirt(' M src/index.js');
    expect(r.clean).toBe(false);
    expect(r.hasRealChanges).toBe(true);
    expect(r.lockfileOnly).toBe(false);
  });

  it('preserveLockfiles reports lockfiles as real changes', () => {
    const r = classifyWorktreeDirt(' M package-lock.json\n', { preserveLockfiles: true });
    expect(r).toMatchObject({ lockfileOnly: false, hasRealChanges: true, realChangePaths: ['package-lock.json'], lockfilePaths: [] });
  });

  it('recognizes a lockfile-only working tree and extracts paths', () => {
    const r = classifyWorktreeDirt(' M package-lock.json\n M client/package-lock.json');
    expect(r.lockfileOnly).toBe(true);
    expect(r.hasRealChanges).toBe(false);
    expect(r.lockfilePaths).toEqual(['package-lock.json', 'client/package-lock.json']);
  });

  it('decodes Git-quoted paths before lockfile and scratch classification', () => {
    const lockfile = classifyWorktreeDirt(' M "my app/package-lock.json"\n');
    expect(lockfile.lockfileOnly).toBe(true);
    expect(lockfile.lockfilePaths).toEqual(['my app/package-lock.json']);
    const emojiPath = classifyWorktreeDirt(' M "my 😀 app/package-lock.json"');
    expect(emojiPath.lockfilePaths).toEqual(['my 😀 app/package-lock.json']);

    expect(classifyWorktreeDirt('?? ".portos-public-review/"').clean).toBe(true);
    expect(classifyWorktreeDirt('?? "PORTOS_PUBLIC_REVIEW_INPUT.json"').clean).toBe(true);
    expect(classifyWorktreeDirt('?? "caf\\303\\251/package-lock.json"').lockfilePaths)
      .toEqual(['café/package-lock.json']);
  });

  it('treats mixed lockfile + real changes as real changes', () => {
    const r = classifyWorktreeDirt(' M package-lock.json\n M src/app.js');
    expect(r.lockfileOnly).toBe(false);
    expect(r.hasRealChanges).toBe(true);
  });

  // realChangePaths feeds branch reconciliation's supersession check — it
  // intersects them with what the default branch changed since the branch
  // diverged, so the paths must be bare and lockfile-free.
  it('extracts the non-lockfile paths, excluding lockfiles and untangling renames', () => {
    const r = classifyWorktreeDirt(' M package-lock.json\n M src/app.js\n?? src/new.js\nR  src/old.js -> src/renamed.js');
    expect(r.realChangePaths).toEqual(['src/app.js', 'src/new.js', 'src/renamed.js']);
    expect(r.realChangePaths).not.toContain('package-lock.json');
  });

  it('splits quoted rename paths without treating a literal arrow as the separator', () => {
    const r = classifyWorktreeDirt('R  "a -> b/x" -> "a b/y"');
    expect(r.realChangePaths).toEqual(['a b/y']);
  });

  it('handles a trimmed first line (no leading status space)', () => {
    const r = classifyWorktreeDirt('M yarn.lock');
    expect(r.lockfileOnly).toBe(true);
    expect(r.lockfilePaths).toEqual(['yarn.lock']);
  });

  it('can ignore a consumed completion sentinel without hiding real work', () => {
    expect(classifyWorktreeDirt('?? .agent-done', { ignoredPaths: ['.agent-done'] }).clean).toBe(true);

    const r = classifyWorktreeDirt('?? .agent-done\n M src/index.js', { ignoredPaths: ['.agent-done'] });
    expect(r.hasRealChanges).toBe(true);
    expect(r.realChangePaths).toEqual(['src/index.js']);
  });

  it('ignores the per-agent sentinel name without hiding real work', () => {
    // The sentinel filename carries the agent id (see doneSentinelName), so the
    // caller passes THIS run's name — not a wildcard that would also swallow a
    // sibling agent's sentinel.
    const ignoredPaths = ['.agent-done', '.agent-done-agent-1'];
    expect(classifyWorktreeDirt('?? .agent-done-agent-1', { ignoredPaths }).clean).toBe(true);

    const r = classifyWorktreeDirt('?? .agent-done-agent-1\n M src/index.js', { ignoredPaths });
    expect(r.hasRealChanges).toBe(true);
    expect(r.realChangePaths).toEqual(['src/index.js']);
    // Another agent's sentinel is NOT ignored — an unrelated run's file in a
    // shared checkout is still dirt this caller must not silently discard.
    expect(classifyWorktreeDirt('?? .agent-done-agent-2', { ignoredPaths }).clean).toBe(false);
  });

  // PortOS materializes the public-review bundle INTO the worktree it hands a
  // reviewer model and never commits it. Subtracted for EVERY caller rather than
  // passed in per call: counted as work, it made `removeWorktree` preserve the
  // tree, `reapMergedWorktrees` hold it, and branch-reconcile spend a coordinator
  // run per pass concluding "no real work product, a human should discard it".
  it('subtracts PortOS runtime scratch with no ignoredPaths from the caller', () => {
    expect(classifyWorktreeDirt('?? PORTOS_PUBLIC_REVIEW_INPUT.json').clean).toBe(true);
    // Untracked directories arrive collapsed to their root…
    expect(classifyWorktreeDirt('?? .portos-public-review/').clean).toBe(true);
    // …and expanded to files under -uall.
    expect(classifyWorktreeDirt('?? .portos-public-review/PR-42.patch').clean).toBe(true);
    expect(classifyWorktreeDirt('?? PORTOS_PUBLIC_REVIEW_INPUT.json\n?? .portos-public-review/').clean).toBe(true);
  });

  it('still reports real work sitting beside the scratch', () => {
    const r = classifyWorktreeDirt('?? PORTOS_PUBLIC_REVIEW_INPUT.json\n M src/index.js');
    expect(r.hasRealChanges).toBe(true);
    expect(r.realChangePaths).toEqual(['src/index.js']);
    // A sibling that merely shares the prefix is real work, not scratch.
    expect(classifyWorktreeDirt('?? .portos-public-review-notes.md').hasRealChanges).toBe(true);
  });
});

// Git reports POSIX separators on every platform, while PATHS.worktrees is
// backslash-separated on Windows — so a bare `startsWith` matched nothing there:
// `cleanupOrphanedWorktrees` skipped every CoS worktree and `reapMergedWorktrees`
// filed them all as `unmanaged-location`, which is why the daily line read
// "reaped 0 merged + 0 orphaned" on a Windows install with orphans on disk.
// These pin the properties the module RELIES ON from the shared helpers, so a
// change to either one surfaces here rather than as silent dead cleanup.
describe('git-vs-PortOS path comparison', () => {
  it('matches a git-reported POSIX path against a Windows worktrees dir', () => {
    // win32-only: `resolvePath` folds `/` to `\` on Windows, which is what makes
    // the mixed-separator comparison work. On POSIX a backslash is a legal
    // filename character, so this case can't arise and isn't asserted.
    if (process.platform !== 'win32') return;
    expect(isPathInsideDir('H:\\repo\\data\\cos\\worktrees', 'H:/repo/data/cos/worktrees/agent-abc')).toBe(true);
  });

  it('does not match a sibling directory that merely shares a prefix', () => {
    expect(isPathInsideDir('/repo/data/cos/worktrees', '/repo/data/cos/worktrees-old/agent-abc')).toBe(false);
  });

  it('does not treat the directory itself as being under itself', () => {
    expect(isPathInsideDir('/repo/data/cos/worktrees', '/repo/data/cos/worktrees')).toBe(false);
  });

  it('reads the agent id off either separator', () => {
    expect(win32.basename('H:/repo/data/cos/worktrees/agent-abc')).toBe('agent-abc');
    expect(win32.basename('H:\\repo\\data\\cos\\worktrees\\agent-abc')).toBe('agent-abc');
  });
});

describe('isHumanClaimWorktree', () => {
  it('is true for /claim worktree dir names', () => {
    expect(isHumanClaimWorktree('claim-extract-compare-helpers')).toBe(true);
    expect(isHumanClaimWorktree('claim-codex5-onboarding-capability-map')).toBe(true);
  });

  it('is false for CoS agent worktree dir names', () => {
    expect(isHumanClaimWorktree('agent-1a2b3c4d')).toBe(false);
    expect(isHumanClaimWorktree('cos-task-xyz')).toBe(false);
  });

  it('is false for non-string / empty input (fail safe)', () => {
    expect(isHumanClaimWorktree(undefined)).toBe(false);
    expect(isHumanClaimWorktree(null)).toBe(false);
    expect(isHumanClaimWorktree('')).toBe(false);
  });
});

describe('Default-Branch Merge Gate (defense-in-depth)', () => {
  it('allows merge when source repo HEAD matches the default branch', () => {
    expect(shouldRefuseDefaultBranchMerge('main', 'main')).toBe(false);
  });

  it('allows merge for a non-main default (e.g. master, dev)', () => {
    expect(shouldRefuseDefaultBranchMerge('master', 'master')).toBe(false);
    expect(shouldRefuseDefaultBranchMerge('develop', 'develop')).toBe(false);
  });

  it('refuses merge when HEAD is on a TUI claim branch', () => {
    expect(shouldRefuseDefaultBranchMerge('claim/extend-syncorchestrator', 'main')).toBe(true);
  });

  it('refuses merge when HEAD is on any feature branch', () => {
    expect(shouldRefuseDefaultBranchMerge('feature/x', 'main')).toBe(true);
    expect(shouldRefuseDefaultBranchMerge('fix/bug-123', 'main')).toBe(true);
  });

  it('refuses merge when HEAD is on another in-flight CoS branch', () => {
    expect(shouldRefuseDefaultBranchMerge('cos/task-abc/agent-xyz', 'main')).toBe(true);
  });

  it('refuses merge when default branch detection failed (fail closed)', () => {
    expect(shouldRefuseDefaultBranchMerge('main', null)).toBe(true);
    expect(shouldRefuseDefaultBranchMerge('main', '')).toBe(true);
    expect(shouldRefuseDefaultBranchMerge('main', undefined)).toBe(true);
  });

  it('refuses merge when source repo HEAD is unknown', () => {
    expect(shouldRefuseDefaultBranchMerge('', 'main')).toBe(true);
    expect(shouldRefuseDefaultBranchMerge(null, 'main')).toBe(true);
    expect(shouldRefuseDefaultBranchMerge(undefined, 'main')).toBe(true);
  });

  it('refuses merge when both inputs are missing', () => {
    expect(shouldRefuseDefaultBranchMerge(null, null)).toBe(true);
  });
});

describe('isGitLockError (worktree add lock detection, #2193)', () => {
  it('recognizes the canonical worktree/index lock errors', () => {
    expect(isGitLockError("fatal: Unable to create '/repo/.git/worktrees/agent-x/index.lock': File exists.")).toBe(true);
    expect(isGitLockError('fatal: could not lock config file .git/config: File exists')).toBe(true);
    expect(isGitLockError('error: cannot lock ref')).toBe(true);
    expect(isGitLockError('Another git process seems to be running in this repository')).toBe(true);
  });

  it('does NOT flag permanent failures — including "already exists", which is NOT lock contention', () => {
    // These fast-fail identically on every retry, so matching them would just
    // burn the retry budget and spam misleading "lock contention" logs (#2193).
    expect(isGitLockError("fatal: invalid reference: origin/nope")).toBe(false);
    expect(isGitLockError('fatal: not a valid object name')).toBe(false);
    expect(isGitLockError("fatal: '/repo/data/cos/worktrees/agent-x' already exists")).toBe(false);
    expect(isGitLockError("fatal: a branch named 'cos/task/agent' already exists")).toBe(false);
    expect(isGitLockError('')).toBe(false);
    expect(isGitLockError(undefined)).toBe(false);
  });

  // A per-file checkout failure is NOT lock contention. It reads "unable to
  // create", but it only happens after git has written most of the tree — so
  // retrying it costs a full checkout per attempt. With the 10-minute add
  // timeout that is 4 × 10 min of head-of-line blocking on the per-repo queue,
  // for an error that never clears. This is the Windows AV-filter failure mode
  // the long timeout exists to tolerate, so the two must not compound.
  it('does NOT flag a per-file checkout failure as lock contention', () => {
    expect(isGitLockError('error: unable to create file some/deep/path.js: Permission denied')).toBe(false);
    expect(isGitLockError('error: unable to create symlink foo/bar: Operation not permitted')).toBe(false);
  });

  it('still flags a genuine lock-FILE creation failure', () => {
    expect(isGitLockError("fatal: Unable to create '/repo/.git/config.lock': File exists")).toBe(true);
  });
});

// Windows git emits CRLF, and a bare split('\n') leaves a trailing \r on every
// parsed value. That is invisible on Linux and silently breaks the reaper on
// Windows: the path and branch carry the \r so containment and equality match
// nothing, and the flag lines stop comparing equal so bare/detached/locked/
// prunable all read false. It failed a real Windows CI job for hours while every
// Linux run stayed green, so the contract is pinned against BOTH line endings.
describe('listWorktrees line endings', () => {
  beforeEach(() => { execGitMock.mockReset(); });

  const PORCELAIN = [
    'worktree /repo',
    'HEAD abc123',
    'branch refs/heads/main',
    '',
    'worktree /repo/.claude/worktrees/wt',
    'HEAD def456',
    'branch refs/heads/feature',
    'locked waiting for explicit owner handoff',
    'prunable',
    '',
    'worktree /repo/detached',
    'HEAD fed789',
    'detached',
    '',
    'worktree /repo/bare',
    'bare',
  ];

  it.each([['LF', '\n'], ['CRLF', '\r\n']])('parses %s porcelain identically', async (_label, eol) => {
    execGitMock.mockResolvedValueOnce({ stdout: PORCELAIN.join(eol), stderr: '', exitCode: 0 });

    const worktrees = await listWorktrees('/repo');

    expect(worktrees).toHaveLength(4);
    // No stray \r anywhere — these values are compared against filesystem paths
    // and branch names, where a trailing carriage return matches nothing.
    expect(worktrees[0]).toMatchObject({ path: '/repo', head: 'abc123', branch: 'refs/heads/main' });
    expect(worktrees[1]).toMatchObject({
      path: '/repo/.claude/worktrees/wt',
      head: 'def456',
      branch: 'refs/heads/feature',
      locked: true,
      lockReason: 'waiting for explicit owner handoff',
      prunable: true,
    });
    expect(worktrees[2]).toEqual({ path: '/repo/detached', head: 'fed789', detached: true });
    expect(worktrees[3]).toEqual({ path: '/repo/bare', bare: true });
  });

  it('returns an empty inventory when git lists no worktrees', async () => {
    execGitMock.mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 });
    expect(await listWorktrees('/repo')).toEqual([]);
  });
});

describe('addWorktreeWithRetry (lock-contention retry, #2193)', () => {
  beforeEach(() => {
    execGitMock.mockReset();
    clearStaleGitLockMock.mockClear();
    vi.useFakeTimers();
  });
  afterEach(() => {
    vi.useRealTimers();
  });

  it('resolves without retrying on first-attempt success', async () => {
    execGitMock.mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 });
    await addWorktreeWithRetry(['worktree', 'add', '/wt', 'main'], '/repo');
    expect(execGitMock).toHaveBeenCalledTimes(1);
  });

  // See WORKTREE_ADD_TIMEOUT_MS for why 30s was not enough.
  it('gives the add far more than execGit\'s 30s default, since it writes a full checkout', async () => {
    execGitMock.mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 });
    await addWorktreeWithRetry(['worktree', 'add', '/wt', 'main'], '/repo');
    const [, , options] = execGitMock.mock.calls[0];
    expect(options?.timeout).toBeGreaterThanOrEqual(5 * 60 * 1000);
  });

  it('does NOT retry a timeout — git is still running and would collide with itself', async () => {
    execGitMock.mockRejectedValueOnce(new Error('git command timed out after 600s: git worktree add -b cos/t/a /wt origin/main'));
    await expect(addWorktreeWithRetry(['worktree', 'add', '-b', 'cos/t/a', '/wt', 'origin/main'], '/repo'))
      .rejects.toThrow(/timed out/);
    expect(execGitMock).toHaveBeenCalledTimes(1);
  });

  it('retries a lock error then succeeds', async () => {
    execGitMock
      .mockRejectedValueOnce(new Error("Unable to create '/repo/.git/index.lock': File exists"))
      .mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 });
    const p = addWorktreeWithRetry(['worktree', 'add', '/wt', 'main'], '/repo');
    await vi.runAllTimersAsync();
    await p;
    expect(execGitMock).toHaveBeenCalledTimes(2);
  });

  // Retrying alone cannot clear an ABANDONED lock — nothing is coming to
  // release it, so all four attempts would fail and block the task.
  it('tries to clear an abandoned lock before backing off', async () => {
    const lockError = new Error("Unable to create '/repo/.git/index.lock': File exists");
    execGitMock
      .mockRejectedValueOnce(lockError)
      .mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 });
    const p = addWorktreeWithRetry(['worktree', 'add', '/wt', 'main'], '/repo');
    await vi.runAllTimersAsync();
    await p;
    expect(clearStaleGitLockMock).toHaveBeenCalledWith(lockError.message);
  });

  // `STALE_GIT_LOCK_MIN_AGE_MS`'s safety argument is "3x the longest git command
  // PortOS can have in flight", and that ceiling is THIS constant — in another
  // file, where raising it would silently erode the headroom and let the sweep
  // unlink a live `git worktree add`'s lock mid-checkout.
  it('keeps the stale-lock threshold clear of the longest git command in flight', async () => {
    const { STALE_GIT_LOCK_MIN_AGE_MS } = await vi.importActual('../lib/gitStaleLock.js');
    expect(STALE_GIT_LOCK_MIN_AGE_MS).toBeGreaterThanOrEqual(3 * WORKTREE_ADD_TIMEOUT_MS);
  });

  it('gives up after the max attempts on persistent lock contention', async () => {
    execGitMock.mockRejectedValue(new Error('cannot lock ref'));
    const p = addWorktreeWithRetry(['worktree', 'add', '/wt', 'main'], '/repo');
    const assertion = expect(p).rejects.toThrow(/cannot lock ref/);
    await vi.runAllTimersAsync();
    await assertion;
    // WORKTREE_ADD_MAX_ATTEMPTS === 4
    expect(execGitMock).toHaveBeenCalledTimes(4);
  });

  it('does NOT retry a non-lock (permanent) error', async () => {
    execGitMock.mockRejectedValueOnce(new Error('fatal: invalid reference: origin/nope'));
    await expect(addWorktreeWithRetry(['worktree', 'add', '/wt', 'origin/nope'], '/repo'))
      .rejects.toThrow(/invalid reference/);
    expect(execGitMock).toHaveBeenCalledTimes(1);
    // …and nothing reached for the unlink: a failure that named no lock must
    // never put the stale-lock sweep in motion.
    expect(clearStaleGitLockMock).not.toHaveBeenCalled();
  });

  it('does NOT retry an "already exists" precondition failure', async () => {
    execGitMock.mockRejectedValueOnce(new Error("fatal: a branch named 'cos/task/agent' already exists"));
    await expect(addWorktreeWithRetry(['worktree', 'add', '-b', 'cos/task/agent', '/wt', 'main'], '/repo'))
      .rejects.toThrow(/already exists/);
    expect(execGitMock).toHaveBeenCalledTimes(1);
  });

  it('preserves the FIRST attempt error so a retry-induced "already exists" cannot mask the real cause', async () => {
    // Attempt 1 creates the branch then fails on a lock error; attempt 2 then
    // fails with a self-inflicted "branch already exists". The final rejection
    // must carry the ORIGINAL lock error so orphan cleanup still runs (#2193).
    execGitMock
      .mockRejectedValueOnce(new Error('error: cannot lock ref (attempt 1 created the branch)'))
      .mockRejectedValueOnce(new Error("fatal: a branch named 'cos/task/agent' already exists"));
    const settled = addWorktreeWithRetry(['worktree', 'add', '-b', 'cos/task/agent', '/wt', 'main'], '/repo').catch(e => e);
    await vi.runAllTimersAsync();
    const err = await settled;
    expect(err.message).toMatch(/already exists/);
    expect(err.firstAttemptError.message).toMatch(/cannot lock ref/);
    expect(execGitMock).toHaveBeenCalledTimes(2);
  });

  it('sets firstAttemptError to the sole error when the first attempt is non-retryable', async () => {
    const only = new Error("fatal: a branch named 'cos/task/agent' already exists");
    execGitMock.mockRejectedValueOnce(only);
    const err = await addWorktreeWithRetry(['worktree', 'add', '-b', 'cos/task/agent', '/wt', 'main'], '/repo').catch(e => e);
    expect(err.firstAttemptError).toBe(only);
  });
});

describe('isPreexistingRefError (orphan-cleanup guard, #2193)', () => {
  it('is true ONLY for a pre-existing BRANCH (git created nothing → skip cleanup)', () => {
    expect(isPreexistingRefError("fatal: a branch named 'cos/task/agent' already exists")).toBe(true);
    expect(isPreexistingRefError("fatal: a branch named 'main' already exists.")).toBe(true);
  });

  it('is FALSE for an occupied worktree PATH — git already created the branch there, so it IS an orphan to clean up', () => {
    expect(isPreexistingRefError("fatal: '/repo/data/cos/worktrees/agent-x' already exists")).toBe(false);
  });

  it('is false for lock contention and other failures (add may have left an orphan)', () => {
    expect(isPreexistingRefError('error: cannot lock ref')).toBe(false);
    expect(isPreexistingRefError('fatal: invalid reference')).toBe(false);
    expect(isPreexistingRefError('')).toBe(false);
    expect(isPreexistingRefError(undefined)).toBe(false);
  });
});

describe('isBranchCheckedOutElsewhereError (branch-busy pause gate)', () => {
  it('matches git\'s wording for a branch held by another worktree, old and new', () => {
    // Current git.
    expect(isBranchCheckedOutElsewhereError(
      "fatal: 'cos/task-x/agent-y' is already used by worktree at '/repo/data/cos/worktrees/agent-y'"
    )).toBe(true);
    // Pre-2.30 wording.
    expect(isBranchCheckedOutElsewhereError(
      "fatal: 'cos/task-x/agent-y' is already checked out at '/repo/data/cos/worktrees/agent-y'"
    )).toBe(true);
  });

  it('does NOT match the other "already exists" failures — those are permanent', () => {
    // An occupied worktree DIRECTORY is not a branch another tree is holding;
    // pausing on it would wait out a cooldown that can never clear it.
    expect(isBranchCheckedOutElsewhereError("fatal: '/repo/data/cos/worktrees/agent-x' already exists")).toBe(false);
    expect(isBranchCheckedOutElsewhereError("fatal: a branch named 'cos/task/agent' already exists")).toBe(false);
    expect(isBranchCheckedOutElsewhereError('error: cannot lock ref')).toBe(false);
    expect(isBranchCheckedOutElsewhereError('fatal: invalid reference: origin/nope')).toBe(false);
    expect(isBranchCheckedOutElsewhereError('')).toBe(false);
    expect(isBranchCheckedOutElsewhereError(undefined)).toBe(false);
  });

  it('stays out of the in-process add retry — that budget is sized for lock contention', () => {
    expect(isGitLockError("fatal: 'b' is already used by worktree at '/repo/wt'")).toBe(false);
  });
});

describe('findAdoptableWorktreeForBranch (take over the tree that holds the branch)', () => {
  const REPO = '/repo';
  const BRANCH = 'cos/task-x/agent-y';

  // `git worktree list --porcelain`: the primary checkout first, then whatever
  // entries a test names.
  function scriptWorktrees(entries) {
    execGitMock.mockReset();
    const stdout = [
      `worktree ${REPO}`, 'HEAD abc123', 'branch refs/heads/main', '',
      ...entries.flatMap(e => [
        `worktree ${e.path}`, 'HEAD def456',
        e.branch ? `branch ${e.branch}` : 'detached',
        ...(e.locked ? ['locked'] : []), ''
      ])
    ].join('\n');
    execGitMock.mockResolvedValue({ stdout, stderr: '' });
  }

  const cosTree = (agentId) => join(PATHS.worktrees, agentId);

  it('finds the CoS worktree holding the branch', async () => {
    scriptWorktrees([{ path: cosTree('agent-y'), branch: `refs/heads/${BRANCH}` }]);

    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH))
      .toEqual({ path: cosTree('agent-y'), agentId: 'agent-y' });
  });

  it('returns null when nothing holds the branch', async () => {
    scriptWorktrees([{ path: cosTree('agent-z'), branch: 'refs/heads/cos/other/agent-z' }]);

    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH)).toBeNull();
  });

  // Adoption MOVES the directory, so a holder PortOS doesn't own is never a
  // candidate — taking the user's own checkout is the branch-jacking this
  // codebase guards against everywhere else.
  it('refuses the primary checkout, and any tree outside the managed root', async () => {
    scriptWorktrees([{ path: '/repo/../elsewhere/tree', branch: `refs/heads/${BRANCH}` }]);
    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH)).toBeNull();

    // The repo root itself, checked out on the branch.
    execGitMock.mockResolvedValue({
      stdout: `worktree ${REPO}\nHEAD abc\nbranch refs/heads/${BRANCH}\n`, stderr: ''
    });
    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH)).toBeNull();
  });

  it('refuses a human /claim worktree — the claim flow owns its cleanup', async () => {
    scriptWorktrees([{ path: cosTree('claim-issue-42'), branch: `refs/heads/${BRANCH}` }]);

    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH)).toBeNull();
  });

  // A review-loop resolve-and-merge follow-up is the one caller that names this
  // exact branch as the thing it exists to finish and land, so it opts in via
  // `allowLiveClaim` instead of retrying `git worktree add` against a branch a
  // `/do:next` claim already holds (#6243).
  it('adopts a human /claim worktree when the caller opts into allowLiveClaim', async () => {
    scriptWorktrees([{ path: cosTree('claim-issue-42'), branch: `refs/heads/${BRANCH}` }]);

    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH, { allowLiveClaim: true, agents: [] }))
      .toEqual({ path: cosTree('claim-issue-42'), agentId: 'claim-issue-42' });
  });

  it('keeps a swarm claim through the child-idle merge handoff, then allows inactive-owner recovery', async () => {
    const path = cosTree('claim-issue-42');
    scriptWorktrees([{ path, branch: `refs/heads/${BRANCH}` }]);
    const parent = { id: 'agent-parent', status: 'running', sourceWorkspace: REPO, claimPicksOwnBranch: true };
    const child = { id: 'agent-child', status: 'completed', sourceWorkspace: REPO, claimBranch: BRANCH };
    const opts = { allowLiveClaim: true, activeAgentIds: new Set([parent.id]), agents: [parent, child] };
    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH, opts)).toBeNull();
    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH, { ...opts, agents: null })).toBeNull();
    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH, {
      ...opts, agents: [{ ...parent, status: 'completed' }, child],
    })).toEqual({ path, agentId: 'claim-issue-42' });
    // A stale pointer must not silently select a different claim holder.
    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH, {
      ...opts, agents: [], preferredPath: cosTree('claim-issue-99'),
    })).toBeNull();
  });

  it('refuses a non-agent directory in the managed root', async () => {
    scriptWorktrees([{ path: cosTree('next-issue-42'), branch: `refs/heads/${BRANCH}` }]);

    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH)).toBeNull();
  });

  it('refuses a tree whose agent is still running — it is mid-edit in there', async () => {
    scriptWorktrees([{ path: cosTree('agent-y'), branch: `refs/heads/${BRANCH}` }]);

    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH, {
      activeAgentIds: new Set(['agent-y'])
    })).toBeNull();
  });

  it('refuses a locked worktree whatever else is true of it', async () => {
    scriptWorktrees([{ path: cosTree('agent-y'), branch: `refs/heads/${BRANCH}`, locked: true }]);

    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH)).toBeNull();
  });

  it('returns null rather than throwing when the listing fails', async () => {
    execGitMock.mockReset();
    execGitMock.mockRejectedValue(new Error('not a git repository'));

    expect(await findAdoptableWorktreeForBranch(REPO, BRANCH)).toBeNull();
    expect(await findAdoptableWorktreeForBranch(REPO, '')).toBeNull();
    expect(await findAdoptableWorktreeForBranch('', BRANCH)).toBeNull();
  });
});

describe('removeWorktree identity, dirt and branch preservation', () => {
  // Routes each git invocation this path makes to a scripted answer, keyed on the
  // subcommand, so a test only has to state what it cares about instead of
  // ordering every call. The preserve/delete decision itself comes from the
  // mocked `hasBranchMergeEvidence` (see the ./git.js mock at the top of this file).
  function scriptGit({ porcelain = '', remoteTargetResolves = true, detectedToplevel } = {}) {
    execGitMock.mockReset();
    let registered = true;
    let statusText = porcelain;
    const deletedRefs = new Set();
    // Discarding a lockfile (checkout of a tracked path, or rm of an untracked
    // one) is what makes the next status clean. The removal recheck reads that
    // status and refuses a still-dirty tree.
    const porcelainPath = (line) => line.slice(3);
    const dropPaths = (paths) => {
      const drop = new Set(paths);
      statusText = statusText.split('\n').filter(line => line && !drop.has(porcelainPath(line))).join('\n');
    };
    rm.mockImplementation(async (target) => {
      const normalized = String(target).replaceAll('\\', '/');
      const hit = statusText.split('\n').map(porcelainPath).filter(path => path && (normalized === path || normalized.endsWith(`/${path}`)));
      if (hit.length) dropPaths(hit);
    });
    execGitMock.mockImplementation((args, cwd) => {
      const [sub] = args;
      if (sub === 'worktree' && args[1] === 'list') return Promise.resolve({ stdout: registered ? `worktree ${join(PATHS.worktrees, 'agent-x')}\nHEAD ${'a'.repeat(40)}\nbranch refs/heads/cos/task-1/agent-x\n` : '', exitCode: 0 });
      if (sub === 'worktree' && args[1] === 'remove') registered = false;
      if (sub === 'rev-parse' && args[1] === '--path-format=absolute') return Promise.resolve({ stdout: '/repo/.git', exitCode: 0 });
      if (sub === 'rev-parse' && args[1] === '--verify' && String(args[2]).startsWith('refs/heads/')) return Promise.resolve({ stdout: 'a'.repeat(40), exitCode: 0 });
      // Whether this clone has an `origin/<default>` to prefer over the local branch.
      if (sub === 'rev-parse' && args[1] === '--verify' && String(args[2]).startsWith('origin/')) {
        return Promise.resolve({ stdout: remoteTargetResolves ? 'deadbeef' : '', stderr: '', exitCode: remoteTargetResolves ? 0 : 1 });
      }
      if (sub === 'rev-parse' && args[1] === '--abbrev-ref' && args[2] === 'HEAD') {
        return Promise.resolve({ stdout: 'main', stderr: '', exitCode: 0 });
      }
      if (sub === 'rev-parse' && args[1] === '--show-toplevel') {
        return Promise.resolve({ stdout: detectedToplevel ?? cwd, stderr: '', exitCode: 0 });
      }
      if (sub === 'checkout' && args[1] === '--') {
        dropPaths(args.slice(2));
        return Promise.resolve({ stdout: '', stderr: '', exitCode: 0 });
      }
      if (sub === 'status') return Promise.resolve({ stdout: statusText, stderr: '', exitCode: 0 });
      if (sub === 'rev-list') return Promise.resolve({ stdout: '0\n', stderr: '', exitCode: 0 });
      if (sub === 'push') {
        const spec = args.find(arg => typeof arg === 'string' && arg.startsWith(':refs/'));
        if (spec) deletedRefs.add(spec.slice(1));
        return Promise.resolve({ stdout: '', stderr: '', exitCode: 0 });
      }
      if (sub === 'show-ref') {
        const ref = args.at(-1);
        return Promise.resolve({ stdout: '', stderr: '', exitCode: deletedRefs.has(ref) ? 1 : 0 });
      }
      return Promise.resolve({ stdout: '', stderr: '', exitCode: 0 });
    });
  }

  const calledWith = (subcommandArgs) =>
    execGitMock.mock.calls.some(([args]) => JSON.stringify(args) === JSON.stringify(subcommandArgs));

  beforeEach(() => {
    releaseCheckoutMock.mockReset().mockImplementation(async (_context, prepare) => prepare());
    preserveCheckoutMock.mockReset().mockResolvedValue({ archiveDir: '/archive', checkoutIdentity: 'original', verify: async () => null });
    retirementReceiptMock.mockClear();
    completionHoldMock.mockReset().mockResolvedValue(null);
    completionOwnersMock.mockReset().mockResolvedValue([]);
    getDefaultBranchMock.mockResolvedValue('main');
    // mockReset (not just mockResolvedValue): the opt-in test asserts the merged
    // check was NOT consulted, so recorded calls must not leak in from a prior test.
    hasBranchMergeEvidenceMock.mockReset();
    hasBranchMergeEvidenceMock.mockResolvedValue(true);
    existsSync.mockReset().mockReturnValue(true);
    realpathSync.mockReset().mockImplementation(p => p);
    realpathSync.native = realpathSync;
    // Removal is verified against the real directory afterwards; scripted removals
    // succeed, so the worktree directory reads as gone (and `worktree list` as empty).
    lstat.mockReset().mockRejectedValue(Object.assign(new Error('gone'), { code: 'ENOENT' }));
    rm.mockClear();
    scriptGit();
  });

  it.each([
    ['a rejected ref read', () => Promise.reject(new Error('git command timed out'))],
    ['a nonzero ref read', () => Promise.resolve({ stdout: '1', stderr: 'bad ref', exitCode: 128 })],
    ['an empty ref count', () => Promise.resolve({ stdout: '', stderr: '', exitCode: 0 })],
    ['a malformed ref count', () => Promise.resolve({ stdout: 'unknown', stderr: '', exitCode: 0 })],
  ])('preserves the worktree and branch when merge preflight returns %s', async (_description, readCount) => {
    const scripted = execGitMock.getMockImplementation();
    execGitMock.mockImplementation((args, ...rest) =>
      args[0] === 'rev-list' ? readCount() : scripted(args, ...rest));

    // This is the scheduled caller's option shape: merge enabled, with no
    // optional branch-preservation flag.
    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: true });

    expect(result).toMatchObject({ merged: false, removed: false, uncommittedSaved: false });
    expect(result.warnings.join(' ')).toMatch(/preserved.*retry/i);
    expect(rm).not.toHaveBeenCalled();
    expect(calledWith(['worktree', 'remove', join(PATHS.worktrees, 'agent-x'), '--force'])).toBe(false);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
    expect(calledWith(['merge', 'cos/task-1/agent-x', '--no-edit'])).toBe(false);
  });

  // An untracked lockfile has no index entry, so `git checkout --` cannot restore it
  // and used to reject the whole removal (#11867). It must be deleted instead.
  it('removes a worktree whose only dirt is an untracked lockfile', async () => {
    scriptGit({ porcelain: '?? package-lock.json' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

    expect(result.removed).toBe(true);
    expect(rm).toHaveBeenCalledWith(join(PATHS.worktrees, 'agent-x', 'package-lock.json'), { force: true });
    expect(calledWith(['checkout', '--', 'package-lock.json'])).toBe(false);
  });

  it('dependency-updates lockfile-only dirt is preserved, not discarded', async () => {
    scriptGit({ porcelain: ' M package-lock.json' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false, preserveLockfiles: true });

    expect(result).toMatchObject({ removed: false, merged: false });
    expect(result.warnings.join(' ')).toMatch(/uncommitted changes detected.*package-lock\.json/);
    expect(calledWith(['checkout', '--', 'package-lock.json'])).toBe(false);
    expect(calledWith(['worktree', 'remove', join(PATHS.worktrees, 'agent-x'), '--force'])).toBe(false);
  });

  it('restores a modified tracked lockfile with checkout before removal', async () => {
    scriptGit({ porcelain: ' M pnpm-lock.yaml' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

    expect(result.removed).toBe(true);
    expect(calledWith(['checkout', '--', 'pnpm-lock.yaml'])).toBe(true);
    expect(rm).not.toHaveBeenCalledWith(expect.stringContaining('pnpm-lock.yaml'), expect.anything());
  });

  it('preserves the worktree instead of rejecting when the lockfile discard fails', async () => {
    scriptGit({ porcelain: ' M yarn.lock' });
    const scripted = execGitMock.getMockImplementation();
    execGitMock.mockImplementation((args, ...rest) => (args[0] === 'checkout'
      ? Promise.reject(new Error('index is locked'))
      : scripted(args, ...rest)));

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

    expect(result).toMatchObject({ removed: false, merged: false, uncommittedSaved: false });
    expect(result.warnings.join(' ')).toMatch(/lockfile discard failed/);
    expect(calledWith(['worktree', 'remove', join(PATHS.worktrees, 'agent-x'), '--force'])).toBe(false);
  });

  it('still removes an empty branch after a verified zero commit count', async () => {
    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: true });

    expect(result.removed).toBe(true);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(true);
  });

  it('attempts and records a merge after a verified positive commit count', async () => {
    const scripted = execGitMock.getMockImplementation();
    execGitMock.mockImplementation((args, ...rest) =>
      args[0] === 'rev-list'
        ? Promise.resolve({ stdout: '2\n', stderr: '', exitCode: 0 })
        : scripted(args, ...rest));

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: true });

    expect(result).toMatchObject({ merged: true, removed: true });
    expect(calledWith(['merge', 'cos/task-1/agent-x', '--no-edit'])).toBe(true);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(true);
  });

  it('preserves a branch after a verified positive count and failed merge', async () => {
    const scripted = execGitMock.getMockImplementation();
    execGitMock.mockImplementation((args, ...rest) => {
      if (args[0] === 'rev-list') return Promise.resolve({ stdout: '1\n', stderr: '', exitCode: 0 });
      if (args[0] === 'merge' && args[1] !== '--abort') return Promise.reject(new Error('merge conflict'));
      return scripted(args, ...rest);
    });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: true });

    expect(result.removed).toBe(true);
    expect(result.merged).toBe(false);
    expect(calledWith(['merge', 'cos/task-1/agent-x', '--no-edit'])).toBe(true);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
  });

  afterEach(() => {
    realpathSync.mockReset().mockImplementation(p => p);
    realpathSync.native = realpathSync;
    lstat.mockReset().mockResolvedValue({});
  });

  describe('when the checkout survives removal (#9909)', () => {
    const present = () => lstat.mockReset().mockResolvedValue({});
    const failRemoval = () => {
      const scripted = execGitMock.getMockImplementation();
      execGitMock.mockImplementation((args, ...rest) => (args[0] === 'worktree' && args[1] === 'remove'
        ? Promise.reject(new Error('Permission denied'))
        : scripted(args, ...rest)));
      rm.mockRejectedValue(new Error('EPERM: operation not permitted'));
    };
    afterEach(() => { rm.mockReset().mockResolvedValue(undefined); });

    it('reports removed:false with a retryable warning, keeps the branch, and flags cleanupIncomplete', async () => {
      const log = vi.spyOn(console, 'log').mockImplementation(() => {});
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      present();
      failRemoval();

      const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

      expect(result).toMatchObject({ merged: false, removed: false, cleanupIncomplete: true });
      expect(result.warnings.join(' ')).toMatch(/cleanup incomplete.*directory still present.*retryable/);
      // Git refusing the removal is a fault, so the cleanup warning reaches stderr; the "branch kept"
      // consequence is already explained by it and follows on stdout.
      expect(warn).toHaveBeenCalledWith(expect.stringContaining('Worktree cleanup incomplete'));
      expect(log).toHaveBeenCalledWith(expect.stringContaining('Worktree for agent-x was not removed — branch cos/task-1/agent-x kept'));
      expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
    });

    it('keeps `merged` accurate for the publication outcome while still refusing to claim removal', async () => {
      present();
      failRemoval();
      const scripted = execGitMock.getMockImplementation();
      execGitMock.mockImplementation((args, ...rest) => (args[0] === 'rev-list' ? Promise.resolve({ stdout: '2', stderr: '', exitCode: 0 })
        : (args[0] === 'rev-parse' && args[1] === '--abbrev-ref' ? Promise.resolve({ stdout: 'main' }) : scripted(args, ...rest))));
      getDefaultBranchMock.mockResolvedValue('main');

      const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: true });

      expect(result.removed).toBe(false);
      expect(result.merged).toBe(true);
      expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
    });

    it('verifies a missing directory whose registration is stale instead of assuming it is gone', async () => {
      existsSync.mockReturnValue(false);
      const path = join(PATHS.worktrees, 'agent-x');
      let pruned = false;
      const scripted = execGitMock.getMockImplementation();
      execGitMock.mockImplementation((args, ...rest) => {
        if (args[0] === 'worktree' && args[1] === 'prune') pruned = true;
        if (args[0] === 'worktree' && args[1] === 'remove') return Promise.reject(new Error('is not a working tree'));
        if (args[0] === 'worktree' && args[1] === 'list') {
          return Promise.resolve({ stdout: pruned ? '' : `worktree ${path}\nHEAD ${'a'.repeat(40)}\nbranch refs/heads/cos/task-1/agent-x\nprunable\n` });
        }
        return scripted(args, ...rest);
      });

      const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

      expect(result.removed).toBe(true);
      expect(pruned).toBe(true);
      expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(true);
    });

    it('does not report an already-gone directory as removed while its registration survives', async () => {
      existsSync.mockReturnValue(false);
      const path = join(PATHS.worktrees, 'agent-x');
      execGitMock.mockImplementation((args) => {
        if (args[0] === 'worktree' && args[1] === 'list') return Promise.resolve({ stdout: `worktree ${path}\nHEAD abc\nbranch refs/heads/b\nlocked\n` });
        if (args[0] === 'worktree' && args[1] === 'remove') return Promise.reject(new Error('locked'));
        return Promise.resolve({ stdout: '', stderr: '', exitCode: 0 });
      });

      const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

      expect(result).toMatchObject({ removed: false, cleanupIncomplete: true });
      expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
    });

    it('persistent removal reports the survivor and keeps the branch', async () => {
      present();
      failRemoval();

      const result = await removePersistentWorktree('fa-1', '/repo', 'feature/x');

      expect(result).toMatchObject({ removed: false, cleanupIncomplete: true });
      expect(result.warnings.join(' ')).toMatch(/cleanup incomplete/);
      expect(calledWith(['branch', '-D', 'feature/x'])).toBe(false);
    });

    it('persistent removal still reports a verified removal', async () => {
      const result = await removePersistentWorktree('fa-1', '/repo', 'feature/x');
      expect(result).toEqual({ removed: true, warnings: [] });
      expect(calledWith(['branch', '-D', 'feature/x'])).toBe(true);
    });
  });

  it('preserves a broken tree resolving to the parent without trusting its dirty status', async () => {
    scriptGit({ detectedToplevel: '/repo', porcelain: ' M src/parent-work.js' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');

    expect(result).toMatchObject({ merged: false, removed: false, cleanupIncomplete: true });
    expect(result.warnings.join(' ')).toContain('broken checkout identity');
    expect(rm).not.toHaveBeenCalled();
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'status')).toBe(false);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'worktree')).toBe(false);
  });

  it('preserves dirt when git reports a symlink-equivalent worktree identity', async () => {
    const worktreePath = join(PATHS.worktrees, 'agent-x');
    const alias = join('/alias', 'agent-x');
    realpathSync.mockImplementation(p => p === alias ? worktreePath : p);
    scriptGit({ detectedToplevel: alias, porcelain: ' M src/index.js' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');

    expect(result.removed).toBe(false);
    expect(result.warnings.join(' ')).toContain('src/index.js');
    expect(rm).not.toHaveBeenCalled();
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
  });

  it('preserves authored work when only native realpath unifies the Git and Node directory spellings', async () => {
    const worktreePath = join(PATHS.worktrees, 'agent-x');
    const alias = join('/git-alias', 'agent-x');
    // Windows short names can survive JS realpath unchanged while Git reports
    // their long spelling. Native realpath resolves the filesystem identity.
    realpathSync.native = vi.fn(p => p === alias ? worktreePath : p);
    scriptGit({ detectedToplevel: alias, porcelain: ' M src/recoverable.js' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');

    expect(result.removed).toBe(false);
    expect(result.warnings.join(' ')).toContain('src/recoverable.js');
    expect(rm).not.toHaveBeenCalled();
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
  });

  it('prunes a missing checkout registered through an alias of its surviving parent', async () => {
    const worktreePath = join(PATHS.worktrees, 'agent-x');
    const alias = join('/git-alias', 'agent-x');
    existsSync.mockReturnValue(false);
    realpathSync.native = vi.fn(p => {
      if ([worktreePath, alias].includes(p)) throw Object.assign(new Error('gone'), { code: 'ENOENT' });
      return p === dirname(alias) ? PATHS.worktrees : p;
    });
    let pruned = false;
    const scripted = execGitMock.getMockImplementation();
    execGitMock.mockImplementation((args, ...rest) => {
      if (args[0] === 'worktree' && args[1] === 'list') {
        return Promise.resolve({ stdout: pruned ? '' : `worktree ${alias}\nHEAD ${'a'.repeat(40)}\nbranch refs/heads/cos/task-1/agent-x\nprunable\n`, exitCode: 0 });
      }
      if (args[0] === 'worktree' && args[1] === 'remove') return Promise.reject(new Error('missing checkout'));
      if (args[0] === 'worktree' && args[1] === 'prune') pruned = true;
      return scripted(args, ...rest);
    });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', {
      merge: false, preserveBranchWithCommits: true,
    });

    expect(result.removed).toBe(true);
    expect(pruned).toBe(true);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(true);
  });

  it('preserves work when identity lookup and status both fail', async () => {
    const scripted = execGitMock.getMockImplementation();
    execGitMock.mockImplementation((args, ...rest) =>
      (args[0] === 'status' || (args[0] === 'rev-parse' && args[1] === '--show-toplevel'))
        ? Promise.reject(new Error('not a git repository'))
        : scripted(args, ...rest));

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');

    expect(result.removed).toBe(false);
    expect(result.warnings.join(' ')).toContain('git status failed');
    expect(rm).not.toHaveBeenCalled();
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
  });

  it('discards only lockfile churn before removing the worktree', async () => {
    scriptGit({ porcelain: ' M client/package-lock.json\n M yarn.lock\n M pnpm-lock.yaml' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');

    expect(result.removed).toBe(true);
    expect(execGitMock).toHaveBeenCalledWith(
      ['checkout', '--', 'client/package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'],
      join(PATHS.worktrees, 'agent-x')
    );
    expect(execGitMock).toHaveBeenCalledWith(
      ['worktree', 'remove', join(PATHS.worktrees, 'agent-x'), '--force'], '/repo', { timeout: WORKTREE_ADD_TIMEOUT_MS }
    );
  });

  it.each(['?? src/new.js', 'A  src/staged.js', ' M package-lock.json\n M src/index.js'])(
    'preserves authored changes (%s) without discarding any files', async porcelain => {
      scriptGit({ porcelain });

      const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');

      expect(result.removed).toBe(false);
      expect(rm).not.toHaveBeenCalled();
      expect(execGitMock.mock.calls.some(([args]) => ['checkout', 'worktree', 'branch'].includes(args[0]))).toBe(false);
    }
  );

  it.each([
    ['main', 'main', 'protected-branch'],
    ['release', 'main', 'protected-branch'],
    ['trunk', 'trunk', 'protected-branch'],
    ['cos/task-1/agent-x', null, 'default-branch-unavailable'],
  ])('retains %s before trusting erroneous cleanup metadata (default %s)', async (branch, base, reason) => {
    getDefaultBranchMock.mockResolvedValue(base);
    const result = await removeWorktree('agent-x', '/repo', branch, { merge: true });
    expect(result.removed).toBe(false);
    expect(result.warnings.join(' ')).toContain(reason);
    expect(preserveCheckoutMock).not.toHaveBeenCalled();
    expect(execGitMock.mock.calls.some(([args]) => ['merge', 'push', 'checkout'].includes(args[0])
      || (args[0] === 'worktree' && ['remove', 'prune'].includes(args[1])))).toBe(false);
  });

  it.each(['active', 'unreadable', 'arrives-during-archive'])('preserves a finalizing checkout when ownership is %s', async state => {
    const otherOwner = { id: 'agent-other', status: 'running', workspacePath: join(PATHS.worktrees, 'agent-x'), metadata: { sourceWorkspace: '/repo', worktreeBranch: 'cos/task-1/agent-x' } };
    if (state === 'active') completionOwnersMock.mockResolvedValue([otherOwner]);
    if (state === 'unreadable') completionOwnersMock.mockResolvedValue(null);
    if (state === 'arrives-during-archive') releaseCheckoutMock.mockImplementation(async (_context, prepare) => {
      completionOwnersMock.mockResolvedValue([otherOwner]);
      return prepare();
    });
    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');
    expect(result.removed).toBe(false);
    expect(result.warnings.join(' ')).toMatch(/claim-owner/);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push'
      || (args[0] === 'worktree' && args[1] === 'remove'))).toBe(false);
  });

  it('leaves a checkout another retirement is archiving to that retirement (#12682)', async () => {
    const { reserveCheckoutRetirementFence } = await import('./cosClaimOwnershipState.js');
    const release = reserveCheckoutRetirementFence({ repoPath: '/repo', path: join(PATHS.worktrees, 'agent-x'), branch: 'cos/task-1/agent-x' });
    try {
      const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');
      expect(result.removed).toBe(false);
      expect(result.warnings.join(' ')).toContain('checkout-retirement-reserved');
      expect(releaseCheckoutMock).not.toHaveBeenCalled();
    } finally { release(); }
  });

  it.each(['present', 'missing', 'lockfile'])('retains %s checkout evidence when archival fails', async state => {
    if (state === 'missing') existsSync.mockReturnValue(false);
    if (state === 'lockfile') scriptGit({ porcelain: ' M package-lock.json' });
    releaseCheckoutMock.mockRejectedValue(new Error('archive disk full'));
    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');
    expect(result.removed).toBe(false);
    expect(result.warnings.join(' ')).toContain('archive disk full');
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'checkout' || args[0] === 'push'
      || (args[0] === 'worktree' && ['remove', 'prune'].includes(args[1])))).toBe(false);
    expect(rm).not.toHaveBeenCalled();
  });

  // #12748: every agent completion archived its checkout inside the shared
  // claim-ownership lock, starving each bind/release/reserve queued behind it.
  it.each(['present', 'missing', 'lockfile'])('removes a %s checkout with the ownership queue free and only it fenced', async state => {
    if (state === 'missing') existsSync.mockReturnValue(false);
    if (state === 'lockfile') scriptGit({ porcelain: ' M package-lock.json' });
    const { withClaimOwnershipLock, checkoutRetirementFenceReason } = await import('./cosClaimOwnershipState.js');
    const fenced = { repoPath: '/repo', path: join(PATHS.worktrees, 'agent-x') };
    let started;
    let finish;
    const archiving = new Promise(resolve => { started = resolve; });
    releaseCheckoutMock.mockImplementationOnce((_context, prepare) => new Promise(resolve => {
      finish = () => resolve(prepare());
      started();
    }));
    const pending = removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');
    await archiving;
    expect(await withClaimOwnershipLock(() => 'settled')).toBe('settled');
    expect(checkoutRetirementFenceReason(fenced)).toBe('checkout-retirement-reserved');
    expect(checkoutRetirementFenceReason({ repoPath: '/repo', branch: 'cos/task-1/agent-x' })).toBe('checkout-retirement-reserved');
    expect(checkoutRetirementFenceReason({ repoPath: '/repo', branch: 'cos/task-2/agent-y', path: join(PATHS.worktrees, 'agent-y') })).toBe(null);
    finish();
    expect((await pending).removed).toBe(true);
    expect(checkoutRetirementFenceReason(fenced)).toBe(null);
  });

  // #12764: resolveMergeTarget's `git fetch origin --prune` still ran inside the
  // second critical section (completionHold via verifyRemoval, and the branch
  // cleanup), so a hung fetch could starve every claim bind queued behind the lock.
  it.each(['present', 'missing'])('fetches the merge target with the ownership queue free for a %s checkout', async state => {
    if (state === 'missing') existsSync.mockReturnValue(false);
    const { withClaimOwnershipLock } = await import('./cosClaimOwnershipState.js');
    const scripted = execGitMock.getMockImplementation();
    const fetches = [];
    execGitMock.mockImplementation(async (args, ...rest) => {
      if (args[0] === 'fetch') {
        const probe = withClaimOwnershipLock(() => 'free');
        fetches.push(await Promise.race([probe, new Promise(resolve => setTimeout(() => resolve('held'), 25))]));
      }
      return scripted(args, ...rest);
    });
    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');
    expect(result.removed).toBe(true);
    expect(fetches.length).toBeGreaterThan(0);
    expect(fetches.every(outcome => outcome === 'free')).toBe(true);
    // One refresh serves the pre-removal check, the post-removal verify and the branch cleanup.
    expect(fetches).toHaveLength(1);
  });

  it('keeps a lockfile-only checkout that changed while its pre-cleanup snapshot was archived', async () => {
    scriptGit({ porcelain: ' M package-lock.json' });
    const scripted = execGitMock.getMockImplementation();
    let archived = false;
    execGitMock.mockImplementation((args, ...rest) => (archived && args[0] === 'status'
      ? Promise.resolve({ stdout: ' M package-lock.json\n?? notes.md', stderr: '', exitCode: 0 })
      : scripted(args, ...rest)));
    releaseCheckoutMock.mockImplementationOnce(async (_context, prepare) => {
      archived = true;
      return prepare();
    });
    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');
    expect(result.removed).toBe(false);
    expect(result.warnings.join(' ')).toContain('changed while its pre-cleanup snapshot was archived');
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'checkout' || args[0] === 'push'
      || (args[0] === 'worktree' && args[1] === 'remove'))).toBe(false);
  });

  it('retains checkout and ref when the checkout becomes dirty before removal', async () => {
    const scripted = execGitMock.getMockImplementation();
    let statusReads = 0;
    execGitMock.mockImplementation((args, ...rest) => {
      if (args[0] === 'status' && ++statusReads > 1) return Promise.resolve({ stdout: ' M src/a.js\n', stderr: '', exitCode: 0 });
      return scripted(args, ...rest);
    });
    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');
    expect(result.removed).toBe(false);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push'
      || (args[0] === 'worktree' && args[1] === 'remove'))).toBe(false);
  });

  it('rechecks manual completion policy before deleting the remaining branch', async () => {
    const scripted = execGitMock.getMockImplementation();
    execGitMock.mockImplementation((args, ...rest) => {
      if (args[0] === 'worktree' && args[1] === 'remove') completionHoldMock.mockResolvedValue('manual-pr-completion');
      return scripted(args, ...rest);
    });
    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x');
    expect(result.removed).toBe(true);
    expect(result.warnings.join(' ')).toContain('manual-pr-completion');
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push')).toBe(false);
  });

  it('KEEPS the branch when it is not yet merged into the default branch', async () => {
    hasBranchMergeEvidenceMock.mockResolvedValue(false);
    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', {
      merge: false, preserveBranchWithCommits: true,
    });

    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
    expect(result.warnings.join(' ')).toMatch(/preserved/i);
  });

  describe.each(['missing', 'broken'])('when the checkout is %s', checkout => {
    beforeEach(() => {
      if (checkout === 'missing') existsSync.mockReturnValue(false);
      else scriptGit({ detectedToplevel: '/repo' });
    });

    it.each([
      ['unmerged', false],
      ['unknown', null],
      ['landed', true],
    ])('honors the retry branch policy when merge evidence is %s', async (_label, evidence) => {
      if (evidence === null) hasBranchMergeEvidenceMock.mockRejectedValue(new Error('ref probe failed'));
      else hasBranchMergeEvidenceMock.mockResolvedValue(evidence);

      const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', {
        merge: false, preserveBranchWithCommits: true,
      });

      expect(result.removed).toBe(checkout === 'missing' && evidence === true);
      expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(checkout === 'missing' && evidence === true);
      if (evidence !== true) expect(result.warnings.join(' ')).toMatch(/preserved/);
    });

    it('preserves unlanded commits when the requested merge cannot use a checkout', async () => {
      hasBranchMergeEvidenceMock.mockResolvedValue(false);
      const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: true });

      expect(result).toMatchObject({ merged: false, removed: false });
      expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
      expect(result.warnings.join(' ')).toMatch(/preserved/);
    });

    it('requires merge proof even when the checkout directory is absent', async () => {
      await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

      expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(checkout === 'missing');
      if (checkout === 'missing') expect(hasBranchMergeEvidenceMock).toHaveBeenCalled();
    });

    it('preserves the branch when its existence probe fails', async () => {
      hasBranchMergeEvidenceMock.mockResolvedValue(true);
      const scripted = execGitMock.getMockImplementation();
      execGitMock.mockImplementation((args, ...rest) => args[0] === 'show-ref'
        ? Promise.resolve({ stdout: '', stderr: 'cannot read refs', exitCode: 128 })
        : scripted(args, ...rest));

      const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', {
        merge: false, preserveBranchWithCommits: true,
      });

      expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
      expect(result.warnings.join(' ')).toMatch(/preserved/);
    });
  });

  // Patch-equivalence matters here: PortOS merges with `--rebase`, so a landed
  // branch has new SHAs. `hasBranchMergeEvidence` is what sees through that — a bare
  // `rev-list --count` would report it ahead and preserve a merged branch forever.
  it('DELETES the branch once it is merged (including rebase/squash-merged)', async () => {
    hasBranchMergeEvidenceMock.mockResolvedValue(true);

    await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', {
      merge: false, preserveBranchWithCommits: true,
    });

    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(true);
  });

  it('calls an empty branch unused instead of already merged', async () => {
    hasBranchMergeEvidenceMock.mockResolvedValue(true);
    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
    scriptGit();

    await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', {
      merge: false, preserveBranchWithCommits: true,
    });

    const lines = log.mock.calls.flat().join('\n');
    expect(lines).toContain('has no commits beyond');
    expect(lines).not.toContain('already merged');
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(true);
    log.mockRestore();
  });

  it('fails CLOSED — keeps the branch when the merged check cannot be determined', async () => {
    hasBranchMergeEvidenceMock.mockRejectedValue(new Error('unknown revision'));

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', {
      merge: false, preserveBranchWithCommits: true,
    });

    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' && args.includes(':refs/heads/cos/task-1/agent-x'))).toBe(false);
    expect(result.warnings.join(' ')).toMatch(/preserved/i);
  });

  // #7653: a PR merged on the forge moves ORIGIN's default branch — this clone's
  // `main` does not move until something fetches. Asking the local ref preserved
  // an already-landed branch and re-queued its task against shipped work.
  it('refreshes and asks origin/<default>, not the stale local branch', async () => {
    scriptGit({ remoteTargetResolves: true });

    await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', {
      merge: false, preserveBranchWithCommits: true,
    });

    expect(calledWith(['fetch', 'origin', '--prune'])).toBe(true);
    expect(hasBranchMergeEvidenceMock).toHaveBeenCalledWith('/repo', 'a'.repeat(40), 'origin/main');
  });

  it('falls back to the local branch when origin has no copy of the default', async () => {
    scriptGit({ remoteTargetResolves: false });

    await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', {
      merge: false, preserveBranchWithCommits: true,
    });

    expect(hasBranchMergeEvidenceMock).toHaveBeenCalledWith('/repo', 'cos/task-1/agent-x', 'main');
  });

  it('retains an unmerged checkout and branch even without the legacy preservation flag', async () => {
    hasBranchMergeEvidenceMock.mockResolvedValue(false);
    await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'push' || (args[0] === 'worktree' && args[1] === 'remove'))).toBe(false);
    expect(hasBranchMergeEvidenceMock).toHaveBeenCalled();
  });

  // The bare "uncommitted changes detected" message left the user unable to tell
  // real abandoned work from a transient read of a worktree already being removed
  // — and the worktree is gone by the time anyone looks. Name the paths.
  it('NAMES the dirty paths in the preserved-worktree warning', async () => {
    scriptGit({ porcelain: ' M server/services/foo.js\n?? notes.md' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

    expect(result.removed).toBe(false);
    expect(result.warnings.join(' ')).toContain('server/services/foo.js');
    expect(result.warnings.join(' ')).toContain('notes.md');
  });

  it('removes a completed worktree whose only dirt is the consumed per-agent sentinel', async () => {
    scriptGit({ porcelain: '?? .agent-done-agent-x' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

    expect(result.removed).toBe(true);
    expect(result.warnings).toEqual([]);
    expect(retirementReceiptMock).toHaveBeenCalledWith('/repo', {
      path: join(PATHS.worktrees, 'agent-x'), branch: 'cos/task-1/agent-x', head: 'a'.repeat(40),
      branchDeleted: true,
    });
  });

  it('removes a completed worktree whose only dirt is the consumed sentinel', async () => {
    scriptGit({ porcelain: '?? .agent-done' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

    expect(result.removed).toBe(true);
    expect(result.warnings).toEqual([]);
  });

  it('preserves real work while excluding the completion sentinel from the warning', async () => {
    scriptGit({ porcelain: '?? .agent-done\n M src/index.js' });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

    expect(result.removed).toBe(false);
    expect(result.warnings.join(' ')).toContain('src/index.js');
    expect(result.warnings.join(' ')).not.toContain('.agent-done');
  });

  it('caps the named paths so a broad sweep cannot flood the notification', async () => {
    scriptGit({ porcelain: Array.from({ length: 9 }, (_, i) => ` M src/f${i}.js`).join('\n') });

    const result = await removeWorktree('agent-x', '/repo', 'cos/task-1/agent-x', { merge: false });

    const warning = result.warnings.join(' ');
    expect(warning).toContain('src/f0.js');
    expect(warning).toContain('(+4 more)');
    expect(warning).not.toContain('src/f8.js');
  });
});

describe('adoptWorktree — resuming an interrupted run in its own worktree', () => {
  const WORKTREES = PATHS.worktrees;
  const DEAD_TREE = join(WORKTREES, 'agent-dead');
  const NEW_TREE = join(WORKTREES, 'agent-new');

  // The dead run's tree is on disk; the retry's destination is not.
  function scriptPaths({ source = true, target = false } = {}) {
    existsSync.mockImplementation((p) => {
      if (p === DEAD_TREE) return source;
      if (p === NEW_TREE) return target;
      return true;
    });
  }

  beforeEach(() => {
    execGitMock.mockReset();
    execGitMock.mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 });
    scriptPaths();
  });

  afterEach(() => { existsSync.mockReturnValue(true); });

  // Renaming to the retry's own id keeps `<worktrees>/<agentId>` == "the agent that
  // owns this tree" — the invariant cleanupOrphanedWorktrees reaps on. Adopted in
  // place, the live retry's worktree would be reaped out from under it.
  it('moves the dead run’s tree to the retrying agent’s directory', async () => {
    const result = await adoptWorktree('agent-new', '/repo', DEAD_TREE, 'cos/task-1/agent-dead');

    // Third arg is the long add/move timeout — a move relocates a whole checkout,
    // so it needs the same headroom as the add it shares a wrapper with.
    expect(execGitMock).toHaveBeenCalledWith(
      ['worktree', 'move', DEAD_TREE, NEW_TREE],
      '/repo',
      expect.objectContaining({ timeout: expect.any(Number) })
    );
    expect(result).toMatchObject({
      worktreePath: NEW_TREE, branchName: 'cos/task-1/agent-dead',
      existingBranch: true, adopted: true
    });
  });

  it('returns null (caller starts clean) when the leftover tree is gone', async () => {
    scriptPaths({ source: false });

    await expect(adoptWorktree('agent-new', '/repo', DEAD_TREE, 'cos/task-1/agent-dead')).resolves.toBeNull();
    expect(execGitMock.mock.calls.filter(([args]) => args[0] !== 'rev-parse')).toEqual([]);
  });

  it('refuses to clobber an occupied destination', async () => {
    scriptPaths({ target: true });

    await expect(adoptWorktree('agent-new', '/repo', DEAD_TREE, 'cos/task-1/agent-dead')).resolves.toBeNull();
    expect(execGitMock.mock.calls.filter(([args]) => args[0] !== 'rev-parse')).toEqual([]);
  });

  // git refuses to move a locked worktree or one with initialized submodules —
  // Decline at the spawn path; the caller preserves any surviving branch holder.
  it('returns null rather than throwing when git refuses the move', async () => {
    execGitMock.mockImplementation(args => args[0] === 'worktree' && args[1] === 'move'
      ? Promise.reject(new Error('working trees containing submodules cannot be moved'))
      : Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }));

    await expect(adoptWorktree('agent-new', '/repo', DEAD_TREE, 'cos/task-1/agent-dead')).resolves.toBeNull();
  });

  it('deletes an untracked lockfile rather than checking it out when adopting', async () => {
    execGitMock.mockImplementation((args) => Promise.resolve({
      stdout: args[0] === 'status' ? '?? package-lock.json' : '', stderr: '', exitCode: 0,
    }));

    await adoptWorktree('agent-new', '/repo', DEAD_TREE, 'cos/task-1/agent-dead');

    expect(rm).toHaveBeenCalledWith(join(NEW_TREE, 'package-lock.json'), { force: true });
    expect(execGitMock).not.toHaveBeenCalledWith(['checkout', '--', 'package-lock.json'], expect.anything());
  });

  it('is a no-op when the tree already sits at the destination', async () => {
    scriptPaths({ source: true, target: true });

    const result = await adoptWorktree('agent-new', '/repo', NEW_TREE, 'cos/task-1/agent-dead');

    expect(execGitMock.mock.calls.filter(([args]) => args[0] !== 'rev-parse')).toEqual([[['status', '--porcelain', '--untracked-files=no'], NEW_TREE]]);
    expect(result).toMatchObject({ worktreePath: NEW_TREE, adopted: true });
  });

  // removeWorktree discards lockfile churn rather than preserving it, and the
  // resume prompt tells the retry that everything uncommitted is its own work to
  // finish and commit — so an adopted tree carrying only a stale `npm install`
  // lockfile bump would ship it in the PR.
  it('discards lockfile-only churn in the adopted tree', async () => {
    execGitMock.mockImplementation((args) => Promise.resolve(
      args[0] === 'status'
        ? { stdout: ' M package-lock.json\n', stderr: '', exitCode: 0 }
        : { stdout: '', stderr: '', exitCode: 0 }
    ));

    await adoptWorktree('agent-new', '/repo', DEAD_TREE, 'cos/task-1/agent-dead');

    expect(execGitMock).toHaveBeenCalledWith(['checkout', '--', 'package-lock.json'], NEW_TREE);
  });

  it('keeps every uncommitted change when the tree holds real work too', async () => {
    execGitMock.mockImplementation((args) => Promise.resolve(
      args[0] === 'status'
        ? { stdout: ' M package-lock.json\n M server/services/thing.js\n', stderr: '', exitCode: 0 }
        : { stdout: '', stderr: '', exitCode: 0 }
    ));

    await adoptWorktree('agent-new', '/repo', DEAD_TREE, 'cos/task-1/agent-dead');

    expect(execGitMock).not.toHaveBeenCalledWith(expect.arrayContaining(['checkout']), expect.anything());
  });

  it('refuses a damaged tree even when it already sits at the destination', async () => {
    scriptPaths({ source: true, target: true });
    execGitMock.mockResolvedValue({ stdout: Array.from({ length: 100 }, (_, i) => ` D file-${i}`).join('\n') });

    await expect(adoptWorktree('agent-new', '/repo', NEW_TREE, 'cos/task-1/agent-dead')).resolves.toBeNull();
    expect(execGitMock.mock.calls.filter(([args]) => args[0] !== 'rev-parse')).toEqual([[['status', '--porcelain', '--untracked-files=no'], NEW_TREE]]);
  });

  it('preserves the tree when its status cannot be inspected', async () => {
    execGitMock.mockRejectedValue(new Error('index unreadable'));

    await expect(adoptWorktree('agent-new', '/repo', DEAD_TREE, 'cos/task-1/agent-dead')).resolves.toBeNull();
    expect(execGitMock.mock.calls.filter(([args]) => args[0] !== 'rev-parse')).toEqual([[['status', '--porcelain', '--untracked-files=no'], DEAD_TREE]]);
  });

  it('returns null on incomplete input instead of guessing', async () => {
    await expect(adoptWorktree(null, '/repo', DEAD_TREE, 'b')).resolves.toBeNull();
    await expect(adoptWorktree('agent-new', '/repo', DEAD_TREE, null)).resolves.toBeNull();
    expect(execGitMock.mock.calls.filter(([args]) => args[0] !== 'rev-parse')).toEqual([]);
  });
});

describe('createWorktree upstream safety (#4172)', () => {
  // Wiring-level coverage: that the branch invariant itself HOLDS against real
  // git is proved in lib/branchUpstreamGuard.test.js (real repos, real config).
  // What can only be checked here is that createWorktree actually reaches for
  // it — the flag on the add, and the guard on the result.
  // `originHasBranch` / `forkRemoteUrl` / `forkRefResolves` script the three
  // lookups the existingBranch resolve order makes, so a test can put the tree
  // in the fork-PR state: no local branch, no origin ref, a fork that answers.
  function scriptGit({ mergeReadings = [], originHasBranch = true, forkRemoteUrl = null, forkRefResolves = true } = {}) {
    const readings = [...mergeReadings];
    execGitMock.mockReset();
    execGitMock.mockImplementation((args) => {
      if (args[0] === 'config' && args[1] === '--get' && /\.merge$/.test(args[2] || '')) {
        const answer = readings.length ? readings.shift() : '';
        // exitCode 1 mirrors `git config --get` on an unset key, which the guard
        // must read as "no upstream" rather than as an error.
        return Promise.resolve({ stdout: answer, stderr: '', exitCode: answer ? 0 : 1 });
      }
      if (args[0] === 'rev-parse' && args[1] === '--verify') {
        const ref = args[2] || '';
        const resolves = ref.startsWith('origin/') ? originHasBranch : forkRefResolves;
        return Promise.resolve({ stdout: resolves ? 'deadbeef' : '', stderr: '', exitCode: resolves ? 0 : 1 });
      }
      if (args[0] === 'remote' && args[1] === 'get-url') {
        return forkRemoteUrl
          ? Promise.resolve({ stdout: `${forkRemoteUrl}\n`, stderr: '', exitCode: 0 })
          : Promise.resolve({ stdout: '', stderr: 'No such remote', exitCode: 2 });
      }
      return Promise.resolve({ stdout: '', stderr: '', exitCode: 0 });
    });
  }

  const argsFor = (predicate) => execGitMock.mock.calls.map(([args]) => args).filter(predicate);

  beforeEach(() => {
    getDefaultBranchMock.mockResolvedValue('main');
    scriptGit();
  });

  it('creates the branch with --no-track so git cannot record refs/heads/main as its upstream', async () => {
    const result = await createWorktree('agent-1', '/repo', 'task-1');

    expect(result).toMatchObject({
      worktreePath: join(PATHS.worktrees, 'agent-1'),
      branchName: 'cos/task-1/agent-1',
      baseBranch: 'main',
      instanceId: 'instance-1',
    });
    expect(execGitMock).toHaveBeenCalledWith(
      ['worktree', 'add', '--no-track', '-b', 'cos/task-1/agent-1', join(PATHS.worktrees, 'agent-1'), 'origin/main'],
      '/repo', expect.objectContaining({ timeout: WORKTREE_ADD_TIMEOUT_MS })
    );

  });

  it.each([
    ['issue-42', 'cos/sys-1/issue-42/agent-plan'],
    ['', 'cos/sys-1/agent-plan'],
  ])('creates and returns the branch for planId %j', async (planId, branchName) => {
    const worktreePath = join(PATHS.worktrees, 'agent-plan');

    expect(await createWorktree('agent-plan', '/repo', 'sys-1', { planId }))
      .toMatchObject({ worktreePath, branchName });
    expect(execGitMock).toHaveBeenCalledWith(
      ['worktree', 'add', '--no-track', '-b', branchName, worktreePath, 'origin/main'],
      '/repo', expect.objectContaining({ timeout: WORKTREE_ADD_TIMEOUT_MS })
    );
  });

  it('keeps dependency-update worktrees detached from source dependencies', async () => {
    const missing = Object.assign(new Error('missing'), { code: 'ENOENT' });
    lstat.mockReset();
    lstat.mockRejectedValue(missing);
    symlink.mockClear();

    await createWorktree('agent-deps', '/repo', 'task-deps', { linkDependencies: false });

    expect(symlink).not.toHaveBeenCalled();
  });

  it('drops an upstream that still points at the default branch', async () => {
    // An older git, or a repo whose config re-tracks despite the flag: the first
    // read finds `main`, the guard unsets, the re-read confirms.
    scriptGit({ mergeReadings: ['refs/heads/main'] });

    await createWorktree('agent-2', '/repo', 'task-2');

    expect(argsFor(a => a[0] === 'branch' && a[1] === '--unset-upstream')).toHaveLength(1);
  });

  it('leaves a healthy branch untouched', async () => {
    await createWorktree('agent-3', '/repo', 'task-3');

    expect(argsFor(a => a[0] === 'branch' && a[1] === '--unset-upstream')).toHaveLength(0);
  });

  it('undoes the add when the upstream cannot be made safe, instead of stranding a worktree', async () => {
    // The guard throws AFTER `worktree add` succeeded, so without an undo the
    // caller sees a failed create while a registered worktree and an orphan
    // branch stay on disk — the debris cleanupOrphanBranch prevents on the add.
    scriptGit({ mergeReadings: ['refs/heads/main', 'refs/heads/main'] });

    await expect(createWorktree('agent-5', '/repo', 'task-5')).rejects.toThrow(/still resolves to/);

    expect(argsFor(a => a[0] === 'worktree' && a[1] === 'remove')).toHaveLength(1);
    expect(argsFor(a => a[0] === 'branch' && a[1] === '-D')).toHaveLength(1);
  });

  it('does NOT delete the branch when undoing an existingBranch attach', async () => {
    // That branch pre-dates this add and may hold real commits — same
    // distinction cleanupOrphanBranch draws.
    scriptGit({ mergeReadings: ['refs/heads/main', 'refs/heads/main'] });

    await expect(createWorktree('agent-6', '/repo', 'task-6', { existingBranch: 'cos/task-0/agent-0' }))
      .rejects.toThrow(/still resolves to/);

    expect(argsFor(a => a[0] === 'worktree' && a[1] === 'remove')).toHaveLength(1);
    expect(argsFor(a => a[0] === 'branch' && a[1] === '-D')).toHaveLength(0);
  });

  it('attaches a FORK PR head from a fork remote and leaves its upstream on the fork (#6064)', async () => {
    // The regression: a fork PR's head has no `origin/<branch>` at all, so
    // before this every "work on this PR's branch" path threw at workspace prep
    // for exactly the PRs external contributors open.
    scriptGit({ originHasBranch: false });

    await createWorktree('agent-fork', '/repo', 'task-fork', {
      existingBranch: 'contributor/fix-thing',
      forkHead: { remoteUrl: 'https://github.com/contributor/widget.git', ownerLogin: 'contributor' },
    });

    expect(argsFor(a => a[0] === 'remote' && a[1] === 'add'))
      .toEqual([['remote', 'add', 'fork-contributor', 'https://github.com/contributor/widget.git']]);
    expect(argsFor(a => a[0] === 'fetch' && a[1] === 'fork-contributor'))
      .toEqual([['fetch', 'fork-contributor', 'contributor/fix-thing']]);
    // The fork is the start point even though the local checkout has its own name.
    const [add] = argsFor(a => a[0] === 'worktree' && a[1] === 'add');
    expect(add).toEqual([
      'worktree', 'add', '--no-track', '-b', 'fork/contributor/contributor/fix-thing',
      join(PATHS.worktrees, 'agent-fork'), 'fork-contributor/contributor/fix-thing',
    ]);
    // ...and the #4172 guard must not "repair" that fork upstream away.
    expect(argsFor(a => a[0] === 'branch' && a[1] === '--unset-upstream')).toHaveLength(0);
  });

  it('re-points a stale fork remote instead of duplicating it or failing', async () => {
    // The remote is named from the OWNER so re-runs reuse it; a contributor who
    // renamed or moved their fork leaves the recorded URL stale.
    scriptGit({ originHasBranch: false, forkRemoteUrl: 'https://github.com/contributor/old-name.git' });

    await createWorktree('agent-fork2', '/repo', 'task-fork2', {
      existingBranch: 'contributor/fix-thing',
      forkHead: { remoteUrl: 'https://github.com/contributor/widget.git', ownerLogin: 'contributor' },
    });

    expect(argsFor(a => a[0] === 'remote' && a[1] === 'add')).toHaveLength(0);
    expect(argsFor(a => a[0] === 'remote' && a[1] === 'set-url'))
      .toEqual([['remote', 'set-url', 'fork-contributor', 'https://github.com/contributor/widget.git']]);
  });

  it('leaves a fork remote alone when it already points at the right URL', async () => {
    scriptGit({ originHasBranch: false, forkRemoteUrl: 'https://github.com/contributor/widget.git' });

    await createWorktree('agent-fork3', '/repo', 'task-fork3', {
      existingBranch: 'contributor/fix-thing',
      forkHead: { remoteUrl: 'https://github.com/contributor/widget.git', ownerLogin: 'contributor' },
    });

    expect(argsFor(a => a[0] === 'remote' && (a[1] === 'add' || a[1] === 'set-url'))).toHaveLength(0);
    const [add] = argsFor(a => a[0] === 'worktree' && a[1] === 'add');
    expect(add).toContain('fork-contributor/contributor/fix-thing');
  });

  it('still throws today\'s exact error when no forkHead is supplied', async () => {
    // A caller without fork coordinates retains the origin-only behavior.
    scriptGit({ originHasBranch: false });

    await expect(createWorktree('agent-fork4', '/repo', 'task-fork4', { existingBranch: 'contributor/fix-thing' }))
      .rejects.toThrow('Cannot attach worktree to contributor/fix-thing: branch missing locally and origin/contributor/fix-thing unavailable');

    expect(argsFor(a => a[0] === 'remote')).toHaveLength(0);
    expect(argsFor(a => a[0] === 'worktree' && a[1] === 'add')).toHaveLength(0);
  });

  it('refuses attachment when the fork fetch leaves no ref', async () => {
    // A fetch that "succeeded" but produced no remote-tracking ref must not send
    // `worktree add` at a start point git would resolve somewhere else.
    scriptGit({ originHasBranch: false, forkRefResolves: false });

    await expect(createWorktree('agent-fork5', '/repo', 'task-fork5', {
      existingBranch: 'contributor/fix-thing',
      forkHead: { remoteUrl: 'https://github.com/contributor/widget.git', ownerLogin: 'contributor' },
    })).rejects.toThrow(/fork ref unavailable/);

    expect(argsFor(a => a[0] === 'worktree' && a[1] === 'add')).toHaveLength(0);
  });

  it('uses the fork even when origin already has the branch', async () => {
    await createWorktree('agent-fork6', '/repo', 'task-fork6', {
      existingBranch: 'shared/branch',
      forkHead: { remoteUrl: 'https://github.com/contributor/widget.git', ownerLogin: 'contributor' },
    });

    expect(argsFor(a => a[0] === 'remote')).not.toHaveLength(0);
    const [add] = argsFor(a => a[0] === 'worktree' && a[1] === 'add');
    expect(add).toContain('fork-contributor/shared/branch');
    expect(add).toContain('fork/contributor/shared/branch');
  });

  it('checks the re-attached branch of an existingBranch worktree too', async () => {
    // Branches created before this fix keep their bad upstream; a review-loop
    // agent re-attaching to one must not inherit a push aimed at main.
    scriptGit({ mergeReadings: ['refs/heads/main'] });

    await createWorktree('agent-4', '/repo', 'task-4', { existingBranch: 'cos/task-0/agent-0' });

    expect(argsFor(a => a[0] === 'branch' && a[1] === '--unset-upstream')).toHaveLength(1);
  });

  // The persistent feature-agent tree needs its own coverage, not just the CoS
  // one: it lives OUTSIDE `WORKTREES_DIR`, so neither `cleanupOrphanedWorktrees`
  // nor `reapMergedWorktrees` reaps it, and its only caller does not catch. A
  // stranded tree there blocks every retry with "already exists" until a human
  // prunes it, so the undo has to happen here rather than being left to a sweeper.
  it('creates the persistent feature-agent branch with --no-track too', async () => {
    const worktreePath = join(PATHS.worktrees, '..', 'feature-agents', 'fa-1', 'worktree');
    expect(await createPersistentWorktree('fa-1', '/repo', 'feature/x', 'main'))
      .toEqual({ worktreePath, branchName: 'feature/x', baseBranch: 'main' });
    expect(execGitMock).toHaveBeenCalledWith(
      ['worktree', 'add', '--no-track', '-b', 'feature/x', worktreePath, 'origin/main'],
      '/repo', expect.objectContaining({ timeout: WORKTREE_ADD_TIMEOUT_MS })
    );
  });

  it('undoes the persistent add when the upstream cannot be made safe', async () => {
    scriptGit({ mergeReadings: ['refs/heads/main', 'refs/heads/main'] });

    await expect(createPersistentWorktree('fa-2', '/repo', 'feature/y', 'main'))
      .rejects.toThrow(/still resolves to/);

    expect(argsFor(a => a[0] === 'worktree' && a[1] === 'remove')).toHaveLength(1);
    expect(argsFor(a => a[0] === 'branch' && a[1] === '-D')).toHaveLength(1);
  });
});

describe('cleanupOrphanedWorktrees ownership and removal', () => {
  const tree = agentId => join(PATHS.worktrees, agentId);

  beforeEach(() => {
    publicationMock.mockReset().mockImplementation((_repo, work) => work());
    existsSync.mockReset().mockReturnValue(true);
    readdir.mockReset().mockResolvedValue([]);
    lstat.mockReset().mockRejectedValue(Object.assign(new Error('gone'), { code: 'ENOENT' }));
    rm.mockClear();
    getDefaultBranchMock.mockResolvedValue('main');
    hasBranchMergeEvidenceMock.mockResolvedValue(true);
    completionHoldMock.mockResolvedValue(null);
    execGitMock.mockReset();
  });

  afterEach(() => {
    publicationMock.mockReset().mockImplementation((_repo, work) => work());
    readdir.mockReset().mockResolvedValue([]);
    lstat.mockReset().mockResolvedValue({});
  });

  it('retains an orphan before lockfile discard or merge when a durable retirement cut owns the repository', async () => {
    execGitMock.mockImplementation(async (args, cwd) => {
      if (args[0] === 'worktree' && args[1] === 'list') return { stdout: ['worktree ' + tree('agent-dead'),
        'HEAD ' + 'a'.repeat(40), 'branch refs/heads/cos/task/agent-dead', ''].join('\n') };
      if (args[0] === 'status') return { stdout: ' M package-lock.json', exitCode: 0 };
      if (args[0] === 'rev-list') return { stdout: '1', exitCode: 0 };
      if (args[0] === 'rev-parse') return { stdout: args[1] === '--show-toplevel' ? cwd : args[1] === '--verify' ? 'a'.repeat(40) : 'main', exitCode: 0 };
      return { stdout: '', exitCode: 0 };
    });
    publicationMock.mockRejectedValueOnce(new Error('checkout-retirement-reserved'));
    expect(await cleanupOrphanedWorktrees('/repo', new Set(), { claimOwners: { agents: [] } })).toBe(0);
    expect(publicationMock).toHaveBeenCalledTimes(1);
    expect(publicationMock).toHaveBeenCalledWith('/repo', expect.any(Function));
    expect(execGitMock.mock.calls.some(([args]) => ['checkout', 'merge', 'branch', 'push'].includes(args[0])
      || (args[0] === 'worktree' && args[1] === 'remove'))).toBe(false);
    expect(rm).not.toHaveBeenCalled();
  });

  it('removes only the clean inactive agent and preserves active, human, locked, dirty and detached trees', async () => {
    const entries = [
      { path: '/repo', branch: 'main' },
      { path: join(PATHS.worktrees + '-old', 'agent-outside'), branch: 'outside' },
      { path: tree('agent-active'), branch: 'cos/task/agent-active' },
      { path: tree('claim-issue-42'), branch: 'claim/issue-42' },
      { path: tree('agent-locked'), branch: 'cos/task/agent-locked', locked: true },
      { path: tree('agent-dead'), branch: 'cos/task/agent-dead' },
      { path: tree('agent-dirty'), branch: 'cos/task/agent-dirty' },
      // Detached HEAD (e.g. interrupted rebase) may carry commits no ref holds; removal would orphan them.
      { path: tree('agent-detached'), detached: true },
    ];
    // `worktree list` reflects removals made so far, as real git does — removal is
    // verified against the registration afterwards.
    const removedPaths = new Set();
    const listing = () => entries.filter(entry => !removedPaths.has(entry.path)).flatMap(entry => [
      'worktree ' + entry.path, 'HEAD ' + 'a'.repeat(40),
      entry.detached ? 'detached' : 'branch refs/heads/' + entry.branch,
      ...(entry.locked ? ['locked protected'] : []), '',
    ]).join('\n');
    // Include the same on-disk entries in the external-repo scan: ownership
    // holds must survive that second pass too.
    readdir.mockResolvedValue(entries.slice(2).map(entry => ({
      name: win32.basename(entry.path), isDirectory: () => true,
    })));
    execGitMock.mockImplementation((args, cwd) => {
      if (args[0] === 'worktree' && args[1] === 'list') return Promise.resolve({ stdout: listing() });
      if (args[0] === 'worktree' && args[1] === 'remove') removedPaths.add(args[2]);
      if (args[0] === 'rev-parse') return Promise.resolve({ stdout: args[1] === '--show-toplevel' ? cwd : args[1] === '--path-format=absolute' ? '/repo/.git' : args[1] === '--verify' ? 'a'.repeat(40) : 'main', exitCode: 0 });
      if (args[0] === 'status') return Promise.resolve({ stdout: cwd === tree('agent-dirty') ? ' M src/work.js' : '' });
      if (args[0] === 'rev-list') return Promise.resolve({ stdout: '0', stderr: '', exitCode: 0 });
      return Promise.resolve({ stdout: '', stderr: '', exitCode: 0 });
    });

    expect(await cleanupOrphanedWorktrees('/repo', new Set(['agent-active']), { claimOwners: { agents: [] } })).toBe(1);
    expect(execGitMock.mock.calls.filter(([args]) => args[0] === 'worktree' && args[1] === 'remove'))
      .toEqual([[['worktree', 'remove', tree('agent-dead'), '--force'], '/repo', { timeout: WORKTREE_ADD_TIMEOUT_MS }]]);
    expect(execGitMock.mock.calls.filter(([args]) => args[0] === 'push').map(([args]) => args.at(-1)))
      .toEqual([':refs/heads/cos/task/agent-dead']);
    expect(execGitMock.mock.calls.filter(([args]) => args[0] === 'status').map(([, cwd]) => cwd))
      .toEqual([tree('agent-dead'), tree('agent-dead'), tree('agent-dirty')]);
    expect(rm).not.toHaveBeenCalled();
  });

  it('re-reads liveness and the agent registry per tree, so a tree claimed after the caller snapshot survives', async () => {
    const entries = [
      { path: '/repo', branch: 'main' },
      { path: tree('agent-late'), branch: 'cos/task/agent-late' },
      { path: tree('agent-registered'), branch: 'cos/task/agent-registered' },
      { path: tree('agent-dead'), branch: 'cos/task/agent-dead' },
    ];
    const live = new Set();
    const removedPaths = new Set();
    execGitMock.mockImplementation((args, cwd) => {
      if (args[0] === 'worktree' && args[1] === 'list') {
        // CoS dispatches agent-late after the job snapshot, before this pass reaches its tree.
        live.add('agent-late');
        return Promise.resolve({ stdout: entries.filter(e => !removedPaths.has(e.path))
          .flatMap(e => ['worktree ' + e.path, 'HEAD ' + 'a'.repeat(40), 'branch refs/heads/' + e.branch, '']).join('\n') });
      }
      if (args[0] === 'worktree' && args[1] === 'remove') removedPaths.add(args[2]);
      if (args[0] === 'rev-parse') return Promise.resolve({ stdout: args[1] === '--show-toplevel' ? cwd : args[1] === '--path-format=absolute' ? '/repo/.git' : args[1] === '--verify' ? 'a'.repeat(40) : 'main', exitCode: 0 });
      if (args[0] === 'rev-list') return Promise.resolve({ stdout: '0', stderr: '', exitCode: 0 });
      return Promise.resolve({ stdout: '', stderr: '', exitCode: 0 });
    });
    const claimOwners = { agents: [{ id: 'agent-registered', status: 'running', workspacePath: tree('agent-registered'), sourceWorkspace: '/repo' }] };

    expect(await cleanupOrphanedWorktrees('/repo', () => new Set(live), { claimOwners })).toBe(1);
    expect(execGitMock.mock.calls.filter(([args]) => args[0] === 'worktree' && args[1] === 'remove'))
      .toEqual([[['worktree', 'remove', tree('agent-dead'), '--force'], '/repo', { timeout: WORKTREE_ADD_TIMEOUT_MS }]]);
    expect(execGitMock.mock.calls.filter(([args]) => args[0] === 'push').map(([args]) => args.at(-1)))
      .toEqual([':refs/heads/cos/task/agent-dead']);
  });

  it('holds every tree when the agent registry cannot be read', async () => {
    execGitMock.mockImplementation((args) => args[0] === 'worktree' && args[1] === 'list'
      ? Promise.resolve({ stdout: ['worktree ' + tree('agent-dead'), 'HEAD ' + 'a'.repeat(40), 'branch refs/heads/cos/task/agent-dead', ''].join('\n') })
      : Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }));

    expect(await cleanupOrphanedWorktrees('/repo', () => new Set(), { claimOwners: { agents: null } })).toBe(0);
    expect(execGitMock.mock.calls.some(([args]) => args[0] === 'worktree' && args[1] === 'remove')).toBe(false);
  });
});