diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 8a5de01..2953268 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,8 +1,8 @@
 name: Release
 
 # Keep this workflow hand-curated. The prepare job produces the verified tarball,
-# checksum, and metadata that future publish steps (for example npm) should
-# reuse instead of rebuilding from scratch.
+# checksum, and metadata that downstream publish steps on GitHub Releases and
+# npm should reuse instead of rebuilding from scratch.
 on:
   workflow_dispatch:
     inputs:
@@ -183,6 +183,7 @@ jobs:
         shell: bash
         env:
           RELEASE_TAG: ${{ needs.prepare-release.outputs.release_tag }}
+          PACKAGE_NAME: ${{ needs.prepare-release.outputs.package_name }}
           PACKAGE_VERSION: ${{ needs.prepare-release.outputs.package_version }}
           TARBALL_FILENAME: ${{ needs.prepare-release.outputs.tarball_filename }}
           CHECKSUM_FILENAME: ${{ needs.prepare-release.outputs.checksum_filename }}
@@ -193,7 +194,14 @@ jobs:
           tarball_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/releases/download/${RELEASE_TAG}/${TARBALL_FILENAME}"
 
           cat > "$RELEASE_NOTES_FILE" <<EOF
-          Install the verified tarball asset from this release instead of relying on the npm registry or a git dependency build:
+          Install from npm once the trusted publish job for this workflow completes:
+
+          ```bash
+          npm install -g "${PACKAGE_NAME}@${PACKAGE_VERSION}"
+          agent-tty version --json
+          ```
+
+          If you need a registry-independent fallback, install the verified tarball asset from this release directly:
 
           ```bash
           VERSION=${PACKAGE_VERSION}
@@ -201,7 +209,7 @@ jobs:
           TARBALL_URL=${tarball_url}
 
           npm install -g "$TARBALL_URL"
-          agent-terminal version --json
+          agent-tty version --json
           ```
 
           For private releases or environments that require authenticated downloads, fetch the asset first and then install locally:
@@ -209,12 +217,12 @@ jobs:
           ```bash
           gh release download "${RELEASE_TAG}" --repo "${GITHUB_REPOSITORY}" --pattern "${TARBALL_FILENAME}"
           npm install -g "./${TARBALL_FILENAME}"
-          agent-terminal version --json
+          agent-tty version --json
           ```
 
           SHA-256 checksum: `${CHECKSUM_SHA256}` (see `${CHECKSUM_FILENAME}` for the portable checksum file).
 
-          This workflow intentionally stops at the verified GitHub Release asset. A future npm-publish job should depend on the prepare-release outputs and reuse this tarball instead of rebuilding it.
+          This workflow prepares one verified tarball and reuses it across GitHub Release assets and npm publishing instead of rebuilding it.
           EOF
 
       - name: Create or update GitHub Release
@@ -258,10 +266,54 @@ jobs:
               "${create_flags[@]}"
           fi
 
-  # Future follow-up:
-  # publish-npm:
-  #   needs: prepare-release
-  #   runs-on: ubuntu-latest
-  #   steps:
-  #     - name: Publish verified tarball to npm
-  #       run: echo 'Reserved for a future npm publish job.'
+  publish-npm:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: prepare-release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download verified release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: release-assets-${{ needs.prepare-release.outputs.release_tag }}
+          path: ${{ runner.temp }}/release-assets
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish verified tarball to npm
+        shell: bash
+        env:
+          PACKAGE_NAME: ${{ needs.prepare-release.outputs.package_name }}
+          PACKAGE_VERSION: ${{ needs.prepare-release.outputs.package_version }}
+          TARBALL_PATH: ${{ runner.temp }}/release-assets/${{ needs.prepare-release.outputs.tarball_filename }}
+        run: |
+          set -euo pipefail
+          if [[ ! -f "$TARBALL_PATH" ]]; then
+            echo "Release tarball missing: $TARBALL_PATH" >&2
+            exit 1
+          fi
+
+          publish_args=()
+          if [[ "$PACKAGE_NAME" == @* ]]; then
+            publish_args+=(--access public)
+          fi
+          if [[ "$PACKAGE_VERSION" == *-* ]]; then
+            dist_tag="${PACKAGE_VERSION#*-}"
+            dist_tag="${dist_tag%%.*}"
+            if [[ -z "$dist_tag" ]]; then
+              echo "Unable to derive prerelease dist-tag from $PACKAGE_VERSION" >&2
+              exit 1
+            fi
+            publish_args+=(--tag "$dist_tag")
+            echo "Publishing prerelease $PACKAGE_NAME@$PACKAGE_VERSION with dist-tag $dist_tag"
+          else
+            echo "Publishing stable $PACKAGE_NAME@$PACKAGE_VERSION with dist-tag latest"
+          fi
+
+          npm publish "$TARBALL_PATH" "${publish_args[@]}"
diff --git a/AGENTS.md b/AGENTS.md
index 940aec1..0a2d907 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,7 +2,7 @@ You are an experienced, pragmatic software engineering AI agent. Do not over-eng
 
 # Project Overview
 
-`agent-terminal` is a CLI-first terminal automation tool for AI agents and humans. It creates long-lived PTY-backed sessions, exposes machine-friendly commands to control them, and produces inspectable artifacts such as semantic snapshots, PNG screenshots, asciicast recordings, and WebM exports.
+`agent-tty` is a CLI-first terminal automation tool for AI agents and humans. It creates long-lived PTY-backed sessions, exposes machine-friendly commands to control them, and produces inspectable artifacts such as semantic snapshots, PNG screenshots, asciicast recordings, and WebM exports.
 
 The current implementation is a TypeScript/Node v1 with these main building blocks:
 
@@ -13,7 +13,7 @@ The current implementation is a TypeScript/Node v1 with these main building bloc
 - **Vitest, ESLint, Prettier, and TypeScript** for quality gates.
 - **mise** as the canonical task runner in CI.
 
-Session state is stored under `~/.agent-terminal` by default. In tests and automation, prefer an isolated absolute `AGENT_TERMINAL_HOME` instead of writing into the real home directory.
+Session state is stored under `~/.agent-tty` by default. In tests and automation, prefer an isolated absolute `AGENT_TTY_HOME` instead of writing into the real home directory.
 
 # Reference
 
@@ -105,12 +105,12 @@ bash dogfood/generate-week3-bundles.sh
 find dogfood -type f -name 'commands.sh' | sort
 ```
 
-Development server: **none**. This is a CLI project, so iterative development usually means running `npx tsx src/cli/main.ts <command>` against an isolated `AGENT_TERMINAL_HOME`.
+Development server: **none**. This is a CLI project, so iterative development usually means running `npx tsx src/cli/main.ts <command>` against an isolated `AGENT_TTY_HOME`.
 
 # Patterns
 
 - **Do use `--json` for automation and prefer direct CLI invocation (`npx tsx src/cli/main.ts ...`) while developing.** Tests and design docs assume automation consumers read JSON envelopes. **Do not** scrape human-readable output when a JSON mode exists, and do not rely on noisy `npm run` wrappers when you need machine-parseable JSON.
-- **Do isolate session homes in tests.** Follow the pattern in `test/helpers.ts` and `test/e2e/helpers.ts`: create a temp directory, set absolute `AGENT_TERMINAL_HOME`, clean it up, and destroy any surviving sessions. **Do not** let tests mutate `~/.agent-terminal`.
+- **Do isolate session homes in tests.** Follow the pattern in `test/helpers.ts` and `test/e2e/helpers.ts`: create a temp directory, set absolute `AGENT_TTY_HOME`, clean it up, and destroy any surviving sessions. **Do not** let tests mutate `~/.agent-tty`.
 - **Do fail fast with assertions and schemas.** Existing code uses `invariant()`, `assertString()`, and `.safeParse()`/`.strict()` heavily. **Do not** silently coerce invalid paths, session IDs, or manifest data.
 - **Do preserve the event-log-as-truth model.** New snapshot, screenshot, wait, or export features should flow through replayable event/state data. **Do not** add one-off state that only live PTY code can see.
 - **Do keep storage writes inside validated helpers.** Path resolution in `src/storage/sessionPaths.ts`, manifest writers, and artifact helpers intentionally guard against path escape and invalid filenames. **Do not** write manifest-like files with ad hoc `fs.writeFile()` logic.
@@ -118,7 +118,7 @@ Development server: **none**. This is a CLI project, so iterative development us
 - **Do update coupled limits together.** `src/host/eventLog.ts` and `src/host/replay.ts` both enforce the 50 MB event-log limit. **Do not** change one without the other.
 - **Do add tests at the right layer.** Small parser/validation changes usually belong in `test/unit`; CLI wiring and temp-home behavior fit `test/integration`; renderer/artifact flows belong in `test/e2e`.
 
-- **Do keep the public `skills/agent-terminal/` artifact binary-first.** The committed public skill and public-facing skill docs must use `agent-terminal ...`, not repo-local `npx`, `tsx`, or `src/cli/main.ts` invocations. When you execute those examples from this source tree, translate them locally to `npx tsx src/cli/main.ts ...`, but do not commit that substitution back into the public skill or README skill-install guidance.
+- **Do keep the public `skills/agent-tty/` artifact binary-first.** The committed public skill and public-facing skill docs must use `agent-tty ...`, not repo-local `npx`, `tsx`, or `src/cli/main.ts` invocations. When you execute those examples from this source tree, translate them locally to `npx tsx src/cli/main.ts ...`, but do not commit that substitution back into the public skill or README skill-install guidance.
 - **Do teach the terminal workflow the public skill is supposed to reinforce.** Prefer `--home`, `--json`, `run`, `wait`, `snapshot`, `screenshot`, and `record export` when writing or maintaining public skill examples. **Do not** teach `tmux`, blind `sleep`, or out-of-band screenshots as the primary workflow.
 
 ## Testing patterns
diff --git a/README.md b/README.md
index 6e6b643..5d7a97f 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,33 @@
-# agent-terminal
+# agent-tty
 
-`agent-terminal` is a Node/TypeScript CLI for launching, controlling, inspecting, and exporting reviewable terminal sessions.
+`agent-tty` 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.
 
 ## Installation
 
-`agent-terminal` currently supports Node `24.x`.
-Today, the supported hosted install path is the GitHub Release tarball asset. npm publication is intentionally not wired yet, and direct git dependency installs remain best-effort because they build from source.
+`agent-tty` currently supports Node `24.x`.
+The recommended hosted install path is the npm package `agent-tty`. GitHub Release tarballs remain the registry-independent fallback, and direct git dependency installs remain best-effort because they build from source.
+
+### npm installation (recommended)
+
+#### Global install from npm
+
+```bash
+PACKAGE_VERSION=<version>
+npm install -g "agent-tty@${PACKAGE_VERSION}"
+agent-tty version --json
+agent-tty --home "$(mktemp -d)" doctor --json
+```
+
+To follow the prerelease channel instead of pinning an exact version, substitute `@beta` (or another dist-tag such as `@rc`) for `@${PACKAGE_VERSION}`.
+
+#### Project-local install from npm
+
+```bash
+PACKAGE_VERSION=<version>
+npm install "agent-tty@${PACKAGE_VERSION}"
+./node_modules/.bin/agent-tty version --json
+```
 
 ### GitHub Release tarball installation
 
@@ -15,11 +36,11 @@ Today, the supported hosted install path is the GitHub Release tarball asset. np
 ```bash
 VERSION=<version>
 RELEASE_TAG="v${VERSION}"
-RELEASE_TGZ="agent-terminal-${VERSION}.tgz"
-TARBALL_URL="https://github.com/coder/agent-terminal/releases/download/${RELEASE_TAG}/${RELEASE_TGZ}"
+RELEASE_TGZ="agent-tty-${VERSION}.tgz"
+TARBALL_URL="https://github.com/coder/agent-tty/releases/download/${RELEASE_TAG}/${RELEASE_TGZ}"
 
 npm install -g "$TARBALL_URL"
-agent-terminal version --json
+agent-tty version --json
 ```
 
 #### Authenticated or private release install
@@ -27,22 +48,22 @@ agent-terminal version --json
 ```bash
 VERSION=<version>
 RELEASE_TAG="v${VERSION}"
-RELEASE_TGZ="agent-terminal-${VERSION}.tgz"
+RELEASE_TGZ="agent-tty-${VERSION}.tgz"
 
-gh release download "$RELEASE_TAG" --repo coder/agent-terminal --pattern "$RELEASE_TGZ"
+gh release download "$RELEASE_TAG" --repo coder/agent-tty --pattern "$RELEASE_TGZ"
 npm install -g "./$RELEASE_TGZ"
-agent-terminal version --json
-agent-terminal --home "$(mktemp -d)" doctor --json
+agent-tty version --json
+agent-tty --home "$(mktemp -d)" doctor --json
 ```
 
 #### Project-local install from a downloaded tarball
 
 ```bash
 VERSION=<version>
-RELEASE_TGZ="./agent-terminal-${VERSION}.tgz"
+RELEASE_TGZ="./agent-tty-${VERSION}.tgz"
 
 npm install "$RELEASE_TGZ"
-./node_modules/.bin/agent-terminal version --json
+./node_modules/.bin/agent-tty version --json
 ```
 
 ### Local tarball build from a source checkout
@@ -55,18 +76,18 @@ npm ci
 npm run pack:private -- --pack-destination "$TARBALL_DIR"
 
 INSTALL_PREFIX=$(mktemp -d)
-npm install -g --prefix "$INSTALL_PREFIX" "$TARBALL_DIR"/agent-terminal-*.tgz
-"$INSTALL_PREFIX"/bin/agent-terminal version --json
-"$INSTALL_PREFIX"/bin/agent-terminal --home "$(mktemp -d)" doctor --json
+npm install -g --prefix "$INSTALL_PREFIX" "$TARBALL_DIR"/*.tgz
+"$INSTALL_PREFIX"/bin/agent-tty version --json
+"$INSTALL_PREFIX"/bin/agent-tty --home "$(mktemp -d)" doctor --json
 ```
 
-`npm run pack:private` always rebuilds `dist/` before packing. Release automation instead uses `npm run pack:release` after the CI-quality build step so GitHub Releases upload the same verified tarball plus a checksum file.
+`npm run pack:private` always rebuilds `dist/` before packing. Release automation instead uses `npm run pack:release` after the CI-quality build step so GitHub Releases and the npm publish job both reuse the same verified tarball plus a checksum file.
 
 ### Git source installation (best-effort)
 
 ```bash
-npm install -g github:coder/agent-terminal
-agent-terminal version --json
+npm install -g github:coder/agent-tty
+agent-tty version --json
 ```
 
 GitHub installs attempt to build from source via npm's `prepare` hook.
@@ -80,11 +101,11 @@ If `doctor --json` reports a missing Playwright browser cache on a fresh machine
 
 ```bash
 AGENT_HOME="$(mktemp -d)"
-agent-terminal --home "$AGENT_HOME" doctor --json
-SESSION_ID=$(agent-terminal --home "$AGENT_HOME" create --json --name demo -- /bin/bash | jq -r '.result.sessionId')
-agent-terminal --home "$AGENT_HOME" run "$SESSION_ID" 'echo hello from agent-terminal' --json
-agent-terminal --home "$AGENT_HOME" snapshot "$SESSION_ID" --format text --json
-agent-terminal --home "$AGENT_HOME" destroy "$SESSION_ID" --json
+agent-tty --home "$AGENT_HOME" doctor --json
+SESSION_ID=$(agent-tty --home "$AGENT_HOME" create --json --name demo -- /bin/bash | jq -r '.result.sessionId')
+agent-tty --home "$AGENT_HOME" run "$SESSION_ID" 'echo hello from agent-tty' --json
+agent-tty --home "$AGENT_HOME" snapshot "$SESSION_ID" --format text --json
+agent-tty --home "$AGENT_HOME" destroy "$SESSION_ID" --json
 ```
 
 ## Documentation map
@@ -105,7 +126,7 @@ agent-terminal --home "$AGENT_HOME" destroy "$SESSION_ID" --json
 
 ## 0.1.0 release focus
 
-`agent-terminal` `0.1.0` is the first release aimed at reliable, isolated, reviewable TUI automation.
+`agent-tty` `0.1.0` is the first release aimed at reliable, isolated, reviewable TUI automation.
 For the explicit shipping contract, see [`RELEASE.md`](./RELEASE.md). For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md).
 Reviewer-facing proof bundles are curated in [`dogfood/CATALOG.md`](./dogfood/CATALOG.md), with current release-signoff evidence in `dogfood/20260326-week9-release-readiness/` and evergreen workflow coverage such as `dogfood/run-command/`.
 
@@ -115,12 +136,12 @@ For setup-heavy TUI automation, prefer an isolated home plus the higher-level `r
 
 ```bash
 AGENT_HOME="$(mktemp -d)"
