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
/**
* Worktree ownership through branch-reconcile's real cleanup boundary (#10270).
*
* A checkout freshly cut from the default branch is clean and an ancestor of
* it, so the merged-branch cleanup used to retire it — and its branch — while
* the process that created it was still running. These tests drive `reconcile`
* against a real throwaway repository (no forge is consulted) to pin that only
* PortOS-managed roots are retired unattended. The Git page's merged-branch
* action shares those ownership gates; external checkouts need scoped release.
*/
import { describe, it, expect, beforeEach, afterEach, afterAll, onTestFailed, vi } from 'vitest';
import { mkdtemp, mkdir, rm, utimes, writeFile, appendFile, unlink } from 'fs/promises';
import { existsSync, realpathSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { execGit } from '../lib/execGit.js';
import { materializeGitRepo, SKIP_HEAVY_INTEGRATION } from '../lib/gitTestRepo.js';
import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../lib/mockPathsDataRoot.js';
import { captureCompletedCheckouts } from './completedCheckoutEvidence.js';
import { readRetirementCheckoutIdentity } from '../lib/retirementCheckoutObservation.js';
// Keep retirement I/O inside a test-owned data root, never the install's data tree.
vi.mock('../lib/paths.js', async importOriginal => makePathsProxy(await importOriginal(), {
dataRoot: () => lazyTempDataRoot('portos-reconcile-own-archives-'),
}));
const pendingPhases = new Set();
afterAll(async () => {
await Promise.all(pendingPhases);
await cleanupTempDataRoots();
});
const injected = vi.hoisted(() => ({ statusPath: null, statusThrows: false, beforeRemove: null, owners: [], policies: [], app: null, schedule: { tasks: {}, executions: {} }, forge: {}, gitSpawns: [], gitInFlight: new Set(), phase: null }));
vi.mock('../lib/execGit.js', async (importOriginal) => {
const actual = await importOriginal();
const observe = run => async (args, cwd, options) => {
const phase = injected.phase;
if (!phase) return run(args, cwd, options);
phase.signal.throwIfAborted();
if (phase.closed) throw new Error(`Manual claim ${phase.name} already settled`);
const remaining = 30000 - (performance.now() - phase.started);
if (remaining <= 0) throw new Error(`Manual claim ${phase.name} exceeded its 30s deadline`);
const command = ['worktree', 'bundle', 'remote'].includes(args[0]) ? args.slice(0, 2).join(' ') : args[0];
const pending = { command, started: performance.now() };
phase.pending.add(pending);
try {
const operation = run(args, cwd, { ...options, timeout: Math.min(options?.timeout || 30000, remaining) });
pending.settled = operation.then(() => {}, () => {});
return await operation;
}
finally {
phase.pending.delete(pending);
const ms = performance.now() - pending.started;
const row = phase.commands.get(command) || { count: 0, ms: 0, maxMs: 0 };
row.count++;
row.ms += ms;
row.maxMs = Math.max(row.maxMs, ms);
phase.commands.set(command, row);
}
};
return { ...actual, execGit: async (args, cwd, options) => {
injected.gitSpawns.push({ args, cwd });
// Git reports forward slashes even when path.join uses Windows separators.
if (args[0] === 'status' && injected.statusPath && cwd?.replaceAll('\\', '/') === injected.statusPath.replaceAll('\\', '/')) {
if (injected.statusThrows || !options?.ignoreExitCode) throw new Error('synthetic unreadable index');
return { stdout: '', stderr: 'synthetic unreadable index', exitCode: 128 };
}
if (args[0] === 'worktree' && args[1] === 'remove' && injected.beforeRemove) {
const before = injected.beforeRemove;
injected.beforeRemove = null;
await before();
throw new Error('synthetic Git removal failure');
}
const running = { args, startedAt: Date.now() };
injected.gitInFlight.add(running);
try {
return await observe(actual.execGit)(args, cwd, options);
} finally {
injected.gitInFlight.delete(running);
}
}, execGitSafe: observe(actual.execGitSafe) };
});
vi.mock('./apps.js', () => ({ getAllApps: async () => [injected.app], getAppById: async id => injected.app?.id === id ? injected.app : null }));
vi.mock('./taskScheduleStore.js', async importOriginal => ({
...await importOriginal(), loadSchedule: async () => injected.schedule,
updateSchedule: async mutate => (await mutate(injected.schedule)).result,
}));
vi.mock('./cosState.js', () => ({
readAgentsStateForSafetyCheck: async () => ({ trusted: injected.owners !== null,
agents: injected.owners && Object.fromEntries(injected.owners.map(agent => [agent.id, agent])) }),
}));
// Use the real completion-policy evaluator with synthetic policy records.
vi.mock('./branchCompletionPolicy.js', async (importOriginal) => {
const actual = await importOriginal();
return { ...actual, readBranchCompletionPolicies: async () => injected.policies, readBranchCompletionHold: input => actual.readBranchCompletionHold(input, {
readPolicies: async () => injected.policies,
}) };
});
// The hermetic repo has no forge. A branch's merged PR is injected at the
// forge-read boundary: { head, mergedAt }, or 'unavailable' for a failed read.
vi.mock('./heldCheckoutReview.js', async (importOriginal) => ({
...await importOriginal(),
findMergedPullRequest: async (repoPath, branch) => {
const pr = injected.forge[branch];
if (!pr || pr === 'unavailable') throw new Error('retirement-forge-unavailable');
return { url: `https://github.com/example/repo/pull/${branch.split('-').at(-1)}`, mergedAt: pr.mergedAt };
},
readRetirementForgeEvidence: async (repoPath, branch, prUrl) => ({ prUrl, prHead: injected.forge[branch].head }),
}));
// Keep the run hermetic: the verdict ledger otherwise reads this install's
// real CoS data directory.
vi.mock('./supersededLedger.js', async (importOriginal) => ({
...await importOriginal(),
readVerdictLedger: async () => [],
}));
const { reconcile, gatherBranchState, classifyBranches, cleanupMerged, reapSupersededBranches, describeIdleReconcilePark } = await import('./branchReconcile.js');
const { clearAgentDispatching, getActiveAgentIds, markAgentDispatching } = await import('./agentState.js');
const { deleteMergedBranches } = await import('./git.js');
const { PATHS } = await import('../lib/paths.js');
const DAY = 24 * 60 * 60 * 1000;
// A reconcile pass is ~55 sequential real-Git spawns plus fixture setup, all inside
// Vitest's 30s test budget. A load-induced stall (#13459) otherwise surfaces as a bare
// timeout; name the stalled Git command before the budget expires.
const SLOW_REPORT_MS = 20_000;
describe.skipIf(SKIP_HEAVY_INTEGRATION)('branch-reconcile worktree ownership (real git)', () => {
let scratch;
let repo;
let external;
let slowReport;
beforeEach(async () => {
await Promise.all(pendingPhases);
Object.assign(injected, { statusPath: null, statusThrows: false, beforeRemove: null, owners: [], policies: [], app: null, schedule: { tasks: {}, executions: {} }, forge: {}, gitSpawns: [], gitInFlight: new Set(), phase: null });
slowReport = setTimeout(() => {
const now = Date.now();
const running = [...injected.gitInFlight].map(({ args, startedAt }) => `git ${args.slice(0, 3).join(' ')} (${now - startedAt}ms)`).join('; ') || 'none';
console.log(`🐢 ownership test still running after ${SLOW_REPORT_MS}ms: ${injected.gitSpawns.length} git spawns, in flight: ${running}`);
}, SLOW_REPORT_MS).unref();
scratch = realpathSync(await mkdtemp(join(tmpdir(), 'portos-reconcile-own-')));
const safeRepo = join(scratch, 'repo');
await mkdir(safeRepo);
await materializeGitRepo(safeRepo, { identity: { email: '[email protected]', name: 'Test' } });
repo = (await execGit(['rev-parse', '--show-toplevel'], safeRepo)).stdout.trim() || safeRepo;
injected.app = { id: 'app-1', repoPath: repo };
external = join(scratch, 'elsewhere');
await mkdir(external);
});
afterEach(async () => {
clearTimeout(slowReport);
// Vitest timeouts do not settle the hook/body promise. Never erase a repo
// while a timed-out phase still has a Git command or continuation using it.
await Promise.all(pendingPhases);
await rm(scratch, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
});
function phaseSummary(phase) {
const commands = [...phase.commands].sort((a, b) => b[1].ms - a[1].ms);
return { phase: phase.name, ms: Math.round((phase.finished ?? performance.now()) - phase.started),
gitCalls: commands.reduce((sum, [, row]) => sum + row.count, 0),
commands: commands.slice(0, 5).map(([command, row]) => ({ command, count: row.count, ms: Math.round(row.ms), maxMs: Math.round(row.maxMs) })),
pending: [...phase.pending].slice(0, 5).map(row => ({ command: row.command, ms: Math.round(performance.now() - row.started) })) };
}
function runPhase(name, signal, work) {
const phase = { name, signal, started: performance.now(), commands: new Map(), pending: new Set() };
injected.phase = phase;
// stderr survives pregate's console suppression, including a hook timeout.
onTestFailed(() => process.stderr.write(`Manual claim diagnostic: ${JSON.stringify(phaseSummary(phase))}\n`));
const run = Promise.resolve().then(work).finally(async () => {
// A rejected Promise.all can leave sibling Git calls running. Close the
// phase to new spawns, then join those calls before releasing its fixture.
phase.closed = true;
await Promise.all([...phase.pending].map(row => row.settled));
phase.finished = performance.now();
process.stderr.write(`Manual claim diagnostic: ${JSON.stringify(phaseSummary(phase))}\n`);
});
const settled = run.then(() => {}, () => {});
pendingPhases.add(settled);
settled.then(() => pendingPhases.delete(settled));
return run;
}
/** A clean checkout of a new branch at main — "merged" by ancestry alone. */
async function addTree(path, branch, { ageMs = 0 } = {}) {
await execGit(['worktree', 'add', '-b', branch, path, 'main'], repo);
if (ageMs) {
const then = new Date(Date.now() - ageMs);
await utimes(path, then, then);
}
return path;
}
const branches = async () => (await execGit(['branch', '--format=%(refname:short)'], repo)).stdout.trim().split('\n');
// Git expands Windows' short TEMP spelling and emits forward slashes; the
// inventory promises Git's checkout path, not Node's fixture-input spelling.
const gitCheckoutPath = async (path) => (await execGit(['rev-parse', '--show-toplevel'], path)).stdout.trim();
// Operator cleanup independently verifies the remote's advertised default.
// A bare fixture's default HEAD otherwise points at an unborn master branch.
async function addOrigin() {
const remote = join(scratch, 'origin.git');
await execGit(['init', '--bare', remote], scratch);
await execGit(['symbolic-ref', 'HEAD', 'refs/heads/main'], remote);
await execGit(['remote', 'add', 'origin', remote], repo);
await execGit(['push', 'origin', 'main'], repo);
}
it('reports an unmerged detached checkout without discarding its tracked, untracked or ignored content', async () => {
const path = await addTree(join(external, 'detached-work'), 'temporary-work');
await writeFile(join(path, 'tracked.txt'), 'unique committed work\n');
await writeFile(join(path, '.gitignore'), 'ignored.txt\n');
await execGit(['add', 'tracked.txt', '.gitignore'], path);
await execGit(['commit', '-m', 'feat: synthetic detached work'], path);
const head = (await execGit(['rev-parse', 'HEAD'], path)).stdout.trim();
await execGit(['checkout', '--detach'], path);
await execGit(['branch', '-D', 'temporary-work'], repo);
await writeFile(join(path, 'untracked.txt'), 'unique untracked work\n');
await writeFile(join(path, 'ignored.txt'), 'unique ignored work\n');
await execGit(['worktree', 'lock', '--reason', 'explicit owner handoff required', path], repo);
const checkoutIdentity = await readRetirementCheckoutIdentity(path);
expect(checkoutIdentity).toMatch(/^[a-f0-9]{64}$/);
const observationStartedAt = Date.now();
const result = await reconcile(repo, { activeAgentIds: new Set() });
const observationFinishedAt = Date.now();
expect(result.detachedWorktrees).toEqual([]); // old merged-only projection cannot see it
const report = describeIdleReconcilePark(result.skipped, [], { worktreeInventory: result.worktreeInventory });
expect(report.remaining).toEqual([{
path: await gitCheckoutPath(path), head, detached: true, locked: true, lockReason: 'explicit owner handoff required',
managed: false, reason: 'worktree-locked', checkoutIdentity, observedAt: expect.any(String),
}]);
const observedAt = Date.parse(report.remaining[0].observedAt);
expect(observedAt).toBeGreaterThanOrEqual(observationStartedAt);
expect(observedAt).toBeLessThanOrEqual(observationFinishedAt);
expect(report.remaining[0].observedAt).toBe(new Date(observedAt).toISOString());
for (const name of ['tracked.txt', 'untracked.txt', 'ignored.txt']) expect(existsSync(join(path, name))).toBe(true);
expect((await execGit(['rev-parse', 'HEAD'], path)).stdout.trim()).toBe(head);
});
it('preserves unmanaged and unverified manual checkouts regardless of age', async () => {
const claudeRoot = join(repo, '.claude', 'worktrees');
await mkdir(claudeRoot, { recursive: true });
const fresh = await addTree(join(external, 'release-preparation'), 'release-prep/v9.9.9');
const old = await addTree(join(external, 'old-workspace'), 'old-workspace', { ageMs: 30 * DAY });
const staleClaim = await addTree(join(claudeRoot, 'claim-issue-5'), 'claim/issue-5', { ageMs: 30 * DAY });
const lockedClaim = await addTree(join(claudeRoot, 'claim-issue-6'), 'claim/issue-6', { ageMs: 30 * DAY });
await execGit(['worktree', 'lock', '--reason', 'await scoped owner release', lockedClaim], repo);
const dirtyClaim = await addTree(join(claudeRoot, 'claim-issue-7'), 'claim/issue-7');
await writeFile(join(dirtyClaim, 'wip.txt'), 'unsaved\n');
await utimes(dirtyClaim, new Date(Date.now() - 30 * DAY), new Date(Date.now() - 30 * DAY));
const staleClaimPath = await gitCheckoutPath(staleClaim);
const result = await reconcile(repo, { activeAgentIds: new Set() });
const reasonFor = (branch) => result.skipped.find((s) => s.branch === branch)?.reason;
const context = JSON.stringify({ cleaned: result.cleaned, skipped: result.skipped });
// Unmanaged: held at any age, checkout AND branch intact.
expect(reasonFor('release-prep/v9.9.9'), context).toBe('worktree-unmanaged-location');
expect(reasonFor('old-workspace'), context).toBe('worktree-unmanaged-location');
expect(existsSync(fresh)).toBe(true);
expect(existsSync(old)).toBe(true);
// Age and registry absence do not prove a manual claim finished.
expect(result.cleaned, context).not.toContain('claim/issue-5');
expect(reasonFor('claim/issue-5'), context).toBe('claim-completion-unverified');
expect(result.merged).toContainEqual(expect.objectContaining({ branch: 'claim/issue-5', state: 'MERGED' }));
expect(existsSync(staleClaim)).toBe(true);
expect(reasonFor('claim/issue-6'), context).toBe('worktree-locked');
expect(existsSync(lockedClaim)).toBe(true);
const report = describeIdleReconcilePark(result.skipped, [], {
wip: result.wip, worktreeInventory: result.worktreeInventory,
});
expect(report.remaining).toContainEqual(expect.objectContaining({
branch: 'claim/issue-6', path: await gitCheckoutPath(lockedClaim), reason: 'worktree-locked',
head: expect.any(String), locked: true, lockReason: 'await scoped owner release', managed: true,
}));
expect(report.remaining).toContainEqual(expect.objectContaining({
branch: 'old-workspace', path: await gitCheckoutPath(old), reason: 'worktree-unmanaged-location', managed: false,
}));
expect(report.remaining).toContainEqual(expect.objectContaining({
path: staleClaimPath, branch: 'claim/issue-5', reason: 'claim-completion-unverified',
}));
expect(result.cleaned, context).not.toContain('claim/issue-7');
expect(existsSync(dirtyClaim)).toBe(true);
const left = await branches();
expect(left).toEqual(expect.arrayContaining(['release-prep/v9.9.9', 'old-workspace', 'claim/issue-6', 'claim/issue-7']));
expect(left).toContain('claim/issue-5');
});
// A real-Git `reconcile` is hundreds of serial Git spawns, and retiring even
// one checkout re-verifies it ~100 times (that floor is the production
// admission contract). The scenarios below therefore keep one retirement per
// test; a single test holding every sibling exhausted the 30s budget when
// pregate loaded the host (#13113).
async function addCompletedClaim() {
const root = join(repo, '.claude', 'worktrees');
await mkdir(root, { recursive: true });
const clean = await addTree(join(root, 'claim-issue-11'), 'claim/issue-11');
const owner = { id: 'completed-claim', status: 'running', startedAt: new Date(Date.now() - 1000).toISOString(),
metadata: { sourceWorkspace: repo, claimPicksOwnBranch: true, claimBranches: ['claim/issue-11'] } };
const completedCheckouts = await captureCompletedCheckouts(owner, { success: true });
expect(completedCheckouts).toHaveLength(1);
injected.policies = [{ ...owner, status: 'completed', result: { success: true }, completedAt: new Date().toISOString(),
metadata: { ...owner.metadata, completedCheckouts } }];
return clean;
}
const reconcileWithoutOwners = () => reconcile(repo, {
activeAgentIds: new Set(), claimOwners: { agents: [], readAgents: async () => [] },
});
it('retires a fresh claim with exact completion evidence while preserving a locked sibling', async () => {
const root = join(repo, '.claude', 'worktrees');
const locked = await addTree(join(root, 'claim-issue-12'), 'claim/issue-12');
await execGit(['worktree', 'lock', locked], repo);
const clean = await addCompletedClaim();
injected.gitSpawns.length = 0;
const result = await reconcileWithoutOwners();
expect(result.cleaned).toEqual(['claim/issue-11']);
expect(existsSync(clean)).toBe(false);
expect(result.skipped).toContainEqual(expect.objectContaining({ branch: 'claim/issue-12', reason: 'worktree-locked' }));
expect(existsSync(locked)).toBe(true);
expect(await branches()).toEqual(expect.arrayContaining(['claim/issue-12']));
// Pinned spawn-count ceiling for single-checkout retirement (#13154):
// Reduced from ~120 serial spawns down to <=105 by sharing Git reads inside
// the critical section (e.g. 1 worktree list per admission, repo common-dir cache).
expect(injected.gitSpawns.length).toBeLessThanOrEqual(105);
});
it('holds a claim checkout with uncommitted or unmerged work', async () => {
const root = join(repo, '.claude', 'worktrees');
const dirty = await addTree(join(root, 'claim-issue-13'), 'claim/issue-13');
await writeFile(join(dirty, 'unfinished.txt'), 'preserve this work\n');
const unmerged = await addTree(join(root, 'claim-issue-14'), 'claim/issue-14');
await writeFile(join(unmerged, 'committed.txt'), 'finish this work\n');
await execGit(['add', 'committed.txt'], unmerged);
await execGit(['commit', '-m', 'feat: unfinished work'], unmerged);
const result = await reconcileWithoutOwners();
expect(result.cleaned).toEqual([]);
expect(result.inFlight).toEqual(expect.arrayContaining([
expect.objectContaining({ branch: 'claim/issue-13', state: 'ABANDONED_WIP' }),
]));
// This hermetic repo has no forge, so committed work is held until PR state
// can be established rather than being retired as merged.
expect(result.wip).toContainEqual(expect.objectContaining({ branch: 'claim/issue-14' }));
for (const path of [dirty, unmerged]) expect(existsSync(path)).toBe(true);
expect(existsSync(join(dirty, 'unfinished.txt'))).toBe(true);
expect(await branches()).toEqual(expect.arrayContaining(['claim/issue-13', 'claim/issue-14']));
});
// A manual /claim: commit in the checkout, merge it into main, leave the tree
// under the managed root, and have the forge report the merge (#12849).
const HOUR = 60 * 60 * 1000;
const mergedLongAgo = () => new Date(Date.now() - 3 * HOUR).toISOString();
async function addManualClaim(n, { merge = true, ageMs = 2 * HOUR } = {}) {
const root = join(repo, '.claude', 'worktrees');
await mkdir(root, { recursive: true });
const branch = `claim/issue-${n}`;
const path = await addTree(join(root, `claim-issue-${n}`), branch);
await writeFile(join(path, `work-${n}.txt`), `issue ${n}\n`);
await execGit(['add', `work-${n}.txt`], path);
await execGit(['commit', '-m', `feat: issue ${n}`], path);
const head = (await execGit(['rev-parse', 'HEAD'], path)).stdout.trim();
if (merge) await execGit(['merge', '--no-ff', '-m', `Merge ${branch}`, branch], repo);
if (ageMs) await utimes(path, new Date(Date.now() - ageMs), new Date(Date.now() - ageMs));
injected.forge[branch] = { head, mergedAt: mergedLongAgo() };
return { branch, path, head };
}
const reconcileManualClaims = () => reconcile(repo, {
activeAgentIds: new Set(), claimOwners: { agents: injected.owners, readAgents: async () => injected.owners },
});
const expectHeld = async (held) => {
for (const { path } of held) expect(existsSync(path)).toBe(true);
expect(await branches()).toEqual(expect.arrayContaining(held.map(claim => claim.branch)));
};
describe('manual claim retirement with an active sibling', () => {
let shipped;
let owned;
// #13473 retained a 31.445s failure under three-worker pregate. Its single
// passing A/B did not diagnose the cause. Give fixture construction and the
// public action their existing, separate 30s hook/test budgets; per-command
// diagnostics and the remaining phase deadline keep a hang visible/bounded.
beforeEach(({ signal }) => runPhase('fixture', signal, async () => {
shipped = await addManualClaim(21);
owned = await addManualClaim(24);
injected.owners = [{ id: 'agent-live-claim', status: 'running', sourceWorkspace: repo, workspacePath: repo,
metadata: { sourceWorkspace: repo, claimBranches: [owned.branch] } }];
}));
it('retires a forge-merged manual claim without a run receipt while an actively owned sibling stays (#12849)', ({ signal }) => runPhase('reconcile and preservation assertions', signal, async () => {
const result = await reconcileManualClaims();
const context = JSON.stringify({ cleaned: result.cleaned, skipped: result.skipped });
expect(result.cleaned, context).toEqual([shipped.branch]);
expect(existsSync(shipped.path)).toBe(false);
expect(await branches()).not.toContain(shipped.branch);
// #13519 replaced archival with archive-free merged cleanup. The exact
// completed ref still protects recovery inside the original repository.
for (const directory of ['held-checkout-archives', 'branch-retirement-archives', 'initialized-checkout-retirements']) {
expect(existsSync(join(PATHS.cos, directory))).toBe(false);
}
expect((await execGit(['rev-parse', `refs/portos/completed/${shipped.head}`], repo)).stdout.trim()).toBe(shipped.head);
expect(result.skipped.find(row => row.branch === owned.branch)?.reason, context).toBe('claim-owner-active');
await expectHeld([owned]);
expect((await execGit(['rev-parse', 'HEAD'], owned.path)).stdout.trim()).toBe(owned.head);
}));
});
it('holds a merged manual claim that is dirty or locked (#12849)', async () => {
const dirty = await addManualClaim(22);
await writeFile(join(dirty.path, 'unsaved.txt'), 'preserve\n');
await utimes(dirty.path, new Date(Date.now() - 2 * HOUR), new Date(Date.now() - 2 * HOUR));
const locked = await addManualClaim(23);
await execGit(['worktree', 'lock', locked.path], repo);
const result = await reconcileManualClaims();
const context = JSON.stringify({ cleaned: result.cleaned, skipped: result.skipped });
expect(result.cleaned, context).toEqual([]);
expect(result.skipped.find(row => row.branch === locked.branch)?.reason, context).toBe('worktree-locked');
expect(result.inFlight).toContainEqual(expect.objectContaining({ branch: dirty.branch, state: 'ABANDONED_WIP' }));
expect(existsSync(join(dirty.path, 'unsaved.txt'))).toBe(true);
await expectHeld([dirty, locked]);
});
it('holds a manual claim whose merge the forge cannot prove for its exact head (#12849)', async () => {
const unmerged = await addManualClaim(25, { merge: false });
const forgeDown = await addManualClaim(26);
injected.forge[forgeDown.branch] = 'unavailable';
const otherHead = await addManualClaim(27);
injected.forge[otherHead.branch] = { head: 'f'.repeat(40), mergedAt: mergedLongAgo() };
const result = await reconcileManualClaims();
const context = JSON.stringify({ cleaned: result.cleaned, skipped: result.skipped });
expect(result.cleaned, context).toEqual([]);
const reasonFor = branch => result.skipped.find(row => row.branch === branch)?.reason;
for (const held of [forgeDown, otherHead]) expect(reasonFor(held.branch), context).toBe('claim-completion-unverified');
expect(result.wip).toContainEqual(expect.objectContaining({ branch: unmerged.branch }));
await expectHeld([unmerged, forgeDown, otherHead]);
});
it('holds a forge-merged manual claim that was merged or created too recently to retire (#12849)', async () => {
const justMerged = await addManualClaim(28);
injected.forge[justMerged.branch].mergedAt = new Date().toISOString();
const young = await addManualClaim(29, { ageMs: 0 });
const result = await reconcileManualClaims();
const context = JSON.stringify({ cleaned: result.cleaned, skipped: result.skipped });
expect(result.cleaned, context).toEqual([]);
for (const held of [justMerged, young]) expect(result.skipped.find(row => row.branch === held.branch)?.reason, context).toBe('claim-completion-unverified');
await expectHeld([justMerged, young]);
});
it('holds a clean agent tree at the default HEAD while its dispatch is still registering (#11775)', async () => {
const root = join(repo, '.claude', 'worktrees');
await mkdir(root, { recursive: true });
const tree = await addTree(join(root, 'agent-dispatching'), 'agent/dispatching');
markAgentDispatching('agent-dispatching');
try {
const held = await reconcile(repo, { activeAgentIds: new Set(getActiveAgentIds()) });
expect(held.cleaned).not.toContain('agent/dispatching');
expect(held.skipped).toContainEqual(expect.objectContaining({ branch: 'agent/dispatching', reason: 'worktree-active-agent' }));
expect(existsSync(tree)).toBe(true);
} finally {
clearAgentDispatching('agent-dispatching');
}
// Once dispatch settles without registering an owner, the same tree is reaped.
const reaped = await reconcile(repo, { activeAgentIds: new Set(getActiveAgentIds()) });
expect(reaped.cleaned).toContain('agent/dispatching');
expect(existsSync(tree)).toBe(false);
});
// #12990: omitted ids used to become `new Set(null)` — "nobody running" — so an
// agent tree in its dispatch-registration window was retired by the default call.
it('holds an agent tree when the operator cleanup is not given live-agent ids', async () => {
const tree = await addTree(join(repo, '.claude', 'worktrees', 'agent-registering'), 'agent/registering');
await addOrigin();
markAgentDispatching('agent-registering');
try {
const unknown = await deleteMergedBranches(repo);
expect(unknown.deleted).toEqual([]);
expect(unknown.skipped).toContain('agent/registering (local: agent liveness unknown)');
expect(existsSync(tree)).toBe(true);
} finally {
clearAgentDispatching('agent-registering');
}
const known = await deleteMergedBranches(repo, { activeAgentIds: new Set() });
expect(known.deleted.map((row) => row.name)).toEqual(['agent/registering']);
expect(existsSync(tree)).toBe(false);
});
it('keeps an unmanaged checkout held at the operator merged-branch cleanup boundary', async () => {
const loose = await addTree(join(external, 'loose'), 'loose-br', { ageMs: 30 * DAY });
const held = await reconcile(repo, { activeAgentIds: new Set() });
expect(held.skipped.find((s) => s.branch === 'loose-br')?.reason).toBe('worktree-unmanaged-location');
await addOrigin();
const operator = await deleteMergedBranches(repo, { activeAgentIds: new Set() });
expect(operator.deleted).toEqual([]);
expect(operator.skipped).toContain('loose-br (local: worktree-unmanaged-location)');
expect(existsSync(loose)).toBe(true);
expect(await branches()).toContain('loose-br');
});
it.each([false, true])('preserves authored files when status is unreadable (throws=%s)', async (throws) => {
const path = await addTree(join(repo, '.claude', 'worktrees', 'claim-unreadable'), 'claim/issue-31', { ageMs: 30 * DAY });
await writeFile(join(path, 'unfinished.txt'), 'keep this work\n');
injected.statusPath = throws ? path : path.replaceAll('/', '\\');
injected.statusThrows = throws;
const result = await reconcile(repo, { activeAgentIds: new Set() });
expect(result.cleaned).not.toContain('claim/issue-31');
expect(result.skipped).toContainEqual(expect.objectContaining({ branch: 'claim/issue-31', reason: 'worktree-status-unavailable' }));
expect(existsSync(join(path, 'unfinished.txt'))).toBe(true);
expect(await branches()).toContain('claim/issue-31');
});
it('does not let a superseded verdict authorize retirement of an unreadable checkout', async () => {
const branch = 'fix/superseded-unreadable';
const path = await addTree(join(repo, '.claude', 'worktrees', 'superseded'), branch);
await writeFile(join(path, 'unfinished.txt'), 'preserve before backup\n');
const tip = (await execGit(['rev-parse', branch], repo)).stdout.trim();
injected.statusPath = path;
const result = await reapSupersededBranches(repo, 'main', [{
branch, tip, worktreePath: path, dirtyPaths: ['unfinished.txt'],
verdict: { branch, tip, verdict: 'SUPERSEDED', dirtyPaths: ['unfinished.txt'] },
}], { cosDir: join(scratch, 'cos') });
expect(result.reaped).toEqual([]);
expect(result.skipped).toContainEqual({ branch, reason: 'worktree-status-unavailable' });
expect(existsSync(join(path, 'unfinished.txt'))).toBe(true);
expect(await branches()).toContain(branch);
});
it('checks current owners when direct cleanup receives only a previously merged ref', async () => {
const branch = 'fix/newly-reserved';
await execGit(['branch', branch, 'main'], repo);
injected.owners = [{ id: 'coordinator', status: 'running', metadata: {
sourceWorkspace: repo, claimBranches: [branch],
} }];
const result = await cleanupMerged(repo, 'main', [{ branch, upstreamGone: true }]);
expect(result.cleaned).toEqual([]);
expect(result.skipped).toEqual([{ branch, reason: 'claim-owner-active' }]);
expect(await branches()).toContain(branch);
});
it('refreshes a stale empty ownership snapshot before retiring a newly claimed branch', async () => {
const branch = 'fix/stale-owner-snapshot';
const path = await addTree(join(repo, '.claude', 'worktrees', 'snapshot'), branch);
injected.owners = [{ id: 'new-owner', status: 'running', metadata: {
sourceWorkspace: repo, claimBranches: [branch],
} }];
const result = await cleanupMerged(repo, 'main', [{ branch, upstreamGone: true }], { claimOwners: { agents: [] } });
expect(result.cleaned).toEqual([]);
expect(result.skipped).toEqual([{ branch, reason: 'claim-owner-active' }]);
expect(existsSync(path)).toBe(true);
expect(await branches()).toContain(branch);
});
it('never uses an old manual claim age or empty snapshot as completion proof', async () => {
const branch = 'claim/issue-55';
const path = await addTree(join(repo, '.claude', 'worktrees', 'claim-issue-55'), branch, { ageMs: 30 * DAY });
// Match gatherBranchState's Git-reported spelling, including Windows
// separators and expanded short paths, so this reaches the policy gate.
const worktreePath = (await execGit(['rev-parse', '--show-toplevel'], path)).stdout.trim();
const entry = { branch, worktreePath, worktreeAgeMs: 30 * DAY, upstreamGone: true };
for (const claimOwners of [{ agents: [] }, { agents: null }, null]) {
const result = await cleanupMerged(repo, 'main', [entry], { claimOwners });
expect(result.cleaned).toEqual([]);
expect(result.skipped).toContainEqual(expect.objectContaining({ branch,
reason: claimOwners?.agents ? 'claim-completion-unverified' : 'claim-ownership-unreadable' }));
expect(existsSync(path)).toBe(true);
expect(await branches()).toContain(branch);
}
});
it('holds a branch queued for the pending-merge coordinator instead of dispatching its open PR, and fails closed when the queue is unreadable', async () => {
const branch = 'claim/issue-1';
await execGit(['checkout', '-q', '-b', branch], repo);
await writeFile(join(repo, 'queued.txt'), 'queued work\n');
await execGit(['add', 'queued.txt'], repo);
await execGit(['commit', '-m', 'feat: queued work'], repo);
await execGit(['checkout', '-q', 'main'], repo);
const base = { defaultBranch: 'main', activeAgentIds: new Set(), claimOwners: { agents: [], readAgents: async () => [] } };
// No origin means no forge read, so the PR the coordinator owns is supplied
// on the gathered entry the way the forge listing would.
const stateFor = async (pendingMergeBranches) => {
const entry = (await gatherBranchState(repo, { ...base, pendingMergeBranches })).find(i => i.branch === branch);
return classifyBranches([{ ...entry, hasOrigin: true, openPr: { number: 1, mergeable: 'MERGEABLE' } }])[0];
};
expect(await stateFor(undefined)).toMatchObject({ state: 'IN_REVIEW' });
expect(await stateFor(new Set())).toMatchObject({ state: 'IN_REVIEW' });
expect(await stateFor(new Set([branch]))).toMatchObject({ state: 'WIP', liveOwnerReason: 'pending-merge-queued' });
expect(await stateFor(null)).toMatchObject({ state: 'WIP', liveOwnerReason: 'pending-merge-unavailable' });
});
it('refreshes a completion handoff before direct retirement and after a Git refusal', async () => {
const ref = 'fix/policy-held-ref';
const checkedOut = 'fix/policy-held-tree';
await execGit(['branch', ref, 'main'], repo);
const path = await addTree(join(repo, '.claude', 'worktrees', 'policy-held'), checkedOut);
const hold = branch => ({ id: `completed-${branch.replaceAll('/', '-')}`, status: 'completed', metadata: {
sourceWorkspace: repo, worktreeBranch: branch, prCompletionPolicy: 'leave-open',
} });
injected.policies = [hold(ref)];
const direct = await cleanupMerged(repo, 'main', [{ branch: ref, upstreamGone: true }]);
expect(direct.cleaned).toEqual([]);
expect(direct.skipped).toEqual([{ branch: ref, reason: 'pr-completion-human-handoff' }]);
injected.beforeRemove = async () => { injected.policies.push(hold(checkedOut)); };
const result = await reconcile(repo);
expect(result.cleaned).not.toContain(checkedOut);
expect(result.wip).toContainEqual(expect.objectContaining({ branch: checkedOut, completionPolicyReason: 'pr-completion-human-handoff' }));
expect(existsSync(path)).toBe(true);
expect(await branches()).toEqual(expect.arrayContaining([ref, checkedOut]));
});
it('protects registered branch owners and coordinator reservations during the early reap', async () => {
const root = join(repo, '.claude', 'worktrees');
const owned = await addTree(join(root, 'owned'), 'claim/issue-32');
const reserved = await addTree(join(root, 'reserved'), 'next/issue-33');
injected.owners = [
{ id: 'agent-owner', status: 'paused', sourceWorkspace: repo, workspacePath: repo, metadata: { claimBranch: 'claim/issue-32' } },
{ id: 'agent-coordinator', status: 'running', sourceWorkspace: repo, workspacePath: repo, metadata: { claimBranches: ['next/issue-33'] } },
];
const result = await reconcile(repo, { activeAgentIds: new Set(), claimOwners: { agents: injected.owners, readAgents: async () => injected.owners } });
expect(result.cleaned).toEqual([]);
for (const path of [owned, reserved]) expect(existsSync(path)).toBe(true);
expect(result.skipped.map(row => row.reason)).toEqual(['claim-owner-active', 'claim-owner-active']);
});
it.each(['owner', 'lock', 'status failure'])('preserves a tree when a new %s appears before the early reaper fallback', async (change) => {
const path = await addTree(join(repo, '.claude', 'worktrees', 'fallback'), 'fix/fallback');
const owners = { agents: [], readAgents: async () => injected.owners };
injected.beforeRemove = async () => {
if (change === 'lock') await execGit(['worktree', 'lock', path], repo);
else if (change === 'status failure') injected.statusPath = path;
else injected.owners = [{ id: 'agent-new-owner', status: 'running', workspacePath: path }];
};
const result = await reconcile(repo, { activeAgentIds: new Set(), claimOwners: owners });
expect(result.cleaned).toEqual([]);
expect(existsSync(path)).toBe(true);
expect(await branches()).toContain('fix/fallback');
const registration = (await execGit(['worktree', 'list', '--porcelain'], repo)).stdout;
expect(registration.split(/\r?\n/)).toContain(`worktree ${path.replaceAll('\\', '/')}`);
if (change === 'lock') expect(registration).toContain('locked');
expect(result.skipped).toContainEqual(expect.objectContaining({ branch: 'fix/fallback', reason: change === 'lock' ? 'worktree-locked' : change === 'status failure' ? 'worktree-status-unavailable' : 'claim-owner-active' }));
});
it('fails closed on an unreadable registry or unknown owner status at the operator cleanup boundary', async () => {
const path = await addTree(join(external, 'unknown-owner'), 'fix/unknown-owner');
await addOrigin();
for (const owners of [null, [{ id: 'agent-unknown', status: 'unknown', workspacePath: path }]]) {
injected.owners = owners;
const result = await deleteMergedBranches(repo, { activeAgentIds: new Set() });
expect(result.deleted).toEqual([]);
expect(result.skipped.some(reason => reason.includes('claim-ownership-unreadable'))).toBe(true);
expect(existsSync(path)).toBe(true);
expect(await branches()).toContain('fix/unknown-owner');
}
});
it('preserves an unreadable detached tree and still retires a clean detached peer', async () => {
const root = join(repo, '.claude', 'worktrees');
const unreadable = join(root, 'unreadable-detached');
const clean = join(root, 'clean-detached');
await execGit(['worktree', 'add', '--detach', unreadable, 'main'], repo);
await execGit(['worktree', 'add', '--detach', clean, 'main'], repo);
await writeFile(join(unreadable, 'unfinished.txt'), 'preserve\n');
injected.statusPath = unreadable;
const result = await reconcile(repo, { activeAgentIds: new Set(), claimOwners: { agents: [], readAgents: async () => [] } });
expect(result.detachedWorktrees).toContainEqual(expect.objectContaining({ path: unreadable.replaceAll('\\', '/'), reason: 'worktree-status-unavailable' }));
expect(existsSync(join(unreadable, 'unfinished.txt'))).toBe(true);
expect(existsSync(clean)).toBe(false);
expect(result.cleaned).toContain(clean.replaceAll('\\', '/'));
});
it('preserves a prunable checkout whose missing pointer makes Git report the parent clean', async () => {
await appendFile(join(repo, '.git', 'info', 'exclude'), '\n.claude/\n');
const path = await addTree(join(repo, '.claude', 'worktrees', 'broken'), 'fix/broken');
await writeFile(join(path, 'unique.txt'), 'uncommitted work\n');
await unlink(join(path, '.git'));
expect((await execGit(['status', '--porcelain'], path)).stdout).toBe('');
expect((await execGit(['worktree', 'list', '--porcelain'], repo)).stdout).toContain('prunable');
const result = await reconcile(repo, { activeAgentIds: new Set() });
expect(result.cleaned).toEqual([]);
expect(result.skipped).toContainEqual(expect.objectContaining({ branch: 'fix/broken', reason: 'worktree-status-unavailable' }));
expect(existsSync(join(path, 'unique.txt'))).toBe(true);
expect(await branches()).toContain('fix/broken');
});
});