@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/terminal/session.server.ts

@@ -0,0 +1,256 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One PTY-backed shell: how it is created, how it is signalled, and what a
+ * snapshot of it looks like.
+ *
+ * Three behaviours here are load-bearing and were verified against Bun 1.4.2.
+ * Each fails *silently* when broken, which is why they are stated rather than
+ * implied by the code:
+ *
+ * 1. **`detached: true` is mandatory — on POSIX.** Without it the child stays in
+ *    the server's own process group: an interactive shell reports "no job
+ *    control in this shell" (Ctrl+Z and `fg` stop working), `process.kill(-pid, …)`
+ *    fails with ESRCH, and a group signal aimed at the *server's* group would
+ *    take Kabmo down with it. **Windows is the exception and must NOT
+ *    detach**: there `detached` becomes `DETACHED_PROCESS`, the child gets no
+ *    console at all, and `cmd.exe` exits 1 immediately (measured on the CI
+ *    runner — every shell `status: "exited"`). Windows has no process group to
+ *    address; `killProcessTree` uses `taskkill /t`.
+ * 2. **The shell must re-acquire the PTY as its controlling terminal.** `setsid`
+ *    drops it, and a shell without one disables job control regardless of
+ *    `-i`. `shellLaunch` performs the re-open; see that module.
+ * 3. **`Bun.Terminal.resize()` never signals the child** — it updates the
+ *    kernel winsize only, so a TUI would not repaint. The caller sends
+ *    SIGWINCH itself.
+ *
+ * A fourth: a PTY read may split a multi-byte character, so bytes are forwarded
+ * verbatim and xterm's own streaming decoder reassembles them.
+ */
+
+import { resolveRoot } from '@/server/lib/fs/root';
+import { scopeToRepo } from '@/server/lib/fs/repo-scope';
+import { describeSpawnFailure } from '@/server/lib/lifecycle/fd-pressure';
+import { killProcessTree } from '@/server/lib/lifecycle/kill-tree';
+import { createTerminalHistory, type TerminalHistory } from '@/server/lib/terminal/history';
+import { resolveShellExecutable, shellCandidates, shellLaunch, terminalEnv } from '@/server/lib/terminal/shell';
+import { shellSpawnOptions } from '@/server/lib/terminal/spawn';
+import {
+  clampTerminalSize,
+  type TerminalErrorCode,
+  type TerminalSnapshot,
+} from '@/shared/lib/workspace/terminal/protocol';
+
+export const TERMINATION_GRACE_MS = 1000;
+
+/** A socket attached to a terminal. Output is raw PTY bytes; control is JSON. */
+export interface TerminalViewer {
+  /**
+   * Deliver one frame. Returns false when the viewer could not accept it —
+   * the socket's send buffer is over its high-water mark — which the session
+   * treats as "this viewer is gone": a PTY producer cannot be paused, so the
+   * alternative is buffering unbounded output in a socket nobody is reading.
+   */
+  send(frame: string | Uint8Array): boolean;
+  /** Detach this viewer. Called when `send` reports it cannot keep up. */
+  drop(): void;
+}
+
+export interface TerminalSession {
+  id: string;
+  cwd: string;
+  shell: string;
+  term: Bun.Terminal;
+  proc: Bun.Subprocess | null;
+  history: TerminalHistory;
+  viewers: Set<TerminalViewer>;
+  cols: number;
+  rows: number;
+  /** Grid the retained scrollback was drawn for — replay must match it. */
+  replayCols: number;
+  replayRows: number;
+  status: 'running' | 'exited';
+  exitCode: number | null;
+  signal: string | null;
+  lastActivity: number;
+}
+
+/**
+ * Deliver `frame` to every viewer, dropping the ones that cannot keep up.
+ *
+ * `Bun.ServerWebSocket.send` returns the bytes queued, or `-1` when the socket
+ * is over its high-water mark and the frame was NOT sent (verified on 1.4.2:
+ * 40 sends of 1 MiB to a socket nobody reads all return `-1`). A viewer that
+ * reports `-1` is closed rather than skipped — skipping would leave xterm's
+ * parser mid-sequence, so the honest outcome is a reconnect that replays the
+ * scrollback. The PTY cannot be paused, so this is the only backpressure a
+ * terminal has.
+ */
+export function fanOut(session: TerminalSession, frame: string | Uint8Array): void {
+  for (const viewer of session.viewers) {
+    if (viewer.send(frame)) continue;
+    session.viewers.delete(viewer);
+    viewer.drop();
+  }
+}
+
+/** A rejected attach, carrying the code the client shows to the user. */
+export class TerminalRuntimeError extends Error {
+  constructor(
+    readonly code: TerminalErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'TerminalRuntimeError';
+  }
+}
+
+export interface AttachRequest {
+  id: string;
+  cols: number;
+  rows: number;
+  root?: string;
+  repo?: string;
+  theme?: 'light' | 'dark';
+}
+
+export async function createSession(request: AttachRequest): Promise<TerminalSession> {
+  const cwd = await resolveSessionCwd(request.root, request.repo);
+  const executable = await resolveShellExecutable(shellCandidates());
+  if (!executable) {
+    throw new TerminalRuntimeError('shell', 'No usable shell found (checked $SHELL, /bin/zsh, /bin/bash, /bin/sh)');
+  }
+
+  const size = clampTerminalSize(request.cols, request.rows);
+  const session: TerminalSession = {
+    id: request.id,
+    cwd,
+    shell: executable,
+    // Assigned below: the PTY callback closes over `session`, so the record has
+    // to exist before the terminal does.
+    term: undefined as unknown as Bun.Terminal,
+    proc: null,
+    history: createTerminalHistory(),
+    viewers: new Set(),
+    cols: size.cols,
+    rows: size.rows,
+    replayCols: size.cols,
+    replayRows: size.rows,
+    status: 'running',
+    exitCode: null,
+    signal: null,
+    lastActivity: Date.now(),
+  };
+
+  const term = new Bun.Terminal({
+    cols: size.cols,
+    rows: size.rows,
+    name: 'xterm-256color',
+    data(_term, bytes) {
+      session.history.append(bytes);
+      session.lastActivity = Date.now();
+      fanOut(session, bytes);
+    },
+  });
+  session.term = term;
+
+  let proc: Bun.Subprocess;
+  try {
+    proc = Bun.spawn(shellLaunch(executable), shellSpawnOptions({
+      terminal: term,
+      cwd,
+      env: terminalEnv(Bun.env, request.theme ?? 'dark'),
+    }));
+  } catch (error) {
+    closeTerminalStream(session);
+    // `describeSpawnFailure` keeps Bun's own message and adds the real cause
+    // when the process is out of descriptors — the raw error argues about
+    // `/bin/sh`, which is the shim, not the thing that ran out.
+    throw new TerminalRuntimeError('spawn', `Failed to start ${executable}: ${describeSpawnFailure(error)}`);
+  }
+  session.proc = proc;
+
+  void proc.exited.then((code) => {
+    if (session.status === 'exited') return;
+    session.status = 'exited';
+    session.exitCode = code ?? null;
+    session.signal = proc.signalCode ?? null;
+    session.lastActivity = Date.now();
+    const frame = JSON.stringify({ t: 'exit', exitCode: session.exitCode, signal: session.signal });
+    fanOut(session, frame);
+  });
+
+  return session;
+}
+
+async function resolveSessionCwd(root: string | undefined, repo: string | undefined): Promise<string> {
+  const baseDir = await resolveRoot(root ?? null, process.cwd());
+  let scoped = baseDir;
+  try {
+    scoped = await scopeToRepo(baseDir, repo ?? null);
+  } catch {
+    throw new TerminalRuntimeError('cwd', 'Invalid repo path');
+  }
+  const stat = await Bun.file(scoped).stat().catch(() => null);
+  if (!stat?.isDirectory()) throw new TerminalRuntimeError('cwd', `Not a directory: ${scoped}`);
+  return scoped;
+}
+
+export function snapshotOf(session: TerminalSession): TerminalSnapshot {
+  return {
+    id: session.id,
+    cwd: session.cwd,
+    shell: session.shell,
+    cols: session.cols,
+    rows: session.rows,
+    status: session.status,
+    exitCode: session.exitCode,
+    signal: session.signal,
+    bunVersion: Bun.version,
+    // `process.version` is the Node version Bun emulates, not a real binary.
+    nodeVersion: process.version,
+    replayCols: session.replayCols,
+    replayRows: session.replayRows,
+  };
+}
+
+/**
+ * Signal the shell's whole process group — and, on Windows, its whole tree.
+ *
+ * `detached: true` made the shell a session leader on POSIX, so the group holds
+ * every command it started: a build, a dev server, a suspended job. Signalling
+ * the pid alone would leave those behind, and one of them holding the PTY open
+ * keeps the panel attached to a shell that is already dead.
+ *
+ * Windows has no process group to signal, and this used to fall through to
+ * `proc.kill` — the direct child only — which left the same grandchildren
+ * running there with nothing to reap them. `killProcessTree` is the module that
+ * already solves this for the omp child (`taskkill /t`, falling back to the
+ * direct kill), and a shell's foreground command is the same problem.
+ */
+export function signalGroup(session: TerminalSession, signal: NodeJS.Signals): void {
+  const pid = session.proc?.pid;
+  if (!pid) {
+    // No pid to address, but a handle that can still signal itself. A real
+    // `Bun.Subprocess` always has one; this keeps a fake (and a child that has
+    // already been reaped) behaving the way it did before the tree kill.
+    try {
+      session.proc?.kill(signal);
+    } catch {
+      // Already gone.
+    }
+    return;
+  }
+  killProcessTree(pid, signal === 'SIGKILL', signal);
+}
+
+export function closeTerminalStream(session: TerminalSession): void {
+  try {
+    session.term.close();
+  } catch {
+    // Already closed.
+  }
+}

