Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { renderHook, render, act, cleanup } from '@testing-library/react';
import { MemoryRouter } from 'react-router';
import { Terminal } from '@xterm/xterm';
// Capture the socket handlers the hook registers so the test can drive the
// shell:* protocol, and record every emit so we can assert the client half of
// the attach/detach contract. The terminal-init effect is a no-op here (its
// `terminalRef` DOM node is never attached in renderHook), so the socket/session
// logic runs without a real xterm instance.
// Hoisted so the vi.mock factory (itself hoisted to the top of the file) can
// reference the same objects the tests drive.
const { handlers, emitted, socketMock } = vi.hoisted(() => {
const handlers = new Map();
const emitted = [];
const socketMock = {
connected: true,
on: (event, fn) => { handlers.set(event, fn); },
off: (event, fn) => { if (handlers.get(event) === fn) handlers.delete(event); },
emit: (event, ...args) => { emitted.push([event, ...args]); },
};
return { handlers, emitted, socketMock };
});
vi.mock('../services/socket', () => ({ default: socketMock }));
vi.mock('../components/ThemeContext', () => ({
useThemeContext: () => ({ themeId: 'test', theme: { mode: 'night' } }),
}));
const { readFileAsBase64, sendShellImage, toastMock } = vi.hoisted(() => ({
readFileAsBase64: vi.fn(),
sendShellImage: vi.fn(),
toastMock: { error: vi.fn(), success: vi.fn() },
}));
vi.mock('../utils/fileUpload', () => ({ readFileAsBase64 }));
vi.mock('../services/api', () => ({ sendShellImage }));
vi.mock('../components/ui/Toast', () => ({ default: toastMock }));
import { useShellSession, MAX_SESSIONS } from './useShellSession.js';
import { MAX_TOTAL_SESSIONS } from '../../../server/lib/shellLimits.js';
const wrapper = ({ children }) => (
<MemoryRouter initialEntries={['/shell']}>{children}</MemoryRouter>
);
const fire = (event, payload) => act(() => { handlers.get(event)?.(payload); });
const lastEmit = (event) => [...emitted].reverse().find(([e]) => e === event);
const session = (id, over = {}) => ({ sessionId: id, attached: false, external: false, createdAt: Date.now(), ...over });
// Render with `list` live and the view attached to `activeId`.
const attachedTo = (activeId, list) => {
const rendered = renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', list);
fire('shell:attached', { sessionId: activeId, bufferedOutput: '' });
return rendered;
};
describe('useShellSession', () => {
beforeEach(() => { handlers.clear(); emitted.length = 0; socketMock.connected = true; });
afterEach(cleanup);
it('requests the session list on mount when the socket is already connected', () => {
renderHook(() => useShellSession({}), { wrapper });
expect(emitted).toContainEqual(['shell:list']);
});
it('auto-starts a fresh session when the list is empty and the user is not idle', () => {
renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', []);
expect(lastEmit('shell:start')).toBeTruthy();
});
// #8708: a remote socket on a password-free install is refused its very
// first shell:list, which no pending request correlates with — the refusal
// must still surface instead of leaving the page waiting.
it('surfaces a host-control refusal of the uncorrelated list request', () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
expect(result.current.hostControlForbidden).toBe(false);
fire('shell:error', { code: 'HOST_CONTROL_FORBIDDEN', error: 'Set an instance password to use it remotely.' });
expect(result.current.hostControlForbidden).toBe(true);
});
it('activates a started session and marks it connected', () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', []); // → startSession, pending target 'new'
fire('shell:started', { sessionId: 'abc' });
expect(result.current.activeSessionId).toBe('abc');
expect(result.current.connected).toBe(true);
});
it('sends Ctrl+B to the active terminal session', () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', []);
fire('shell:started', { sessionId: 'abc' });
act(() => result.current.sendCtrlB());
expect(lastEmit('shell:input')).toEqual(['shell:input', { sessionId: 'abc', data: '\x02' }]);
});
it('sends Escape to the active terminal session', () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', []);
fire('shell:started', { sessionId: 'abc' });
act(() => result.current.sendEsc());
expect(lastEmit('shell:input')).toEqual(['shell:input', { sessionId: 'abc', data: '\x1b' }]);
});
// cd goes over its own event carrying the PATH — the server owns the quoting,
// because only it knows whether the session runs cmd.exe, PowerShell, or a
// POSIX shell (the hard-coded POSIX form was unusable on Windows).
it('sends the folder path over shell:cd rather than composing a cd command', () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', []);
fire('shell:started', { sessionId: 'abc' });
act(() => result.current.sendCd('I:\\code\\example-app'));
expect(lastEmit('shell:cd')).toEqual(['shell:cd', { sessionId: 'abc', path: 'I:\\code\\example-app' }]);
});
// LF would leave the command typed-but-unexecuted on cmd.exe — see SUBMIT_KEY.
it('submits a quick command with a carriage return, not a line feed', () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', []);
fire('shell:started', { sessionId: 'abc' });
act(() => result.current.sendCommand('claude'));
expect(lastEmit('shell:input')).toEqual(['shell:input', { sessionId: 'abc', data: 'claude\r' }]);
});
it('ignores a shell:attached whose id does not match the pending target (strict-equality guard)', () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
// First load with one free survivor → auto-attach to s1 (claim:true), pending target 's1'.
fire('shell:sessions', [session('s1')]);
expect(lastEmit('shell:attach')).toEqual(['shell:attach', { sessionId: 's1', claim: true }]);
// A stale/mismatched attach response must not activate.
fire('shell:attached', { sessionId: 'other', bufferedOutput: '' });
expect(result.current.activeSessionId).toBeNull();
// The matching response activates.
fire('shell:attached', { sessionId: 's1', bufferedOutput: '' });
expect(result.current.activeSessionId).toBe('s1');
});
it('drops the active view when the server detaches the displayed session', () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', [session('s1')]);
fire('shell:attached', { sessionId: 's1', bufferedOutput: '' });
expect(result.current.activeSessionId).toBe('s1');
fire('shell:detached', { sessionId: 's1', reason: 'attached-elsewhere' });
expect(result.current.activeSessionId).toBeNull();
expect(result.current.connected).toBe(false);
});
it('surfaces derived counts and the active session', () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', [session('s1'), session('run1', { external: true })]);
fire('shell:attached', { sessionId: 's1', bufferedOutput: '' });
expect(result.current.interactiveCount).toBe(1);
expect(result.current.liveRunCount).toBe(1);
expect(result.current.isLiveRun).toBe(false);
expect(result.current.activeSession?.sessionId).toBe('s1');
});
it('exports the shell session cap', () => {
expect(MAX_SESSIONS).toBe(MAX_TOTAL_SESSIONS);
});
// Losing the session you are looking at must not strand you on a dead terminal
// while other live shells sit one click away in the tab strip. Every trigger —
// user close, exit, takeover — goes through the one recovery path.
describe('recovering the displayed session', () => {
it('activates the next free shell when the user stops the active session', () => {
const { result } = attachedTo('s2', [session('s1'), session('s2')]);
act(() => result.current.stopSession());
expect(lastEmit('shell:stop')).toEqual(['shell:stop', { sessionId: 's2' }]);
// Auto-pick, so claim:true — a multi-tab race must not boot another tab.
expect(lastEmit('shell:attach')).toEqual(['shell:attach', { sessionId: 's1', claim: true }]);
fire('shell:attached', { sessionId: 's1', bufferedOutput: '' });
expect(result.current.activeSessionId).toBe('s1');
expect(result.current.connected).toBe(true);
});
it('activates the next free shell when the user kills the active tab', () => {
const { result } = attachedTo('s2', [session('s1'), session('s2')]);
act(() => result.current.killOtherSession('s2'));
expect(lastEmit('shell:attach')).toEqual(['shell:attach', { sessionId: 's1', claim: true }]);
});
it('leaves the view alone when the killed tab is not the active one', () => {
const { result } = attachedTo('s2', [session('s1'), session('s2')]);
emitted.length = 0;
act(() => result.current.killOtherSession('s1'));
expect(lastEmit('shell:attach')).toBeUndefined();
expect(result.current.activeSessionId).toBe('s2');
});
// A session that dies on its own reaches the same recovery, and the takeover
// path must not depend on the server's follow-up broadcast to recover.
it('attaches to a free survivor when the displayed session exits on its own', () => {
const { result } = attachedTo('s2', [session('s1'), session('s2')]);
emitted.length = 0;
fire('shell:exit', { sessionId: 's2', code: 0 });
expect(result.current.activeSessionId).toBeNull();
expect(lastEmit('shell:attach')).toEqual(['shell:attach', { sessionId: 's1', claim: true }]);
});
it('attaches to a free survivor when another tab takes the displayed session', () => {
const { result } = attachedTo('s2', [session('s1'), session('s2')]);
emitted.length = 0;
fire('shell:detached', { sessionId: 's2', reason: 'attached-elsewhere' });
expect(result.current.activeSessionId).toBeNull();
expect(lastEmit('shell:attach')).toEqual(['shell:attach', { sessionId: 's1', claim: true }]);
});
it('stays put when nothing free is left to switch to', () => {
// s1 is driving another tab and run1 is an external TUI run — neither is a
// safe auto-pick, so the user genuinely has nowhere to land.
const { result } = attachedTo('s2', [
session('s1', { attached: true }),
session('run1', { external: true }),
session('s2'),
]);
emitted.length = 0;
act(() => result.current.stopSession());
expect(lastEmit('shell:attach')).toBeUndefined();
expect(result.current.activeSessionId).toBeNull();
expect(result.current.connected).toBe(false);
});
// A reconnect re-runs the initial-load branch, which is the one that spawns.
// Respawning there would make Stop a no-op, so the close has to suppress it.
it('does not spawn a replacement on reconnect after the user stopped their last shell', () => {
const { result } = attachedTo('s1', [session('s1')]);
act(() => result.current.stopSession());
emitted.length = 0;
fire('connect');
fire('shell:sessions', []);
expect(lastEmit('shell:start')).toBeUndefined();
});
// Same reconnect, but a free shell exists: adoption is not what's suppressed.
it('does adopt a free shell on reconnect after a stop', () => {
const { result } = attachedTo('s1', [session('s1')]);
act(() => result.current.stopSession());
emitted.length = 0;
fire('connect');
fire('shell:sessions', [session('s9')]);
expect(lastEmit('shell:attach')).toEqual(['shell:attach', { sessionId: 's9', claim: true }]);
});
// The flag a close leaves behind suppresses spawning, NOT adoption: a shell
// freed by another tab afterwards must still land, or the user is stuck on
// "Disconnected" with a live shell one click away.
it('adopts a shell that frees up after a close left nothing to switch to', () => {
const { result } = attachedTo('s2', [session('s1', { attached: true }), session('s2')]);
act(() => result.current.stopSession());
emitted.length = 0;
fire('shell:sessions', [session('s1')]); // the other tab let go of s1
expect(lastEmit('shell:attach')).toEqual(['shell:attach', { sessionId: 's1', claim: true }]);
});
});
// The Shell page's provider launch menu. The ID is what crosses the wire —
// the server pairs it with the provider's own env, which a typed command line
// would leave behind (and which is secret, so it can't cross at all).
describe('launchProvider', () => {
it('starts a new session by provider ID, inheriting the displayed cwd', () => {
const { result } = attachedTo('s1', [session('s1', { cwd: '/repos/example-app' })]);
act(() => { result.current.launchProvider('claude-code-tui'); });
expect(lastEmit('shell:start')).toEqual([
'shell:start', { cwd: '/repos/example-app', providerId: 'claude-code-tui' },
]);
});
it('omits cwd when the displayed session reports none', () => {
const { result } = attachedTo('s1', [session('s1')]);
act(() => { result.current.launchProvider('codex-tui'); });
expect(lastEmit('shell:start')).toEqual(['shell:start', { providerId: 'codex-tui' }]);
});
it('never emits — and never arms a stale launch — without a provider id', () => {
const { result } = attachedTo('s1', [session('s1')]);
const before = emitted.length;
act(() => { result.current.launchProvider(''); });
expect(emitted.length).toBe(before);
// The id must not have been parked in the pending-opts slot either: a
// later plain "New" would otherwise spawn the provider instead of a shell.
act(() => { result.current.startNewSession(); });
expect(lastEmit('shell:start')).toEqual(['shell:start', undefined]);
});
});
// Restart asks for a *replacement* shell, so it must not run the survivor
// adoption path even when another shell is free.
describe('restartSession', () => {
it('starts a fresh shell rather than adopting a survivor', () => {
vi.useFakeTimers();
const { result } = attachedTo('s2', [session('s1'), session('s2')]);
emitted.length = 0;
act(() => result.current.restartSession());
expect(lastEmit('shell:stop')).toEqual(['shell:stop', { sessionId: 's2' }]);
expect(lastEmit('shell:attach')).toBeUndefined();
// The reserved 'new' pending slot keeps the post-stop broadcast from
// adopting s1 into the gap.
fire('shell:sessions', [session('s1')]);
expect(lastEmit('shell:attach')).toBeUndefined();
act(() => { vi.advanceTimersByTime(1000); });
expect(lastEmit('shell:start')).toBeTruthy();
vi.useRealTimers();
});
it('aborts the deferred start when the user switches sessions inside the window', () => {
vi.useFakeTimers();
const { result } = attachedTo('s2', [session('s1'), session('s2')]);
act(() => result.current.restartSession());
emitted.length = 0;
act(() => result.current.switchToSession('s1'));
act(() => { vi.advanceTimersByTime(1000); });
expect(lastEmit('shell:start')).toBeUndefined();
expect(lastEmit('shell:attach')).toEqual(['shell:attach', { sessionId: 's1' }]);
vi.useRealTimers();
});
});
// sendImage goes over HTTP, not the shell:* socket protocol — socket.io's 1MB
// frame limit can't carry a photo, and it needs a result.
describe('sendImage', () => {
const photo = new File(['x'], 'photo.jpg', { type: 'image/jpeg' });
const activeHook = () => {
const rendered = renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', []);
fire('shell:started', { sessionId: 'abc' });
return rendered;
};
beforeEach(() => {
readFileAsBase64.mockReset().mockResolvedValue('Zm9v');
sendShellImage.mockReset().mockResolvedValue({ sessionId: 'abc', filename: 'shell-aa11bb22-photo.jpg' });
toastMock.error.mockReset();
toastMock.success.mockReset();
});
it('posts the bytes to the active session and resolves true', async () => {
const { result } = activeHook();
await expect(result.current.sendImage(photo, 'what is this?')).resolves.toBe(true);
// `silent` because this hook owns the error toast — otherwise the user sees two.
expect(sendShellImage).toHaveBeenCalledWith(
'abc',
{ data: 'Zm9v', filename: 'photo.jpg', message: 'what is this?' },
{ silent: true },
);
expect(toastMock.success).toHaveBeenCalled();
});
it('resolves false and toasts when the server rejects the send', async () => {
sendShellImage.mockRejectedValue(new Error('Session not found'));
const { result } = activeHook();
await expect(result.current.sendImage(photo, 'hi')).resolves.toBe(false);
expect(toastMock.error).toHaveBeenCalledWith(expect.stringContaining('Session not found'));
expect(toastMock.success).not.toHaveBeenCalled();
});
it('resolves false without posting when the file cannot be read', async () => {
readFileAsBase64.mockRejectedValue(new Error('boom'));
const { result } = activeHook();
await expect(result.current.sendImage(photo, 'hi')).resolves.toBe(false);
expect(sendShellImage).not.toHaveBeenCalled();
});
it('refuses to send when there is no active session', async () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
await expect(result.current.sendImage(photo, 'hi')).resolves.toBe(false);
expect(readFileAsBase64).not.toHaveBeenCalled();
});
// Mid-switch the terminal has been cleared and the pending target is another
// session — a send here would land in the session the user is leaving.
it('refuses to send while an attach is in flight', async () => {
const { result } = renderHook(() => useShellSession({}), { wrapper });
fire('shell:sessions', [session('s1')]);
fire('shell:attached', { sessionId: 's1', bufferedOutput: '' });
act(() => result.current.switchToSession('s2'));
await expect(result.current.sendImage(photo, 'hi')).resolves.toBe(false);
expect(readFileAsBase64).not.toHaveBeenCalled();
});
});
// The `?cmd=` deep link is a contract with every page that links INTO the
// shell — the AI Providers card's "Launch in Shell" button, the GSD/Apps
// "open claude here" buttons. If this hook stopped consuming the param the
// buttons would silently drop the user at a bare prompt with no error, so pin
// that the query param reaches the server as `shell:start { initialCommand }`.
describe('?cmd= / ?cwd= / ?provider= deep links', () => {
const at = (entry) => ({ children }) => (
<MemoryRouter initialEntries={[entry]}>{children}</MemoryRouter>
);
it('starts a new session carrying the ?cmd= line as initialCommand', () => {
const cmd = 'codex --dangerously-bypass-approvals-and-sandbox --model gpt-5';
renderHook(() => useShellSession({}), { wrapper: at(`/shell?cmd=${encodeURIComponent(cmd)}`) });
fire('shell:sessions', []);
expect(lastEmit('shell:start')).toEqual(['shell:start', { initialCommand: cmd }]);
});
it('starts a NEW session rather than adopting a live one, so the command actually runs', () => {
renderHook(() => useShellSession({}), { wrapper: at('/shell?cmd=claude&cwd=%2Ftmp%2Fapp') });
fire('shell:sessions', [session('already-running')]);
expect(lastEmit('shell:start')).toEqual(['shell:start', { cwd: '/tmp/app', initialCommand: 'claude' }]);
expect(lastEmit('shell:attach')).toBeUndefined();
});
// The AI Providers card links by provider ID so the SERVER can pair the
// command with that provider's env (its backend/auth live in secret
// envVars). If the hook dropped the param, the shell would open at a bare
// prompt and the button would look broken with no error anywhere.
it('forwards ?provider= to the server as shell:start { providerId }', () => {
renderHook(() => useShellSession({}), { wrapper: at('/shell?provider=claude-ollama-tui') });
fire('shell:sessions', []);
expect(lastEmit('shell:start')).toEqual(['shell:start', { providerId: 'claude-ollama-tui' }]);
});
it('sends no command of its own for a provider launch — the server owns it', () => {
renderHook(() => useShellSession({}), { wrapper: at('/shell?provider=codex') });
fire('shell:sessions', [session('already-running')]);
const [, opts] = lastEmit('shell:start');
expect(opts.initialCommand).toBeUndefined();
expect(lastEmit('shell:attach')).toBeUndefined();
});
});
// The terminal-init effect only runs when `terminalRef` is attached, which the
// socket-level tests above never do — so these mount a probe component that
// renders a real host <div>. That constructs a REAL Terminal, which is what
// makes the keyboard-trap assertions meaningful: xterm's own `_keyDown` either
// cancels the keydown (trapping focus) or releases it for the browser's
// default backtab. See issue #7262 (WCAG 2.1.2) — without the custom handler,
// Tab/Shift+Tab/Escape are all swallowed by the textarea.
describe('terminal accessibility', () => {
let attachSpy;
const mountShellTerminal = () => {
attachSpy = vi.spyOn(Terminal.prototype, 'attachCustomKeyEventHandler');
const Probe = () => {
const { terminalRef } = useShellSession({});
return <div ref={terminalRef} />;
};
const rendered = render(<Probe />, { wrapper });
return { term: attachSpy.mock.contexts[0], host: rendered.container.firstChild };
};
afterEach(() => attachSpy?.mockRestore());
it('constructs the terminal with screenReaderMode, so output reaches a live region', () => {
const { term, host } = mountShellTerminal();
// Pin the option itself — a future options rewrite must not silently drop it.
expect(term.options.screenReaderMode).toBe(true);
// Its observable effect: the .xterm-accessibility live region only exists
// under screenReaderMode; without it every rendered row is aria-hidden.
expect(host.querySelector('.xterm-accessibility .live-region')).toBeTruthy();
});
it('installs a custom key handler that releases Shift+Tab but keeps Tab for the shell', () => {
mountShellTerminal();
expect(attachSpy).toHaveBeenCalledTimes(1);
const handler = attachSpy.mock.calls[0][0];
// Shift+Tab is the documented focus-escape gesture — false tells xterm not
// to process the event at all, so the browser performs the backtab.
expect(handler({ key: 'Tab', shiftKey: true })).toBe(false);
// Plain Tab stays claimed — it is shell completion.
expect(handler({ key: 'Tab', shiftKey: false })).toBe(true);
// Escape is NOT the way out: TUIs bind it, so it must keep reaching the PTY.
expect(handler({ key: 'Escape', shiftKey: false })).toBe(true);
});
it('lets a Shift+Tab keydown through uncancelled so focus can leave the terminal', () => {
const { term } = mountShellTerminal();
// Input only reaches the socket once a session is attached.
fire('shell:sessions', []);
fire('shell:started', { sessionId: 'abc' });
emitted.length = 0;
const backtab = new KeyboardEvent('keydown', { key: 'Tab', keyCode: 9, shiftKey: true, cancelable: true });
term.textarea.dispatchEvent(backtab);
expect(backtab.defaultPrevented).toBe(false);
// The escape must also be clean: without the custom handler, SR mode still
// releases the key but fires ESC[Z into the PTY (zsh reads it as reverse
// completion). The early return sends nothing.
expect(emitted).toHaveLength(0);
// The control case: plain Tab is still claimed and reaches the PTY as
// completion input.
const complete = new KeyboardEvent('keydown', { key: 'Tab', keyCode: 9, cancelable: true });
term.textarea.dispatchEvent(complete);
expect(complete.defaultPrevented).toBe(true);
expect(lastEmit('shell:input')).toEqual(['shell:input', { sessionId: 'abc', data: '\t' }]);
});
});
});