@vantran-se/openchamber-web 1.22.1 → 1.22.2

package/server/lib/terminal/DOCUMENTATION.md

@@ -2,7 +2,7 @@
 
 ## Ownership
 
-`runtime.js` owns terminal identity, PTY processes, status, ordered output, bounded scrollback, WebSocket attachments, and lifecycle routes. `shells.js` discovers executable shell families and resolves the persisted shell ID without accepting command strings or arguments. Clients own tab arrangement and choose stable terminal IDs. Electron uses this same runtime in-process; VS Code returns an explicit unsupported error.
+`runtime.js` owns terminal identity, PTY processes, launch mode, session purpose, ordered output, bounded scrollback, WebSocket attachments, and lifecycle routes. `shells.js` discovers executable shell families, resolves the persisted shell ID, and builds the per-shell argv for interactive versus command launches. Clients own tab arrangement. Interactive terminals use stable IDs; project actions keep a stable UI tab and allocate a fresh terminal ID for each command execution. Electron uses this same runtime in-process; VS Code returns an explicit unsupported error.
 
 ## Protocol
 
@@ -19,21 +19,25 @@
 
 HTTP remains the authenticated command plane for create, resize, appearance updates, restart, close, and force-kill. There is no SSE output or HTTP input compatibility path.
 
-`GET /api/terminal/sessions` enumerates live sessions (optionally filtered by resolved `cwd`) so clients can adopt terminals their local tab projection does not know about — another device, a new browser tab, or cleared storage. `POST /api/terminal/touch` refreshes `lastActivity` for the listed session ids; open clients call it periodically so background tabs, which hold no WebSocket attachment, are not idle-reaped while a client still shows them.
+`GET /api/terminal/sessions` enumerates live sessions (optionally filtered by resolved `cwd`) so clients can adopt terminals their local tab projection does not know about — another device, a new browser tab, or cleared storage. Listings include the effective launch mode and the normalized purpose, but never the command text. `POST /api/terminal/touch` refreshes `lastActivity` for the listed session ids; open clients call it periodically so background tabs, which hold no WebSocket attachment, are not idle-reaped while a client still shows them.
 
 ## PTY Lifecycle
 
 - IDs are client-provided or generated with `randomUUID()`.
-- Concurrent creates for one ID are single-flight only when working directory and shell preference match. Existing IDs cannot be reused for another working directory.
+- Create defaults to interactive mode. Command mode requires a non-empty trimmed command no longer than the terminal input limit and launches the shell so the PTY exits when that command exits. Each session also carries a normalized purpose. Omitted purpose means `{ type: 'terminal' }`. Project actions use `{ type: 'project-action', actionId, executionId }`, and the server validates both IDs as non-empty bounded strings. Create responses and attach snapshots echo the effective mode and purpose.
+- Concurrent creates for one ID are single-flight only when working directory, shell preference, login mode, launch mode, and session purpose match. Command-mode creates must also match the command text, unless the purpose is a project action that is already running for the same resolved `(cwd, actionId)` pair. In that case the runtime returns the existing session and its existing execution identity, even when another client requested a different session ID. Existing IDs cannot be reused for another working directory or another purpose.
 - Dimensions are bounded to 1-1000 columns and 1-500 rows; input is capped at 64 KiB.
 - A client may create before its renderer has mounted. It derives an initial size from the container and font metrics (falling back to 80x24 when unavailable), then sends a resize once Ghostty reports its final dimensions. This allows shell startup and renderer initialization to overlap.
 - PTY children explicitly clear `NODE_CHANNEL_FD`; daemon IPC descriptors are host-private and invalid after PTY descriptor cleanup.
 - PTY children also strip AppImage `ARGV0` (and other host-private shell vars such as `ELECTRON_RUN_AS_NODE`, `BASH_ENV`, `ENV`, `BASH_XTRACEFD`). An exported `ARGV0` makes zsh rewrite argv[0] for every external command, which breaks Python venv detection and other argv[0]/$0 consumers while leaving `/proc/self/exe` correct. On Linux, PTY spawn is wrapped with `env -u ARGV0` because `bun-pty` merges the native OS environ and would otherwise reintroduce `ARGV0` after a JS-only delete.