package/src/server/lib/terminal/shell.test.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  resolveShellExecutable,
+  shellArgs,
+  shellCandidates,
+  shellLaunch,
+  terminalEnv,
+} from '@/server/lib/terminal/shell';
+
+describe('shellCandidates', () => {
+  test('prefers an absolute $SHELL over the platform defaults', () => {
+    expect(shellCandidates({ SHELL: '/opt/homebrew/bin/fish' }, 'darwin')[0]).toBe('/opt/homebrew/bin/fish');
+  });
+
+  test('ignores a relative $SHELL so PATH cannot choose the login shell', () => {
+    expect(shellCandidates({ SHELL: 'fish' }, 'darwin')).toEqual(['/bin/zsh', '/bin/bash', '/bin/sh']);
+  });
+
+  test('falls back to the platform defaults without $SHELL', () => {
+    expect(shellCandidates({}, 'linux')).toEqual(['/bin/zsh', '/bin/bash', '/bin/sh']);
+  });
+
+  test('uses COMSPEC on windows', () => {
+    expect(shellCandidates({ COMSPEC: 'C:\\Windows\\System32\\cmd.exe' }, 'win32')).toEqual([
+      'C:\\Windows\\System32\\cmd.exe',
+    ]);
+  });
+});
+
+describe('shellArgs', () => {
+  test('POSIX shells launch interactive and login', () => {
+    // Interactive is what enables job control; without it Ctrl+Z/`fg` are dead.
+    expect(shellArgs('darwin')).toEqual(['-i', '-l']);
+  });
+
+  test('cmd.exe takes neither flag', () => {
+    expect(shellArgs('win32')).toEqual([]);
+  });
+});
+
+describe('shellLaunch', () => {
+  test('re-acquires the controlling terminal before exec on POSIX', () => {
+    // Without this, a detached child has no controlling tty and the shell
+    // silently disables job control.
+    const argv = shellLaunch('/bin/zsh', 'darwin');
+    expect(argv[0]).toBe('/bin/sh');
+    expect(argv[1]).toBe('-c');
+    expect(argv[2]).toContain('exec /bin/zsh -i -l');
+    // `exec` matters: it keeps the pid, so the shell stays the session leader
+    // and a group signal still reaches everything it starts.
+    expect(argv[2].match(/exec /g)?.length).toBe(2);
+  });
+
+  test('re-acquires the terminal through /dev/fd/0, guarded by [ -t 0 ]', () => {
+    // `/dev/tty` resolves through the child's CONTROLLING terminal, which a
+    // `setsid()` child does not have: on Linux the open fails with ENXIO while
+    // macOS tolerates it, so the shim died before the shell started and every
+    // terminal test timed out on CI. `/dev/fd/0` is the PTY the parent already
+    // wired up and resolves on both.
+    const script = shellLaunch('/bin/zsh', 'darwin')[2];
+    expect(script).toContain('</dev/fd/0');
+    expect(script).not.toContain('/dev/tty');
+    // The device nodes are no test at all — both always exist — so the guard
+    // has to ask whether stdin is a terminal. A device-node guard takes the
+    // redirect branch on a child with no terminal, and the failing redirect
+    // then kills the shim (dash exits 2) with the fallback never reached.
+    expect(script).toContain('if [ -t 0 ]; then');
+    expect(script).not.toContain('-c /dev/fd/0');
+    // A shell with no terminal still starts, unredirected: job control is lost,
+    // the terminal is not.
+    expect(script.endsWith('exec /bin/zsh -i -l')).toBe(true);
+  });
+
+  test('runs the shell directly on windows', () => {
+    expect(shellLaunch('cmd.exe', 'win32')).toEqual(['cmd.exe']);
+  });
+});
+
+describe('terminalEnv', () => {
+  test('describes the renderer and theme to the child', () => {
+    const env = terminalEnv({ PATH: '/usr/bin', COLORFGBG: 'stale' }, 'light');
+    expect(env.TERM).toBe('xterm-256color');
+    expect(env.COLORTERM).toBe('truecolor');
+    expect(env.COLORFGBG).toBe('0;15');
+    expect(env.PATH).toBe('/usr/bin');
+  });
+
+  test('drops Kabmo IPC descriptor', () => {
+    // An inherited NODE_CHANNEL_FD makes Node CLIs print IPC parse errors.
+    const env = terminalEnv({ NODE_CHANNEL_FD: '3' }, 'dark');
+    expect('NODE_CHANNEL_FD' in env).toBe(false);
+    expect(env.COLORFGBG).toBe('15;0');
+  });
+
+  test('Kabmo host env does not reach the shell', () => {
+    // Measured before this: a PTY under a Kabmo serving 3001 reported
+    // `PORT=3001 NODE_ENV=production`, so `bun run dev` typed into the terminal
+    // panel failed with "Port 3001 is already served by Kabmo" while the
+    // same command in a plain terminal ran on 3000.
+    const env = terminalEnv({ PATH: '/usr/bin', PORT: '3001', NODE_ENV: 'production', NEXT_PUBLIC_X: '1' }, 'dark');
+    expect('PORT' in env).toBe(false);
+    expect('NODE_ENV' in env).toBe(false);
+    expect('NEXT_PUBLIC_X' in env).toBe(false);
+    // The rest of the environment still passes through, or the shell loses PATH.
+    expect(env.PATH).toBe('/usr/bin');
+  });
+});
+
+describe('resolveShellExecutable', () => {
+  test('returns the first candidate that exists', async () => {
+    const checked: string[] = [];
+    const resolved = await resolveShellExecutable(['/nope/zsh', '/bin/bash'], async (target) => {
+      checked.push(target);
+      return target === '/bin/bash';
+    });
+    expect(resolved).toBe('/bin/bash');
+    expect(checked).toEqual(['/nope/zsh', '/bin/bash']);
+  });
+
+  test('reports no shell when nothing exists', async () => {
+    expect(await resolveShellExecutable(['/nope'], async () => false)).toBeNull();
+  });
+});

