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/README.md
+++ b/packages/pty/pty-local/README.md
@@ -0,0 +1,32 @@
+# @deepseek-ai/dsh-pty-local
+
+Local `node-pty` backend for `ctx.pty`. It starts an interactive shell under the shared `ctx.sandboxPolicy`, strips credential-shaped ambient environment variables, retains bounded line-oriented output, detects readiness, and tears down the captured process tree rooted at the `node-pty` child.
+
+## Plugin (`pty-local`)
+
+The plugin injects `pty`, `sandbox`, and `sandboxPolicy`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The current session-level sandbox override is resolved at spawn and remains fixed for the PTY lifetime.
+
+Linux readiness combines a private bash prompt marker, foreground-process-group syscall inspection, silence fallback, and absolute timeout. macOS uses the prompt marker plus silence/timeout because it has no `/proc` syscall surface. Unrecognized or unreadable process state is never a positive exact-idle signal.
+
+## Model Experience
+
+### Indirect consumer
+
+#### What the model sees
+
+Nothing directly. Through `@deepseek-ai/dsh-tool-pty`, the model may receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
+
+#### Token effect
+
+None until a consumer returns bounded backend output. Retained PTY scrollback is not placed in model history by this package.
+
+#### KV Cache effect
+
+No direct invalidation; the consumer owns prompts, schemas, and appended results.
+
+## Known Limitations and Deferred Work
+
+- Line-oriented output is normalized; full-screen alternate-buffer interaction is unsupported.
+- Linux exact probes support x64 and arm64 UAPI tables; other architectures use prompt-marker and silence/timeout readiness.
+- A descendant that daemonizes and reparents before teardown leaves the captured tree; cleanup never broadens to the launcher PID's POSIX session because that can include unrelated processes.
+- Sessions do not survive harness process exit.
--- a/packages/pty/pty-local/package.json
+++ b/packages/pty/pty-local/package.json
@@ -0,0 +1,45 @@
+{
+  "name": "@deepseek-ai/dsh-pty-local",
+  "description": "Local node-pty backend for persistent DeepSeek Harness PTY sessions",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "scripts": {
+    "postinstall": "node src/ensure-spawn-helper.mjs"
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-pty": "^0.0.1",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "node-pty": "^1.1.0",
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-pty": "workspace:^",
+    "@deepseek-ai/dsh-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
--- 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(', ')}`)
+    }
+  }
+}
--- a/packages/pty/pty-local/tests/config.spec.ts
+++ b/packages/pty/pty-local/tests/config.spec.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import type { Config } from '@deepseek-ai/dsh-pty-local/src/config.ts'
+import { validateConfig } from '@deepseek-ai/dsh-pty-local/src/config.ts'
+
+function config(overrides: Partial<Config> = {}): Config {
+  return {
+    backendType: 'shell', shellPath: '/bin/bash', shellArgs: [], rows: 40, cols: 160,
+    scrollbackLines: 100, scrollbackMaxBytes: 1024, maxReadBytes: 512,
+    pollIntervalMs: 10, exactProbeAfterMs: 20, idleSilenceMs: 100, timeoutMs: 1000,
+    disposeGraceMs: 100,
+    ...overrides,
+  }
+}
+
+describe('pty-local config', () => {
+  it('accepts resolved positive bounds', () => {
+    expect(() => { validateConfig(config()) }).not.toThrow()
+  })
+
+  it('rejects empty names, invalid numbers, and a read cap above retention', () => {
+    expect(() => { validateConfig(config({ backendType: '' })) }).toThrow('backendType')
+    expect(() => { validateConfig(config({ shellPath: '' })) }).toThrow('shellPath')
+    expect(() => { validateConfig(config({ rows: 0 })) }).toThrow('rows')
+    expect(() => { validateConfig(config({ rows: 1.5 })) }).toThrow('rows')
+    expect(() => { validateConfig(config({ maxReadBytes: 2048 })) }).toThrow('must not exceed')
+  })
+})
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -0,0 +1,186 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { IPty, IPtyForkOptions } from 'node-pty'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SandboxProvider from '@deepseek-ai/dsh-sandbox'
+import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
+import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
+import * as ptyLocal from '@deepseek-ai/dsh-pty-local'
+import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-local/src/config.ts'
+import type { ProcessInspector } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
+import type { LocalPtySession } from '@deepseek-ai/dsh-pty-local/src/session.ts'
+
+class EmptySandbox extends SandboxProvider {
+  confine(_argv: readonly string[], _policy: SandboxPolicy): ConfinedArgv {
+    return { argv: [], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
+  }
+}
+
+class RecordingSandbox extends SandboxProvider {
+  calls: { argv: readonly string[]; policy: SandboxPolicy }[] = []
+
+  confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv {
+    this.calls.push({ argv, policy })
+    return { argv: ['/sandbox', '--', ...argv], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
+  }
+}
+
+function config(): ResolvedConfig {
+  return {
+    backendType: 'shell', shellPath: '/bin/bash', shellArgs: [], rows: 24, cols: 80,
+    scrollbackLines: 10, scrollbackMaxBytes: 100, maxReadBytes: 50,
+    pollIntervalMs: 10, exactProbeAfterMs: 20, idleSilenceMs: 50, timeoutMs: 100,
+    disposeGraceMs: 10,
+  }
+}
+
+function agent(ctx: Context): Agent {
+  const id = SessionId('agent')
+  return {
+    id, options: {}, session: new Session(id), status: 'idle', ctx,
+    send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+  }
+}
+
+const inspector = {
+  foregroundPgid: () => undefined,
+  isStdinWaiting: () => false,
+  processTree: () => [],
+  isAlive: () => false,
+  signalGroup() {},
+  signalProcess() {},
+} satisfies ProcessInspector
+
+function spec(owner: Agent, signal?: AbortSignal) {
+  return {
+    sessionId: PtySessionId('pty-1'), owner, type: 'shell',
+    ...signal !== undefined ? { signal } : {},
+  }
+}
+
+describe('LocalPtyBackend startup rollback', () => {
+  it('rejects pre-aborted setup and empty sandbox argv', async () => {
+    const ctx = new Context()
+    await ctx.plugin(EmptySandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/tmp' })
+    const backend = new LocalPtyBackend(ctx, config(), inspector)
+    const controller = new AbortController()
+    controller.abort()
+    await expect(backend.spawn(spec(agent(ctx), controller.signal))).rejects.toThrow('spawn aborted')
+    await expect(backend.spawn(spec(agent(ctx)))).rejects.toThrow('empty argv')
+  })
+
+  it('closes failed startup and aggregates cleanup failure', async () => {
+    const ctx = new Context()
+    await ctx.plugin(EmptySandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    const spawnTerminal = (() => ({} as IPty)) as never
+
+    const closed = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
+    const failed = { initialize: () => Promise.reject(new Error('startup failed')), close: closed } as unknown as LocalPtySession
+    const backend = new LocalPtyBackend(ctx, config(), inspector, spawnTerminal, () => failed)
+    await expect(backend.spawn(spec(agent(ctx)))).rejects.toThrow('startup failed')
+    expect(closed).toHaveBeenCalledWith('PTY startup failed')
+
+    const doublyFailed = {
+      initialize: () => Promise.reject(new Error('startup failed')),
+      close: () => Promise.reject(new Error('cleanup failed')),
+    } as unknown as LocalPtySession
+    const aggregate = new LocalPtyBackend(ctx, config(), inspector, spawnTerminal, () => doublyFailed)
+    await expect(aggregate.spawn(spec(agent(ctx)))).rejects.toThrow('startup and cleanup both failed')
+  })
+
+  it('wraps confined argv, scrubs the environment, and returns initialized sessions', async () => {
+    const ctx = new Context()
+    await ctx.plugin(RecordingSandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: '/workspace' })
+    const terminal = {} as IPty
+    let spawned: { file: string; args: string[]; options: IPtyForkOptions } | undefined
+    const spawnTerminal = ((file: string, args: string[], options: IPtyForkOptions) => {
+      spawned = { file, args, options }
+      return terminal
+    }) as never
+    const initialized = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
+    const session = { initialize: initialized } as unknown as LocalPtySession
+    const backend = new LocalPtyBackend(
+      ctx,
+      { ...config(), shellArgs: ['-i'] },
+      inspector,
+      spawnTerminal,
+      () => session,
+    )
+    const previous = process.env.PTY_TEST_SECRET
+    process.env.PTY_TEST_SECRET = 'must-not-leak'
+    try {
+      expect(await backend.spawn({ ...spec(agent(ctx)), cwd: '/work' })).toBe(session)
+    } finally {
+      if (previous === undefined) delete process.env.PTY_TEST_SECRET
+      else process.env.PTY_TEST_SECRET = previous
+    }
+
+    expect(spawned).toMatchObject({
+      file: '/sandbox',
+      args: ['--', '/bin/bash', '-i'],
+      options: {
+        name: 'dumb', cols: 80, rows: 24, cwd: '/work',
+        env: {
+          TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ', BASH_SILENCE_DEPRECATION_WARNING: '1',
+          DSH_SHELL: '1', DSH_SESSION_ID: 'agent', DSH_PTY_SESSION_ID: 'pty-1',
+        },
+      },
+    })
+    expect(spawned?.options.env?.PTY_TEST_SECRET).toBeUndefined()
+    expect(initialized).toHaveBeenCalledWith(undefined)
+  })
+
+  it('composes the default local session around a spawned terminal', async () => {
+    const ctx = new Context()
+    await ctx.plugin(EmptySandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/workspace' })
+    let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
+    const terminal = {
+      pid: 123, cols: 80, rows: 24, process: 'bash', handleFlowControl: false,
+      onData(listener: (data: string) => void) {
+        queueMicrotask(() => { listener('\x1b]133;D;0\x07dsh> ') })
+        return { dispose() {} }
+      },
+      onExit(listener: (event: { exitCode: number; signal?: number }) => void) {
+        exitListener = listener
+        return { dispose() {} }
+      },
+      write() {},
+      kill() { exitListener?.({ exitCode: 0, signal: 15 }) },
+      resize() {}, clear() {}, pause() {}, resume() {},
+    } as IPty
+    const backend = new LocalPtyBackend(ctx, config(), inspector, () => terminal)
+    const session = await backend.spawn(spec(agent(ctx)))
+    expect(session.motd).toBe('dsh> ')
+    await session.close('test complete')
+  })
+})
+
+describe('pty-local plugin shape', () => {
+  it('keeps name, inject, and Config through Loader unwrapExports', () => {
+    expect('default' in ptyLocal).toBe(false)
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(ptyLocal) as Record<string, unknown>
+    expect(unwrapped.name).toBe('pty-local')
+    expect(unwrapped.inject).toEqual(['pty', 'sandbox', 'sandboxPolicy'])
+    expect(unwrapped.Config).toBeDefined()
+  })
+
+  it('validates config and registers the configured backend', async () => {
+    const ctx = new Context()
+    await ctx.plugin(PtyService)
+    await ctx.plugin(EmptySandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    const fiber = await ctx.plugin(ptyLocal, config())
+    expect(ctx.pty.listBackends()).toEqual(['shell'])
+    await fiber.dispose()
+    expect(ctx.pty.listBackends()).toEqual([])
+  })
+})
--- a/packages/pty/pty-local/tests/local.spec.ts
+++ b/packages/pty/pty-local/tests/local.spec.ts
@@ -0,0 +1,122 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import PtyService from '@deepseek-ai/dsh-pty'
+import SandboxProvider from '@deepseek-ai/dsh-sandbox'
+import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import * as ptyLocal from '@deepseek-ai/dsh-pty-local'
+
+const roots: string[] = []
+const contexts: Context[] = []
+
+afterEach(async () => {
+  for (const ctx of contexts.splice(0)) await ctx.fiber.dispose()
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+class PassthroughSandbox extends SandboxProvider {
+  calls: { argv: readonly string[]; policy: SandboxPolicy }[] = []
+
+  confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv {
+    this.calls.push({ argv, policy })
+    return { argv: [...argv], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
+  }
+}
+
+function stubAgent(ctx: Context, rawId: string): Agent {
+  const id = SessionId(rawId)
+  const scope = ctx.plugin(() => {})
+  return {
+    id, options: {}, session: new Session(id), status: 'idle', ctx: scope.ctx,
+    send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+  }
+}
+
+async function harness(mode: 'danger-full-access' | 'workspace-write') {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-pty-local-'))
+  roots.push(root)
+  const ctx = new Context()
+  contexts.push(ctx)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(PtyService)
+  await ctx.plugin(PassthroughSandbox)
+  await ctx.plugin(SandboxPolicyService, { mode, workspaceRoot: root })
+  const fiber = await ctx.plugin(ptyLocal, {
+    pollIntervalMs: 10,
+    exactProbeAfterMs: 20,
+    idleSilenceMs: 250,
+    timeoutMs: 2000,
+    disposeGraceMs: 500,
+    scrollbackLines: 100,
+    scrollbackMaxBytes: 32_768,
+    maxReadBytes: 16_384,
+  })
+  const agent = stubAgent(ctx, `agent-${mode}`)
+  ctx.agents.register(agent)
+  return { ctx, root, agent, fiber, sandbox: ctx.sandbox as PassthroughSandbox }
+}
+
+describe('pty-local real shell', () => {
+  it('persists cwd and environment across sends, scrubs secrets, and closes', async () => {
+    const previous = process.env.DSH_TEST_SECRET
+    process.env.DSH_TEST_SECRET = 'must-not-leak'
+    try {
+      const { ctx, root, agent } = await harness('danger-full-access')
+      const created = await ctx.pty.spawn(agent, { type: 'shell', name: 'main', cwd: root })
+      expect(created.motd).toContain('dsh> ')
+
+      const first = ctx.pty.startSend(agent, created.sessionId, { text: 'export KEEP=ok; cd /', submit: true })
+      expect((await first.done).waitReason).toBe('stdin_read')
+      const second = ctx.pty.startSend(agent, created.sessionId, { text: 'printf "cwd=%s keep=%s secret=%s\\n" "$PWD" "$KEEP" "${DSH_TEST_SECRET-unset}"', submit: true })
+      expect((await second.done).viewport).toContain('cwd=/ keep=ok secret=unset')
+
+      expect(ctx.pty.read(agent, created.sessionId, { offset: 0, count: 20 }).text).toContain('cwd=/ keep=ok secret=unset')
+      expect(await ctx.pty.kill(agent, created.sessionId)).toBe(true)
+      expect(ctx.pty.list(agent)).toEqual([])
+    } finally {
+      if (previous === undefined) delete process.env.DSH_TEST_SECRET
+      else process.env.DSH_TEST_SECRET = previous
+    }
+  }, 10_000)
+
+  it('wraps the exact shell argv under confined policy and unregisters on reload', async () => {
+    const { ctx, root, agent, fiber, sandbox } = await harness('workspace-write')
+    const created = await ctx.pty.spawn(agent, { type: 'shell' })
+    expect(sandbox.calls).toEqual([{
+      argv: ['/bin/bash', '--noprofile', '--norc', '-i'],
+      policy: { mode: 'workspace-write', workspaceRoot: root },
+    }])
+    await fiber.dispose()
+    expect(ctx.pty.listBackends()).toEqual([])
+    expect(ctx.pty.list(agent)).toHaveLength(1)
+    await ctx.pty.kill(agent, created.sessionId)
+  }, 10_000)
+
+  it('signals a foreground command and kills a TERM-ignoring background descendant', async () => {
+    const { ctx, agent } = await harness('danger-full-access')
+    const created = await ctx.pty.spawn(agent, { type: 'shell' })
+
+    const foreground = ctx.pty.startSend(agent, created.sessionId, { text: 'sleep 60', submit: true })
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect((await ctx.pty.signal(agent, created.sessionId, 'SIGINT')).delivered).toBe(true)
+    expect((await foreground.done).waitReason).toBe('stdin_read')
+
+    const background = ctx.pty.startSend(agent, created.sessionId, {
+      text: 'sh -c \'trap "" TERM; sleep 60\' & echo CHILD=$!',
+      submit: true,
+    })
+    const output = (await background.done).viewport
+    const child = /CHILD=(\d+)/.exec(output)?.[1]
+    expect(child).toBeDefined()
+    const pid = Number(child)
+    expect(() => process.kill(pid, 0)).not.toThrow()
+    await ctx.pty.kill(agent, created.sessionId)
+    expect(() => process.kill(pid, 0)).toThrow()
+  }, 10_000)
+})
--- a/packages/pty/pty-local/tests/process-inspector.spec.ts
+++ b/packages/pty/pty-local/tests/process-inspector.spec.ts
@@ -0,0 +1,215 @@
+import { describe, expect, it } from 'vitest'
+import { createProcessInspector, parseProcStat } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
+import type { ProcessInspectorInternals } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
+
+function stat(pid: number, pgrp: number, session: number, tpgid: number, started: string, parentPid = 1): string {
+  const rest = ['S', String(parentPid), String(pgrp), String(session), '99', String(tpgid)]
+  while (rest.length < 19) rest.push('0')
+  rest.push(started)
+  return `${pid} (command with space) ${rest.join(' ')}`
+}
+
+function syscall(number: number, ...args: number[]): string {
+  const six = [...args]
+  while (six.length < 6) six.push(0)
+  return `${number} ${six.slice(0, 6).map(value => `0x${value.toString(16)}`).join(' ')}`
+}
+
+function fakeInternals() {
+  const files = new Map<string, string>()
+  const dirs = new Map<string, string[]>()
+  const memories = new Map<string, Buffer>()
+  const fds = new Map<number, string>()
+  const kills: Array<[number, NodeJS.Signals]> = []
+  let nextFd = 10
+  let ps = ''
+  let tpgid = '0'
+  const internals: ProcessInspectorInternals = {
+    readFile(path) {
+      const value = files.get(path)
+      if (value === undefined) throw new Error(`missing ${path}`)
+      return value
+    },
+    readDir(path) {
+      const value = dirs.get(path)
+      if (value === undefined) throw new Error(`missing ${path}`)
+      return value
+    },
+    open(path) {
+      if (!memories.has(path)) throw new Error(`missing ${path}`)
+      const fd = nextFd++
+      fds.set(fd, path)
+      return fd
+    },
+    read(fd, buffer, length, position) {
+      const path = fds.get(fd)
+      if (path === undefined) throw new Error('bad fd')
+      const source = memories.get(path)
+      if (source === undefined) throw new Error('missing memory')
+      return source.copy(buffer, 0, position, Math.min(source.length, position + length))
+    },
+    close(fd) { fds.delete(fd) },
+    exec(_file, args) {
+      if (args.includes('tpgid=')) return tpgid
+      return ps
+    },
+    kill(pid, signal) { kills.push([pid, signal]) },
+  }
+  return {
+    internals, files, dirs, memories, kills,
+    setPs(value: string) { ps = value },
+    setTpgid(value: string) { tpgid = value },
+  }
+}
+
+describe('Linux process inspector', () => {
+  it('parses stat safely, captures only the rooted process tree, and signals identities', () => {
+    expect(parseProcStat('bad')).toBeUndefined()
+    expect(parseProcStat('1 () S')).toBeUndefined()
+    expect(parseProcStat(stat(10, 20, 30, 40, '500'))).toEqual({ pid: 10, parentPid: 1, pgrp: 20, session: 30, tpgid: 40, started: '500' })
+
+    const fake = fakeInternals()
+    fake.dirs.set('/proc', ['x', '10', '11', '12', '13', '14'])
+    fake.files.set('/proc/10/stat', stat(10, 20, 30, 40, '500'))
+    fake.files.set('/proc/11/stat', stat(11, 21, 30, -1, '501'))
+    fake.files.set('/proc/12/stat', stat(12, 22, 30, -1, '502', 10))
+    fake.files.set('/proc/13/stat', stat(13, 23, 30, -1, '503', 12))
+    const inspector = createProcessInspector('linux', 'x64', fake.internals)
+    expect(inspector.foregroundPgid(10)).toBe(40)
+    expect(inspector.foregroundPgid(11)).toBeUndefined()
+    expect(inspector.foregroundPgid(99)).toBeUndefined()
+    expect(inspector.processTree(10)).toEqual([
+      { pid: 13, started: '503' },
+      { pid: 12, started: '502' },
+      { pid: 10, started: '500' },
+    ])
+    expect(inspector.processTree(99)).toEqual([])
+    expect(inspector.isAlive({ pid: 10, started: '500' })).toBe(true)
+    expect(inspector.isAlive({ pid: 10, started: 'old' })).toBe(false)
+    inspector.signalGroup(40, 'SIGINT')
+    inspector.signalProcess({ pid: 10, started: '500' }, 'SIGTERM')
+    inspector.signalProcess({ pid: 10, started: 'old' }, 'SIGKILL')
+    expect(fake.kills).toEqual([[-40, 'SIGINT'], [10, 'SIGTERM']])
+  })
+
+  it('detects read, select, poll, and epoll waits across non-leader threads', () => {
+    const fake = fakeInternals()
+    fake.dirs.set('/proc', ['100', '101'])
+    fake.files.set('/proc/100/stat', stat(100, 77, 100, 77, '1'))
+    fake.files.set('/proc/101/stat', stat(101, 77, 100, 77, '2'))
+    fake.dirs.set('/proc/100/task', ['100'])
+    fake.dirs.set('/proc/101/task', ['101', '102'])
+    const inspector = createProcessInspector('linux', 'x64', fake.internals)
+
+    fake.files.set('/proc/100/task/100/syscall', 'running')
+    fake.files.set('/proc/101/task/101/syscall', '-1 0x0')
+    fake.files.set('/proc/101/task/102/syscall', syscall(0, 0))
+    expect(inspector.isStdinWaiting(77)).toBe(true)
+
+    fake.files.set('/proc/101/task/102/syscall', syscall(270, 1, 0x10))
+    const fdSet = Buffer.alloc(0x11)
+    fdSet[0x10] = 1
+    fake.memories.set('/proc/101/mem', fdSet)
+    expect(inspector.isStdinWaiting(77)).toBe(true)
+
+    const poll = Buffer.alloc(8)
+    poll.writeInt32LE(0, 0)
+    poll.writeInt16LE(1, 4)
+    fake.files.set('/proc/101/task/102/syscall', syscall(7, 0x20, 1))
+    fake.memories.set('/proc/101/mem', Buffer.concat([Buffer.alloc(0x20), poll]))
+    expect(inspector.isStdinWaiting(77)).toBe(true)
+
+    fake.files.set('/proc/101/task/102/syscall', syscall(232, 5, 0, 1))
+    fake.files.set('/proc/101/fdinfo/5', 'pos: 0\ntfd: 0 events: 19\n')
+    expect(inspector.isStdinWaiting(77)).toBe(true)
+  })
+
+  it('fails closed on unsupported, malformed, unreadable, or non-stdin waits', () => {
+    const fake = fakeInternals()
+    fake.dirs.set('/proc', ['100'])
+    fake.files.set('/proc/100/stat', stat(100, 77, 100, 77, '1'))
+    fake.dirs.set('/proc/100/task', ['100'])
+    fake.files.set('/proc/100/task/100/syscall', syscall(0, 2))
+    expect(createProcessInspector('linux', 'mips', fake.internals).isStdinWaiting(77)).toBe(false)
+    expect(createProcessInspector('linux', 'x64', fake.internals).isStdinWaiting(77)).toBe(false)
+
+    fake.files.set('/proc/100/task/100/syscall', syscall(270, 1, 0))
+    expect(createProcessInspector('linux', 'x64', fake.internals).isStdinWaiting(77)).toBe(false)
+    fake.files.set('/proc/100/task/100/syscall', syscall(7, 0, 0))
+    expect(createProcessInspector('linux', 'x64', fake.internals).isStdinWaiting(77)).toBe(false)
+    fake.files.set('/proc/100/task/100/syscall', syscall(7, 0, 1))
+    expect(createProcessInspector('linux', 'x64', fake.internals).isStdinWaiting(77)).toBe(false)
+    fake.files.set('/proc/100/task/100/syscall', syscall(7, 0x20, 1))
+    expect(createProcessInspector('linux', 'x64', fake.internals).isStdinWaiting(77)).toBe(false)
+    fake.files.set('/proc/100/task/100/syscall', syscall(232, 9, 0, 1))
+    expect(createProcessInspector('linux', 'x64', fake.internals).isStdinWaiting(77)).toBe(false)
+    fake.files.set('/proc/100/task/100/syscall', syscall(999))
+    expect(createProcessInspector('linux', 'x64', fake.internals).isStdinWaiting(77)).toBe(false)
+
+    fake.files.set('/proc/100/task/100/syscall', 'not-a-number 0x0')
+    expect(createProcessInspector('linux', 'x64', fake.internals).isStdinWaiting(77)).toBe(false)
+    fake.dirs.delete('/proc/100/task')
+    expect(createProcessInspector('linux', 'x64', fake.internals).isStdinWaiting(77)).toBe(false)
+    fake.dirs.set('/proc', ['100', '200'])
+    fake.files.set('/proc/200/stat', stat(200, 88, 200, 88, '2'))
+    expect(createProcessInspector('linux', 'x64', fake.internals).isStdinWaiting(77)).toBe(false)
+  })
+
+  it('contains unreadable syscall, memory, and fdinfo boundaries', () => {
+    const fake = fakeInternals()
+    fake.dirs.set('/proc', ['100'])
+    fake.files.set('/proc/100/stat', stat(100, 77, 100, 77, '1'))
+    fake.dirs.set('/proc/100/task', ['100'])
+    const inspector = createProcessInspector('linux', 'x64', fake.internals)
+    expect(inspector.isStdinWaiting(77)).toBe(false)
+
+    fake.files.set('/proc/100/task/100/syscall', syscall(270, 1, 0x10))
+    expect(inspector.isStdinWaiting(77)).toBe(false)
+    fake.files.set('/proc/100/task/100/syscall', syscall(232, 5, 0, 1))
+    expect(inspector.isStdinWaiting(77)).toBe(false)
+
+    const noStdinPoll = Buffer.alloc(0x28)
+    noStdinPoll.writeInt32LE(2, 0x20)
+    noStdinPoll.writeInt16LE(1, 0x24)
+    fake.memories.set('/proc/100/mem', noStdinPoll)
+    fake.files.set('/proc/100/task/100/syscall', syscall(7, 0x20, 1))
+    expect(inspector.isStdinWaiting(77)).toBe(false)
+  })
+})
+
+describe('macOS process inspector', () => {
+  it('reads tpgid and process trees, contains cycles, and identity-fences signals', () => {
+    const fake = fakeInternals()
+    fake.setTpgid('55\n')
+    fake.setPs(' 10 1 Mon Jul 21 10:00:00 2026\n 11 10 Mon Jul 21 10:00:01 2026\n 12 11 Mon Jul 21 10:00:02 2026\n 13 99 Mon Jul 21 10:00:03 2026\nmalformed\n')
+    const inspector = createProcessInspector('darwin', 'arm64', fake.internals)
+    expect(inspector.foregroundPgid(10)).toBe(55)
+    expect(inspector.isStdinWaiting(55)).toBe(false)
+    expect(inspector.processTree(10)).toEqual([
+      { pid: 12, started: 'Mon Jul 21 10:00:02 2026' },
+      { pid: 11, started: 'Mon Jul 21 10:00:01 2026' },
+      { pid: 10, started: 'Mon Jul 21 10:00:00 2026' },
+    ])
+    expect(inspector.processTree(99)).toEqual([])
+    expect(inspector.isAlive({ pid: 11, started: 'Mon Jul 21 10:00:01 2026' })).toBe(true)
+    inspector.signalGroup(55, 'SIGTSTP')
+    inspector.signalProcess({ pid: 11, started: 'Mon Jul 21 10:00:01 2026' }, 'SIGKILL')
+    inspector.signalProcess({ pid: 12, started: 'missing' }, 'SIGTERM')
+    expect(fake.kills).toEqual([[-55, 'SIGTSTP'], [11, 'SIGKILL']])
+
+    fake.setPs(' 10 11 Mon Jul 21 10:00:00 2026\n 11 10 Mon Jul 21 10:00:01 2026\n')
+    expect(inspector.processTree(10)).toEqual([
+      { pid: 11, started: 'Mon Jul 21 10:00:01 2026' },
+      { pid: 10, started: 'Mon Jul 21 10:00:00 2026' },
+    ])
+  })
+
+  it('returns undefined for missing or invalid foreground groups and rejects unsupported platforms', () => {
+    const fake = fakeInternals()
+    fake.setTpgid('-1')
+    expect(createProcessInspector('darwin', 'arm64', fake.internals).foregroundPgid(1)).toBeUndefined()
+    fake.internals.exec = () => { throw new Error('gone') }
+    expect(createProcessInspector('darwin', 'arm64', fake.internals).foregroundPgid(1)).toBeUndefined()
+    expect(() => createProcessInspector('win32', 'x64', fake.internals)).toThrow('unsupported platform win32')
+  })
+})
--- a/packages/pty/pty-local/tests/sanitize.spec.ts
+++ b/packages/pty/pty-local/tests/sanitize.spec.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import { normalizeTerminalText, TerminalSanitizer } from '@deepseek-ai/dsh-pty-local/src/sanitize.ts'
+
+describe('TerminalSanitizer', () => {
+  it('removes split CSI and owned OSC prompt markers', () => {
+    const sanitizer = new TerminalSanitizer()
+    expect(sanitizer.push('red\x1b[3')).toEqual({ text: 'red', prompt: false })
+    expect(sanitizer.push('1m text\x1b[0m\r\n')).toEqual({ text: ' text\n', prompt: false })
+    expect(sanitizer.push('\x1b]133;')).toEqual({ text: '', prompt: false })
+    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true })
+  })
+
+  it('drops unrelated OSC, short escapes, BEL, and incomplete trailing escape', () => {
+    const sanitizer = new TerminalSanitizer()
+    expect(sanitizer.push('a\x1b]0;title\x1b\\b\x1b7c\x07')).toEqual({ text: 'abc', prompt: false })
+    expect(sanitizer.push('tail\x1b')).toEqual({ text: 'tail', prompt: false })
+    expect(sanitizer.flush()).toBe('')
+    expect(sanitizer.flush()).toBe('')
+    expect(sanitizer.push('\x1b]0;one\x07middle\x1b\\')).toEqual({ text: 'middle', prompt: false })
+    expect(sanitizer.push('\x1b]0;one\x1b\\middle\x07')).toEqual({ text: 'middle', prompt: false })
+    expect(sanitizer.push('\x1b]0;title\x1b\\')).toEqual({ text: '', prompt: false })
+  })
+
+  it('normalizes CRLF and standalone carriage returns', () => {
+    expect(normalizeTerminalText('a\r\nb\rc\x07')).toBe('a\nb\nc')
+  })
+})
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -0,0 +1,301 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { IDisposable, IPty } from 'node-pty'
+import { LocalPtySession } from '@deepseek-ai/dsh-pty-local/src/session.ts'
+import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-local/src/config.ts'
+import type { ProcessIdentity, ProcessInspector } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
+import type { PtySendOperation, PtySessionStatus, PtySignal } from '@deepseek-ai/dsh-pty'
+
+class FakeTerminal {
+  pid = 123
+  cols = 80
+  rows = 24
+  process = 'bash'
+  handleFlowControl = false
+  writes: string[] = []
+  kills: string[] = []
+  throwWrite = false
+  throwKill = false
+  private dataListeners = new Set<(data: string) => void>()
+  private exitListeners = new Set<(event: { exitCode: number; signal?: number }) => void>()
+
+  readonly onData = (listener: (data: string) => void): IDisposable => {
+    this.dataListeners.add(listener)
+    return { dispose: () => this.dataListeners.delete(listener) }
+  }
+
+  readonly onExit = (listener: (event: { exitCode: number; signal?: number }) => void): IDisposable => {
+    this.exitListeners.add(listener)
+    return { dispose: () => this.exitListeners.delete(listener) }
+  }
+
+  emitData(data: string): void {
+    for (const listener of this.dataListeners) listener(data)
+  }
+
+  emitExit(exitCode = 0, signal?: number): void {
+    for (const listener of this.exitListeners) listener({ exitCode, ...signal === undefined ? {} : { signal } })
+  }
+
+  write(data: string): void {
+    if (this.throwWrite) throw new Error('write failed')
+    this.writes.push(data)
+  }
+
+  kill(signal?: string): void {
+    if (this.throwKill) throw new Error('kill failed')
+    this.kills.push(signal ?? 'SIGHUP')
+    this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
+  }
+
+  resize() {}
+  clear() {}
+  pause() {}
+  resume() {}
+
+  asPty(): IPty {
+    return this
+  }
+}
+
+class FakeInspector implements ProcessInspector {
+  pgid: number | undefined = 456
+  waiting = false
+  members: ProcessIdentity[] = []
+  alive = new Set<number>()
+  groups: Array<[number, PtySignal]> = []
+  processes: Array<[number, 'SIGTERM' | 'SIGKILL']> = []
+  throwGroup = false
+  throwProcess = false
+  removeOnSignal = true
+
+  foregroundPgid() { return this.pgid }
+  isStdinWaiting() { return this.waiting }
+  processTree() { return this.members }
+  isAlive(identity: ProcessIdentity) { return this.alive.has(identity.pid) }
+  signalGroup(pgid: number, signal: PtySignal) {
+    if (this.throwGroup) throw new Error('group failed')
+    this.groups.push([pgid, signal])
+  }
+  signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL') {
+    if (this.throwProcess) throw new Error('process raced')
+    this.processes.push([identity.pid, signal])
+    if (this.removeOnSignal) this.alive.delete(identity.pid)
+  }
+}
+
+function config(overrides: Partial<ResolvedConfig> = {}): ResolvedConfig {
+  return {
+    backendType: 'shell', shellPath: '/bin/bash', shellArgs: [], rows: 24, cols: 80,
+    scrollbackLines: 10, scrollbackMaxBytes: 128, maxReadBytes: 64,
+    pollIntervalMs: 10, exactProbeAfterMs: 20, idleSilenceMs: 50, timeoutMs: 100,
+    disposeGraceMs: 20,
+    ...overrides,
+  }
+}
+
+afterEach(() => { vi.useRealTimers() })
+
+async function initialize(session: LocalPtySession, terminal: FakeTerminal): Promise<void> {
+  const pending = session.initialize()
+  terminal.emitData('\x1b]133;D;0\x07dsh> ')
+  await vi.advanceTimersByTimeAsync(10)
+  await pending
+}
+
+describe('LocalPtySession readiness and output', () => {
+  it('captures prompt MOTD, writes submit explicitly, and settles exact stdin waits', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    await initialize(session, terminal)
+    expect(session.motd).toBe('dsh> ')
+
+    inspector.waiting = true
+    const operation = session.startSend({ text: 'python3', submit: true })
+    expect(terminal.writes).toEqual(['python3', '\r'])
+    terminal.emitData('Python\r\n>>> ')
+    await vi.advanceTimersByTimeAsync(20)
+    expect(await operation.done).toMatchObject({ waitReason: 'stdin_read', viewport: 'Python\n>>> ', sessionStatus: { kind: 'running' } })
+    expect(operation.cancel()).toBe(false)
+  })
+
+  it('distinguishes inferred idle, timeout, exit signal, and operation reads', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    inspector.pgid = undefined
+    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    await initialize(session, terminal)
+
+    const inferred = session.startSend({ text: 'sleep', submit: false })
+    terminal.emitData('working')
+    expect(inferred.readOutput()).toEqual({ delta: 'working', truncated: false })
+    await vi.advanceTimersByTimeAsync(60)
+    expect((await inferred.done).waitReason).toBe('inferred_idle')
+
+    const timeout = session.startSend({ text: 'blocked', submit: false })
+    await vi.advanceTimersByTimeAsync(40)
+    terminal.emitData('.')
+    await vi.advanceTimersByTimeAsync(40)
+    terminal.emitData('.')
+    await vi.advanceTimersByTimeAsync(30)
+    expect((await timeout.done).waitReason).toBe('timeout')
+
+    const exiting = session.startSend({ text: 'exit', submit: true })
+    terminal.emitExit(7, 9)
+    expect(await exiting.done).toMatchObject({ waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: 7, signal: 'SIGKILL' } })
+    expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
+  })
+
+  it('cancels with Ctrl-C, observes AbortSignal, and contains write failures', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    await initialize(session, terminal)
+
+    const controller = new AbortController()
+    const operation = session.startSend({ text: 'sleep', submit: true, signal: controller.signal })
+    expect(() => session.startSend({ text: 'again', submit: true })).toThrow('active send')
+    controller.abort()
+    expect(terminal.writes.at(-1)).toBe('\x03')
+    terminal.emitData('\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+
+    const aborted = new AbortController()
+    aborted.abort()
+    expect(() => session.startSend({ text: '', submit: false, signal: aborted.signal })).toThrow('aborted before write')
+
+    terminal.throwWrite = true
+    const failed = session.startSend({ text: 'x', submit: false })
+    await expect(failed.done).rejects.toThrow('write failed')
+    const failedInternal = failed as unknown as { append(text: string): void; fail(error: unknown): void }
+    failedInternal.append('ignored')
+    failedInternal.fail(new Error('ignored'))
+  })
+
+  it('handles startup exit, unknown exit signals, cancel-write failure, and stale polls', async () => {
+    vi.useFakeTimers()
+    const startupTerminal = new FakeTerminal()
+    const startup = new LocalPtySession(startupTerminal.asPty(), new FakeInspector(), config())
+    const initializing = startup.initialize(new AbortController().signal)
+    startupTerminal.emitExit(1)
+    await expect(initializing).rejects.toThrow('exited during startup')
+    expect(startup.status()).toEqual({ kind: 'exited', exitCode: 1, signal: null })
+
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal.asPty(), new FakeInspector(), config())
+    await initialize(session, terminal)
+    const operation = session.startSend({ text: '', submit: false })
+    const operationInternal = operation as unknown as {
+      append(text: string): void
+      settle(reason: 'timeout', status: PtySessionStatus, inherited: boolean): void
+    }
+    operationInternal.append('')
+    const sessionInternal = session as unknown as {
+      pollReadiness(operation: PtySendOperation): void
+      statusValue: PtySessionStatus
+      appendOutput(text: string): void
+    }
+    sessionInternal.appendOutput('')
+    sessionInternal.pollReadiness({} as PtySendOperation)
+    sessionInternal.statusValue = { kind: 'exited', exitCode: 2, signal: null }
+    sessionInternal.pollReadiness(operation)
+    await operation.done
+    operationInternal.settle('timeout', { kind: 'running' }, false)
+
+    const unknownTerminal = new FakeTerminal()
+    const unknown = new LocalPtySession(unknownTerminal.asPty(), new FakeInspector(), config())
+    unknownTerminal.emitExit(1, 999)
+    expect(unknown.status()).toEqual({ kind: 'exited', exitCode: 1, signal: null })
+
+    const cancelTerminal = new FakeTerminal()
+    const cancel = new LocalPtySession(cancelTerminal.asPty(), new FakeInspector(), config())
+    await initialize(cancel, cancelTerminal)
+    const cancellable = cancel.startSend({ text: '', submit: false })
+    cancelTerminal.throwWrite = true
+    expect(cancellable.cancel()).toBe(true)
+    await expect(cancellable.done).rejects.toThrow('write failed')
+  })
+})
+
+describe('LocalPtySession bounds, signals, and teardown', () => {
+  it('validates pagination and enforces line/UTF-8 bounds', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(
+      terminal.asPty(),
+      new FakeInspector(),
+      config({ scrollbackLines: 3, scrollbackMaxBytes: 12, maxReadBytes: 6 }),
+    )
+    expect(session.read({})).toMatchObject({ text: '' })
+    await initialize(session, terminal)
+    const operation = session.startSend({ text: '', submit: false })
+    terminal.emitData('一\n二\n三\n四')
+    await vi.advanceTimersByTimeAsync(60)
+    expect((await operation.done).truncated).toBe(true)
+    const page = session.read({ offset: 0, count: 3 })
+    expect(Buffer.byteLength(page.text)).toBeLessThanOrEqual(6)
+    expect(page.truncated).toBe(true)
+    expect(session.read({ offset: 999 })).toMatchObject({ text: '', lineBegin: 999, lineEnd: 999 })
+    expect(() => session.read({ offset: -1 })).toThrow('offset')
+    expect(() => session.read({ count: 0 })).toThrow('count')
+
+    const tinyTerminal = new FakeTerminal()
+    const tiny = new LocalPtySession(tinyTerminal.asPty(), new FakeInspector(), config({ maxReadBytes: 1 }))
+    await initialize(tiny, tinyTerminal)
+    const tinyOperation = tiny.startSend({ text: '', submit: false })
+    tinyTerminal.emitData('一')
+    await vi.advanceTimersByTimeAsync(60)
+    await tinyOperation.done
+    expect(tiny.read({ offset: 0, count: 1 }).text).toBe('')
+  })
+
+  it('signals verified groups and refuses unresolved or shell-targeted hard kills', async () => {
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    expect(await session.signal('SIGINT')).toEqual({ delivered: true, targetPgid: 456 })
+    inspector.pgid = terminal.pid
+    await expect(session.signal('SIGKILL')).rejects.toThrow('use pty_kill')
+    inspector.pgid = undefined
+    await expect(session.signal('SIGTERM')).rejects.toThrow('cannot resolve')
+  })
+
+  it('closes idempotently, contains signal races, and reports survivors', async () => {
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 123, started: 'a' }]
+    inspector.alive.add(123)
+    inspector.throwProcess = true
+    terminal.throwKill = true
+    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 1 }))
+    const closing = session.close('test')
+    expect(session.close('other')).toBe(closing)
+    await expect(closing).rejects.toThrow('surviving pids: 123')
+    expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
+  })
+
+  it('waits for SIGKILL recipients to leave the process table after the shell exits', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 124, started: 'child' }]
+    inspector.alive.add(124)
+    inspector.removeOnSignal = false
+    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 20 }))
+
+    let settled = false
+    const closing = session.close('test').then(() => { settled = true })
+    await vi.advanceTimersByTimeAsync(20)
+    expect(inspector.processes).toContainEqual([124, 'SIGKILL'])
+    expect(settled).toBe(false)
+
+    inspector.alive.delete(124)
+    await vi.advanceTimersByTimeAsync(20)
+    await closing
+    expect(settled).toBe(true)
+  })
+})
--- a/packages/pty/pty-local/tsconfig.json
+++ b/packages/pty/pty-local/tsconfig.json
@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../pty"
+    },
+    {
+      "path": "../../sandbox/sandbox"
+    },
+    {
+      "path": "../../sandbox/sandbox-policy"
+    }
+  ]
+}