-- `GET /api/terminal/shells` reports shell IDs available on the active server using the same augmented PATH provided to spawned PTYs, plus whether each executable has a supported login-mode argument. `auto` preserves environment/platform fallback order; an explicit unavailable shell fails creation instead of silently running a different shell. Login mode is opt-in and uses only built-in arguments for known shells. Preference changes affect new sessions and explicit restarts, not running PTYs.
-- PTY data and exit callbacks enter one FIFO queue. Stale callbacks from replaced processes are ignored.
+- `GET /api/terminal/shells` reports shell IDs available on the active server using the same augmented PATH provided to spawned PTYs, plus whether each executable has a supported login-mode argument. `auto` preserves environment/platform fallback order; an explicit unavailable shell fails creation instead of silently running a different shell. Login mode is opt-in and uses only built-in arguments for known shells. Interactive shells still launch as before. Command-mode launches reuse the same environment and login support, but switch argv by shell family: POSIX and Fish use interactive `-c`, Nushell uses `-c`, PowerShell uses `-Command`, and cmd uses `/d /s /c`. Preference changes affect new sessions and explicit restarts, not running PTYs.
+- PTY data and exit callbacks enter one FIFO queue. The runtime wires those listeners in the same synchronous turn that receives the PTY object. `node-pty` and `bun-pty` both expose the PTY before dispatching registered callbacks. If a backend emitted exit before listener registration, this layer could not recover it, so the wiring stays adjacent to PTY creation.
 - Scrollback is retained on the server and capped at 512 KiB with UTF-8-safe trimming. Device-status, device-attribute, cursor-position reply, and color-query exchanges are removed from replay history with incomplete control sequences carried across PTY chunks; live output remains byte-for-byte unchanged.
-- Exited sessions remain attachable until explicit close or idle cleanup.
-- Restarts are serialized per terminal. Each restart spawns and wires the replacement before terminating the old process, retaining the terminal ID.
+- Exited sessions remain attachable until explicit close, idle cleanup, or a successful replacement of the same project action. Creating a replacement retires only exited records for the same resolved directory and action, after the new PTY starts. Failed creation preserves the old record and output. These replaced records do not exhaust the terminal capacity limit.
+- Deduplicated create responses may describe another client's execution. Cancellation cleanup closes only the terminal ID allocated for the cancelled request; it never closes an adopted peer execution.
+- Create and restart validate the working directory with a real `stat` and answer HTTP 400 `Invalid working directory` when it is not a directory. When the path does not exist at all (`ENOENT`/`ENOTDIR`, a worktree deleted outside OpenChamber) the body also carries `code: "TERMINAL_CWD_MISSING"`. That is the one rejection the client can recover from: the session, not the terminal, is stranded, and the shared UI moves it to its project directory and starts a terminal there. Every other rejection stays generic; the runtime never substitutes a parent directory on its own.
+- Restarts are serialized per terminal. Each restart spawns and wires the replacement before terminating the old process, retaining the terminal ID. Command-mode sessions reject restart with HTTP 400 instead of silently turning into interactive shells with stale action metadata.
+- A delete that arrives while create is still pending leaves a cancellation tombstone. When the PTY arrives, the runtime terminates it immediately, never inserts the session into the live map, and returns a create error while the delete still succeeds.
 - Close uses SIGTERM with bounded SIGKILL escalation. Force-kill, idle cleanup, and runtime shutdown terminate process groups immediately where supported. Removal explicitly sends a fatal scoped closure and evicts client projections even when a PTY backend fails to emit `onExit`; attached terminals are not considered idle.
 
 ## Security And Relay

package/server/lib/terminal/runtime.js

@@ -9,7 +9,7 @@ import {
 } from './terminal-ws-protocol.js';
 import { sanitizeTerminalHistoryChunk } from './history.js';
 import { consumeTerminalThemeQueries, terminalThemeModeReport } from './theme-response.js';
-import { createTerminalShellResolver, getTerminalShellLoginArgs, normalizeTerminalShell } from './shells.js';
+import { buildTerminalShellLaunch, createTerminalShellResolver, normalizeTerminalShell } from './shells.js';
 import { stripAppImageArgv0Leak, resolveLinuxPtyLaunch } from '../inherited-env.js';
 
 const MAX_SESSIONS = 20;
@@ -17,7 +17,69 @@ const MAX_HISTORY_BYTES = 512 * 1024;
 const MAX_INPUT_CHARS = 65_536;
 const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 const TERMINATION_GRACE_MS = 1000;