package/src/server/lib/terminal/shell.ts

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which shell the PTY runtime launches, with which argv, and with which
+ * environment.
+ *
+ * Resolution is a pure function of the environment plus an existence probe, so
+ * the preference order stays testable without spawning anything: the user's
+ * `$SHELL` first, then the platform's usual suspects.
+ */
+
+import { stripKabmoHostEnv } from '@kabmo-labs/kabmo-sdk';
+
+const POSIX_FALLBACKS = ['/bin/zsh', '/bin/bash', '/bin/sh'];
+
+/** Candidate executables, most preferred first. */
+export function shellCandidates(
+  env: Record<string, string | undefined> = Bun.env,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  if (platform === 'win32') {
+    const comspec = env.COMSPEC?.trim();
+    return comspec ? [comspec] : ['cmd.exe'];
+  }
+  const candidates: string[] = [];
+  const preferred = env.SHELL?.trim();
+  // Only an absolute $SHELL is trusted: a bare name would be resolved against
+  // PATH at spawn time, which is not the login shell the user configured.
+  if (preferred && preferred.startsWith('/')) candidates.push(preferred);
+  for (const fallback of POSIX_FALLBACKS) {
+    if (!candidates.includes(fallback)) candidates.push(fallback);
+  }
+  return candidates;
+}
+
+/**
+ * `-i -l` for POSIX shells: interactive (prompt, line editing, job control —
+ * job control is what makes Ctrl+Z/`fg` work at all) and login (the user's
+ * profile, so PATH and aliases match a normal terminal). cmd.exe takes neither.
+ */
+export function shellArgs(platform: NodeJS.Platform = process.platform): string[] {
+  return platform === 'win32' ? [] : ['-i', '-l'];
+}
+
+/**
+ * Full argv for the PTY child.
+ *
+ * POSIX shells are launched through a one-line `/bin/sh` shim that re-acquires
+ * the PTY as its controlling terminal before `exec`-ing the real shell:
+ *
+ *     if [ -t 0 ]; then exec <shell> -i -l </dev/fd/0 >/dev/fd/0 2>&1; fi; exec <shell> -i -l
+ *
+ * This is required, not cosmetic. The runtime must spawn with
+ * `detached: true` — without it the child lands in the *server's* process
+ * group, where a group signal would take Kabmo down and `SIGWINCH`
+ * cannot be addressed to the shell alone. But `setsid()` also drops the
+ * controlling terminal, and a shell with no controlling tty silently disables
+ * job control (`setopt monitor` fails): Ctrl+Z, `fg` and `jobs` stop working,
+ * and typing while a foreground command runs goes to that command instead of
+ * the shell. Re-opening the terminal as stdin/stdout restores it. Verified on
+ * both macOS and Linux: with the shim `tpgid` is the shell's own pid and
+ * `setopt monitor` succeeds; without it `tpgid` is -1 and Ctrl+Z is swallowed.
+ *
+ * Two details are load-bearing, and each was a real failure:
+ *
+ * - **The device is `/dev/fd/0`, not `/dev/tty`.** `/dev/tty` resolves through
+ *   the child's *controlling terminal*, and a `setsid()` child has none — so on
+ *   Linux the open fails with `ENXIO` ("no such device or address") even though
+ *   the node exists, while on macOS the same open succeeds because Darwin
+ *   tolerates it. That platform split is what took CI down: every terminal test
+ *   timed out because the shim died before the shell ever started. `/dev/fd/0`
+ *   is the PTY the parent already wired up, so it needs no controlling terminal
+ *   to resolve and is correct on both.
+ * - **The guard is `[ -t 0 ]`**, which asks whether stdin is a terminal. The
+ *   device nodes are no test at all — `/dev/tty` always exists and `/dev/fd/0`
+ *   always exists — so a guard built on them takes the redirect branch on a
+ *   child that has no terminal, and the failing redirect then kills the shim
+ *   (dash exits 2, the shell never starts) with the fallback never reached.
+ *
+ * This replaces `T=$(tty 2>/dev/null); … <"$T" >"$T"`, which paid a whole
+ * `/usr/bin/tty` subprocess per terminal to learn a path the kernel already
+ * resolves. Measured to spawn: 5.37 ms -> 3.32 ms on macOS.
+ *
+ * `exec` keeps the pid, so the shell stays the session leader and group kill
+ * still reaches everything it starts. If stdin is not a terminal the shell runs
+ * unredirected — stdio is already wired to whatever the parent gave it, only
+ * job control is lost.
+ */
+export function shellLaunch(executable: string, platform: NodeJS.Platform = process.platform): string[] {
+  if (platform === 'win32') return [executable];
+  const inner = [executable, ...shellArgs(platform)].join(' ');
+  return [
+    '/bin/sh',
+    '-c',
+    `if [ -t 0 ]; then exec ${inner} </dev/fd/0 >/dev/fd/0 2>&1; fi; exec ${inner}`,
+  ];
+}
+
+/**
+ * Environment for the PTY child. `TERM`/`COLORTERM` describe the renderer on
+ * the other end of the socket; `COLORFGBG` carries the active Kabmo theme so
+ * prompts that read it (zsh themes, vim) pick readable colors.
+ *
+ * The Kabmo's OWN variables are removed by the shared SDK rule, for the same
+ * reason `NODE_CHANNEL_FD` and the password are: this shell must behave like the
+ * one on the operator's desktop, and `PORT` here is the port Kabmo is
+ * serving (the CLI sets it on the server process) — measured, a PTY under a
+ * Kabmo on 3001 reported `PORT=3001 NODE_ENV=production`, so a `bun run dev`
+ * typed into this panel hit "Port 3001 is already served by Kabmo" while
+ * the same command in a plain terminal ran on 3000. `NODE_ENV` matters beyond
+ * the port: it decides dev vs production for whatever the user runs, and
+ * `production` makes `bun install`/`npm install` skip devDependencies.
+ */
+export function terminalEnv(
+  base: Record<string, string | undefined>,
+  theme: 'light' | 'dark' = 'dark',
+): Record<string, string | undefined> {
+  const env: Record<string, string | undefined> = stripKabmoHostEnv(base, process.platform);
+  // The Kabmo's own IPC descriptor is host-private and meaningless inside the
+  // PTY; an inherited value makes Node CLIs fail to parse their IPC channel.
+  delete env.NODE_CHANNEL_FD;
+  // Belt and braces. `lib/auth/env-password.ts` already removes this at boot, so
+  // the value should never reach here — but the shell panel is the one place a
+  // leaked password is trivially readable (`echo $KABMO_UI_PASSWORD`), and
+  // a future refactor of the boot path must not be able to reintroduce that.
+  delete env.KABMO_UI_PASSWORD;
+  delete env.OMPCHAMBER_UI_PASSWORD;
+  env.TERM = 'xterm-256color';
+  env.COLORTERM = 'truecolor';
+  env.COLORFGBG = theme === 'light' ? '0;15' : '15;0';
+  return env;
+}
+
+/** First candidate that exists on disk, or null when none does. */
+export async function resolveShellExecutable(
+  candidates: string[],
+  exists: (target: string) => Promise<boolean> = async (target) => Bun.file(target).exists(),
+): Promise<string | null> {
+  for (const candidate of candidates) {
+    if (await exists(candidate)) return candidate;
+  }
+  return null;
+}

