dsh-better-sidebar 0.10.0

package/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `dsh-better-sidebar`.
+ * @module dsh-better-sidebar/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from './context-types.ts'
+
+const PACKAGE_NAME = 'dsh-better-sidebar'
+
+/** Cordis companion plugin name. */
+export const name = 'dsh-better-sidebar-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the sidebar owns no service state or event protocol
+ * of its own — every route is mounted under the host's webServer fence, the
+ * pty lifecycle is exercised by the smoke spec, and the panel's store is a
+ * plain snapshot registry asserted by the behavior specs. The route fence,
+ * pty quota, and store semantics are each observed through their seams.
+ */
+const install: () => void = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

package/src/jobs-routes.ts

@@ -0,0 +1,257 @@
+/**
+ * Background-job routes of the /sidebar JSON API ('jobs.output' /
+ * 'jobs.kill'). The job LIST needs no route: it arrives through the
+ * harness's `session/jobs` push mirror (`jobsBySession` in the sessions
+ * list feed). The routes:
+ *
+ * - 'jobs.output' — REPLAYS the output the MODEL has read so far for one
+ *   job. The source is the owner session's own event log: `tool/call` rows
+ *   of `job_output` name the job via `arguments.job_id`, and the paired
+ *   `tool/result` rows carry the finalized content the model received.
+ *   Because the session store's in-memory log can lag the live append feed
+ *   after a host restart (the store session stays frozen at its
+ *   rehydration boundary), the plugin ALSO mirrors job_output events from
+ *   the live `session/event` feed and merges both sources (deduped by seq).
+ *   This touches NO DSH source: the model's `job_output` cursor is never
+ *   consumed, and the pane stays empty until the agent reads the job.
+ * - 'jobs.kill' — the registry's stock `kill` (a pristine DSH API),
+ *   fenced by the owning session via the live agent caller. Absent registry
+ *   → 503, mirroring the settings routes' optional-service downgrade.
+ */
+import type { Context, SidebarSessionEvent } from './context-types.ts'
+import { requireString, SidebarError } from './wire.ts'
+
+/** The two background-job routes of the sidebar API. */
+export interface SidebarJobsRoutes {
+  /** The output the model has read so far for one job (event replay, capped). */
+  output(payload: unknown): { text: string; truncated: boolean; read: boolean }
+  /** Request cancellation of one job (live jobs flip to stopping). */
+  kill(payload: unknown): { ok: true; outcome: 'requested' | 'already-finished' }
+}
+
+/** The 'tool/result' message envelope inside a session event's data. */
+interface ToolResultMessageLike {
+  source?: { kind?: unknown; callId?: unknown }
+  content?: unknown
+}
+
+/** One 'tool-result' content block (the inner blocks carry the text). */
+interface ToolResultBlockLike {
+  type?: unknown
+  content?: unknown
+  isError?: unknown
+}
+
+/**
+ * Extract the plain text of a finalized tool result: the text blocks inside
+ * the 'tool-result' block, joined with newlines. Error results and
+ * non-text blocks contribute nothing.
+ */
+function resultText(message: ToolResultMessageLike): string | undefined {
+  if (!Array.isArray(message.content)) return undefined
+  const parts: string[] = []
+  for (const block of message.content) {
+    if (block === null || typeof block !== 'object') continue
+    const candidate = block as ToolResultBlockLike
+    if (candidate.type !== 'tool-result') continue
+    const inner = candidate.content
+    if (!Array.isArray(inner)) continue
+    for (const item of inner) {
+      if (item === null || typeof item !== 'object') continue
+      const textItem = item as { type?: unknown; text?: unknown }
+      if (textItem.type === 'text' && typeof textItem.text === 'string') {
+        parts.push(textItem.text)
+      }
+    }
+  }
+  return parts.length > 0 ? parts.join('\n') : undefined
+}
+
+/** Whether a tool/result is an error result (the inner block's isError flag). */
+function resultIsError(message: ToolResultMessageLike): boolean {
+  if (!Array.isArray(message.content)) return false
+  return message.content.some((block) => {
+    if (block === null || typeof block !== 'object') return false
+    return (block as ToolResultBlockLike).type === 'tool-result'
+      && (block as ToolResultBlockLike).isError === true
+  })
+}
+
+/** Whether a job_output result carries no new output — the controller's
+ *  model-facing "(no new output)" body, noise for the human pane. */
+function isNoNewOutput(text: string): boolean {
+  return text.startsWith('(no new output)')
+}
+
+/** One compact job_output trace (a tool/call or its paired tool/result). */
+interface JobOutputTrace {
+  seq: number
+  kind: 'call' | 'result'
+  /** The tool call identity pairing the two rows. */
+  callId: string
+  /** tool/call: the job id parsed from the model arguments. */
+  jobId?: string
+  /** tool/result: the finalized text the model received. */
+  text?: string
+  /** tool/result: whether the result was an error (read counts, text skipped). */
+  isError?: boolean
+}
+
+/** Extract the job_output trace of one raw session event (undefined = unrelated). */
+function traceOf(event: SidebarSessionEvent): JobOutputTrace | undefined {
+  if (event.type === 'tool/call') {
+    const data = event.data as { name?: unknown; callId?: unknown; arguments?: unknown }
+    if (data.name !== 'job_output' || typeof data.callId !== 'string') return undefined
+    let jobId: string | undefined
+    try {
+      const args = JSON.parse(typeof data.arguments === 'string' ? data.arguments : '') as { job_id?: unknown }
+      if (typeof args.job_id === 'string') jobId = args.job_id
+    } catch {
+      // Malformed model arguments: not a job_output pair.
+    }
+    if (jobId === undefined) return undefined
+    return { seq: event.seq, kind: 'call', callId: data.callId, jobId }
+  }
+  if (event.type === 'tool/result') {
+    const message = (event.data as { message?: unknown }).message as ToolResultMessageLike | undefined
+    if (message === undefined) return undefined
+    const callId = message.source?.callId
+    if (typeof callId !== 'string') return undefined
+    return {
+      seq: event.seq,
+      kind: 'result',
+      callId,
+      text: resultText(message),
+      isError: resultIsError(message),
+    }
+  }
+  return undefined
+}
+
+/** Per-session cap of mirrored live traces (a bounded, lossy ring). */
+const MIRROR_MAX_ENTRIES = 200
+
+/**
+ * The live job_output mirror: subscribes to the session append feed and
+ * caches the job_output traces the session store's own log can lag behind
+ * (after a host restart the store session stays frozen at its rehydration
+ * boundary, so `session.events` misses everything appended since — the very
+ * reads the pane exists to show). Zero DSH writes: the api-proxy pushes the
+ * same feed to browsers.
+ */
+function createJobOutputMirror(ctx: Context): { entries(sessionId: string): readonly JobOutputTrace[] } {
+  const perSession = new Map<string, JobOutputTrace[]>()
+  // tool/call identities per session, so unrelated tool/result rows are
+  // never cached (only job_output results pair with a cached call).
+  const callIds = new Map<string, Set<string>>()
+  if (typeof ctx.on !== 'function') {
+    // Test doubles without the event API degrade to seed-only replay.
+    return { entries: () => [] }
+  }
+  const dispose = ctx.on('session/event', (session, event) => {
+    const sessionId = (session as { id?: unknown } | null)?.id
+    if (typeof sessionId !== 'string') return
+    if (event.type === 'tool/call') {
+      const trace = traceOf(event)
+      if (trace?.kind !== 'call') return
+      let ids = callIds.get(sessionId)
+      if (ids === undefined) callIds.set(sessionId, ids = new Set())
+      ids.add(trace.callId)
+      push(sessionId, trace)
+    } else if (event.type === 'tool/result') {
+      const trace = traceOf(event)
+      if (trace?.kind !== 'result') return
+      if (!callIds.get(sessionId)?.has(trace.callId)) return
+      push(sessionId, trace)
+    }
+  })
+  ctx.effect(() => dispose, 'dsh-better-sidebar: job-output event mirror')
+
+  const push = (sessionId: string, trace: JobOutputTrace): void => {
+    let list = perSession.get(sessionId)
+    if (list === undefined) perSession.set(sessionId, list = [])
+    list.push(trace)
+    if (list.length > MIRROR_MAX_ENTRIES) {
+      const removed = list.splice(0, list.length - MIRROR_MAX_ENTRIES)
+      const ids = callIds.get(sessionId)
+      if (ids !== undefined) {
+        for (const entry of removed) {
+          if (entry.kind === 'call') ids.delete(entry.callId)
+        }
+        if (ids.size === 0) callIds.delete(sessionId)
+      }
+    }
+  }
+
+  return { entries: (sessionId) => perSession.get(sessionId) ?? [] }
+}
+
+/**
+ * Build the jobs routes bound to the plugin context. `output` merges the
+ * owner session's own event log with the live job_output mirror; `kill`
+ * reads the jobs/agents services lazily and degrades to a 503 when the
+ * deployment lacks the registry.
+ * @param ctx - host plugin context.
+ * @param outputLimit - response cap for one output replay in bytes; longer
+ *   texts are sliced and flagged `truncated` (mirrors the fs.read cap).
+ */
+export function buildJobsApi(ctx: Context, outputLimit: number): SidebarJobsRoutes {
+  const jobs = ctx.get('jobs')
+  const agents = ctx.get('agents')
+  const mirror = createJobOutputMirror(ctx)
+  /** The live caller whose session id the registry fence compares against. */
+  const callerOf = (sessionId: string) => agents?.get(sessionId)
+  /** Registry refusals become a 404 job-error; unknown and foreign ids are indistinguishable. */
+  const registryError = (error: unknown): SidebarError =>
+    new SidebarError('job-error', error instanceof Error ? error.message : String(error), 404)
+  return {
+    output(payload) {
+      const sessionId = requireString(payload, 'sessionId')
+      const id = requireString(payload, 'id')
+      // Merge the store's event log (durable seed + whatever it received)
+      // with the live mirror, deduped by seq — a trace never double-counts.
+      const bySeq = new Map<number, JobOutputTrace>()
+      for (const event of ctx.sessions.get(sessionId)?.events ?? []) {
+        const trace = traceOf(event)
+        if (trace !== undefined) bySeq.set(trace.seq, trace)
+      }
+      for (const trace of mirror.entries(sessionId)) bySeq.set(trace.seq, trace)
+      // Pair calls with results in seq order: the model's reads, oldest first.
+      const jobOf = new Map<string, string>()
+      const parts: string[] = []
+      let read = false
+      for (const trace of [...bySeq.values()].sort((left, right) => left.seq - right.seq)) {
+        if (trace.kind === 'call') {
+          if (trace.jobId !== undefined) jobOf.set(trace.callId, trace.jobId)
+        } else if (jobOf.get(trace.callId) === id) {
+          read = true
+          if (trace.isError !== true && trace.text !== undefined && !isNoNewOutput(trace.text)) {
+            parts.push(trace.text)
+          }
+        }
+      }
+      const text = parts.join('\n')
+      return {
+        text: text.length > outputLimit ? text.slice(0, outputLimit) : text,
+        truncated: text.length > outputLimit,
+        read,
+      }
+    },
+    kill(payload) {
+      if (jobs === undefined) {
+        throw new SidebarError('job-error', 'the background-job registry is not mounted in this deployment', 503)
+      }
+      const sessionId = requireString(payload, 'sessionId')
+      const id = requireString(payload, 'id')
+      const record = payload as { reason?: unknown } | null
+      const reason = typeof record?.reason === 'string' && record.reason !== ''
+        ? record.reason
+        : 'user requested via sidebar'
+      try {
+        return { ok: true, outcome: jobs.kill(id, callerOf(sessionId), reason) }
+      } catch (error) {
+        throw registryError(error)
+      }
+    },
+  }
+}

