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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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);
});
});