package/src/server/lib/terminal/spawn.test.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The one spawn option that differs by platform, asserted per platform.
+ *
+ * `detached` is not a portable idea. On POSIX it is `setsid()` and the terminal
+ * panel needs it; on Windows it is `DETACHED_PROCESS`, which gives the child NO
+ * console — and `cmd.exe` will not run without one, so every shell died with
+ * `exitCode: 1` within a second. Measured on the Windows CI runner: all eight
+ * attached shells came back `status: "exited"`, which made the terminal panel
+ * look broken and left the capacity cap counting nothing.
+ *
+ * A POSIX-only run cannot observe that, which is why the options are built by a
+ * function taking a `platform` argument instead of a literal at the spawn site.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { shellSpawnOptions } from '@/server/lib/terminal/spawn';
+
+/** A stand-in for the PTY; the builder only passes it through. */
+const TERMINAL = { cols: 80, rows: 24 } as unknown as Bun.Terminal;
+const BASE = { terminal: TERMINAL, cwd: '/work', env: { PATH: '/usr/bin' } };
+
+describe('shellSpawnOptions', () => {
+  test('POSIX detaches, so a group signal reaches what the shell started', () => {
+    // Without it the child sits in the SERVER's process group: `kill(-pid)` is
+    // ESRCH, Ctrl+Z stops working, and a group signal would take Kabmo
+    // down with the shell.
+    for (const platform of ['darwin', 'linux'] as const) {
+      expect(shellSpawnOptions({ ...BASE, platform }).detached).toBe(true);
+    }
+  });
+
+  test('Windows does NOT detach, because DETACHED_PROCESS leaves no console', () => {
+    // The bug this pins: with `detached: true` the shell had no console at all
+    // and `cmd.exe` exited 1 immediately, so the panel showed a dead terminal
+    // and the cap counted zero shells.
+    expect(shellSpawnOptions({ ...BASE, platform: 'win32' }).detached).toBe(false);
+  });
+
+  test('everything else is passed through unchanged', () => {
+    const options = shellSpawnOptions({ ...BASE, platform: 'win32' });
+    expect(options.terminal).toBe(TERMINAL);
+    expect(options.cwd).toBe('/work');
+    expect(options.env).toEqual({ PATH: '/usr/bin' });
+  });
+});