+const INTERACTIVE_TERMINAL_MODE = 'interactive';
+const COMMAND_TERMINAL_MODE = 'command';
+// Error code the create/restart routes attach when the requested cwd no longer
+// exists. Mirrored by `TERMINAL_CWD_MISSING_CODE` in packages/ui/src/lib/terminalApi.ts.
+const TERMINAL_CWD_MISSING_CODE = 'TERMINAL_CWD_MISSING';
+const TERMINAL_PURPOSE = Object.freeze({ type: 'terminal' });
+const MAX_PURPOSE_ID_CHARS = 128;
+const OBJECT_TAG = '[object Object]';
 const validateSize = (value, max) => Number.isInteger(value) && value >= 1 && value <= max;
+const isString = (value) => String(value) === value;
+const isObjectRecord = (value) => value != null && !Array.isArray(value) && Object.prototype.toString.call(value) === OBJECT_TAG;
+const normalizeCreateMode = ({ mode, command }) => {
+  const normalizedMode = mode == null ? INTERACTIVE_TERMINAL_MODE : mode;
+  if (normalizedMode !== INTERACTIVE_TERMINAL_MODE && normalizedMode !== COMMAND_TERMINAL_MODE) throw new Error('Invalid terminal mode');
+  if (normalizedMode === INTERACTIVE_TERMINAL_MODE) {
+    if (command != null) throw new Error('Interactive terminal create does not accept a command');
+    return { mode: INTERACTIVE_TERMINAL_MODE, command: null };
+  }
+  if (!isString(command) || !command.trim()) throw new Error('Terminal command is required');
+  const trimmedCommand = command.trim();
+  if (trimmedCommand.length > MAX_INPUT_CHARS) throw new Error('Terminal command exceeds the input limit');
+  return { mode: COMMAND_TERMINAL_MODE, command: trimmedCommand };
+};
+const normalizePurposeId = (value, errorMessage) => {
+  if (!isString(value) || !value.trim()) throw new Error(errorMessage);
+  const normalized = value.trim();
+  if (normalized.length > MAX_PURPOSE_ID_CHARS) throw new Error(errorMessage);
+  return normalized;
+};
+const normalizeTerminalPurpose = (value) => {
+  if (value == null) return TERMINAL_PURPOSE;
+  if (!isObjectRecord(value)) throw new Error('Invalid terminal purpose');
+  if (value.type === 'terminal') return TERMINAL_PURPOSE;
+  if (value.type !== 'project-action') throw new Error('Invalid terminal purpose');
+  return {
+    type: 'project-action',
+    actionId: normalizePurposeId(value.actionId, 'Terminal project action id is required'),
+    executionId: normalizePurposeId(value.executionId, 'Terminal execution id is required'),
+  };
+};
+const getSessionPurpose = (session) => session.purpose ?? TERMINAL_PURPOSE;
+const isPurposeActionMatch = (left, right) => {
+  if (left.type !== right.type) return false;
+  return left.type !== 'project-action' || left.actionId === right.actionId;
+};
+const findRunningActionSession = (sessions, resolvedCwd, purpose, path) => {
+  if (purpose.type !== 'project-action') return null;
+  for (const session of sessions.values()) {
+    if (session.status !== 'running') continue;
+    if (path.resolve(session.cwd) !== resolvedCwd) continue;
+    const sessionPurpose = getSessionPurpose(session);
+    if (sessionPurpose.type === 'project-action' && sessionPurpose.actionId === purpose.actionId) return session;
+  }
+  return null;
+};
+const findPendingActionCreate = (pendingSessionCreates, resolvedCwd, purpose) => {
+  if (purpose.type !== 'project-action') return null;
+  for (const pending of pendingSessionCreates.values()) {
+    if (pending.cancelled || pending.cwd !== resolvedCwd) continue;
+    if (pending.purpose?.type === 'project-action' && pending.purpose.actionId === purpose.actionId) return pending;
+  }
+  return null;
+};
 const trimHistory = (history) => {
   const bytes = Buffer.from(history);
   if (bytes.byteLength <= MAX_HISTORY_BYTES) return history;
@@ -54,13 +116,11 @@ export function createTerminalRuntime({
     return ptyProviderPromise;
   };
 
-  const spawnPty = async ({ cwd, cols, rows, themeMode, shell, loginShell }) => {
+  const spawnPty = async ({ cwd, cols, rows, themeMode, shell, loginShell, mode, command }) => {
     const provider = await getPtyProvider();
     const resolvedShell = await shellResolver.resolve(shell);
     let lastError = null;
     for (const executable of resolvedShell.executables) {
-      const args = loginShell ? getTerminalShellLoginArgs(executable) : [];
-      if (!args) throw new Error(`Terminal shell "${resolvedShell.id}" does not support login mode`);
       try {
         const env = { ...process.env, PATH: buildAugmentedPath(), TERM: 'xterm-256color', COLORTERM: 'truecolor', COLORFGBG: themeMode === 'light' ? '0;15' : '15;0' };
         // The daemon's IPC fd is closed inside the PTY. An explicit override is
@@ -70,9 +130,11 @@ export function createTerminalRuntime({
         // AppImage exports ARGV0; zsh would otherwise rewrite argv[0] for every command (#2588).
         // bun-pty also merges the native OS environ, so wrap with `env -u ARGV0` on Linux.
         stripAppImageArgv0Leak(env);
-        const launch = resolveLinuxPtyLaunch(executable, args);
-        const options = { name: 'xterm-256color', cwd, cols, rows, env, ...(process.platform === 'win32' ? { useConpty: true } : {}) };
-        return { process: provider.spawn(launch.executable, launch.args, options), backend: provider.backend, shell: resolvedShell.id, loginShell };
+        const shellLaunch = buildTerminalShellLaunch(executable, { mode, command, loginShell });
+        const launch = resolveLinuxPtyLaunch(shellLaunch.executable, shellLaunch.args);
+        const options = { name: 'xterm-256color', cwd, cols, rows, env };
+        if (process.platform === 'win32') options.useConpty = true;
+        return { process: await provider.spawn(launch.executable, launch.args, options), backend: provider.backend, shell: resolvedShell.id, loginShell };
       } catch (error) { lastError = error; }
     }
     throw lastError ?? new Error('No executable shell found');
@@ -123,6 +185,7 @@ export function createTerminalRuntime({
   const snapshot = (session) => ({
     t: 'snapshot', v: 3, s: session.id, q: session.sequence, history: session.history,
     status: session.status, exitCode: session.exitCode, signal: session.signal,
+    mode: session.mode ?? INTERACTIVE_TERMINAL_MODE, purpose: getSessionPurpose(session),
     runtime, ptyBackend: session.backend,
   });
 
@@ -175,11 +238,18 @@ export function createTerminalRuntime({
     ptyProcess.onExit(({ exitCode, signal }) => { session.eventQueue.push({ type: 'exit', process: ptyProcess, exitCode, signal }); drainEvents(session); });
   };
 
+  // A working directory that no longer exists (a deleted worktree) is the one
+  // rejection the client can recover from by moving the session to its
+  // project, so the response names it. Every other rejection stays generic.
+  const invalidWorkingDirectory = (code) => Object.assign(new Error('Invalid working directory'), code ? { code } : {});
   const validateCwd = async (cwd) => {
     if (typeof cwd !== 'string' || !cwd.trim()) throw new Error('cwd is required');
-    const stats = await fs.promises.stat(cwd).catch(() => null);
-    if (!stats?.isDirectory()) throw new Error('Invalid working directory');
+    let stats;
+    try { stats = await fs.promises.stat(cwd); }
+    catch (error) { throw invalidWorkingDirectory(error?.code === 'ENOENT' || error?.code === 'ENOTDIR' ? TERMINAL_CWD_MISSING_CODE : undefined); }
+    if (!stats?.isDirectory()) throw invalidWorkingDirectory();
   };
+  const errorBody = (error, fallback) => ({ error: error?.message || fallback, ...(typeof error?.code === 'string' ? { code: error.code } : {}) });
 
   const applyAppearance = (session, { themeMode, terminalBackground, terminalForeground }) => {
     const previous = [session.themeMode, session.terminalBackground, session.terminalForeground];
@@ -192,48 +262,87 @@ export function createTerminalRuntime({
     }
   };
 
-  const startSession = async (session, { cwd, cols, rows, themeMode = 'dark', terminalBackground, terminalForeground, shell, loginShell }, clear = true) => {
+  const startSession = async (session, { cwd, cols, rows, themeMode = 'dark', terminalBackground, terminalForeground, shell, loginShell, mode = INTERACTIVE_TERMINAL_MODE, command = null, purpose = TERMINAL_PURPOSE }, clear = true) => {
     await validateCwd(cwd);
-    const spawned = await spawnPty({ cwd, cols, rows, themeMode, shell, loginShell });
+    const spawned = await spawnPty({ cwd, cols, rows, themeMode, shell, loginShell, mode, command });
     if (clear) { session.history = ''; session.pendingHistoryControlSequence = ''; session.pendingThemeControlSequence = ''; session.themeModeEnabled = false; }
     session.cwd = cwd; session.cols = cols; session.rows = rows; session.process = spawned.process;
     session.backend = spawned.backend; session.shell = spawned.shell; session.loginShell = spawned.loginShell; session.status = 'running'; session.exitCode = null; session.signal = null;
+    session.mode = mode; session.command = mode === COMMAND_TERMINAL_MODE ? command : null;
+    session.purpose = purpose;
     session.themeMode = themeMode === 'light' ? 'light' : 'dark'; session.terminalBackground = terminalBackground; session.terminalForeground = terminalForeground;
     session.lastActivity = Date.now(); session.eventQueue.length = 0;
     wire(session, spawned.process);
+    return spawned.process;
   };
 
-  const createSession = async ({ sessionId, cwd, cols = 80, rows = 24, themeMode, terminalBackground, terminalForeground, shell = 'auto', loginShell = false }) => {
+  const createSession = async ({ sessionId, cwd, cols = 80, rows = 24, themeMode, terminalBackground, terminalForeground, shell = 'auto', loginShell = false, mode, command, purpose }) => {
     if (!validateSize(cols, 1000) || !validateSize(rows, 500)) throw new Error('Invalid terminal dimensions');
     if (typeof loginShell !== 'boolean') throw new Error('Invalid terminal login mode');
     const normalizedShell = normalizeTerminalShell(shell);
     if (!normalizedShell) throw new Error('Invalid terminal shell');
+    const launchMode = normalizeCreateMode({ mode, command });
+    const normalizedPurpose = normalizeTerminalPurpose(purpose);
     const id = typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : randomUUID();
     if (id.length > 128) throw new Error('Invalid terminal session id');
     const existing = sessions.get(id);
     const resolvedCwd = path.resolve(cwd);
     if (existing?.status === 'running') {
       if (path.resolve(existing.cwd) !== resolvedCwd) throw new Error('Terminal session belongs to a different working directory');
+      if (!isPurposeActionMatch(getSessionPurpose(existing), normalizedPurpose)) throw new Error('Terminal session is already running with a different purpose');
+      if (normalizedPurpose.type === 'project-action') { applyAppearance(existing, { themeMode, terminalBackground, terminalForeground }); return existing; }
+      if ((existing.mode ?? INTERACTIVE_TERMINAL_MODE) !== launchMode.mode) throw new Error('Terminal session is already running with a different mode');
+      if (launchMode.mode === COMMAND_TERMINAL_MODE && existing.command !== launchMode.command) throw new Error('Terminal session is already running with a different command');
       applyAppearance(existing, { themeMode, terminalBackground, terminalForeground });
       return existing;
     }
+    const runningActionSession = findRunningActionSession(sessions, resolvedCwd, normalizedPurpose, path);
+    if (runningActionSession) {
+      applyAppearance(runningActionSession, { themeMode, terminalBackground, terminalForeground });
+      return runningActionSession;
+    }
     const pending = pendingSessionCreates.get(id);
     if (pending) {
       if (pending.cwd !== resolvedCwd) throw new Error('Terminal session belongs to a different working directory');
+      if (!isPurposeActionMatch(pending.purpose, normalizedPurpose)) throw new Error('Terminal session is already being created with a different purpose');
+      if (normalizedPurpose.type === 'project-action') return pending.promise;
       if (pending.shell !== normalizedShell) throw new Error('Terminal session is already being created with a different shell');
       if (pending.loginShell !== loginShell) throw new Error('Terminal session is already being created with a different login mode');
+      if (pending.mode !== launchMode.mode) throw new Error('Terminal session is already being created with a different mode');
+      if (launchMode.mode === COMMAND_TERMINAL_MODE && pending.command !== launchMode.command) throw new Error('Terminal session is already being created with a different command');
       const session = await pending.promise;
       applyAppearance(session, { themeMode, terminalBackground, terminalForeground });
       return session;
     }
-    if (!existing && sessions.size + pendingSessionCreates.size >= MAX_SESSIONS) throw new Error('Maximum terminal sessions reached');
+    const pendingActionCreate = findPendingActionCreate(pendingSessionCreates, resolvedCwd, normalizedPurpose);
+    if (pendingActionCreate) {
+      const session = await pendingActionCreate.promise;
+      applyAppearance(session, { themeMode, terminalBackground, terminalForeground });
+      return session;
+    }
+    const superseded = normalizedPurpose.type === 'project-action'
+      ? [...sessions.values()].filter((session) => session.id !== id && session.status === 'exited'
+        && path.resolve(session.cwd) === resolvedCwd && isPurposeActionMatch(getSessionPurpose(session), normalizedPurpose))
+      : [];
+    if (!existing && sessions.size - superseded.length + pendingSessionCreates.size >= MAX_SESSIONS) throw new Error('Maximum terminal sessions reached');
+    const pendingEntry = { cwd: resolvedCwd, shell: normalizedShell, loginShell, mode: launchMode.mode, command: launchMode.command, purpose: normalizedPurpose, cancelled: false, promise: null };
     const creation = (async () => {
       const session = existing ?? { id, sequence: 0, history: '', pendingHistoryControlSequence: '', pendingThemeControlSequence: '', eventQueue: [], draining: false, createdAt: Date.now() };
-      await startSession(session, { cwd, cols, rows, themeMode, terminalBackground, terminalForeground, shell: normalizedShell, loginShell });
+      const ptyProcess = await startSession(session, { cwd, cols, rows, themeMode, terminalBackground, terminalForeground, shell: normalizedShell, loginShell, mode: launchMode.mode, command: launchMode.command, purpose: normalizedPurpose });
+      if (pendingEntry.cancelled) {
+        session.process = null;
+        await terminateProcess(ptyProcess, true);
+        throw new Error('Terminal session was closed during creation');
+      }
+      for (const previous of superseded) {
+        if (sessions.get(previous.id) !== previous || previous.status !== 'exited') continue;
+        sessions.delete(previous.id);
+        closeAttachments(previous.id, 'SUPERSEDED', 'Terminal replaced by a new action run');
+      }
       sessions.set(id, session);
       return session;
     })();
-    const pendingEntry = { cwd: resolvedCwd, shell: normalizedShell, loginShell, promise: creation };
+    pendingEntry.promise = creation;
     pendingSessionCreates.set(id, pendingEntry);
     try { return await creation; }
     finally { if (pendingSessionCreates.get(id) === pendingEntry) pendingSessionCreates.delete(id); }
@@ -276,16 +385,39 @@ export function createTerminalRuntime({
 
   const upgradeHandler = (req, socket, head) => {
     if (parseRequestPathname(req.url) !== TERMINAL_WS_PATH) return;
-    void (async () => {
+    const accept = () => {
+      if (!wsServer) { rejectWebSocketUpgrade(socket, 500, 'Terminal WebSocket unavailable'); return; }
       try {
-        if (uiAuthController?.enabled) {
-          if (!await uiAuthController.ensureSessionToken(req, null)) { rejectWebSocketUpgrade(socket, 401, 'UI authentication required'); return; }
-          if (!await isRequestOriginAllowed(req)) { rejectWebSocketUpgrade(socket, 403, 'Invalid origin'); return; }
-        }
-        if (!wsServer) { rejectWebSocketUpgrade(socket, 500, 'Terminal WebSocket unavailable'); return; }
         wsServer.handleUpgrade(req, socket, head, (ws) => wsServer.emit('connection', ws, req));
       } catch { rejectWebSocketUpgrade(socket, 500, 'Upgrade failed'); }
-    })();
+    };
+    const checkOrigin = () => {
+      try {
+        const result = isRequestOriginAllowed(req);
+        if (!(result instanceof Promise)) {
+          if (result) accept();
+          else rejectWebSocketUpgrade(socket, 403, 'Invalid origin');
+          return;
+        }
+        void result.then((allowed) => {
+          if (allowed) accept();
+          else rejectWebSocketUpgrade(socket, 403, 'Invalid origin');
+        }).catch(() => rejectWebSocketUpgrade(socket, 500, 'Upgrade failed'));
+      } catch { rejectWebSocketUpgrade(socket, 500, 'Upgrade failed'); }
+    };
+    if (!uiAuthController?.enabled) { accept(); return; }
+    try {
+      const result = uiAuthController.ensureSessionToken(req, null);
+      if (!(result instanceof Promise)) {
+        if (result) checkOrigin();
+        else rejectWebSocketUpgrade(socket, 401, 'UI authentication required');
+        return;
+      }
+      void result.then((sessionToken) => {
+        if (sessionToken) checkOrigin();
+        else rejectWebSocketUpgrade(socket, 401, 'UI authentication required');
+      }).catch(() => rejectWebSocketUpgrade(socket, 500, 'Upgrade failed'));
+    } catch { rejectWebSocketUpgrade(socket, 500, 'Upgrade failed'); }
   };
   server.on('upgrade', upgradeHandler);
 
@@ -308,6 +440,8 @@ export function createTerminalRuntime({
         cwd: session.cwd,
         status: session.status,
         createdAt: Number.isInteger(session.createdAt) ? session.createdAt : null,
+        mode: session.mode ?? INTERACTIVE_TERMINAL_MODE,
+        purpose: getSessionPurpose(session),
       });
     }
     res.json({ sessions: list });
@@ -326,8 +460,18 @@ export function createTerminalRuntime({
     res.json({ touched });
   });
   app.post('/api/terminal/create', async (req, res) => {
-    try { const session = await createSession(req.body ?? {}); res.json({ sessionId: session.id, cols: session.cols, rows: session.rows, status: session.status }); }
-    catch (error) { res.status(error?.message === 'Maximum terminal sessions reached' ? 429 : 400).json({ error: error?.message || 'Failed to create terminal session' }); }
+    try {
+      const session = await createSession(req.body ?? {});
+      res.json({
+        sessionId: session.id,
+        cols: session.cols,
+        rows: session.rows,
+        status: session.status,
+        mode: session.mode ?? INTERACTIVE_TERMINAL_MODE,
+        purpose: getSessionPurpose(session),
+      });
+    }
+    catch (error) { res.status(error?.message === 'Maximum terminal sessions reached' ? 429 : 400).json(errorBody(error, 'Failed to create terminal session')); }
   });
   app.post('/api/terminal/:sessionId/resize', (req, res) => {
     const session = sessions.get(req.params.sessionId);
@@ -346,6 +490,7 @@ export function createTerminalRuntime({
   app.post('/api/terminal/:sessionId/restart', async (req, res) => {
     const session = sessions.get(req.params.sessionId);
     if (!session) return res.status(404).json({ error: 'Terminal session not found' });
+    if ((session.mode ?? INTERACTIVE_TERMINAL_MODE) === COMMAND_TERMINAL_MODE) return res.status(400).json({ error: 'Command-mode terminal sessions cannot be restarted' });
     const cwd = req.body?.cwd ?? session.cwd;
     const cols = req.body?.cols ?? session.cols;
     const rows = req.body?.rows ?? session.rows;
@@ -370,12 +515,21 @@ export function createTerminalRuntime({
     try {
       await restart;
       res.json({ sessionId: session.id, cols, rows, status: session.status });
-    } catch (error) { res.status(400).json({ error: error?.message || 'Failed to restart terminal' }); }
+    } catch (error) { res.status(400).json(errorBody(error, 'Failed to restart terminal')); }
     finally { if (pendingSessionRestarts.get(session.id) === restart) pendingSessionRestarts.delete(session.id); }
   });
   app.delete('/api/terminal/:sessionId', async (req, res) => {
     const session = sessions.get(req.params.sessionId);
-    if (!session) return res.status(404).json({ error: 'Terminal session not found' });
+    if (!session) {
+      const pending = pendingSessionCreates.get(req.params.sessionId);
+      if (!pending) return res.status(404).json({ error: 'Terminal session not found' });
+      pending.cancelled = true;
+      try { await pending.promise; }
+      catch (error) {
+        if (error?.message !== 'Terminal session was closed during creation') throw error;
+      }
+      return res.json({ success: true });
+    }
     sessions.delete(session.id);
     closeAttachments(session.id, 'CLOSED', 'Terminal closed');
     await terminateProcess(session.process);