feat: Agent Terminal v1 — Week 4 design gap closure (#7)

* docs: add week 3 status and week 4 plan

Update stale design docs to reflect shipped Week 3 work, add a formal Week 3 status record, and add a concrete Week 4 plan focused on the remaining design-parity gaps.\n\n---\n_Generated with [`mux`](https://github.com/coder/mux) • Model: `openai:gpt-5.4` • Thinking: `xhigh`_

* Add file input support to type and paste

* Add cursor position render waits

* Add shared CLI context and exit-code mapping

* Align CLI integration exit codes

* Add create env, term, name, and shell options

* Extend session status state machine

* Harden session lifecycle reconciliation

* Update CLI handlers for destroyed sessions

* Fix wait --wait-for-exit terminal guard order

* test: cover failed and destroyed session states

* Fix lint violations in lifecycle changes

* test: accept terminal export status after force destroy

* feat(renderer): add profile hash and snapshot metadata contracts

* style: format files for prettier compliance

* Add screenshot metadata to backend and CLI

* Enrich export metadata headers

* style: format enriched metadata files for prettier compliance

* Add snapshot include-scrollback flag

* Handle snapshot scrollback RPC option

* Add ghostty-web snapshot scrollback support

* Add snapshot scrollback test coverage

* style: format files for prettier compliance

* Fix snapshot test mock parameter types

* style: fix formatting after WS1+WS2+WS3 integration

* docs: sync Week 4 status and remaining gaps

* test: add unicode-grid fixture app

* test: add scrollback-demo fixture app

* test: add E2E tests for unicode-grid and scrollback-demo

* dogfood: add week4-cli-parity proof bundle

* dogfood: add week4-unicode-review proof bundle

* dogfood: add week4-scrollback-review proof bundle

* dogfood: add week4-failure-recovery proof bundle

* style: fix dogfood formatting

* docs: mark week 4 fixtures as shipped

* Add March 22 dogfood proof bundles

* Add March 22 color and alt-screen dogfood artifacts

* Add dogfood artifacts for unicode and scrollback scenarios

* Add 2026-03-22 dogfood CLI artifacts

* Handle wait render host-unreachable fallback

* Preserve session creation dimensions for replay

* Fix scrollback snapshot viewport normalization

* Recreate renderer backend on replay resize

* Fix lint errors in viewport normalization changes

* Update integration tests for viewport normalization

* style: fix formatting and rename mistyped dogfood files

* style: rename remaining mistyped dogfood files to .txt

* style: format dogfood JSON files

* style: format unicode dogfood files

* style: format all dogfood artifacts

* style: rename all non-JSON dogfood files to .txt

* docs: add 20260323 dogfood bugfix evidence

* Fix review findings for input handling and docs

---------

Co-authored-by: Mux <mux@local>

Author: ThomasK33

README.md

@@ -1,16 +1,85 @@
 # agent-terminal
 
-Node/TypeScript CLI scaffold.
+`agent-terminal` is a Node/TypeScript CLI for launching, controlling, inspecting, and exporting reviewable terminal sessions.
+It is built for agent workflows that need both semantic state and visual artifacts from live or exited TUIs.
 
-## Setup
+## Quick start
 
-1. `mise install`
-2. `mise run bootstrap`
-3. `mise run ci`
+```bash
+mise install
+npm ci
+npx playwright install chromium
+npm run build
 
-## CI
+SESSION_ID=$(node dist/cli/main.js create --json --name demo | jq -r '.data.sessionId')
+node dist/cli/main.js type "$SESSION_ID" 'echo hello from agent-terminal'
+node dist/cli/main.js send-keys "$SESSION_ID" Enter
+node dist/cli/main.js inspect "$SESSION_ID" --json
+node dist/cli/main.js destroy "$SESSION_ID"
+```
 
-- GitHub Actions uses `mise` as the canonical entrypoint for tool setup and quality gates.
-- The committed workflow in `.github/workflows/ci.yml` is hand-curated. `mise generate github-action` is useful as a scaffold, but the checked-in file is the maintained source of truth because it includes repo-specific triggers, bootstrap behavior, and step-level logs.
-- CI uses `mise run bootstrap-ci` for deterministic `npm ci` installs, then explicitly runs `npx playwright install chromium` so renderer smoke coverage is exercised on GitHub Actions.
-- For v1, CI intentionally follows the major-version tool pins declared in `mise.toml` (`node = "24"`, `python = "3"`). This repo does not commit a `mise.lock` yet.
+## Feature highlights
+
+- Full session lifecycle management: create, inspect, list, wait, destroy, and garbage-collect.
+- Semantic snapshots for structured or text inspection, including optional scrollback capture.
+- Renderer-backed screenshots and replay exports for reviewable visual evidence.
+- Recording export to asciicast (`.cast`) or WebM for artifact bundles.
+- Failure recovery via reconciliation, stale-session cleanup, and retained manifests/artifacts.
+
+## CLI-wide flags
+
+- `--home <path>`: override the agent-terminal home directory.
+- `--timeout-ms <n>`: apply a shared CLI timeout budget in milliseconds.
+- `--no-color`: disable ANSI color in human-readable output.
+- `--json`: available on user-facing commands to emit structured command envelopes.
+
+## Commands
+
+- `version`: print the CLI version.
+- `doctor`: validate local environment requirements.
+- `create [command...]`: create a session and launch the requested command or shell.
+- `list`: list sessions, optionally including exited ones.
+- `inspect <session-id>`: inspect manifest state and artifact metadata for a session.
+- `destroy <session-id>`: tear down a session, with optional forced shutdown.
+- `gc`: remove stale or old sessions.
+- `type <session-id> [text]`: type text into a session.
+- `paste <session-id> [text]`: paste text into a session.
+- `mark <session-id> <label>`: add a marker event to a session timeline.
+- `send-keys <session-id> <keys...>`: send key sequences such as `Enter` or `Ctrl+C`.
+- `resize <session-id>`: resize the PTY dimensions.
+- `signal <session-id> <signal>`: send a POSIX signal to the session child process.
+- `snapshot <session-id>`: capture a semantic snapshot of terminal contents.
+- `screenshot <session-id>`: capture a rendered PNG screenshot.
+- `record export <session-id>`: export replay artifacts as asciicast or WebM.
+- `wait <session-id>`: wait for exit, idleness, text, regex, cursor, or stable-screen conditions.
+
+## Development setup
+
+```bash
+mise install
+npm ci
+npx playwright install chromium
+```
+
+Useful shortcuts:
+
+- `mise run bootstrap`: install npm dependencies and Chromium in one step.
+- `npm run cli -- --help`: inspect the CLI locally without building.
+
+## Verification
+
+```bash
+npm run verify
+```
+
+That runs formatting, linting, typechecking, unit/e2e tests, and the production build.
+
+## Design docs
+
+Design and implementation notes live under `design/`, especially `design/20260319_agent-terminal-v1/`.
+
+## Repository notes
+
+- CI uses `mise` for tool provisioning and quality-gate entrypoints.
+- Chromium is required locally for screenshot and replay export coverage.
+- Dogfood proof bundles and validation notes live under `dogfood/` and `design/`.

WEEK2-GAPS.md

@@ -1,29 +1,53 @@
-# Week 2 remaining gaps
+# Remaining gaps after Week 4
 
-The Week 2 renderer-backed inspection slice is complete, but the following work is still intentionally out of scope or not yet delivered:
+> Historical note: this file keeps its original filename (`WEEK2-GAPS.md`) because earlier design docs and proof bundles already reference it. Its contents now describe the current post-Week-4 delta rather than the original Week 2-only gap list.
 
-## Export and packaging
+Week 1 control-plane work, Week 2 renderer-backed inspection, Week 3 export / retention, and the core Week 4 CLI / artifact / lifecycle hardening have all landed. The remaining work is now concentrated in the areas below.
 
-- **Asciicast export** is not implemented yet.
-- **WebM video export** is not implemented yet.
-- **MCP wrapper** is not implemented yet.
+## Post-Week-4 remaining gaps
 
-## Renderer backends and platform coverage
+### CLI contract and config parity
 
-- **Native renderer adapters** are not implemented yet; the current slice is centered on the reference `ghostty-web` path.
-- **Cross-platform rendering parity** is not guaranteed yet.
+- **`--log-level`** is still not implemented.
+- **Global render-profile selection** is still partial; `screenshot` exposes a command-local `--profile`, but there is not yet a broader global/profile-default story.
+- **`--idle-timeout-ms`** is still not implemented for `create`.
+- **`--append-newline`** is still not implemented for `type`.
+- **Config-file loading** is still not implemented, and the broader env/config precedence story from `02-cli-contract.md` remains incomplete.
+- **Full envelope/result-shape parity** with every CLI-contract example is still incomplete.
 
-## Input and topology
+### Artifact fidelity and metadata
 
-- **Mouse input support** is not implemented yet.
-- **Remote/network sessions** are not implemented yet.
+- **Per-cell style metadata** is still not implemented.
+- **The fuller `SnapshotCell` / expanded snapshot schema** from `03-rendering-and-artifacts.md` is still not implemented.
+- **Bundled deterministic font assets** are still not implemented; built-in profiles still rely on generic `monospace`.
+- **Full replay timing controls** are still not exposed as a complete reviewer-facing CLI surface.
 
-## Fidelity and determinism
+### Failure semantics and recovery
 
-- **Screenshot pixel-perfect determinism** is not guaranteed; font rendering can still vary by environment.
-- **Scrollback in snapshots** is not implemented; snapshots currently report the visible viewport only.
-- **Cursor blink animation in screenshots** is not captured; screenshots represent a static frame.
+- **Renderer/host recovery proof** is still lighter than the main event-log/offline-replay story.
+- **Broader failure storytelling** is still incomplete; the repo now records `failed` plus `failureReason`, but the docs still sketch richer future distinctions between abnormal child exit, host failure, and renderer failure.
 
-## Security & Isolation
+### Fixture suite and dogfooding
 
-- **Renderer CSP trade-off** currently allows `unsafe-inline`/`unsafe-eval` for the ghostty-web harness because the localhost-only loopback renderer still needs inline bootstrap code and WASM eval support in current browsers.
+- **Local proof-bundle review helper/page** is still not implemented.
+
+### Platform and future-scope work
+
+- **Native renderer adapters** are still not implemented.
+- **Mouse input support** is still not implemented.
+- **Remote/network sessions** are still not implemented.
+- **MCP wrapper** is still not implemented.
+- **Cross-platform rendering parity** is still not guaranteed, and Windows remains behind the design’s intended tier-2 shape.
+- **Renderer CSP trade-off** still exists; the localhost-only ghostty-web harness still needs `unsafe-inline` / `unsafe-eval` today.
+
+## Recommended next step
+
+The next milestone should focus on the still-open parity and validation work rather than a brand-new feature family:
+
+1. finish CLI/config parity,
+2. finish snapshot/rendering fidelity,
+3. finish the remaining validation/tooling work around local proof-bundle review,
+4. strengthen failure/recovery validation,
+5. then continue broader native/platform future work.
+
+See `design/20260319_agent-terminal-v1/10-week-4-status.md` for the detailed Week 4 status record and `design/20260319_agent-terminal-v1/09-week-4-plan.md` for the original Week 4 plan.

design/20260319_agent-terminal-v1.md

@@ -19,18 +19,20 @@ It is designed to let an agent:
 
 This design intentionally describes a **general product**, not a Mux-specific implementation. A future Mux integration should consume `agent-terminal` as an external CLI/runtime rather than baking Mux-specific assumptions into the design.
 
-## Current shipped status (2026-03-21)
+## Current shipped status (2026-03-22)
 
-The repository now ships the first renderer-backed vertical slice of this design:
+The repository now ships the first three milestones of this design:
 
 - long-lived session hosts,
 - PTY control and append-only event logs,
 - renderer-backed `snapshot` and `wait`,
 - deterministic `screenshot`,
-- artifact manifests,
+- `record export --format asciicast`,
+- `record export --format webm`,
+- artifact manifests and `gc`,
 - and proof bundles under `dogfood/`.
 
-Replay export artifacts such as asciicast and video remain part of the design direction, but they are still future work rather than shipped functionality.
+The implementation is now beyond the original Week 2 slice, but it is **not** yet fully done against the broader v1 design. The main remaining gaps are CLI-contract parity, richer snapshot / screenshot fidelity, missing fixture scenarios, and a few failure-state / platform hardening items. See [08-week-3-status.md](./20260319_agent-terminal-v1/08-week-3-status.md), [09-week-4-plan.md](./20260319_agent-terminal-v1/09-week-4-plan.md), and [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md) for the current follow-on work.
 
 ## Executive summary
 
@@ -194,6 +196,8 @@ This design file is the entry point. Detailed supporting docs live in `design/20
 - [05-dogfooding-and-validation.md](./20260319_agent-terminal-v1/05-dogfooding-and-validation.md)
 - [06-roadmap-and-week-1-plan.md](./20260319_agent-terminal-v1/06-roadmap-and-week-1-plan.md)
 - [07-week-2-plan.md](./20260319_agent-terminal-v1/07-week-2-plan.md)
+- [08-week-3-status.md](./20260319_agent-terminal-v1/08-week-3-status.md)
+- [09-week-4-plan.md](./20260319_agent-terminal-v1/09-week-4-plan.md)
 
 ## High-level architecture
 

design/20260319_agent-terminal-v1/02-cli-contract.md

@@ -684,3 +684,22 @@ The CLI contract is complete when:
 - key grammar is canonicalized and tested,
 - `doctor` catches missing browser/render dependencies,
 - and the CLI can be driven end-to-end by a non-interactive agent process.
+
+## 24. Week 4 implementation status
+
+As of 2026-03-22, Week 4 closed several of the highest-value CLI contract gaps:
+
+- shipped global root flags `--home`, `--timeout-ms`, and `--no-color` via a shared command context,
+- shipped differentiated process exit codes `0` through `8` via structured error-to-exit-code mapping,
+- shipped `create` options `--env`, `--term`, `--name`, and `--shell`,
+- shipped file-backed input for `type` and `paste` via `--file`,
+- and shipped renderer-backed cursor waits via `wait --cursor-row` / `--cursor-col`.
+
+The following contract items remain future work:
+
+- `--log-level`,
+- a true global `--profile` override surface,
+- `--idle-timeout-ms`,
+- `--append-newline`,
+- config-file loading and the broader config/env precedence story beyond `AGENT_TERMINAL_HOME`,
+- and full JSON envelope/result-shape alignment with every example in this contract.

design/20260319_agent-terminal-v1/03-rendering-and-artifacts.md

@@ -31,30 +31,33 @@ That distinction must remain explicit in both code and documentation.
 
 V1 should support four artifact classes.
 
-| Artifact          | Purpose                                              | Required in v1 |
-| ----------------- | ---------------------------------------------------- | -------------- |
-| Semantic snapshot | Structured screen state for reasoning and assertions | Yes            |
-| Screenshot PNG    | Visual verification of layout, color, and wrapping   | Yes            |
-| Asciicast         | Portable terminal replay artifact                    | Not yet shipped |
-| Replay video      | Reviewer-friendly visual playback                    | Not yet shipped |
+| Artifact          | Purpose                                              | Required in v1 | Shipped as of 2026-03-22 |
+| ----------------- | ---------------------------------------------------- | -------------- | ------------------------ |
+| Semantic snapshot | Structured screen state for reasoning and assertions | Yes            | Yes                      |
+| Screenshot PNG    | Visual verification of layout, color, and wrapping   | Yes            | Yes                      |
+| Asciicast         | Portable terminal replay artifact                    | Yes            | Yes                      |
+| Replay video      | Reviewer-friendly visual playback                    | Yes            | Yes                      |
 
-## Current implementation status (2026-03-21)
+## Current implementation status (2026-03-22)
 
-The current Week 2 implementation ships the first two artifact classes from this design:
+The current implementation now ships all four artifact classes from this design:
 
 - semantic snapshots,
-- and screenshot PNGs.
+- screenshot PNGs,
+- asciicast export,
+- and replay-video export.
 
-It does **not** yet ship asciicast export or replay video export; those remain deferred and are tracked in `WEEK2-GAPS.md`.
-
-The current renderer path is:
+The current renderer/export path is:
 
 - host-prepared replay input,
 - lazy `ghostty-web` boot in headless Chromium,
 - viewport-scoped semantic extraction,
 - deterministic screenshot capture,
+- deterministic replay export to asciicast and WebM,
 - and manifest-backed artifact storage under `artifacts/`.
 
+Remaining follow-on work is now mostly about fidelity and design parity rather than missing artifact classes. Scrollback snapshots and richer screenshot/export metadata now ship; the biggest open items are per-cell style metadata, bundled deterministic font assets, the fuller `SnapshotCell` surface, and more explicit replay timing controls. These are tracked in [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md) and [09-week-4-plan.md](./09-week-4-plan.md).
+
 ## 4. Canonical replay model
 
 Everything visual should be reproducible from:
@@ -519,3 +522,19 @@ This area is complete only when:
 - replay video export exists and is reviewable,
 - every artifact is manifest-backed and hash-stamped,
 - and renderer crashes can be repaired from replay without losing the session.
+
+## 18. Week 4 implementation status
+
+As of 2026-03-22, Week 4 materially narrowed the rendering/artifact delta:
+
+- shipped scrollback-aware snapshots through `snapshot --include-scrollback` / `includeScrollback`,
+- shipped screenshot metadata enrichment (`rendererBackend`, `pixelWidth`, `pixelHeight`, `sha256`, and `renderProfileHash`),
+- shipped render-profile hashing via `hashProfile(...)`,
+- and shipped richer asciicast/WebM export metadata for offline review.
+
+The remaining design-level follow-ons are:
+
+- per-cell styling and the fuller `SnapshotCell` contract,
+- a bundled deterministic font asset instead of host `monospace`,
+- the broader snapshot schema sketched earlier in this document,
+- and a fuller replay-timing option surface for reviewer-facing video export.

design/20260319_agent-terminal-v1/05-dogfooding-and-validation.md

@@ -6,25 +6,51 @@ It is intentionally prescriptive.
 
 A follow-up AI coding agent should treat this file as the minimum review protocol, not optional guidance.
 
-## Current shipped state (2026-03-21)
+## Current shipped state (2026-03-22)
 
-This document still describes the *target* dogfooding protocol, but the current shipped product only supports a subset of the artifact expectations below.
+This document still describes the broader dogfooding target, but the repository now ships the full core artifact set needed for review bundles.
 
 Shipped today:
 
 - JSON command outputs,
-- semantic snapshots,
-- PNG screenshots,
+- semantic snapshots, including optional scrollback capture,
+- PNG screenshots with richer metadata,
+- `.cast` export,
+- replay video export,
 - artifact manifests,
 - and notes / proof bundles under `dogfood/`.
 
-Not yet shipped:
+The remaining gaps are now mostly about local review ergonomics rather than missing artifact classes. The dedicated `unicode-grid` and `scrollback-demo` fixtures, their matching E2E coverage, and the Week 4 proof bundles are now shipped; the biggest open item is a local bundle review helper.
 
-- `.cast` export,
-- replay video export,
-- and some of the richer fixture scenarios listed below.
+Read the remainder of this file as the broader validation target and checklist for closing those remaining gaps.
+
+## Week 4 coverage
+
+As of 2026-03-22, the repo ships the deterministic `unicode-grid` and `scrollback-demo` fixtures plus dedicated E2E coverage in `test/e2e/unicode-grid.test.ts` and `test/e2e/scrollback-demo.test.ts`.
+
+The repo also now has four Week 4 proof bundles that cover the shipped gap-closing work:
+
+- `dogfood/20260322-week4-cli-parity/` proves CLI-contract parity and result-shape behavior,
+- `dogfood/20260322-week4-failure-recovery/` proves failure retention and recovery evidence,
+- `dogfood/20260322-week4-scrollback-review/` proves scrollback capture and replay review,
+- and `dogfood/20260322-week4-unicode-review/` proves unicode/width review coverage.
+
+Bugfix verification bundles also ship alongside that Week 4 coverage:
+
+- `dogfood/20260323-bugfix-resize/` proves post-resize snapshot/screenshot recovery,
+- and `dogfood/20260323-bugfix-scrollback/` proves scrollback viewport normalization.
+
+Earlier proof bundles remain relevant context:
+
+- `dogfood/20260321-post-hardening-smoke/` revalidates live inspect/wait/snapshot/screenshot/doctor flows,
+- `dogfood/20260321-week3-renderer-complete/` proves live and post-exit snapshot/screenshot/export plus GC,
+- `dogfood/20260321-week3-crash-retention/` proves abnormal-exit evidence retention,
+- `dogfood/20260322-global-cli-context/` proves `--home`, `--no-color`, and exit-code differentiation for missing sessions,
+- and `dogfood/20260322-lazyvim-scenario/` demonstrates real-world TUI driving plus screenshot / asciicast / WebM review artifacts.
+
+The main remaining validation gap is:
 
-Read the remainder of this file as the broader validation target, not a claim that every artifact class is already implemented.
+- there is still no local proof-bundle review helper/page.
 
 ## 1. Dogfooding goals