package/src/server/lib/terminal/spawn.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The spawn options for a PTY shell, assembled in one place because ONE of them
+ * is platform-bound and getting it wrong is silent in the worst way: the shell
+ * starts, dies, and the panel looks broken with nothing in the log.
+ *
+ * POSIX needs `detached: true`. `setsid()` makes the shell its own process-group
+ * leader, which is what lets `process.kill(-pid, …)` reach a foreground command
+ * and what keeps a group signal from taking Kabmo down with the shell. The
+ * controlling terminal it costs is restored by the `shellLaunch` shim.
+ *
+ * Windows must NOT detach. `detached` maps to `UV_PROCESS_DETACHED`, which passes
+ * `DETACHED_PROCESS` to `CreateProcessW` — a child with **no console at all**.
+ * `cmd.exe` will not run without one, so every shell exited with code 1 within a
+ * second (measured on the Windows CI runner: all eight attached shells came back
+ * `status: "exited"`, `exitCode: 1`), which left the cap counting nothing and
+ * the panel showing a dead terminal. Windows has no process group to address
+ * anyway — `killProcessTree` walks the tree with `taskkill /t`.
+ *
+ * It is a builder rather than a literal at the spawn site because the whole
+ * point is a value a POSIX-only test run cannot observe: the assertions have to
+ * ask for the Windows options explicitly.
+ */
+
+export interface ShellSpawnInput {
+  /** The PTY the child's stdio is wired to. */
+  terminal: Bun.Terminal;
+  /** Working directory the shell opens in. */
+  cwd: string;
+  /** Environment for the child (already stripped of Kabmo's own). */
+  env: Record<string, string | undefined>;
+  /** Platform override, so the Windows branch is reachable from a POSIX run. */
+  platform?: NodeJS.Platform;
+}
+
+/** Options for `Bun.spawn` when the child is an interactive shell on a PTY. */
+export function shellSpawnOptions({ terminal, cwd, env, platform = process.platform }: ShellSpawnInput): {
+  terminal: Bun.Terminal;
+  detached: boolean;
+  cwd: string;
+  env: Record<string, string | undefined>;
+} {
+  // Windows deliberately false: `DETACHED_PROCESS` gives the child no console,
+  // and a shell cannot run without one. Every other platform needs the session
+  // so a group signal reaches what the shell started.
+  return { terminal, detached: platform !== 'win32', cwd, env };
+}