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 { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { act, cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
import { awaitEnabled } from '../../../test/enabledBarrier.js';
vi.mock('../../../services/api', () => ({
PORTOS_APP_ID: 'portos-default',
getAppRepositorySources: vi.fn(),
syncAppRepositoryFork: vi.fn(),
handleSelfRestart: vi.fn(),
getProviders: vi.fn(),
addCosTask: vi.fn(),
}));
vi.mock('../../../services/apiLocalLlm', async (importOriginal) => ({
...await importOriginal(),
getToolUseModels: vi.fn().mockResolvedValue({ models: [] }),
}));
vi.mock('../../../hooks/useForgeScopeRefresh', () => ({
default: vi.fn(() => ({ active: false, pending: false, device: null, start: vi.fn(), cancel: vi.fn() })),
}));
vi.mock('../../../hooks/useAppOperation', () => ({
useAppOperation: vi.fn(),
}));
import * as api from '../../../services/api';
import useForgeScopeRefresh from '../../../hooks/useForgeScopeRefresh';
import { useAppOperation } from '../../../hooks/useAppOperation';
import RepositorySourcePanel from './RepositorySourcePanel';
import { MemoryRouter } from 'react-router';
const source = ({
id,
label,
branch,
head,
origin,
localVsOrigin = { ahead: 0, behind: 0, state: 'current' },
forkVsUpstream = null,
forkSyncable,
}) => ({
id,
label,
present: true,
branch,
head,
shortHead: head.slice(0, 7),
clean: true,
origin: {
hasOrigin: true,
isGithub: true,
head,
shortHead: head.slice(0, 7),
...origin,
},
upstream: {
fullName: `anima-research/${id === 'primary' ? 'example-app' : 'example-runtime'}`,
branch,
},
localVsOrigin,
forkVsUpstream,
// Mirrors the server's `isForkSyncable` so fixtures carry the payload the
// client actually reads (server/services/managedAppRepositories.js).
forkSyncable: forkSyncable ?? (id === 'primary'
&& Boolean(origin?.isFork)
&& origin?.canPush !== false
&& forkVsUpstream?.state !== 'diverged'),
remoteFresh: true,
remoteError: null,
});
const canonicalStatus = () => ({
kind: 'managed-app',
updateAvailable: true,
updatePullsAll: true,
updateRestartsApp: true,
sources: [
source({
id: 'primary',
label: 'Example App',
branch: 'main',
head: '1'.repeat(40),
origin: {
fullName: 'anima-research/example-app',
isUpstream: true,
isFork: false,
},
localVsOrigin: { ahead: 0, behind: 1, state: 'behind' },
}),
source({
id: 'companion-1',
label: 'example-runtime',
branch: 'prod-serving',
head: '2'.repeat(40),
origin: {
fullName: 'anima-research/example-runtime',
isUpstream: true,
isFork: false,
},
}),
],
});
beforeEach(() => {
vi.clearAllMocks();
useAppOperation.mockReturnValue({
steps: [], isOperating: false, operationType: null, error: null, completed: false,
startUpdate: vi.fn(),
});
api.getAppRepositorySources.mockResolvedValue(canonicalStatus());
api.syncAppRepositoryFork.mockResolvedValue({ synced: true, alreadyUpToDate: false });
});
afterEach(() => cleanup());
describe('managed app repository sources', () => {
it('updates stale submodules through the managed flow without a recovery agent', async () => {
const status = canonicalStatus();
status.sources = [{ ...status.sources[0], clean: false, submodulesOnly: true, localVsOrigin: { ahead: 0, behind: 0, state: 'current' } }];
api.getAppRepositorySources.mockResolvedValue(status);
render(<RepositorySourcePanel appId="portos-default" appName="PortOS" hasLocalChanges />);
expect(await screen.findByText('submodules need updating')).toBeInTheDocument();
expect(screen.queryByRole('button', { name: 'Resolve with agent' })).not.toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: 'Update app' }));
fireEvent.click(within(screen.getByRole('dialog')).getByRole('button', { name: 'Update app' }));
expect(useAppOperation().startUpdate).toHaveBeenCalledWith('portos-default', 'PortOS', { syncFork: false });
expect(api.addCosTask).not.toHaveBeenCalled();
});
it('explains and versions both independent checkouts', async () => {
render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
expect(await screen.findByText('Repository sources')).toBeInTheDocument();
expect(screen.getByText('Independent companion checkout · not a submodule')).toBeInTheDocument();
expect(screen.getByTestId('repository-source-primary')).toHaveTextContent('main @ 1111111');
expect(screen.getByTestId('repository-source-primary')).toHaveTextContent('Checkout 1 behind');
expect(screen.getByTestId('repository-source-companion-1')).toHaveTextContent('prod-serving @ 2222222');
expect(screen.getByTestId('repository-source-companion-1')).toHaveTextContent('Current');
expect(screen.getByRole('button', { name: 'Update app' })).toBeInTheDocument();
});
it('keeps the current update step visible while the operation is running', async () => {
useAppOperation.mockReturnValue({
steps: [{ step: 'npm-install:root', status: 'running', message: 'Installing root dependencies...' }],
isOperating: true,
operationType: 'update',
error: null,
completed: false,
startUpdate: vi.fn(),
});
render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
expect(await screen.findByRole('status', { name: 'App operation status' })).toHaveTextContent('Installing root dependencies...');
expect(screen.getByRole('button', { name: 'Updating...' })).toBeDisabled();
});
it('shows local, fork, and upstream as separate version hops and can sync only the fork', async () => {
const status = canonicalStatus();
status.sources[0] = source({
id: 'primary',
label: 'Example App',
branch: 'main',
head: '1'.repeat(40),
origin: {
fullName: 'example-owner/example-app',
isUpstream: false,
isFork: true,
},
forkVsUpstream: { available: true, ahead: 0, behind: 2, state: 'behind', error: null },
});
api.getAppRepositorySources.mockResolvedValue(status);
render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
const primary = await screen.findByTestId('repository-source-primary');
expect(primary).toHaveTextContent('example-owner/example-app (fork)');
expect(primary).toHaveTextContent('anima-research/example-app (upstream)');
expect(screen.getByRole('button', { name: 'Sync fork & update app' })).toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: 'Sync fork' }));
await waitFor(() => expect(api.syncAppRepositoryFork).toHaveBeenCalledWith('app-example', { silent: true }));
expect(useAppOperation.mock.results[0].value.startUpdate).not.toHaveBeenCalled();
});
it('offers the credential fix when the fork sync is refused for a missing token scope', async () => {
const status = canonicalStatus();
status.sources[0] = source({
id: 'primary',
label: 'Example App',
branch: 'main',
head: '1'.repeat(40),
origin: { fullName: 'example-owner/example-app', isUpstream: false, isFork: true },
forkVsUpstream: { available: true, ahead: 0, behind: 2, state: 'behind', error: null },
});
api.getAppRepositorySources.mockResolvedValue(status);
api.syncAppRepositoryFork.mockRejectedValue(Object.assign(new Error('refused without `workflow` scope'), {
code: 'FORGE_TOKEN_SCOPE_MISSING',
context: { host: 'ghe.example.com', scopes: ['workflow'], command: 'gh auth refresh -h ghe.example.com -s workflow', refreshable: true },
}));
render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
await screen.findByTestId('repository-source-primary');
fireEvent.click(screen.getByRole('button', { name: 'Sync fork' }));
expect(await screen.findByText(/ghe\.example\.com token is missing the workflow scope/)).toBeInTheDocument();
expect(screen.getByRole('button', { name: /Authorize workflow/ })).toBeInTheDocument();
});
it.each([
{ credential: 'oauth', command: 'gh auth refresh -h ghe.example.com -s workflow', refreshable: true },
{ credential: 'personal-access-token', command: null, refreshable: false },
{ credential: 'oauth', command: 'gh auth refresh -h ghe.example.com -s workflow', refreshable: false },
])('repairs a combined update scope refusal without automatically retrying ($credential, $refreshable)', async (guidance) => {
const status = canonicalStatus();
status.sources[0].origin = { ...status.sources[0].origin, isFork: true, isUpstream: false };
status.sources[0].forkVsUpstream = { available: true, ahead: 0, behind: 2, state: 'behind' };
status.sources[0].forkSyncable = true;
api.getAppRepositorySources.mockResolvedValue(status);
const startUpdate = vi.fn();
const operation = { steps: [], isOperating: false, operationType: 'update', startUpdate };
useAppOperation.mockImplementation(() => operation);
const view = render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
fireEvent.click(await screen.findByRole('button', { name: 'Sync fork & update app' }));
fireEvent.click(await screen.findByRole('button', { name: 'Sync fork and update' }));
expect(screen.getByRole('button', { name: 'Reload to update again' })).toBeDisabled();
Object.assign(operation, { error: 'workflow scope missing', errorCode: 'FORGE_TOKEN_SCOPE_MISSING',
errorContext: { host: 'ghe.example.com', scopes: ['workflow'], ...guidance } });
view.rerender(<RepositorySourcePanel appId="app-example" appName="Example App" />);
expect(await screen.findByText(/ghe\.example\.com token is missing the workflow scope/)).toBeInTheDocument();
expect(screen.getByRole('button', { name: 'Sync fork & update app' })).toBeEnabled();
if (guidance.refreshable) {
const authorize = screen.getByRole('button', { name: 'Authorize workflow' });
fireEvent.click(authorize);
expect(useForgeScopeRefresh.mock.results.at(-1).value.start).toHaveBeenCalledWith(['workflow']);
act(() => useForgeScopeRefresh.mock.calls.at(-1)[0].onRefreshed());
expect(screen.queryByRole('button', { name: 'Authorize workflow' })).not.toBeInTheDocument();
} else {
expect(screen.queryByRole('button', { name: 'Authorize workflow' })).not.toBeInTheDocument();
expect(guidance.command ? screen.getByText(guidance.command) : screen.getByText(/personal access token, which can't be updated/)).toBeInTheDocument();
}
expect(startUpdate).toHaveBeenCalledTimes(1);
fireEvent.click(screen.getByRole('button', { name: 'Sync fork & update app' }));
fireEvent.click(await screen.findByRole('button', { name: 'Sync fork and update' }));
expect(startUpdate).toHaveBeenLastCalledWith('app-example', 'Example App', { syncFork: true });
expect(startUpdate).toHaveBeenCalledTimes(2);
});
// Eidoverse's video checkout is cloned from `anima-research`'s fork of a third
// project. The drift from upstream is real and worth reporting, but PortOS can
// only read that fork — so the panel must say so instead of offering a sync
// that would 403 and a badge that reads like a pending chore (#6321).
it('reports a read-only fork\'s drift without offering a sync it cannot perform', async () => {
const status = canonicalStatus();
status.updateAvailable = false;
status.sources[0] = source({
id: 'primary',
label: 'Example App',
branch: 'main',
head: '1'.repeat(40),
origin: { fullName: 'anima-research/example-app', isUpstream: true, isFork: false },
});
status.sources[1] = source({
id: 'companion-1',
label: 'example-runtime',
branch: 'prod-serving',
head: '2'.repeat(40),
origin: {
fullName: 'other-owner/example-runtime',
isUpstream: false,
isFork: true,
canPush: false,
},
forkVsUpstream: { available: true, ahead: 0, behind: 12, state: 'behind', error: null },
});
api.getAppRepositorySources.mockResolvedValue(status);
render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
const companion = await screen.findByTestId('repository-source-companion-1');
expect(companion).toHaveTextContent('Fork is 12 commits behind');
expect(companion).toHaveTextContent('cannot push to it');
// Not "Fork 12 behind": that badge is a call to action, and there is none.
expect(within(companion).getByText('Custom origin')).toBeInTheDocument();
expect(screen.queryByRole('button', { name: 'Sync fork' })).toBeNull();
expect(screen.getByText('All checkouts are current.')).toBeInTheDocument();
});
it('confirms that one managed update syncs the fork and updates every checkout', async () => {
const status = canonicalStatus();
status.sources[0] = source({
id: 'primary',
label: 'Example App',
branch: 'main',
head: '1'.repeat(40),
origin: {
fullName: 'example-owner/example-app',
isUpstream: false,
isFork: true,
},
forkVsUpstream: { available: true, ahead: 0, behind: 2, state: 'behind', error: null },
});
api.getAppRepositorySources.mockResolvedValue(status);
const onUpdated = vi.fn();
render(<RepositorySourcePanel appId="app-example" appName="Example App" onUpdated={onUpdated} />);
fireEvent.click(await screen.findByRole('button', { name: 'Sync fork & update app' }));
const dialog = await screen.findByRole('dialog');
expect(dialog).toHaveTextContent('Pull 1 independent companion checkout');
expect(dialog).toHaveTextContent('Rebuild the production UI when a build script is configured');
expect(dialog).toHaveTextContent('Restart the app\'s managed processes');
fireEvent.click(screen.getByRole('button', { name: 'Sync fork and update' }));
await waitFor(() => expect(useAppOperation.mock.results[0].value.startUpdate).toHaveBeenCalledWith(
'app-example', 'Example App', { syncFork: true },
));
expect(api.syncAppRepositoryFork).not.toHaveBeenCalled();
expect(onUpdated).not.toHaveBeenCalled();
});
it('refreshes source status when the parent Git tab reports a branch update', async () => {
const currentStatus = canonicalStatus();
currentStatus.updateAvailable = false;
currentStatus.sources[0] = source({
id: 'primary',
label: 'Example App',
branch: 'main',
head: '3'.repeat(40),
origin: {
fullName: 'anima-research/example-app',
isUpstream: true,
isFork: false,
},
});
api.getAppRepositorySources
.mockResolvedValueOnce(canonicalStatus())
.mockResolvedValueOnce(currentStatus);
const { rerender } = render(
<RepositorySourcePanel appId="app-example" appName="Example App" refreshKey={0} />,
);
expect(await screen.findByText('Checkout 1 behind')).toBeInTheDocument();
rerender(<RepositorySourcePanel appId="app-example" appName="Example App" refreshKey={1} />);
await waitFor(() => expect(api.getAppRepositorySources).toHaveBeenCalledTimes(2));
await waitFor(() => expect(screen.getByTestId('repository-source-primary')).toHaveTextContent('Current'));
});
it('locks the update action after dispatch until the page reloads', async () => {
render(<RepositorySourcePanel appId="portos-default" appName="PortOS" />);
fireEvent.click(await screen.findByRole('button', { name: 'Update app' }));
fireEvent.click(within(await screen.findByRole('dialog')).getByRole('button', { name: 'Update app' }));
const updateButton = screen.getByRole('button', { name: 'Reload to update again' });
expect(updateButton).toBeDisabled();
expect(useAppOperation.mock.results[0].value.startUpdate).toHaveBeenCalledWith(
'portos-default', 'PortOS', { syncFork: false },
);
});
it('re-checks sources and unlocks the update button when a managed app update completes', async () => {
let complete;
useAppOperation.mockImplementation(({ onComplete }) => {
complete = onComplete;
return { ...useAppOperation.mock.results[0]?.value, steps: [], isOperating: false, startUpdate: vi.fn(), restarting: false };
});
render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
fireEvent.click(await screen.findByRole('button', { name: 'Update app' }));
fireEvent.click(within(await screen.findByRole('dialog')).getByRole('button', { name: 'Update app' }));
expect(await screen.findByRole('button', { name: 'Reload to update again' })).toBeDisabled();
const calls = api.getAppRepositorySources.mock.calls.length;
act(() => complete());
await waitFor(() => expect(api.getAppRepositorySources.mock.calls.length).toBe(calls + 1));
expect(await screen.findByRole('button', { name: 'Update app' })).toBeEnabled();
expect(screen.queryByRole('button', { name: 'Reload to update again' })).toBeNull();
});
it('refuses automatic fork sync after divergence but still permits updating from the fork as-is', async () => {
const status = canonicalStatus();
status.sources[0] = source({
id: 'primary',
label: 'Example App',
branch: 'main',
head: '1'.repeat(40),
origin: {
fullName: 'example-owner/example-app',
isUpstream: false,
isFork: true,
},
forkVsUpstream: { available: true, ahead: 1, behind: 2, state: 'diverged', error: null },
});
api.getAppRepositorySources.mockResolvedValue(status);
render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
expect(await screen.findByRole('button', { name: 'Fork needs reconciliation' })).toBeDisabled();
fireEvent.click(screen.getByRole('button', { name: 'Update app from fork' }));
fireEvent.click(await screen.findByRole('button', { name: 'Update app' }));
await waitFor(() => expect(useAppOperation.mock.results[0].value.startUpdate).toHaveBeenCalledOnce());
expect(api.syncAppRepositoryFork).not.toHaveBeenCalled();
});
it('never reports current when the fork-to-upstream comparison failed', async () => {
const status = canonicalStatus();
status.updateAvailable = false;
status.sources[0] = source({
id: 'primary',
label: 'Example App',
branch: 'main',
head: '1'.repeat(40),
origin: {
fullName: 'example-owner/example-app',
isUpstream: false,
isFork: true,
},
forkVsUpstream: {
available: false,
ahead: null,
behind: null,
state: 'unknown',
error: 'Could not compare the fork with canonical upstream',
},
});
api.getAppRepositorySources.mockResolvedValue(status);
render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
const primary = await screen.findByTestId('repository-source-primary');
expect(primary).toHaveTextContent('Upstream check unavailable');
expect(primary).toHaveTextContent('fork freshness is unknown');
expect(screen.getByText('Remote freshness is unknown; a managed update can retry the source checkouts.')).toBeInTheDocument();
});
it('offers to update from a fork as-is after a FORK_SYNC_REQUIRED refusal', async () => {
useAppOperation.mockReturnValue({
steps: [], isOperating: false, operationType: 'update',
error: 'Running from a fork (alice/PortOS). Sync your fork first, or acknowledge.',
errorCode: 'FORK_SYNC_REQUIRED', completed: false,
startUpdate: vi.fn(),
});
render(<RepositorySourcePanel appId="portos-default" appName="PortOS" />);
const retryButton = await screen.findByRole('button', { name: 'Update from fork as-is' });
fireEvent.click(retryButton);
expect(useAppOperation.mock.results[0].value.startUpdate).toHaveBeenCalledWith(
'portos-default', 'PortOS', { acknowledgeFork: true },
);
});
it('offers to update anyway after a PERSISTENT_MIND_IMAGES_IN_FLIGHT refusal', async () => {
useAppOperation.mockReturnValue({
steps: [], isOperating: false, operationType: 'update',
error: 'Persistent Mind has 1 queued image message.',
errorCode: 'PERSISTENT_MIND_IMAGES_IN_FLIGHT', completed: false,
startUpdate: vi.fn(),
});
render(<RepositorySourcePanel appId="portos-default" appName="PortOS" />);
const retryButton = await screen.findByRole('button', { name: 'Update anyway (back up first)' });
fireEvent.click(retryButton);
expect(useAppOperation.mock.results[0].value.startUpdate).toHaveBeenCalledWith(
'portos-default', 'PortOS', { acknowledgePersistentMindImageBackup: true },
);
});
it('does not offer an acknowledgement retry for a refusal with no acknowledgement (AGENTS_ACTIVE)', async () => {
useAppOperation.mockReturnValue({
steps: [], isOperating: false, operationType: 'update',
error: '1 CoS agent is running — updating would restart PortOS and sever it.',
errorCode: 'AGENTS_ACTIVE', completed: false,
startUpdate: vi.fn(),
});
render(<RepositorySourcePanel appId="portos-default" appName="PortOS" />);
await screen.findByText(/CoS agent is running/);
expect(screen.queryByRole('button', { name: 'Update from fork as-is' })).not.toBeInTheDocument();
expect(screen.queryByRole('button', { name: 'Update anyway (back up first)' })).not.toBeInTheDocument();
});
it('does not mislabel an undiscovered repository topology as a custom origin', async () => {
const status = canonicalStatus();
status.updateAvailable = false;
status.sources = [source({
id: 'primary',
label: 'Example App',
branch: 'main',
head: '1'.repeat(40),
origin: {
fullName: 'example-owner/example-app',
isUpstream: null,
isFork: false,
},
})];
api.getAppRepositorySources.mockResolvedValue(status);
render(<RepositorySourcePanel appId="app-example" appName="Example App" />);
const primary = await screen.findByTestId('repository-source-primary');
expect(primary).toHaveTextContent('Upstream check unavailable');
expect(primary).not.toHaveTextContent('Custom origin');
expect(screen.getByRole('button', { name: 'Update app' })).toBeInTheDocument();
});
});
describe('PortOS self-update restart handoff', () => {
it('swaps the banner copy to the restart notice once useAppOperation reports it', async () => {
// The detection itself lives in useAppOperation (see its own suite). What
// this panel owes the user is telling them the page will come back rather
// than leaving "Stopping PortOS apps..." on screen with no explanation.
useAppOperation.mockReturnValue({
steps: [{ step: 'pm2-stop', status: 'running', message: 'Stopping PortOS apps...' }],
isOperating: true, operationType: 'update', error: null, errorCode: null, completed: false,
restarting: true,
startUpdate: vi.fn(),
});
render(<RepositorySourcePanel appId="portos-default" appName="PortOS" />);
expect(await screen.findByText(
'PortOS is restarting — this page reloads once it answers again.',
)).toBeInTheDocument();
// Every action stays locked while the install is coming back.
expect(screen.getByRole('button', { name: 'Check sources' })).toBeDisabled();
});
});
it('replaces unsafe dirty-checkout updates with an explicitly configured recovery task', async () => {
const status = canonicalStatus();
status.sources[0].clean = false;
api.getAppRepositorySources.mockResolvedValue(status);
api.getProviders.mockResolvedValue({ activeProvider: 'example-cli', providers: [{ id: 'example-cli', name: 'Example CLI', type: 'cli', enabled: true, models: ['example-model'], defaultModel: 'example-model' }] });
api.addCosTask.mockResolvedValue({ id: 'task-example' });
render(<MemoryRouter><RepositorySourcePanel appId="app-example" appName="Example App" /></MemoryRouter>);
fireEvent.click(await screen.findByRole('button', { name: 'Resolve with agent' }));
expect(screen.queryByRole('button', { name: 'Update app' })).not.toBeInTheDocument();
expect(api.addCosTask).not.toHaveBeenCalled();
const start = screen.getByRole('button', { name: 'Start recovery agent' });
await awaitEnabled(start);
fireEvent.change(screen.getByLabelText('Model'), { target: { value: 'example-model' } });
fireEvent.click(start);
await screen.findByRole('link', { name: 'Recovery queued · View agents' });
expect(api.addCosTask).toHaveBeenCalledWith(expect.objectContaining({ app: 'app-example', provider: 'example-cli', model: 'example-model', useWorktree: false, openPR: false, workflow: 'app-checkout-recovery', prompt: expect.stringMatching(/including untracked files and the index[\s\S]*never an acceptable resting place[\s\S]*empty stash list/) }), { silent: true });
expect(useAppOperation().startUpdate).not.toHaveBeenCalled();
});