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 { useEffect, useRef, useState, useCallback } from 'react';
import useMounted from './useMounted';
import { useSearchParams, useParams, useNavigate } from 'react-router';
import { useSocket } from './useSocket';
import { useThemeContext } from '../components/ThemeContext';
import { createShellTerminal, readTerminalTheme } from '../components/shell/createShellTerminal';
import { attachDictationBridge } from '../lib/terminalDictation';
import { fitTerminal } from '../lib/terminalFit';
import {
attachTerminalTouchScroll,
attachTerminalWheelScroll,
resetTerminalWheelScroll,
scrollTerminalPage,
} from '../lib/terminalScroll';
import { readFileAsBase64 } from '../utils/fileUpload';
import * as api from '../services/api';
import toast from '../components/ui/Toast';
import { MAX_TOTAL_SESSIONS } from '../../../server/lib/shellLimits.js';
// Shared with the server (lib/shellLimits.js) so the "at cap" UI can't drift.
export const MAX_SESSIONS = MAX_TOTAL_SESSIONS;
// recoverToSurvivor's no-op fallback, for the one caller already sitting at bare
// /shell and content to stay there when nothing is free to adopt.
const STAY_PUT = () => {};
/**
* useShellSession — all socket/session/terminal state and lifecycle for the Shell
* page, extracted so the route component (`pages/Shell.jsx`) stays thin and purely
* presentational (the WritersRoom pattern). The hook owns the xterm instance, the
* Socket.IO shell:* protocol, and every attach/detach/generation guard.
*
* ── Attach/detach contract (single-subscriber PTY sessions) ─────────────────────
* The server (`server/services/shell.js`) stores ONE attached socket per PTY session
* and fans output to it. This hook implements the client half of that contract:
*
* • pendingAttachRef = { target, generation } tracks the in-flight start/attach.
* - `target`: the requested session id, the sentinel 'new' (shell:start, id not
* yet known), or null (nothing pending OR the request was cancelled mid-flight).
* - `generation`: monotonically bumped on every state change (start, attach,
* success-consume, cancel, error). Deferred work (setTimeout fallbacks) captures
* the generation and aborts if it advanced — so a user action during the delay
* window can't be clobbered by a stale timer.
* Response handlers gate on STRICT equality with `target`: a null/stale target
* falls through, so a cancelled-during-pending response can never re-activate.
*
* • claim:true on shell:attach → server refuses to displace a DIFFERENT socket.
* Auto-pick paths (survivor adoption, exit/error recovery) send claim:true so a
* multi-tab broadcast race can't boot another tab via shell:detached. User-intent
* paths (tab click, deep-link URL) default to claim:false so explicit intent wins.
*
* • shell:detached — the server tells the previously-attached socket its session was
* taken over; we drop the dead local view rather than appear "Connected" forever.
*
* • recoverToSurvivor(excludeId, onNothing) — the ONE recovery path. Every way the
* displayed session can go away (it exited, another tab took it over, it was
* killed externally, an attach failed, the user closed it) ends here, so a policy
* change lands once instead of in five near-copies. Callers vary only in what to
* do when nothing is free, which is the single knob.
*
* • suppressAutoStartRef — set when a user close leaves nothing to hand over, and
* cleared by every user-initiated start/attach. It suppresses only the paths that
* SPAWN a session: without it, stopping your last shell would immediately respawn
* one and make Stop a no-op. It deliberately does NOT suppress adopting an already
* live free session — being handed a working shell is never the thing we're
* suppressing, and sitting on "Disconnected" while one is free is precisely the
* broken state these recovery paths exist to prevent.
*
* • mountedRef — flipped false on unmount so a deferred (setTimeout) recovery attach
* short-circuits instead of claiming a session with no listener left to render it.
*
* `clearActiveSession()` clears only the DISPLAYED session — it never touches
* pendingAttachRef, because clearing the view and cancelling an in-flight request are
* separate concerns. Explicit cancellation paths call `cancelPendingAttach()` directly.
*
* @param {object} params
* @param {boolean} params.isFullscreen — presentational fullscreen flag; drives a
* one-shot refit when the terminal swaps between in-flow and fixed-overlay layout.
* @returns session state, terminal ref, and the session action callbacks the route
* renders against.
*/
export function useShellSession({ isFullscreen } = {}) {
const [searchParams, setSearchParams] = useSearchParams();
const { sessionId: urlSessionId } = useParams();
const navigate = useNavigate();
const terminalRef = useRef(null);
const termInstanceRef = useRef(null);
const sessionIdRef = useRef(null);
const initialOptsRef = useRef(null);
const hasInitializedRef = useRef(false);
// Mirror urlSessionId into a ref so callbacks (activateSession, handleSessions) can read the
// latest URL without forcing the heavy socket-listener effect to re-bind on every URL change.
const urlSessionIdRef = useRef(urlSessionId);
// Keep navigate in a ref so callbacks don't list it in deps — guarantees the socket-listener
// effect can't tear down on URL change even if router internals ever start returning a fresh
// navigate identity per render.
const navigateRef = useRef(navigate);
// Set to 'push' before any user-initiated switch (tab click, "New" button) so the next
// activateSession pushes a history entry; auto/URL-driven switches keep the 'replace' default.
const pendingNavIntentRef = useRef('replace');
// In-flight start/attach state: { target, generation }. See the attach/detach
// contract in the module doc comment above for the full semantics.
const pendingAttachRef = useRef({ target: null, generation: 0 });
// Flipped on unmount so deferred work (setTimeout-scheduled recovery attaches)
// can short-circuit instead of firing shell:attach from a teardown component —
// which would claim a session with no listener left to render it.
const mountedRef = useMounted();
// useCallback for stable identity so consumers can list these in dep arrays without
// causing useEffect re-binds on every render. They only touch a ref, so empty deps is correct.
const setPendingAttach = useCallback((target) => {
pendingAttachRef.current = { target, generation: pendingAttachRef.current.generation + 1 };
}, []);
const cancelPendingAttach = useCallback(() => setPendingAttach(null), [setPendingAttach]);
// Suppresses the session-SPAWNING branches only — see the module doc comment above
// for why adoption of an already-live free session is deliberately left enabled.
const suppressAutoStartRef = useRef(false);
const socket = useSocket();
const { themeId, theme: activeTheme } = useThemeContext();
const themeMode = activeTheme?.mode ?? 'night';
const [connected, setConnected] = useState(false);
const [sessions, setSessions] = useState([]);
const [activeSessionId, setActiveSessionId] = useState(null);
// Set when the server refuses the shell to this connection: a remote
// browser on a password-free install has no host-control authority (#8708).
const [hostControlForbidden, setHostControlForbidden] = useState(false);
const sessionsRef = useRef([]);
useEffect(() => { urlSessionIdRef.current = urlSessionId; }, [urlSessionId]);
useEffect(() => { navigateRef.current = navigate; }, [navigate]);
// Read query params once on mount for initial session options
useEffect(() => {
if (initialOptsRef.current) return;
const cwd = searchParams.get('cwd');
const cmd = searchParams.get('cmd');
const session = searchParams.get('session');
// `provider` is the AI Providers page's "Launch in Shell" hand-off. It sends
// an ID rather than a command line because the server has to pair the
// command with the provider's own env (its backend/auth live in secret
// `envVars` the client never sees) — see socket.js's shell:start handler.
const provider = searchParams.get('provider');
if (cwd || cmd || session || provider) {
initialOptsRef.current = { cwd, cmd, session, provider };
setSearchParams({}, { replace: true });
} else {
initialOptsRef.current = {};
}
}, []);
// The one place a shell:* event addressed at the ACTIVE session goes out, so the
// mid-attach guard can't be applied to one sender and forgotten on the next.
// focus:false skips returning keyboard focus to the terminal after sending — used by
// the nav-key hot buttons so repeated arrow taps on touch devices don't keep re-summoning
// the on-screen keyboard (input is delivered over the socket regardless of focus).
// Returns whether the payload actually went out — the dictation bridge needs to know,
// since it tracks what the PTY has received to compute its next correction.
const emitToSession = useCallback((event, payload, { focus = true } = {}) => {
if (!socket || !sessionIdRef.current) return false;
// Don't fire quick-commands into the prior session while a switch/start is mid-flight.
if (pendingAttachRef.current.target) return false;
socket.emit(event, { sessionId: sessionIdRef.current, ...payload });
if (focus) termInstanceRef.current?.focus();
return true;
}, [socket]);
const emitShellInput = useCallback(
(data, opts) => emitToSession('shell:input', { data }, opts),
[emitToSession]
);
// Send a photo (plus an optional message) to whatever is running in the active
// session — the point being a live `claude`/`codex` TUI, which reads images off
// disk. This one goes over HTTP, not the `shell:*` socket protocol: socket.io's
// 1MB frame limit can't carry a photo, and it's a one-shot request that needs a
// result. The server saves the bytes and bracket-pastes `<message>\n<path>` into
// the PTY; the path never comes back, so nothing here can leak the install layout.
//
// Resolves true only on success, so the caller can keep its composer open (with
// the user's message intact) to retry. Errors are toasted here — the guard
// refusals have no other error surface, so this owns all of them and the API call
// is `silent`.
const sendImage = useCallback(async (file, message = '') => {
if (!sessionIdRef.current) {
toast.error('No active shell session');
return false;
}
// Same guard as emitShellInput: a mid-switch send would land in the session
// the user is leaving.
if (pendingAttachRef.current.target) {
toast.error('Session is still attaching — try again in a moment');
return false;
}
// Capture the target BEFORE the read: a big photo takes a moment to encode, and
// the send belongs to the session the user was looking at when they hit Send —
// not to whichever one happens to be active by the time the bytes are ready.
const sessionId = sessionIdRef.current;
const data = await readFileAsBase64(file).catch(() => null);
if (!data) {
toast.error(`Failed to read ${file.name}`);
return false;
}
const sent = await api.sendShellImage(sessionId, { data, filename: file.name, message }, { silent: true })
.catch((err) => {
toast.error(`Failed to send image: ${err.message}`);
return null;
});
if (!sent) return false;
toast.success('Image sent to session');
return true;
}, []);
// CR, not LF — see SUBMIT_KEY in server/lib/tuiHandshake.js for why. Same byte as
// TerminalHotKeys' Enter key.
const sendCommand = useCallback((cmd) => emitShellInput(cmd + '\r'), [emitShellInput]);
// cd is the one "command" the client does NOT compose itself: it sends the folder and
// the server renders the `cd` for the session's actual shell (server/lib/shellCd.js).
const sendCd = useCallback((path) => emitToSession('shell:cd', { path }), [emitToSession]);
const sendCtrlB = useCallback(() => emitShellInput('\x02'), [emitShellInput]);
const sendCtrlC = useCallback(() => emitShellInput('\x03'), [emitShellInput]);
const sendEsc = useCallback(() => emitShellInput('\x1b'), [emitShellInput]);
// Arrow keys send CSI or SS3 based on the terminal's DECCKM state (see NAV_KEYS);
// Enter and any other literal-`seq` keys pass through unchanged. focus:false keeps the
// soft keyboard down on touch — these buttons exist to replace it, not trigger it.
const sendNavKey = useCallback((key) => {
if (key.seq != null) { emitShellInput(key.seq, { focus: false }); return; }
const appCursor = termInstanceRef.current?.modes?.applicationCursorKeysMode;
emitShellInput(`\x1b${appCursor ? 'O' : '['}${key.code}`, { focus: false });
}, [emitShellInput]);
// Scroll the VIEW by one screenful — distinct from the arrow keys above, which
// drive whatever the TUI does with a cursor key. `direction` is -1 for up, 1 for
// down; lib/terminalScroll.js owns why this can't just be term.scrollPages().
const scrollPage = useCallback((direction) => {
scrollTerminalPage(termInstanceRef.current, direction);
}, []);
// Initialize terminal once
useEffect(() => {
if (!terminalRef.current || termInstanceRef.current) return;
// Construction, theme, links and the Shift+Tab focus escape are shared with
// the iTerm2 view (components/shell/createShellTerminal.js).
const term = createShellTerminal(terminalRef.current);
// xterm binds no touch handlers of its own, so without this a swipe over the
// terminal does nothing. Alternate-screen TUIs need the matching wheel capture so
// one that never asked for mouse tracking gets its supported PageUp/PageDown
// bindings instead of a cursor key. See lib/terminalScroll.js. Attached here rather
// than in its own effect: neither handler has reactive deps, so both lifetimes are
// exactly the terminal instance's (unlike the dictation bridge, which needs
// emitShellInput).
const detachTouchScroll = attachTerminalTouchScroll(term);
const detachWheelScroll = attachTerminalWheelScroll(term);
// Deferred fit — cancelled in cleanup: an unmount inside the frame window
// would otherwise fit a disposed terminal (its _renderService.dimensions
// getter throws post-dispose — an uncaught error in a rAF callback).
const fitFrame = requestAnimationFrame(() => {
fitTerminal(term);
});
termInstanceRef.current = term;
return () => {
cancelAnimationFrame(fitFrame);
detachTouchScroll();
detachWheelScroll();
term.dispose();
termInstanceRef.current = null;
};
}, []);
// Re-skin the live terminal when the user switches themes. The terminal is
// created once (above), so without this the xterm palette would stay frozen at
// whatever theme was active on mount — most visibly, a dark terminal stranded in
// a daytime theme. Depends on themeId (catches sibling day↔day / night↔night
// swaps that change accent/bg) and themeMode (catches the day/night palette flip).
useEffect(() => {
if (termInstanceRef.current) {
termInstanceRef.current.options.theme = readTerminalTheme();
}
}, [themeId, themeMode]);
// Refit the terminal to its container and tell the PTY about the new size.
const refitTerminal = useCallback(() => {
const term = termInstanceRef.current;
if (!term) return;
fitTerminal(term);
if (socket && sessionIdRef.current) {
socket.emit('shell:resize', {
sessionId: sessionIdRef.current,
cols: term.cols,
rows: term.rows
});
}
}, [socket]);
// Handle window resize
useEffect(() => {
window.addEventListener('resize', refitTerminal);
return () => window.removeEventListener('resize', refitTerminal);
}, [refitTerminal]);
// Entering/leaving fullscreen swaps the terminal between the in-flow flex box and
// the fixed overlay — a big size change. The ResizeObserver below catches it too,
// but refit on the next frame so the new cols/rows reach the PTY immediately
// instead of waiting for the observer to settle.
useEffect(() => {
const frame = requestAnimationFrame(() => refitTerminal());
return () => cancelAnimationFrame(frame);
}, [isFullscreen, refitTerminal]);
// Refit whenever the terminal *container* changes size — not just the window.
// The toolbars (session tabs, live-run banner, quick-commands bar) mount
// conditionally on `connected`, which shrinks the flex-1 terminal box after the
// one-shot mount fit() has already run. Without re-fitting, xterm keeps its
// taller row count and overflows below the fold, hiding the prompt and breaking
// scrollback. A ResizeObserver catches every such reflow (the user's "resize the
// window and it appears" glitch). rAF-guarded so fit()'s own DOM mutation can't
// re-enter the observer in a tight loop.
useEffect(() => {
const el = terminalRef.current;
if (!el || typeof ResizeObserver === 'undefined') return;
let frame = null;
const observer = new ResizeObserver(() => {
if (frame != null) return;
frame = requestAnimationFrame(() => {
frame = null;
refitTerminal();
});
});
observer.observe(el);
return () => {
if (frame != null) cancelAnimationFrame(frame);
observer.disconnect();
};
}, [refitTerminal]);
// Handle terminal input. emitShellInput already owns the "don't land keystrokes in
// the session we're leaving" guard (the terminal has been cleared and "Attaching…"
// is showing), so both input paths go through it rather than re-deriving it.
// focus:false — typing is already focused, and the bridge must not steal focus.
useEffect(() => {
if (!termInstanceRef.current) return;
const send = (data) => emitShellInput(data, { focus: false });
const disposable = termInstanceRef.current.onData(send);
// Voice dictation (iOS mic key, macOS Fn Fn) streams progressively refined
// guesses and rewrites what it already typed. xterm forwards each insertion
// and ignores the matching deletions, so the PTY accumulates the garble
// ("determin" + "determine" + "determines"…). The bridge intercepts the
// hidden textarea and forwards a diff (DELs + additions) instead. It sends
// straight to `send` rather than looping back through `terminal.input()`:
// onData's only consumer IS this emit, and the round trip would throw away
// the delivered/dropped signal the bridge needs to track the PTY.
const detachDictation = attachDictationBridge(termInstanceRef.current, send);
// Detach the DOM listeners first — at unmount the terminal-init effect's
// cleanup has already disposed the terminal, so nothing here should depend
// on xterm's disposable running successfully.
return () => {
detachDictation();
disposable.dispose();
};
}, [emitShellInput]);
const clearActiveSession = useCallback(() => {
sessionIdRef.current = null;
setActiveSessionId(null);
setConnected(false);
// Don't touch pendingAttachRef here — clearing the displayed session is a separate
// concern from cancelling an in-flight user request. handleShellExit / Detached /
// external-kill reconciliation all call this, but the user may have a switch in
// flight to a different session that we want to land successfully. Explicit user
// cancellation paths (Stop button, X on active tab) call cancelPendingAttach
// themselves.
}, []);
// The single auto-pick rule: the newest session that is neither already attached to
// another socket — adopting one would boot that tab via shell:detached — nor an
// external TUI run, which is an opt-in view the user clicks into rather than a
// default landing session. `excludeId` drops the session that just died, which is
// often still listed in the snapshot we're reconciling against. The displayed
// session is excluded unconditionally: `attached` is recipient-relative (the server
// reports the session bound to THIS socket as unattached), so without it a caller
// that picks before clearing the view would re-attach the tab to itself.
const pickFreeSurvivor = useCallback((excludeId = null) => {
const survivor = sessionsRef.current.findLast(s => (
!s.attached && !s.external && s.sessionId !== excludeId && s.sessionId !== sessionIdRef.current
));
return survivor?.sessionId ?? null;
}, []);
const goToShellRoot = useCallback(() => {
navigateRef.current('/shell', { replace: true });
}, []);
const activateSession = useCallback((sessionId) => {
sessionIdRef.current = sessionId;
setActiveSessionId(sessionId);
setConnected(true);
if (urlSessionIdRef.current !== sessionId) {
const intent = pendingNavIntentRef.current;
pendingNavIntentRef.current = 'replace';
navigateRef.current(`/shell/${sessionId}`, { replace: intent === 'replace' });
}
}, []);
// intent: 'push' arms the next activateSession to push a history entry. Only set AFTER the
// socket-connected guard so a disconnected call doesn't leak the intent into a later auto-activation.
//
// `launch` ({ cwd?, cmd?, provider? }) is the in-page caller's version of what
// initialOptsRef carries for a `?cwd=/?cmd=/?provider=` deep link. Passing it
// as an argument rather than parking it in the ref is what keeps a start that
// never fires from arming the NEXT one with someone else's provider.
const startSession = useCallback(({ intent, launch } = {}) => {
if (!socket?.connected) return;
if (intent === 'push') pendingNavIntentRef.current = 'push';
setPendingAttach('new');
suppressAutoStartRef.current = false;
if (termInstanceRef.current) {
// reset() not clear(): the xterm instance is reused across every session,
// and a full-screen TUI (a watched agent-tui claude/codex run) leaves DEC
// private modes ON — mouse-motion tracking, focus reporting, bracketed
// paste, alt-screen. clear() only wipes the viewport, so those modes would
// persist into this fresh shell and make xterm inject escape-sequence
// reports (mouse/focus events) as INPUT, echoing as accumulating garbage
// at the prompt. reset() restores the terminal to a clean initial state.
resetTerminalWheelScroll(termInstanceRef.current);
termInstanceRef.current.reset();
termInstanceRef.current.writeln('\x1b[36mStarting shell session...\x1b[0m');
}
const opts = launch || initialOptsRef.current || {};
const startOpts = {};
if (opts.cwd) startOpts.cwd = opts.cwd;
if (opts.cmd) startOpts.initialCommand = opts.cmd;
if (opts.provider) startOpts.providerId = opts.provider;
initialOptsRef.current = {};
socket.emit('shell:start', Object.keys(startOpts).length > 0 ? startOpts : undefined);
}, [socket, setPendingAttach]);
const attachToSession = useCallback((sessionId, { intent, claim = false } = {}) => {
if (!socket?.connected) return;
if (intent === 'push') pendingNavIntentRef.current = 'push';
setPendingAttach(sessionId);
suppressAutoStartRef.current = false;
if (termInstanceRef.current) {
// reset() not clear() — drop any DEC private modes (mouse/focus tracking,
// alt-screen) the previously-viewed session left active so they can't
// bleed into this one as injected escape-sequence input. See startSession.
resetTerminalWheelScroll(termInstanceRef.current);
termInstanceRef.current.reset();
termInstanceRef.current.writeln('\x1b[36mAttaching to session...\x1b[0m');
}
// claim:true → server refuses to displace a different socket. Used by auto-pick
// paths so multi-tab broadcast races don't cause one tab's auto-adopt to boot
// another tab via shell:detached. User intent paths default to claim:false.
socket.emit('shell:attach', claim ? { sessionId, claim: true } : { sessionId });
}, [socket, setPendingAttach]);
// The one recovery path — see the module doc comment. Hands the user the next free
// shell, or runs `onNothing` (default: fall back to bare /shell) when there is none.
const recoverToSurvivor = useCallback((excludeId = null, onNothing = goToShellRoot) => {
const survivor = pickFreeSurvivor(excludeId);
if (!survivor) {
onNothing();
return;
}
// claim:true — an auto-pick must never boot another tab off a session it is
// already driving, however the broadcast race falls out.
attachToSession(survivor, { claim: true });
}, [pickFreeSurvivor, attachToSession, goToShellRoot]);
// The session the user is looking at just went away by their own action (Stop
// button, or X on the active tab). Reading "Disconnected" at bare /shell while other
// live sessions sit one click away in the tab strip is the broken state this avoids.
const closeActiveSession = useCallback(() => {
const closedId = sessionIdRef.current;
clearActiveSession();
cancelPendingAttach();
// Disarm the nav intent — if the cancelled request was a user-initiated tab
// click that had set 'push', a later automatic activation must not push a
// history entry the user no longer wanted.
pendingNavIntentRef.current = 'replace';
recoverToSurvivor(closedId, () => {
if (termInstanceRef.current) {
termInstanceRef.current.writeln('\r\n\x1b[33m[Session killed]\x1b[0m');
}
// Nothing to hand over, so don't spawn a replacement either — that would make
// Stop a no-op. Adoption stays armed, so a session freed later still lands.
suppressAutoStartRef.current = true;
goToShellRoot();
});
}, [clearActiveSession, cancelPendingAttach, recoverToSurvivor, goToShellRoot]);
const stopSession = useCallback(() => {
if (!socket || !sessionIdRef.current) return;
socket.emit('shell:stop', { sessionId: sessionIdRef.current });
closeActiveSession();
}, [socket, closeActiveSession]);
const killOtherSession = useCallback((sessionId) => {
if (!socket) return;
socket.emit('shell:stop', { sessionId });
if (sessionId === sessionIdRef.current) closeActiveSession();
}, [socket, closeActiveSession]);
// Restart = kill the current session, then start a fresh one after a short delay
// (gives the server time to tear down the old PTY). Deliberately NOT built on
// stopSession: the user asked for a replacement shell here, not for the next one
// in the strip, so this must not run the survivor-adoption path.
//
// Reserving the pending slot as 'new' up front does three jobs across the delay
// window: it blocks input to the dead PTY, it stops the shell:sessions broadcast
// that follows the stop from adopting a survivor into the gap, and its generation
// is the staleness guard — a user action inside the window (tab click, New) bumps
// it and aborts our delayed start rather than letting it clobber their switch.
const restartSession = useCallback(() => {
if (!socket || !sessionIdRef.current) return;
socket.emit('shell:stop', { sessionId: sessionIdRef.current });
clearActiveSession();
pendingNavIntentRef.current = 'replace';
setPendingAttach('new');
if (termInstanceRef.current) {
termInstanceRef.current.writeln('\r\n\x1b[33m[Restarting session...]\x1b[0m');
}
goToShellRoot();
const gen = pendingAttachRef.current.generation;
setTimeout(() => {
if (!mountedRef.current) return;
if (pendingAttachRef.current.generation !== gen) return;
startSession();
}, 1000);
}, [socket, clearActiveSession, setPendingAttach, startSession, goToShellRoot]);
const switchToSession = useCallback((sessionId, { fromUrl = false } = {}) => {
// Compare against the in-flight attach target if there is one, falling back to the
// currently-displayed session. Without this, a back→forward race (B→A while attach
// to A is pending, then forward back to B) would short-circuit on `sessionId ===
// sessionIdRef.current` and leave the pending attach to overwrite the user's forward.
const pendingTarget = pendingAttachRef.current.target;
const currentTarget = (pendingTarget && pendingTarget !== 'new') ? pendingTarget : sessionIdRef.current;
if (sessionId === currentTarget) return;
// Don't pre-clear — keep the previously displayed session in sessionIdRef until
// shell:attached lands (handleShellAttached → activateSession swaps atomically).
// If shell:error fires instead, handleShellError can restore URL/terminal to the
// session we were already showing rather than leaving the UI stranded on a dead URL.
attachToSession(sessionId, { intent: fromUrl ? undefined : 'push' });
}, [attachToSession]);
// User clicked "New" button — push intent so back/forward can return to the prior session.
const startNewSession = useCallback(() => {
startSession({ intent: 'push' });
}, [startSession]);
// Launch a configured TUI provider from the Shell page's provider menu — the
// in-page twin of the AI Providers page's `?provider=` deep link. Always a NEW
// session, and always by ID rather than by command line; the reason is in
// `components/shell/ShellProviderLauncher.jsx`. The displayed session's cwd
// rides along so a launch lands in the folder the user already cd'd to rather
// than back at $HOME.
const launchProvider = useCallback((providerId) => {
if (!providerId) return;
const cwd = sessionsRef.current.find(s => s.sessionId === sessionIdRef.current)?.cwd;
startSession({ intent: 'push', launch: { provider: providerId, cwd } });
}, [startSession]);
// Handle socket connection and shell session events
useEffect(() => {
if (!socket) return;
const handleConnect = () => {
// Request session list first — decide what to do in handleSessions
hasInitializedRef.current = false;
socket.emit('shell:list');
};
const handleDisconnect = () => {
// Clear session state so reconnect auto-reattaches
clearActiveSession();
};
const handleSessions = (sessionList) => {
sessionsRef.current = sessionList;
setSessions(sessionList);
// On first load, auto-attach to existing session or create new
if (!hasInitializedRef.current) {
hasInitializedRef.current = true;
const opts = initialOptsRef.current || {};
const urlSid = urlSessionIdRef.current;
// If we have initial opts (cwd/cmd), always create a new session
if (opts.session && sessionList.some(s => s.sessionId === opts.session)) {
attachToSession(opts.session);
initialOptsRef.current = {};
} else if (opts.cwd || opts.cmd || opts.provider) {
startSession();
} else if (urlSid && sessionList.some(s => s.sessionId === urlSid)) {
// URL points at a live session — attach to that one (deep-link intent
// overrides the "don't steal" guard; the prior tab gets shell:detached).
attachToSession(urlSid);
} else if (sessionList.length > 0 && !sessionIdRef.current) {
// Attach to the most recent existing session that isn't already driving
// another tab. handleConnect resets hasInitializedRef, so this also runs on
// every reconnect — adoption is safe there, spawning is not.
recoverToSurvivor(null, () => {
// Every live session is attached elsewhere. If the user hasn't just closed
// one, they landed here (probably via a now-dead deep link) intending to
// get a shell — start a fresh one rather than leaving them at bare /shell.
// Capacity counts only interactive shells: external TUI runs are exempt
// from the cap server-side, so they must not block a new shell here.
const atCap = sessionList.filter(s => !s.external).length >= MAX_SESSIONS;
if (suppressAutoStartRef.current || atCap) goToShellRoot();
else startSession();
});
} else if (sessionList.length === 0 && !suppressAutoStartRef.current) {
// Auto-start on empty list — skipped after a user close so a transient
// reconnect (which resets hasInitializedRef and re-enters this branch)
// doesn't spawn a new session over an explicit Stop.
startSession();
}
return;
}
// Post-init: the session we're displaying may have been killed externally (another tab,
// direct server kill). Server sends a fresh sessions list without a shell:exit to this
// socket if it wasn't the attached one. Reconcile by auto-attaching to a survivor that
// isn't already attached elsewhere (otherwise we'd boot the other tab via shell:detached).
const displayed = sessionIdRef.current;
if (displayed && !sessionList.some(s => s.sessionId === displayed)) {
clearActiveSession();
if (termInstanceRef.current) {
termInstanceRef.current.writeln('\r\n\x1b[33m[Session removed externally]\x1b[0m');
}
// Let any user-initiated pending attach complete instead of overriding it.
if (pendingAttachRef.current.target) return;
recoverToSurvivor(displayed);
return;
}
// Tab is sitting on bare /shell with no displayed session — it arrived when every
// live session was attached elsewhere, or the user closed their last free one. If
// another tab later disconnects and frees a session, adopt it so the user doesn't
// have to click to recover. Gated only on there being no in-flight start/attach to
// race; STAY_PUT because bare /shell is already where we are.
if (!displayed && !pendingAttachRef.current.target) {
recoverToSurvivor(null, STAY_PUT);
}
};
const handleShellStarted = ({ sessionId: sid }) => {
// Only consume the response when we're still waiting on a start. If the user
// initiated an attach after the start emit, pendingAttachRef now holds that
// attach target — this stale start response must not steal the activation
// away from the in-flight attach. (The just-spawned session stays alive
// server-side; it'll show up in the next shell:sessions broadcast and the
// user can switch to it manually.)
if (pendingAttachRef.current.target !== 'new') return;
cancelPendingAttach();
activateSession(sid);
if (termInstanceRef.current) {
socket.emit('shell:resize', {
sessionId: sid,
cols: termInstanceRef.current.cols,
rows: termInstanceRef.current.rows
});
}
};
const handleShellAttached = ({ sessionId: sid, bufferedOutput }) => {
// Strict equality: only consume the response if it matches the current pending
// target exactly. A null target (no pending OR user-cancelled mid-flight) and
// a stale target (user moved on to a different attach) both fall through here.
// This is the only guard between a cancelled-during-pending response and an
// erroneous activation that would navigate back to a session the user just left.
if (pendingAttachRef.current.target !== sid) return;
cancelPendingAttach();
activateSession(sid);
if (termInstanceRef.current) {
// reset() not clear(): wipe modes/parser state from the prior session
// before repainting this one's buffer, so a previously-viewed full-screen
// TUI's lingering mouse/focus tracking can't inject garbage here. The
// freshly-painted bufferedOutput re-establishes whatever modes THIS
// session legitimately uses — the server leads it with a mode preamble so
// that holds even once the session's own declaration has scrolled out of
// the replay window (server/lib/terminalReplay.js). See startSession for
// the full rationale.
resetTerminalWheelScroll(termInstanceRef.current);
termInstanceRef.current.reset();
if (bufferedOutput) {
termInstanceRef.current.write(bufferedOutput);
}
socket.emit('shell:resize', {
sessionId: sid,
cols: termInstanceRef.current.cols,
rows: termInstanceRef.current.rows
});
}
};
const handleShellOutput = ({ sessionId: sid, data }) => {
// Suppress old-session output during a pending switch — the terminal has been
// cleared and is waiting for the new session's buffer; bleeding old output here
// produces confusing partial paint.
if (pendingAttachRef.current.target) return;
if (sid === sessionIdRef.current && termInstanceRef.current) {
termInstanceRef.current.write(data);
}
};
const handleShellExit = ({ sessionId: sid, code }) => {
if (sid !== sessionIdRef.current) return;
clearActiveSession();
if (termInstanceRef.current) {
termInstanceRef.current.writeln(`\r\n\x1b[33m[Shell exited with code ${code}]\x1b[0m`);
}
// If the user has an in-flight start/attach to a different session, let it
// complete instead of overriding it with our fallback. The handleShellAttached
// response will install the new session and the user's intent wins.
if (pendingAttachRef.current.target) return;
// Recovering synchronously (rather than behind a timer) is what keeps the
// shell:sessions broadcast that follows shell:exit from adopting a different
// survivor into the gap — attachToSession sets the pending target before the
// broadcast can arrive, and the adoption branch skips while it's set.
recoverToSurvivor(sid);
};
const handleShellDetached = ({ sessionId: sid, reason }) => {
// Server notified us this session was taken over by another socket
// (typically the same user opening the deep link in another tab). The PTY
// stream now goes there; locally we drop the dead view rather than appear
// "Connected" forever with no output.
if (sid !== sessionIdRef.current) return;
clearActiveSession();
if (termInstanceRef.current) {
const note = reason === 'attached-elsewhere'
? 'Session attached in another tab — disconnected here'
: 'Session detached';
termInstanceRef.current.writeln(`\r\n\x1b[33m[${note}]\x1b[0m`);
}
// If the user already has an attach in flight to a different session, let the
// pending request complete (its handleShellAttached will navigate appropriately).
if (pendingAttachRef.current.target) return;
// Recover explicitly rather than relying on the shell:sessions broadcast the
// server happens to send after a takeover: this is the path the user is least
// responsible for, so it must not be the one whose recovery is incidental.
recoverToSurvivor(sid);
};
const handleShellError = ({ error, code, sessionId: errSid }) => {
// A refusal answers every shell event, including the list request no
// pending attach correlates with — settle any pending start/attach and
// surface it once instead of letting the page wait forever.
if (code === 'HOST_CONTROL_FORBIDDEN') {
cancelPendingAttach();
setHostControlForbidden(true);
return;
}
// Correlate this error to our current pending request before deciding whether
// to display it. Four cases:
// 1) start failure: server-side errSid omitted, our pending is 'new'. Show + recover.
// 2) attach failure (server-correlated): errSid present and matches pending. Show + recover.
// 3) legacy attach failure (older server emit without errSid): pending is a
// session id (not 'new', not null). Tolerated for back-compat. Show + recover.
// 4) passive error on the currently displayed session (e.g. shell:input to a
// session that died): errSid matches sessionIdRef. Show, but don't mutate
// pending state — the user's switch (if any) is unrelated.
// Everything else — stale errors from requests the user has moved past, or
// expected claim:true race rejections from auto-pick — drop silently to avoid
// flashing red noise in the terminal for requests the UI no longer cares about.
const pending = pendingAttachRef.current.target;
const isStartFailure = !errSid && pending === 'new';
const isAttachFailure = pending && pending !== 'new' && (!errSid || errSid === pending);
const isPassiveOnActive = errSid && !isAttachFailure && errSid === sessionIdRef.current;
if (!isStartFailure && !isAttachFailure && !isPassiveOnActive) return;
if (termInstanceRef.current) {
termInstanceRef.current.writeln(`\r\n\x1b[31m[Error: ${error}]\x1b[0m`);
}
if (isPassiveOnActive && !isStartFailure && !isAttachFailure) {
// Passive error displayed; do not touch pending state.
return;
}
// This error corresponds to our current request — reset pending state and run recovery.
pendingNavIntentRef.current = 'replace';
const failedTarget = isAttachFailure ? pending : null;
cancelPendingAttach();
const live = sessionsRef.current;
const active = sessionIdRef.current;
if (!active) {
// No previously-displayed session to restore (e.g. initial deep-link attach
// failed before any session was active). Fall back to a free survivor so the
// user isn't stranded on /shell/<dead-id> with only the error message visible.
recoverToSurvivor(failedTarget);
return;
}
if (!live.some(s => s.sessionId === active)) {
// The session we were displaying is also gone — recover the same way.
clearActiveSession();
recoverToSurvivor(failedTarget);
return;
}
// Active session is still alive. Distinguish a switch failure (re-attach so the
// terminal that attachToSession just cleared gets repainted) from a start
// failure with an existing session (leave the terminal as-is so the error
// message stays readable). Two switch-failure paths:
// • Tab-click switch: failedTarget is a session id != active. URL didn't move
// because activateSession never fired.
// • URL-nav switch: urlSessionIdRef diverged from active.
const switchAttempt = failedTarget && failedTarget !== active;
const urlDiverged = urlSessionIdRef.current && urlSessionIdRef.current !== active;
if (switchAttempt || urlDiverged) {
if (urlDiverged) {
navigateRef.current(`/shell/${active}`, { replace: true });
}
// Capture generation so a user action during the 100ms window aborts our
// deferred recovery attach.
setPendingAttach(active);
const gen = pendingAttachRef.current.generation;
setTimeout(() => {
if (!mountedRef.current) return;
if (pendingAttachRef.current.generation !== gen) return;
// The setPendingAttach we just did is consumed here — clear and emit.
cancelPendingAttach();
attachToSession(active);
}, 100);
}
};
socket.on('connect', handleConnect);
socket.on('disconnect', handleDisconnect);
socket.on('shell:sessions', handleSessions);
socket.on('shell:started', handleShellStarted);
socket.on('shell:attached', handleShellAttached);
socket.on('shell:output', handleShellOutput);
socket.on('shell:exit', handleShellExit);
socket.on('shell:detached', handleShellDetached);
socket.on('shell:error', handleShellError);
if (socket.connected) {
handleConnect();
}
return () => {
socket.off('connect', handleConnect);
socket.off('disconnect', handleDisconnect);
socket.off('shell:sessions', handleSessions);
socket.off('shell:started', handleShellStarted);
socket.off('shell:attached', handleShellAttached);
socket.off('shell:output', handleShellOutput);
socket.off('shell:exit', handleShellExit);
socket.off('shell:detached', handleShellDetached);
socket.off('shell:error', handleShellError);
// Leaving the Shell page: tell the server we've stopped viewing so any
// watched TUI run resumes normal idle completion instead of staying
// paused for a page we've left (the singleton socket stays connected
// across navigations, so `disconnect` won't fire). This effect only
// re-binds on socket identity change, so this runs on real unmount.
if (socket.connected) socket.emit('shell:release-views');
// Don't kill session on unmount — it persists server-side
sessionIdRef.current = null;
};
}, [socket, startSession, attachToSession, activateSession, clearActiveSession, cancelPendingAttach, setPendingAttach, recoverToSurvivor, goToShellRoot]);
// React to URL changes after init (browser back/forward, manual URL paste, sidebar click).
// fromUrl: true keeps the next activateSession in 'replace' mode — the browser already
// owns this history entry, so we don't want to double-push.
useEffect(() => {
if (!hasInitializedRef.current) return;
// URL points at a known live session — switch the display if it isn't already there.
if (urlSessionId && sessionsRef.current.some(s => s.sessionId === urlSessionId)) {
switchToSession(urlSessionId, { fromUrl: true });
return;
}
// URL points at bare /shell or a dead/unknown session.
if (sessionIdRef.current) {
// Have an active session — mirror its id back into the URL so reload restores it.
navigateRef.current(`/shell/${sessionIdRef.current}`, { replace: true });
return;
}
// No active session, no live target for the URL. Clear the stale id from the
// address bar — but only when there's nothing in flight, since a pending attach
// will navigate via activateSession on success. handleSessions handles survivor
// adoption and the deep-link new-session fallback when initial-load runs.
if (urlSessionId && !pendingAttachRef.current.target) {
goToShellRoot();
}
}, [urlSessionId, switchToSession, goToShellRoot]);
// External TUI runs (editorial review, pipeline stages, etc.) are surfaced as
// opt-in, fully-interactive tabs — you can watch and step in. They're labelled
// distinctly and don't count toward the shell cap.
const interactiveCount = sessions.filter(s => !s.external).length;
const liveRunCount = sessions.filter(s => s.external).length;
const activeSession = sessions.find(s => s.sessionId === activeSessionId);
const isLiveRun = !!activeSession?.external;
return {
terminalRef,
connected,
hostControlForbidden,
sessions,
activeSessionId,
activeSession,
interactiveCount,
liveRunCount,
isLiveRun,
emitShellInput,
sendImage,
sendCommand,
sendCd,
sendCtrlB,
sendCtrlC,
sendEsc,
sendNavKey,
scrollPage,
restartSession,
stopSession,
startNewSession,
launchProvider,
switchToSession,
killOtherSession,
};
}