@pi-chamber/web 0.1.8

package/server/lib/terminal/runtime.test.js

@@ -0,0 +1,566 @@
+import { EventEmitter } from 'node:events';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import express from 'express';
+import { WebSocket } from 'ws';
+
+import { createTerminalRuntime } from './runtime.js';
+import { createTerminalWsControlFrame, readTerminalWsControlFrame } from './terminal-ws-protocol.js';
+
+function createResponse() {
+  return {
+    statusCode: 200,
+    body: null,
+    status(code) {
+      this.statusCode = code;
+      return this;
+    },
+    json(payload) {
+      this.body = payload;
+      return this;
+    },
+  };
+}
+
+function createRuntime(server, overrides = {}) {
+  const app = overrides.app ?? {
+    post() {},
+    get() {},
+    delete() {},
+  };
+
+  return createTerminalRuntime({
+    app,
+    server,
+    express: { text: () => (_req, _res, next) => next?.() },
+    fs,
+    path,
+    uiAuthController: null,
+    buildAugmentedPath: () => process.env.PATH || '',
+    searchPathFor: () => null,
+    isExecutable: () => false,
+    isRequestOriginAllowed: async () => true,
+    rejectWebSocketUpgrade() {},
+    TERMINAL_INPUT_WS_HEARTBEAT_INTERVAL_MS: 30_000,
+    TERMINAL_INPUT_WS_REBIND_WINDOW_MS: 1_000,
+    TERMINAL_INPUT_WS_MAX_REBINDS_PER_WINDOW: 3,
+    ...overrides,
+  });
+}
+
+describe('terminal runtime', () => {
+  const createHarness = (overrides = {}) => {
+    const routes = { get: new Map(), post: new Map(), delete: new Map() };
+    const processes = [];
+    const app = {
+      post(route, handler) { routes.post.set(route, handler); },
+      get(route, handler) { routes.get.set(route, handler); },
+      delete(route, handler) { routes.delete.set(route, handler); },
+    };
+    const loadPtyProvider = async () => ({
+      backend: 'fake-pty',
+      spawn: (shell, args, options) => {
+        const dataHandlers = new Set();
+        const exitHandlers = new Set();
+        const process = {
+          pid: 123 + processes.length,
+          shell,
+          args,
+          options,
+          writes: [],
+          resizes: [],
+          killed: false,
+          kills: [],
+          write(data) { this.writes.push(data); },
+          resize(cols, rows) { this.resizes.push([cols, rows]); },
+          kill(signal) { this.killed = true; this.kills.push(signal ?? 'SIGTERM'); },
+          onData(handler) { dataHandlers.add(handler); return { dispose: () => dataHandlers.delete(handler) }; },
+          onExit(handler) { exitHandlers.add(handler); return { dispose: () => exitHandlers.delete(handler) }; },
+          emitData(data) { for (const handler of dataHandlers) handler(data); },
+          emitExit(exitCode = 0, signal = 0) { for (const handler of exitHandlers) handler({ exitCode, signal }); },
+        };
+        processes.push(process);
+        return process;
+      },
+    });
+    const server = new EventEmitter();
+    const runtime = createRuntime(server, {
+      app,
+      loadPtyProvider,
+      terminalTerminationGraceMs: 10,
+      fs: { promises: { stat: async () => ({ isDirectory: () => true }) } },
+      searchPathFor: () => '/bin/sh',
+      isExecutable: () => true,
+      ...overrides,
+    });
+    return { routes, processes, runtime };
+  };
+
+  it('rejects regular files as terminal working directories', async () => {
+    const postRoutes = new Map();
+    const app = {
+      post(route, ...handlers) {
+        postRoutes.set(route, handlers.at(-1));
+      },
+      get() {},
+      delete() {},
+    };
+    const server = new EventEmitter();
+    const runtime = createRuntime(server, {
+      app,
+      fs: {
+        promises: {
+          stat: async () => ({ isDirectory: () => false }),
+        },
+      },
+      uiAuthController: { enabled: false },
+      buildAugmentedPath: () => '',
+      TERMINAL_INPUT_WS_HEARTBEAT_INTERVAL_MS: 1000,
+      TERMINAL_INPUT_WS_REBIND_WINDOW_MS: 1000,
+    });
+
+    try {
+      const createRoute = postRoutes.get('/api/terminal/create');
+      const res = createResponse();
+
+      await createRoute({ body: { cwd: '/tmp/not-a-directory' } }, res);
+
+      expect(res.statusCode).toBe(400);
+      expect(res.body).toEqual({ error: 'Invalid working directory' });
+    } finally {
+      await runtime.shutdown();
+    }
+  });
+
+  it('removes its websocket upgrade listener on shutdown', async () => {
+    const server = new EventEmitter();
+    const runtime = createRuntime(server);
+
+    expect(server.listenerCount('upgrade')).toBe(1);
+
+    await runtime.shutdown();
+
+    expect(server.listenerCount('upgrade')).toBe(0);
+  });
+
+  it('creates client-identified sessions and forwards bounded resize operations', async () => {
+    const harness = createHarness();
+    try {
+      const response = createResponse();
+      await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'term-1', cwd: '/repo', cols: 120, rows: 40, themeMode: 'light', terminalBackground: '#faf8f0', terminalForeground: '#1b1b1b' } }, response);
+      expect(response.body).toEqual({ sessionId: 'term-1', cols: 120, rows: 40, status: 'running' });
+      expect(harness.processes[0].options.cwd).toBe('/repo');
+      expect(harness.processes[0].options.env.COLORFGBG).toBe('0;15');
+      expect(harness.processes[0].options.env.NODE_CHANNEL_FD).toBe('');
+      expect(harness.processes[0].options.env).not.toHaveProperty('ARGV0');
+      expect(harness.processes[0].options.env).not.toHaveProperty('ELECTRON_RUN_AS_NODE');
+      if (process.platform === 'linux') {
+        expect(harness.processes[0].shell).toMatch(/\/env$/);
+        expect(harness.processes[0].args.slice(0, 3)).toEqual(['-u', 'ARGV0', expect.any(String)]);
+      }
+      harness.processes[0].emitData('\u001b[?2031h\u001b]10;?\u0007\u001b]11;?\u0007\u001b[0c');
+      expect(harness.processes[0].writes).toEqual(['\u001b]10;rgb:1b1b/1b1b/1b1b\u001b\\', '\u001b]11;rgb:fafa/f8f8/f0f0\u001b\\', '\u001b[?1;2c']);
+
+      const appearance = createResponse();
+      harness.routes.post.get('/api/terminal/:sessionId/appearance')({ params: { sessionId: 'term-1' }, body: { themeMode: 'dark' } }, appearance);
+      expect(appearance.body).toEqual({ success: true });
+      expect(harness.processes[0].writes.at(-1)).toBe('\u001b[?997;1n');
+
+      const resize = createResponse();
+      harness.routes.post.get('/api/terminal/:sessionId/resize')({ params: { sessionId: 'term-1' }, body: { cols: 200, rows: 60 } }, resize);
+      expect(resize.statusCode).toBe(200);
+      expect(harness.processes[0].resizes).toEqual([[200, 60]]);
+
+      const invalid = createResponse();
+      harness.routes.post.get('/api/terminal/:sessionId/resize')({ params: { sessionId: 'term-1' }, body: { cols: 1001, rows: 60 } }, invalid);
+      expect(invalid.statusCode).toBe(400);
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('strips AppImage ARGV0 from PTY child environments', async () => {
+    const previousArgv0 = process.env.ARGV0;
+    process.env.ARGV0 = '/path/to/PiChamber/PiChamber-1.17.2-linux-x86_64.AppImage';
+    const harness = createHarness();
+    try {
+      const response = createResponse();
+      await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'term-argv0', cwd: '/repo', cols: 80, rows: 24 } }, response);
+      expect(response.statusCode).toBe(200);
+      expect(harness.processes[0].options.env).not.toHaveProperty('ARGV0');
+      if (process.platform === 'linux') {
+        expect(harness.processes[0].shell).toMatch(/\/env$/);
+        expect(harness.processes[0].args[0]).toBe('-u');
+        expect(harness.processes[0].args[1]).toBe('ARGV0');
+      }
+    } finally {
+      if (previousArgv0 === undefined) delete process.env.ARGV0;
+      else process.env.ARGV0 = previousArgv0;
+      await harness.runtime.shutdown();
+    }
+  });
+
+  it('lists available shells and uses the selected shell for create and restart', async () => {
+    const executables = new Set(['/bin/zsh', '/bin/bash', '/bin/sh']);
+    const harness = createHarness({
+      fs: {
+        promises: {
+          stat: async () => ({ isDirectory: () => true }),
+          readFile: async () => '/bin/zsh\n/bin/bash\n/bin/false\n',
+        },
+      },
+      searchPathFor: (name) => executables.has(`/bin/${name}`) ? `/bin/${name}` : null,
+      isExecutable: (candidate) => executables.has(candidate),
+    });
+    try {
+      const listed = createResponse();
+      await harness.routes.get.get('/api/terminal/shells')({}, listed);
+      expect(listed.body).toEqual(expect.arrayContaining([
+        { id: 'auto', name: 'Auto', supportsLogin: true },
+        { id: 'zsh', name: 'zsh', supportsLogin: true },
+        { id: 'bash', name: 'bash', supportsLogin: true },
+        { id: 'sh', name: 'sh', supportsLogin: false },
+      ]));
+
+      const created = createResponse();
+      await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'term-shell', cwd: '/repo', shell: 'zsh', loginShell: true } }, created);
+      expect(created.statusCode).toBe(200);
+      if (process.platform === 'linux') {
+        expect(harness.processes[0].shell).toMatch(/\/env$/);
+        expect(harness.processes[0].args).toEqual(['-u', 'ARGV0', '/bin/zsh', '-l']);
+      } else {
+        expect(harness.processes[0].shell).toBe('/bin/zsh');
+        expect(harness.processes[0].args).toEqual(['-l']);
+      }
+
+      const restarted = createResponse();
+      await harness.routes.post.get('/api/terminal/:sessionId/restart')({ params: { sessionId: 'term-shell' }, body: { shell: 'bash', loginShell: true } }, restarted);
+      expect(restarted.statusCode).toBe(200);
+      if (process.platform === 'linux') {
+        expect(harness.processes[1].shell).toMatch(/\/env$/);
+        expect(harness.processes[1].args).toEqual(['-u', 'ARGV0', '/bin/bash', '-l']);
+      } else {
+        expect(harness.processes[1].shell).toBe('/bin/bash');
+        expect(harness.processes[1].args).toEqual(['-l']);
+      }
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('rejects invalid and unavailable explicit shells', async () => {
+    const harness = createHarness({
+      fs: {
+        promises: {
+          stat: async () => ({ isDirectory: () => true }),
+          readFile: async () => '/bin/sh\n',
+        },
+      },
+      searchPathFor: (name) => name === 'sh' ? '/bin/sh' : null,
+      isExecutable: (candidate) => candidate === '/bin/sh',
+    });
+    try {
+      for (const [shell, error] of [
+        ['zsh -c whoami', 'Invalid terminal shell'],
+        ['fish', 'Terminal shell "fish" is not available'],
+      ]) {
+        const response = createResponse();
+        await harness.routes.post.get('/api/terminal/create')({ body: { cwd: '/repo', shell } }, response);
+        expect(response.statusCode).toBe(400);
+        expect(response.body).toEqual({ error });
+      }
+      expect(harness.processes).toHaveLength(0);
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('rejects invalid and unsupported login modes', async () => {
+    const harness = createHarness({
+      fs: {
+        promises: {
+          stat: async () => ({ isDirectory: () => true }),
+          readFile: async () => '/bin/sh\n',
+        },
+      },
+      searchPathFor: (name) => name === 'sh' ? '/bin/sh' : null,
+      isExecutable: (candidate) => candidate === '/bin/sh',
+    });
+    try {
+      for (const [loginShell, error] of [
+        ['true', 'Invalid terminal login mode'],
+        [true, 'Terminal shell "sh" does not support login mode'],
+      ]) {
+        const response = createResponse();
+        await harness.routes.post.get('/api/terminal/create')({ body: { cwd: '/repo', shell: 'sh', loginShell } }, response);
+        expect(response.statusCode).toBe(400);
+        expect(response.body).toEqual({ error });
+      }
+      expect(harness.processes).toHaveLength(0);
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('preserves the running process when a replacement shell is unavailable', async () => {
+    const harness = createHarness({
+      fs: {
+        promises: {
+          stat: async () => ({ isDirectory: () => true }),
+          readFile: async () => '/bin/sh\n',
+        },
+      },
+      searchPathFor: (name) => name === 'sh' ? '/bin/sh' : null,
+      isExecutable: (candidate) => candidate === '/bin/sh',
+    });
+    try {
+      await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'term-1', cwd: '/repo', shell: 'sh' } }, createResponse());
+      const restarted = createResponse();
+
+      await harness.routes.post.get('/api/terminal/:sessionId/restart')({ params: { sessionId: 'term-1' }, body: { shell: 'fish' } }, restarted);
+
+      expect(restarted.statusCode).toBe(400);
+      expect(restarted.body.error).toBe('Terminal shell "fish" is not available');
+      expect(harness.processes).toHaveLength(1);
+      expect(harness.processes[0].killed).toBe(false);
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('deduplicates concurrent creates and rejects cross-directory id reuse', async () => {
+    const harness = createHarness();
+    try {
+      const create = harness.routes.post.get('/api/terminal/create');
+      const first = createResponse();
+      const second = createResponse();
+      await Promise.all([
+        create({ body: { sessionId: 'term-shared', cwd: '/repo' } }, first),
+        create({ body: { sessionId: 'term-shared', cwd: '/repo' } }, second),
+      ]);
+      expect(harness.processes).toHaveLength(1);
+      expect(first.body.sessionId).toBe('term-shared');
+      expect(second.body.sessionId).toBe('term-shared');
+
+      const conflicting = createResponse();
+      await create({ body: { sessionId: 'term-shared', cwd: '/other' } }, conflicting);
+      expect(conflicting.statusCode).toBe(400);
+      expect(conflicting.body.error).toBe('Terminal session belongs to a different working directory');
+      expect(harness.processes).toHaveLength(1);
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('rejects concurrent creates with conflicting shell preferences', async () => {
+    const harness = createHarness();
+    try {
+      const create = harness.routes.post.get('/api/terminal/create');
+      const first = createResponse();
+      const conflicting = createResponse();
+      await Promise.all([
+        create({ body: { sessionId: 'term-shared', cwd: '/repo', shell: 'auto' } }, first),
+        create({ body: { sessionId: 'term-shared', cwd: '/repo', shell: 'zsh' } }, conflicting),
+      ]);
+
+      expect(first.statusCode).toBe(200);
+      expect(conflicting.statusCode).toBe(400);
+      expect(conflicting.body.error).toBe('Terminal session is already being created with a different shell');
+      expect(harness.processes).toHaveLength(1);
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('rejects concurrent creates with conflicting login modes', async () => {
+    const harness = createHarness();
+    try {
+      const create = harness.routes.post.get('/api/terminal/create');
+      const first = createResponse();
+      const conflicting = createResponse();
+      await Promise.all([
+        create({ body: { sessionId: 'term-shared', cwd: '/repo', shell: 'auto', loginShell: false } }, first),
+        create({ body: { sessionId: 'term-shared', cwd: '/repo', shell: 'auto', loginShell: true } }, conflicting),
+      ]);
+
+      expect(first.statusCode).toBe(200);
+      expect(conflicting.statusCode).toBe(400);
+      expect(conflicting.body.error).toBe('Terminal session is already being created with a different login mode');
+      expect(harness.processes).toHaveLength(1);
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('restarts atomically with the same identity and closes the previous process', async () => {
+    const harness = createHarness();
+    try {
+      await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'term-1', cwd: '/repo' } }, createResponse());
+      const restarted = createResponse();
+      await harness.routes.post.get('/api/terminal/:sessionId/restart')({ params: { sessionId: 'term-1' }, body: { cwd: '/other', cols: 90, rows: 30 } }, restarted);
+      expect(restarted.body).toEqual({ sessionId: 'term-1', cols: 90, rows: 30, status: 'running' });
+      expect(harness.processes).toHaveLength(2);
+      expect(harness.processes[0].killed).toBe(true);
+      expect(harness.processes[1].options.cwd).toBe('/other');
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('serializes concurrent restarts without orphaning replacement processes', async () => {
+    const harness = createHarness();
+    try {
+      const create = harness.routes.post.get('/api/terminal/create');
+      const restart = harness.routes.post.get('/api/terminal/:sessionId/restart');
+      await create({ body: { sessionId: 'term-1', cwd: '/repo' } }, createResponse());
+      const first = createResponse();
+      const second = createResponse();
+
+      await Promise.all([
+        restart({ params: { sessionId: 'term-1' }, body: { cwd: '/first' } }, first),
+        restart({ params: { sessionId: 'term-1' }, body: { cwd: '/second' } }, second),
+      ]);
+
+      expect(first.statusCode).toBe(200);
+      expect(second.statusCode).toBe(200);
+      expect(harness.processes).toHaveLength(3);
+      expect(harness.processes[0].killed).toBe(true);
+      expect(harness.processes[1].killed).toBe(true);
+      expect(harness.processes[2].killed).toBe(false);
+      expect(harness.processes[2].options.cwd).toBe('/second');
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('retains exited sessions until explicit close', async () => {
+    const harness = createHarness();
+    try {
+      await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'term-1', cwd: '/repo' } }, createResponse());
+      harness.processes[0].emitData('last output');
+      harness.processes[0].emitExit(7, 0);
+      const resize = createResponse();
+      harness.routes.post.get('/api/terminal/:sessionId/resize')({ params: { sessionId: 'term-1' }, body: { cols: 80, rows: 24 } }, resize);
+      expect(resize.statusCode).toBe(200);
+      const closed = createResponse();
+      await harness.routes.delete.get('/api/terminal/:sessionId')({ params: { sessionId: 'term-1' } }, closed);
+      expect(closed.body).toEqual({ success: true });
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('escalates close to SIGKILL when a running process ignores SIGTERM', async () => {
+    const harness = createHarness();
+    try {
+      await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'term-1', cwd: '/repo' } }, createResponse());
+      await harness.routes.delete.get('/api/terminal/:sessionId')({ params: { sessionId: 'term-1' } }, createResponse());
+      expect(harness.processes[0].kills).toEqual(['SIGTERM', 'SIGKILL']);
+    } finally { await harness.runtime.shutdown(); }
+  });
+
+  it('runs snapshot-first attach, scoped I/O, replay, reconnect, and close over a real websocket', async () => {
+    const app = express();
+    app.use(express.json());
+    const server = http.createServer(app);
+    const processes = [];
+    const loadPtyProvider = async () => ({
+      backend: 'fake-pty',
+      spawn: () => {
+        const data = new Set();
+        const exits = new Set();
+        const process = {
+          pid: 99123,
+          killed: false,
+          writes: [],
+          write(value) { this.writes.push(value); }, resize() {}, kill() { this.killed = true; },
+          onData(handler) { data.add(handler); return { dispose: () => data.delete(handler) }; },
+          onExit(handler) { exits.add(handler); return { dispose: () => exits.delete(handler) }; },
+          emitData(value) { for (const handler of data) handler(value); },
+          emitExit(exitCode) { for (const handler of exits) handler({ exitCode, signal: 0 }); },
+        };
+        processes.push(process);
+        return process;
+      },
+    });
+    const runtime = createRuntime(server, {
+      app, loadPtyProvider,
+      terminalTerminationGraceMs: 10,
+      fs: { promises: { stat: async () => ({ isDirectory: () => true }) } },
+      searchPathFor: () => '/bin/sh', isExecutable: () => true,
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    const base = `http://127.0.0.1:${address.port}`;
+    const socketUrl = `ws://127.0.0.1:${address.port}/api/terminal/ws`;
+    const sockets = [];
+
+    const open = async () => {
+      const socket = new WebSocket(socketUrl);
+      sockets.push(socket);
+      const messages = [];
+      socket.on('message', (raw) => messages.push(readTerminalWsControlFrame(raw)));
+      await new Promise((resolve, reject) => { socket.once('open', resolve); socket.once('error', reject); });
+      const next = async (type, sessionId) => {
+        for (let attempt = 0; attempt < 100; attempt += 1) {
+          const index = messages.findIndex((message) => message?.t === type && (!sessionId || message.s === sessionId));
+          if (index >= 0) return messages.splice(index, 1)[0];
+          await new Promise((resolve) => setTimeout(resolve, 2));
+        }
+        throw new Error(`Timed out waiting for ${type}`);
+      };
+      await next('hello');
+      return { socket, next, messages };
+    };
+
+    try {
+      const created = await fetch(`${base}/api/terminal/create`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ sessionId: 'term-live', cwd: '/repo', cols: 80, rows: 24 }),
+      });
+      expect(created.status).toBe(200);
+      const secondCreated = await fetch(`${base}/api/terminal/create`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ sessionId: 'term-second', cwd: '/other', cols: 80, rows: 24 }),
+      });
+      expect(secondCreated.status).toBe(200);
+
+      const first = await open();
+      first.socket.send(createTerminalWsControlFrame({ t: 'attach', v: 3, s: 'term-live' }));
+      first.socket.send(createTerminalWsControlFrame({ t: 'attach', v: 3, s: 'term-second' }));
+      expect(await first.next('snapshot', 'term-live')).toMatchObject({ s: 'term-live', q: 0, history: '', status: 'running' });
+      expect(await first.next('snapshot', 'term-second')).toMatchObject({ s: 'term-second', q: 0, history: '', status: 'running' });
+      first.socket.send(createTerminalWsControlFrame({ t: 'write', v: 3, s: 'term-live', d: 'echo ok\r' }));
+      first.socket.send(createTerminalWsControlFrame({ t: 'write', v: 3, s: 'term-second', d: 'pwd\r' }));
+      first.socket.send(createTerminalWsControlFrame({ t: 'write', v: 3, s: 'term-live', d: 'echo next\r' }));
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      expect(processes[0].writes).toEqual(['echo ok\r', 'echo next\r']);
+      expect(processes[1].writes).toEqual(['pwd\r']);
+
+      processes[1].emitData('/other\r\n');
+      expect(await first.next('output', 'term-second')).toMatchObject({ s: 'term-second', q: 1, d: '/other\r\n' });
+      first.socket.send(createTerminalWsControlFrame({ t: 'detach', v: 3, s: 'term-second' }));
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      processes[1].emitData('detached\r\n');
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      expect(first.messages.some((message) => message?.t === 'output' && message.s === 'term-second')).toBe(false);
+
+      processes[0].emitData('ok\r\n');
+      expect(await first.next('output', 'term-live')).toMatchObject({ s: 'term-live', q: 1, d: 'ok\r\n' });
+      processes[0].emitData('\u001b[6n');
+      expect(await first.next('output', 'term-live')).toMatchObject({ s: 'term-live', q: 2, d: '\u001b[6n', r: '' });
+      const secondClosed = await fetch(`${base}/api/terminal/term-second`, { method: 'DELETE' });
+      expect(secondClosed.status).toBe(200);
+      first.socket.close();
+
+      const second = await open();
+      second.socket.send(createTerminalWsControlFrame({ t: 'attach', v: 3, s: 'term-live' }));
+      expect(await second.next('snapshot')).toMatchObject({ s: 'term-live', q: 2, history: 'ok\r\n', status: 'running' });
+      processes[0].emitExit(7);
+      expect(await second.next('exit')).toMatchObject({ s: 'term-live', q: 3, exitCode: 7 });
+
+      const closed = await fetch(`${base}/api/terminal/term-live`, { method: 'DELETE' });
+      expect(closed.status).toBe(200);
+      expect(await second.next('error')).toMatchObject({ s: 'term-live', code: 'CLOSED', fatal: true });
+
+      await fetch(`${base}/api/terminal/create`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ sessionId: 'term-kill', cwd: '/repo' }),
+      });
+      second.socket.send(createTerminalWsControlFrame({ t: 'attach', v: 3, s: 'term-kill' }));
+      await second.next('snapshot');
+      const killed = await fetch(`${base}/api/terminal/force-kill`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ cwd: '/repo' }),
+      });
+      expect(await killed.json()).toEqual({ success: true, killedCount: 1, killedSessionIds: ['term-kill'] });
+      expect(await second.next('error')).toMatchObject({ s: 'term-kill', code: 'KILLED', fatal: true });
+      expect(processes[2].killed).toBe(true);
+    } finally {
+      for (const socket of sockets) socket.terminate();
+      await runtime.shutdown();
+      server.closeAllConnections?.();
+      await new Promise((resolve) => server.close(resolve));
+    }
+  }, 15_000);
+});

package/server/lib/terminal/shells.js

@@ -0,0 +1,100 @@
+const TERMINAL_SHELL_IDS = ['bash', 'zsh', 'sh', 'fish', 'pwsh', 'powershell', 'cmd', 'dash', 'ksh', 'nu'];
+const TERMINAL_SHELL_ID_SET = new Set(TERMINAL_SHELL_IDS);
+
+export const normalizeTerminalShell = (value) => {
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim().toLowerCase();
+  return normalized === 'auto' || TERMINAL_SHELL_ID_SET.has(normalized) ? normalized : null;
+};
+
+const shellIdFromPath = (value) => {
+  const filename = String(value || '').replace(/\\/g, '/').split('/').pop()?.toLowerCase() || '';
+  const id = filename.endsWith('.exe') ? filename.slice(0, -4) : filename;
+  return TERMINAL_SHELL_ID_SET.has(id) ? id : null;
+};
+
+const SHELL_LABELS = { pwsh: 'PowerShell', powershell: 'Windows PowerShell', cmd: 'Command Prompt' };
+const shellLabel = (id) => SHELL_LABELS[id] ?? id;
+
+export const getTerminalShellLoginArgs = (executable, platform = process.platform) => {
+  const id = shellIdFromPath(executable);
+  if (id === 'bash' || id === 'zsh' || id === 'ksh') return ['-l'];
+  if (id === 'fish' || id === 'nu') return ['--login'];
+  if (id === 'pwsh' && platform !== 'win32') return ['-Login'];
+  return null;
+};
+
+export const createTerminalShellResolver = ({ fs, path, searchPathFor, isExecutable, buildAugmentedPath = () => env.PATH || '', platform = process.platform, env = process.env }) => {
+  const resolveExecutable = (candidate) => {
+    if (!candidate) return null;
+    const value = String(candidate);
+    const found = value.includes('/') || value.includes('\\') ? value : searchPathFor(value, buildAugmentedPath());
+    if (found && isExecutable(found)) return found;
+    return isExecutable(value) ? value : null;
+  };
+
+  const defaultCandidates = () => platform === 'win32'
+    ? [
+        env.PICHAMBER_TERMINAL_SHELL,
+        env.SHELL,
+        env.ComSpec,
+        path.join(env.SystemRoot || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+        'pwsh.exe',
+        'powershell.exe',
+        'cmd.exe',
+      ]
+    : [env.PICHAMBER_TERMINAL_SHELL, env.SHELL, '/bin/zsh', '/bin/bash', '/bin/sh', 'zsh', 'bash', 'sh'];
+
+  const resolveCandidates = (candidates) => {
+    const seen = new Set();
+    return candidates
+      .map(resolveExecutable)
+      .filter((candidate) => candidate && !seen.has(candidate) && seen.add(candidate));
+  };
+
+  const list = async () => {
+    let configuredShells = [];
+    if (platform !== 'win32') {
+      try {
+        const contents = await fs.promises.readFile('/etc/shells', 'utf8');
+        configuredShells = contents
+          .split(/\r?\n/)
+          .map((line) => line.trim())
+          .filter((line) => line && !line.startsWith('#'));
+      } catch {
+        // PATH and platform defaults below remain authoritative fallbacks.
+      }
+    }
+
+    const candidates = platform === 'win32'
+      ? [...defaultCandidates(), ...TERMINAL_SHELL_IDS]
+      : [env.PICHAMBER_TERMINAL_SHELL, env.SHELL, ...configuredShells, ...TERMINAL_SHELL_IDS, '/bin/zsh', '/bin/bash', '/bin/sh'];
+    const autoExecutable = resolveCandidates(defaultCandidates())[0] ?? null;
+    const byId = new Map([
+      ['auto', {
+        id: 'auto',
+        name: 'Auto',
+        executable: autoExecutable,
+        supportsLogin: Boolean(autoExecutable && getTerminalShellLoginArgs(autoExecutable, platform)),
+      }],
+    ]);
+    for (const executable of resolveCandidates(candidates)) {
+      const id = shellIdFromPath(executable);
+      if (id && !byId.has(id)) {
+        byId.set(id, { id, name: shellLabel(id), executable, supportsLogin: Boolean(getTerminalShellLoginArgs(executable, platform)) });
+      }
+    }
+    return [...byId.values()];
+  };
+
+  const resolve = async (preference) => {
+    const normalized = normalizeTerminalShell(preference ?? 'auto');
+    if (!normalized) throw new Error('Invalid terminal shell');
+    if (normalized === 'auto') return { id: 'auto', executables: resolveCandidates(defaultCandidates()) };
+    const selected = (await list()).find((shell) => shell.id === normalized);
+    if (!selected) throw new Error(`Terminal shell "${normalized}" is not available`);
+    return { id: selected.id, executables: [selected.executable] };
+  };
+
+  return { list, resolve };
+};