package/src/prefs-shared.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared "Side card" preference vocabulary (types + constants), consumed by
+ * BOTH halves: the host registers the schemastery schema over these values
+ * (config.ts) and the client reads/writes them through the settings RPC
+ * (client/prefs.ts, client/SideCardSection.tsx). Kept free of schemastery so
+ * the browser bundle never pulls the schema runtime in.
+ */
+
+/** The user-settings namespace holding the side card preferences. */
+export const SIDEBAR_PREFS_NS = 'dsh-better-sidebar'
+
+/** User-facing side card preferences (new-conversation defaults). */
+export interface SidebarPrefs {
+  /** Whether a brand-new conversation opens the side card by default. */
+  openByDefault: boolean
+  /** Default panel width as a percent of the window width (20–60). */
+  defaultWidthPercent: number
+  /**
+   * Whether the sidebar auto-activates (opens the panel) and expands the
+   * Subagent page when the current conversation spawns a new subagent.
+   */
+  autoOpenSubagent: boolean
+  /**
+   * Whether the sidebar auto-activates (opens the panel) and expands the
+   * Jobs page when a NEW background job appears for the current
+   * conversation (any new job id, not just the first one).
+   */
+  autoOpenJobs: boolean
+  /**
+   * Whether the model-facing agent terminal tools (terminal_create / list /
+   * send / read / wait_for / resize / signal / close) are injected into the
+   * model's toolset. Off by default: the feature stays dormant until the
+   * user explicitly enables it in the side card settings.
+   */
+  agentTerminalTools: boolean
+  /**
+   * Whether expanding the bottom panel for the FIRST time in a session tries
+   * to open a fresh terminal tab there (the terminal quota/type still gates
+   * the attempt). On by default; the switch lives under the terminal tab's
+   * row in the Side card settings.
+   */
+  bottomPanelAutoTerminal: boolean
+  /**
+   * Whether chat-side file opens (tool-row path links, the produced-files
+   * row, prose file mentions — every path that funnels through the client
+   * runtime's `ctx.workspaces.openPath`) open in the sidebar editor instead
+   * of the Host OS's default application. On by default; the editor tab's
+   * own enable switch gates it too (both must be on for the takeover).
+   */
+  interceptOpenPath: boolean
+  /**
+   * Whether the HTML previewer drops its sandboxed iframe. Sandbox ON (the
+   * default) renders previewed HTML in an opaque-origin iframe that cannot
+   * touch the GUI; turning it OFF runs the previewed page with the GUI's
+   * own origin — full read/write access to session files and internal
+   * APIs. Only for trusted local content; the setting copy warns.
+   */
+  htmlViewerNoSandbox: boolean
+  /**
+   * Whether a newly opened HTML preview starts UNSANDBOXED (the per-surface
+   * temporary unlock pre-applied). Off by default: previews open sandboxed
+   * and the status row offers the one-tap unlock; when on, previews open
+   * in the red unsandboxed state and the status row offers a one-tap
+   * restore for the current file.
+   */
+  htmlViewerDefaultUnsafe: boolean
+  /**
+   * Whether the browser tab drops its sandboxed iframe. Sandbox ON (the
+   * default) keeps browsed sites in an opaque origin with no GUI access;
+   * turning it OFF runs any visited site with the GUI's own origin — it
+   * can read session data and act as the logged-in GUI. Only for trusted
+   * sites; the setting copy warns.
+   */
+  browserNoSandbox: boolean
+  /**
+   * Whether clicking an http(s) EXTERNAL link in the GUI (chat messages,
+   * tool rows, prose mentions) opens the sidebar browser instead of a new
+   * browser tab. On by default; gated on the browser tab's own enable
+   * switch (both must be on for the takeover). Ctrl/Cmd+click always
+   * bypasses the takeover.
+   */
+  browserInterceptLinks: boolean
+  /**
+   * Per-tab enable switches, keyed by tab descriptor id (`'explorer'`,
+   * `'my-plugin:db'`). An ABSENT key means enabled — only an explicit
+   * `false` disables a tab type (hidden from the + menu, `openTab` refuses,
+   * and derived flows like subagent auto-open / agent-terminal tabs stop).
+   * Already-open tabs of a disabled type keep rendering (closing one
+   * prevents reopening), matching the "existing conversations keep their
+   * own layouts" rule.
+   */
+  tabsEnabled: Record<string, boolean>
+  /**
+   * Per-viewer enable switches, keyed by file viewer descriptor id
+   * (`'image'`, `'my-plugin:csv'`). An ABSENT key means enabled; a disabled
+   * viewer is skipped by `matchFileViewer` so files fall through to the
+   * next matching viewer (or the download button when none match).
+   */
+  viewersEnabled: Record<string, boolean>
+}
+
+/** Range contract of {@link SidebarPrefs.defaultWidthPercent}. */
+export const WIDTH_PERCENT_MIN = 20
+export const WIDTH_PERCENT_MAX = 60
+export const WIDTH_PERCENT_DEFAULT = 30
+
+/** Fallback prefs used whenever the settings document is unreachable or malformed. */
+export const SIDEBAR_PREFS_DEFAULTS: SidebarPrefs = {
+  openByDefault: true,
+  defaultWidthPercent: WIDTH_PERCENT_DEFAULT,
+  autoOpenSubagent: true,
+  autoOpenJobs: true,
+  agentTerminalTools: false,
+  bottomPanelAutoTerminal: true,
+  interceptOpenPath: true,
+  htmlViewerNoSandbox: false,
+  htmlViewerDefaultUnsafe: false,
+  browserNoSandbox: false,
+  browserInterceptLinks: true,
+  tabsEnabled: {},
+  viewersEnabled: {},
+}
+
+/** Clamp one width percent into the contract range (shared by schema and client reads). */
+export function clampWidthPercent(value: number): number {
+  return Math.min(WIDTH_PERCENT_MAX, Math.max(WIDTH_PERCENT_MIN, Math.round(value)))
+}

package/src/pty-manager.ts

@@ -0,0 +1,199 @@
+/**
+ * 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 * as nodePty from 'node-pty'
+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: nodePty.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).
+ */
+export class PtyManager {
+  private readonly sessions = new Map<string, SidebarPty>()
+  private readonly pendingCloses = new Map<string, ReturnType<typeof setTimeout>>()
+
+  constructor(
+    private readonly shell: string,
+    private readonly maxPerSession: number,
+  ) {}
+
+  /** 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): 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: nodePty.spawn(this.shell, [], {
+        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.
+   */
+  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)
+  }
+
+  /** Cancel a pending scheduled close (the terminal is being reopened). */
+  cancelClose(key: string): void {
+    const timer = this.pendingCloses.get(key)
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      this.pendingCloses.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)
+  }
+}
+
+/** The interactive shell for this platform (empty SHELL falls back). */
+export function defaultShell(): string {
+  if (process.platform === 'win32') return 'powershell.exe'
+  const shell = process.env.SHELL
+  return shell !== undefined && shell.trim() !== '' ? shell : '/bin/bash'
+}