-agent-terminal --home "$AGENT_HOME" doctor --json
-SESSION_ID=$(agent-terminal --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
-agent-terminal --home "$AGENT_HOME" run "$SESSION_ID" 'npm install'
-agent-terminal --home "$AGENT_HOME" wait "$SESSION_ID" --text 'ready'
-agent-terminal --home "$AGENT_HOME" screenshot "$SESSION_ID"
-agent-terminal --home "$AGENT_HOME" record export "$SESSION_ID" --format webm
+agent-tty --home "$AGENT_HOME" doctor --json
+SESSION_ID=$(agent-tty --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
+agent-tty --home "$AGENT_HOME" run "$SESSION_ID" 'npm install'
+agent-tty --home "$AGENT_HOME" wait "$SESSION_ID" --text 'ready'
+agent-tty --home "$AGENT_HOME" screenshot "$SESSION_ID"
+agent-tty --home "$AGENT_HOME" record export "$SESSION_ID" --format webm
 ```
 
 Recommended sequence:
@@ -134,61 +155,62 @@ Recommended sequence:
 
 ## AI agent skill
 
-The public skill lives under `skills/agent-terminal/` and ships in the release tarball package.
-Install `agent-terminal` from a GitHub Release tarball first, then either use the packaged skill directly or let TanStack Intent map it into your agent config.
+The public skill lives under `skills/agent-tty/` and ships in the npm package as well as the GitHub Release tarball.
+Install `agent-tty` from npm first (or from a GitHub Release tarball when you need a registry-independent fallback), then either use the packaged skill directly or let TanStack Intent map it into your agent config.
 
-For coding agents that can ingest instructions on demand, `agent-terminal skill` prints the packaged `SKILL.md` directly to stdout after installation.
+For coding agents that can ingest instructions on demand, `agent-tty skill` prints the packaged `SKILL.md` directly to stdout after installation.
 
 ```bash
-agent-terminal skill
+agent-tty skill
 ```
 
 ### TanStack Intent integration
 
-After downloading `agent-terminal-<version>.tgz` from GitHub Releases, install it in the project and let Intent wire the mapping into `AGENTS.md`, `CLAUDE.md`, or another supported agent config file.
+After installing `agent-tty` in the project, let Intent wire the mapping into `AGENTS.md`, `CLAUDE.md`, or another supported agent config file.
 
 ```bash
-npm install ./agent-terminal-<version>.tgz
+PACKAGE_VERSION=<version>
+npm install "agent-tty@${PACKAGE_VERSION}"
 npx @tanstack/intent@latest list
 npx @tanstack/intent@latest install
 ```
 
-That workflow keeps the skill version aligned with the installed `agent-terminal` package and avoids writing one-off instructions for each individual coding agent.
+That workflow keeps the skill version aligned with the installed `agent-tty` package and avoids writing one-off instructions for each individual coding agent.
 
 ### Mux skill installation
 
-After installing the release tarball globally:
+After installing the npm package globally:
 
 ```bash
-mkdir -p ~/.mux/skills/agent-terminal
-cp -R "$(npm root -g)/agent-terminal/skills/agent-terminal/." ~/.mux/skills/agent-terminal/
+mkdir -p ~/.mux/skills/agent-tty
+cp -R "$(npm root -g)/agent-tty/skills/agent-tty/." ~/.mux/skills/agent-tty/
 ```
 
 ### Direct skill copy for other skill loaders
 
-After installing the release tarball globally:
+After installing the npm package globally:
 
 ```bash
-mkdir -p ~/.claude/skills/agent-terminal
-cp -R "$(npm root -g)/agent-terminal/skills/agent-terminal/." ~/.claude/skills/agent-terminal/
+mkdir -p ~/.claude/skills/agent-tty
+cp -R "$(npm root -g)/agent-tty/skills/agent-tty/." ~/.claude/skills/agent-tty/
 ```
 
-If your assistant supports repository-backed skills, point it at `coder/agent-terminal` and select the `agent-terminal` skill directory.
+If your assistant supports repository-backed skills, point it at `coder/agent-tty` and select the `agent-tty` skill directory.
 
 ### Suggested `AGENTS.md` / `CLAUDE.md` snippet
 
 ```markdown
 ## Terminal Automation
 
-Use `agent-terminal` for terminal and TUI automation instead of `tmux`, ad hoc PTY wrappers, or external screenshot tools.
+Use `agent-tty` for terminal and TUI automation instead of `tmux`, ad hoc PTY wrappers, or external screenshot tools.
 
 Preferred workflow:
 
-1. Create an isolated home and session with `agent-terminal --home "$AGENT_HOME" create --json -- /bin/bash`.
-2. Use `agent-terminal run` for setup and bootstrap commands.
-3. Use `agent-terminal wait` for observable readiness instead of blind sleeps.
-4. Use `agent-terminal snapshot` to inspect the current terminal state.
-5. Use `agent-terminal screenshot` or `agent-terminal record export` for reviewer-facing artifacts.
+1. Create an isolated home and session with `agent-tty --home "$AGENT_HOME" create --json -- /bin/bash`.
+2. Use `agent-tty run` for setup and bootstrap commands.
+3. Use `agent-tty wait` for observable readiness instead of blind sleeps.
+4. Use `agent-tty snapshot` to inspect the current terminal state.
+5. Use `agent-tty screenshot` or `agent-tty record export` for reviewer-facing artifacts.
 6. Destroy the session when the task is done.
 ```
 
@@ -200,11 +222,11 @@ npm run intent:validate
 
 ## Isolation
 
-- `--home <path>` stores manifests, sockets, event logs, and artifacts under an isolated agent-terminal home. Pass the same `--home` value to each command in a workflow.
-- `doctor --json` reports whether `agent-terminal` is using the default location or an isolated home, including a `home_isolation` check for whether `--home` produced an isolated environment.
+- `--home <path>` stores manifests, sockets, event logs, and artifacts under an isolated agent-tty home. Pass the same `--home` value to each command in a workflow.
+- `doctor --json` reports whether `agent-tty` is using the default location or an isolated home, including a `home_isolation` check for whether `--home` produced an isolated environment.
 - It also exposes `browser_cache_accessible`, which verifies the Playwright browser cache is discoverable for renderer operations before screenshot/export flows.
 - Renderer boot now carries Playwright browser-cache resolution into isolated-home workflows automatically when Chromium is installed in the normal cache or exposed through `PLAYWRIGHT_BROWSERS_PATH`.
-- In a new machine, CI job, or container, run `agent-terminal --home <path> doctor --json` before starting screenshot or recording workflows.
+- In a new machine, CI job, or container, run `agent-tty --home <path> doctor --json` before starting screenshot or recording workflows.
 
 ## Platform Support
 
@@ -214,7 +236,7 @@ npm run intent:validate
 
 ## CLI-wide flags
 
-- `--home <path>`: override the agent-terminal home directory.
+- `--home <path>`: override the agent-tty 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.
@@ -245,10 +267,10 @@ npm run intent:validate
 Basic usage:
 
 ```bash
-agent-terminal run <session-id> [command]
-agent-terminal run <session-id> --file ./setup.sh
-agent-terminal run <session-id> 'npm install && npm test' --timeout 60000 --json
-agent-terminal run <session-id> 'npm run dev' --no-wait
+agent-tty run <session-id> [command]
+agent-tty run <session-id> --file ./setup.sh
+agent-tty run <session-id> 'npm install && npm test' --timeout 60000 --json
+agent-tty run <session-id> 'npm run dev' --no-wait
 ```
 
 Important flags:
@@ -289,7 +311,7 @@ For contributor workflow and release hygiene, see [`docs/CONTRIBUTING.md`](./doc
 ## Design docs
 
 Design and implementation notes live under [`design/`](./design/README.md).
-Start with [`design/ARCHITECTURE.md`](./design/ARCHITECTURE.md) for the stable overview, use [`design/20260319_agent-terminal-v1/`](./design/20260319_agent-terminal-v1/) for the active reference set, and use [`design/archive/`](./design/archive/) for week-by-week project history.
+Start with [`design/ARCHITECTURE.md`](./design/ARCHITECTURE.md) for the stable overview, use [`design/20260319_agent-tty-v1/`](./design/20260319_agent-tty-v1/) for the active reference set, and use [`design/archive/`](./design/archive/) for week-by-week project history.
 
 ## Repository notes
 
diff --git a/RELEASE.md b/RELEASE.md
index b85c672..c2e807f 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,13 +1,13 @@
-# agent-terminal 0.1.0 release contract
+# agent-tty 0.1.0 release contract
 
-`agent-terminal` `0.1.0` is the first release that explicitly targets isolated, reviewable terminal automation for real TUI workflows.
+`agent-tty` `0.1.0` is the first release that explicitly targets isolated, reviewable terminal automation for real TUI workflows.
 The contract below is the bar for what maintainers should feel comfortable supporting at release time.
 If a workflow depends on behavior outside this document, treat it as future-scope or best-effort rather than a guaranteed `0.1.0` capability.
 For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md). For reviewer-facing proof bundles, start with [`dogfood/CATALOG.md`](./dogfood/CATALOG.md).
 
 ## What 0.1.0 delivers
 
-- Reliable isolated session lifecycle management: `create`, `inspect`, `destroy`, and `gc` all work against isolated agent-terminal homes.
+- Reliable isolated session lifecycle management: `create`, `inspect`, `destroy`, and `gc` all work against isolated agent-tty homes.
 - Renderer-backed screenshots, semantic snapshots, and WebM export for reviewer-visible proof artifacts.
 - The `run` command for robust in-session command execution without having to simulate long shell setup scripts as manual keystrokes.
 - `doctor --json` with isolation-aware diagnostics for home resolution, renderer prerequisites, and screenshot viability.
diff --git a/ROADMAP.md b/ROADMAP.md
index fa5a837..144b756 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,4 +1,4 @@
-# agent-terminal roadmap
+# agent-tty roadmap
 
 `RELEASE.md` defines what `0.1.0` ships today. This roadmap tracks intentionally deferred work and post-release direction so the repository front door separates shipped scope from future scope.
 For historical week-by-week planning and status context, see [`design/archive/`](./design/archive/). For the stable design overview, see [`design/ARCHITECTURE.md`](./design/ARCHITECTURE.md).
diff --git a/design/20260319_agent-terminal-v1/01-architecture.md b/design/20260319_agent-tty-v1/01-architecture.md
similarity index 98%
rename from design/20260319_agent-terminal-v1/01-architecture.md
rename to design/20260319_agent-tty-v1/01-architecture.md
index e6a132c..5eeabff 100644
--- a/design/20260319_agent-terminal-v1/01-architecture.md
+++ b/design/20260319_agent-tty-v1/01-architecture.md
@@ -1,10 +1,10 @@
-# agent-terminal v1 architecture
+# agent-tty v1 architecture
 
 ## 1. Design principles
 
 ### 1.1 General-purpose first
 
-`agent-terminal` must be useful outside Mux.
+`agent-tty` must be useful outside Mux.
 
 Concretely, that means:
 
@@ -80,18 +80,18 @@ A per-session host gives simpler isolation:
 
 Public binary:
 
-- `agent-terminal`
+- `agent-tty`
 
 Internal host entrypoint:
 
-- `agent-terminal _host --session-id ...`
+- `agent-tty _host --session-id ...`
 
 The internal `_host` subcommand is not documented for end users and may change without semver guarantees.
 
 ## 3. Suggested repository layout for a standalone implementation
 
 ```text
-agent-terminal/
+agent-tty/
 ├── src/
 │   ├── cli/
 │   │   ├── main.ts
@@ -151,7 +151,7 @@ agent-terminal/
 ## 4. Session directory layout
 
 ```text
-~/.agent-terminal/
+~/.agent-tty/
 ├── config.json
 ├── sessions/
 │   └── <session-id>/
diff --git a/design/20260319_agent-terminal-v1/02-cli-contract.md b/design/20260319_agent-tty-v1/02-cli-contract.md
similarity index 89%
rename from design/20260319_agent-terminal-v1/02-cli-contract.md
rename to design/20260319_agent-tty-v1/02-cli-contract.md
index 4cdecaa..e389633 100644
--- a/design/20260319_agent-terminal-v1/02-cli-contract.md
+++ b/design/20260319_agent-tty-v1/02-cli-contract.md
@@ -1,4 +1,4 @@
-# agent-terminal v1 CLI contract
+# agent-tty v1 CLI contract
 
 This document defines the concrete v1 CLI contract.
 
@@ -66,7 +66,7 @@ Failure envelope:
     "retryable": false,
     "details": {
       "sessionId": "missing-session",
-      "manifestPath": "/tmp/agent-terminal/sessions/missing-session/session.json"
+      "manifestPath": "/tmp/agent-tty/sessions/missing-session/session.json"
     }
   }
 }
@@ -95,7 +95,7 @@ All public commands should support these where sensible:
 | Flag                  | Meaning                                             |
 | --------------------- | --------------------------------------------------- |
 | `--json`              | Emit JSON envelope                                  |
-| `--home <path>`       | Override `~/.agent-terminal`                        |
+| `--home <path>`       | Override `~/.agent-tty`                        |
 | `--log-level <level>` | `error`, `warn`, `info`, `debug`, `trace`           |
 | `--timeout-ms <n>`    | Command timeout                                     |
 | `--profile <name>`    | Render profile override for render-related commands |
@@ -114,11 +114,11 @@ Resolved config order:
 
 | Variable                      | Meaning                                |
 | ----------------------------- | -------------------------------------- |
-| `AGENT_TERMINAL_HOME`         | Override home directory                |
-| `AGENT_TERMINAL_LOG_LEVEL`    | Logging default                        |
-| `AGENT_TERMINAL_PROFILE`      | Default render profile                 |
-| `AGENT_TERMINAL_BROWSER_PATH` | Override Playwright browser executable |
-| `AGENT_TERMINAL_KEEP_TEMP`    | Preserve temp replay outputs           |
+| `AGENT_TTY_HOME`         | Override home directory                |
+| `AGENT_TTY_LOG_LEVEL`    | Logging default                        |
+| `AGENT_TTY_PROFILE`      | Default render profile                 |
+| `AGENT_TTY_BROWSER_PATH` | Override Playwright browser executable |
+| `AGENT_TTY_KEEP_TEMP`    | Preserve temp replay outputs           |
 
 ## 4. Resource identifiers
 
@@ -148,9 +148,9 @@ Create a new session host and spawn a PTY child.
 ### 5.1 Syntax
 
 ```bash
-agent-terminal create [options] [command...]
-agent-terminal create [options]
-agent-terminal create [options] --shell /bin/zsh
+agent-tty create [options] [command...]
+agent-tty create [options]
+agent-tty create [options] --shell /bin/zsh
 ```
 
 ### 5.2 Required behavior
@@ -209,7 +209,7 @@ List sessions known in the home directory.
 ### 6.1 Syntax
 
 ```bash
-agent-terminal list [--all] [--json]
+agent-tty list [--all] [--json]
 ```
 
 ### 6.2 Behavior
@@ -237,8 +237,8 @@ Return the shipped merged session summary for one session.
 ### 7.1 Syntax
 
 ```bash
-agent-terminal inspect <session-id>
-agent-terminal inspect <session-id> --json
+agent-tty inspect <session-id>
+agent-tty inspect <session-id> --json
 ```
 
 ### 7.2 Behavior
@@ -317,9 +317,9 @@ Write raw UTF-8 text bytes into the PTY.
 ### 8.1 Syntax
 
 ```bash
-agent-terminal type <session-id> 'hello world'
-agent-terminal type <session-id> --file ./payload.txt
-agent-terminal type <session-id> 'hello world' --append-newline
+agent-tty type <session-id> 'hello world'
+agent-tty type <session-id> --file ./payload.txt
+agent-tty type <session-id> 'hello world' --append-newline
 ```
 
 ### 8.2 Flags
@@ -344,8 +344,8 @@ Write text as a paste operation.
 ### 9.1 Syntax
 
 ```bash
-agent-terminal paste <session-id> 'multiline\ninput'
-agent-terminal paste <session-id> --file ./payload.txt
+agent-tty paste <session-id> 'multiline\ninput'
+agent-tty paste <session-id> --file ./payload.txt
 ```
 
 ### 9.2 Semantics
@@ -367,9 +367,9 @@ Send named keys and chords.
 ### 10.1 Syntax
 
 ```bash
-agent-terminal send-keys <session-id> Enter
-agent-terminal send-keys <session-id> ctrl+l g g
-agent-terminal send-keys <session-id> alt+shift+f10
+agent-tty send-keys <session-id> Enter
+agent-tty send-keys <session-id> ctrl+l g g
+agent-tty send-keys <session-id> alt+shift+f10
 ```
 
 ### 10.2 Key grammar
@@ -414,7 +414,7 @@ Resize the terminal.
 ### 11.1 Syntax
 
 ```bash
-agent-terminal resize <session-id> --rows 50 --cols 140
+agent-tty resize <session-id> --rows 50 --cols 140
 ```
 
 ### 11.2 Required behavior
@@ -438,8 +438,8 @@ Send a process signal to the PTY child.
 ### 12.1 Syntax
 
 ```bash
-agent-terminal signal <session-id> INT
-agent-terminal signal <session-id> TERM
+agent-tty signal <session-id> INT
+agent-tty signal <session-id> TERM
 ```
 
 ### 12.2 Required behavior
@@ -466,11 +466,11 @@ V1 should support:
 ### 13.2 Syntax examples
 
 ```bash
-agent-terminal wait <session-id> --text 'Ready'
-agent-terminal wait <session-id> --regex 'Connected: .*'
-agent-terminal wait <session-id> --idle-ms 250
-agent-terminal wait <session-id> --screen-stable-ms 300
-agent-terminal wait <session-id> --exit
+agent-tty wait <session-id> --text 'Ready'
+agent-tty wait <session-id> --regex 'Connected: .*'
+agent-tty wait <session-id> --idle-ms 250
+agent-tty wait <session-id> --screen-stable-ms 300
+agent-tty wait <session-id> --exit
 ```
 
 ### 13.3 Semantics
@@ -515,10 +515,10 @@ Capture semantic terminal state.
 ### 14.1 Syntax
 
 ```bash
-agent-terminal snapshot <session-id>
-agent-terminal snapshot <session-id> --format text
-agent-terminal snapshot <session-id> --include-scrollback
-agent-terminal snapshot <session-id> --include-scrollback --include-cells --json
+agent-tty snapshot <session-id>
+agent-tty snapshot <session-id> --format text
+agent-tty snapshot <session-id> --include-scrollback
+agent-tty snapshot <session-id> --include-scrollback --include-cells --json
 ```
 
 ### 14.2 Formats
@@ -558,10 +558,10 @@ Capture a PNG screenshot from the selected renderer backend.
 ### 15.1 Syntax
 
 ```bash
-agent-terminal screenshot <session-id>
-agent-terminal screenshot <session-id> --profile reference-light
-agent-terminal screenshot <session-id> --show-cursor
-agent-terminal screenshot <session-id> --hide-cursor
+agent-tty screenshot <session-id>
+agent-tty screenshot <session-id> --profile reference-light
+agent-tty screenshot <session-id> --show-cursor
+agent-tty screenshot <session-id> --hide-cursor
 ```
 
 ### 15.2 Required behavior
@@ -581,7 +581,7 @@ agent-terminal screenshot <session-id> --hide-cursor
   "profileName": "reference-dark",
   "cols": 120,
   "rows": 40,
-  "artifactPath": "/home/user/.agent-terminal/sessions/.../artifacts/screenshot-85-reference-dark.png",
+  "artifactPath": "/home/user/.agent-tty/sessions/.../artifacts/screenshot-85-reference-dark.png",
   "pngSizeBytes": 123456,
   "cursorVisible": false,
   "rendererBackend": "ghostty-web",
@@ -604,8 +604,8 @@ Export a replay artifact.
 ### 16.2 Syntax
 
 ```bash
-agent-terminal record export <session-id> --format asciicast --out ./run.cast
-agent-terminal record export <session-id> --format webm --out ./run.webm
+agent-tty record export <session-id> --format asciicast --out ./run.cast
+agent-tty record export <session-id> --format webm --out ./run.webm
 ```
 
 ### 16.3 Semantics
@@ -621,8 +621,8 @@ Terminate session control.
 ### 17.1 Syntax
 
 ```bash
-agent-terminal destroy <session-id>
-agent-terminal destroy <session-id> --force
+agent-tty destroy <session-id>
+agent-tty destroy <session-id> --force
 ```
 
 ### 17.2 Semantics
@@ -648,8 +648,8 @@ Garbage-collect old sessions and temp artifacts.
 ### 18.1 Syntax
 
 ```bash
-agent-terminal gc --older-than 7d
-agent-terminal gc --stale-only
+agent-tty gc --older-than 7d
+agent-tty gc --stale-only
 ```
 
 ### 18.2 Behavior
diff --git a/design/20260319_agent-terminal-v1/03-rendering-and-artifacts.md b/design/20260319_agent-tty-v1/03-rendering-and-artifacts.md
similarity index 99%
rename from design/20260319_agent-terminal-v1/03-rendering-and-artifacts.md
rename to design/20260319_agent-tty-v1/03-rendering-and-artifacts.md
index b1065eb..83f1eda 100644
--- a/design/20260319_agent-terminal-v1/03-rendering-and-artifacts.md
+++ b/design/20260319_agent-tty-v1/03-rendering-and-artifacts.md
@@ -1,6 +1,6 @@
-# agent-terminal v1 rendering and artifacts
+# agent-tty v1 rendering and artifacts
 
-This document defines how `agent-terminal` turns PTY activity into inspectable artifacts.
+This document defines how `agent-tty` turns PTY activity into inspectable artifacts.
 
 ## 1. Rendering philosophy
 
diff --git a/design/20260319_agent-terminal-v1/04-implementation-plan.md b/design/20260319_agent-tty-v1/04-implementation-plan.md
similarity index 98%
rename from design/20260319_agent-terminal-v1/04-implementation-plan.md
rename to design/20260319_agent-tty-v1/04-implementation-plan.md
index c3341bc..88fc5af 100644
--- a/design/20260319_agent-terminal-v1/04-implementation-plan.md
+++ b/design/20260319_agent-tty-v1/04-implementation-plan.md
@@ -1,4 +1,4 @@
-# agent-terminal v1 implementation plan
+# agent-tty v1 implementation plan
 
 This plan is written so a follow-up AI coding agent can execute against it directly.
 
@@ -132,8 +132,8 @@ Create the initial project scaffold and the fundamental types.
 
 ### Dogfooding gate
 
-- run `agent-terminal version --json`,
-- run `agent-terminal doctor --json`,
+- run `agent-tty version --json`,
+- run `agent-tty doctor --json`,
 - capture a screenshot of the CLI output,
 - record a short terminal video showing both commands,
 - store artifacts under `dogfood/phase-0/`.
@@ -413,7 +413,7 @@ Fixture apps under `test/fixtures/apps/`:
 
 ### Acceptance criteria
 
-- every fixture can be launched by `agent-terminal create -- ...`,
+- every fixture can be launched by `agent-tty create -- ...`,
 - every fixture is used by at least one integration or e2e test,
 - the final proof bundle contains screenshots and videos for the critical flows.
 
diff --git a/design/20260319_agent-terminal-v1/05-dogfooding-and-validation.md b/design/20260319_agent-tty-v1/05-dogfooding-and-validation.md
similarity index 99%
rename from design/20260319_agent-terminal-v1/05-dogfooding-and-validation.md
rename to design/20260319_agent-tty-v1/05-dogfooding-and-validation.md
index 89aac09..9f2c983 100644
--- a/design/20260319_agent-terminal-v1/05-dogfooding-and-validation.md
+++ b/design/20260319_agent-tty-v1/05-dogfooding-and-validation.md
@@ -1,6 +1,6 @@
-# agent-terminal v1 dogfooding and validation
+# agent-tty v1 dogfooding and validation
 
-This document defines how to prove that `agent-terminal` actually works for TUI dogfooding.
+This document defines how to prove that `agent-tty` actually works for TUI dogfooding.
 
 It is intentionally prescriptive.
 
@@ -501,7 +501,7 @@ Every scenario directory should include `notes.md` using a template like:
 
 ## Command under test
 
-`agent-terminal ...`
+`agent-tty ...`
 
 ## Expected behavior
 
diff --git a/design/ARCHITECTURE.md b/design/ARCHITECTURE.md
index 0ef97f7..9aa2a35 100644
--- a/design/ARCHITECTURE.md
+++ b/design/ARCHITECTURE.md
@@ -3,9 +3,9 @@ author: "@mux"
 date: 2026-03-19
 ---
 
-# agent-terminal architecture overview
+# agent-tty architecture overview
 
-`agent-terminal` is a CLI-first terminal automation system for AI agents and humans.
+`agent-tty` is a CLI-first terminal automation system for AI agents and humans.
 
 It is designed to let an agent:
 
@@ -17,7 +17,7 @@ It is designed to let an agent:
 - export replay artifacts that reviewers can inspect,
 - and later swap the reference renderer for native terminal backends.
 
-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.
+This design intentionally describes a **general product**, not a Mux-specific implementation. A future Mux integration should consume `agent-tty` as an external CLI/runtime rather than baking Mux-specific assumptions into the design.
 
 ## Current shipped status (2026-03-26)
 
@@ -48,7 +48,7 @@ The stable contract and deferred work now have dedicated homes: use [`../RELEASE
 
 The recommended v1 shape is:
 
-1. **CLI-first** public surface: `agent-terminal ...`
+1. **CLI-first** public surface: `agent-tty ...`
 2. **No MCP in v1**
 3. **TypeScript/Node** implementation
 4. **One session-host process per terminal session**, not a global daemon
@@ -103,7 +103,7 @@ This shape optimizes for the constraints discussed so far:
 
 The public contract is the CLI and its JSON output, not an internal RPC API and not Mux tools.
 
-This keeps `agent-terminal` reusable by:
+This keeps `agent-tty` reusable by:
 
 - AI coding agents,
 - shell scripts,
@@ -170,7 +170,7 @@ The architecture reserves native backends for later:
 
 ## Tiered truth model
 
-`agent-terminal` should treat terminal truth as layered rather than singular.
+`agent-tty` should treat terminal truth as layered rather than singular.
 
 | Layer                  | Source of truth             | What it answers                                           |
 | ---------------------- | --------------------------- | --------------------------------------------------------- |
@@ -197,15 +197,15 @@ Asciicast and replay-video export remain intended follow-on capabilities rather
 
 ## Deliverables in this design set
 
-This design file is the entry point. Detailed supporting docs live in the active reference set under `design/20260319_agent-terminal-v1/`, while historical planning/status material lives under `design/archive/`.
+This design file is the entry point. Detailed supporting docs live in the active reference set under `design/20260319_agent-tty-v1/`, while historical planning/status material lives under `design/archive/`.
 
 ### Active reference set
 
-- [01-architecture.md](./20260319_agent-terminal-v1/01-architecture.md)
-- [02-cli-contract.md](./20260319_agent-terminal-v1/02-cli-contract.md)
-- [03-rendering-and-artifacts.md](./20260319_agent-terminal-v1/03-rendering-and-artifacts.md)
-- [04-implementation-plan.md](./20260319_agent-terminal-v1/04-implementation-plan.md)
-- [05-dogfooding-and-validation.md](./20260319_agent-terminal-v1/05-dogfooding-and-validation.md)
+- [01-architecture.md](./20260319_agent-tty-v1/01-architecture.md)
+- [02-cli-contract.md](./20260319_agent-tty-v1/02-cli-contract.md)
+- [03-rendering-and-artifacts.md](./20260319_agent-tty-v1/03-rendering-and-artifacts.md)
+- [04-implementation-plan.md](./20260319_agent-tty-v1/04-implementation-plan.md)
+- [05-dogfooding-and-validation.md](./20260319_agent-tty-v1/05-dogfooding-and-validation.md)
 
 ### Historical archive
 
@@ -226,8 +226,8 @@ This design file is the entry point. Detailed supporting docs live in the active
 
 ```mermaid
 flowchart TD
-    CLI["agent-terminal CLI"] --> SessionCtl["Session host control socket"]
-    CLI --> Home["~/.agent-terminal"]
+    CLI["agent-tty CLI"] --> SessionCtl["Session host control socket"]
+    CLI --> Home["~/.agent-tty"]
 
     SessionCtl --> Host["Per-session host process"]
     Host --> PTY["node-pty PTY child"]
diff --git a/design/README.md b/design/README.md
index 2a2bc8f..64a9f20 100644
--- a/design/README.md
+++ b/design/README.md
@@ -6,19 +6,19 @@ The active reference set stays separate from the week-by-week project history so
 ## Start here
 
 1. [`ARCHITECTURE.md`](./ARCHITECTURE.md) — stable product and architecture overview.
-2. [`20260319_agent-terminal-v1/02-cli-contract.md`](./20260319_agent-terminal-v1/02-cli-contract.md) — CLI contract details.
-3. [`20260319_agent-terminal-v1/03-rendering-and-artifacts.md`](./20260319_agent-terminal-v1/03-rendering-and-artifacts.md) — replay, screenshot, and export model.
-4. [`20260319_agent-terminal-v1/05-dogfooding-and-validation.md`](./20260319_agent-terminal-v1/05-dogfooding-and-validation.md) — proof-bundle expectations.
+2. [`20260319_agent-tty-v1/02-cli-contract.md`](./20260319_agent-tty-v1/02-cli-contract.md) — CLI contract details.
+3. [`20260319_agent-tty-v1/03-rendering-and-artifacts.md`](./20260319_agent-tty-v1/03-rendering-and-artifacts.md) — replay, screenshot, and export model.
+4. [`20260319_agent-tty-v1/05-dogfooding-and-validation.md`](./20260319_agent-tty-v1/05-dogfooding-and-validation.md) — proof-bundle expectations.
 
 ## Active reference set
 
 The original v1 design review produced a focused reference set that is still useful as evergreen technical documentation:
 
-- [`20260319_agent-terminal-v1/01-architecture.md`](./20260319_agent-terminal-v1/01-architecture.md)
-- [`20260319_agent-terminal-v1/02-cli-contract.md`](./20260319_agent-terminal-v1/02-cli-contract.md)
-- [`20260319_agent-terminal-v1/03-rendering-and-artifacts.md`](./20260319_agent-terminal-v1/03-rendering-and-artifacts.md)
-- [`20260319_agent-terminal-v1/04-implementation-plan.md`](./20260319_agent-terminal-v1/04-implementation-plan.md)
-- [`20260319_agent-terminal-v1/05-dogfooding-and-validation.md`](./20260319_agent-terminal-v1/05-dogfooding-and-validation.md)
+- [`20260319_agent-tty-v1/01-architecture.md`](./20260319_agent-tty-v1/01-architecture.md)
+- [`20260319_agent-tty-v1/02-cli-contract.md`](./20260319_agent-tty-v1/02-cli-contract.md)
+- [`20260319_agent-tty-v1/03-rendering-and-artifacts.md`](./20260319_agent-tty-v1/03-rendering-and-artifacts.md)
+- [`20260319_agent-tty-v1/04-implementation-plan.md`](./20260319_agent-tty-v1/04-implementation-plan.md)
+- [`20260319_agent-tty-v1/05-dogfooding-and-validation.md`](./20260319_agent-tty-v1/05-dogfooding-and-validation.md)
 
 ## Historical archive
 
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 5bd0c93..008e4b4 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -20,7 +20,7 @@ npx playwright install chromium
 
 - Use `npx tsx src/cli/main.ts ...` while developing from the source tree.
 - Prefer `--json` when a workflow needs machine-readable output.
-- Use an isolated absolute `AGENT_TERMINAL_HOME` for tests and manual dogfooding.
+- Use an isolated absolute `AGENT_TTY_HOME` for tests and manual dogfooding.
 - Keep storage writes, manifests, and protocol updates inside the existing validated helpers and schemas.
 
 ## Validation
@@ -52,4 +52,4 @@ npm run intent:validate
 - Keep the root docs split clear: `README.md` for overview, `RELEASE.md` for current scope, `ROADMAP.md` for future scope.
 - Update [`design/README.md`](../design/README.md) when the active vs archived design split changes.
 - Update [`dogfood/CATALOG.md`](../dogfood/CATALOG.md) when you add or promote a reviewer-facing proof bundle.
-- Prefer public `agent-terminal ...` invocations in shipped skill/docs examples; do not commit repo-local `npx tsx src/cli/main.ts ...` substitutions into public-facing examples.
+- Prefer public `agent-tty ...` invocations in shipped skill/docs examples; do not commit repo-local `npx tsx src/cli/main.ts ...` substitutions into public-facing examples.
diff --git a/docs/RELEASE-PROCESS.md b/docs/RELEASE-PROCESS.md
index fd0ec3e..7cae60b 100644
--- a/docs/RELEASE-PROCESS.md
+++ b/docs/RELEASE-PROCESS.md
@@ -1,6 +1,21 @@
 # Release process
 
-`RELEASE.md` defines the shipping contract. This document describes how maintainers should validate, version, tag, and publish that contract on GitHub Releases.
+`RELEASE.md` defines the shipping contract. This document describes how maintainers should validate, version, tag, and publish that contract on GitHub Releases and npm.
+
+## One-time npm trusted publishing setup
+
+1. Ensure the intended npm package name remains `agent-tty`.
+2. On npm, configure trusted publishing for `agent-tty` with these GitHub Actions settings:
+   - organization or user: `coder`
+   - repository: `agent-tty`
+   - workflow filename: `release.yml` (the workflow file committed at `.github/workflows/release.yml`)
+   - environment name: leave empty unless this workflow later adds a protected GitHub environment for publishing
+3. After the first successful trusted publish, restrict the package's npm publishing access to require 2FA and disallow traditional tokens.
+4. Keep the package metadata aligned with npm provenance expectations:
+   - `package.json.name` must stay `agent-tty`
+   - `package.json.repository.url` must stay `git+https://github.com/coder/agent-tty.git`
+   - `package.json.publishConfig.registry` must stay `https://registry.npmjs.org/`
+5. No GitHub Actions secret is required for npm publishing in this flow; the workflow uses GitHub-hosted runners plus OIDC trusted publishing.
 
 ## Release prerequisites
 
@@ -8,7 +23,7 @@
 2. Re-read [`../ROADMAP.md`](../ROADMAP.md) and confirm deferred work is not mixed back into the release contract.
 3. Verify the primary docs route correctly from [`../README.md`](../README.md) to release, roadmap, design, and dogfood materials.
 4. Review [`../dogfood/CATALOG.md`](../dogfood/CATALOG.md) and make sure the release-signoff bundle is current and easy to find.
-5. Confirm npm publication is still intentionally out of scope for this workflow; the supported hosted install path today is the GitHub Release tarball asset.
+5. Confirm the published package metadata still points at `agent-tty` and the public GitHub repository.
 6. Remember that `main` is protected: release changes must land through a pull request, and the release tag must be created only after that PR is merged.
 
 ## Validation bar
@@ -31,7 +46,7 @@ If the public skill changed, also run:
 npm run intent:validate
 ```
 
-`mise run ci` exercises formatting, lint, typecheck, tests, build, and the install smoke. The install smoke validates the shared release tarball packer plus the guaranteed tarball install route before any publish step runs.
+`mise run ci` exercises formatting, lint, typecheck, tests, build, and the install smoke. The install smoke validates the shared release tarball packer plus the required tarball install route before any publish step runs.
 
 ## Prepare the release asset locally (optional but recommended)
 
@@ -45,7 +60,7 @@ cat "$RELEASE_DIR/package-metadata.json"
 sha256sum -c "$RELEASE_DIR"/*.tgz.sha256
 ```
 
-That command produces the same tarball, checksum, and metadata shape that the GitHub release workflow uploads.
+That command produces the same tarball, checksum, and metadata shape that the GitHub release workflow uploads and later reuses for npm publishing.
 
 ## Release flow overview
 
@@ -55,7 +70,7 @@ Because `main` is pull-request-only, the correct release flow is:
 2. bump the version **without creating a tag yet**,
 3. open and merge a PR,
 4. tag the merged `main` commit,
-5. let the `Release` workflow publish the GitHub Release assets.
+5. let the `Release` workflow publish the GitHub Release assets and npm package.
 
 Do **not** run `npm version ...` on `main` and then push `HEAD --follow-tags`; GitHub will reject the protected-branch push but still accept the tag, which can start a release from an unmerged commit.
 
@@ -108,7 +123,7 @@ Release candidate with an exact version:
 npm version 0.1.1-rc.0 --no-git-tag-version
 ```
 
-Versions containing a hyphen, such as `-beta.0` or `-rc.0`, are published by the workflow as GitHub prereleases.
+Versions containing a hyphen, such as `-beta.0` or `-rc.0`, are published by the workflow as GitHub prereleases and published to the matching npm dist-tag (`beta`, `rc`, and so on).
 
 ### Open the release PR
 
@@ -149,7 +164,7 @@ or:
 - `package.json`: `0.1.1-beta.0`
 - tag: `v0.1.1-beta.0`
 
-## Publish the GitHub Release
+## Publish the GitHub Release and npm package
 
 The hand-curated workflow lives at [`.github/workflows/release.yml`](../.github/workflows/release.yml).
 It triggers automatically on pushed `v*` tags, and it can also be rerun manually for an already-existing remote tag via the **Release** workflow's `tag` input.
@@ -162,33 +177,72 @@ The workflow will:
 - run `mise run ci`,
 - pack the verified tarball with `npm run pack:release`,
 - upload the tarball, checksum, and metadata JSON as workflow artifacts,
-- and create or update the GitHub Release with the `.tgz` and `.sha256` assets attached.
+- create or update the GitHub Release with the `.tgz` and `.sha256` assets attached,
+- and publish that same verified tarball to npm via trusted publishing on a GitHub-hosted runner.
 
-The workflow intentionally splits artifact preparation from GitHub release publication so a future npm-publish job can depend on the verified `prepare-release` outputs instead of rebuilding the package.
+Stable releases publish with npm's default `latest` dist-tag.
+Prerelease versions publish with the prerelease identifier as the dist-tag, so `0.1.1-beta.0` publishes to the `beta` dist-tag and `0.1.1-rc.1` publishes to the `rc` dist-tag.
 
-## Verify the published release assets
+## Verify the published npm package
 
-After the workflow succeeds, verify the hosted asset before announcing the release:
+After the workflow succeeds, verify the exact npm package version before announcing the release:
+
+```bash
+PACKAGE_NAME='agent-tty'
+PACKAGE_VERSION='<version>'
+INSTALL_PREFIX=$(mktemp -d)
+AGENT_TTY_HOME=$(mktemp -d)
+
+npm view "$PACKAGE_NAME" dist-tags --json
+npm install -g --prefix "$INSTALL_PREFIX" "$PACKAGE_NAME@$PACKAGE_VERSION"
+"$INSTALL_PREFIX"/bin/agent-tty version --json
+"$INSTALL_PREFIX"/bin/agent-tty --home "$AGENT_TTY_HOME" doctor --json
+```
+
+If the release is a prerelease, also confirm the intended dist-tag points at the exact published version:
+
+```bash
+PACKAGE_NAME='agent-tty'
+PACKAGE_VERSION='<version>'
+DIST_TAG=$(node --input-type=module <<'EOF_NODE'
+const version = process.env.PACKAGE_VERSION;
+if (!version.includes('-')) {
+  process.stdout.write('latest');
+  process.exit(0);
+}
+const prerelease = version.split('-', 2)[1] ?? '';
+const distTag = prerelease.split('.', 1)[0] ?? '';
+if (distTag.length === 0) {
+  throw new Error(`unable to derive dist-tag from ${version}`);
+}
+process.stdout.write(distTag);
+EOF_NODE
+)
+
+npm view "$PACKAGE_NAME" dist-tags --json
+printf 'expected dist-tag %s for %s\n' "$DIST_TAG" "$PACKAGE_VERSION"
+```
+
+## Verify the published GitHub Release assets
+
+Also verify the hosted tarball fallback before announcing the release:
 
 ```bash
 VERSION=<version>
 RELEASE_TAG="v${VERSION}"
-RELEASE_TGZ="agent-terminal-${VERSION}.tgz"
+RELEASE_TGZ="agent-tty-${VERSION}.tgz"
 
 DOWNLOAD_DIR=$(mktemp -d)
 INSTALL_PREFIX=$(mktemp -d)
-AGENT_TERMINAL_HOME=$(mktemp -d)
+AGENT_TTY_HOME=$(mktemp -d)
 
-gh release download "$RELEASE_TAG" --repo coder/agent-terminal --dir "$DOWNLOAD_DIR" --pattern "$RELEASE_TGZ"
-gh release download "$RELEASE_TAG" --repo coder/agent-terminal --dir "$DOWNLOAD_DIR" --pattern "${RELEASE_TGZ}.sha256"
-(
-  cd "$DOWNLOAD_DIR"
-  sha256sum -c "${RELEASE_TGZ}.sha256"
-)
+gh release download "$RELEASE_TAG" --repo coder/agent-tty --dir "$DOWNLOAD_DIR" --pattern "$RELEASE_TGZ"
+gh release download "$RELEASE_TAG" --repo coder/agent-tty --dir "$DOWNLOAD_DIR" --pattern "${RELEASE_TGZ}.sha256"
+sha256sum -c "$DOWNLOAD_DIR/${RELEASE_TGZ}.sha256"
 
 npm install -g --prefix "$INSTALL_PREFIX" "$DOWNLOAD_DIR/$RELEASE_TGZ"
-"$INSTALL_PREFIX"/bin/agent-terminal version --json
-"$INSTALL_PREFIX"/bin/agent-terminal --home "$AGENT_TERMINAL_HOME" doctor --json
+"$INSTALL_PREFIX"/bin/agent-tty version --json
+"$INSTALL_PREFIX"/bin/agent-tty --home "$AGENT_TTY_HOME" doctor --json
 ```
 
 For private releases, authenticated download is the expected verification route.
@@ -218,9 +272,3 @@ Then create or update the release branch PR, merge it, and tag the merged `main`
 - Keep at least one current release-readiness bundle under `dogfood/`.
 - Keep evergreen scenario bundles easy to discover from the dogfood catalog.
 - When a change affects release, packaging, install, renderer, screenshot, wait, export, or review UX, include screenshots and recordings in the relevant proof bundle when feasible.
-
-## Future npm publish seam
-
-The release workflow intentionally stops at the GitHub Release asset.
-A future npm-publish job should depend on `prepare-release`, consume the verified tarball and metadata JSON that job already emits, and publish without rebuilding the package.
-Package name and registry decisions remain a separate follow-up because the current npm name is not settled.
diff --git a/package-lock.json b/package-lock.json
index 47b2a16..306e693 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,11 +1,11 @@
 {
-  "name": "agent-terminal",
+  "name": "agent-tty",
   "version": "0.1.1-beta.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "agent-terminal",
+      "name": "agent-tty",
       "version": "0.1.1-beta.0",
       "dependencies": {
         "commander": "14.0.3",
@@ -16,7 +16,7 @@
         "zod": "4.3.6"
       },
       "bin": {
-        "agent-terminal": "dist/cli/main.js"
+        "agent-tty": "dist/cli/main.js"
       },
       "devDependencies": {
         "@eslint/js": "10.0.1",
diff --git a/package.json b/package.json
index 70f38c8..ae0d7e0 100644
--- a/package.json
+++ b/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "agent-terminal",
+  "name": "agent-tty",
   "version": "0.1.1-beta.0",
   "description": "Terminal automation CLI for AI agents and humans",
   "keywords": [
@@ -9,13 +9,21 @@
     "ai",
     "tanstack-intent"
   ],
+  "homepage": "https://github.com/coder/agent-tty#readme",
+  "bugs": {
+    "url": "https://github.com/coder/agent-tty/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coder/agent-tty.git"
+  },
   "type": "module",
   "packageManager": "npm@11.9.0",
   "engines": {
     "node": ">=24.0.0 <25"
   },
   "bin": {
-    "agent-terminal": "./dist/cli/main.js"
+    "agent-tty": "./dist/cli/main.js"
   },
   "files": [
     "dist",
@@ -24,6 +32,9 @@
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node ./scripts/copy-renderer-assets.mjs",
     "clean": "rimraf coverage dist *.tsbuildinfo",
diff --git a/scripts/smoke-install.mjs b/scripts/smoke-install.mjs
index 512b7db..bae4f94 100755
--- a/scripts/smoke-install.mjs
+++ b/scripts/smoke-install.mjs
@@ -45,7 +45,7 @@ assert(
 const [binName] = Object.keys(packageBins);
 assert(typeof binName === 'string' && binName.length > 0, 'bin name missing');
 
-const tempRoot = await mkdtemp(join(tmpdir(), 'agent-terminal-install-smoke-'));
+const tempRoot = await mkdtemp(join(tmpdir(), 'agent-tty-install-smoke-'));
 
 function logStep(message) {
   assert(message.length > 0, 'log messages must be non-empty');
@@ -213,7 +213,7 @@ function getRequiredPackPaths(rendererAssets) {
     'dist/cli/main.js',
     'dist/index.js',
     'dist/index.d.ts',
-    'skills/agent-terminal/SKILL.md',
+    'skills/agent-tty/SKILL.md',
     ...rendererAssets.map(
       (assetPath) => `dist/renderer/ghosttyWeb/assets/${assetPath}`,
     ),
@@ -378,10 +378,10 @@ async function createGitInstallSource() {
   });
 
   run('git', ['init', '--quiet'], { cwd: gitSourceRoot });
-  run('git', ['config', 'user.email', 'agent-terminal@example.invalid'], {
+  run('git', ['config', 'user.email', 'agent-tty@example.invalid'], {
     cwd: gitSourceRoot,
   });
-  run('git', ['config', 'user.name', 'agent-terminal smoke'], {
+  run('git', ['config', 'user.name', 'agent-tty smoke'], {
     cwd: gitSourceRoot,
   });
   run('git', ['add', '--all'], { cwd: gitSourceRoot });
diff --git a/skills/agent-terminal/SKILL.md b/skills/agent-terminal/SKILL.md
deleted file mode 100644
index 1c514eb..0000000
--- a/skills/agent-terminal/SKILL.md
+++ /dev/null
@@ -1,102 +0,0 @@
----
-name: agent-terminal
-description: Terminal and TUI automation CLI for AI agents. Use when the user needs to create a terminal session, run a command in a terminal, automate an interactive CLI or TUI, wait for terminal output, capture a TUI screenshot, export a terminal recording, or test a CLI workflow with reviewable artifacts.
-advertise: true
----
-
-# Terminal Automation with agent-terminal
-
-If `agent-terminal` is not already available in the environment, fetch the current `README.md` from `coder/agent-terminal` on GitHub and follow its installation instructions before continuing. Otherwise use `agent-terminal` directly.
-Examples use `jq` for JSON parsing; any JSON-processing tool works.
-Prefer isolated homes, JSON envelopes, and renderer-backed artifacts so terminal workflows stay reviewable and reproducible.
-
-## Core Workflow
-
-Every terminal or TUI automation task should follow this pattern:
-
-1. **Create an isolated home** with `--home`.
-2. **Check prerequisites** with `doctor --json` before screenshot or recording work.
-3. **Create a session** with `create --json`.
-4. **Run setup commands** with `run` instead of simulating long shell typing.
-5. **Wait on observable terminal state** with `wait` instead of blind sleeps.
-6. **Inspect the current screen** with `snapshot`.
-7. **Capture proof artifacts** with `screenshot` or `record export`.
-8. **Destroy the session** when finished.
-
-```bash
-AGENT_HOME="$(mktemp -d)"
-agent-terminal --home "$AGENT_HOME" doctor --json
-SESSION_ID=$(agent-terminal --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
-agent-terminal --home "$AGENT_HOME" run "$SESSION_ID" 'printf "ready\n"'
-agent-terminal --home "$AGENT_HOME" wait "$SESSION_ID" --text 'ready' --json
-agent-terminal --home "$AGENT_HOME" snapshot "$SESSION_ID" --format text --json
-agent-terminal --home "$AGENT_HOME" screenshot "$SESSION_ID" --json
-agent-terminal --home "$AGENT_HOME" record export "$SESSION_ID" --format webm --json
-agent-terminal --home "$AGENT_HOME" destroy "$SESSION_ID" --json
-```
-
-## Essential Commands
-
-```bash
-# Environment and lifecycle
-agent-terminal --home <path> doctor --json
-agent-terminal --home <path> create --json -- /bin/bash
-agent-terminal --home <path> inspect <session-id> --json
-agent-terminal --home <path> destroy <session-id> --json
-
-# In-session control
-agent-terminal --home <path> run <session-id> 'command here' --json
-agent-terminal --home <path> type <session-id> 'literal text' --json
-agent-terminal --home <path> paste <session-id> 'multiline payload' --json
-agent-terminal --home <path> send-keys <session-id> Enter Ctrl+C --json
-
-# Observation and proof
-agent-terminal --home <path> wait <session-id> --text 'ready' --json
-agent-terminal --home <path> wait <session-id> --screen-stable-ms 1000 --json
-agent-terminal --home <path> snapshot <session-id> --format text --json
-agent-terminal --home <path> screenshot <session-id> --json
-agent-terminal --home <path> record export <session-id> --format webm --json
-```
-
-## Common Patterns
-
-### Bootstrap a shell session
-
-```bash
-AGENT_HOME="$(mktemp -d)"
-SESSION_ID=$(agent-terminal --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
-agent-terminal --home "$AGENT_HOME" run "$SESSION_ID" 'pwd && ls -la' --json
-agent-terminal --home "$AGENT_HOME" snapshot "$SESSION_ID" --format text --json
-```
-
-### Drive an interactive CLI or TUI
-
-```bash
-AGENT_HOME="$(mktemp -d)"
-SESSION_ID=$(agent-terminal --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
-agent-terminal --home "$AGENT_HOME" run "$SESSION_ID" '<interactive-command>' --no-wait --json
-agent-terminal --home "$AGENT_HOME" wait "$SESSION_ID" --screen-stable-ms 1000 --json
-agent-terminal --home "$AGENT_HOME" send-keys "$SESSION_ID" Down Down Enter --json
-agent-terminal --home "$AGENT_HOME" screenshot "$SESSION_ID" --json
-```
-
-### Export reviewer-facing artifacts
-
-```bash
-AGENT_HOME="$(mktemp -d)"
-SESSION_ID=$(agent-terminal --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
-agent-terminal --home "$AGENT_HOME" run "$SESSION_ID" 'printf "artifact proof\n"' --json
-agent-terminal --home "$AGENT_HOME" wait "$SESSION_ID" --text 'artifact proof' --json
-agent-terminal --home "$AGENT_HOME" screenshot "$SESSION_ID" --json
-agent-terminal --home "$AGENT_HOME" record export "$SESSION_ID" --format asciicast --json
-agent-terminal --home "$AGENT_HOME" record export "$SESSION_ID" --format webm --json
-```
-
-## Anti-Patterns
-
-- **Do not reach for `tmux`, `screen`, or ad hoc PTY wrappers first** when `agent-terminal` can provide an isolated, inspectable session.
-- **Do not rely on blind `sleep` calls** when `wait --text`, `wait --idle-ms`, or `wait --screen-stable-ms` can observe terminal readiness directly.
-- **Do not bypass `--json`** when another tool or agent needs machine-readable results.
-- **Do not use external screenshot tools as the primary proof path** when `agent-terminal screenshot` and `agent-terminal record export` can produce renderer-backed artifacts tied to the session timeline.
-- **Do not leave sessions running after the task ends**; destroy them explicitly.
-- **Do not rewrite public examples into repo-local development invocations**; the public workflow should stay `agent-terminal ...`.
diff --git a/skills/agent-tty/SKILL.md b/skills/agent-tty/SKILL.md
new file mode 100644
index 0000000..cb1cee0
--- /dev/null
+++ b/skills/agent-tty/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: agent-tty
+description: Terminal and TUI automation CLI for AI agents. Use when the user needs to create a terminal session, run a command in a terminal, automate an interactive CLI or TUI, wait for terminal output, capture a TUI screenshot, export a terminal recording, or test a CLI workflow with reviewable artifacts.
+advertise: true
+---
+
+# Terminal Automation with agent-tty
+
+If `agent-tty` is not already available in the environment, fetch the current `README.md` from `coder/agent-tty` on GitHub and follow its installation instructions before continuing. Otherwise use `agent-tty` directly.
+Examples use `jq` for JSON parsing; any JSON-processing tool works.
+Prefer isolated homes, JSON envelopes, and renderer-backed artifacts so terminal workflows stay reviewable and reproducible.
+
+## Core Workflow
+
+Every terminal or TUI automation task should follow this pattern:
+
+1. **Create an isolated home** with `--home`.
+2. **Check prerequisites** with `doctor --json` before screenshot or recording work.
+3. **Create a session** with `create --json`.
+4. **Run setup commands** with `run` instead of simulating long shell typing.
+5. **Wait on observable terminal state** with `wait` instead of blind sleeps.
+6. **Inspect the current screen** with `snapshot`.
+7. **Capture proof artifacts** with `screenshot` or `record export`.
+8. **Destroy the session** when finished.
+
+```bash
+AGENT_HOME="$(mktemp -d)"
+agent-tty --home "$AGENT_HOME" doctor --json
+SESSION_ID=$(agent-tty --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
+agent-tty --home "$AGENT_HOME" run "$SESSION_ID" 'printf "ready\n"'
+agent-tty --home "$AGENT_HOME" wait "$SESSION_ID" --text 'ready' --json
+agent-tty --home "$AGENT_HOME" snapshot "$SESSION_ID" --format text --json
+agent-tty --home "$AGENT_HOME" screenshot "$SESSION_ID" --json
+agent-tty --home "$AGENT_HOME" record export "$SESSION_ID" --format webm --json
+agent-tty --home "$AGENT_HOME" destroy "$SESSION_ID" --json
+```
+
+## Essential Commands
+
+```bash
+# Environment and lifecycle
+agent-tty --home <path> doctor --json
+agent-tty --home <path> create --json -- /bin/bash
+agent-tty --home <path> inspect <session-id> --json
+agent-tty --home <path> destroy <session-id> --json
+
+# In-session control
+agent-tty --home <path> run <session-id> 'command here' --json
+agent-tty --home <path> type <session-id> 'literal text' --json
+agent-tty --home <path> paste <session-id> 'multiline payload' --json
+agent-tty --home <path> send-keys <session-id> Enter Ctrl+C --json
+
+# Observation and proof
+agent-tty --home <path> wait <session-id> --text 'ready' --json
+agent-tty --home <path> wait <session-id> --screen-stable-ms 1000 --json
+agent-tty --home <path> snapshot <session-id> --format text --json
+agent-tty --home <path> screenshot <session-id> --json
+agent-tty --home <path> record export <session-id> --format webm --json
+```
+
+## Common Patterns
+
+### Bootstrap a shell session
+
+```bash
+AGENT_HOME="$(mktemp -d)"
+SESSION_ID=$(agent-tty --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
+agent-tty --home "$AGENT_HOME" run "$SESSION_ID" 'pwd && ls -la' --json
+agent-tty --home "$AGENT_HOME" snapshot "$SESSION_ID" --format text --json
+```
+
+### Drive an interactive CLI or TUI
+
+```bash
+AGENT_HOME="$(mktemp -d)"
+SESSION_ID=$(agent-tty --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
+agent-tty --home "$AGENT_HOME" run "$SESSION_ID" '<interactive-command>' --no-wait --json
+agent-tty --home "$AGENT_HOME" wait "$SESSION_ID" --screen-stable-ms 1000 --json
+agent-tty --home "$AGENT_HOME" send-keys "$SESSION_ID" Down Down Enter --json
+agent-tty --home "$AGENT_HOME" screenshot "$SESSION_ID" --json
+```
+
+### Export reviewer-facing artifacts
+
+```bash
+AGENT_HOME="$(mktemp -d)"
+SESSION_ID=$(agent-tty --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
+agent-tty --home "$AGENT_HOME" run "$SESSION_ID" 'printf "artifact proof\n"' --json
+agent-tty --home "$AGENT_HOME" wait "$SESSION_ID" --text 'artifact proof' --json
+agent-tty --home "$AGENT_HOME" screenshot "$SESSION_ID" --json
+agent-tty --home "$AGENT_HOME" record export "$SESSION_ID" --format asciicast --json
+agent-tty --home "$AGENT_HOME" record export "$SESSION_ID" --format webm --json
+```
+
+## Anti-Patterns
+
+- **Do not reach for `tmux`, `screen`, or ad hoc PTY wrappers first** when `agent-tty` can provide an isolated, inspectable session.
+- **Do not rely on blind `sleep` calls** when `wait --text`, `wait --idle-ms`, or `wait --screen-stable-ms` can observe terminal readiness directly.
+- **Do not bypass `--json`** when another tool or agent needs machine-readable results.
+- **Do not use external screenshot tools as the primary proof path** when `agent-tty screenshot` and `agent-tty record export` can produce renderer-backed artifacts tied to the session timeline.
+- **Do not leave sessions running after the task ends**; destroy them explicitly.
+- **Do not rewrite public examples into repo-local development invocations**; the public workflow should stay `agent-tty ...`.
diff --git a/src/cli/commands/doctor.ts b/src/cli/commands/doctor.ts
index 7275caa..3f6feb0 100644
--- a/src/cli/commands/doctor.ts
+++ b/src/cli/commands/doctor.ts
@@ -366,14 +366,14 @@ async function runWorkingDirectoryCheck(): Promise<string> {
 }
 
 async function runTemporaryDirectoryCheck(): Promise<string> {
-  const directoryPrefix = join(tmpdir(), 'agent-terminal-');
+  const directoryPrefix = join(tmpdir(), 'agent-tty-');
   const temporaryDirectory = await mkdtemp(directoryPrefix);
   await rm(temporaryDirectory, { recursive: true, force: true });
   return `temp dir ok: ${tmpdir()}`;
 }
 
 export function runHomeIsolationCheck(): string {
-  const configuredHome = process.env.AGENT_TERMINAL_HOME;
+  const configuredHome = process.env.AGENT_TTY_HOME;
   if (configuredHome === undefined) {
     return 'Agent-terminal home uses default location';
   }
@@ -750,9 +750,7 @@ async function runGhosttyWebAvailableCheck(): Promise<string> {
 
 async function runScreenshotViabilityCheck(): Promise<string> {
   const chromium = await getPlaywrightChromium();
-  const temporaryDirectory = await mkdtemp(
-    join(tmpdir(), 'agent-terminal-doctor-'),
-  );
+  const temporaryDirectory = await mkdtemp(join(tmpdir(), 'agent-tty-doctor-'));
   const screenshotPath = join(temporaryDirectory, 'smoke-check.png');
   let browser: BrowserLike | null = null;
 
diff --git a/src/cli/commands/inputSource.ts b/src/cli/commands/inputSource.ts
index 7136484..4512b9f 100644
--- a/src/cli/commands/inputSource.ts
+++ b/src/cli/commands/inputSource.ts
@@ -24,7 +24,7 @@ function createInvalidInputError(
 }
 
 function usageMessage(commandName: 'type' | 'paste' | 'run'): string {
-  return `Usage: agent-terminal ${commandName} <session-id> [text] [--file <path>]`;
+  return `Usage: agent-tty ${commandName} <session-id> [text] [--file <path>]`;
 }
 
 function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
diff --git a/src/cli/commands/skill.ts b/src/cli/commands/skill.ts
index baf52a4..d1c6aba 100644
--- a/src/cli/commands/skill.ts
+++ b/src/cli/commands/skill.ts
@@ -8,7 +8,7 @@ import { ERROR_CODES, makeCliError } from '../../protocol/errors.js';
 import { assertString, invariant } from '../../util/assert.js';
 
 const COMMAND_NAME = 'skill';
-const SKILL_NAME = 'agent-terminal';
+const SKILL_NAME = 'agent-tty';
 const SKILL_SOURCE = 'packaged-file';
 
 export interface SkillResult {
@@ -24,10 +24,7 @@ export interface SkillDependencies {
 
 const DEFAULT_SKILL_DEPENDENCIES: SkillDependencies = {
   readFile: (path, encoding) => readFile(path, encoding),
-  skillFileUrl: new URL(
-    '../../../skills/agent-terminal/SKILL.md',
-    import.meta.url,
-  ),
+  skillFileUrl: new URL('../../../skills/agent-tty/SKILL.md', import.meta.url),
 };
 
 export async function loadPackagedSkillContent(
diff --git a/src/cli/commands/version.ts b/src/cli/commands/version.ts
index c5ce402..e05029c 100644
--- a/src/cli/commands/version.ts
+++ b/src/cli/commands/version.ts
@@ -90,7 +90,7 @@ export async function runVersionCommand(options: {
     json: options.json,
     result,
     lines: [
-      `agent-terminal ${result.cliVersion}`,
+      `agent-tty ${result.cliVersion}`,
       `protocol ${result.protocolVersion}`,
       `runtime ${result.runtime.node} (${result.runtime.platform}/${result.runtime.arch})`,
     ],
diff --git a/src/cli/context.ts b/src/cli/context.ts
index f77f737..c509fe5 100644
--- a/src/cli/context.ts
+++ b/src/cli/context.ts
@@ -104,23 +104,23 @@ export async function resolveCommandContext(
   options: GlobalCliOptions,
   env: NodeJS.ProcessEnv = process.env,
 ): Promise<CommandContext> {
-  const configuredHome = options.home ?? env.AGENT_TERMINAL_HOME;
+  const configuredHome = options.home ?? env.AGENT_TTY_HOME;
   const home =
     configuredHome === undefined
-      ? resolveHome(env.AGENT_TERMINAL_HOME)
+      ? resolveHome(env.AGENT_TTY_HOME)
       : validateHomePath(
           configuredHome,
-          options.home !== undefined ? '--home' : 'AGENT_TERMINAL_HOME',
+          options.home !== undefined ? '--home' : 'AGENT_TTY_HOME',
         );
   const configFile = await loadConfigFile(home);
   const logLevel = resolveLogLevel(
-    options.logLevel ?? env.AGENT_TERMINAL_LOG_LEVEL ?? configFile?.logLevel,
+    options.logLevel ?? env.AGENT_TTY_LOG_LEVEL ?? configFile?.logLevel,
   );
   const logger = createLogger(logLevel);
   const profileDefault =
     options.profileDefault ??
     options.profile ??
-    env.AGENT_TERMINAL_PROFILE ??
+    env.AGENT_TTY_PROFILE ??
     configFile?.defaultProfile;
 
   return Object.freeze({
diff --git a/src/cli/main.ts b/src/cli/main.ts
index 1afbdd8..1dedcd4 100644
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -108,21 +108,21 @@ function wrapAction<Args extends unknown[]>(
 }
 
 const CODING_AGENT_HELP_INTRO =
-  'MANDATORY FOR CODING AGENTS: read the `agent-terminal` skill first. If your agent already loaded that skill, follow it; otherwise run `agent-terminal skill` before any other agent-terminal command.';
+  'MANDATORY FOR CODING AGENTS: read the `agent-tty` skill first. If your agent already loaded that skill, follow it; otherwise run `agent-tty skill` before any other agent-tty command.';
 const CODING_AGENT_HELP_OUTRO =
-  'Coding agents: use the preloaded `agent-terminal` skill when available; otherwise call `agent-terminal skill` before using session commands.';
+  'Coding agents: use the preloaded `agent-tty` skill when available; otherwise call `agent-tty skill` before using session commands.';
 const SKILL_COMMAND_DESCRIPTION =
   'Fallback first step for coding agents: print the packaged skill if it is not already loaded';
 
 async function main(): Promise<void> {
   const program = new Command()
-    .name('agent-terminal')
+    .name('agent-tty')
     .description('CLI for managing and controlling terminal sessions')
     .showHelpAfterError()
     .exitOverride();
 
   program
-    .option('--home <path>', 'Override the agent-terminal home directory')
+    .option('--home <path>', 'Override the agent-tty home directory')
     .option(
       '--timeout-ms <n>',
       'Set a shared CLI timeout in milliseconds',
@@ -136,14 +136,14 @@ async function main(): Promise<void> {
     const context = await resolveCommandContext(
       actionCommand.optsWithGlobals<GlobalCliOptions>(),
     );
-    process.env.AGENT_TERMINAL_HOME = context.home;
+    process.env.AGENT_TTY_HOME = context.home;
     // Propagate the resolved log level to the process environment so that
     // subsystems instantiated outside the CLI context (e.g., renderer backends,
     // host processes) inherit the correct level via createProcessLogger().
     // This is intentional: threading a Logger instance through every factory
     // and constructor is a larger refactor with no user-visible benefit, since
     // the env var is set before any command handler runs.
-    process.env.AGENT_TERMINAL_LOG_LEVEL = context.logLevel;
+    process.env.AGENT_TTY_LOG_LEVEL = context.logLevel;
     setColorEnabled(context.colorEnabled);
     setCommandContext(actionCommand, context);
     context.logger.debug('resolved command context', {
@@ -753,7 +753,7 @@ try {
     process.exitCode = error.code === 'commander.helpDisplayed' ? 0 : 2;
   } else if (error instanceof CliError) {
     setColorEnabled(!process.argv.includes('--no-color'));
-    emitCliError('agent-terminal', error);
+    emitCliError('agent-tty', error);
   } else {
     throw error;
   }
diff --git a/src/config/resolveConfig.ts b/src/config/resolveConfig.ts
index 1ee1eca..91f66d4 100644
--- a/src/config/resolveConfig.ts
+++ b/src/config/resolveConfig.ts
@@ -27,7 +27,7 @@ export const ConfigFileSchema = z
   .strict();
 export type ConfigFile = z.infer<typeof ConfigFileSchema>;
 
-export interface AgentTerminalConfig {
+export interface AgentTtyConfig {
   readonly home: string;
   readonly cols: number;
   readonly rows: number;
@@ -101,7 +101,7 @@ export async function loadConfigFile(home: string): Promise<ConfigFile | null> {
   return result.data;
 }
 
-export function resolveConfig(): Readonly<AgentTerminalConfig> {
+export function resolveConfig(): Readonly<AgentTtyConfig> {
   return Object.freeze({
     home: resolveHome(),
     cols: DEFAULT_COLS,
diff --git a/src/export/webm.ts b/src/export/webm.ts
index 6102184..cecdad4 100644
--- a/src/export/webm.ts
+++ b/src/export/webm.ts
@@ -146,7 +146,7 @@ export async function generateWebmExport(
     480,
     Math.ceil(rows * profile.fontSize * 1.5) + 32,
   );
-  const videoTmpDir = await mkdtemp(join(tmpdir(), 'agent-terminal-webm-'));
+  const videoTmpDir = await mkdtemp(join(tmpdir(), 'agent-tty-webm-'));
   let backend: VideoCapableRendererBackend | null = null;
 
   try {
diff --git a/src/host/lifecycle.ts b/src/host/lifecycle.ts
index e2472f1..9457bb3 100644
--- a/src/host/lifecycle.ts
+++ b/src/host/lifecycle.ts
@@ -454,7 +454,7 @@ export function launchHost(config: LaunchHostConfig): number {
       env: {
         ...process.env,
         ...config.env,
-        AGENT_TERMINAL_HOME: config.home,
+        AGENT_TTY_HOME: config.home,
         TERM: config.term,
       },
     },
diff --git a/src/index.ts b/src/index.ts
index f3756cc..c9c3f78 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -35,4 +35,4 @@ export type {
   SessionStatus,
 } from './protocol/schemas.js';
 export type { ProtocolErrorCode } from './protocol/errors.js';
-export type { AgentTerminalConfig } from './config/resolveConfig.js';
+export type { AgentTtyConfig } from './config/resolveConfig.js';
diff --git a/src/renderer/ghosttyWeb/backend.ts b/src/renderer/ghosttyWeb/backend.ts
index 94bd5bf..01a3c3d 100644
--- a/src/renderer/ghosttyWeb/backend.ts
+++ b/src/renderer/ghosttyWeb/backend.ts
@@ -91,8 +91,8 @@ interface GhosttyBrowserBridge {
 }
 
 interface GhosttyBrowserGlobal {
-  __agentTerminal?: GhosttyBrowserBridge;
-  __agentTerminalLog?: (
+  __agentTty?: GhosttyBrowserBridge;
+  __agentTtyLog?: (
     level: LogLevel,
     message: string,
     detail?: string,
@@ -141,7 +141,7 @@ const EMBEDDED_HARNESS_HTML = `<!doctype html>
       name="viewport"
       content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
     />
-    <title>agent-terminal ghostty-web harness</title>
+    <title>agent-tty ghostty-web harness</title>
     <style>
       :root {
         color-scheme: light dark;
@@ -215,11 +215,11 @@ const EMBEDDED_HARNESS_HTML = `<!doctype html>
       const terminalShell = document.getElementById('terminal-shell');
 
       function log(level, message, detail) {
-        if (typeof globalThis.__agentTerminalLog !== 'function') {
+        if (typeof globalThis.__agentTtyLog !== 'function') {
           return;
         }
 
-        void globalThis.__agentTerminalLog(level, message, detail);
+        void globalThis.__agentTtyLog(level, message, detail);
       }
 
       function invariant(condition, message) {
@@ -658,7 +658,7 @@ const EMBEDDED_HARNESS_HTML = `<!doctype html>
         document.body.dataset.rows = String(rows);
       }
 
-      window.__agentTerminal = {
+      window.__agentTty = {
         async write(data) {
           const terminal = getReadyTerminal();
           assertStringValue(data, 'write() data must be a string');
@@ -1277,7 +1277,7 @@ export class GhosttyWebBackend implements VideoCapableRendererBackend {
     sessionId: string,
     profile: RenderProfileConfig,
     videoOptions?: VideoRecordingOptions,
-    // The default logger reads AGENT_TERMINAL_LOG_LEVEL from process.env at
+    // The default logger reads AGENT_TTY_LOG_LEVEL from process.env at
     // construction time. In CLI flows, main.ts sets this env var in preAction
     // before any command handler runs, so the effective level is correct.
     // Callers may pass an explicit Logger for testing or non-CLI contexts.
@@ -1954,7 +1954,7 @@ export class GhosttyWebBackend implements VideoCapableRendererBackend {
     const page = this.requireOperationalPage('getVisibleText()');
 
     const visibleText = await page.evaluate(() => {
-      const bridge = (globalThis as GhosttyBrowserGlobal).__agentTerminal;
+      const bridge = (globalThis as GhosttyBrowserGlobal).__agentTty;
       if (bridge === undefined || typeof bridge.getVisibleText !== 'function') {
         throw new Error('ghostty-web bridge getVisibleText() is unavailable');
       }
@@ -2034,7 +2034,7 @@ export class GhosttyWebBackend implements VideoCapableRendererBackend {
 
       this.page = await this.browserContext.newPage();
       await this.page.exposeFunction(
-        '__agentTerminalLog',
+        '__agentTtyLog',
         (level: unknown, message: unknown, detail?: unknown) => {
           assertLogLevel(level, 'ghostty-web harness log level must be valid');
           assertString(
@@ -2089,7 +2089,7 @@ export class GhosttyWebBackend implements VideoCapableRendererBackend {
       });
       await this.page.waitForFunction(
         () => {
-          const bridge = (globalThis as GhosttyBrowserGlobal).__agentTerminal;
+          const bridge = (globalThis as GhosttyBrowserGlobal).__agentTty;
           return (
             bridge !== undefined &&
             typeof bridge.isReady === 'function' &&
@@ -2101,7 +2101,7 @@ export class GhosttyWebBackend implements VideoCapableRendererBackend {
       );
 
       const bridgeReady = await this.page.evaluate(() => {
-        const bridge = (globalThis as GhosttyBrowserGlobal).__agentTerminal;
+        const bridge = (globalThis as GhosttyBrowserGlobal).__agentTty;
         return (
           bridge !== undefined &&
           typeof bridge.isReady === 'function' &&
@@ -2241,7 +2241,7 @@ export class GhosttyWebBackend implements VideoCapableRendererBackend {
 
     const snapshot = await page.evaluate(
       (opts) => {
-        const bridge = (globalThis as GhosttyBrowserGlobal).__agentTerminal;
+        const bridge = (globalThis as GhosttyBrowserGlobal).__agentTty;
         if (bridge === undefined || typeof bridge.getSnapshot !== 'function') {
           throw new Error('ghostty-web bridge getSnapshot() is unavailable');
         }
@@ -2331,7 +2331,7 @@ export class GhosttyWebBackend implements VideoCapableRendererBackend {
 
     await page.evaluate(
       async ([nextCols, nextRows]) => {
-        const bridge = (globalThis as GhosttyBrowserGlobal).__agentTerminal;
+        const bridge = (globalThis as GhosttyBrowserGlobal).__agentTty;
         if (bridge === undefined || typeof bridge.resize !== 'function') {
           throw new Error('ghostty-web bridge resize() is unavailable');
         }
@@ -2347,7 +2347,7 @@ export class GhosttyWebBackend implements VideoCapableRendererBackend {
     visible: boolean,
   ): Promise<void> {
     await page.evaluate((showCursorInScreenshot: boolean) => {
-      const bridge = (globalThis as GhosttyBrowserGlobal).__agentTerminal;
+      const bridge = (globalThis as GhosttyBrowserGlobal).__agentTty;
       if (
         bridge === undefined ||
         typeof bridge.setCursorVisible !== 'function'
@@ -2505,7 +2505,7 @@ export class GhosttyWebBackend implements VideoCapableRendererBackend {
     }
 
     await page.evaluate(async (chunks: string[]) => {
-      const bridge = (globalThis as GhosttyBrowserGlobal).__agentTerminal;
+      const bridge = (globalThis as GhosttyBrowserGlobal).__agentTty;
       if (bridge === undefined || typeof bridge.write !== 'function') {
         throw new Error('ghostty-web bridge write() is unavailable');
       }
@@ -2520,7 +2520,7 @@ export class GhosttyWebBackend implements VideoCapableRendererBackend {
     assertString(data, 'bridge write data must be a string');
 
     await page.evaluate(async (nextData) => {
-      const bridge = (globalThis as GhosttyBrowserGlobal).__agentTerminal;
+      const bridge = (globalThis as GhosttyBrowserGlobal).__agentTty;
       if (bridge === undefined || typeof bridge.write !== 'function') {
         throw new Error('ghostty-web bridge write() is unavailable');
       }
diff --git a/src/renderer/ghosttyWeb/harness.html b/src/renderer/ghosttyWeb/harness.html
index f870fa2..89bb80d 100644
--- a/src/renderer/ghosttyWeb/harness.html
+++ b/src/renderer/ghosttyWeb/harness.html
@@ -6,7 +6,7 @@
       name="viewport"
       content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
     />
-    <title>agent-terminal ghostty-web harness</title>
+    <title>agent-tty ghostty-web harness</title>
     <style>
       :root {
         color-scheme: light dark;
@@ -491,7 +491,7 @@
         document.body.dataset.rows = String(rows);
       }
 
-      window.__agentTerminal = {
+      window.__agentTty = {
         async write(data) {
           const terminal = getReadyTerminal();
           assertStringValue(data, 'write() data must be a string');
diff --git a/src/storage/home.ts b/src/storage/home.ts
index b80ed46..8baa652 100644
--- a/src/storage/home.ts
+++ b/src/storage/home.ts
@@ -6,7 +6,7 @@ import process from 'node:process';
 
 import { invariant } from '../util/assert.js';
 
-const DEFAULT_HOME_DIRECTORY_NAME = '.agent-terminal';
+const DEFAULT_HOME_DIRECTORY_NAME = '.agent-tty';
 
 function validateConfiguredHome(
   configuredHome: string,
@@ -24,18 +24,15 @@ function validateConfiguredHome(
 }
 
 export function resolveHome(
-  configuredHome = process.env.AGENT_TERMINAL_HOME,
+  configuredHome = process.env.AGENT_TTY_HOME,
 ): string {
   if (configuredHome !== undefined) {
-    return validateConfiguredHome(configuredHome, 'AGENT_TERMINAL_HOME');
+    return validateConfiguredHome(configuredHome, 'AGENT_TTY_HOME');
   }
 
   const normalized = normalize(join(homedir(), DEFAULT_HOME_DIRECTORY_NAME));
 
-  invariant(
-    isAbsolute(normalized),
-    'resolved agent-terminal home must be absolute',
-  );
+  invariant(isAbsolute(normalized), 'resolved agent-tty home must be absolute');
 
   try {
     return realpathSync(normalized);
@@ -45,7 +42,7 @@ export function resolveHome(
 }
 
 export async function ensureHome(
-  configuredHome = process.env.AGENT_TERMINAL_HOME,
+  configuredHome = process.env.AGENT_TTY_HOME,
 ): Promise<string> {
   const home = resolveHome(configuredHome);
 
diff --git a/src/tools/review-bundle.ts b/src/tools/review-bundle.ts
index d58ec58..0156512 100644
--- a/src/tools/review-bundle.ts
+++ b/src/tools/review-bundle.ts
@@ -136,7 +136,7 @@ const SUPPORT_FILE_NAMES = new Set([
   'command-status.tsv',
   'doctor.json',
   'session-id.txt',
-  'agent-terminal-home.txt',
+  'agent-tty-home.txt',
   'events.jsonl',
   'event-log.jsonl',
 ]);
diff --git a/src/util/logger.ts b/src/util/logger.ts
index 186cb79..f2fd273 100644
--- a/src/util/logger.ts
+++ b/src/util/logger.ts
@@ -126,7 +126,7 @@ export class Logger {
       details.length === 0
         ? ''
         : ` ${details.map((detail) => formatLogDetail(detail)).join(' ')}`;
-    this.sink(`[agent-terminal] ${level}: ${message}${suffix}\n`);
+    this.sink(`[agent-tty] ${level}: ${message}${suffix}\n`);
   }
 }
 
@@ -138,5 +138,5 @@ export function createProcessLogger(
   env: NodeJS.ProcessEnv = process.env,
   sink?: LogSink,
 ): Logger {
-  return createLogger(resolveLogLevel(env.AGENT_TERMINAL_LOG_LEVEL), sink);
+  return createLogger(resolveLogLevel(env.AGENT_TTY_LOG_LEVEL), sink);
 }
diff --git a/test/e2e/export-fixtures.test.ts b/test/e2e/export-fixtures.test.ts
index 9c5fce7..38c34d8 100644
--- a/test/e2e/export-fixtures.test.ts
+++ b/test/e2e/export-fixtures.test.ts
@@ -34,7 +34,7 @@ const RENDER_WAIT_TIMEOUT_MS = 10_000;
 const WEBM_TIMEOUT_MS = 120_000;
 
 function testEnv(home: string): Record<string, string> {
-  return { AGENT_TERMINAL_HOME: home };
+  return { AGENT_TTY_HOME: home };
 }
 
 function withJsonFlag(args: string[]): string[] {
diff --git a/test/e2e/hello-prompt.test.ts b/test/e2e/hello-prompt.test.ts
index cc4bb38..41db4fa 100644
--- a/test/e2e/hello-prompt.test.ts
+++ b/test/e2e/hello-prompt.test.ts
@@ -36,7 +36,7 @@ interface SendKeysResult {
 }
 
 function testEnv(home: string): Record<string, string> {
-  return { AGENT_TERMINAL_HOME: home };
+  return { AGENT_TTY_HOME: home };
 }
 
 describe('hello-prompt e2e', { timeout: 30_000 }, () => {
diff --git a/test/e2e/helpers.ts b/test/e2e/helpers.ts
index cc5de86..3f9d905 100644
--- a/test/e2e/helpers.ts
+++ b/test/e2e/helpers.ts
@@ -55,7 +55,7 @@ export function normalizeTerminalOutput(output: string): string {
 
 export async function createIsolatedHome(): Promise<string> {
   // prettier-ignore
-  const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-e2e-home-')));
+  const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-e2e-home-')));
   return home;
 }
 
diff --git a/test/e2e/renderer-errors.test.ts b/test/e2e/renderer-errors.test.ts
index 8e31c4d..70d215a 100644
--- a/test/e2e/renderer-errors.test.ts
+++ b/test/e2e/renderer-errors.test.ts
@@ -66,7 +66,7 @@ describe('renderer error paths e2e', { timeout: 120_000 }, () => {
 
     const envelope = runCliErrorEnvelope(
       ['screenshot', sessionId, '--profile', 'nonexistent-profile'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
 
     expect(envelope.command).toBe('screenshot');
@@ -84,7 +84,7 @@ describe('renderer error paths e2e', { timeout: 120_000 }, () => {
 
     const envelope = runCliErrorEnvelope(
       ['screenshot', sessionId, '--profile', oversizedProfile],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
 
     expect(profileValidation.success).toBe(false);
@@ -121,14 +121,14 @@ describe('renderer error paths e2e', { timeout: 120_000 }, () => {
 
     const waitResult = runCli(
       ['wait', sessionId, '--exit', '--timeout', '10000', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
     expect(waitResult.exitCode).toBe(0);
     expect(waitResult.stderr).toBe('');
 
     const result = runCli(['snapshot', sessionId, '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
 
     expect(result.exitCode).toBe(0);
@@ -157,7 +157,7 @@ describe('renderer error paths e2e', { timeout: 120_000 }, () => {
 
     const envelope = runCliErrorEnvelope(
       ['wait', sessionId, '--text', repeatCharacter(1001)],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
 
@@ -173,7 +173,7 @@ describe('renderer error paths e2e', { timeout: 120_000 }, () => {
 
     const envelope = runCliErrorEnvelope(
       ['wait', sessionId, '--regex', repeatCharacter(201)],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
 
@@ -189,7 +189,7 @@ describe('renderer error paths e2e', { timeout: 120_000 }, () => {
 
     const envelope = runCliErrorEnvelope(
       ['wait', sessionId, '--regex', '(a+)+'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
 
@@ -204,7 +204,7 @@ describe('renderer error paths e2e', { timeout: 120_000 }, () => {
 
     const envelope = runCliErrorEnvelope(
       ['wait', sessionId, '--regex', '[invalid('],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
 
@@ -219,7 +219,7 @@ describe('renderer error paths e2e', { timeout: 120_000 }, () => {
 
     const envelope = runCliErrorEnvelope(
       ['wait', sessionId, '--text', 'hello', '--regex', 'world'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
 
     expect(envelope.command).toBe('wait');
@@ -233,7 +233,7 @@ describe('renderer error paths e2e', { timeout: 120_000 }, () => {
 
     const envelope = runCliErrorEnvelope(
       ['wait', sessionId, '--exit', '--text', 'hello'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
 
     expect(envelope.command).toBe('wait');
diff --git a/test/e2e/renderer-slice.test.ts b/test/e2e/renderer-slice.test.ts
index 9cbe3e1..a9e988f 100644
--- a/test/e2e/renderer-slice.test.ts
+++ b/test/e2e/renderer-slice.test.ts
@@ -32,7 +32,7 @@ const SCREEN_STABLE_MS = 1_000;
 const PNG_MAGIC_HEX = '89504e470d0a1a0a';
 
 function testEnv(home: string): Record<string, string> {
-  return { AGENT_TERMINAL_HOME: home };
+  return { AGENT_TTY_HOME: home };
 }
 
 function withJsonFlag(args: string[]): string[] {
diff --git a/test/e2e/resize-demo.test.ts b/test/e2e/resize-demo.test.ts
index 60b0e3d..daf22d8 100644
--- a/test/e2e/resize-demo.test.ts
+++ b/test/e2e/resize-demo.test.ts
@@ -34,7 +34,7 @@ interface SendKeysResult {
 }
 
 function testEnv(home: string): Record<string, string> {
-  return { AGENT_TERMINAL_HOME: home };
+  return { AGENT_TTY_HOME: home };
 }
 
 describe('resize-demo e2e', { timeout: 30_000 }, () => {
diff --git a/test/e2e/scrollback-demo.test.ts b/test/e2e/scrollback-demo.test.ts
index 15533ad..95ae98b 100644
--- a/test/e2e/scrollback-demo.test.ts
+++ b/test/e2e/scrollback-demo.test.ts
@@ -26,7 +26,7 @@ const PNG_MAGIC_HEX = '89504e470d0a1a0a';
 const EXIT_WAIT_TIMEOUT_MS = 15_000;
 
 function testEnv(home: string): Record<string, string> {
-  return { AGENT_TERMINAL_HOME: home };
+  return { AGENT_TTY_HOME: home };
 }
 
 function expectStructuredSnapshot(
diff --git a/test/e2e/unicode-grid.test.ts b/test/e2e/unicode-grid.test.ts
index 33d988f..8dd5486 100644
--- a/test/e2e/unicode-grid.test.ts
+++ b/test/e2e/unicode-grid.test.ts
@@ -27,7 +27,7 @@ interface CreateResult {
 const PNG_MAGIC_HEX = '89504e470d0a1a0a';
 
 function testEnv(home: string): Record<string, string> {
-  return { AGENT_TERMINAL_HOME: home };
+  return { AGENT_TTY_HOME: home };
 }
 
 function expectTextSnapshot(
diff --git a/test/helpers.ts b/test/helpers.ts
index 71e8135..c3b45bd 100644
--- a/test/helpers.ts
+++ b/test/helpers.ts
@@ -121,7 +121,7 @@ export function createSession(
   command: string[] = ['/bin/sh', '-c', 'exec cat'],
 ): string {
   const result = runCli(['create', '--json', '--', ...command], {
-    AGENT_TERMINAL_HOME: testHome,
+    AGENT_TTY_HOME: testHome,
   });
   expect(result.status).toBe(0);
   expect(result.stderr).toBe('');
@@ -139,7 +139,7 @@ export function destroySession(testHome: string, sessionId: string): void {
   }
 
   runCli(['destroy', sessionId, '--json'], {
-    AGENT_TERMINAL_HOME: testHome,
+    AGENT_TTY_HOME: testHome,
   });
 }
 
@@ -165,7 +165,7 @@ export function inspectSession(
   sessionId: string,
 ): SessionRecord {
   const result = runCli(['inspect', sessionId, '--json'], {
-    AGENT_TERMINAL_HOME: testHome,
+    AGENT_TTY_HOME: testHome,
   });
   expect(result.status).toBe(0);
   expect(result.stderr).toBe('');
diff --git a/test/integration/cli.test.ts b/test/integration/cli.test.ts
index c5f18f2..9c1bc43 100644
--- a/test/integration/cli.test.ts
+++ b/test/integration/cli.test.ts
@@ -29,7 +29,7 @@ interface ErrorEnvelope {
 let testHome = '';
 
 function testEnv(): Record<string, string> {
-  return { AGENT_TERMINAL_HOME: testHome };
+  return { AGENT_TTY_HOME: testHome };
 }
 
 function parseErrorEnvelope(output: string): CommandErrorEnvelope {
@@ -37,23 +37,15 @@ function parseErrorEnvelope(output: string): CommandErrorEnvelope {
 }
 
 function readPackagedSkill(): string {
-  return readFileSync('skills/agent-terminal/SKILL.md', 'utf8');
+  return readFileSync('skills/agent-tty/SKILL.md', 'utf8');
 }
 
-function readPackageVersion(): string {
-  const packageJson = JSON.parse(readFileSync('package.json', 'utf8')) as {
-    version: unknown;
-  };
-  if (typeof packageJson.version !== 'string') {
-    throw new TypeError('package.json version must be a string');
-  }
-  return packageJson.version;
-}
+const SEMVER_WITH_OPTIONAL_PRERELEASE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 
 describe('CLI integration', () => {
   beforeEach(() => {
     // prettier-ignore
-    testHome = realpathSync(mkdtempSync(join(tmpdir(), 'agent-terminal-cli-home-')));
+    testHome = realpathSync(mkdtempSync(join(tmpdir(), 'agent-tty-cli-home-')));
   });
 
   afterEach(() => {
@@ -73,7 +65,7 @@ describe('CLI integration', () => {
 
     expect(parsed.ok).toBe(true);
     expect(parsed.command).toBe('version');
-    expect(parsed.result.cliVersion).toBe(readPackageVersion());
+    expect(parsed.result.cliVersion).toMatch(SEMVER_WITH_OPTIONAL_PRERELEASE);
     expect(parsed.result.rendererBackends).toEqual(['ghostty-web']);
   });
 
@@ -100,7 +92,7 @@ describe('CLI integration', () => {
     expect(parsed.ok).toBe(true);
     expect(parsed.command).toBe('skill');
     expect(parsed.result).toEqual({
-      name: 'agent-terminal',
+      name: 'agent-tty',
       source: 'packaged-file',
       content: readPackagedSkill(),
     });
@@ -113,14 +105,14 @@ describe('CLI integration', () => {
     expect(result.stderr).toBe('');
     expect(result.stdout.startsWith('MANDATORY FOR CODING AGENTS:')).toBe(true);
     expect(result.stdout).toContain(
-      'If your agent already loaded that skill, follow it; otherwise run `agent-terminal skill` before any other agent-terminal command.',
+      'If your agent already loaded that skill, follow it; otherwise run `agent-tty skill` before any other agent-tty command.',
     );
     expect(result.stdout).toContain('skill [options]');
     expect(result.stdout).toContain(
       'Fallback first step for coding agents: print the packaged skill if it is not already loaded',
     );
     expect(result.stdout).toContain(
-      'Coding agents: use the preloaded `agent-terminal` skill when available; otherwise call `agent-terminal skill` before using session commands.',
+      'Coding agents: use the preloaded `agent-tty` skill when available; otherwise call `agent-tty skill` before using session commands.',
     );
   });
 
@@ -293,9 +285,9 @@ describe('CLI integration', () => {
     expect(allChecks.every((check) => check.status === 'pass')).toBe(true);
   });
 
-  it('uses --home instead of AGENT_TERMINAL_HOME', () => {
+  it('uses --home instead of AGENT_TTY_HOME', () => {
     // prettier-ignore
-    const overrideHome = realpathSync(mkdtempSync(join(tmpdir(), 'agent-terminal-cli-override-')));
+    const overrideHome = realpathSync(mkdtempSync(join(tmpdir(), 'agent-tty-cli-override-')));
 
     try {
       const result = runCli(
@@ -360,7 +352,7 @@ describe('CLI integration', () => {
     expect(result.status).toBe(0);
     expect(result.stderr).not.toBe('');
     expect(result.stderr).toContain(
-      '[agent-terminal] debug: resolved command context',
+      '[agent-tty] debug: resolved command context',
     );
 
     const parsed = JSON.parse(result.stdout) as SuccessEnvelope<{
@@ -398,7 +390,7 @@ describe('CLI integration', () => {
     const parsed = JSON.parse(result.stdout) as ErrorEnvelope;
 
     expect(parsed.ok).toBe(false);
-    expect(parsed.command).toBe('agent-terminal');
+    expect(parsed.command).toBe('agent-tty');
     expect(parsed.error.code).toBe('INVALID_INPUT');
     expect(parsed.error.message).toBe(
       'Log level must be one of debug, info, warn, or error.',
@@ -416,7 +408,7 @@ describe('CLI integration', () => {
     const parsed = JSON.parse(result.stdout) as ErrorEnvelope;
 
     expect(parsed.ok).toBe(false);
-    expect(parsed.command).toBe('agent-terminal');
+    expect(parsed.command).toBe('agent-tty');
     expect(parsed.error.code).toBe('INVALID_INPUT');
     expect(parsed.error.message).toBe('--home must be an absolute path.');
   });
@@ -425,7 +417,7 @@ describe('CLI integration', () => {
     const result = runCli(['--no-color', 'version'], testEnv());
     expect(result.status).toBe(0);
     expect(result.stderr).toBe('');
-    expect(result.stdout).toContain('agent-terminal');
+    expect(result.stdout).toContain('agent-tty');
     expect(result.stdout).not.toContain('\u001b[');
   });
 });
diff --git a/test/integration/event-log.test.ts b/test/integration/event-log.test.ts
index 6dd72e5..6f9fcc8 100644
--- a/test/integration/event-log.test.ts
+++ b/test/integration/event-log.test.ts
@@ -16,7 +16,7 @@ import {
 } from '../helpers.js';
 
 function runMixedActionSequence(testHome: string, sessionId: string): void {
-  const env = { AGENT_TERMINAL_HOME: testHome };
+  const env = { AGENT_TTY_HOME: testHome };
 
   const typeResult = runCli(['type', sessionId, 'hello', '--json'], env);
   expect(typeResult.status).toBe(0);
@@ -57,7 +57,7 @@ let testHome = '';
 describe('event-log integration', { timeout: 30000 }, () => {
   beforeEach(async () => {
     // prettier-ignore
-    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-home-')));
+    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-home-')));
   });
 
   afterEach(async () => {
diff --git a/test/integration/gc.test.ts b/test/integration/gc.test.ts
index 6c6c950..c1bd1a9 100644
--- a/test/integration/gc.test.ts
+++ b/test/integration/gc.test.ts
@@ -39,7 +39,7 @@ let testHome = '';
 describe('gc integration', { timeout: 30000 }, () => {
   beforeEach(async () => {
     // prettier-ignore
-    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-gc-')));
+    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-gc-')));
   });
 
   afterEach(async () => {
@@ -55,14 +55,14 @@ describe('gc integration', { timeout: 30000 }, () => {
     const sessionDirectory = join(testHome, 'sessions', sessionId);
 
     const destroyResult = runCli(['destroy', sessionId, '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(destroyResult.status).toBe(0);
     expect(destroyResult.stderr).toBe('');
     expect(await pathExists(sessionDirectory)).toBe(true);
 
     const gcResult = runCli(['gc', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(gcResult.status).toBe(0);
     expect(gcResult.stderr).toBe('');
@@ -98,7 +98,7 @@ describe('gc integration', { timeout: 30000 }, () => {
     expect(destroyedSession.status).toBe('destroyed');
 
     const gcResult = runCli(['gc', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(gcResult.status).toBe(0);
     expect(gcResult.stderr).toBe('');
diff --git a/test/integration/host-renderer-rpc.test.ts b/test/integration/host-renderer-rpc.test.ts
index 69580de..ddb755f 100644
--- a/test/integration/host-renderer-rpc.test.ts
+++ b/test/integration/host-renderer-rpc.test.ts
@@ -39,7 +39,7 @@ async function waitForOutputMarker(
 ): Promise<void> {
   const waitResult = runCli(
     ['wait', sessionId, '--idle-ms', '2000', '--timeout', '10000', '--json'],
-    { AGENT_TERMINAL_HOME: testHome },
+    { AGENT_TTY_HOME: testHome },
     15_000,
   );
 
@@ -83,7 +83,7 @@ describe(
 
     beforeEach(async () => {
       // prettier-ignore
-      testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-host-renderer-')));
+      testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-host-renderer-')));
       sessionId = createSession(testHome, [
         '/bin/sh',
         '-c',
diff --git a/test/integration/io-loop.test.ts b/test/integration/io-loop.test.ts
index d5de410..cfae327 100644
--- a/test/integration/io-loop.test.ts
+++ b/test/integration/io-loop.test.ts
@@ -21,7 +21,7 @@ let testHome = '';
 describe('io-loop integration', { timeout: 30000 }, () => {
   beforeEach(async () => {
     // prettier-ignore
-    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-home-')));
+    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-home-')));
   });
 
   afterEach(async () => {
@@ -38,7 +38,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
       const typeResult = runCli(
         ['type', sessionId, 'echo test-marker', '--json'],
         {
-          AGENT_TERMINAL_HOME: testHome,
+          AGENT_TTY_HOME: testHome,
         },
       );
       expect(typeResult.status).toBe(0);
@@ -47,7 +47,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
       const sendKeysResult = runCli(
         ['send-keys', sessionId, 'Enter', '--json'],
         {
-          AGENT_TERMINAL_HOME: testHome,
+          AGENT_TTY_HOME: testHome,
         },
       );
       expect(sendKeysResult.status).toBe(0);
@@ -55,7 +55,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
 
       const waitResult = runCli(
         ['wait', sessionId, '--idle-ms', '500', '--timeout', '5000', '--json'],
-        { AGENT_TERMINAL_HOME: testHome },
+        { AGENT_TTY_HOME: testHome },
         30000,
       );
       expect(waitResult.status).toBe(0);
@@ -92,7 +92,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
       const start = Date.now();
       const waitResult = runCli(
         ['wait', sessionId, '--idle-ms', '1000', '--timeout', '5000', '--json'],
-        { AGENT_TERMINAL_HOME: testHome },
+        { AGENT_TTY_HOME: testHome },
         30000,
       );
       const elapsed = Date.now() - start;
@@ -118,7 +118,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
       await sleep(500);
 
       const typeResult = runCli(['type', sessionId, 'keepalive', '--json'], {
-        AGENT_TERMINAL_HOME: testHome,
+        AGENT_TTY_HOME: testHome,
       });
       expect(typeResult.status).toBe(0);
       expect(typeResult.stderr).toBe('');
@@ -126,7 +126,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
       const sendKeysResult = runCli(
         ['send-keys', sessionId, 'Enter', '--json'],
         {
-          AGENT_TERMINAL_HOME: testHome,
+          AGENT_TTY_HOME: testHome,
         },
       );
       expect(sendKeysResult.status).toBe(0);
@@ -134,7 +134,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
 
       const waitResult = runCli(
         ['wait', sessionId, '--idle-ms', '60000', '--timeout', '300', '--json'],
-        { AGENT_TERMINAL_HOME: testHome },
+        { AGENT_TTY_HOME: testHome },
         30000,
       );
       expect(waitResult.status).toBe(0);
@@ -165,7 +165,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
           '-c',
           'exec cat',
         ],
-        { AGENT_TERMINAL_HOME: testHome },
+        { AGENT_TTY_HOME: testHome },
       );
       expect(createResult.status).toBe(0);
       expect(createResult.stderr).toBe('');
@@ -177,7 +177,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
 
       const waitResult = runCli(
         ['wait', sessionId, '--exit', '--timeout', '10000', '--json'],
-        { AGENT_TERMINAL_HOME: testHome },
+        { AGENT_TTY_HOME: testHome },
         30000,
       );
       expect(waitResult.status).toBe(0);
@@ -212,7 +212,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
           '-c',
           'exec cat',
         ],
-        { AGENT_TERMINAL_HOME: testHome },
+        { AGENT_TTY_HOME: testHome },
       );
       expect(createResult.status).toBe(0);
       expect(createResult.stderr).toBe('');
@@ -239,7 +239,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
       await sleep(500);
 
       const signalResult = runCli(['signal', sessionId, 'SIGTERM', '--json'], {
-        AGENT_TERMINAL_HOME: testHome,
+        AGENT_TTY_HOME: testHome,
       });
       expect(signalResult.status).toBe(0);
       expect(signalResult.stderr).toBe('');
@@ -257,7 +257,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
 
       const waitResult = runCli(
         ['wait', sessionId, '--exit', '--timeout', '5000', '--json'],
-        { AGENT_TERMINAL_HOME: testHome },
+        { AGENT_TTY_HOME: testHome },
         30000,
       );
       expect(waitResult.status).toBe(0);
@@ -286,7 +286,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
 
       const waitResult = runCli(
         ['wait', sessionId, '--exit', '--timeout', '5000', '--json'],
-        { AGENT_TERMINAL_HOME: testHome },
+        { AGENT_TTY_HOME: testHome },
         30000,
       );
       expect(waitResult.status).toBe(0);
@@ -314,7 +314,7 @@ describe('io-loop integration', { timeout: 30000 }, () => {
 
       const waitResult = runCli(
         ['wait', sessionId, '--exit', '--json'],
-        { AGENT_TERMINAL_HOME: testHome },
+        { AGENT_TTY_HOME: testHome },
         30000,
       );
       expect(waitResult.status).toBe(0);
diff --git a/test/integration/lifecycle.test.ts b/test/integration/lifecycle.test.ts
index 4f56f76..7f30a19 100644
--- a/test/integration/lifecycle.test.ts
+++ b/test/integration/lifecycle.test.ts
@@ -60,7 +60,7 @@ let testHome = '';
 describe('lifecycle integration', { timeout: 30000 }, () => {
   beforeEach(async () => {
     // prettier-ignore
-    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-home-')));
+    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-home-')));
   });
 
   afterEach(async () => {
@@ -70,7 +70,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
   it('full lifecycle: create → list → inspect → destroy', () => {
     const createResult = runCli(
       ['create', '--json', '--', '/bin/sh', '-c', 'echo ready; sleep 30'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
     expect(createResult.status).toBe(0);
     expect(createResult.stderr).toBe('');
@@ -83,7 +83,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     expect(sessionId.length).toBeGreaterThan(0);
 
     const listResult = runCli(['list', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(listResult.status).toBe(0);
     expect(listResult.stderr).toBe('');
@@ -103,7 +103,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     expect(listedSession?.pid).toBeTypeOf('number');
 
     const inspectResult = runCli(['inspect', sessionId, '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(inspectResult.status).toBe(0);
     expect(inspectResult.stderr).toBe('');
@@ -131,7 +131,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     expect(listedSession?.pid).toBe(inspectEnvelope.result.session.childPid);
 
     const destroyResult = runCli(['destroy', sessionId, '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(destroyResult.status).toBe(0);
     expect(destroyResult.stderr).toBe('');
@@ -148,7 +148,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
   it('exited sessions hidden by default list, visible with --all', () => {
     const createResult = runCli(
       ['create', '--json', '--', '/bin/sh', '-c', 'echo done; sleep 30'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
     expect(createResult.status).toBe(0);
     expect(createResult.stderr).toBe('');
@@ -157,13 +157,13 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     ).result.sessionId;
 
     const destroyResult = runCli(['destroy', sessionId, '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(destroyResult.status).toBe(0);
     expect(destroyResult.stderr).toBe('');
 
     const listDefault = runCli(['list', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(listDefault.status).toBe(0);
     expect(listDefault.stderr).toBe('');
@@ -177,7 +177,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     ).toBeUndefined();
 
     const listAll = runCli(['list', '--all', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(listAll.status).toBe(0);
     expect(listAll.stderr).toBe('');
@@ -218,7 +218,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
         '-c',
         'printf "%s|%s|%s" "$FOO" "$BAZ" "$TERM"; exit 0',
       ],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
     expect(createResult.status).toBe(0);
     expect(createResult.stderr).toBe('');
@@ -245,7 +245,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     expect(manifest.term).toBe('vt100');
 
     const listResult = runCli(['list', '--all', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(listResult.status).toBe(0);
     expect(listResult.stderr).toBe('');
@@ -293,7 +293,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
         '-c',
         'sleep 30',
       ],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
     expect(createResult.status).toBe(0);
     expect(createResult.stderr).toBe('');
@@ -324,7 +324,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
         '-c',
         'sleep 30',
       ],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
     expect(createResult.status).toBe(0);
     expect(createResult.stderr).toBe('');
@@ -360,7 +360,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     await chmod(shellPath, 0o755);
 
     const createResult = runCli(['create', '--shell', shellPath, '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(createResult.status).toBe(0);
     expect(createResult.stderr).toBe('');
@@ -382,7 +382,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     expect(await readFile(shellMarkerPath, 'utf8')).toContain('custom-shell');
 
     const typeResult = runCli(['type', sessionId, 'exit\n', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(typeResult.status).toBe(0);
     expect(typeResult.stderr).toBe('');
@@ -400,7 +400,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
         '-c',
         'exit 0',
       ],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
     expect(createResult.status).toBe(2);
     expect(createResult.stderr).toBe('');
@@ -415,7 +415,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     const missingShellPath = join(testHome, 'missing-shell.sh');
     const createResult = runCli(
       ['create', '--shell', missingShellPath, '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
     expect(createResult.status).toBe(2);
     expect(createResult.stderr).toBe('');
@@ -478,7 +478,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     await sleep(1000);
 
     const listResult = runCli(['list', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(
       listResult.status,
@@ -503,7 +503,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     ).toBeUndefined();
 
     const listAllResult = runCli(['list', '--all', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(
       listAllResult.status,
@@ -573,7 +573,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     ).toContain(String(hostPid));
 
     const gcResult = runCli(['gc', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(
       gcResult.status,
@@ -606,7 +606,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     ).toBeGreaterThan(0);
 
     const listAfterGcResult = runCli(['list', '--all', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(
       listAfterGcResult.status,
@@ -646,7 +646,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     expect(session.status).toBe('destroyed');
 
     const typeResult = runCli(['type', sessionId, 'hello', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(typeResult.status).not.toBe(0);
     expect(typeResult.stderr).toBe('');
@@ -673,7 +673,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     const snapshotResult = runCli(
       ['snapshot', sessionId, '--format', 'text', '--json'],
       {
-        AGENT_TERMINAL_HOME: testHome,
+        AGENT_TTY_HOME: testHome,
       },
     );
     expect(snapshotResult.status).toBe(0);
@@ -691,7 +691,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
 
   it('inspect nonexistent session returns SESSION_NOT_FOUND', () => {
     const result = runCli(['inspect', 'NONEXISTENT', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(result.status).not.toBe(0);
     expect(result.stderr).toBe('');
@@ -702,7 +702,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
 
   it('send-keys to non-existent session returns SESSION_NOT_FOUND', () => {
     const result = runCli(['send-keys', 'NONEXISTENT', 'Enter', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(result.status).not.toBe(0);
     expect(result.stderr).toBe('');
@@ -713,7 +713,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
 
   it('destroy non-existent session returns SESSION_NOT_FOUND', () => {
     const result = runCli(['destroy', 'NONEXISTENT', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(result.status).not.toBe(0);
     expect(result.stderr).toBe('');
@@ -732,7 +732,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
         '-c',
         'echo marker-test-output; exit 0',
       ],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
     expect(createResult.status).toBe(0);
     expect(createResult.stderr).toBe('');
@@ -767,7 +767,7 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     expect(exitEvents[0]?.payload.exitCode).toBe(0);
 
     const destroyResult = runCli(['destroy', sessionId, '--force', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(destroyResult.status).toBe(0);
   });
diff --git a/test/integration/pty-basics.test.ts b/test/integration/pty-basics.test.ts
index 387c2d9..636a011 100644
--- a/test/integration/pty-basics.test.ts
+++ b/test/integration/pty-basics.test.ts
@@ -26,7 +26,7 @@ let testHome = '';
 describe('pty-basics integration', { timeout: 30000 }, () => {
   beforeEach(async () => {
     // prettier-ignore
-    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-home-')));
+    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-home-')));
   });
 
   afterEach(async () => {
@@ -41,7 +41,7 @@ describe('pty-basics integration', { timeout: 30000 }, () => {
       await sleep(500);
 
       const typeResult = runCli(['type', sessionId, 'hello', '--json'], {
-        AGENT_TERMINAL_HOME: testHome,
+        AGENT_TTY_HOME: testHome,
       });
       expect(typeResult.status).toBe(0);
       expect(typeResult.stderr).toBe('');
@@ -76,7 +76,7 @@ describe('pty-basics integration', { timeout: 30000 }, () => {
       const typeResult = runCli(
         ['type', sessionId, '--file', inputPath, '--json'],
         {
-          AGENT_TERMINAL_HOME: testHome,
+          AGENT_TTY_HOME: testHome,
         },
       );
       expect(typeResult.status).toBe(0);
@@ -109,7 +109,7 @@ describe('pty-basics integration', { timeout: 30000 }, () => {
       const sendKeysResult = runCli(
         ['send-keys', sessionId, 'Enter', '--json'],
         {
-          AGENT_TERMINAL_HOME: testHome,
+          AGENT_TTY_HOME: testHome,
         },
       );
       expect(sendKeysResult.status).toBe(0);
@@ -145,7 +145,7 @@ describe('pty-basics integration', { timeout: 30000 }, () => {
       await sleep(500);
 
       const pasteResult = runCli(['paste', sessionId, 'test-text', '--json'], {
-        AGENT_TERMINAL_HOME: testHome,
+        AGENT_TTY_HOME: testHome,
       });
       expect(pasteResult.status).toBe(0);
       expect(pasteResult.stderr).toBe('');
@@ -185,7 +185,7 @@ describe('pty-basics integration', { timeout: 30000 }, () => {
       const pasteResult = runCli(
         ['paste', sessionId, '--file', inputPath, '--json'],
         {
-          AGENT_TERMINAL_HOME: testHome,
+          AGENT_TTY_HOME: testHome,
         },
       );
       expect(pasteResult.status).toBe(0);
@@ -222,7 +222,7 @@ describe('pty-basics integration', { timeout: 30000 }, () => {
 
       const resizeResult = runCli(
         ['resize', sessionId, '--cols', '120', '--rows', '40', '--json'],
-        { AGENT_TERMINAL_HOME: testHome },
+        { AGENT_TTY_HOME: testHome },
       );
       expect(resizeResult.status).toBe(0);
       expect(resizeResult.stderr).toBe('');
diff --git a/test/integration/record-export.test.ts b/test/integration/record-export.test.ts
index 09c7a0a..4f1ae77 100644
--- a/test/integration/record-export.test.ts
+++ b/test/integration/record-export.test.ts
@@ -47,7 +47,7 @@ function normalizeOutput(output: string): string {
 function waitForIdle(testHome: string, sessionId: string): void {
   const result = runCli(
     ['wait', sessionId, '--idle-ms', '300', '--timeout', '10000', '--json'],
-    { AGENT_TERMINAL_HOME: testHome },
+    { AGENT_TTY_HOME: testHome },
     15_000,
   );
 
@@ -61,7 +61,7 @@ function waitForIdle(testHome: string, sessionId: string): void {
 function waitForExit(testHome: string, sessionId: string): void {
   const result = runCli(
     ['wait', sessionId, '--exit', '--timeout', '10000', '--json'],
-    { AGENT_TERMINAL_HOME: testHome },
+    { AGENT_TTY_HOME: testHome },
     15_000,
   );
 
@@ -84,7 +84,7 @@ describe('record export integration', { timeout: 120_000 }, () => {
 
   beforeEach(async () => {
     // prettier-ignore
-    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-record-export-')));
+    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-record-export-')));
   });
 
   afterEach(async () => {
@@ -101,13 +101,13 @@ describe('record export integration', { timeout: 120_000 }, () => {
     waitForIdle(testHome, sessionId);
 
     const typeResult = runCli(['type', sessionId, 'hello export', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(typeResult.status).toBe(0);
     expect(typeResult.stderr).toBe('');
 
     const enterResult = runCli(['send-keys', sessionId, 'Enter', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
     expect(enterResult.status).toBe(0);
     expect(enterResult.stderr).toBe('');
@@ -116,7 +116,7 @@ describe('record export integration', { timeout: 120_000 }, () => {
 
     const exportResult = runCli(
       ['record', 'export', sessionId, '--format', 'asciicast', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
     expect(exportResult.status).toBe(0);
@@ -171,7 +171,7 @@ describe('record export integration', { timeout: 120_000 }, () => {
 
     const secondExportResult = runCli(
       ['record', 'export', sessionId, '--format', 'asciicast', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
     expect(secondExportResult.status).toBe(0);
@@ -225,7 +225,7 @@ describe('record export integration', { timeout: 120_000 }, () => {
 
     const exportResult = runCli(
       ['record', 'export', sessionId, '--format', 'asciicast', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
     expect(exportResult.status).toBe(0);
@@ -258,7 +258,7 @@ describe('record export integration', { timeout: 120_000 }, () => {
 
     const exportResult = runCli(
       ['record', 'export', sessionId, '--format', 'webm', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       120_000,
     );
     expect(exportResult.status).toBe(0);
@@ -316,7 +316,7 @@ describe('record export integration', { timeout: 120_000 }, () => {
 
     const exportResult = runCli(
       ['record', 'export', sessionId, '--format', 'webm', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       120_000,
     );
     expect(exportResult.status).toBe(0);
@@ -364,7 +364,7 @@ describe('record export integration', { timeout: 120_000 }, () => {
   it('rejects invalid export formats', () => {
     const result = runCli(
       ['record', 'export', 'session-01', '--format', 'bogus', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
 
diff --git a/test/integration/renderer-backend.test.ts b/test/integration/renderer-backend.test.ts
index 9334a0d..eb31064 100644
--- a/test/integration/renderer-backend.test.ts
+++ b/test/integration/renderer-backend.test.ts
@@ -112,7 +112,7 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
 
   it('resolves the browser cache from the original HOME when HOME is isolated before boot', async () => {
     // prettier-ignore
-    const isolatedHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-renderer-home-')));
+    const isolatedHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-renderer-home-')));
     const previousHome = process.env.HOME;
     const previousBrowsersPath = process.env.PLAYWRIGHT_BROWSERS_PATH;
     if (previousHome === undefined) {
@@ -363,7 +363,7 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
       },
     ]);
     // prettier-ignore
-    const outputDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-renderer-restart-')));
+    const outputDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-renderer-restart-')));
     const screenshotAPath = join(outputDir, 'renderer-a.png');
     const screenshotBPath = join(outputDir, 'renderer-b.png');
 
@@ -433,7 +433,7 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
     );
 
     // prettier-ignore
-    const outputDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-renderer-shot-')));
+    const outputDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-renderer-shot-')));
     const outputPath = join(outputDir, 'renderer.png');
 
     try {
diff --git a/test/integration/run.test.ts b/test/integration/run.test.ts
index 801ac54..61d4899 100644
--- a/test/integration/run.test.ts
+++ b/test/integration/run.test.ts
@@ -19,13 +19,13 @@ let testHome = '';
 let sessionId = '';
 
 function testEnv(): Record<string, string> {
-  return { AGENT_TERMINAL_HOME: testHome };
+  return { AGENT_TTY_HOME: testHome };
 }
 
 describe('run command integration', { timeout: 45_000 }, () => {
   beforeEach(() => {
     // prettier-ignore
-    testHome = realpathSync(mkdtempSync(join(tmpdir(), 'agent-terminal-run-home-')));
+    testHome = realpathSync(mkdtempSync(join(tmpdir(), 'agent-tty-run-home-')));
   });
 
   afterEach(async () => {
diff --git a/test/integration/wait-render.test.ts b/test/integration/wait-render.test.ts
index 04eddf0..c6aa041 100644
--- a/test/integration/wait-render.test.ts
+++ b/test/integration/wait-render.test.ts
@@ -47,7 +47,7 @@ async function waitForOutputMarker(
 ): Promise<void> {
   const waitResult = runCli(
     ['wait', sessionId, '--idle-ms', '200', '--timeout', '10000', '--json'],
-    { AGENT_TERMINAL_HOME: testHome },
+    { AGENT_TTY_HOME: testHome },
     15_000,
   );
 
@@ -107,7 +107,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
 
   beforeEach(async () => {
     // prettier-ignore
-    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-wait-render-')));
+    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-wait-render-')));
     sessionId = createSession(testHome, [...SESSION_COMMAND]);
     await waitForOutputMarker(testHome, sessionId, 'booting');
 
@@ -250,7 +250,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
   it('matches text via CLI --text', () => {
     const result = runCli(
       ['wait', sessionId, '--text', 'Ready', '--timeout', '15000', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       20_000,
     );
 
@@ -276,7 +276,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
         '15000',
         '--json',
       ],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       20_000,
     );
 
@@ -294,7 +294,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
   it('detects screen stability via CLI --screen-stable-ms', () => {
     const readyResult = runCli(
       ['wait', sessionId, '--text', 'Ready', '--timeout', '15000', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       20_000,
     );
 
@@ -311,7 +311,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
         '10000',
         '--json',
       ],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
 
@@ -342,7 +342,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
         '5000',
         '--json',
       ],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       10_000,
     );
 
@@ -361,7 +361,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
   it('rejects non-integer CLI --cursor-row values', () => {
     const result = runCli(
       ['wait', sessionId, '--cursor-row', '1.5', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
 
     expect(result.exitCode).not.toBe(0);
@@ -374,7 +374,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
 
   it('rejects negative CLI --cursor-col values', () => {
     const result = runCli(['wait', sessionId, '--cursor-col', '-1', '--json'], {
-      AGENT_TERMINAL_HOME: testHome,
+      AGENT_TTY_HOME: testHome,
     });
 
     expect(result.exitCode).not.toBe(0);
@@ -388,7 +388,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
   it('rejects mixing --exit with --text', () => {
     const result = runCli(
       ['wait', sessionId, '--exit', '--text', 'Ready', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
 
     expect(result.exitCode).not.toBe(0);
@@ -401,7 +401,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
   it('rejects --text and --regex together', () => {
     const result = runCli(
       ['wait', sessionId, '--text', 'foo', '--regex', 'bar', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
     );
 
     expect(result.exitCode).not.toBe(0);
@@ -414,7 +414,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
   it('legacy wait --idle-ms still works', () => {
     const result = runCli(
       ['wait', sessionId, '--idle-ms', '300', '--timeout', '10000', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
 
@@ -433,7 +433,7 @@ describe('wait render integration', { timeout: 120_000 }, () => {
     ]);
     const result = runCli(
       ['wait', shortSessionId, '--exit', '--timeout', '10000', '--json'],
-      { AGENT_TERMINAL_HOME: testHome },
+      { AGENT_TTY_HOME: testHome },
       15_000,
     );
 
diff --git a/test/unit/cli/context.test.ts b/test/unit/cli/context.test.ts
index 9278f0e..08263e0 100644
--- a/test/unit/cli/context.test.ts
+++ b/test/unit/cli/context.test.ts
@@ -35,19 +35,19 @@ describe('CLI context resolution', () => {
     mocks.loadConfigFile.mockResolvedValue(null);
   });
 
-  it('prefers --home over AGENT_TERMINAL_HOME', async () => {
+  it('prefers --home over AGENT_TTY_HOME', async () => {
     const context = await resolveCommandContext(
       { home: TEST_FLAG_HOME },
-      { AGENT_TERMINAL_HOME: TEST_ENV_HOME },
+      { AGENT_TTY_HOME: TEST_ENV_HOME },
     );
 
     expect(context.home).toBe(TEST_FLAG_HOME);
   });
 
-  it('falls back to AGENT_TERMINAL_HOME when --home is absent', async () => {
+  it('falls back to AGENT_TTY_HOME when --home is absent', async () => {
     const context = await resolveCommandContext(
       {},
-      { AGENT_TERMINAL_HOME: TEST_ENV_HOME },
+      { AGENT_TTY_HOME: TEST_ENV_HOME },
     );
 
     expect(context.home).toBe(TEST_ENV_HOME);
@@ -95,8 +95,8 @@ describe('CLI context resolution', () => {
       resolveCommandContext(
         { home: TEST_FLAG_HOME },
         {
-          AGENT_TERMINAL_HOME: TEST_ENV_HOME,
-          AGENT_TERMINAL_LOG_LEVEL: 'debug',
+          AGENT_TTY_HOME: TEST_ENV_HOME,
+          AGENT_TTY_LOG_LEVEL: 'debug',
         },
       ),
     ).resolves.toMatchObject({ logLevel: 'debug' });
@@ -125,8 +125,8 @@ describe('CLI context resolution', () => {
       resolveCommandContext(
         { home: TEST_FLAG_HOME },
         {
-          AGENT_TERMINAL_HOME: TEST_ENV_HOME,
-          AGENT_TERMINAL_PROFILE: 'env-profile',
+          AGENT_TTY_HOME: TEST_ENV_HOME,
+          AGENT_TTY_PROFILE: 'env-profile',
         },
       ),
     ).resolves.toMatchObject({ profileDefault: 'env-profile' });
@@ -145,7 +145,7 @@ describe('CLI context resolution', () => {
 
     const context = await resolveCommandContext(
       { home: TEST_FLAG_HOME },
-      { AGENT_TERMINAL_LOG_LEVEL: 'debug' },
+      { AGENT_TTY_LOG_LEVEL: 'debug' },
     );
 
     expect(context.logger.getLevel()).toBe('debug');
diff --git a/test/unit/commands/create.test.ts b/test/unit/commands/create.test.ts
index 091ad98..acb77e6 100644
--- a/test/unit/commands/create.test.ts
+++ b/test/unit/commands/create.test.ts
@@ -44,7 +44,7 @@ import { createLogger } from '../../../src/util/logger.js';
 
 describe('create command', () => {
   const context = {
-    home: '/tmp/agent-terminal-home',
+    home: '/tmp/agent-tty-home',
     timeoutMs: undefined,
     colorEnabled: true,
     logLevel: 'info',
@@ -90,14 +90,14 @@ describe('create command', () => {
     vi.clearAllMocks();
     mocks.allocateSession.mockResolvedValue({
       sessionId: 'session-01',
-      sessionDirectory: '/tmp/agent-terminal-home/sessions/session-01',
+      sessionDirectory: '/tmp/agent-tty-home/sessions/session-01',
     });
     mocks.launchHost.mockReturnValue(12345);
     mocks.sendRpc.mockResolvedValue({ session: { sessionId: 'session-01' } });
     mocks.readManifestIfExists.mockResolvedValue(makeManifest());
     mocks.sessionDir.mockImplementation(
       (_home: string, sessionId: string) =>
-        `/tmp/agent-terminal-home/sessions/${sessionId}`,
+        `/tmp/agent-tty-home/sessions/${sessionId}`,
     );
     mocks.manifestPath.mockImplementation(
       (sessionDirectory: string) => `${sessionDirectory}/session.json`,
diff --git a/test/unit/commands/doctor.test.ts b/test/unit/commands/doctor.test.ts
index 8a373d1..0d5d3f7 100644
--- a/test/unit/commands/doctor.test.ts
+++ b/test/unit/commands/doctor.test.ts
@@ -100,12 +100,12 @@ describe('doctor command', () => {
     originalHome = process.env.HOME;
     originalPlaywrightBrowsersPath = process.env.PLAYWRIGHT_BROWSERS_PATH;
     // prettier-ignore
-    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-doctor-home-')));
-    process.env.AGENT_TERMINAL_HOME = testHome;
+    testHome = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-doctor-home-')));
+    process.env.AGENT_TTY_HOME = testHome;
   });
 
   afterEach(async () => {
-    delete process.env.AGENT_TERMINAL_HOME;
+    delete process.env.AGENT_TTY_HOME;
     if (originalHome === undefined) {
       delete process.env.HOME;
     } else {
@@ -182,29 +182,29 @@ describe('doctor command', () => {
     },
   );
 
-  it('reports the default location when AGENT_TERMINAL_HOME is not explicitly set', () => {
-    delete process.env.AGENT_TERMINAL_HOME;
+  it('reports the default location when AGENT_TTY_HOME is not explicitly set', () => {
+    delete process.env.AGENT_TTY_HOME;
 
     expect(runHomeIsolationCheck()).toBe(
       'Agent-terminal home uses default location',
     );
   });
 
-  it('reports an explicit system home location when AGENT_TERMINAL_HOME matches HOME', () => {
+  it('reports an explicit system home location when AGENT_TTY_HOME matches HOME', () => {
     process.env.HOME = testHome;
-    process.env.AGENT_TERMINAL_HOME = testHome;
+    process.env.AGENT_TTY_HOME = testHome;
 
     expect(runHomeIsolationCheck()).toBe(
       'Agent-terminal home is explicitly set to system home location',
     );
   });
 
-  it('reports an isolated agent-terminal home when AGENT_TERMINAL_HOME differs from HOME', async () => {
+  it('reports an isolated agent-tty home when AGENT_TTY_HOME differs from HOME', async () => {
     const systemHome = await realpath(
-      await mkdtemp(join(tmpdir(), 'agent-terminal-system-home-')),
+      await mkdtemp(join(tmpdir(), 'agent-tty-system-home-')),
     );
     process.env.HOME = systemHome;
-    process.env.AGENT_TERMINAL_HOME = testHome;
+    process.env.AGENT_TTY_HOME = testHome;
 
     try {
       expect(runHomeIsolationCheck()).toBe(
@@ -217,7 +217,7 @@ describe('doctor command', () => {
 
   it('passes browser_cache_accessible when PLAYWRIGHT_BROWSERS_PATH contains browser directories', async () => {
     const browserCachePath = await realpath(
-      await mkdtemp(join(tmpdir(), 'agent-terminal-browser-cache-')),
+      await mkdtemp(join(tmpdir(), 'agent-tty-browser-cache-')),
     );
     process.env.PLAYWRIGHT_BROWSERS_PATH = browserCachePath;
     await mkdir(join(browserCachePath, 'chromium-1234'));
@@ -276,7 +276,7 @@ describe('doctor command', () => {
 
   it('uses the HOME-based default Playwright cache path when no override is set', async () => {
     const systemHome = await realpath(
-      await mkdtemp(join(tmpdir(), 'agent-terminal-system-home-')),
+      await mkdtemp(join(tmpdir(), 'agent-tty-system-home-')),
     );
     const browserCachePath = join(systemHome, '.cache', 'ms-playwright');
     delete process.env.PLAYWRIGHT_BROWSERS_PATH;
diff --git a/test/unit/commands/gc.test.ts b/test/unit/commands/gc.test.ts
index 5c6155f..c178ea6 100644
--- a/test/unit/commands/gc.test.ts
+++ b/test/unit/commands/gc.test.ts
@@ -216,7 +216,7 @@ describe('gc command helpers', () => {
   });
 
   it('removes exited sessions and never deletes running sessions', async () => {
-    const home = '/tmp/agent-terminal';
+    const home = '/tmp/agent-tty';
     const { dependencies, removedPaths, bytesBySession } =
       createMockDependencies(home, {
         'exited-01': {
@@ -260,7 +260,7 @@ describe('gc command helpers', () => {
   });
 
   it('skips deleting a session that restarts after the exited check', async () => {
-    const home = '/tmp/agent-terminal';
+    const home = '/tmp/agent-tty';
     const exitedManifest = createSessionRecord({
       sessionId: 'race-01',
       status: 'exited',
@@ -303,7 +303,7 @@ describe('gc command helpers', () => {
   });
 
   it('reports removals in dry-run mode without deleting anything', async () => {
-    const home = '/tmp/agent-terminal';
+    const home = '/tmp/agent-tty';
     const { dependencies, removedPaths, bytesBySession } =
       createMockDependencies(home, {
         'exited-01': {
@@ -335,7 +335,7 @@ describe('gc command helpers', () => {
   });
 
   it('filters removals by age threshold', async () => {
-    const home = '/tmp/agent-terminal';
+    const home = '/tmp/agent-tty';
     const { dependencies } = createMockDependencies(home, {
       'old-exited': {
         manifest: createSessionRecord({
@@ -373,7 +373,7 @@ describe('gc command helpers', () => {
   });
 
   it('handles rm failure gracefully and continues with other sessions', async () => {
-    const home = '/tmp/agent-terminal';
+    const home = '/tmp/agent-tty';
     const { dependencies, removedPaths, bytesBySession } =
       createMockDependencies(home, {
         'failed-01': {
@@ -425,7 +425,7 @@ describe('gc command helpers', () => {
   });
 
   it('only targets stale sessions when --stale-only is used', async () => {
-    const home = '/tmp/agent-terminal';
+    const home = '/tmp/agent-tty';
     const staleBefore = createSessionRecord({
       sessionId: 'stale-01',
       status: 'running',
diff --git a/test/unit/commands/golden-envelopes.test.ts b/test/unit/commands/golden-envelopes.test.ts
index 22ba32a..03dae35 100644
--- a/test/unit/commands/golden-envelopes.test.ts
+++ b/test/unit/commands/golden-envelopes.test.ts
@@ -44,7 +44,7 @@ const VersionResultSchema = z
 
 const SkillResultSchema = z
   .object({
-    name: z.literal('agent-terminal'),
+    name: z.literal('agent-tty'),
     source: z.literal('packaged-file'),
     content: z.string().min(1),
   })
@@ -734,7 +734,7 @@ const goldenResultContracts: readonly GoldenResultContractCase[] = [
       cols: 80,
       rows: 24,
       artifactPath:
-        '/tmp/agent-terminal/sessions/session-01/artifacts/screenshot-8-reference-dark.png',
+        '/tmp/agent-tty/sessions/session-01/artifacts/screenshot-8-reference-dark.png',
       pngSizeBytes: 4096,
       cursorVisible: true,
       rendererBackend: 'ghostty-web',
@@ -1048,8 +1048,7 @@ describe('JSON envelope contracts', () => {
       message: 'Session "missing-session" was not found.',
       details: {
         sessionId: 'missing-session',
-        manifestPath:
-          '/tmp/agent-terminal/sessions/missing-session/session.json',
+        manifestPath: '/tmp/agent-tty/sessions/missing-session/session.json',
       },
     });
 
@@ -1070,8 +1069,7 @@ describe('JSON envelope contracts', () => {
         retryable: false,
         details: {
           sessionId: 'missing-session',
-          manifestPath:
-            '/tmp/agent-terminal/sessions/missing-session/session.json',
+          manifestPath: '/tmp/agent-tty/sessions/missing-session/session.json',
         },
       },
     });
diff --git a/test/unit/commands/inspect.test.ts b/test/unit/commands/inspect.test.ts
index 40c5adc..fefffb0 100644
--- a/test/unit/commands/inspect.test.ts
+++ b/test/unit/commands/inspect.test.ts
@@ -58,7 +58,7 @@ import type { SessionStatus } from '../../../src/protocol/schemas.js';
 import { createLogger } from '../../../src/util/logger.js';
 
 const TEST_CONTEXT = {
-  home: '/tmp/agent-terminal',
+  home: '/tmp/agent-tty',
   timeoutMs: undefined,
   colorEnabled: true,
   logLevel: 'info',
@@ -114,7 +114,7 @@ describe('inspect command', () => {
     vi.clearAllMocks();
     mocks.sessionDir.mockImplementation(
       (_home: string, sessionId: string) =>
-        `/tmp/agent-terminal/sessions/${sessionId}`,
+        `/tmp/agent-tty/sessions/${sessionId}`,
     );
     mocks.manifestPath.mockImplementation(
       (sessionDirectory: string) => `${sessionDirectory}/session.json`,
@@ -150,14 +150,14 @@ describe('inspect command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'inspect',
     );
     expect(mocks.countEventLogEntries).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/events.jsonl',
+      '/tmp/agent-tty/sessions/session-01/events.jsonl',
     );
     expect(mocks.computeArtifactHealth).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01',
+      '/tmp/agent-tty/sessions/session-01',
     );
     expect(mocks.deriveTerminationCategory).toHaveBeenCalledWith(liveSession);
     const emitted = getLastEmitSuccessPayload() as {
@@ -227,7 +227,7 @@ describe('inspect command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'inspect',
     );
 
@@ -342,16 +342,16 @@ describe('inspect command', () => {
     });
 
     expect(mocks.reconcileSession).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01',
+      '/tmp/agent-tty/sessions/session-01',
     );
     expect(mocks.readManifest).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/session.json',
+      '/tmp/agent-tty/sessions/session-01/session.json',
     );
     expect(mocks.countEventLogEntries).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/events.jsonl',
+      '/tmp/agent-tty/sessions/session-01/events.jsonl',
     );
     expect(mocks.computeArtifactHealth).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01',
+      '/tmp/agent-tty/sessions/session-01',
     );
     expect(mocks.deriveTerminationCategory).toHaveBeenCalledWith(
       reconciledSession,
diff --git a/test/unit/commands/mark.test.ts b/test/unit/commands/mark.test.ts
index 3b2afa0..7eca964 100644
--- a/test/unit/commands/mark.test.ts
+++ b/test/unit/commands/mark.test.ts
@@ -38,7 +38,7 @@ import { runMarkCommand } from '../../../src/cli/commands/mark.js';
 import { createLogger } from '../../../src/util/logger.js';
 
 const TEST_CONTEXT = {
-  home: '/tmp/agent-terminal',
+  home: '/tmp/agent-tty',
   timeoutMs: undefined,
   colorEnabled: true,
   logLevel: 'info',
@@ -70,10 +70,10 @@ function createSessionRecord(
 describe('mark command', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    mocks.resolveHome.mockReturnValue('/tmp/agent-terminal');
+    mocks.resolveHome.mockReturnValue('/tmp/agent-tty');
     mocks.sessionDir.mockImplementation(
       (_home: string, sessionId: string) =>
-        `/tmp/agent-terminal/sessions/${sessionId}`,
+        `/tmp/agent-tty/sessions/${sessionId}`,
     );
     mocks.manifestPath.mockImplementation(
       (sessionDirectory: string) => `${sessionDirectory}/session.json`,
@@ -97,7 +97,7 @@ describe('mark command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'mark',
       { label: 'checkpoint' },
     );
@@ -154,7 +154,7 @@ describe('mark command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'mark',
       { label: '' },
     );
diff --git a/test/unit/commands/record-export.test.ts b/test/unit/commands/record-export.test.ts
index 5d996f8..3366be9 100644
--- a/test/unit/commands/record-export.test.ts
+++ b/test/unit/commands/record-export.test.ts
@@ -86,7 +86,7 @@ import { hashProfile, resolveProfile } from '../../../src/renderer/profiles.js';
 import { createLogger } from '../../../src/util/logger.js';
 
 const TEST_CONTEXT = {
-  home: '/tmp/agent-terminal',
+  home: '/tmp/agent-tty',
   timeoutMs: undefined,
   colorEnabled: true,
   logLevel: 'info',
@@ -132,10 +132,10 @@ async function createTemporaryDirectory(prefix: string): Promise<string> {
 describe('record export command', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    mocks.resolveHome.mockReturnValue('/tmp/agent-terminal');
+    mocks.resolveHome.mockReturnValue('/tmp/agent-tty');
     mocks.sessionDir.mockImplementation(
       (_home: string, sessionId: string) =>
-        `/tmp/agent-terminal/sessions/${sessionId}`,
+        `/tmp/agent-tty/sessions/${sessionId}`,
     );
     mocks.manifestPath.mockImplementation(
       (sessionDirectory: string) => `${sessionDirectory}/session.json`,
@@ -159,10 +159,10 @@ describe('record export command', () => {
       },
     ]);
     mocks.ensureArtifactsDir.mockResolvedValue(
-      '/tmp/agent-terminal/sessions/session-01/artifacts',
+      '/tmp/agent-tty/sessions/session-01/artifacts',
     );
     mocks.loadPackageMetadata.mockResolvedValue({
-      name: 'agent-terminal',
+      name: 'agent-tty',
       version: '0.1.0-test',
     });
     mocks.recordingFilename.mockReturnValue('recording-1-asciicast.cast');
@@ -234,14 +234,14 @@ describe('record export command', () => {
     expect(mocks.loadPackageMetadata).toHaveBeenCalledTimes(1);
 
     expect(mocks.ensureArtifactsDir).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01',
+      '/tmp/agent-tty/sessions/session-01',
     );
     expect(mocks.writeTextFileAtomic).toHaveBeenCalledWith({
-      path: '/tmp/agent-terminal/sessions/session-01/artifacts/recording-2-asciicast.cast',
+      path: '/tmp/agent-tty/sessions/session-01/artifacts/recording-2-asciicast.cast',
       pathLabel: 'record export path',
       contents: expectedContents,
       writeErrorMessage:
-        'Failed to write record export artifact at /tmp/agent-terminal/sessions/session-01/artifacts/recording-2-asciicast.cast.',
+        'Failed to write record export artifact at /tmp/agent-tty/sessions/session-01/artifacts/recording-2-asciicast.cast.',
     });
     expect(mocks.createArtifactEntry).toHaveBeenCalledWith({
       kind: 'recording',
@@ -253,7 +253,7 @@ describe('record export command', () => {
       metadata: {
         format: 'asciicast',
         outputPath:
-          '/tmp/agent-terminal/sessions/session-01/artifacts/recording-2-asciicast.cast',
+          '/tmp/agent-tty/sessions/session-01/artifacts/recording-2-asciicast.cast',
         width: 80,
         height: 24,
         title: 'session-01',
@@ -264,7 +264,7 @@ describe('record export command', () => {
       },
     });
     expect(mocks.appendArtifact).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01',
+      '/tmp/agent-tty/sessions/session-01',
       expect.objectContaining({
         kind: 'recording',
         filename: 'recording-2-asciicast.cast',
@@ -279,7 +279,7 @@ describe('record export command', () => {
         sessionId: 'session-01',
         format: 'asciicast',
         artifactPath:
-          '/tmp/agent-terminal/sessions/session-01/artifacts/recording-2-asciicast.cast',
+          '/tmp/agent-tty/sessions/session-01/artifacts/recording-2-asciicast.cast',
         bytes: Buffer.byteLength(expectedContents, 'utf8'),
         sha256: expectedSha256,
         capturedAtSeq: 2,
@@ -298,7 +298,7 @@ describe('record export command', () => {
         'Session ID: session-01',
         'Format: asciicast',
         'Captured At Seq: 2',
-        'Artifact Path: /tmp/agent-terminal/sessions/session-01/artifacts/recording-2-asciicast.cast',
+        'Artifact Path: /tmp/agent-tty/sessions/session-01/artifacts/recording-2-asciicast.cast',
         `Bytes: ${String(Buffer.byteLength(expectedContents, 'utf8'))}`,
         `SHA256: ${expectedSha256}`,
         'Duration: 1500 ms',
@@ -354,7 +354,7 @@ describe('record export command', () => {
 
     expect(generateWebmExportArgs.sessionId).toBe('session-01');
     expect(generateWebmExportArgs.sessionDir).toBe(
-      '/tmp/agent-terminal/sessions/session-01',
+      '/tmp/agent-tty/sessions/session-01',
     );
     expect(generateWebmExportArgs.manifest).toEqual(createSessionRecord());
     expect(generateWebmExportArgs.events).toEqual([
@@ -372,14 +372,14 @@ describe('record export command', () => {
       },
     ]);
     expect(generateWebmExportArgs.outputPath).toBe(
-      '/tmp/agent-terminal/sessions/session-01/artifacts/recording-1-webm.webm',
+      '/tmp/agent-tty/sessions/session-01/artifacts/recording-1-webm.webm',
     );
     expect(mocks.writeTextFileAtomic).not.toHaveBeenCalled();
     expect(mocks.stat).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/artifacts/recording-1-webm.webm',
+      '/tmp/agent-tty/sessions/session-01/artifacts/recording-1-webm.webm',
     );
     expect(mocks.readFile).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/artifacts/recording-1-webm.webm',
+      '/tmp/agent-tty/sessions/session-01/artifacts/recording-1-webm.webm',
     );
 
     expect(mocks.createArtifactEntry).toHaveBeenCalledTimes(1);
@@ -654,7 +654,7 @@ describe('record export command', () => {
       code: ERROR_CODES.SESSION_NOT_FOUND,
       details: {
         sessionId: 'session-01',
-        manifestPath: '/tmp/agent-terminal/sessions/session-01/session.json',
+        manifestPath: '/tmp/agent-tty/sessions/session-01/session.json',
       },
     });
     expect(mocks.readEventLogRecords).not.toHaveBeenCalled();
@@ -663,7 +663,7 @@ describe('record export command', () => {
 
   it('writes explicit relative output paths within the current working directory', async () => {
     const workspaceDirectory = await createTemporaryDirectory(
-      'agent-terminal-record-export-workspace-',
+      'agent-tty-record-export-workspace-',
     );
     const exportsDirectory = join(workspaceDirectory, 'exports');
     await mkdir(exportsDirectory, { recursive: true });
@@ -700,7 +700,7 @@ describe('record export command', () => {
 
   it('resolves symlinked output directories to their real paths', async () => {
     const workspaceDirectory = await createTemporaryDirectory(
-      'agent-terminal-record-export-realpath-',
+      'agent-tty-record-export-realpath-',
     );
     const realExportsDirectory = join(workspaceDirectory, 'real-exports');
     const symlinkExportsDirectory = join(workspaceDirectory, 'linked-exports');
@@ -734,7 +734,7 @@ describe('record export command', () => {
 
   it('rejects output paths whose parent directory does not exist', async () => {
     const workspaceDirectory = await createTemporaryDirectory(
-      'agent-terminal-record-export-missing-parent-',
+      'agent-tty-record-export-missing-parent-',
     );
 
     await expect(
diff --git a/test/unit/commands/run.test.ts b/test/unit/commands/run.test.ts
index 776da96..69fc334 100644
--- a/test/unit/commands/run.test.ts
+++ b/test/unit/commands/run.test.ts
@@ -37,7 +37,7 @@ import { ERROR_CODES } from '../../../src/protocol/errors.js';
 import { createLogger } from '../../../src/util/logger.js';
 
 const TEST_CONTEXT = {
-  home: '/tmp/agent-terminal',
+  home: '/tmp/agent-tty',
   timeoutMs: undefined,
   colorEnabled: true,
   logLevel: 'info',
@@ -87,7 +87,7 @@ describe('run command', () => {
     vi.clearAllMocks();
     mocks.sessionDir.mockImplementation(
       (_home: string, sessionId: string) =>
-        `/tmp/agent-terminal/sessions/${sessionId}`,
+        `/tmp/agent-tty/sessions/${sessionId}`,
     );
     mocks.manifestPath.mockImplementation(
       (sessionDirectory: string) => `${sessionDirectory}/session.json`,
@@ -113,7 +113,7 @@ describe('run command', () => {
     await runRunCommand(createOptions());
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'run',
       {
         command: 'echo hello',
@@ -146,7 +146,7 @@ describe('run command', () => {
     await runRunCommand(createOptions({ wait: false }));
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'run',
       {
         command: 'echo hello',
@@ -169,7 +169,7 @@ describe('run command', () => {
     await runRunCommand(createOptions({ timeout: 5_000 }));
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'run',
       {
         command: 'echo hello',
diff --git a/test/unit/commands/screenshot.test.ts b/test/unit/commands/screenshot.test.ts
index 78f1ad0..3034c46 100644
--- a/test/unit/commands/screenshot.test.ts
+++ b/test/unit/commands/screenshot.test.ts
@@ -71,7 +71,7 @@ import { runScreenshotCommand } from '../../../src/cli/commands/screenshot.js';
 import { createLogger } from '../../../src/util/logger.js';
 
 const TEST_CONTEXT = {
-  home: '/tmp/agent-terminal',
+  home: '/tmp/agent-tty',
   timeoutMs: undefined,
   colorEnabled: true,
   logLevel: 'info',
@@ -180,10 +180,10 @@ function mockOfflineReplayRendererSuccess(
 describe('screenshot command', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    mocks.resolveHome.mockReturnValue('/tmp/agent-terminal');
+    mocks.resolveHome.mockReturnValue('/tmp/agent-tty');
     mocks.sessionDir.mockImplementation(
       (_home: string, sessionId: string) =>
-        `/tmp/agent-terminal/sessions/${sessionId}`,
+        `/tmp/agent-tty/sessions/${sessionId}`,
     );
     mocks.manifestPath.mockImplementation(
       (sessionDirectory: string) => `${sessionDirectory}/session.json`,
@@ -199,7 +199,7 @@ describe('screenshot command', () => {
       ...(entry as Record<string, unknown>),
     }));
     mocks.ensureArtifactsDir.mockResolvedValue(
-      '/tmp/agent-terminal/sessions/session-01/artifacts',
+      '/tmp/agent-tty/sessions/session-01/artifacts',
     );
     mocks.rename.mockResolvedValue(undefined);
     mocks.rm.mockResolvedValue(undefined);
@@ -220,7 +220,7 @@ describe('screenshot command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'screenshot',
       { profile: 'reference-dark' },
     );
@@ -258,7 +258,7 @@ describe('screenshot command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'screenshot',
       { profile: 'reference-dark', showCursor: true },
     );
@@ -287,7 +287,7 @@ describe('screenshot command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'screenshot',
       { profile: 'configured-profile' },
     );
@@ -313,7 +313,7 @@ describe('screenshot command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'screenshot',
       { profile: 'reference-light' },
     );
@@ -352,7 +352,7 @@ describe('screenshot command', () => {
     expect(mocks.sendRpc).not.toHaveBeenCalled();
     expect(mocks.withOfflineReplayRenderer).toHaveBeenCalledWith(
       {
-        sessionDir: '/tmp/agent-terminal/sessions/session-01',
+        sessionDir: '/tmp/agent-tty/sessions/session-01',
         profileName: 'reference-dark',
       },
       expect.any(Function),
@@ -380,7 +380,7 @@ describe('screenshot command', () => {
       },
     });
     expect(mocks.appendArtifact).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01',
+      '/tmp/agent-tty/sessions/session-01',
       expect.objectContaining({
         kind: 'screenshot',
         filename: 'screenshot-5-reference-dark.png',
@@ -487,7 +487,7 @@ describe('screenshot command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'screenshot',
       { profile: 'reference-dark' },
     );
diff --git a/test/unit/commands/skill.test.ts b/test/unit/commands/skill.test.ts
index ad94fa7..2d30804 100644
--- a/test/unit/commands/skill.test.ts
+++ b/test/unit/commands/skill.test.ts
@@ -11,10 +11,7 @@ import {
 
 describe('skill command', () => {
   it('loads the packaged skill content', async () => {
-    const expectedContent = await readFile(
-      'skills/agent-terminal/SKILL.md',
-      'utf8',
-    );
+    const expectedContent = await readFile('skills/agent-tty/SKILL.md', 'utf8');
     const content = await loadPackagedSkillContent();
 
     expect(content).toBe(expectedContent);
@@ -24,7 +21,7 @@ describe('skill command', () => {
   it('builds the skill result payload', async () => {
     const result = await buildSkillResult();
 
-    expect(result.name).toBe('agent-terminal');
+    expect(result.name).toBe('agent-tty');
     expect(result.source).toBe('packaged-file');
     expect(result.content.length).toBeGreaterThan(0);
   });
@@ -55,7 +52,7 @@ describe('skill command', () => {
           cause: error,
         });
       }
-      expect(skillPath).toContain('skills/agent-terminal/SKILL.md');
+      expect(skillPath).toContain('skills/agent-tty/SKILL.md');
     }
   });
 });
diff --git a/test/unit/commands/snapshot.test.ts b/test/unit/commands/snapshot.test.ts
index a0f7d4d..3d956ae 100644
--- a/test/unit/commands/snapshot.test.ts
+++ b/test/unit/commands/snapshot.test.ts
@@ -62,7 +62,7 @@ import { runSnapshotCommand } from '../../../src/cli/commands/snapshot.js';
 import { createLogger } from '../../../src/util/logger.js';
 
 const TEST_CONTEXT = {
-  home: '/tmp/agent-terminal',
+  home: '/tmp/agent-tty',
   timeoutMs: undefined,
   colorEnabled: true,
   logLevel: 'info',
@@ -166,10 +166,10 @@ function installOfflineReplaySuccessMock(
 describe('snapshot command', () => {
   beforeEach(() => {
     vi.resetAllMocks();
-    mocks.resolveHome.mockReturnValue('/tmp/agent-terminal');
+    mocks.resolveHome.mockReturnValue('/tmp/agent-tty');
     mocks.sessionDir.mockImplementation(
       (_home: string, sessionId: string) =>
-        `/tmp/agent-terminal/sessions/${sessionId}`,
+        `/tmp/agent-tty/sessions/${sessionId}`,
     );
     mocks.manifestPath.mockImplementation(
       (sessionDirectory: string) => `${sessionDirectory}/session.json`,
@@ -220,7 +220,7 @@ describe('snapshot command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'snapshot',
       { format: 'structured', includeScrollback: false, includeCells: false },
     );
@@ -263,7 +263,7 @@ describe('snapshot command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'snapshot',
       { format: 'text', includeScrollback: false, includeCells: false },
     );
@@ -359,7 +359,7 @@ describe('snapshot command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'snapshot',
       {
         format: 'structured',
@@ -406,7 +406,7 @@ describe('snapshot command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'snapshot',
       { format: 'text', includeScrollback: true, includeCells: false },
     );
@@ -443,11 +443,11 @@ describe('snapshot command', () => {
 
     expect(mocks.sendRpc).not.toHaveBeenCalled();
     expect(mocks.withOfflineReplayRenderer).toHaveBeenCalledWith(
-      { sessionDir: '/tmp/agent-terminal/sessions/session-01' },
+      { sessionDir: '/tmp/agent-tty/sessions/session-01' },
       expect.any(Function),
     );
     expect(mocks.ensureArtifactsDir).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01',
+      '/tmp/agent-tty/sessions/session-01',
     );
     expect(mocks.snapshotFilename).toHaveBeenCalledWith(5, 'structured');
     expect(mocks.writeTextFileAtomic).toHaveBeenCalledWith({
@@ -472,7 +472,7 @@ describe('snapshot command', () => {
       },
     });
     expect(mocks.appendArtifact).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01',
+      '/tmp/agent-tty/sessions/session-01',
       {
         kind: 'snapshot',
         filename: 'snapshot-5-structured.json',
@@ -667,12 +667,12 @@ describe('snapshot command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'snapshot',
       { format: 'text', includeScrollback: false, includeCells: false },
     );
     expect(mocks.withOfflineReplayRenderer).toHaveBeenCalledWith(
-      { sessionDir: '/tmp/agent-terminal/sessions/session-01' },
+      { sessionDir: '/tmp/agent-tty/sessions/session-01' },
       expect.any(Function),
     );
     expect(mocks.emitSuccess).toHaveBeenCalledWith({
diff --git a/test/unit/commands/type.test.ts b/test/unit/commands/type.test.ts
index c834faf..792e89b 100644
--- a/test/unit/commands/type.test.ts
+++ b/test/unit/commands/type.test.ts
@@ -36,7 +36,7 @@ import { runTypeCommand } from '../../../src/cli/commands/type.js';
 import { createLogger } from '../../../src/util/logger.js';
 
 const TEST_CONTEXT = {
-  home: '/tmp/agent-terminal',
+  home: '/tmp/agent-tty',
   timeoutMs: undefined,
   colorEnabled: true,
   logLevel: 'info',
@@ -70,7 +70,7 @@ describe('type command', () => {
     vi.clearAllMocks();
     mocks.sessionDir.mockImplementation(
       (_home: string, sessionId: string) =>
-        `/tmp/agent-terminal/sessions/${sessionId}`,
+        `/tmp/agent-tty/sessions/${sessionId}`,
     );
     mocks.manifestPath.mockImplementation(
       (sessionDirectory: string) => `${sessionDirectory}/session.json`,
@@ -99,7 +99,7 @@ describe('type command', () => {
       file: undefined,
     });
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'type',
       { text: 'hello\n' },
     );
@@ -123,7 +123,7 @@ describe('type command', () => {
       file: '/tmp/input.txt',
     });
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'type',
       { text: 'from-file\n' },
     );
@@ -141,7 +141,7 @@ describe('type command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'type',
       { text: 'hello\n\n' },
     );
@@ -156,7 +156,7 @@ describe('type command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'type',
       { text: 'hello' },
     );
@@ -174,7 +174,7 @@ describe('type command', () => {
     });
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'type',
       { text: '\n' },
     );
diff --git a/test/unit/commands/version.test.ts b/test/unit/commands/version.test.ts
index dfead6a..1a28b52 100644
--- a/test/unit/commands/version.test.ts
+++ b/test/unit/commands/version.test.ts
@@ -6,19 +6,20 @@ import {
   loadPackageMetadata,
 } from '../../../src/cli/commands/version.js';
 
+const SEMVER_WITH_OPTIONAL_PRERELEASE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
 describe('version command', () => {
   it('loads package metadata', async () => {
     const packageMetadata = await loadPackageMetadata();
 
-    expect(packageMetadata.name).toBe('agent-terminal');
-    expect(packageMetadata.version.length).toBeGreaterThan(0);
+    expect(packageMetadata.name).toBe('agent-tty');
+    expect(packageMetadata.version).toMatch(SEMVER_WITH_OPTIONAL_PRERELEASE);
   });
 
   it('builds the version result without capabilities by default', async () => {
-    const packageMetadata = await loadPackageMetadata();
     const result = await buildVersionResult();
 
-    expect(result.cliVersion).toBe(packageMetadata.version);
+    expect(result.cliVersion).toMatch(SEMVER_WITH_OPTIONAL_PRERELEASE);
     expect(result.protocolVersion).toBe('0.1.0');
     expect(result.rendererBackends).toEqual(['ghostty-web']);
     expect(result.runtime.node).toMatch(/^v\d+\.\d+\.\d+$/);
@@ -52,10 +53,9 @@ describe('version command', () => {
       .spyOn(process.stderr, 'write')
       .mockReturnValue(true);
 
-    const packageMetadata = await loadPackageMetadata();
     const result = await buildVersionResult({ includeCapabilities: true });
 
-    expect(result.cliVersion).toBe(packageMetadata.version);
+    expect(result.cliVersion).toMatch(SEMVER_WITH_OPTIONAL_PRERELEASE);
     expect(result.protocolVersion).toBe('0.1.0');
     expect(result.rendererBackends).toEqual(['ghostty-web']);
     expect(result.runtime.node).toMatch(/^v\d+\.\d+\.\d+$/);
diff --git a/test/unit/commands/wait.test.ts b/test/unit/commands/wait.test.ts
index 6418227..2b0bb39 100644
--- a/test/unit/commands/wait.test.ts
+++ b/test/unit/commands/wait.test.ts
@@ -43,7 +43,7 @@ import { runWaitCommand } from '../../../src/cli/commands/wait.js';
 import { createLogger } from '../../../src/util/logger.js';
 
 const TEST_CONTEXT = {
-  home: '/tmp/agent-terminal',
+  home: '/tmp/agent-tty',
   timeoutMs: undefined,
   colorEnabled: true,
   logLevel: 'info',
@@ -145,10 +145,10 @@ function mockOfflineReplaySnapshot(
 describe('wait command', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    mocks.resolveHome.mockReturnValue('/tmp/agent-terminal');
+    mocks.resolveHome.mockReturnValue('/tmp/agent-tty');
     mocks.sessionDir.mockImplementation(
       (_home: string, sessionId: string) =>
-        `/tmp/agent-terminal/sessions/${sessionId}`,
+        `/tmp/agent-tty/sessions/${sessionId}`,
     );
     mocks.manifestPath.mockImplementation(
       (sessionDirectory: string) => `${sessionDirectory}/session.json`,
@@ -271,7 +271,7 @@ describe('wait command', () => {
     await runWaitCommand(createOptions({ text: 'hello', timeout: 0 }));
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'waitForRender',
       {
         text: 'hello',
@@ -316,7 +316,7 @@ describe('wait command', () => {
     await runWaitCommand(createOptions({ waitForExit: true }));
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'wait',
       {
         exit: true,
@@ -340,7 +340,7 @@ describe('wait command', () => {
     await runWaitCommand(createOptions({ idleMs: 500 }));
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'wait',
       {
         exit: undefined,
@@ -369,7 +369,7 @@ describe('wait command', () => {
     await runWaitCommand(createOptions({ text: 'hello' }));
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'waitForRender',
       {
         text: 'hello',
@@ -401,7 +401,7 @@ describe('wait command', () => {
     await runWaitCommand(createOptions({ regex: '\\d+' }));
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'waitForRender',
       {
         text: undefined,
@@ -436,7 +436,7 @@ describe('wait command', () => {
     );
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'waitForRender',
       {
         text: 'hello',
@@ -470,7 +470,7 @@ describe('wait command', () => {
     await runWaitCommand(createOptions({ text: 'hello' }));
 
     expect(mocks.sendRpc).toHaveBeenCalledWith(
-      '/tmp/agent-terminal/sessions/session-01/rpc.sock',
+      '/tmp/agent-tty/sessions/session-01/rpc.sock',
       'waitForRender',
       {
         text: 'hello',
@@ -483,7 +483,7 @@ describe('wait command', () => {
       605_000,
     );
     expect(mocks.withOfflineReplayRenderer).toHaveBeenCalledWith(
-      { sessionDir: '/tmp/agent-terminal/sessions/session-01' },
+      { sessionDir: '/tmp/agent-tty/sessions/session-01' },
       expect.any(Function),
     );
     expect(mocks.emitSuccess).toHaveBeenCalledWith({
@@ -591,7 +591,7 @@ describe('wait command', () => {
       code: ERROR_CODES.SESSION_NOT_FOUND,
       details: {
         sessionId: 'session-01',
-        manifestPath: '/tmp/agent-terminal/sessions/session-01/session.json',
+        manifestPath: '/tmp/agent-tty/sessions/session-01/session.json',
       },
     });
     expect(mocks.sendRpc).not.toHaveBeenCalled();
diff --git a/test/unit/config/resolveConfig.test.ts b/test/unit/config/resolveConfig.test.ts
index a05f383..950ec0d 100644
--- a/test/unit/config/resolveConfig.test.ts
+++ b/test/unit/config/resolveConfig.test.ts
@@ -13,7 +13,7 @@ const temporaryHomes: string[] = [];
 
 async function createTemporaryHome(): Promise<string> {
   // prettier-ignore
-  const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-config-')));
+  const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-config-')));
   temporaryHomes.push(home);
   return home;
 }
diff --git a/test/unit/export/webm.test.ts b/test/unit/export/webm.test.ts
index eadf66d..864c113 100644
--- a/test/unit/export/webm.test.ts
+++ b/test/unit/export/webm.test.ts
@@ -193,7 +193,7 @@ describe('generateWebmExport', () => {
     const result = await generateWebmExport(
       {
         sessionId: 'session-01',
-        sessionDir: '/tmp/agent-terminal/sessions/session-01',
+        sessionDir: '/tmp/agent-tty/sessions/session-01',
         manifest: createManifest(),
         events: createEvents(),
         outputPath: '/tmp/exports/recording-1-webm.webm',
@@ -223,7 +223,7 @@ describe('generateWebmExport', () => {
       fontSize: 16,
       name: 'reference-dark',
     });
-    expect(videoOptions.outputDir).toContain('agent-terminal-webm-');
+    expect(videoOptions.outputDir).toContain('agent-tty-webm-');
     expect(videoOptions.size).toEqual({
       width: 864,
       height: 608,
@@ -267,7 +267,7 @@ describe('generateWebmExport', () => {
     const result = await generateWebmExport(
       {
         sessionId: 'session-01',
-        sessionDir: '/tmp/agent-terminal/sessions/session-01',
+        sessionDir: '/tmp/agent-tty/sessions/session-01',
         manifest: createManifest(),
         events: createEvents(),
         outputPath: '/tmp/exports/recording-1-webm.webm',
@@ -289,7 +289,7 @@ describe('generateWebmExport', () => {
     const result = await generateWebmExport(
       {
         sessionId: 'session-01',
-        sessionDir: '/tmp/agent-terminal/sessions/session-01',
+        sessionDir: '/tmp/agent-tty/sessions/session-01',
         manifest: createManifest(),
         events: createEvents(),
         outputPath: '/tmp/exports/recording-1-webm.webm',
@@ -311,7 +311,7 @@ describe('generateWebmExport', () => {
     const result = await generateWebmExport(
       {
         sessionId: 'session-01',
-        sessionDir: '/tmp/agent-terminal/sessions/session-01',
+        sessionDir: '/tmp/agent-tty/sessions/session-01',
         manifest: createManifest(),
         events: createEvents(),
         outputPath: '/tmp/exports/recording-1-webm.webm',
@@ -335,7 +335,7 @@ describe('generateWebmExport', () => {
     await expect(
       generateWebmExport({
         sessionId: 'session-01',
-        sessionDir: '/tmp/agent-terminal/sessions/session-01',
+        sessionDir: '/tmp/agent-tty/sessions/session-01',
         manifest: createManifest(),
         events: [],
         outputPath: '/tmp/exports/recording-1-webm.webm',
@@ -347,7 +347,7 @@ describe('generateWebmExport', () => {
     await expect(
       generateWebmExport({
         sessionId: 'session-01',
-        sessionDir: '/tmp/agent-terminal/sessions/session-01',
+        sessionDir: '/tmp/agent-tty/sessions/session-01',
         manifest: createManifest(),
         events: createEvents(),
         outputPath: 'relative/path.webm',
@@ -364,7 +364,7 @@ describe('generateWebmExport', () => {
       generateWebmExport(
         {
           sessionId: 'session-01',
-          sessionDir: '/tmp/agent-terminal/sessions/session-01',
+          sessionDir: '/tmp/agent-tty/sessions/session-01',
           manifest: createManifest(),
           events: createEvents(),
           outputPath: '/tmp/exports/recording-1-webm.webm',
@@ -388,7 +388,7 @@ describe('generateWebmExport', () => {
       generateWebmExport(
         {
           sessionId: 'session-01',
-          sessionDir: '/tmp/agent-terminal/sessions/session-01',
+          sessionDir: '/tmp/agent-tty/sessions/session-01',
           manifest: createManifest(),
           events: createEvents(),
           outputPath: '/tmp/exports/recording-1-webm.webm',
@@ -413,7 +413,7 @@ describe('generateWebmExport', () => {
       generateWebmExport(
         {
           sessionId: 'session-01',
-          sessionDir: '/tmp/agent-terminal/sessions/session-01',
+          sessionDir: '/tmp/agent-tty/sessions/session-01',
           manifest: createManifest(),
           events: createEvents(),
           outputPath: '/tmp/exports/recording-1-webm.webm',
diff --git a/test/unit/host/eventLog.test.ts b/test/unit/host/eventLog.test.ts
index 4c8dde5..fd4a440 100644
--- a/test/unit/host/eventLog.test.ts
+++ b/test/unit/host/eventLog.test.ts
@@ -24,7 +24,7 @@ let eventLogPath = '';
 describe('countEventLogEntries', () => {
   beforeEach(async () => {
     // prettier-ignore
-    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-event-log-')));
+    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-event-log-')));
     eventLogPath = join(tempDir, 'events.jsonl');
   });
 
@@ -63,7 +63,7 @@ describe('countEventLogEntries', () => {
 describe('EventLog', () => {
   beforeEach(async () => {
     // prettier-ignore
-    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-event-log-')));
+    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-event-log-')));
     eventLogPath = join(tempDir, 'events.jsonl');
     await writeFile(eventLogPath, '', 'utf8');
   });
diff --git a/test/unit/host/renderer.test.ts b/test/unit/host/renderer.test.ts
index 13a4f4e..3a840e9 100644
--- a/test/unit/host/renderer.test.ts
+++ b/test/unit/host/renderer.test.ts
@@ -179,7 +179,7 @@ describe('HostRendererManager', () => {
 
   beforeEach(async () => {
     // prettier-ignore
-    sessionDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-renderer-')));
+    sessionDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-renderer-')));
     backends = [];
     backendFactory = vi.fn(() => {
       const backend = createFakeBackend();
diff --git a/test/unit/host/replay.test.ts b/test/unit/host/replay.test.ts
index 85a4383..26432a6 100644
--- a/test/unit/host/replay.test.ts
+++ b/test/unit/host/replay.test.ts
@@ -79,7 +79,7 @@ let eventLogPath = '';
 describe('replay helpers', () => {
   beforeEach(async () => {
     // prettier-ignore
-    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-replay-')));
+    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-replay-')));
     eventLogPath = join(tempDir, 'events.jsonl');
   });
 
diff --git a/test/unit/renderer/browserPath.test.ts b/test/unit/renderer/browserPath.test.ts
index f318fd6..6f0a786 100644
--- a/test/unit/renderer/browserPath.test.ts
+++ b/test/unit/renderer/browserPath.test.ts
@@ -21,7 +21,7 @@ async function createPlaywrightCacheHome(): Promise<{
   browserCachePath: string;
   home: string;
 }> {
-  const home = await createHomeDirectory('agent-terminal-browser-path-');
+  const home = await createHomeDirectory('agent-tty-browser-path-');
   const browserCachePath = join(home, '.cache', 'ms-playwright');
   await mkdir(join(browserCachePath, 'chromium-1234'), { recursive: true });
   return { browserCachePath, home };
@@ -67,7 +67,7 @@ describe('Playwright browser path resolution', () => {
   });
 
   it('resolves macOS browser cache from captured HOME', async () => {
-    const home = await createHomeDirectory('agent-terminal-browser-path-mac-');
+    const home = await createHomeDirectory('agent-tty-browser-path-mac-');
     const macCachePath = join(home, 'Library', 'Caches', 'ms-playwright');
     await mkdir(join(macCachePath, 'chromium-1234'), { recursive: true });
 
@@ -111,9 +111,7 @@ describe('Playwright browser path resolution', () => {
   });
 
   it('returns null without crashing when no browser cache is present', async () => {
-    const home = await createHomeDirectory(
-      'agent-terminal-browser-path-empty-',
-    );
+    const home = await createHomeDirectory('agent-tty-browser-path-empty-');
     const env: NodeJS.ProcessEnv = {};
 
     const resolution = ensurePlaywrightBrowsersPath({
diff --git a/test/unit/replay/offlineReplay.test.ts b/test/unit/replay/offlineReplay.test.ts
index c697a78..61fa098 100644
--- a/test/unit/replay/offlineReplay.test.ts
+++ b/test/unit/replay/offlineReplay.test.ts
@@ -168,7 +168,7 @@ async function createSessionFixture(options?: {
   manifestOverrides?: Partial<SessionRecord>;
 }): Promise<{ sessionDir: string; sessionId: string }> {
   // prettier-ignore
-  const sessionDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-offline-replay-')));
+  const sessionDir = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-offline-replay-')));
   tempDirs.push(sessionDir);
 
   const sessionId = basename(sessionDir);
diff --git a/test/unit/storage/artifactHealth.test.ts b/test/unit/storage/artifactHealth.test.ts
index 17233e2..1c81203 100644
--- a/test/unit/storage/artifactHealth.test.ts
+++ b/test/unit/storage/artifactHealth.test.ts
@@ -28,7 +28,7 @@ afterEach(async () => {
 
 async function createSessionDir(sessionId = 'session-01'): Promise<string> {
   const home = await realpath(
-    await mkdtemp(join(tmpdir(), 'agent-terminal-artifact-health-')),
+    await mkdtemp(join(tmpdir(), 'agent-tty-artifact-health-')),
   );
   temporaryDirectories.push(home);
   return join(home, sessionId);
diff --git a/test/unit/storage/artifactStorage.test.ts b/test/unit/storage/artifactStorage.test.ts
index bd14764..5da456b 100644
--- a/test/unit/storage/artifactStorage.test.ts
+++ b/test/unit/storage/artifactStorage.test.ts
@@ -42,7 +42,7 @@ afterEach(async () => {
 
 async function createSessionDir(sessionId = 'session-01'): Promise<string> {
   // prettier-ignore
-  const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-artifacts-')));
+  const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-artifacts-')));
   temporaryDirectories.push(home);
   return join(home, sessionId);
 }
diff --git a/test/unit/storage/sessionPaths.test.ts b/test/unit/storage/sessionPaths.test.ts
index c701d92..2ec28a0 100644
--- a/test/unit/storage/sessionPaths.test.ts
+++ b/test/unit/storage/sessionPaths.test.ts
@@ -47,18 +47,18 @@ afterEach(async () => {
 
 describe('session paths', () => {
   it('builds session-specific absolute paths', () => {
-    const home = '/tmp/agent-terminal-home';
+    const home = '/tmp/agent-tty-home';
     const directory = sessionDir(home, 'session-01');
 
-    expect(directory).toBe('/tmp/agent-terminal-home/sessions/session-01');
+    expect(directory).toBe('/tmp/agent-tty-home/sessions/session-01');
     expect(manifestPath(directory)).toBe(
-      '/tmp/agent-terminal-home/sessions/session-01/session.json',
+      '/tmp/agent-tty-home/sessions/session-01/session.json',
     );
     expect(eventLogPath(directory)).toBe(
-      '/tmp/agent-terminal-home/sessions/session-01/events.jsonl',
+      '/tmp/agent-tty-home/sessions/session-01/events.jsonl',
     );
     expect(socketPath(directory)).toBe(
-      '/tmp/agent-terminal-home/sessions/session-01/host.sock',
+      '/tmp/agent-tty-home/sessions/session-01/host.sock',
     );
   });
 
@@ -84,7 +84,7 @@ describe('session paths', () => {
 describe('manifest storage', () => {
   it('writes and reads manifests with validation', async () => {
     // prettier-ignore
-    const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-home-')));
+    const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-home-')));
     temporaryDirectories.push(home);
     const path = manifestPath(sessionDir(home, 'session-01'));
     const record = createSessionRecord();
@@ -98,7 +98,7 @@ describe('manifest storage', () => {
 
   it('returns null when a manifest does not exist', async () => {
     // prettier-ignore
-    const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-home-')));
+    const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-home-')));
     temporaryDirectories.push(home);
     const path = manifestPath(sessionDir(home, 'missing-session'));
 
@@ -107,7 +107,7 @@ describe('manifest storage', () => {
 
   it('rejects invalid manifest contents during reads', async () => {
     // prettier-ignore
-    const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-home-')));
+    const home = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-home-')));
     temporaryDirectories.push(home);
     const path = manifestPath(sessionDir(home, 'session-01'));
 
diff --git a/test/unit/tools/review-bundle.test.ts b/test/unit/tools/review-bundle.test.ts
index 553e686..558f7be 100644
--- a/test/unit/tools/review-bundle.test.ts
+++ b/test/unit/tools/review-bundle.test.ts
@@ -25,7 +25,7 @@ const tempDirs: string[] = [];
 
 async function createTempDir(): Promise<string> {
   // prettier-ignore
-  const directory = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-review-bundle-')));
+  const directory = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-review-bundle-')));
   tempDirs.push(directory);
   return directory;
 }
diff --git a/test/unit/tools/validate-bundle.test.ts b/test/unit/tools/validate-bundle.test.ts
index 59b9729..3263820 100644
--- a/test/unit/tools/validate-bundle.test.ts
+++ b/test/unit/tools/validate-bundle.test.ts
@@ -23,7 +23,7 @@ const tempDirs: string[] = [];
 
 async function createTempDir(): Promise<string> {
   // prettier-ignore
-  const directory = await realpath(await mkdtemp(join(tmpdir(), 'agent-terminal-validate-bundle-')));
+  const directory = await realpath(await mkdtemp(join(tmpdir(), 'agent-tty-validate-bundle-')));
   tempDirs.push(directory);
   return directory;
 }
@@ -222,7 +222,7 @@ describe('validate-bundle', () => {
   it('fails when the bundle directory does not exist', async () => {
     const missingBundleRoot = join(
       tmpdir(),
-      'agent-terminal-validate-bundle-does-not-exist',
+      'agent-tty-validate-bundle-does-not-exist',
     );
 
     const result = await validateBundle(
diff --git a/test/unit/util/logger.test.ts b/test/unit/util/logger.test.ts
index a51f7f1..5d5d609 100644
--- a/test/unit/util/logger.test.ts
+++ b/test/unit/util/logger.test.ts
@@ -54,30 +54,30 @@ describe('Logger', () => {
       {
         loggerLevel: 'debug' as const,
         expectedWrites: [
-          '[agent-terminal] debug: visible debug\n',
-          '[agent-terminal] info: visible info\n',
-          '[agent-terminal] warn: visible warn\n',
-          '[agent-terminal] error: visible error\n',
+          '[agent-tty] debug: visible debug\n',
+          '[agent-tty] info: visible info\n',
+          '[agent-tty] warn: visible warn\n',
+          '[agent-tty] error: visible error\n',
         ],
       },
       {
         loggerLevel: 'info' as const,
         expectedWrites: [
-          '[agent-terminal] info: visible info\n',
-          '[agent-terminal] warn: visible warn\n',
-          '[agent-terminal] error: visible error\n',
+          '[agent-tty] info: visible info\n',
+          '[agent-tty] warn: visible warn\n',
+          '[agent-tty] error: visible error\n',
         ],
       },
       {
         loggerLevel: 'warn' as const,
         expectedWrites: [
-          '[agent-terminal] warn: visible warn\n',
-          '[agent-terminal] error: visible error\n',
+          '[agent-tty] warn: visible warn\n',
+          '[agent-tty] error: visible error\n',
         ],
       },
       {
         loggerLevel: 'error' as const,
-        expectedWrites: ['[agent-terminal] error: visible error\n'],
+        expectedWrites: ['[agent-tty] error: visible error\n'],
       },
     ];
 
@@ -102,7 +102,7 @@ describe('Logger', () => {
 
     expect(logger.getLevel()).toBe('debug');
     expect(writes).toHaveLength(1);
-    expect(writes[0]).toContain('[agent-terminal] debug: context');
+    expect(writes[0]).toContain('[agent-tty] debug: context');
     expect(writes[0]).toContain('{"command":"doctor"}');
     expect(writes[0]).toContain('boom');
   });
@@ -122,33 +122,30 @@ describe('Logger', () => {
     expect(() => logger.debug('msg', BigInt(42))).not.toThrow();
 
     expect(writes).toEqual([
-      '[agent-terminal] debug: msg null\n',
-      '[agent-terminal] debug: msg undefined\n',
-      '[agent-terminal] debug: msg 42\n',
-      '[agent-terminal] debug: msg true\n',
-      '[agent-terminal] debug: msg [object Object]\n',
-      '[agent-terminal] debug: msg Symbol(test)\n',
-      '[agent-terminal] debug: msg 42\n',
+      '[agent-tty] debug: msg null\n',
+      '[agent-tty] debug: msg undefined\n',
+      '[agent-tty] debug: msg 42\n',
+      '[agent-tty] debug: msg true\n',
+      '[agent-tty] debug: msg [object Object]\n',
+      '[agent-tty] debug: msg Symbol(test)\n',
+      '[agent-tty] debug: msg 42\n',
     ]);
   });
 
   it('creates a process logger from env', () => {
     const { writes, sink } = createSink();
-    const logger = createProcessLogger(
-      { AGENT_TERMINAL_LOG_LEVEL: 'error' },
-      sink,
-    );
+    const logger = createProcessLogger({ AGENT_TTY_LOG_LEVEL: 'error' }, sink);
 
     logger.warn('hidden warn');
     logger.error('visible error');
 
-    expect(writes).toEqual(['[agent-terminal] error: visible error\n']);
+    expect(writes).toEqual(['[agent-tty] error: visible error\n']);
   });
 
   it('defaults process loggers to info when the env var is missing or undefined', () => {
     for (const env of [
       {},
-      { AGENT_TERMINAL_LOG_LEVEL: undefined },
+      { AGENT_TTY_LOG_LEVEL: undefined },
     ] satisfies Array<NodeJS.ProcessEnv>) {
       const { writes, sink } = createSink();
       const logger = createProcessLogger(env, sink);
@@ -158,7 +155,7 @@ describe('Logger', () => {
       logger.debug('hidden debug');
       logger.info('visible info');
 
-      expect(writes).toEqual(['[agent-terminal] info: visible info\n']);
+      expect(writes).toEqual(['[agent-tty] info: visible info\n']);
     }
   });