feat: add persistent PTY sessions

2026-07-21 16:01:00 +08:00
parent b4750f6333
commit 58cde5103a
71 changed files with 5677 additions and 82 deletions
--- a/packages/pty/pty-local/src/config.ts
+++ b/packages/pty/pty-local/src/config.ts
@@ -0,0 +1,72 @@
+/** Validated configuration for the local PTY backend. */
+
+import z from 'schemastery'
+
+/** Public plugin configuration. */
+export interface Config {
+  /** Backend registry type (default: `shell`). */
+  backendType?: string
+  /** Interactive shell executable (default: `/bin/bash`). */
+  shellPath?: string
+  /** Shell arguments (default: `--noprofile --norc -i`). */
+  shellArgs?: string[]
+  /** Terminal rows. */
+  rows?: number
+  /** Terminal columns. */
+  cols?: number
+  /** Maximum retained logical lines. */
+  scrollbackLines?: number
+  /** Maximum retained UTF-8 bytes. */
+  scrollbackMaxBytes?: number
+  /** Maximum bytes returned by one read or settled viewport. */
+  maxReadBytes?: number
+  /** Readiness polling interval. */
+  pollIntervalMs?: number
+  /** Delay before Linux exact syscall probes. */
+  exactProbeAfterMs?: number
+  /** Silence duration that yields `inferred_idle`. */
+  idleSilenceMs?: number
+  /** Absolute send wait bound. */
+  timeoutMs?: number
+  /** Grace before teardown escalates to `SIGKILL`. */
+  disposeGraceMs?: number
+}
+
+/** Configuration after Schemastery defaults. */
+export type ResolvedConfig = Required<Config>
+
+/** Schemastery config exposed by the plugin. */
+export const Config: z<Config> = z.object({
+  backendType: z.string().default('shell'),
+  shellPath: z.string().default('/bin/bash'),
+  shellArgs: z.array(z.string()).default(['--noprofile', '--norc', '-i']),
+  rows: z.number().default(40),
+  cols: z.number().default(160),
+  scrollbackLines: z.number().default(10_000),
+  scrollbackMaxBytes: z.number().default(4 * 1024 * 1024),
+  maxReadBytes: z.number().default(256 * 1024),
+  pollIntervalMs: z.number().default(50),
+  exactProbeAfterMs: z.number().default(150),
+  idleSilenceMs: z.number().default(3_000),
+  timeoutMs: z.number().default(30_000),
+  disposeGraceMs: z.number().default(3_000),
+})
+
+/**
+ * Assert every numeric config field is a positive safe integer and bounds compose.
+ * @param config - Schemastery-resolved plugin configuration.
+ * @returns Narrows the input to the fully resolved configuration.
+ */
+export function validateConfig(config: Config): asserts config is ResolvedConfig {
+  const resolved = config as ResolvedConfig
+  if (resolved.backendType.length === 0) throw new Error('pty-local: backendType must be non-empty')
+  if (resolved.shellPath.length === 0) throw new Error('pty-local: shellPath must be non-empty')
+  for (const [name, value] of Object.entries(resolved)) {
+    if (typeof value === 'number' && (!Number.isSafeInteger(value) || value <= 0)) {
+      throw new Error(`pty-local: ${name} must be a positive safe integer`)
+    }
+  }
+  if (resolved.maxReadBytes > resolved.scrollbackMaxBytes) {
+    throw new Error('pty-local: maxReadBytes must not exceed scrollbackMaxBytes')
+  }
+}
--- a/packages/pty/pty-local/src/ensure-spawn-helper.mjs
+++ b/packages/pty/pty-local/src/ensure-spawn-helper.mjs
@@ -0,0 +1,16 @@
+/** Restore the executable bit stripped from node-pty's prebuilt helper. */
+
+import { chmodSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const entry = fileURLToPath(import.meta.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)
+}
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -0,0 +1,108 @@
+/**
+ * Local persistent PTY backend using public `node-pty` APIs, shared sandbox
+ * policy, bounded output, platform readiness probes, and process-session cleanup.
+ * @module @deepseek-ai/dsh-pty-local
+ */
+
+import { Context } from 'cordis'
+import * as nodePty from 'node-pty'
+import type { IPtyForkOptions } from 'node-pty'
+import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
+import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
+import { createProcessInspector } from './process-inspector.ts'
+import type { ProcessInspector } from './process-inspector.ts'
+import { LocalPtySession } from './session.ts'
+
+export { Config } from './config.ts'
+export type { Config as PtyLocalConfig } from './config.ts'
+
+/** Cordis plugin name. */
+export const name = 'pty-local'
+/** Required services: registry plus the one shared confinement policy. */
+export const inject = ['pty', 'sandbox', 'sandboxPolicy']
+
+const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
+
+function childEnvironment(spec: PtyBackendSpawnSpec): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined && !SENSITIVE_ENV_PATTERN.test(key) && !key.startsWith('DSH_')) env[key] = value
+  }
+  return {
+    ...env,
+    TERM: 'dumb',
+    PAGER: 'cat',
+    GIT_PAGER: 'cat',
+    PS1: 'dsh> ',
+    PROMPT_COMMAND: 'printf "\\033]133;D;%s\\007" "$?"',
+    BASH_SILENCE_DEPRECATION_WARNING: '1',
+    DSH_SHELL: '1',
+    DSH_SESSION_ID: spec.owner.id,
+    DSH_PTY_SESSION_ID: spec.sessionId,
+  }
+}
+
+function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSpec): string[] {
+  const argv = [config.shellPath, ...config.shellArgs]
+  const mode: SandboxMode = effectiveSandboxMode(spec.owner.session.events) ?? ctx.sandboxPolicy.defaultMode
+  if (mode === 'danger-full-access') return argv
+  return ctx.sandbox.confine(argv, {
+    mode: mode,
+    workspaceRoot: ctx.sandboxPolicy.workspaceRoot,
+  }).argv
+}
+
+/** Local shell backend registered under the configured type. */
+export class LocalPtyBackend implements PtyBackend {
+  readonly type: string
+
+  constructor(
+    private readonly ctx: Context,
+    private readonly config: ResolvedConfig,
+    private readonly inspector: ProcessInspector,
+    private readonly spawnTerminal: typeof nodePty.spawn = nodePty.spawn,
+    private readonly createSession: (
+      terminal: ReturnType<typeof nodePty.spawn>,
+      inspector: ProcessInspector,
+      config: ResolvedConfig,
+    ) => LocalPtySession = (terminal, inspector, config) => new LocalPtySession(terminal, inspector, config),
+  ) {
+    this.type = config.backendType
+  }
+
+  async spawn(spec: PtyBackendSpawnSpec): Promise<LocalPtySession> {
+    if (spec.signal?.aborted === true) throw new Error('PTY spawn aborted')
+    const argv = spawnArgv(this.ctx, this.config, spec)
+    const file = argv[0]
+    if (file === undefined) throw new Error('pty-local: sandbox returned empty argv')
+    const options: IPtyForkOptions = {
+      name: 'dumb',
+      cols: this.config.cols,
+      rows: this.config.rows,
+      cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
+      env: childEnvironment(spec),
+    }
+    const terminal = this.spawnTerminal(file, argv.slice(1), options)
+    const session = this.createSession(terminal, this.inspector, this.config)
+    try {
+      await session.initialize(spec.signal)
+      return session
+    } catch (error) {
+      try {
+        await session.close('PTY startup failed')
+      } catch (closeError: unknown) {
+        throw new AggregateError([error, closeError], 'PTY startup and cleanup both failed')
+      }
+      throw error
+    }
+  }
+}
+
+/** Register the local PTY backend. */
+export function apply(ctx: Context, config: Config): void {
+  validateConfig(config)
+  const inspector = createProcessInspector()
+  ctx.pty.registerBackend(new LocalPtyBackend(ctx, config, inspector))
+}
--- a/packages/pty/pty-local/src/process-inspector.ts
+++ b/packages/pty/pty-local/src/process-inspector.ts
@@ -0,0 +1,326 @@
+/** Platform process-table inspection used for readiness, signals, and teardown. */
+
+import { closeSync, openSync, readFileSync, readdirSync, readSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import type { PtySignal } from '@deepseek-ai/dsh-pty'
+
+/** PID plus start identity, preventing teardown escalation after PID reuse. */
+export interface ProcessIdentity {
+  pid: number
+  started: string
+}
+
+/** Injectable OS process operations used by one local PTY session. */
+export interface ProcessInspector {
+  foregroundPgid(shellPid: number): number | undefined
+  isStdinWaiting(pgid: number): boolean
+  /** Return the root and its current transitive descendants, children first. */
+  processTree(rootPid: number): ProcessIdentity[]
+  isAlive(identity: ProcessIdentity): boolean
+  signalGroup(pgid: number, signal: PtySignal): void
+  signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void
+}
+
+/** Testable boundary around filesystem, process-table, and signal syscalls. */
+export interface ProcessInspectorInternals {
+  readFile(path: string): string
+  readDir(path: string): string[]
+  open(path: string): number
+  read(fd: number, buffer: Buffer, length: number, position: number): number
+  close(fd: number): void
+  exec(file: string, args: string[]): string
+  kill(pid: number, signal: NodeJS.Signals): void
+}
+
+/* v8 ignore start -- thin OS bindings; injected logic is unit-tested and real platform composition exercises them. */
+const DEFAULT_INTERNALS: ProcessInspectorInternals = {
+  readFile: path => readFileSync(path, 'utf8'),
+  readDir: path => readdirSync(path),
+  open: path => openSync(path, 'r'),
+  read: (fd, buffer, length, position) => readSync(fd, buffer, 0, length, position),
+  close: closeSync,
+  exec: (file, args) => execFileSync(file, args, { encoding: 'utf8' }),
+  kill: (pid, signal) => process.kill(pid, signal),
+}
+/* v8 ignore stop */
+
+interface ProcStat {
+  pid: number
+  parentPid: number
+  pgrp: number
+  session: number
+  tpgid: number
+  started: string
+}
+
+/**
+ * Parse fields used from Linux `/proc/<pid>/stat`, including parenthesized comm text.
+ * @param text - complete stat line.
+ * @returns Parsed identity/group fields, or undefined for malformed input.
+ */
+export function parseProcStat(text: string): ProcStat | undefined {
+  const open = text.indexOf('(')
+  const close = text.lastIndexOf(')')
+  if (open <= 0 || close <= open) return undefined
+  const pid = Number(text.slice(0, open).trim())
+  const rest = text.slice(close + 2).trim().split(/\s+/)
+  const parentPid = Number(rest[1])
+  const pgrp = Number(rest[2])
+  const session = Number(rest[3])
+  const tpgid = Number(rest[5])
+  const started = rest[19]
+  if (![pid, parentPid, pgrp, session, tpgid].every(Number.isSafeInteger) || started === undefined) return undefined
+  return { pid, parentPid, pgrp, session, tpgid, started }
+}
+
+function readLinuxStat(internals: ProcessInspectorInternals, pid: number): ProcStat | undefined {
+  try {
+    return parseProcStat(internals.readFile(`/proc/${pid}/stat`))
+  } catch (_unreadableProcEntry) {
+    return undefined
+  }
+}
+
+function numericEntries(internals: ProcessInspectorInternals, path: string): number[] {
+  try {
+    return internals.readDir(path).filter(entry => /^\d+$/.test(entry)).map(Number)
+  } catch (_unreadableProcDirectory) {
+    return []
+  }
+}
+
+interface SyscallInfo {
+  number: number
+  args: number[]
+}
+
+function readSyscall(internals: ProcessInspectorInternals, pid: number, tid: number): SyscallInfo | undefined {
+  try {
+    const text = internals.readFile(`/proc/${pid}/task/${tid}/syscall`).trim()
+    if (text === 'running' || text.startsWith('-1 ')) return undefined
+    const fields = text.split(/\s+/)
+    const number = Number(fields[0])
+    const args = fields.slice(1, 7).map(field => Number.parseInt(field, 16))
+    if (!Number.isSafeInteger(number) || args.some(value => !Number.isSafeInteger(value))) return undefined
+    return { number, args }
+  } catch (_unreadableSyscall) {
+    return undefined
+  }
+}
+
+function readMemory(
+  internals: ProcessInspectorInternals,
+  pid: number,
+  address: number,
+  length: number,
+): Buffer | undefined {
+  let fd: number | undefined
+  try {
+    fd = internals.open(`/proc/${pid}/mem`)
+    const buffer = Buffer.alloc(length)
+    const count = internals.read(fd, buffer, length, address)
+    return buffer.subarray(0, count)
+  } catch (_unreadableProcessMemory) {
+    return undefined
+  } finally {
+    if (fd !== undefined) internals.close(fd)
+  }
+}
+
+function fdSetHasStdin(internals: ProcessInspectorInternals, pid: number, address: number): boolean {
+  return address !== 0 && (readMemory(internals, pid, address, 8)?.[0] ?? 0) % 2 === 1
+}
+
+function pollHasStdin(
+  internals: ProcessInspectorInternals,
+  pid: number,
+  address: number,
+  count: number,
+): boolean {
+  if (address === 0 || count <= 0) return false
+  const memory = readMemory(internals, pid, address, Math.min(count, 1024) * 8)
+  if (memory === undefined) return false
+  for (let offset = 0; offset + 8 <= memory.length; offset += 8) {
+    if (memory.readInt32LE(offset) === 0 && (memory.readInt16LE(offset + 4) & 0x001) !== 0) return true
+  }
+  return false
+}
+
+function epollHasStdin(internals: ProcessInspectorInternals, pid: number, epfd: number): boolean {
+  try {
+    return internals.readFile(`/proc/${pid}/fdinfo/${epfd}`)
+      .split('\n')
+      .some(line => /^tfd:\s+0\b/.test(line.trim()))
+  } catch (_unreadableFdInfo) {
+    return false
+  }
+}
+
+interface SyscallTable {
+  read: number
+  select?: number
+  pselect: number
+  poll?: number
+  ppoll: number
+  epollWait?: number
+  epollPwait: number
+}
+
+const SYSCALLS: Partial<Record<NodeJS.Architecture, SyscallTable>> = {
+  x64: { read: 0, select: 23, pselect: 270, poll: 7, ppoll: 271, epollWait: 232, epollPwait: 281 },
+  arm64: { read: 63, pselect: 72, ppoll: 73, epollPwait: 22 },
+}
+
+function syscallWaitsOnStdin(
+  internals: ProcessInspectorInternals,
+  pid: number,
+  syscall: SyscallInfo,
+  table: SyscallTable,
+): boolean {
+  const [a0 = 0, a1 = 0, a2 = 0] = syscall.args
+  if (syscall.number === table.read) return a0 === 0
+  if (syscall.number === table.select || syscall.number === table.pselect) {
+    return a0 >= 1 && fdSetHasStdin(internals, pid, a1)
+  }
+  if (syscall.number === table.poll || syscall.number === table.ppoll) {
+    return a1 >= 1 && pollHasStdin(internals, pid, a0, a1)
+  }
+  if (syscall.number === table.epollWait || syscall.number === table.epollPwait) {
+    return a2 >= 1 && epollHasStdin(internals, pid, a0)
+  }
+  return false
+}
+
+abstract class PosixProcessInspector implements ProcessInspector {
+  constructor(protected readonly internals: ProcessInspectorInternals) {}
+
+  abstract foregroundPgid(shellPid: number): number | undefined
+  abstract isStdinWaiting(pgid: number): boolean
+  abstract processTree(rootPid: number): ProcessIdentity[]
+  abstract isAlive(identity: ProcessIdentity): boolean
+
+  signalGroup(pgid: number, signal: PtySignal): void {
+    this.internals.kill(-pgid, signal)
+  }
+
+  signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void {
+    if (this.isAlive(identity)) this.internals.kill(identity.pid, signal)
+  }
+}
+
+interface ProcessTreeEntry extends ProcessIdentity {
+  parentPid: number
+}
+
+function processTree(entries: ProcessTreeEntry[], rootPid: number): ProcessIdentity[] {
+  const byPid = new Map(entries.map(entry => [entry.pid, entry]))
+  const root = byPid.get(rootPid)
+  if (root === undefined) return []
+  const byParent = new Map<number, ProcessTreeEntry[]>()
+  for (const entry of entries) {
+    const children = byParent.get(entry.parentPid) ?? []
+    children.push(entry)
+    byParent.set(entry.parentPid, children)
+  }
+  const visited = new Set<number>()
+  const result: ProcessIdentity[] = []
+  const visit = (entry: ProcessTreeEntry): void => {
+    if (visited.has(entry.pid)) return
+    visited.add(entry.pid)
+    for (const child of byParent.get(entry.pid) ?? []) visit(child)
+    result.push({ pid: entry.pid, started: entry.started })
+  }
+  visit(root)
+  return result
+}
+
+class LinuxProcessInspector extends PosixProcessInspector {
+  constructor(
+    private readonly arch: NodeJS.Architecture,
+    internals: ProcessInspectorInternals,
+  ) {
+    super(internals)
+  }
+
+  foregroundPgid(shellPid: number): number | undefined {
+    const tpgid = readLinuxStat(this.internals, shellPid)?.tpgid
+    return tpgid !== undefined && tpgid > 0 ? tpgid : undefined
+  }
+
+  isStdinWaiting(pgid: number): boolean {
+    const table = SYSCALLS[this.arch]
+    if (table === undefined) return false
+    for (const pid of numericEntries(this.internals, '/proc')) {
+      if (readLinuxStat(this.internals, pid)?.pgrp !== pgid) continue
+      for (const tid of numericEntries(this.internals, `/proc/${pid}/task`)) {
+        const syscall = readSyscall(this.internals, pid, tid)
+        if (syscall !== undefined && syscallWaitsOnStdin(this.internals, pid, syscall, table)) return true
+      }
+    }
+    return false
+  }
+
+  processTree(rootPid: number): ProcessIdentity[] {
+    const entries = numericEntries(this.internals, '/proc').flatMap((pid) => {
+      const stat = readLinuxStat(this.internals, pid)
+      return stat === undefined ? [] : [{ pid, parentPid: stat.parentPid, started: stat.started }]
+    })
+    return processTree(entries, rootPid)
+  }
+
+  isAlive(identity: ProcessIdentity): boolean {
+    return readLinuxStat(this.internals, identity.pid)?.started === identity.started
+  }
+
+}
+
+interface PsEntry extends ProcessTreeEntry {}
+
+function macProcessTable(internals: ProcessInspectorInternals): PsEntry[] {
+  return internals.exec('/bin/ps', ['-axo', 'pid=,ppid=,lstart=']).split('\n').flatMap((line) => {
+    const match = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/.exec(line)
+    if (match?.[1] === undefined || match[2] === undefined || match[3] === undefined) return []
+    return [{ pid: Number(match[1]), parentPid: Number(match[2]), started: match[3] }]
+  })
+}
+
+class MacProcessInspector extends PosixProcessInspector {
+  foregroundPgid(shellPid: number): number | undefined {
+    try {
+      const value = Number(this.internals.exec('/bin/ps', ['-o', 'tpgid=', '-p', String(shellPid)]).trim())
+      return Number.isSafeInteger(value) && value > 0 ? value : undefined
+    } catch (_missingProcess) {
+      return undefined
+    }
+  }
+
+  isStdinWaiting(_pgid: number): boolean {
+    return false
+  }
+
+  processTree(rootPid: number): ProcessIdentity[] {
+    return processTree(macProcessTable(this.internals), rootPid)
+  }
+
+  isAlive(identity: ProcessIdentity): boolean {
+    return macProcessTable(this.internals).some(entry => entry.pid === identity.pid && entry.started === identity.started)
+  }
+
+}
+
+/**
+ * Create the supported platform inspector or fail at plugin load.
+ * @param platform - target Node platform.
+ * @param arch - target CPU architecture for Linux syscall numbers.
+ * @param internals - filesystem/process boundary, injectable for deterministic tests.
+ * @returns Platform process inspector.
+ */
+export function createProcessInspector(
+  platform: NodeJS.Platform = process.platform,
+  arch: NodeJS.Architecture = process.arch,
+  internals: ProcessInspectorInternals = DEFAULT_INTERNALS,
+): ProcessInspector {
+  if (platform === 'linux') return new LinuxProcessInspector(arch, internals)
+  if (platform === 'darwin') return new MacProcessInspector(internals)
+  throw new Error(`pty-local: unsupported platform ${platform}`)
+}
--- a/packages/pty/pty-local/src/sanitize.ts
+++ b/packages/pty/pty-local/src/sanitize.ts
@@ -0,0 +1,99 @@
+/** Streaming terminal-control sanitizer for the line-oriented first release. */
+
+/** OSC marker emitted by the controlled bash before each prompt. */
+export const PROMPT_MARKER_PREFIX = '133;D;'
+
+/** One sanitized chunk plus whether it contained the owned prompt marker. */
+export interface SanitizedChunk {
+  text: string
+  prompt: boolean
+}
+
+/**
+ * Remove CSI/OSC/short escape sequences while preserving split-sequence carry.
+ * Full terminal emulation is deliberately deferred; ordinary line output and
+ * the private prompt marker are the supported contract.
+ */
+export class TerminalSanitizer {
+  private pending = ''
+
+  /**
+   * Consume one decoded `node-pty` data chunk.
+   * @param chunk - decoded terminal data.
+   * @returns Printable text and whether the private prompt marker completed.
+   */
+  push(chunk: string): SanitizedChunk {
+    this.pending += chunk
+    let text = ''
+    let prompt = false
+    let index = 0
+    while (index < this.pending.length) {
+      const escape = this.pending.indexOf('\x1b', index)
+      if (escape < 0) {
+        text += this.pending.slice(index)
+        index = this.pending.length
+        break
+      }
+      text += this.pending.slice(index, escape)
+      if (escape + 1 >= this.pending.length) {
+        index = escape
+        break
+      }
+      const kind = this.pending[escape + 1]
+      if (kind === ']') {
+        const bel = this.pending.indexOf('\x07', escape + 2)
+        const stringTerminator = this.pending.indexOf('\x1b\\', escape + 2)
+        let end = -1
+        if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2)
+        else if (bel >= 0) end = bel + 1
+        else if (stringTerminator >= 0) end = stringTerminator + 2
+        if (end < 0) {
+          index = escape
+          break
+        }
+        const terminatorBytes = this.pending[end - 1] === '\x07' ? 1 : 2
+        const content = this.pending.slice(escape + 2, end - terminatorBytes)
+        if (content.startsWith(PROMPT_MARKER_PREFIX)) prompt = true
+        index = end
+        continue
+      }
+      if (kind === '[') {
+        let end = escape + 2
+        while (end < this.pending.length) {
+          const code = this.pending.charCodeAt(end)
+          if (code >= 0x40 && code <= 0x7e) break
+          end += 1
+        }
+        if (end >= this.pending.length) {
+          index = escape
+          break
+        }
+        index = end + 1
+        continue
+      }
+      // Two-byte escape family (save/restore cursor and similar).
+      index = escape + 2
+    }
+    this.pending = this.pending.slice(index)
+    return { text: normalizeTerminalText(text), prompt }
+  }
+
+  /**
+   * Flush a trailing printable fragment when the PTY exits.
+   * @returns Remaining printable text; incomplete escapes are discarded.
+   */
+  flush(): string {
+    const text = this.pending.startsWith('\x1b') ? '' : this.pending
+    this.pending = ''
+    return normalizeTerminalText(text)
+  }
+}
+
+/**
+ * Normalize CRLF and standalone carriage returns for line-oriented rendering.
+ * @param text - sanitized terminal text.
+ * @returns Line-normalized text with BEL removed.
+ */
+export function normalizeTerminalText(text: string): string {
+  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n').replaceAll('\x07', '')
+}
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -0,0 +1,372 @@
+/** Local `node-pty` session: bounded output, readiness, signals, and teardown. */
+
+import { constants } from 'node:os'
+import { Buffer } from 'node:buffer'
+import type { IDisposable, IPty } from 'node-pty'
+import type {
+  PtyBackendSession,
+  PtyReadRequest,
+  PtyReadResult,
+  PtySendOperation,
+  PtySendRead,
+  PtySendRequest,
+  PtySendResult,
+  PtySessionStatus,
+  PtySignal,
+  PtySignalResult,
+  PtyWaitReason,
+} from '@deepseek-ai/dsh-pty'
+import type { ResolvedConfig } from './config.ts'
+import type { ProcessInspector } from './process-inspector.ts'
+import { TerminalSanitizer } from './sanitize.ts'
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function utf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
+  if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
+  const chars = Array.from(text)
+  let bytes = 0
+  let start = chars.length
+  while (start > 0) {
+    const next = Buffer.byteLength(chars[start - 1] as string)
+    if (bytes + next > maxBytes) break
+    bytes += next
+    start -= 1
+  }
+  return { text: chars.slice(start).join(''), truncated: true }
+}
+
+class BoundedTextBuffer {
+  private value = ''
+  private dropped = false
+
+  constructor(
+    private readonly maxBytes: number,
+    private readonly maxLines?: number,
+  ) {}
+
+  append(text: string): void {
+    if (text.length === 0) return
+    this.value += text
+    if (this.maxLines !== undefined) {
+      const lines = this.value.split('\n')
+      if (lines.length > this.maxLines) {
+        this.value = lines.slice(lines.length - this.maxLines).join('\n')
+        this.dropped = true
+      }
+    }
+    const tail = utf8Tail(this.value, this.maxBytes)
+    this.value = tail.text
+    this.dropped ||= tail.truncated
+  }
+
+  consume(): PtySendRead {
+    const delta = this.value
+    const truncated = this.dropped
+    this.value = ''
+    this.dropped = false
+    return { delta, truncated }
+  }
+
+  snapshot(): { text: string; truncated: boolean } {
+    return { text: this.value, truncated: this.dropped }
+  }
+}
+
+class LocalSendOperation implements PtySendOperation {
+  private readonly output: BoundedTextBuffer
+  private readonly promise: PromiseWithResolvers<PtySendResult>
+  private finished = false
+
+  constructor(
+    maxBytes: number,
+    readonly startedAt: number,
+    private readonly onCancel: () => void,
+  ) {
+    this.output = new BoundedTextBuffer(maxBytes)
+    this.promise = Promise.withResolvers<PtySendResult>()
+  }
+
+  get done(): Promise<PtySendResult> {
+    return this.promise.promise
+  }
+
+  append(text: string): void {
+    if (!this.finished) this.output.append(text)
+  }
+
+  settle(waitReason: PtyWaitReason, sessionStatus: PtySessionStatus, inheritedTruncation: boolean): void {
+    if (this.finished) return
+    this.finished = true
+    const read = this.output.snapshot()
+    this.promise.resolve({
+      viewport: read.text,
+      waitReason,
+      sessionStatus,
+      truncated: read.truncated || inheritedTruncation,
+    })
+  }
+
+  fail(error: unknown): void {
+    if (this.finished) return
+    this.finished = true
+    this.promise.reject(error)
+  }
+
+  readOutput(): PtySendRead {
+    return this.output.consume()
+  }
+
+  cancel(): boolean {
+    if (this.finished) return false
+    this.onCancel()
+    return true
+  }
+}
+
+function signalName(number: number | undefined): NodeJS.Signals | null {
+  if (number === undefined || number === 0) return null
+  for (const [name, value] of Object.entries(constants.signals)) {
+    if (value === number) return name as NodeJS.Signals
+  }
+  return null
+}
+
+/** Backend session wrapping one `node-pty` process and its captured process tree. */
+export class LocalPtySession implements PtyBackendSession {
+  motd = ''
+  readonly pid: number
+  private readonly sanitizer = new TerminalSanitizer()
+  private readonly scrollback: BoundedTextBuffer
+  private readonly exitPromise: PromiseWithResolvers<void> = Promise.withResolvers<void>()
+  private readonly dataDisposable: IDisposable
+  private readonly exitDisposable: IDisposable
+  private statusValue: PtySessionStatus = { kind: 'running' }
+  private active: LocalSendOperation | undefined
+  private activeTimer: NodeJS.Timeout | undefined
+  private activeAbort: (() => void) | undefined
+  private promptSeen = false
+  private lastOutputAt = Date.now()
+  private closePromise: Promise<void> | undefined
+
+  constructor(
+    private readonly terminal: IPty,
+    private readonly inspector: ProcessInspector,
+    private readonly config: ResolvedConfig,
+  ) {
+    this.pid = terminal.pid
+    this.scrollback = new BoundedTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
+    this.dataDisposable = terminal.onData((data) => { this.onData(data) })
+    this.exitDisposable = terminal.onExit(({ exitCode, signal }) => {
+      const tail = this.sanitizer.flush()
+      this.appendOutput(tail)
+      this.statusValue = { kind: 'exited', exitCode, signal: signalName(signal) }
+      this.settleActive('session_exit')
+      this.exitPromise.resolve()
+    })
+  }
+
+  /**
+   * Capture startup output through the same readiness contract as later sends.
+   * @param signal - optional cancellation while the shell reaches its first prompt.
+   * @returns Resolves after startup readiness; rejects if the shell exits.
+   */
+  async initialize(signal?: AbortSignal): Promise<void> {
+    const operation = this.startSend({ text: '', submit: false, ...signal !== undefined ? { signal } : {} })
+    const result = await operation.done
+    if (result.waitReason === 'session_exit') throw new Error('PTY shell exited during startup')
+    this.motd = result.viewport
+  }
+
+  startSend(request: PtySendRequest): PtySendOperation {
+    if (this.closePromise !== undefined) throw new Error('PTY session is closing')
+    if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
+    if (this.active !== undefined) throw new Error('PTY session already has an active send')
+    if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
+
+    const operation = new LocalSendOperation(this.config.maxReadBytes, Date.now(), () => {
+      try {
+        this.terminal.write('\x03')
+      } catch (error: unknown) {
+        operation.fail(error)
+      }
+    })
+    this.active = operation
+    this.lastOutputAt = Date.now()
+    this.promptSeen = false
+
+    if (request.signal !== undefined) {
+      const onAbort = (): void => { operation.cancel() }
+      request.signal.addEventListener('abort', onAbort, { once: true })
+      this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
+    }
+
+    try {
+      if (request.text.length > 0) this.terminal.write(request.text)
+      if (request.submit) this.terminal.write('\r')
+    } catch (error: unknown) {
+      this.clearActive()
+      operation.fail(error)
+      return operation
+    }
+
+    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
+    return operation
+  }
+
+  read(request: PtyReadRequest): PtyReadResult {
+    const snapshot = this.scrollback.snapshot()
+    const lines = snapshot.text.split('\n')
+    const totalLines = snapshot.text.length === 0 ? 0 : lines.length
+    const offset = request.offset ?? 0
+    const count = request.count ?? 500
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('PTY read offset must be a non-negative safe integer')
+    if (!Number.isSafeInteger(count) || count <= 0) throw new Error('PTY read count must be a positive safe integer')
+    if (offset >= totalLines) {
+      return { text: '', totalLines, lineBegin: offset, lineEnd: offset, truncated: snapshot.truncated }
+    }
+    const end = totalLines - offset
+    const start = Math.max(0, end - count)
+    const requested = lines.slice(start, end).join('\n')
+    const bounded = utf8Tail(requested, this.config.maxReadBytes)
+    const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split('\n').length
+    return {
+      text: bounded.text,
+      totalLines,
+      lineBegin: offset,
+      lineEnd: offset + returnedLines,
+      truncated: snapshot.truncated || bounded.truncated,
+    }
+  }
+
+  signal(signal: PtySignal): Promise<PtySignalResult> {
+    return Promise.resolve().then(() => {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
+      if (signal === 'SIGKILL' && pgid === this.pid) {
+        throw new Error('refusing to SIGKILL the PTY shell; use pty_kill')
+      }
+      this.inspector.signalGroup(pgid, signal)
+      return { delivered: true, targetPgid: pgid }
+    })
+  }
+
+  status(): PtySessionStatus {
+    return this.statusValue
+  }
+
+  close(reason: string): Promise<void> {
+    this.closePromise ??= this.closeOnce(reason)
+    return this.closePromise
+  }
+
+  private onData(data: string): void {
+    const sanitized = this.sanitizer.push(data)
+    this.appendOutput(sanitized.text)
+    if (sanitized.prompt) {
+      this.promptSeen = true
+      this.lastOutputAt = Date.now()
+    }
+  }
+
+  private appendOutput(text: string): void {
+    if (text.length === 0) return
+    this.lastOutputAt = Date.now()
+    this.scrollback.append(text)
+    this.active?.append(text)
+  }
+
+  private pollReadiness(operation: LocalSendOperation): void {
+    if (this.active !== operation) return
+    if (this.statusValue.kind === 'exited') {
+      this.settleActive('session_exit')
+      return
+    }
+    if (this.promptSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
+      this.settleActive('stdin_read')
+      return
+    }
+    const elapsed = Date.now() - operation.startedAt
+    if (elapsed >= this.config.exactProbeAfterMs) {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (pgid !== undefined && this.inspector.isStdinWaiting(pgid)) {
+        this.settleActive('stdin_read')
+        return
+      }
+    }
+    if (Date.now() - this.lastOutputAt >= this.config.idleSilenceMs) {
+      this.settleActive('inferred_idle')
+      return
+    }
+    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
+  }
+
+  private settleActive(waitReason: PtyWaitReason): void {
+    const operation = this.active
+    if (operation === undefined) return
+    const scrollbackTruncated = this.scrollback.snapshot().truncated
+    this.clearActive()
+    operation.settle(waitReason, this.statusValue, scrollbackTruncated)
+  }
+
+  private clearActive(): void {
+    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
+    this.activeTimer = undefined
+    this.activeAbort?.()
+    this.activeAbort = undefined
+    this.active = undefined
+  }
+
+  private async closeOnce(reason: string): Promise<void> {
+    this.dataDisposable.dispose()
+    const members = this.inspector.processTree(this.pid)
+    for (const member of members) {
+      try {
+        this.inspector.signalProcess(member, 'SIGTERM')
+      } catch (_alreadyExitedDuringTerm) {
+        // Identity is rechecked by the inspector; a same-tick exit is success.
+      }
+    }
+    try {
+      this.terminal.kill('SIGTERM')
+    } catch (_topLevelAlreadyExited) {
+      // onExit or identity checks below remain authoritative.
+    }
+
+    const deadline = Date.now() + this.config.disposeGraceMs
+    let survivors = members.filter(member => this.inspector.isAlive(member))
+    while (survivors.length > 0 && Date.now() < deadline) {
+      await delay(Math.min(25, this.config.disposeGraceMs))
+      survivors = members.filter(member => this.inspector.isAlive(member))
+    }
+    for (const survivor of survivors) {
+      try {
+        this.inspector.signalProcess(survivor, 'SIGKILL')
+      } catch (_alreadyExitedDuringKill) {
+        // Final identity check below decides success.
+      }
+    }
+    try {
+      this.terminal.kill('SIGKILL')
+    } catch (_topLevelAlreadyKilled) {
+      // The root may already have delivered onExit.
+    }
+
+    const killDeadline = Date.now() + this.config.disposeGraceMs
+    survivors = members.filter(member => this.inspector.isAlive(member))
+    while (survivors.length > 0 && Date.now() < killDeadline) {
+      await delay(Math.min(25, this.config.disposeGraceMs))
+      survivors = members.filter(member => this.inspector.isAlive(member))
+    }
+    const exitWaitMs = Math.max(0, killDeadline - Date.now())
+    await Promise.race([this.exitPromise.promise, delay(exitWaitMs)])
+    survivors = members.filter(member => this.inspector.isAlive(member))
+    this.settleActive('session_exit')
+    this.exitDisposable.dispose()
+    if (survivors.length > 0) {
+      throw new Error(`PTY cleanup failed (${reason}); surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
+    }
+  }
+}