feat: headless execute, session baseDir, env injection, and run command

[jesse23]

Summary

Four new features building on the existing POST /s/:id/execute endpoint, each with a full ADR:

• Execute resilience (ADR 027): server never crashes on a bad agent tool call — child.on('error') handler, done flag, and uncaughtException/unhandledRejection guards; structured { exit, error, code } exit line so agents can distinguish spawn failure from command failure without parsing stderr
• Session base directory (ADR 028): POST /api/sessions accepts baseDir (absolute path); PTY shell and headless execute commands both start in that directory; CLI webtty go [id] --dir <path> resolves and forwards it
• Env injection (ADR 030): env field in ~/.config/webtty/config.json (same contract as ~/.claude/settings.json) — merged over process.env and injected into both PTY shells and execute commands; TERM/COLORTERM always win for PTY spawns
• webtty run command (ADR 029): webtty run <id> starts the server + session + PTY via transient WebSocket — no browser; webtty run <id> <cmd> [args...] drives POST /s/:id/execute directly from the terminal, streaming stdout/stderr and forwarding exit code

Also includes:

• Spec + ADR renames: server.pipe.md → headless-execute.md, 026.server.pipe.md → 026.server.headless-execute.md
• bun run dev script for running from source without a build step

Test plan

• bun test — 229 pass, 0 fail
• webtty run myproject — starts server + session + PTY, prints URL, no browser opens
• webtty run myproject echo hello — streams "hello" to stdout, exits 0
• webtty run myproject __no_such_cmd__ — prints ENOENT error, exits 1
• webtty go myproject --dir /tmp — PTY shell starts in /tmp
• POST /api/sessions with invalid baseDir — returns 400
• env: { "GITLAB_HOST": "..." } in config — var present in PTY shell and execute commands

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds multiple “headless + session-scoped execution” capabilities to webtty by extending session creation to carry a working directory, injecting config-defined environment variables into spawned processes, hardening the execute endpoint against spawn failures, and introducing a webtty run CLI for browserless operation.

Changes:

• Add baseDir to sessions and ensure PTY + execute spawns run with cwd: session.baseDir.
• Add config.env and inject it into PTY spawns and POST /s/:id/execute.
• Add execute resilience (child.on('error'), done flag, server-level rejection guards) and new CLI webtty run.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/server/websocket.ts	Pass session.baseDir and config.env into PTY spawn.
src/server/session.ts	Store baseDir on sessions and include it in session JSON.
src/server/routes.ts	Accept/validate baseDir on session creation; inject env + cwd for execute; add spawn error handling.
src/server/routes.test.ts	Add coverage for execute spawn failure (ENOENT) emitting structured exit line.
src/server/index.ts	Add process-level error guards and catch unhandled route promise rejections.
src/pty/node.ts	Thread cwd and injected env into node-pty spawn.
src/pty/index.ts	Extend spawnForSession to accept cwd and injected env.
src/pty/index.test.ts	Update spawnForSession tests for new parameters.
src/pty/bun.ts	Thread cwd and injected env into Bun spawn.
src/config.ts	Add env to config schema, defaults, and parsing/validation.
src/cli/index.ts	Add run command; add global --dir parsing; adjust go aliases.
src/cli/commands.ts	Implement cmdRun (warm-up PTY via WS, or headless execute streaming).
package.json	Point webtty script to source entry for dev; add webtty:prod for dist CLI.
docs/specs/webtty.md	Document baseDir on session creation.
docs/specs/headless-execute.md	Update ADR link + mark execute and resilience items.
docs/specs/config.md	Document env injection feature.
docs/specs/cli.md	Document webtty run feature.
docs/adrs/030.config.env-inject.md	ADR for config-based environment injection.
docs/adrs/029.cli.exec.md	ADR for new webtty run command behavior.
docs/adrs/028.session.base-dir.md	ADR for session baseDir plumbing and validation.
docs/adrs/027.server.execute-resilience.md	ADR for execute hardening + structured spawn-failure exit line.
docs/adrs/026.server.headless-execute.md	Update spec link after spec rename.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.