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
/**
* Tests for agentWorkspacePrep — the workspace-path + worktree/JIRA
* provisioning extracted out of spawnAgentForTask.
*
* The contract these pin: the function returns a discriminated outcome
* ('ready' | 'deferred' | 'blocked') so spawnAgentForTask can fire
* cleanupOnError + the matching agent:deferred / agent:error event at the
* call site (where the spawn-local dedup guard / lane / execution state
* lives). A read-only task takes the fast path — no git pull, no worktree.
*/
import { describe, it, expect, beforeEach, vi } from 'vitest';
const recoveryCheck = vi.hoisted(() => vi.fn(async () => null));
const pendingGuardCheck = vi.hoisted(() => vi.fn(async () => null));
vi.mock('./pendingMergeRecovery.js', () => ({ validatePendingMergeRecovery: (...args) => pendingGuardCheck(...args) }));
vi.mock('./cos.js', () => ({}));
vi.mock('./cosMergeHandoff.js', () => ({ validateCleanupReviewTarget: (...args) => recoveryCheck(...args) }));
const publication = vi.hoisted(() => ({ active: false, refuse: false }));
vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: vi.fn(async (_repo, work) => {
if (publication.refuse) throw new Error('checkout-retirement-reserved');
publication.active = true;
try { return await work(); } finally { publication.active = false; }
}) }));
vi.mock('./cosEvents.js', () => ({ emitLog: vi.fn() }));
vi.mock('../lib/execGit.js', () => ({
execGit: vi.fn().mockImplementation(async args => ({ stdout: args.includes('--is-inside-work-tree') ? 'true' : '', stderr: '', exitCode: 0 })),
}));
vi.mock('./cosTaskStore.js', () => ({
updateTask: vi.fn().mockResolvedValue({}),
addTask: vi.fn().mockResolvedValue({}),
}));
vi.mock('./cosAgentLifecycle.js', () => ({
getAgents: vi.fn().mockResolvedValue([]),
}));
vi.mock('./apps.js', () => ({ getAppById: vi.fn().mockResolvedValue(null) }));
vi.mock('./git.js', () => ({
ensureLatest: vi.fn(),
isRepo: vi.fn().mockResolvedValue(true),
notGitRepoMessage: (name) => `${name} is not a git repository — run \`git init\``,
fetchOrigin: vi.fn().mockResolvedValue(undefined),
getRepoBranches: vi.fn().mockResolvedValue({ baseBranch: 'main' }),
checkout: vi.fn().mockResolvedValue(undefined),
createBranch: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('./taskConflict.js', () => ({ detectConflicts: vi.fn().mockResolvedValue({ recommendation: 'proceed' }) }));
// `isBranchCheckedOutElsewhereError` is imported from the REAL module: it is a
// pure predicate over git's own wording, and re-stating that regex in the mock
// would make every branch-busy assertion below agree with a copy of the code
// instead of with the code.
vi.mock('../lib/claimContinuation.js', async (importOriginal) => {
const actual = await importOriginal();
return {
...actual,
claimContinuationWorkspace: vi.fn((...args) => actual.claimContinuationWorkspace(...args)),
};
});
vi.mock('./worktreeManager.js', async (importOriginal) => ({
...(await importOriginal()),
createWorktree: vi.fn(),
adoptWorktree: vi.fn(),
unlinkWorktreeDependencies: vi.fn().mockResolvedValue(undefined),
findAdoptableWorktreeForBranch: vi.fn().mockResolvedValue(null),
releaseIdleSiblingNextHolder: vi.fn().mockResolvedValue(null),
releaseOwnerlessForeignHolder: vi.fn().mockResolvedValue(null),
listWorktrees: vi.fn().mockResolvedValue([]),
mergeBaseIntoFeatureWorktree: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('./agentAppWorkspace.js', () => ({
getAppWorkspace: vi.fn().mockResolvedValue('/repos/app-x'),
getAppDataForTask: vi.fn().mockResolvedValue(null),
}));
vi.mock('./promptSections/appContext.js', () => ({
createJiraTicketForTask: vi.fn(),
}));
vi.mock('../lib/fileUtils.js', async (importOriginal) => {
const actual = await importOriginal();
return {
...actual,
ensureDir: vi.fn().mockResolvedValue(undefined),
};
});
const handBackPrRemediationMock = vi.fn().mockResolvedValue(true);
vi.mock('./prRemediationFollowUp.js', () => ({ handBackPrRemediation: (...args) => handBackPrRemediationMock(...args) }));
vi.mock('./deepAudit.js', () => ({ getDeepAuditSourceRevision: vi.fn().mockResolvedValue('a'.repeat(40)) }));
vi.mock('./featureAgents.js', () => ({ getFeatureAgent: vi.fn().mockResolvedValue(null) }));
vi.mock('fs', async (importOriginal) => {
const actual = await importOriginal();
return { ...actual, existsSync: vi.fn(actual.existsSync) };
});
import { prepareAgentWorkspace, resolveTaskExistingBranch } from './agentWorkspacePrep.js';
import { claimContinuationWorkspace } from '../lib/claimContinuation.js';
import { updateTask, addTask } from './cosTaskStore.js';
import { getAgents } from './cosAgentLifecycle.js';
import { emitLog } from './cosEvents.js';
import { ensureLatest, isRepo, fetchOrigin, createBranch } from './git.js';
import { getAppDataForTask } from './agentAppWorkspace.js';
import { createJiraTicketForTask } from './promptSections/appContext.js';
import { getFeatureAgent } from './featureAgents.js';
import { existsSync } from 'fs';
import { join } from 'path';
import { execGit } from '../lib/execGit.js';
import { detectConflicts } from './taskConflict.js';
import { getAppWorkspace } from './agentAppWorkspace.js';
import { PINNED_HEAD_MOVED, createWorktree, adoptWorktree, findAdoptableWorktreeForBranch, listWorktrees, mergeBaseIntoFeatureWorktree, releaseIdleSiblingNextHolder, releaseOwnerlessForeignHolder, unlinkWorktreeDependencies } from './worktreeManager.js';
import { ensureDir, PATHS } from '../lib/fileUtils.js';
import { creativeDirectorScratchCwd } from '../lib/spawnCwd.js';
beforeEach(() => { vi.clearAllMocks(); recoveryCheck.mockReset().mockResolvedValue(null); pendingGuardCheck.mockReset().mockResolvedValue(null); listWorktrees.mockResolvedValue([]); publication.active = publication.refuse = false; });
describe('prepareAgentWorkspace — Creative Director scratch cwd (#4650)', () => {
it('pins a CD no-worktree task to an isolated scratch dir and skips the git pull', async () => {
const task = {
id: 't-cd',
taskType: 'internal',
metadata: { creativeDirector: { projectId: 'p', kind: 'plan' }, useWorktree: false },
};
const r = await prepareAgentWorkspace({ agentId: 'agent-cd', task });
expect(r.outcome).toBe('ready');
expect(r.workspacePath).toBe(creativeDirectorScratchCwd('agent-cd'));
expect(r.workspacePath).not.toBe(PATHS.root);
expect(r.worktreeInfo).toBeNull();
expect(ensureDir).toHaveBeenCalledWith(r.workspacePath);
expect(execGit).toHaveBeenCalledWith(['init'], r.workspacePath);
expect(ensureLatest).not.toHaveBeenCalled();
expect(createWorktree).not.toHaveBeenCalled();
expect(detectConflicts).not.toHaveBeenCalled();
});
it('leaves a CD task that explicitly asked for a worktree on the normal path', async () => {
ensureLatest.mockResolvedValue({ success: true, upToDate: true });
createWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-cd-wt', branchName: 'cos/t-cd/agent-cd-wt', baseBranch: 'main',
});
const task = {
id: 't-cd-wt',
taskType: 'internal',
metadata: { creativeDirector: { projectId: 'p', kind: 'plan' }, useWorktree: true },
};
const r = await prepareAgentWorkspace({ agentId: 'agent-cd-wt', task });
expect(r.outcome).toBe('ready');
expect(r.workspacePath).toBe('/mock/worktrees/agent-cd-wt');
expect(ensureLatest).not.toHaveBeenCalled();
expect(createWorktree).toHaveBeenCalled();
});
});
describe('prepareAgentWorkspace', () => {
it('provisions a Deep replacement from its server-owned source pin', async () => {
createWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/agent-deep', branchName: 'cos/deep', baseBranch: 'main' });
const task = { id: 'deep', taskType: 'internal', metadata: { useWorktree: true, auditDepth: 'deep' } };
expect(await prepareAgentWorkspace({ agentId: 'agent-deep', task })).toMatchObject({ outcome: 'ready' });
expect(createWorktree).toHaveBeenCalledWith('agent-deep', expect.any(String), 'deep', expect.objectContaining({ baseCommit: 'a'.repeat(40) }));
});
it('provisions extended Deep from the ordinary source without reading old coverage pins', async () => {
const { getDeepAuditSourceRevision } = await import('./deepAudit.js');
getDeepAuditSourceRevision.mockClear();
createWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/extended', branchName: 'cos/extended', baseBranch: 'main' });
const task = { id: 'extended', taskType: 'internal', metadata: { useWorktree: true, auditDepth: 'deep', auditWorkflow: 'extended-v1' } };
expect(await prepareAgentWorkspace({ agentId: 'agent-extended', task })).toMatchObject({ outcome: 'ready' });
expect(getDeepAuditSourceRevision).not.toHaveBeenCalled();
expect(createWorktree.mock.calls[0][3]).not.toHaveProperty('baseCommit');
expect(createWorktree).toHaveBeenCalledWith('agent-extended', expect.any(String), 'extended', expect.objectContaining({ baseBranch: 'main' }));
});
it('normalizes legacy investigations into isolated PR delivery', async () => {
ensureLatest.mockResolvedValue({ success: true, upToDate: true });
createWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-investigation',
branchName: 'cos/sys-investigation/agent-investigation',
baseBranch: 'main',
});
const task = {
id: 'sys-investigation',
taskType: 'internal',
description: '[Auto] Investigate agent failure: legacy task',
metadata: {},
};
const r = await prepareAgentWorkspace({ agentId: 'agent-investigation', task });
expect(task.metadata).toMatchObject({
useWorktree: true,
openPR: true,
prCompletion: 'merge-on-green',
});
expect(r.outcome).toBe('ready');
expect(r.explicitWorktree).toBe(true);
expect(ensureLatest).not.toHaveBeenCalled();
expect(createWorktree).toHaveBeenCalled();
});
describe('worktree isolation flags', () => {
const run = async (metadata) => {
ensureLatest.mockResolvedValue({ success: true, upToDate: true });
createWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/agent-flags', branchName: 'cos/t-flags/agent-flags', baseBranch: 'main' });
return prepareAgentWorkspace({ agentId: 'agent-flags', task: { id: 't-flags', taskType: 'user', metadata } });
};
it('openPR alone implies an isolated worktree and never pulls the shared checkout', async () => {
const r = await run({ openPR: true });
expect(r.explicitWorktree).toBe(true);
expect(createWorktree).toHaveBeenCalled();
expect(ensureLatest).not.toHaveBeenCalled();
});
it('useWorktree alone isolates without implying a PR', async () => {
const r = await run({ useWorktree: 'true' });
expect(r.explicitWorktree).toBe(true);
expect(createWorktree).toHaveBeenCalled();
expect(ensureLatest).not.toHaveBeenCalled();
});
it('neither flag runs in the shared checkout after pulling it', async () => {
const r = await run({});
expect(r.explicitWorktree).toBe(false);
expect(createWorktree).not.toHaveBeenCalled();
expect(ensureLatest).toHaveBeenCalled();
});
});
it('read-only task: returns ready with the shared workspace and skips the git pull', async () => {
const task = { id: 't-ro', taskType: 'user', metadata: { readOnly: true } };
const r = await prepareAgentWorkspace({ agentId: 'agent-ro', task });
expect(r.outcome).toBe('ready');
expect(r.worktreeInfo).toBeNull();
expect(r.jiraBranchName).toBeNull();
expect(r.explicitWorktree).toBe(false);
expect(ensureLatest).not.toHaveBeenCalled();
});
it('read-only task with explicit isolation gets a disposable worktree', async () => {
createWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-ro-isolated',
branchName: 'cos/t-ro-isolated/agent-ro-isolated',
baseBranch: 'main',
});
const task = {
id: 't-ro-isolated', taskType: 'internal',
metadata: { readOnly: true, useWorktree: true },
};
const r = await prepareAgentWorkspace({ agentId: 'agent-ro-isolated', task });
expect(r.outcome).toBe('ready');
expect(r.workspacePath).toBe('/mock/worktrees/agent-ro-isolated');
expect(r.worktreeInfo).toEqual(expect.objectContaining({
worktreePath: '/mock/worktrees/agent-ro-isolated',
}));
expect(createWorktree).toHaveBeenCalledWith('agent-ro-isolated', expect.any(String), 't-ro-isolated', expect.objectContaining({
baseBranch: 'main',
}));
expect(ensureLatest).not.toHaveBeenCalled();
expect(detectConflicts).not.toHaveBeenCalled();
});
it('does not link source dependencies into dependency-update worktrees', async () => {
createWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-deps',
branchName: 'cos/t-deps/agent-deps',
baseBranch: 'main',
});
const task = {
id: 't-deps', taskType: 'internal',
metadata: { analysisType: 'dependency-updates', useWorktree: true },
};
const r = await prepareAgentWorkspace({ agentId: 'agent-deps', task });
expect(r.outcome).toBe('ready');
expect(createWorktree).toHaveBeenCalledWith('agent-deps', expect.any(String), 't-deps', expect.objectContaining({
linkDependencies: false,
}));
});
it('blocks a read-only task when its required worktree cannot be created', async () => {
createWorktree.mockResolvedValue(null);
const task = {
id: 't-ro-blocked', taskType: 'internal',
metadata: { readOnly: true, useWorktree: true },
};
const r = await prepareAgentWorkspace({ agentId: 'agent-ro-blocked', task });
expect(r.outcome).toBe('blocked');
expect(r.reason).toContain('isolation was required');
expect(updateTask).toHaveBeenCalledWith('t-ro-blocked', expect.objectContaining({
status: 'blocked',
metadata: expect.objectContaining({ blockedCategory: 'worktree-failed' }),
}), 'internal');
});
it('blocks a worktree task for a non-git app up front, without attempting a fetch', async () => {
isRepo.mockResolvedValueOnce(false);
getAppWorkspace.mockResolvedValue(process.cwd());
const task = { id: 't-nogit', taskType: 'internal', metadata: { readOnly: true, useWorktree: true, app: 'Example App' } };
const r = await prepareAgentWorkspace({ agentId: 'agent-nogit', task });
expect(r.outcome).toBe('blocked');
expect(r.reason).toContain('Example App is not a git repository');
expect(createWorktree).not.toHaveBeenCalled();
expect(fetchOrigin).not.toHaveBeenCalled();
expect(updateTask).toHaveBeenCalledWith('t-nogit', expect.objectContaining({
status: 'blocked',
metadata: expect.objectContaining({ blockedCategory: 'worktree-failed' }),
}), 'internal');
});
it('plan-only task: keeps the no-worktree path even with delivery flags present', async () => {
const task = {
id: 't-plan-only',
taskType: 'user',
metadata: {
planOnly: true,
readOnly: true,
noCodeOutput: true,
useWorktree: false,
openPR: false,
simplify: false,
},
};
const r = await prepareAgentWorkspace({ agentId: 'agent-plan-only', task });
expect(r.outcome).toBe('ready');
expect(r.worktreeInfo).toBeNull();
expect(r.explicitWorktree).toBe(false);
expect(ensureLatest).not.toHaveBeenCalled();
expect(createWorktree).not.toHaveBeenCalled();
});
it('defers when the pre-task git pull hits an unresolvable conflict', async () => {
ensureLatest.mockResolvedValue({ conflict: true, branch: 'feature/x', error: 'rebase failed' });
const task = { id: 't-conflict', taskType: 'user', metadata: {} };
const r = await prepareAgentWorkspace({ agentId: 'agent-c', task });
expect(r.outcome).toBe('deferred');
expect(r.deferReason).toBe('git-conflict');
expect(r.branch).toBe('feature/x');
// A timed pause, not `pending` — pending was re-dequeued every few seconds.
const [, patch] = updateTask.mock.calls.find(([id]) => id === 't-conflict');
expect(patch.status).toBe('blocked');
expect(patch.metadata.blockedCategory).toBe('git-conflict-wait');
expect(Date.parse(patch.metadata.cooldownUntil)).toBeGreaterThan(Date.now());
expect(addTask.mock.calls[0][0].metadata).toEqual({ gitConflictResolution: true });
});
it('lets the conflict-resolver task skip the pull it exists to fix', async () => {
ensureLatest.mockResolvedValue({ conflict: true, branch: 'main', error: 'rebase failed' });
const task = { id: 't-resolver', taskType: 'internal', metadata: { gitConflictResolution: true } };
const r = await prepareAgentWorkspace({ agentId: 'agent-r', task });
expect(r.outcome).toBe('ready');
expect(ensureLatest).not.toHaveBeenCalled();
});
it('proceeds in the shared workspace when the pull is clean and no conflict is detected', async () => {
ensureLatest.mockResolvedValue({ success: true, upToDate: true });
const task = { id: 't-clean', taskType: 'user', metadata: {} };
const r = await prepareAgentWorkspace({ agentId: 'agent-clean', task });
expect(r.outcome).toBe('ready');
expect(r.worktreeInfo).toBeNull();
expect(detectConflicts).toHaveBeenCalled();
});
describe('a shared-checkout task the conflict scan isolates', () => {
const task = () => ({ id: 't-busy', taskType: 'user', metadata: {} });
beforeEach(() => {
ensureLatest.mockResolvedValue({ success: true, upToDate: true });
detectConflicts.mockResolvedValueOnce({ hasConflict: true, recommendation: 'worktree', reason: 'workspace-has-uncommitted-changes' });
});
it('cuts a worktree when another agent is already working in the checkout', async () => {
createWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/agent-busy', branchName: 'cos/t-busy/agent-busy', baseBranch: 'main' });
const r = await prepareAgentWorkspace({ agentId: 'agent-busy', task: task() });
expect(r).toMatchObject({ outcome: 'ready', workspacePath: '/mock/worktrees/agent-busy', explicitWorktree: false });
expect(r.worktreeInfo.branchName).toBe('cos/t-busy/agent-busy');
});
it('stays in the shared checkout when that worktree cannot be created', async () => {
createWorktree.mockRejectedValue(new Error('disk full'));
const r = await prepareAgentWorkspace({ agentId: 'agent-busy', task: task() });
expect(r).toMatchObject({ outcome: 'ready', worktreeInfo: null, workspacePath: PATHS.root });
});
});
describe('a JIRA-enabled app', () => {
const jiraTask = () => ({ id: 't-jira', taskType: 'user', description: 'Fix the Widget!', metadata: { app: 'app-x', createJiraTicket: true } });
beforeEach(() => {
getAppWorkspace.mockResolvedValue(process.cwd());
ensureLatest.mockResolvedValue({ success: true, upToDate: true });
getAppDataForTask.mockResolvedValueOnce({ jira: { enabled: true, instanceId: 'jira-1', createPR: false } });
createJiraTicketForTask.mockResolvedValueOnce({ ticketId: 'EX-7', ticketUrl: 'https://jira.example.com/browse/EX-7' });
});
it('creates the ticket and its feature branch in the app checkout instead of a worktree', async () => {
const task = jiraTask();
const r = await prepareAgentWorkspace({ agentId: 'agent-jira', task });
expect(r).toMatchObject({ outcome: 'ready', jiraBranchName: 'feature/EX-7-fix-the-widget', worktreeInfo: null });
expect(r.jiraTicket.ticketId).toBe('EX-7');
expect(createBranch).toHaveBeenCalledWith(process.cwd(), 'feature/EX-7-fix-the-widget');
expect(task.metadata).toMatchObject({
jiraTicketId: 'EX-7', jiraBranch: 'feature/EX-7-fix-the-widget', jiraInstanceId: 'jira-1', jiraCreatePR: false,
});
expect(detectConflicts).not.toHaveBeenCalled();
expect(createWorktree).not.toHaveBeenCalled();
});
it('keeps the ticket but falls back to the ordinary shared-checkout path when the branch cannot be created', async () => {
createBranch.mockRejectedValueOnce(new Error('branch exists'));
const task = jiraTask();
const r = await prepareAgentWorkspace({ agentId: 'agent-jira', task });
expect(r).toMatchObject({ outcome: 'ready', jiraBranchName: null });
expect(r.jiraTicket.ticketId).toBe('EX-7');
expect(task.metadata).toMatchObject({ jiraTicketId: 'EX-7', jiraBranch: null });
expect(detectConflicts).toHaveBeenCalled();
});
});
it('runs a feature-agent task in its persistent worktree and merges its base first', async () => {
ensureLatest.mockResolvedValue({ success: true, upToDate: true });
getFeatureAgent.mockResolvedValueOnce({ id: 'fa-1', name: 'Example Agent', git: { branchName: 'feature/fa-1', baseBranch: 'dev', autoMergeBase: true } });
const faWorktree = join(PATHS.cos, 'feature-agents', 'fa-1', 'worktree');
const realExistsSync = existsSync.getMockImplementation();
existsSync.mockImplementation(path => path === faWorktree || realExistsSync(path));
const task = { id: 't-fa', taskType: 'internal', metadata: { featureAgentRun: true, featureAgentId: 'fa-1' } };
const r = await prepareAgentWorkspace({ agentId: 'agent-fa', task })
.finally(() => existsSync.mockImplementation(realExistsSync));
expect(r).toMatchObject({ outcome: 'ready', workspacePath: faWorktree });
expect(r.worktreeInfo).toEqual({ worktreePath: faWorktree, branchName: 'feature/fa-1', baseBranch: 'dev', isPersistentWorktree: true });
expect(mergeBaseIntoFeatureWorktree).toHaveBeenCalledWith('fa-1', 'dev');
expect(createWorktree).not.toHaveBeenCalled();
});
});
describe('prepareAgentWorkspace — workspace validation (#3180)', () => {
// Both shapes used to fall through to the PortOS root, so the agent did its
// work in the PortOS checkout instead of the user's app. A blocked task the
// user can fix beats a wrong-repo commit they have to discover later.
it('blocks when the task names an app that resolves to no repo path', async () => {
getAppWorkspace.mockResolvedValue(null);
const task = { id: 't-no-path', taskType: 'user', metadata: { app: 'primes' } };
const r = await prepareAgentWorkspace({ agentId: 'agent-np', task });
expect(r.outcome).toBe('blocked');
expect(r.reason).toContain('primes');
expect(r.reason).toContain('Repository Path');
});
it('blocks when the resolved workspace does not exist on disk', async () => {
getAppWorkspace.mockResolvedValue('/definitely/not/a/real/repo/path');
const task = { id: 't-missing', taskType: 'user', metadata: { app: 'primes' } };
const r = await prepareAgentWorkspace({ agentId: 'agent-ms', task });
expect(r.outcome).toBe('blocked');
expect(r.reason).toContain('/definitely/not/a/real/repo/path');
});
it('blocks when the resolved workspace is a file, not a directory', async () => {
const { mkdtempSync, rmSync, writeFileSync } = await import('fs');
const { tmpdir } = await import('os');
const { join } = await import('path');
const root = mkdtempSync(join(tmpdir(), 'prep-'));
try {
const file = join(root, 'a-file.txt');
writeFileSync(file, 'x');
getAppWorkspace.mockResolvedValue(file);
const task = { id: 't-file', taskType: 'user', metadata: { app: 'primes' } };
const r = await prepareAgentWorkspace({ agentId: 'agent-f', task });
expect(r.outcome).toBe('blocked');
expect(r.reason).toContain('not a directory');
} finally {
rmSync(root, { recursive: true, force: true });
}
});
// The repoPath field accepts a literal '~/...' — the CoS path must expand it
// the same way the /runs path does, or every task for that app is blocked.
it('expands a ~ repoPath instead of blocking it', async () => {
const { homedir } = await import('os');
getAppWorkspace.mockResolvedValue('~');
const task = { id: 't-tilde', taskType: 'user', metadata: { app: 'primes', readOnly: true } };
const r = await prepareAgentWorkspace({ agentId: 'agent-t', task });
expect(r.outcome).toBe('ready');
expect(r.workspacePath).toBe(homedir());
});
it('proceeds when the app resolves to a real directory', async () => {
getAppWorkspace.mockResolvedValue(process.cwd());
const task = { id: 't-ok', taskType: 'user', metadata: { app: 'primes', readOnly: true } };
const r = await prepareAgentWorkspace({ agentId: 'agent-ok', task });
expect(r.outcome).toBe('ready');
expect(r.workspacePath).toBe(process.cwd());
});
// Returning `blocked` without persisting it left the task `pending`, so the
// scheduler re-dequeued it every tick and re-logged the same ❌ forever — the
// instruction ("set it in Apps") only ever reachable from that log.
it('parks the task as blocked so it stops being re-dequeued every tick', async () => {
getAppWorkspace.mockResolvedValue(null);
const task = { id: 't-park', taskType: 'user', metadata: { app: 'pipeline', context: 'keep me' } };
await prepareAgentWorkspace({ agentId: 'agent-park', task });
expect(updateTask).toHaveBeenCalledWith('t-park', expect.objectContaining({
status: 'blocked',
metadata: expect.objectContaining({
blockedCategory: 'app-unresolved',
blockedReason: expect.stringContaining('Repository Path'),
context: 'keep me',
}),
}), 'user');
});
it('parks the task as blocked when the repo path exists in Apps but not on disk', async () => {
getAppWorkspace.mockResolvedValue('/definitely/not/a/real/repo/path');
const task = { id: 't-park2', taskType: 'user', metadata: { app: 'primes' } };
await prepareAgentWorkspace({ agentId: 'agent-park2', task });
expect(updateTask).toHaveBeenCalledWith('t-park2', expect.objectContaining({
status: 'blocked',
metadata: expect.objectContaining({ blockedCategory: 'app-unresolved' }),
}), 'user');
});
});
// A run killed by a server restart never reaches its completion hook, so its
// worktree survives with UNCOMMITTED work in it. The retry must pick that tree
// up instead of building a fresh one off the default branch and redoing it.
describe('prepareAgentWorkspace — resuming an interrupted run', () => {
const DEAD_TREE = '/mock/worktrees/agent-dead';
const resumeTask = (extra = {}) => ({
id: 't-resume', taskType: 'user',
metadata: {
useWorktree: true,
existingBranch: 'cos/t-resume/agent-dead',
resumedFromAgentId: 'agent-dead',
resumeWorktreePath: DEAD_TREE,
...extra
}
});
beforeEach(() => {
ensureLatest.mockResolvedValue({ success: true, upToDate: true });
getAgents.mockResolvedValue([]);
findAdoptableWorktreeForBranch.mockResolvedValue(null);
});
it('recovers the namespaced fork holder without adopting the base repository main checkout', async () => {
findAdoptableWorktreeForBranch.mockResolvedValue({ path: DEAD_TREE, agentId: 'agent-dead' });
adoptWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/agent-new', branchName: 'fork/contributor/main', adopted: true });
const task = resumeTask({ existingBranch: 'fork/contributor/main',
forkHead: { remoteUrl: 'https://github.com/contributor/example.git', ownerLogin: 'contributor' } });
const result = await prepareAgentWorkspace({ agentId: 'agent-new', task });
expect(result.outcome).toBe('ready');
expect(findAdoptableWorktreeForBranch).toHaveBeenCalledWith(expect.any(String), 'fork/contributor/main', expect.any(Object));
expect(adoptWorktree).toHaveBeenCalledWith('agent-new', expect.any(String), DEAD_TREE, 'fork/contributor/main');
expect(createWorktree).not.toHaveBeenCalled();
});
it('adopts the interrupted run’s worktree instead of creating a new one', async () => {
findAdoptableWorktreeForBranch.mockResolvedValue({ path: DEAD_TREE, agentId: 'agent-dead' });
adoptWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-new', branchName: 'cos/t-resume/agent-dead',
baseBranch: null, existingBranch: true, adopted: true
});
const r = await prepareAgentWorkspace({
agentId: 'agent-new', task: resumeTask({ analysisType: 'dependency-updates' }),
});
expect(adoptWorktree).toHaveBeenCalledWith('agent-new', expect.any(String), DEAD_TREE, 'cos/t-resume/agent-dead', { preserveLockfiles: true });
expect(unlinkWorktreeDependencies).toHaveBeenCalledWith(expect.any(String), '/mock/worktrees/agent-new');
expect(createWorktree).not.toHaveBeenCalled();
expect(r.outcome).toBe('ready');
expect(r.worktreeInfo.adopted).toBe(true);
expect(r.workspacePath).toBe('/mock/worktrees/agent-new');
});
// The tree is gone (already cleaned up) but the branch survived — attach to it,
// which is the pre-existing resume shape.
it('falls back to attaching the branch when the leftover tree is gone', async () => {
adoptWorktree.mockResolvedValue(null);
createWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-new', branchName: 'cos/t-resume/agent-dead',
baseBranch: null, existingBranch: true
});
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: resumeTask() });
expect(createWorktree).toHaveBeenCalledWith('agent-new', expect.any(String), 't-resume',
expect.objectContaining({ existingBranch: 'cos/t-resume/agent-dead' }));
expect(r.outcome).toBe('ready');
});
it('discovers and adopts the branch holder before cutting a fresh resume branch', async () => {
const stalePointer = '/mock/worktrees/agent-moved';
findAdoptableWorktreeForBranch.mockResolvedValue({ path: DEAD_TREE, agentId: 'agent-dead' });
adoptWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-new', branchName: 'cos/t-resume/agent-dead',
baseBranch: null, existingBranch: true, adopted: true
});
const r = await prepareAgentWorkspace({
agentId: 'agent-new', task: resumeTask({ resumeWorktreePath: stalePointer })
});
expect(findAdoptableWorktreeForBranch).toHaveBeenCalledWith(expect.any(String), 'cos/t-resume/agent-dead',
expect.objectContaining({ preferredPath: stalePointer }));
expect(adoptWorktree).toHaveBeenCalledWith('agent-new', expect.any(String), DEAD_TREE, 'cos/t-resume/agent-dead');
expect(createWorktree).not.toHaveBeenCalled();
expect(r.outcome).toBe('ready');
});
// The run that died may have been isolated by conflict AUTO-detection rather than
// useWorktree/openPR. Its retry must still take the worktree path — conflict
// detection returns `proceed` once the dead agent is gone, so the old gate sent
// the retry into the shared workspace and abandoned the work on disk.
it('takes the worktree path for a resume even when the task never asked for isolation', async () => {
findAdoptableWorktreeForBranch.mockResolvedValue({ path: DEAD_TREE, agentId: 'agent-dead' });
adoptWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-new', branchName: 'cos/t-resume/agent-dead',
baseBranch: null, existingBranch: true, adopted: true
});
const task = resumeTask();
delete task.metadata.useWorktree;
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task });
expect(adoptWorktree).toHaveBeenCalled();
expect(detectConflicts).not.toHaveBeenCalled();
expect(r.workspacePath).toBe('/mock/worktrees/agent-new');
});
// Blocking a task that never opted into isolation would be stricter than its own
// contract — it ran in the shared workspace before the pointer existed.
it('degrades to the shared workspace when a resume-only task cannot get a worktree', async () => {
adoptWorktree.mockResolvedValue(null);
createWorktree.mockResolvedValue(null);
const task = resumeTask();
delete task.metadata.useWorktree;
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task });
expect(r.outcome).toBe('ready');
expect(r.worktreeInfo).toBeNull();
});
// ...but a task that DID request isolation still fails closed.
it('still blocks when an explicitly-isolated resume cannot get a worktree', async () => {
adoptWorktree.mockResolvedValue(null);
createWorktree.mockResolvedValue(null);
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: resumeTask() });
expect(r.outcome).toBe('blocked');
});
describe('a relaunched claim continuing in place', () => {
const CLAIM_DIR = '/mock/worktrees/claim-portos-issue-42';
const claimTask = (extra = {}) => ({
id: 't-claim', taskType: 'user',
metadata: {
claimFlow: true,
claimTarget: '42',
claimResumeInPlace: true,
existingBranch: 'claim/issue-42',
resumedFromAgentId: 'agent-dead',
resumeWorktreePath: CLAIM_DIR,
useWorktree: false,
...extra,
},
});
const pointerWorkspace = () => ({
workspacePath: CLAIM_DIR,
worktreeInfo: {
worktreePath: CLAIM_DIR,
branchName: 'claim/issue-42',
baseBranch: null,
existingBranch: true,
adopted: true,
claimResumeInPlace: true,
},
});
const holder = { path: CLAIM_DIR, branch: 'refs/heads/claim/issue-42' };
beforeEach(() => {
claimContinuationWorkspace.mockReturnValueOnce(pointerWorkspace());
listWorktrees.mockResolvedValue([holder]);
});
it('continues inside the existing claim worktree when no other owner holds it', async () => {
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: claimTask() });
expect(r.outcome).toBe('ready');
expect(r.workspacePath).toBe(CLAIM_DIR);
expect(r.worktreeInfo.claimResumeInPlace).toBe(true);
expect(createWorktree).not.toHaveBeenCalled();
expect(adoptWorktree).not.toHaveBeenCalled();
expect(ensureLatest).not.toHaveBeenCalled();
});
it('defers the launch when a live owner registered the branch after the pointer was made', async () => {
getAgents.mockResolvedValue([
{ id: 'agent-other', status: 'running', metadata: { claimBranch: 'claim/issue-42' } },
]);
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: claimTask() });
expect(r.outcome).toBe('blocked');
expect(r.workspacePath).toBeUndefined();
expect(updateTask).toHaveBeenCalledWith('t-claim', expect.objectContaining({
status: 'blocked',
metadata: expect.objectContaining({
blockedCategory: 'worktree-busy',
worktreeBusyAttempts: 1,
existingBranch: 'claim/issue-42',
claimResumeInPlace: true,
}),
}), 'user');
expect(createWorktree).not.toHaveBeenCalled();
expect(adoptWorktree).not.toHaveBeenCalled();
});
it('defers while a live picker run in the repository might own the tree, and continues once it ends', async () => {
getAgents.mockResolvedValue([{ id: 'agent-picker', status: 'running', metadata: { claimPicksOwnBranch: true } }]);
const deferred = await prepareAgentWorkspace({ agentId: 'agent-new', task: claimTask() });
expect(deferred.outcome).toBe('blocked');
expect(createWorktree).not.toHaveBeenCalled();
getAgents.mockResolvedValue([{ id: 'agent-picker', status: 'completed', metadata: { claimPicksOwnBranch: true } }]);
claimContinuationWorkspace.mockReturnValueOnce(pointerWorkspace());
const resumed = await prepareAgentWorkspace({ agentId: 'agent-new', task: claimTask() });
expect(resumed.outcome).toBe('ready');
expect(resumed.workspacePath).toBe(CLAIM_DIR);
});
it('fails closed when the agent registry cannot be read', async () => {
getAgents.mockRejectedValue(new Error('state unreadable'));
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: claimTask() });
expect(r.outcome).toBe('blocked');
expect(updateTask).toHaveBeenCalledWith('t-claim', expect.objectContaining({
metadata: expect.objectContaining({ blockedCategory: 'worktree-busy' }),
}), 'user');
});
it('fails closed when the checkout now holds a different branch', async () => {
listWorktrees.mockResolvedValue([{ path: CLAIM_DIR, branch: 'refs/heads/claim/issue-43' }]);
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: claimTask() });
expect(r.outcome).toBe('blocked');
expect(createWorktree).not.toHaveBeenCalled();
});
it('stops waiting after the retry budget and blocks for a human instead of entering', async () => {
listWorktrees.mockResolvedValue([]);
const r = await prepareAgentWorkspace({
agentId: 'agent-new', task: claimTask({ worktreeBusyAttempts: 5 }),
});
expect(r.outcome).toBe('blocked');
expect(updateTask).toHaveBeenCalledWith('t-claim', expect.objectContaining({
metadata: expect.objectContaining({ blockedCategory: 'worktree-failed' }),
}), 'user');
expect(createWorktree).not.toHaveBeenCalled();
});
});
it('ignores a stale worktree pointer with no branch to resume', async () => {
createWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-new', branchName: 'cos/t-resume/agent-new', baseBranch: 'main'
});
await prepareAgentWorkspace({
agentId: 'agent-new', task: resumeTask({ existingBranch: undefined })
});
expect(adoptWorktree).not.toHaveBeenCalled();
expect(createWorktree).toHaveBeenCalled();
});
});
// A merge follow-up preps its worktree within a second or two of the cleanup that
// spawned it, so it can find the PR branch still checked out in the previous
// agent's tree. Blocking there orphans the pull request the follow-up exists to
// land, so the branch-busy failure is a TIMED pause instead.
describe('prepareAgentWorkspace — the branch is checked out in another worktree', () => {
const BUSY = new Error("fatal: 'cos/task-x/agent-y' is already used by worktree at '/mock/worktrees/agent-y'");
const followUpTask = (extra = {}) => ({
id: 'sys-rl-1', taskType: 'internal',
metadata: {
useWorktree: true,
reviewLoopFollowUp: true,
reviewLoopPRBranch: 'cos/task-x/agent-y',
reviewLoopPRUrl: 'https://github.com/o/r/pull/1',
...extra
}
});
beforeEach(() => {
ensureLatest.mockResolvedValue({ success: true, upToDate: true });
adoptWorktree.mockResolvedValue(null);
createWorktree.mockRejectedValue(BUSY);
getAgents.mockResolvedValue([]);
// Default: nobody adoptable holds the branch, so the pause path below is
// reached. The adoption tests opt in explicitly.
findAdoptableWorktreeForBranch.mockResolvedValue(null);
});
// The whole point of a merge follow-up's worktree is to be attached to the PR
// branch. When a tree PortOS owns already has it — the finished run's own,
// preserved because it was dirty — that tree IS the workspace being asked for,
// and no cooldown was ever going to free it.
it('keeps a changed Deep submodule workspace blocked for explicit recovery instead of retrying or creating a fresh branch', async () => {
findAdoptableWorktreeForBranch.mockResolvedValue({ path: '/mock/worktrees/agent-y', agentId: 'agent-y' });
adoptWorktree.mockRejectedValueOnce(Object.assign(new Error('Preserve retained submodule changes'), { code: 'DEEP_RESUME_PRESERVED' }));
const task = followUpTask({ auditDepth: 'deep' });
const result = await prepareAgentWorkspace({ agentId: 'agent-new', task });
expect(result.outcome).toBe('blocked');
expect(createWorktree).not.toHaveBeenCalled();
expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ metadata: expect.objectContaining({ blockedCategory: 'deep-audit-partial' }) }), expect.anything());
});
it('adopts the worktree that already holds the branch instead of pausing', async () => {
findAdoptableWorktreeForBranch.mockResolvedValue({ path: '/mock/worktrees/agent-y', agentId: 'agent-y' });
adoptWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-new', branchName: 'cos/task-x/agent-y',
baseBranch: null, existingBranch: true, adopted: true
});
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
expect(adoptWorktree).toHaveBeenCalledWith('agent-new', expect.any(String), '/mock/worktrees/agent-y', 'cos/task-x/agent-y');
expect(r.outcome).toBe('ready');
expect(r.workspacePath).toBe('/mock/worktrees/agent-new');
// Not blocked, not paused — the task never reaches updateTask at all.
expect(updateTask).not.toHaveBeenCalled();
});
// A release PR's head is the default branch, which the primary checkout holds. That
// checkout is never adopted or released; the worktree comes up detached on the first
// attempt rather than pausing on `worktree-busy` for a holder that never leaves (#12855).
it('never offers the primary checkout for adoption and starts the follow-up without a cooldown', async () => {
listWorktrees.mockResolvedValue([{ path: PATHS.root, branch: 'refs/heads/main', head: 'a'.repeat(40) }]);
const detached = { worktreePath: '/mock/worktrees/agent-new', branchName: 'main', baseBranch: null, existingBranch: true, detached: true, headIsDefaultBranch: true };
createWorktree.mockReset();
createWorktree.mockResolvedValue(detached);
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask({ reviewLoopPRBranch: 'main' }) });
expect(findAdoptableWorktreeForBranch).not.toHaveBeenCalled();
expect(adoptWorktree).not.toHaveBeenCalled();
expect(createWorktree).toHaveBeenCalledWith('agent-new', expect.any(String), 'sys-rl-1', expect.objectContaining({ existingBranch: 'main' }));
expect(r).toMatchObject({ outcome: 'ready', worktreeInfo: detached });
expect(updateTask).not.toHaveBeenCalled();
});
it('checks a recovered head before adoption and consumes only its initial-launch pin before registration', async () => {
const target = { version: 1, repoPath: PATHS.root, branch: 'cos/task-x/agent-y', headSha: 'a'.repeat(40) };
const task = followUpTask({ cleanupReviewTarget: target });
findAdoptableWorktreeForBranch.mockResolvedValue({ path: '/mock/worktrees/agent-y', agentId: 'agent-y' });
adoptWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/agent-new', branchName: target.branch, adopted: true });
const registered = vi.fn(async result => {
expect(task.metadata.cleanupReviewTarget).toBeUndefined();
expect(Object.hasOwn(task.metadata, 'cleanupReviewTarget')).toBe(true);
expect(task.metadata.cleanupReviewLaunchEvidence).toEqual(target);
return result;
});
expect((await prepareAgentWorkspace({ agentId: 'agent-new', task, onPrepared: registered })).outcome).toBe('ready');
expect(recoveryCheck.mock.calls.map(([call]) => call.workspacePath)).toEqual([PATHS.root, '/mock/worktrees/agent-y', '/mock/worktrees/agent-new']);
expect(registered).toHaveBeenCalledOnce();
// Its own later fixes are governed by the registered coordinator's normal
// continuation, not a stale initial-head pin that recursively spawns work.
recoveryCheck.mockClear();
await prepareAgentWorkspace({ agentId: 'agent-new', task });
expect(recoveryCheck).not.toHaveBeenCalled();
});
it('pins a legacy pending-merge recovery checkout and consumes the pin only before registration', async () => {
const target = { version: 1, repoPath: PATHS.root, branch: 'cos/task-x/agent-y', headSha: 'a'.repeat(40), prCompletion: 'merge-on-green' };
const task = followUpTask({ pendingMergeGuardTarget: target, prCompletion: 'merge-on-green' });
createWorktree.mockReset().mockResolvedValue({ worktreePath: '/mock/worktrees/agent-new', branchName: target.branch });
const registered = vi.fn(async result => {
expect(task.metadata.pendingMergeGuardTarget).toBeUndefined();
expect(task.metadata.pendingMergeGuardLaunchEvidence).toEqual(target);
expect(result.cleanupReviewPinConsumed).toBe(true);
return result;
});
expect((await prepareAgentWorkspace({ agentId: 'agent-new', task, onPrepared: registered })).outcome).toBe('ready');
expect(createWorktree).toHaveBeenCalledWith('agent-new', PATHS.root, task.id, expect.objectContaining({ expectedHeadSha: target.headSha }));
expect(pendingGuardCheck.mock.calls.map(([call]) => [call.workspacePath, call.requireCheckout])).toEqual([
[PATHS.root, undefined], ['/mock/worktrees/agent-new', true],
]);
expect(registered).toHaveBeenCalledOnce();
});
it('blocks a stale pending-merge target before touching its checkout', async () => {
const target = { version: 1, repoPath: PATHS.root, branch: 'cos/task-x/agent-y', headSha: 'a'.repeat(40), prCompletion: 'merge-on-green' };
const task = followUpTask({ pendingMergeGuardTarget: target, prCompletion: 'merge-on-green' });
pendingGuardCheck.mockResolvedValue('recovery-head-moved');
expect((await prepareAgentWorkspace({ agentId: 'agent-new', task })).outcome).toBe('blocked');
expect(createWorktree).not.toHaveBeenCalled();
expect(task.metadata.pendingMergeGuardTarget).toEqual(target);
});
it('verifies a retained legacy checkout before adopting it for guard recovery', async () => {
const target = { version: 1, repoPath: PATHS.root, branch: 'cos/task-x/agent-y', headSha: 'a'.repeat(40), prCompletion: 'merge-on-green' };
const task = followUpTask({ pendingMergeGuardTarget: target, prCompletion: 'merge-on-green' });
findAdoptableWorktreeForBranch.mockResolvedValue({ path: '/mock/worktrees/agent-y', agentId: 'agent-y' });
adoptWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/agent-new', branchName: target.branch, adopted: true });
expect((await prepareAgentWorkspace({ agentId: 'agent-new', task })).outcome).toBe('ready');
expect(pendingGuardCheck.mock.calls.map(([call]) => call.workspacePath)).toEqual([PATHS.root, '/mock/worktrees/agent-y', '/mock/worktrees/agent-new']);
expect(adoptWorktree).toHaveBeenCalledOnce();
expect(createWorktree).not.toHaveBeenCalled();
});
it('preserves the pin and holder when target drift is detected before adoption', async () => {
const target = { version: 1, repoPath: PATHS.root, branch: 'cos/task-x/agent-y', headSha: 'a'.repeat(40) };
const task = followUpTask({ cleanupReviewTarget: target });
findAdoptableWorktreeForBranch.mockResolvedValue({ path: '/mock/worktrees/agent-y', agentId: 'agent-y' });
recoveryCheck.mockResolvedValueOnce(null).mockResolvedValueOnce('review-head-moved');
expect((await prepareAgentWorkspace({ agentId: 'agent-new', task })).outcome).toBe('blocked');
expect(adoptWorktree).not.toHaveBeenCalled();
expect(task.metadata.cleanupReviewTarget).toEqual(target);
});
// A resolve-and-merge follow-up's whole purpose is landing THIS branch, so the
// user's own trigger is the signal to take over whatever a `/do:next` claim
// left checked out on it — instead of retrying against it until the task gives
// up and strands the PR the follow-up exists to land (#6243).
it('opts into adopting a live /claim worktree for a review-loop follow-up', async () => {
findAdoptableWorktreeForBranch.mockResolvedValue({ path: '/mock/worktrees/claim-issue-42', agentId: 'claim-issue-42' });
adoptWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-new', branchName: 'cos/task-x/agent-y',
baseBranch: null, existingBranch: true, adopted: true
});
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
const [, , opts] = findAdoptableWorktreeForBranch.mock.calls.at(-1);
expect(opts.allowLiveClaim).toBe(true);
expect(r.outcome).toBe('ready');
expect(updateTask).not.toHaveBeenCalled();
});
// A PR-remediation agent runs the PR's own tests, so it attaches only at the
// head PortOS reviewed (#12486). Adopting a surviving tree would hand it a
// checkout nothing proved is that commit, so it always attaches fresh, pinned.
describe('a PR-remediation follow-up pinned to the reviewed head', () => {
const REVIEWED = 'a'.repeat(40);
const remediationTask = (extra = {}) => ({
id: 't-remediation', taskType: 'internal',
metadata: { useWorktree: true, prRemediationFollowUp: true, existingBranch: 'contributor/fix-thing', prRemediationHeadSha: REVIEWED, ...extra },
});
it('never adopts a holder and attaches fresh at the reviewed commit', async () => {
findAdoptableWorktreeForBranch.mockResolvedValue({ path: '/mock/worktrees/claim-issue-99', agentId: 'claim-issue-99' });
createWorktree.mockResolvedValueOnce({ worktreePath: '/mock/worktrees/agent-new', branchName: 'contributor/fix-thing', baseBranch: null, existingBranch: true });
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: remediationTask() });
expect(adoptWorktree).not.toHaveBeenCalled();
expect(createWorktree).toHaveBeenCalledWith('agent-new', expect.any(String), 't-remediation',
expect.objectContaining({ existingBranch: 'contributor/fix-thing', expectedHeadSha: REVIEWED }));
expect(r.outcome).toBe('ready');
expect(handBackPrRemediationMock).not.toHaveBeenCalled();
});
it('never falls back to the shared checkout when persisted isolation flags are missing', async () => {
createWorktree.mockRejectedValueOnce(new Error('transport unavailable'));
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: remediationTask({ useWorktree: false }) });
expect(r.outcome).toBe('blocked');
expect(ensureLatest).not.toHaveBeenCalled();
});
it('blocks the task for good and hands the PR back when the head moved', async () => {
createWorktree.mockRejectedValueOnce(Object.assign(new Error('origin/contributor/fix-thing is at bbbb'), { code: PINNED_HEAD_MOVED }));
const task = remediationTask();
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task });
expect(r.outcome).toBe('blocked');
// Not `worktree-busy`: a timed pause would retry the same moved head.
expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({
status: 'blocked', metadata: expect.objectContaining({ blockedCategory: 'pr-head-moved' }),
}), expect.anything());
expect(handBackPrRemediationMock).toHaveBeenCalledWith(expect.objectContaining({ task }));
});
it.each([
{ prRemediationHeadSha: null },
{ prRemediationHeadSha: 'not-a-commit' },
{ existingBranch: null },
])('refuses incomplete remediation coordinates without touching git (%j)', async (missing) => {
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: remediationTask(missing) });
expect(r.outcome).toBe('blocked');
expect(createWorktree).not.toHaveBeenCalled();
expect(handBackPrRemediationMock).toHaveBeenCalledTimes(1);
});
});
// A `/do:next` run keeps its tree in a sibling directory outside the managed
// root, which adoption refuses. Releasing that idle holder lets the follow-up
// attach instead of pausing until its busy budget runs out.
it('releases an idle /do:next sibling holder for a review-loop follow-up, then attaches', async () => {
getAgents.mockResolvedValue([{ id: 'agent-live', status: 'running', metadata: { workspacePath: '/elsewhere/live' } }]);
releaseIdleSiblingNextHolder.mockResolvedValueOnce({ path: '/repos/next-issue-1' });
createWorktree.mockResolvedValueOnce({ worktreePath: '/mock/worktrees/agent-new', branchName: 'cos/task-x/agent-y', baseBranch: null });
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
expect(releaseIdleSiblingNextHolder).toHaveBeenCalledWith(expect.any(String), 'cos/task-x/agent-y', expect.objectContaining({ activeWorkspacePaths: ['/elsewhere/live'], agents: expect.any(Array), requestingAgentId: 'agent-new' }));
expect(r.outcome).toBe('ready');
expect(updateTask).not.toHaveBeenCalled();
});
// A plain resume never targets a claim tree — its pointer names a CoS
// `agent-*` worktree — so it must not carry the same carve-out.
it('does not opt into live-claim adoption for a plain resume', async () => {
findAdoptableWorktreeForBranch.mockResolvedValue(null);
const task = { id: 't-resume', taskType: 'user', metadata: { useWorktree: true, existingBranch: 'cos/t-resume/agent-dead' } };
await prepareAgentWorkspace({ agentId: 'agent-new', task });
const [, , opts] = findAdoptableWorktreeForBranch.mock.calls.at(-1);
expect(opts.allowLiveClaim).toBe(false);
expect(releaseIdleSiblingNextHolder).not.toHaveBeenCalled();
});
// Adoption MOVES the directory, so the protected set has to cover every agent
// that still needs its tree — including a PAUSED one, whose worktree is
// deliberately preserved as resume context and which is absent from the
// in-process maps entirely.
it('protects running AND paused agents from having their tree moved', async () => {
getAgents.mockResolvedValue([
{ id: 'agent-running', status: 'running' },
{ id: 'agent-paused', status: 'paused' },
{ id: 'agent-done', status: 'completed' },
]);
await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
const [, , opts] = findAdoptableWorktreeForBranch.mock.calls.at(-1);
expect([...opts.activeAgentIds].sort()).toEqual(['agent-paused', 'agent-running']);
});
// An unreadable agent list must not read as "nothing is running" — that is the
// one wrong answer, since it would move a live run's directory.
it('refuses to adopt at all when the agent list cannot be read', async () => {
getAgents.mockRejectedValue(new Error('state.json unreadable'));
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
expect(findAdoptableWorktreeForBranch).not.toHaveBeenCalled();
expect(adoptWorktree).toHaveBeenCalledTimes(0);
expect(r.outcome).toBe('blocked');
});
it('recovers an unrelated ordinary agent branch while a swarm owns claim branches', async () => {
const path = '/mock/worktrees/agent-y';
const branch = 'cos/task-x/agent-y';
listWorktrees.mockResolvedValue([{ path, branch: `refs/heads/${branch}` }]);
getAgents.mockResolvedValue([{ id: 'agent-parent', status: 'running', claimPicksOwnBranch: true }]);
findAdoptableWorktreeForBranch.mockResolvedValue({ path, agentId: 'agent-y' });
adoptWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/agent-new', branchName: branch, adopted: true });
const result = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
expect(result.outcome).toBe('ready');
expect(adoptWorktree).toHaveBeenCalled();
});
it.each(['claim/issue-42', 'next/issue-42'])('defers coordinator takeover of %s through the child completion and merge window', async branch => {
const path = '/mock/worktrees/claim-issue-42';
listWorktrees.mockResolvedValue([{ path, branch: `refs/heads/${branch}` }]);
getAgents.mockResolvedValue([
{ id: 'agent-parent', status: 'running', claimPicksOwnBranch: true },
{ id: 'agent-child', status: 'completed', claimBranch: branch },
]);
// Without owner admission this route moves the selected checkout, or
// detaches a sibling holder and creates a new one. Neither is authorized.
findAdoptableWorktreeForBranch.mockResolvedValue({ path, agentId: 'claim-issue-42' });
adoptWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/agent-new', branchName: branch, adopted: true });
const result = await prepareAgentWorkspace({
agentId: 'agent-new', task: followUpTask({ reviewLoopPRBranch: branch }),
});
expect(result).toMatchObject({ outcome: 'blocked', reason: expect.stringContaining('owner-ambiguous') });
expect(adoptWorktree).not.toHaveBeenCalled();
expect(releaseIdleSiblingNextHolder).not.toHaveBeenCalled();
expect(createWorktree).not.toHaveBeenCalled();
});
it.each(['unreadable', 'missing', 'changed'])('refuses %s coordinator ownership without taking a fallback', async fault => {
const path = '/mock/worktrees/claim-issue-42';
listWorktrees.mockResolvedValue(fault === 'unreadable' ? null : fault === 'missing' ? [] : [{ path, branch: 'refs/heads/claim/issue-99' }]);
const result = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask({
reviewLoopPRBranch: 'claim/issue-42', resumeWorktreePath: path,
}) });
expect(result.outcome).toBe('blocked');
expect(adoptWorktree).not.toHaveBeenCalled();
expect(releaseIdleSiblingNextHolder).not.toHaveBeenCalled();
expect(createWorktree).not.toHaveBeenCalled();
});
it('falls back to the cooldown pause when the adoption is refused', async () => {
findAdoptableWorktreeForBranch.mockResolvedValue({ path: '/mock/worktrees/agent-y', agentId: 'agent-y' });
adoptWorktree.mockResolvedValue(null);
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
expect(r.outcome).toBe('blocked');
expect(updateTask.mock.calls.at(-1)[1].metadata.blockedCategory).toBe('worktree-busy');
});
// Only a task that KNOWS which branch it wants can take over the tree holding
// it. A plain isolated task's add failure names a branch it just tried to
// create, and adopting some other tree would hand it unrelated work.
it('does not go looking for a holder when the task has no branch to attach to', async () => {
const task = { id: 't-plain', taskType: 'user', metadata: { useWorktree: true } };
await prepareAgentWorkspace({ agentId: 'agent-new', task });
expect(findAdoptableWorktreeForBranch).not.toHaveBeenCalled();
});
it('pauses with a cooldown instead of blocking, and keeps the branch pointer', async () => {
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
expect(r.outcome).toBe('blocked');
const [, patch] = updateTask.mock.calls.at(-1);
expect(patch.status).toBe('blocked');
expect(patch.metadata.blockedCategory).toBe('worktree-busy');
// `worktree-busy` is a PAUSE category, so its canonical PR branch survives —
// the revived attempt must still attach to the PR branch, not cut a new one.
expect(patch.metadata.reviewLoopPRBranch).toBe('cos/task-x/agent-y');
// The cooldown stamp is what the sweeper in cosTaskGenerator revives on.
expect(new Date(patch.metadata.cooldownUntil).getTime()).toBeGreaterThan(Date.now());
expect(patch.metadata.worktreeBusyAttempts).toBe(1);
// A retried busy branch is handled, not a fault: the pause reports at info and stderr stays quiet.
expect(emitLog).toHaveBeenCalledWith('info', expect.stringContaining('retrying after a short cooldown'), expect.any(Object));
expect(emitLog).not.toHaveBeenCalledWith('warn', expect.stringContaining('Worktree creation failed'), expect.anything());
});
it('counts up from the attempts already recorded on the task', async () => {
// Metadata round-trips through TASKS.md as strings.
await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask({ worktreeBusyAttempts: '3' }) });
const [, patch] = updateTask.mock.calls.at(-1);
expect(patch.metadata.worktreeBusyAttempts).toBe(4);
expect(patch.metadata.blockedCategory).toBe('worktree-busy');
});
it('gives up on a branch nothing is going to release, so a human sees the real block', async () => {
// A worktree removeWorktree REFUSED to delete (uncommitted changes) holds the
// branch until someone clears it — waiting forever would just hide the PR.
await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask({ worktreeBusyAttempts: 5 }) });
const [, patch] = updateTask.mock.calls.at(-1);
expect(patch.metadata.blockedCategory).toBe('worktree-failed');
// The git error rides along — "worktree creation failed" alone said nothing
// about which branch was held, or by what.
expect(patch.metadata.blockedReason).toContain('already used by worktree');
// Once the retry budget is spent nothing retries it, so the failure is a fault again.
expect(emitLog).toHaveBeenCalledWith('warn', expect.stringContaining('Worktree creation failed for task'), expect.any(Object));
});
// A terminal session's own worktree holds the branch for good: nothing PortOS
// runs ever reaps it, so the cooldown can only burn the retry budget (#12845).
describe('an ownerless foreign holder', () => {
const READY = { worktreePath: '/mock/worktrees/agent-new', branchName: 'cos/task-x/agent-y', baseBranch: null, existingBranch: true };
it('is released and the branch attached within the same attempt', async () => {
createWorktree.mockRejectedValueOnce(BUSY).mockResolvedValueOnce(READY);
releaseOwnerlessForeignHolder.mockResolvedValue({ path: '/scratch/wt-portos' });
getAgents.mockResolvedValue([
{ id: 'agent-live', status: 'running', workspacePath: '/mock/worktrees/agent-live' },
{ id: 'agent-done', status: 'completed', workspacePath: '/mock/worktrees/agent-done' },
]);
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
expect(r.outcome).toBe('ready');
expect(createWorktree).toHaveBeenCalledTimes(2);
expect(releaseOwnerlessForeignHolder).toHaveBeenCalledWith(expect.any(String), 'cos/task-x/agent-y', expect.objectContaining({
requestingAgentId: 'agent-new',
activeWorkspacePaths: ['/mock/worktrees/agent-live'],
}));
expect(updateTask).not.toHaveBeenCalled();
});
it.each([
['refuses to release', () => releaseOwnerlessForeignHolder.mockResolvedValue(null)],
['throws while releasing', () => releaseOwnerlessForeignHolder.mockRejectedValue(new Error('git exploded'))],
['finds the agent list unreadable at release time', () => getAgents.mockResolvedValueOnce([]).mockRejectedValue(new Error('state unreadable'))],
])('keeps the timed worktree-busy pause when the holder %s', async (_label, arrange) => {
arrange();
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
expect(r.outcome).toBe('blocked');
expect(createWorktree).toHaveBeenCalledTimes(1);
expect(updateTask.mock.calls.at(-1)[1].metadata.blockedCategory).toBe('worktree-busy');
});
it('pauses when the branch is still busy after a release', async () => {
releaseOwnerlessForeignHolder.mockResolvedValue({ path: '/scratch/wt-portos' });
const r = await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
expect(r.outcome).toBe('blocked');
expect(createWorktree).toHaveBeenCalledTimes(2);
expect(updateTask.mock.calls.at(-1)[1].metadata.blockedCategory).toBe('worktree-busy');
});
it('is not sought for a failure that is not a busy branch', async () => {
createWorktree.mockRejectedValue(new Error("fatal: '/mock/worktrees/agent-new' already exists"));
await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
expect(releaseOwnerlessForeignHolder).not.toHaveBeenCalled();
});
});
it('does NOT pause for a permanent worktree failure', async () => {
createWorktree.mockRejectedValue(new Error("fatal: '/mock/worktrees/agent-new' already exists"));
await prepareAgentWorkspace({ agentId: 'agent-new', task: followUpTask() });
const [, patch] = updateTask.mock.calls.at(-1);
expect(patch.metadata.blockedCategory).toBe('worktree-failed');
});
});
// Which branch a task's worktree attaches to when `existingBranch` didn't survive
// `updateTask`'s resume-pointer strip — see the docblock on the function.
describe('resolveTaskExistingBranch', () => {
it('prefers the explicit pointer', () => {
expect(resolveTaskExistingBranch({ existingBranch: 'cos/a/agent-1' })).toBe('cos/a/agent-1');
});
it('falls back to a follow-up’s own record of its PR branch', () => {
expect(resolveTaskExistingBranch({
reviewLoopFollowUp: true, reviewLoopPRBranch: 'cos/a/agent-1'
})).toBe('cos/a/agent-1');
// TASKS.md round-trips metadata as strings.
expect(resolveTaskExistingBranch({
reviewLoopFollowUp: 'true', reviewLoopPRBranch: 'cos/a/agent-1'
})).toBe('cos/a/agent-1');
});
// The ORIGINAL task also carries PR metadata once its review loop starts; it
// owns that branch through its own worktree and must not be re-pointed at it.
it('ignores a PR branch on anything that is not a follow-up', () => {
expect(resolveTaskExistingBranch({ reviewLoopPRBranch: 'cos/a/agent-1' })).toBeNull();
expect(resolveTaskExistingBranch({ reviewLoopFollowUp: false, reviewLoopPRBranch: 'cos/a/agent-1' })).toBeNull();
expect(resolveTaskExistingBranch({})).toBeNull();
expect(resolveTaskExistingBranch(undefined)).toBeNull();
});
it('attaches a stripped follow-up to its PR branch rather than cutting a new one', async () => {
ensureLatest.mockResolvedValue({ success: true, upToDate: true });
adoptWorktree.mockResolvedValue(null);
createWorktree.mockResolvedValue({
worktreePath: '/mock/worktrees/agent-new', branchName: 'cos/task-x/agent-y',
baseBranch: null, existingBranch: true
});
await prepareAgentWorkspace({
agentId: 'agent-new',
task: {
id: 'sys-rl-1', taskType: 'internal',
metadata: {
useWorktree: true, reviewLoopFollowUp: true,
reviewLoopPRBranch: 'cos/task-x/agent-y',
reviewLoopPRUrl: 'https://github.com/o/r/pull/1'
}
}
});
expect(createWorktree).toHaveBeenCalledWith('agent-new', expect.any(String), 'sys-rl-1',
expect.objectContaining({ existingBranch: 'cos/task-x/agent-y' }));
});
});
describe('durable workspace preparation and registration lifetime', () => {
it('retains admission after ordinary creation until its registration continuation settles', async () => {
let finish;
const registration = new Promise(resolve => { finish = resolve; });
createWorktree.mockImplementationOnce(async () => {
expect(publication.active).toBe(true);
return { worktreePath: '/mock/worktrees/new', branchName: 'cos/new' };
});
const onPrepared = vi.fn(async result => {
expect(result.outcome).toBe('ready');
expect(publication.active).toBe(true);
await registration;
expect(publication.active).toBe(true);
return 'registered-and-spawned';
});
const result = prepareAgentWorkspace({ agentId: 'new', task: {
id: 'new', metadata: { useWorktree: true },
}, onPrepared });
await vi.waitFor(() => expect(onPrepared).toHaveBeenCalledOnce());
expect(publication.active).toBe(true);
finish();
expect(await result).toBe('registered-and-spawned');
expect(publication.active).toBe(false);
});
it('refuses before ordinary preparation can mutate or call registration', async () => {
publication.refuse = true;
const onPrepared = vi.fn();
await expect(prepareAgentWorkspace({ agentId: 'new', task: {
id: 'new', metadata: { useWorktree: true },
}, onPrepared })).rejects.toThrow('checkout-retirement-reserved');
expect(createWorktree).not.toHaveBeenCalled();
expect(ensureLatest).not.toHaveBeenCalled();
expect(onPrepared).not.toHaveBeenCalled();
});
it('continues non-Git read-only tasks without a repository permit', async () => {
execGit.mockResolvedValueOnce({ stdout: '', stderr: 'fatal: not a git repository (or any of the parent directories): .git', exitCode: 128 });
const onPrepared = vi.fn(async result => {
expect(publication.active).toBe(false);
return result;
});
const result = await prepareAgentWorkspace({ agentId: 'docs', task: {
id: 'docs', metadata: { readOnly: true },
}, onPrepared });
expect(result.outcome).toBe('ready');
expect(onPrepared).toHaveBeenCalledOnce();
});
it.each(['fatal: permission denied', 'fatal: not a git repository: /broken/gitdir'])('does not treat an unreadable repository as non-Git: %s', async stderr => {
execGit.mockResolvedValueOnce({ stdout: '', stderr, exitCode: 128 });
const onPrepared = vi.fn();
await expect(prepareAgentWorkspace({ agentId: 'new', task: { id: 'new', metadata: {} }, onPrepared }))
.rejects.toThrow('Cannot establish workspace repository identity');
expect(ensureLatest).not.toHaveBeenCalled();
expect(onPrepared).not.toHaveBeenCalled();
});
});