@keith9681/dsh-sidebar 0.15.2

package/src/pty-deps.ts

@@ -0,0 +1,240 @@
+/**
+ * node-pty dependency loading for the host half (issue #140, plugin side).
+ *
+ * The terminal surfaces (UI tabs + model-facing terminal_* tools) need
+ * node-pty, but the package must NEVER be imported statically at module
+ * top level: a missing or broken install (pnpm 11's strict-dep-builds
+ * skipping node-pty's install script, a pruned store entry, a failed
+ * prebuilt-binary download…) would then fail the plugin module load and —
+ * because a loader entry apply failure aborts the boot — take the whole
+ * `dsh web` server down with it.
+ *
+ * Instead the host half loads node-pty lazily (synchronously, via
+ * createRequire — the same resolution `ensureSpawnHelper` already uses in
+ * production). When the load fails the plugin stays mounted in a degraded
+ * state: the terminal tab shows a friendly error carrying a pasteable
+ * repair command (see scripts/install.sh / install.ps1 `--repair`), and the
+ * agent terminal tools are simply not registered.
+ *
+ * Version contract: the plugin must stay in sync with DSH core —
+ * `@deepseek-ai/dsh-subprocess-local` declares `"node-pty": "^1.1.0"` in
+ * its `dependencies`. Both sides then resolve the SAME pnpm store entry
+ * (same range, same integrity → one native binding, no drift). Do NOT
+ * switch to a fork (e.g. @lydell/node-pty) or a different range without
+ * re-checking the core declaration.
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { homedir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type * as nodePtyNs from 'node-pty'
+import { SidebarError } from './wire.ts'
+
+/** The node-pty module surface the registries consume (spawn/kill/resize/…). */
+export type NodePtyModule = typeof nodePtyNs
+
+/**
+ * The node-pty version range this plugin ships. MUST stay identical to the
+ * range DSH core declares (`@deepseek-ai/dsh-subprocess-local`): the same
+ * range keeps pnpm resolving both to one physical package.
+ */
+export const DSH_NODE_PTY_RANGE = '^1.1.0'
+
+/**
+ * The WebSocket close-code-1011 reason the host sends when node-pty is
+ * unavailable. The client recognizes this exact marker and fetches the full
+ * repair details from `/sidebar/api/terminal.deps` (a WS close reason is
+ * capped at 123 bytes, so the command itself cannot ride the close frame).
+ */
+export const PTY_DEPS_MISSING = 'pty-deps-missing'
+
+/** A require-compatible loader, injectable for tests. */
+export type NodePtyRequire = (id: string) => unknown
+
+const defaultRequire: NodePtyRequire = createRequire(import.meta.url)
+
+type LoadResult = { ok: true; module: NodePtyModule } | { ok: false; cause: unknown }
+
+let cached: LoadResult | undefined
+
+/**
+ * Load node-pty once (synchronously) and cache the outcome. Returns null
+ * when the package or its native binding cannot be loaded; the cause stays
+ * queryable through {@link nodePtyLoadCause}. Never throws.
+ */
+export function loadNodePty(requireImpl: NodePtyRequire = defaultRequire): NodePtyModule | null {
+  if (cached === undefined) {
+    try {
+      cached = { ok: true, module: requireImpl('node-pty') as NodePtyModule }
+    } catch (cause) {
+      cached = { ok: false, cause }
+    }
+  }
+  return cached.ok ? cached.module : null
+}
+
+/** The recorded load failure (undefined when the load succeeded or never ran). */
+export function nodePtyLoadCause(): unknown {
+  return cached !== undefined && !cached.ok ? cached.cause : undefined
+}
+
+/** Forget the cached outcome (tests only — a real reload is otherwise one-shot). */
+export function resetNodePtyCache(): void {
+  cached = undefined
+}
+
+/** Load node-pty or throw the canonical degraded-mode error (class-constructor default). */
+export function loadRequiredNodePty(): NodePtyModule {
+  const module = loadNodePty()
+  if (module === null) {
+    const cause = describeCause(nodePtyLoadCause())
+    throw new SidebarError(
+      'pty-deps-missing',
+      `node-pty (${DSH_NODE_PTY_RANGE}) failed to load: ${cause} — run the repair command shown in the terminal tab`,
+      503,
+    )
+  }
+  return module
+}
+
+/** Resolve a directory to its physical location (symlinked/link: installs). */
+function realDir(file: string): string {
+  try {
+    return dirname(realpathSync(file))
+  } catch {
+    return dirname(file)
+  }
+}
+
+/** Walk up from `dir` looking for a DSH profile root (package.json + pnpm-workspace.yaml). */
+function walkUp(dir: string, isRoot: (dir: string) => boolean): string | null {
+  let current = dir
+  for (let depth = 0; depth < 16; depth += 1) {
+    if (isRoot(current)) return current
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return null
+}
+
+/** Whether `dir` looks like a DSH profile root (the plugin lives under its node_modules). */
+function isProfileRoot(dir: string): boolean {
+  return existsSync(join(dir, 'package.json')) && existsSync(join(dir, 'pnpm-workspace.yaml'))
+}
+
+/**
+ * Detect the DSH profile directory this plugin is installed into: the
+ * nearest ancestor of the plugin module that carries both `package.json`
+ * and `pnpm-workspace.yaml` (the profile root; the plugin resolves from the
+ * profile's node_modules). Falls back to `$DSH_HOME/profiles/web` (the
+ * standard web profile), then null.
+ */
+export function findProfileDir(fromFile: string = fileURLToPath(import.meta.url)): string | null {
+  const detected = walkUp(realDir(fromFile), isProfileRoot)
+  if (detected !== null) return detected
+  const home = process.env.DSH_HOME !== undefined && process.env.DSH_HOME.trim() !== ''
+    ? process.env.DSH_HOME
+    : join(homedir(), '.dsh')
+  const web = join(home, 'profiles', 'web')
+  return isProfileRoot(web) ? realpathSync(web) : null
+}
+
+/** Whether `dir`'s package.json declares this plugin's name. */
+function isPluginRoot(dir: string): boolean {
+  const file = join(dir, 'package.json')
+  if (!existsSync(file)) return false
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as { name?: unknown }
+    return parsed.name === 'dsh-better-sidebar'
+  } catch {
+    return false
+  }
+}
+
+/** The plugin package root (walk-up from the module; works for lib/ and src/ layouts). */
+export function findPluginRoot(fromFile: string = fileURLToPath(import.meta.url)): string | null {
+  return walkUp(realDir(fromFile), isPluginRoot)
+}
+
+/** Options for {@link buildRepairCommand}. */
+export interface RepairCommandOptions {
+  /** The plugin package root (where scripts/install.sh / install.ps1 live). */
+  pluginRoot: string | null
+  /** The detected profile directory (null → the standard `web` profile). */
+  profileDir: string | null
+  /** Platform override for tests; defaults to the live process. */
+  platform?: NodeJS.Platform
+}
+
+/**
+ * The pasteable repair command for a broken node-pty install: rerun the
+ * plugin's own installer in `--repair` mode (idempotent: it re-writes the
+ * profile's `allowBuilds: node-pty: true` and re-installs/rebuilds the
+ * dependency). Falls back to DSH's plugin command when the scripts are not
+ * shipped (exotic layouts).
+ */
+export function buildRepairCommand(options: RepairCommandOptions): { command: string; note?: string } {
+  const { pluginRoot, profileDir } = options
+  const platform = options.platform ?? process.platform
+  const profileName = profileDir !== null ? basename(profileDir) : null
+  const profileArg = profileName !== null
+    ? (platform === 'win32' ? ` -Profile "${profileName}"` : ` --profile "${profileName}"`)
+    : ''
+  if (pluginRoot !== null) {
+    if (platform === 'win32') {
+      const script = join(pluginRoot, 'scripts', 'install.ps1')
+      if (existsSync(script)) {
+        return { command: `powershell -ExecutionPolicy Bypass -File "${script}" -Repair${profileArg}` }
+      }
+    } else {
+      const script = join(pluginRoot, 'scripts', 'install.sh')
+      if (existsSync(script)) {
+        return { command: `bash "${script}" --repair${profileArg}` }
+      }
+    }
+  }
+  const name = profileName ?? 'web'
+  return {
+    command: `dsh plugin --profile "${name}" install`,
+    note: 'If pnpm 11 blocked node-pty\'s build script, ensure `allowBuilds: node-pty: true` in the profile\'s pnpm-workspace.yaml (the plugin\'s scripts/install.sh / install.ps1 --repair does this automatically).',
+  }
+}
+
+/** One-line human description of the recorded load cause. */
+function describeCause(cause: unknown): string {
+  if (cause instanceof Error) return cause.message
+  return String(cause)
+}
+
+/** Structured status served by the `/sidebar/api/terminal.deps` endpoint. */
+export type NodePtyDepsStatus =
+  | { ok: true }
+  | {
+    ok: false
+    /** The require-time error message (module missing, native binding broken…). */
+    cause: string
+    /** The pasteable repair command (terminal/cmd). */
+    command: string
+    /** The detected profile name (null when undetected → the command defaults to web). */
+    profile: string | null
+    /** Optional supplementary hint (fallback command only). */
+    note?: string
+  }
+
+/** Current node-pty dependency status (loaded vs degraded + repair info). */
+export function depsStatus(options: { fromFile?: string } = {}): NodePtyDepsStatus {
+  const module = loadNodePty()
+  if (module !== null) return { ok: true }
+  const pluginRoot = findPluginRoot(options.fromFile)
+  const profileDir = findProfileDir(options.fromFile)
+  const { command, note } = buildRepairCommand({ pluginRoot, profileDir })
+  return {
+    ok: false,
+    cause: describeCause(nodePtyLoadCause()),
+    command,
+    profile: profileDir !== null ? basename(profileDir) : null,
+    ...(note !== undefined ? { note } : {}),
+  }
+}

