terminal.md
Workspace Terminals
The Explorer terminal action opens or focuses a terminal for its selected cwd in the right panel's existing tab bar. Each terminal tab keeps the cwd it was created with. Files still mount only their active viewer; terminal panels stay mounted behind inactive tabs, hidden panels, and session or project switches.
Lifecycle
- Each new tab generates a random terminal ID before creation. Creation with the same ID and cwd is idempotent, including React Strict Mode's repeated effects. An existing ID cannot be reused for another cwd.
sessionStorageretains terminal IDs, cwds, and the active terminal layout across refresh. Restored tabs first check the existing server instance and never silently start replacement processes after expiry or server restart.- A new PTY gets a 120-second connection lease. Subscribing cancels expiry; the last subscriber leaving starts a new 120-second grace period. This also collects creations that never establish their initial connection.
- Hiding a panel, switching tabs, and unmounting a component only disconnect clients. Explicitly terminating a tab waits for creation and in-flight input before deleting the PTY. Restart waits for termination before creating a new ID. Failed termination leaves the tab available to retry.
- A shell exit closes the SSE stream and retains its output and exit code in the browser. Unobserved server records expire after the same grace period.
- Explicit termination and expiry signal the shell, escalating to SIGKILL after two seconds if it ignores SIGHUP. Server shutdown force-kills shells immediately.
Transport
Output events carry a monotonically increasing UTF-16 offset in SSE id.
Reconnections use Last-Event-ID (or after on an explicit reconnect) and send
only the missing suffix. The server keeps at most 128 KiB of UTF-16 code units;
an older cursor triggers a terminal reset and bounded history replay. This is
bounded output history, not a serialized full-screen terminal snapshot. Slow
SSE consumers are disconnected once their response queue fills.
Input and resizes are serialized. Pending adjacent input is batched so remote connections do not require one round trip per keystroke; large pastes are split without splitting Unicode characters. Failed input is not retried because its delivery may be ambiguous. Reconnect attaches to the same process with a fresh writer; restart explicitly replaces the process.
bin/prepare-terminal.js repairs node-pty 1.1.0's macOS spawn-helper executable
bits during installation, including published/npm-installed Pi Web packages.
Pi Web pins node-pty to 1.2.0-beta.15, which includes Linux x64 and ARM64
prebuilt binaries. Native module loading is deferred until terminal creation,
so missing or incompatible binaries produce a JSON error with repair instructions.
Empty or non-JSON API errors show the HTTP status and direct users to the server log.
If a native binary cannot load, run
npm rebuild node-pty --build-from-source --ignore-scripts=false --foreground-scripts from the
installation directory (for npx, the cache directory containing node_modules).
On Debian/Ubuntu, install python3 and build-essential first. This forces a
source build instead of reusing a missing or incompatible prebuilt binary.
Restart Pi Web after repair.
Verification
Run npm test for native PTY, lease, output cursor, input queue, and storage
checks. npm run test:terminal starts an isolated development server and runs
desktop/mobile browser checks using generated session fixtures. Install the
Playwright Chromium browser first with npx playwright install chromium.
The browser check prints the temporary location of its screenshots and log.