Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
// Git/filesystem are synthetic in this suite; real durable admission has its own boundary tests.
vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_repo, work) => work() }));
const store = { state: null, stateGate: null, readGate: null, saveGate: null, unreadable: false, stale: false };
const deferred = () => {
let resolve;
let reject;
const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
return { promise, resolve, reject };
};
vi.mock('./cosState.js', () => ({
withStateLock: vi.fn(async work => { if (store.stateGate) await store.stateGate; return work(); }),
readAgentsStateForSafetyCheck: vi.fn(async () => {
if (store.readGate) await store.readGate;
return { trusted: !store.unreadable, agents: structuredClone(store.state.agents) };
}),
loadState: async () => store.stale ? { agents: {} } : store.state,
saveState: vi.fn(async next => { if (store.saveGate) await store.saveGate; store.state = structuredClone(next); }),
}));
vi.mock('./cosEvents.js', () => ({ cosEvents: { emit: vi.fn() } }));
const { updateClaimOwnership, checkReconcileOwnership, CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS } = await import('./cosClaimOwnership.js');
// Hold the same leaf fence cleanup uses while exercising binding through its public service.
const { withClaimOwnershipLock, reserveCheckoutRetirementFence } = await import('./cosClaimOwnershipState.js');
const { claimContinuationAdmission, claimBranchAdmission } = await import('../lib/claimContinuation.js');
const { withStateLock, readAgentsStateForSafetyCheck, saveState } = await import('./cosState.js');
const { cosEvents } = await import('./cosEvents.js');
const SOURCE = '/repos/app-x';
const CHILD = '/repos/app-x/data/cos/worktrees/claim-issue-101';
beforeEach(() => {
store.stateGate = store.readGate = store.saveGate = null;
store.unreadable = store.stale = false;
vi.clearAllMocks();
store.state = {
agents: {
'agent-epicrun': {
id: 'agent-epicrun', status: 'running', workspacePath: SOURCE,
metadata: { sourceWorkspace: SOURCE, claimBranch: 'claim/issue-100', claimPicksOwnBranch: false, claimSelectionPending: true },
},
},
};
});
afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks(); });
describe('updateClaimOwnership', () => {
it('reserves before creation, seeds the exact physical checkout on rebind, and refuses a replacement generation', async () => {
const { mkdtemp, readFile, writeFile, rename, rm } = await import('node:fs/promises');
const { tmpdir } = await import('node:os');
const { join } = await import('node:path');
const { materializeGitRepo } = await import('../lib/gitTestRepo.js');
const { execGit } = await import('../lib/execGit.js');
const scratch = await mkdtemp(join(tmpdir(), 'portos-claim-seed-'));
try {
const repo = join(scratch, 'repo');
const checkout = join(scratch, 'claim');
await materializeGitRepo(repo);
store.state.agents['agent-epicrun'] = { id: 'agent-epicrun', status: 'running',
startedAt: new Date().toISOString(), metadata: { sourceWorkspace: repo, workspacePath: repo,
claimPicksOwnBranch: true, claimBranches: [] } };
const bind = () => updateClaimOwnership({ agentId: 'agent-epicrun', action: 'bind', branch: 'claim/issue-101' });
expect(await bind()).toEqual({ bound: true, branch: 'claim/issue-101' });
expect(store.state.agents['agent-epicrun'].metadata.checkoutSeeds).toEqual([]);
await execGit(['worktree', 'add', '-b', 'claim/issue-101', checkout, 'main'], repo);
expect(await bind()).toEqual({ bound: true, branch: 'claim/issue-101' });
const seed = store.state.agents['agent-epicrun'].metadata.checkoutSeeds[0];
expect(seed).toMatchObject({ branch: 'claim/issue-101', incarnation: { pointer: { ino: expect.any(String) } } });
await writeFile(join(checkout, 'wanted.txt'), 'wanted work');
expect(await bind()).toEqual({ bound: true, branch: 'claim/issue-101' });
expect(store.state.agents['agent-epicrun'].metadata.checkoutSeeds).toEqual([seed]);
const pointer = join(checkout, '.git');
const contents = await readFile(pointer);
await rename(pointer, join(scratch, 'original-pointer'));
await writeFile(pointer, contents);
expect(await bind()).toEqual({ bound: false, reason: 'checkout-seed-unavailable' });
expect(store.state.agents['agent-epicrun'].metadata.checkoutSeeds).toEqual([seed]);
expect(await readFile(join(checkout, 'wanted.txt'), 'utf8')).toBe('wanted work');
} finally { await rm(scratch, { recursive: true, force: true, maxRetries: 3 }); }
});
it('persists the bound child branch on the run record and settles its selection', async () => {
expect(await updateClaimOwnership({ agentId: 'agent-epicrun', action: 'bind', branch: 'claim/issue-101' }))
.toEqual({ bound: true, branch: 'claim/issue-101' });
expect(await updateClaimOwnership({ agentId: 'agent-epicrun', action: 'bind', branch: 'claim/issue-101' }))
.toEqual({ bound: true, branch: 'claim/issue-101' });
expect(store.state.agents['agent-epicrun'].metadata).toMatchObject({
claimBranch: 'claim/issue-100', claimBranches: ['claim/issue-101'], claimSelectionPending: false,
});
expect(await updateClaimOwnership({ agentId: 'agent-epicrun', action: 'release', branch: 'claim/issue-101' }))
.toEqual({ released: true, branch: 'claim/issue-101' });
expect(store.state.agents['agent-epicrun'].metadata).toMatchObject({ claimBranches: [], claimReleasedBranches: ['claim/issue-101'] });
});
it('refuses an unknown or finished run without writing', async () => {
const before = structuredClone(store.state);
expect(await updateClaimOwnership({ agentId: 'agent-gone', action: 'bind', branch: 'claim/issue-101' }))
.toEqual({ bound: false, reason: 'owner-unknown' });
store.state.agents['agent-epicrun'].status = 'completed';
expect(await updateClaimOwnership({ agentId: 'agent-epicrun', action: 'bind', branch: 'claim/issue-101' }))
.toEqual({ bound: false, reason: 'owner-not-running' });
expect(store.state.agents['agent-epicrun'].metadata).toEqual(before.agents['agent-epicrun'].metadata);
});
});
describe('claim ownership queued transaction deadlines', () => {
const update = action => updateClaimOwnership({ agentId: 'agent-epicrun', action, branch: 'claim/issue-101' });
const tick = () => vi.advanceTimersByTimeAsync(0);
beforeEach(() => {
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });
vi.spyOn(console, 'warn').mockImplementation(() => {});
vi.spyOn(console, 'log').mockImplementation(() => {});
vi.spyOn(console, 'error').mockImplementation(() => {});
});
it.each(['bind', 'release'])('fences a timed-out %s at each queued boundary', async action => {
store.state.agents['agent-epicrun'].metadata.claimBranches = action === 'release' ? ['claim/issue-101'] : [];
const before = structuredClone(store.state);
// A retirement can hold ownership while unrelated state writers hold state.
// Neither resumed callback may mutate after the caller received a refusal.
for (const queue of ['ownership', 'state']) {
const gate = deferred();
const held = queue === 'ownership' ? withClaimOwnershipLock(() => gate.promise) : null;
if (queue === 'state') store.stateGate = gate.promise;
const pending = update(action);
await tick();
await vi.advanceTimersByTimeAsync(CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS);
expect(await pending).toEqual({ [action === 'bind' ? 'bound' : 'released']: false,
reason: `${queue}-queue-timeout`, retryAfterMs: 5000 });
expect(readAgentsStateForSafetyCheck).not.toHaveBeenCalled();
gate.resolve();
if (held) await held;
await withClaimOwnershipLock(() => {});
expect(store.state).toEqual(before);
expect(saveState).not.toHaveBeenCalled();
expect(cosEvents.emit).not.toHaveBeenCalled();
}
store.stateGate = null;
expect(await update(action)).toEqual({ [action === 'bind' ? 'bound' : 'released']: true, branch: 'claim/issue-101' });
});
it('fences overdue callbacks even when the timer has not run, sharing the budget across queues', async () => {
const ownership = deferred();
const state = deferred();
const held = withClaimOwnershipLock(() => ownership.promise);
store.stateGate = state.promise;
const pending = update('bind');
await tick();
await vi.advanceTimersByTimeAsync(CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS - 1);
ownership.resolve();
await held;
await tick();
expect(withStateLock).toHaveBeenCalledOnce();
// Advance only the monotonic clock; leave the scheduled timer unfired.
vi.spyOn(performance, 'now').mockReturnValue(CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS);
state.resolve();
expect(await pending).toEqual({ bound: false, reason: 'state-queue-timeout', retryAfterMs: 5000 });
expect(readAgentsStateForSafetyCheck).not.toHaveBeenCalled();
expect(saveState).not.toHaveBeenCalled();
await withClaimOwnershipLock(() => {});
});
it('keeps a started save owned until durable settlement and reports redacted persistence evidence', async () => {
const save = deferred();
store.saveGate = save.promise;
const before = structuredClone(store.state);
let settled = false;
const pending = update('bind').then(result => { settled = true; return result; });
await tick();
expect(saveState).toHaveBeenCalledOnce();
await vi.advanceTimersByTimeAsync(CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS);
expect(settled).toBe(false);
expect(store.state).toEqual(before);
expect(cosEvents.emit).not.toHaveBeenCalled();
expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('status=pending phase=persistence'));
let nextEntered = false;
const following = withClaimOwnershipLock(() => { nextEntered = true; });
await tick();
expect(nextEntered).toBe(false);
save.resolve();
expect(await pending).toEqual({ bound: true, branch: 'claim/issue-101' });
await following;
expect(store.state.agents['agent-epicrun'].metadata.claimBranches).toEqual(['claim/issue-101']);
expect(cosEvents.emit).toHaveBeenCalledOnce();
const diagnostics = [...console.warn.mock.calls, ...console.log.mock.calls].flat().join(' ');
expect(diagnostics).not.toMatch(/agent-epicrun|claim\/issue|repos/);
expect(diagnostics).toMatch(/ownershipQueueMs=\d+ stateQueueMs=\d+ ownerReadMs=\d+ ownershipCheckMs=\d+ persistenceMs=\d+/);
});
it('diagnoses an in-flight trusted owner read and refuses unreadable or stale ownership without writes', async () => {
const read = deferred();
store.readGate = read.promise;
store.unreadable = true;
const pending = update('bind');
await tick();
await vi.advanceTimersByTimeAsync(CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS);
expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('status=pending phase=ownerRead'));
read.resolve();
expect(await pending).toEqual({ bound: false, reason: 'ownership-unreadable' });
store.unreadable = false;
store.stale = true;
expect(await update('release')).toEqual({ released: false, reason: 'ownership-stale' });
expect(saveState).not.toHaveBeenCalled();
});
it('propagates a started persistence failure and releases the queue only after rejection', async () => {
const save = deferred();
store.saveGate = save.promise;
const before = structuredClone(store.state);
const pending = update('bind');
const failure = expect(pending).rejects.toThrow('synthetic write failure');
await tick();
await vi.advanceTimersByTimeAsync(CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS);
save.reject(new Error('synthetic write failure'));
await failure;
await withClaimOwnershipLock(() => {});
expect(store.state).toEqual(before);
expect(cosEvents.emit).not.toHaveBeenCalled();
expect(console.error).toHaveBeenCalledWith(expect.stringContaining('status=failed phase=persistence'));
});
});
// The scan that dispatched a reconcile worker is stale by the time it mutates:
// ownership acquired in between must refuse at the worker's own recheck.
describe('checkReconcileOwnership', () => {
const holder = { path: CHILD, branch: 'refs/heads/claim/issue-101' };
const check = (agents, overrides = {}, input = {}) => checkReconcileOwnership(
{ appId: 'app-x', branch: 'claim/issue-101', worktreePath: CHILD, ...input },
{
getAppById: async (id) => (id === 'app-x' ? { id, repoPath: SOURCE } : null),
listWorktrees: async () => [holder],
getAgents: async () => agents,
getActiveAgentIds: () => [],
readCompletionHold: async () => null,
...overrides,
},
);
it('admits a checkout no live run owns', async () => {
expect(await check([])).toEqual({ admitted: true });
});
it('refuses once a claim run bound the branch after the scan', async () => {
const owner = { id: 'agent-epicrun', status: 'running', workspacePath: SOURCE, metadata: { sourceWorkspace: SOURCE, claimBranches: ['claim/issue-101'] } };
expect(await check([owner])).toEqual({ admitted: false, reason: 'claim-owner-active' });
expect(await check([{ ...owner, status: 'completed' }])).toEqual({ admitted: true });
});
it('refuses when ownership is unreadable, the app is unknown, or the holder moved', async () => {
expect(await check(null)).toEqual({ admitted: false, reason: 'ownership-unreadable' });
expect(await check([], { listWorktrees: async () => { throw new Error('git failed'); } })).toEqual({ admitted: false, reason: 'ownership-unreadable' });
expect(await check([], {}, { appId: 'app-missing' })).toEqual({ admitted: false, reason: 'app-unknown' });
expect(await check([], { listWorktrees: async () => [] })).toEqual({ admitted: false, reason: 'holder-changed' });
expect(await check([], { listWorktrees: async () => [{ ...holder, locked: true }] })).toEqual({ admitted: false, reason: 'worktree-locked' });
});
});
// A successful check by a named coordinator is an acquire (#10096): the claim run
// that binds mid-mutation would otherwise be handed the same checkout.
describe('checkReconcileOwnership reservation', () => {
const holder = { path: CHILD, branch: 'refs/heads/claim/issue-101' };
const admit = (agentId, input = {}) => checkReconcileOwnership(
{ appId: 'app-x', branch: 'claim/issue-101', worktreePath: CHILD, agentId, ...input },
{
getAppById: async (id) => ({ id, repoPath: SOURCE }),
listWorktrees: async () => [holder],
getAgents: async () => Object.values(store.state.agents),
getActiveAgentIds: () => [],
readCompletionHold: async () => null,
},
);
const bind = () => updateClaimOwnership({ agentId: 'agent-picker', action: 'bind', branch: 'claim/issue-101' });
beforeEach(() => {
store.state.agents['agent-recon'] = {
id: 'agent-recon', status: 'running', workspacePath: SOURCE, metadata: { sourceWorkspace: SOURCE },
};
store.state.agents['agent-picker'] = {
id: 'agent-picker', status: 'running', workspacePath: SOURCE,
metadata: { sourceWorkspace: SOURCE, claimBranch: 'claim/issue-100', claimPicksOwnBranch: false },
};
delete store.state.agents['agent-epicrun'];
});
it('refuses a claim bind, continuation and adoption of an admitted branch until the coordinator ends', async () => {
expect(await admit('agent-recon')).toEqual({ admitted: true });
expect(store.state.agents['agent-recon'].metadata.claimBranches).toEqual(['claim/issue-101']);
expect(await bind()).toEqual({ bound: false, reason: 'owner-active' });
const agents = Object.values(store.state.agents);
const metadata = { existingBranch: 'claim/issue-101', resumeWorktreePath: CHILD };
expect(claimContinuationAdmission({ metadata, agentId: 'agent-picker', sourceWorkspace: SOURCE, worktrees: [holder], agents }))
.toEqual({ admit: false, reason: 'owner-active' });
expect(claimBranchAdmission({ branchName: 'claim/issue-101', preferredPath: CHILD, agentId: 'agent-picker', sourceWorkspace: SOURCE, worktrees: [holder], agents }))
.toEqual({ admit: false, reason: 'owner-active' });
store.state.agents['agent-recon'].status = 'completed';
expect(await bind()).toEqual({ bound: true, branch: 'claim/issue-101' });
});
it('lets the coordinator re-admit its own branch and release it explicitly', async () => {
expect(await admit('agent-recon')).toEqual({ admitted: true });
expect(await admit('agent-recon')).toEqual({ admitted: true });
expect(store.state.agents['agent-recon'].metadata.claimBranches).toEqual(['claim/issue-101']);
expect(await updateClaimOwnership({ agentId: 'agent-recon', action: 'release', branch: 'claim/issue-101' }))
.toEqual({ released: true, branch: 'claim/issue-101' });
expect(await bind()).toEqual({ bound: true, branch: 'claim/issue-101' });
});
it('stays read-only without an agent id and writes nothing when refused', async () => {
const before = structuredClone(store.state);
expect(await admit(undefined)).toEqual({ admitted: true });
expect(store.state).toEqual(before);
expect(await admit('agent-gone')).toEqual({ admitted: false, reason: 'owner-unknown' });
store.state.agents['agent-recon'].status = 'completed';
expect(await admit('agent-recon')).toEqual({ admitted: false, reason: 'owner-not-running' });
store.state.agents['agent-recon'].status = 'running';
store.state.agents['agent-picker'].metadata.claimBranches = ['claim/issue-101'];
expect(await admit('agent-recon')).toEqual({ admitted: false, reason: 'claim-owner-active' });
expect(store.state.agents['agent-recon'].metadata.claimBranches).toBeUndefined();
});
// #12682: retirement archives with the ownership lock released, fenced per checkout.
it('refuses binds and admissions for a checkout being archived, and only that checkout, until the fence lifts', async () => {
const before = structuredClone(store.state);
const releaseFence = await withClaimOwnershipLock(() => reserveCheckoutRetirementFence({ repoPath: SOURCE, path: CHILD, branch: 'refs/heads/claim/issue-101' }));
expect(await withClaimOwnershipLock(() => reserveCheckoutRetirementFence({ repoPath: `${SOURCE}/`, path: CHILD }))).toBeNull();
expect(await bind()).toEqual({ bound: false, reason: 'checkout-retirement-reserved' });
expect(await admit('agent-recon')).toEqual({ admitted: false, reason: 'checkout-retirement-reserved' });
expect(await admit(undefined)).toEqual({ admitted: false, reason: 'checkout-retirement-reserved' });
expect(store.state).toEqual(before);
// Releasing a branch and binding a different one are not fenced.
expect(await updateClaimOwnership({ agentId: 'agent-picker', action: 'bind', branch: 'claim/issue-102' }))
.toEqual({ bound: true, branch: 'claim/issue-102' });
expect(await updateClaimOwnership({ agentId: 'agent-picker', action: 'release', branch: 'claim/issue-102' }))
.toEqual({ released: true, branch: 'claim/issue-102' });
await withClaimOwnershipLock(releaseFence);
expect(await bind()).toEqual({ bound: true, branch: 'claim/issue-101' });
});
it('reserves nothing for a branch no claim run can bind', async () => {
const before = structuredClone(store.state);
const feature = { path: '/repos/app-x/other', branch: 'refs/heads/feature/x' };
expect(await checkReconcileOwnership(
{ appId: 'app-x', branch: 'feature/x', worktreePath: feature.path, agentId: 'agent-recon' },
{ getAppById: async (id) => ({ id, repoPath: SOURCE }), listWorktrees: async () => [feature], getAgents: async () => [], getActiveAgentIds: () => [], readCompletionHold: async () => null },
)).toEqual({ admitted: true });
expect(store.state).toEqual(before);
});
});