pty-architecture

name	pty-architecture
description	PTY-based multi-session architecture for Code Quest. Covers three-layer design, node-pty spawn config, and worktree isolation. Use when implementing or modifying session management, PTY spawning, or terminal integration.

PTY Architecture

Three-Layer Design

React UI (xterm.js) ←→ Socket.IO ←→ Battle Server (node-pty) ←→ Claude CLI

• UI Layer: xterm.js renders terminal output, Socket.IO for real-time events
• Server Layer: BattleBridge manages PTY sessions, OutputParser converts stream-json to events
• CLI Layer: Each session = independent PTY process running Claude CLI

Key Design Decisions

Why node-pty over child_process.spawn?

Feature	node-pty	child_process
ANSI colors	Full support	Claude disables colors
Terminal resize	pty.resize()	Not supported
Session isolation	Simple per-process	Complex

PTY Spawn Config

spawn(command, args, {
  name: 'xterm-256color',
  cols: 120, rows: 30,
  cwd: workingDir,
  env: { ...process.env, TERM: 'xterm-256color', FORCE_COLOR: '1', COLORTERM: 'truecolor' }
});

Circular Buffer (10KB)

Output buffer capped at 10KB, sliced to last 5KB on overflow. Prevents memory leaks in long sessions while keeping recent output for late-joining viewers.

Graceful Shutdown

SIGTERM → wait 5s → SIGKILL. Allows CLI to save state before forced termination.

Worktree Isolation

Worktree battles use isolated cwd paths (e.g., /worktrees/feature-branch), preventing concurrent sessions from conflicting on the same working directory.

Troubleshooting

• posix_spawnp failed: chmod +x node_modules/node-pty/build/Release/spawn-helper
• No ANSI colors: Ensure TERM=xterm-256color and FORCE_COLOR=1 in env
• Zombie process: Use SIGTERM→SIGKILL pattern with 5s timeout