package/src/pty-manager.ts

@@ -0,0 +1,376 @@
+/**
+ * PTY session table for the sidebar terminals. One node-pty process per
+ * `${sessionId}:${tabId}` key; processes survive WebSocket disconnects
+ * (page refresh, tab switch) and reconnect to the same process by key.
+ * Output is mirrored into a bounded transcript ring (capped bytes) so a new
+ * connection replays history before live data. Sessions die only when the
+ * tab is closed or the plugin tears down.
+ */
+import { chmodSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { createRequire } from 'node:module'
+import { userInfo } from 'node:os'
+import type { IPty } from 'node-pty'
+import { loadRequiredNodePty, type NodePtyModule } from './pty-deps.ts'
+import { SidebarError } from './wire.ts'
+
+/** Per-terminal transcript bound (bytes kept for replay). */
+const TRANSCRIPT_LIMIT = 1 << 20
+
+/**
+ * Restore the executable bit pnpm strips from node-pty's prebuilt
+ * spawn-helper (the macOS helper that forks and sets up the pty). Without it
+ * every spawn fails with `posix_spawnp failed`. Idempotent; mirrors
+ * @deepseek-ai/dsh-terminal-bash's ensure-spawn-helper postinstall, run at
+ * plugin activation so link-installed deployments get the fix too.
+ */
+export function ensureSpawnHelper(): void {
+  if (process.platform === 'win32') return
+  try {
+    const require = createRequire(import.meta.url)
+    const entry = require.resolve('node-pty')
+    const packageRoot = dirname(dirname(entry))
+    const candidates = [
+      join(packageRoot, 'prebuilds', `${process.platform}-${process.arch}`, 'spawn-helper'),
+      join(packageRoot, 'build', 'Release', 'spawn-helper'),
+    ]
+    for (const helper of candidates) {
+      if (existsSync(helper)) chmodSync(helper, 0o755)
+    }
+  } catch {
+    // Resolution or chmod failure: the terminal surfaces its own spawn error.
+  }
+}
+
+/** One live terminal. */
+export interface SidebarPty {
+  /** `${sessionId}:${tabId}` registry key. */
+  key: string
+  sessionId: string
+  tabId: string
+  /** The working directory the process was SPAWNED with (a reconnect that
+   *  resolves a different authoritative cwd respawns instead of reusing —
+   *  the page-load hydrate race can attach the real cwd after the first
+   *  connect, and a shell in the wrong directory must not linger). */
+  cwd: string
+  pty: IPty
+  /** Output accumulated since spawn (bounded; head dropped when over the limit). */
+  transcript: string
+  /** Whether the top-level process exited (transcript stays replayable). */
+  exited: boolean
+  exitCode?: number | null
+}
+
+/**
+ * The terminal registry. `maxPerSession` bounds concurrent processes per
+ * conversation (the client caps tabs at the same number).
+ *
+ * Lifecycle of a UI-tab pty when its WebSocket drops:
+ * - **Close frame** (`{type:'close'}`): the user closed the tab → schedule a
+ *   0-ms close (quota released immediately).
+ * - **Park frame** (`{type:'park'}`): the user switched to another
+ *   conversation; the tab is still open in its session's persisted state but
+ *   its view unmounted → mark the pty as parked (no auto-close countdown).
+ *   The pty stays alive until the user switches back (a reconnecting view
+ *   calls `open()` which clears the parked state) or the tab is later closed
+ *   (a `{type:'close'}` frame from a fresh connection). Without `park`, a
+ *   bare socket drop would start the reconnect-grace countdown and kill the
+ *   shell after `reconnectGraceMs` — wrong for a session switch, where the
+ *   user is still actively using the app, just in another conversation.
+ * - **Bare socket drop** (no frame): page refresh, crash, plugin teardown →
+ *   schedule a close after `reconnectGraceMs` so a quick reconnect reattaches
+ *   the same shell.
+ */
+export class PtyManager {
+  private readonly sessions = new Map<string, SidebarPty>()
+  private readonly pendingCloses = new Map<string, ReturnType<typeof setTimeout>>()
+  /** Tabs whose view unmounted because the user switched conversations — the
+   *  tab is still open in its session's state, so the pty must NOT enter the
+   *  reconnect-grace countdown. Cleared by `cancelClose` (a reconnecting
+   *  view's `open()` cancels it) or by `scheduleClose` (an explicit close
+   *  frame still kills a parked pty). */
+  private readonly parked = new Set<string>()
+
+  constructor(
+    private readonly shell: string,
+    private readonly maxPerSession: number,
+    private readonly shellArgs: string[] = [],
+    /** The loaded node-pty module (injected so a broken install degrades instead of crashing the plugin). */
+    private readonly nodePty: NodePtyModule = loadRequiredNodePty(),
+  ) {}
+
+  /** All live terminal keys of one session. */
+  keysOf(sessionId: string): string[] {
+    const keys: string[] = []
+    for (const handle of this.sessions.values()) {
+      if (handle.sessionId === sessionId) keys.push(handle.key)
+    }
+    return keys
+  }
+
+  /**
+   * Open (or reuse) the terminal for a session/tab key. A handle whose
+   * process already exited is replaced with a fresh spawn (reconnecting a
+   * dead terminal must yield a live shell, not an input sink), and so is a
+   * live handle whose spawn cwd differs from the now-authoritative one (the
+   * first connect of a page load can arrive before the session hydrates, so
+   * it fell back to the process cwd — reconnecting with the real cwd must
+   * restart the shell in the right directory). Reopening also cancels any
+   * pending scheduled close (a reconnect within the grace window keeps the
+   * process alive).
+   * @param sessionId - conversation id.
+   * @param tabId - client tab id.
+   * @param cwd - initial working directory (the session's cwd).
+   * @param cols - initial terminal width.
+   * @param rows - initial terminal height.
+   * @returns the live handle.
+   * @throws {SidebarError} pty-error when the per-session cap is reached.
+   */
+  open(
+    sessionId: string,
+    tabId: string,
+    cwd: string,
+    cols: number,
+    rows: number,
+    shell?: string,
+    shellArgs?: string[],
+  ): SidebarPty {
+    const key = `${sessionId}:${tabId}`
+    this.cancelClose(key)
+    const existing = this.sessions.get(key)
+    if (existing !== undefined && !existing.exited && existing.cwd === cwd) return existing
+    if (existing !== undefined) this.close(key)
+    // Zombie cleanup: a session's exited handles (shell closed, tab dropped
+    // on an old host without the close frame) must not eat the quota.
+    for (const [candidate, handle] of [...this.sessions]) {
+      if (handle.sessionId === sessionId && handle.exited) this.close(candidate)
+    }
+    if (this.keysOf(sessionId).length >= this.maxPerSession) {
+      throw new SidebarError('pty-error', `terminal limit reached (${this.maxPerSession}) for this session`, 400)
+    }
+    const handle: SidebarPty = {
+      key,
+      sessionId,
+      tabId,
+      cwd,
+      pty: this.nodePty.spawn(shell ?? this.shell, shellSpawnArgs(shellArgs ?? this.shellArgs), {
+        name: 'xterm-256color',
+        cols: Math.max(2, Math.floor(cols)),
+        rows: Math.max(2, Math.floor(rows)),
+        cwd,
+        env: { ...process.env },
+      }),
+      transcript: '',
+      exited: false,
+    }
+    handle.pty.onData((data) => {
+      handle.transcript += data
+      if (handle.transcript.length > TRANSCRIPT_LIMIT) {
+        handle.transcript = handle.transcript.slice(handle.transcript.length - TRANSCRIPT_LIMIT)
+      }
+    })
+    handle.pty.onExit(({ exitCode }) => {
+      handle.exited = true
+      handle.exitCode = exitCode
+    })
+    this.sessions.set(key, handle)
+    return handle
+  }
+
+  /**
+   * Schedule the terminal's destruction after `delayMs`. A tab close sends
+   * delay 0 (release the quota immediately); a bare socket drop (refresh,
+   * crash) uses the grace period so a quick reconnect keeps the process.
+   * `open()` cancels any pending close. Clears the parked state — an explicit
+   * close frame on a parked pty (the user switched back and closed the tab)
+   * still kills it.
+   */
+  scheduleClose(key: string, delayMs: number): void {
+    const handle = this.sessions.get(key)
+    if (handle === undefined) return
+    this.cancelClose(key)
+    const timer = setTimeout(() => { this.close(key) }, delayMs)
+    this.pendingCloses.set(key, timer)
+  }
+
+  /**
+   * Park a terminal: the owning tab's view unmounted because the user
+   * switched to another conversation, but the tab is still open in its
+   * session's persisted state. Cancels any pending grace close and marks
+   * the pty so the host's `ws.on('close')` handler does NOT start the
+   * reconnect-grace countdown — the pty stays alive until the user switches
+   * back (a reconnecting view's `open()` clears this) or explicitly closes
+   * the tab (a `{type:'close'}` frame's `scheduleClose` clears this).
+   */
+  park(key: string): void {
+    if (this.sessions.get(key) === undefined) return
+    this.cancelClose(key)
+    this.parked.add(key)
+  }
+
+  /** Whether this pty was parked (its view unmounted for a session switch). */
+  isParked(key: string): boolean {
+    return this.parked.has(key)
+  }
+
+  /** Cancel a pending scheduled close (the terminal is being reopened).
+   *  Also clears the parked state — a reconnecting view reattaches a parked
+   *  pty and resumes normal lifecycle. */
+  cancelClose(key: string): void {
+    const timer = this.pendingCloses.get(key)
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      this.pendingCloses.delete(key)
+    }
+    this.parked.delete(key)
+  }
+
+  /** Resolve a live handle by key, or undefined. */
+  get(key: string): SidebarPty | undefined {
+    return this.sessions.get(key)
+  }
+
+  /** Close a terminal and drop its state (the owning tab was closed). */
+  close(key: string): void {
+    this.cancelClose(key)
+    const handle = this.sessions.get(key)
+    if (handle === undefined) return
+    this.sessions.delete(key)
+    try {
+      handle.pty.kill()
+    } catch {
+      // Already exited or gone; nothing left to kill.
+    }
+  }
+
+  /** Close every terminal (plugin teardown). */
+  disposeAll(): void {
+    for (const timer of this.pendingCloses.values()) clearTimeout(timer)
+    this.pendingCloses.clear()
+    for (const key of [...this.sessions.keys()]) this.close(key)
+  }
+}
+
+/**
+ * Inputs for {@link defaultShell} resolution. Every field is optional and
+ * defaults to the live process, which keeps the no-argument call sites
+ * working while tests (and exotic embedders) can pin the platform, the
+ * environment, and the existence probe independently — the Windows chain
+ * never executes on the ubuntu CI runners, so it is only testable through
+ * these injection points.
+ */
+export interface ShellResolutionOptions {
+  /** Platform override (defaults to `process.platform`). */
+  platform?: NodeJS.Platform
+  /** Environment override; the resolver only reads SHELL, DSH_SIDEBAR_SHELL, PATH, ProgramW6432, ProgramFiles, LOCALAPPDATA. */
+  env?: NodeJS.ProcessEnv
+  /** Explicitly configured shell (the `shell` config field); wins over every automatic source. Empty means unset. */
+  explicit?: string
+  /** File-existence probe override (defaults to `existsSync`). */
+  exists?: (path: string) => boolean
+}
+
+/**
+ * Candidate directories that may contain a `pwsh.exe` on Windows: PATH
+ * entries first, then the well-known machine/user install locations
+ * (including preview channels and per-user MSI/portable layouts). The
+ * machine-scope search reads both `ProgramW6432` and `ProgramFiles` so a
+ * 32-bit Node process — whose `ProgramFiles` points at `(x86)` — still
+ * finds a 64-bit PowerShell 7 install. De-duped while preserving priority
+ * order.
+ */
+function windowsPwshCandidateDirs(env: NodeJS.ProcessEnv): string[] {
+  const dirs: string[] = []
+  const pathEntries = env.PATH
+  if (pathEntries !== undefined) {
+    // The win32 branch always uses the Windows PATH separator; hardcoding it
+    // keeps the function testable from POSIX runners without a delimiter
+    // injection point.
+    for (const entry of pathEntries.split(';')) {
+      const trimmed = entry.trim()
+      if (trimmed !== '') dirs.push(trimmed)
+    }
+  }
+  for (const programFiles of [env.ProgramW6432, env.ProgramFiles]) {
+    if (programFiles === undefined || programFiles.trim() === '') continue
+    dirs.push(join(programFiles, 'PowerShell', '7'))
+    dirs.push(join(programFiles, 'PowerShell', '7-preview'))
+  }
+  const localAppData = env.LOCALAPPDATA
+  if (localAppData !== undefined && localAppData.trim() !== '') {
+    dirs.push(join(localAppData, 'Microsoft', 'PowerShell', '7'))
+    dirs.push(join(localAppData, 'Microsoft', 'PowerShell', '7-preview'))
+    dirs.push(join(localAppData, 'Programs', 'PowerShell', '7'))
+    dirs.push(join(localAppData, 'Programs', 'PowerShell', '7-preview'))
+  }
+  return [...new Set(dirs)]
+}
+
+/**
+ * The interactive shell for this platform, resolved like a terminal
+ * emulator: an explicitly configured shell (the `shell` config field) wins,
+ * then `$SHELL` on POSIX (deployment override), then the account's login
+ * shell from passwd, then `/bin/bash`. The passwd step matters because
+ * service managers and container inits often start dsh without `SHELL`, and
+ * the tab should still open the user's login shell (e.g. zsh) instead of
+ * silently degrading to bash.
+ *
+ * Windows previously short-circuited to `powershell.exe` (the inbox 5.1)
+ * before any resolution, so PowerShell 7 users always got a legacy shell
+ * without `??`/`?.`/ternary and with poor ANSI/UTF-8 defaults. The Windows
+ * chain is now: explicit shell → `DSH_SIDEBAR_SHELL` env override → first
+ * `pwsh.exe` found on PATH or in a known install directory → the 5.1
+ * fallback (machines without PowerShell 7 keep working).
+ */
+export function defaultShell(options: ShellResolutionOptions = {}): string {
+  const platform = options.platform ?? process.platform
+  const env = options.env ?? process.env
+  const exists = options.exists ?? existsSync
+  const explicit = options.explicit
+  if (explicit !== undefined && explicit.trim() !== '') return explicit.trim()
+  if (platform === 'win32') {
+    const envShell = env.DSH_SIDEBAR_SHELL
+    if (envShell !== undefined && envShell.trim() !== '') return envShell.trim()
+    for (const dir of windowsPwshCandidateDirs(env)) {
+      const candidate = join(dir, 'pwsh.exe')
+      if (exists(candidate)) return candidate
+    }
+    return 'powershell.exe'
+  }
+  const envShell = env.SHELL
+  if (envShell !== undefined && envShell.trim() !== '') return envShell.trim()
+  // userInfo() throws when the uid has no passwd entry (rare chroots);
+  // without a login shell there is nothing better than the bash default.
+  try {
+    const loginShell = userInfo().shell
+    if (typeof loginShell === 'string' && loginShell.trim() !== '') return loginShell
+  } catch {
+    // no passwd entry: fall through to /bin/bash
+  }
+  return '/bin/bash'
+}
+
+/**
+ * A short display name for a shell executable, used as the terminal tab
+ * title. `/bin/zsh` → `zsh`, `C:\...\powershell.exe` → `powershell`.
+ * Falls back to the raw value when no basename can be derived.
+ */
+export function shellDisplayName(shell: string): string {
+  const normalized = shell.replace(/\\/g, '/')
+  const base = normalized.slice(normalized.lastIndexOf('/') + 1)
+  if (base === '') return shell
+  return base.replace(/\.(exe|cmd|bat)$/i, '')
+}
+
+/**
+ * Spawn arguments that make the shell behave like a terminal-emulator tab:
+ * POSIX shells start as login shells (`-l`) so they read the profile files
+ * (`~/.profile`, `~/.zprofile`); Windows PowerShell takes no login flag.
+ *
+ * When explicit `configured` args are supplied they REPLACE the platform
+ * defaults entirely, giving deployments full control over shell startup.
+ */
+export function shellSpawnArgs(configured: string[] = []): string[] {
+  if (configured.length > 0) return [...configured]
+  return process.platform === 'win32' ? [] : ['-l']
+}