docs(proposals): the Terminal tab, a shell in each coding agent's sandbox: Dean's decisions, the new-terminal rules, and the architecture

Merged
DA
5d ago
+1085-0

Summary

The Terminal tab's proposal and architecture, as Dean decided them on 2026-10-14. Docs only; no behavior change.

  • docs/proposals/terminal-tab.md: Dean's decisions and the round-3 "New terminal: the rules" table (approved: "Terminal - looks good to me"). A terminal belongs to one coding agent's sandbox, never the plan. It connects on demand and disconnects after 5 minutes without typing. There's no cap. A stopped sandbox resumes only on a click. GitHub stays live while a terminal is connected, and the agent is not told.
  • docs/proposals/terminal-architecture.md: components, data flows, session-replay masking, where terminal output may and may not go, the two AGENTS.md lines Dean approved, risks, costs, and the PR breakdown the stack below follows.

Design show (static mocks on the app's compiled CSS): https://stage-w2158.conductor.show/ (round 3; earlier rounds linked from it).

This PR is the base of the terminal stack: web PRs 1ā€“3 (lease + lifecycle, tmux + routes, the WebSocket relay) and host PR 4 follow, and desktop PRs 5ā€“9 come from a parallel worker.

Evidence

  • Platform-independent checks: pnpm check:affected (docs only).
  • macOS Electron verification (./scripts/verify.sh): not run. Docs only.

Visual evidence

Not applicable (docs). The mocks are linked above.

Invariants

  • ./scripts/check.sh green; renderer/UI PRs also ./scripts/verify.sh with evidence inspected. (CI)
  • JSON Schema goldens unchanged.
  • Every behavior change has, in this PR, the test that fails without it; no change-detector test added. (No behavior change.)
  • Gateway envelope goldens unchanged.
  • No new as type assertion outside the allowlisted files.
  • No Effect.runPromise/runSync/runFork outside the runtime edges.
  • No new raw async primitives.
  • No discarded Effect, Stream, or Layer.
  • Test count unchanged.
  • No hand-rolled file replaced.
  • No CLAUDE.md/AGENTS.md sentence names a changed part.
  • PRIVACY.md unchanged.
  • Package deps unchanged.

šŸ¤– Generated with Claude Code

Devin Review

Summary by cubic

Adds the proposal and architecture for a Terminal tab in each coding agent's sandbox, recording Dean's decisions from 2026-10-14. Docs only; no behavior change. The latest commits fix the host contract (PR 4) for the desktop PRs: the terminal acts, the refusals they answer, the MessagePort messages, and the connection states.

  • docs/proposals/terminal-tab.md records the approved round-3 rules: a terminal belongs to one coding agent's sandbox, connects on demand, and disconnects after 5 minutes without typing. There is no cap; a stopped sandbox resumes only on a click.
  • docs/proposals/terminal-architecture.md covers components, data flows, session-replay masking, where terminal bytes may and may not go, the two approved AGENTS.md lines, risks, costs, and the PR breakdown for the stack below.
  • This PR is the base of the terminal stack: web PRs 1ā€“3 (lease + lifecycle, tmux + routes, the WebSocket relay) and host PR 4 follow; desktop PRs 5ā€“9 come from a parallel worker.