Fix review findings for input handling and docs

Author: ThomasK33

README.md

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

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

@@ -35,6 +35,11 @@ The repo also now has four Week 4 proof bundles that cover the shipped gap-closi
 - `dogfood/20260322-week4-scrollback-review/` proves scrollback capture and replay review,
 - and `dogfood/20260322-week4-unicode-review/` proves unicode/width review coverage.
 
+Bugfix verification bundles also ship alongside that Week 4 coverage:
+
+- `dogfood/20260323-bugfix-resize/` proves post-resize snapshot/screenshot recovery,
+- and `dogfood/20260323-bugfix-scrollback/` proves scrollback viewport normalization.
+
 Earlier proof bundles remain relevant context:
 
 - `dogfood/20260321-post-hardening-smoke/` revalidates live inspect/wait/snapshot/screenshot/doctor flows,

dogfood/20260323-bugfix-resize/notes.md

@@ -13,20 +13,20 @@ Scenario B-redux completed successfully. The previously failing post-resize `scr
 
 ## Command log
 
-| User step | Stored file | Exit code | Command |
-| --- | --- | ---: | --- |
-| 2 | `01-create.json` | 0 | `npx tsx src/cli/main.ts create --cols 120 --rows 40 --json -- npx tsx test/fixtures/apps/resize-demo/main.ts` |
-| 3 | `02-wait-size.json` | 0 | `npx tsx src/cli/main.ts wait 01KMCYX32BMKX4F48WRMRSDC12 --text "SIZE:" --json` |
-| 4 | `03-screenshot-before-resize.json` | 0 | `npx tsx src/cli/main.ts screenshot 01KMCYX32BMKX4F48WRMRSDC12 --json` |
-| 5 | `04-resize-large.json` | 0 | `npx tsx src/cli/main.ts resize 01KMCYX32BMKX4F48WRMRSDC12 --cols 140 --rows 50 --json` |
-| 6 | `05-wait-stable-large.json` | 0 | `npx tsx src/cli/main.ts wait 01KMCYX32BMKX4F48WRMRSDC12 --screen-stable-ms 500 --json` |
-| 7 | `06-screenshot-after-resize-large.json` | 0 | `npx tsx src/cli/main.ts screenshot 01KMCYX32BMKX4F48WRMRSDC12 --json` |
-| 8 | `07-snapshot-after-resize-large.json` | 0 | `npx tsx src/cli/main.ts snapshot 01KMCYX32BMKX4F48WRMRSDC12 --json` |
-| 9 | `08-resize-small.json` | 0 | `npx tsx src/cli/main.ts resize 01KMCYX32BMKX4F48WRMRSDC12 --cols 80 --rows 24 --json` |
-| 10 | `09-wait-stable-small.json` | 0 | `npx tsx src/cli/main.ts wait 01KMCYX32BMKX4F48WRMRSDC12 --screen-stable-ms 500 --json` |
-| 11 | `10-screenshot-after-resize-small.json` | 0 | `npx tsx src/cli/main.ts screenshot 01KMCYX32BMKX4F48WRMRSDC12 --json` |
-| 12 | `11-snapshot-after-resize-small.json` | 0 | `npx tsx src/cli/main.ts snapshot 01KMCYX32BMKX4F48WRMRSDC12 --json` |
-| 13 | `12-destroy.json` | 0 | `npx tsx src/cli/main.ts destroy 01KMCYX32BMKX4F48WRMRSDC12 --json` |
+| User step | Stored file                             | Exit code | Command                                                                                                        |
+| --------- | --------------------------------------- | --------: | -------------------------------------------------------------------------------------------------------------- |
+| 2         | `01-create.json`                        |         0 | `npx tsx src/cli/main.ts create --cols 120 --rows 40 --json -- npx tsx test/fixtures/apps/resize-demo/main.ts` |
+| 3         | `02-wait-size.json`                     |         0 | `npx tsx src/cli/main.ts wait 01KMCYX32BMKX4F48WRMRSDC12 --text "SIZE:" --json`                                |
+| 4         | `03-screenshot-before-resize.json`      |         0 | `npx tsx src/cli/main.ts screenshot 01KMCYX32BMKX4F48WRMRSDC12 --json`                                         |
+| 5         | `04-resize-large.json`                  |         0 | `npx tsx src/cli/main.ts resize 01KMCYX32BMKX4F48WRMRSDC12 --cols 140 --rows 50 --json`                        |
+| 6         | `05-wait-stable-large.json`             |         0 | `npx tsx src/cli/main.ts wait 01KMCYX32BMKX4F48WRMRSDC12 --screen-stable-ms 500 --json`                        |
+| 7         | `06-screenshot-after-resize-large.json` |         0 | `npx tsx src/cli/main.ts screenshot 01KMCYX32BMKX4F48WRMRSDC12 --json`                                         |
+| 8         | `07-snapshot-after-resize-large.json`   |         0 | `npx tsx src/cli/main.ts snapshot 01KMCYX32BMKX4F48WRMRSDC12 --json`                                           |
+| 9         | `08-resize-small.json`                  |         0 | `npx tsx src/cli/main.ts resize 01KMCYX32BMKX4F48WRMRSDC12 --cols 80 --rows 24 --json`                         |
+| 10        | `09-wait-stable-small.json`             |         0 | `npx tsx src/cli/main.ts wait 01KMCYX32BMKX4F48WRMRSDC12 --screen-stable-ms 500 --json`                        |
+| 11        | `10-screenshot-after-resize-small.json` |         0 | `npx tsx src/cli/main.ts screenshot 01KMCYX32BMKX4F48WRMRSDC12 --json`                                         |
+| 12        | `11-snapshot-after-resize-small.json`   |         0 | `npx tsx src/cli/main.ts snapshot 01KMCYX32BMKX4F48WRMRSDC12 --json`                                           |
+| 13        | `12-destroy.json`                       |         0 | `npx tsx src/cli/main.ts destroy 01KMCYX32BMKX4F48WRMRSDC12 --json`                                            |
 
 ## Previously failing steps
 

dogfood/20260323-bugfix-resize/summary.json

@@ -55,4 +55,4 @@
       "text": ""
     }
   ]
-}
+}

dogfood/20260323-bugfix-scrollback/notes.md

@@ -13,15 +13,15 @@ Scenario F-redux completed successfully. The wait matched `SCROLLBACK COMPLETE`,
 
 ## Command log
 
-| User step | Stored file | Exit code | Command |
-| --- | --- | ---: | --- |
-| 2 | `01-create.json` | 0 | `npx tsx src/cli/main.ts create --cols 80 --rows 24 --json -- npx tsx test/fixtures/apps/scrollback-demo/main.ts` |
-| 3 | `02-wait-text.json` | 0 | `npx tsx src/cli/main.ts wait 01KMCYYK6GSKR6ZF3NAW7GFE5N --text "SCROLLBACK COMPLETE" --timeout 10000 --json` |
-| 4 | `03-snapshot-viewport.json` | 0 | `npx tsx src/cli/main.ts snapshot 01KMCYYK6GSKR6ZF3NAW7GFE5N --json` |
-| 5 | `04-snapshot-scrollback.json` | 0 | `npx tsx src/cli/main.ts snapshot 01KMCYYK6GSKR6ZF3NAW7GFE5N --include-scrollback --json` |
-| 6 | `05-screenshot.json` | 0 | `npx tsx src/cli/main.ts screenshot 01KMCYYK6GSKR6ZF3NAW7GFE5N --json` |
-| 7 | `06-wait-exit.txt` | 0 | `npx tsx src/cli/main.ts wait 01KMCYYK6GSKR6ZF3NAW7GFE5N --exit` |
-| 8 | `07-destroy.json` | 0 | `npx tsx src/cli/main.ts destroy 01KMCYYK6GSKR6ZF3NAW7GFE5N --json` |
+| User step | Stored file                   | Exit code | Command                                                                                                           |
+| --------- | ----------------------------- | --------: | ----------------------------------------------------------------------------------------------------------------- |
+| 2         | `01-create.json`              |         0 | `npx tsx src/cli/main.ts create --cols 80 --rows 24 --json -- npx tsx test/fixtures/apps/scrollback-demo/main.ts` |
+| 3         | `02-wait-text.json`           |         0 | `npx tsx src/cli/main.ts wait 01KMCYYK6GSKR6ZF3NAW7GFE5N --text "SCROLLBACK COMPLETE" --timeout 10000 --json`     |
+| 4         | `03-snapshot-viewport.json`   |         0 | `npx tsx src/cli/main.ts snapshot 01KMCYYK6GSKR6ZF3NAW7GFE5N --json`                                              |
+| 5         | `04-snapshot-scrollback.json` |         0 | `npx tsx src/cli/main.ts snapshot 01KMCYYK6GSKR6ZF3NAW7GFE5N --include-scrollback --json`                         |
+| 6         | `05-screenshot.json`          |         0 | `npx tsx src/cli/main.ts screenshot 01KMCYYK6GSKR6ZF3NAW7GFE5N --json`                                            |
+| 7         | `06-wait-exit.txt`            |         0 | `npx tsx src/cli/main.ts wait 01KMCYYK6GSKR6ZF3NAW7GFE5N --exit`                                                  |
+| 8         | `07-destroy.json`             |         0 | `npx tsx src/cli/main.ts destroy 01KMCYYK6GSKR6ZF3NAW7GFE5N --json`                                               |
 
 ## Previously failing checks
 

dogfood/20260323-bugfix-scrollback/summary.json

@@ -48,4 +48,4 @@
     }
   ],
   "screenshot": "05-screenshot.png"
-}
+}

src/cli/commands/inputSource.ts

@@ -1,6 +1,5 @@
 import assert from 'node:assert/strict';
-import { constants as fsConstants } from 'node:fs';
-import { access, readFile } from 'node:fs/promises';
+import { lstat, readFile, stat } from 'node:fs/promises';
 
 import { ERROR_CODES, makeCliError } from '../../protocol/errors.js';
 
@@ -10,6 +9,8 @@ interface ResolveCommandInputTextOptions {
   file: string | undefined;
 }
 
+export const MAX_INPUT_FILE_SIZE = 10_000_000;
+
 function createInvalidInputError(
   message: string,
   details?: Record<string, unknown>,
@@ -30,6 +31,88 @@ function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
   return error instanceof Error && 'code' in error;
 }
 
+function createInputFileLookupError(
+  filePath: string,
+  error: unknown,
+): ReturnType<typeof createInvalidInputError> {
+  if (isErrnoException(error) && error.code === 'ENOENT') {
+    return createInvalidInputError(
+      `Input file "${filePath}" was not found.`,
+      {
+        file: filePath,
+      },
+      error,
+    );
+  }
+
+  if (
+    isErrnoException(error) &&
+    ['EACCES', 'EPERM'].includes(error.code ?? '')
+  ) {
+    return createInvalidInputError(
+      `Input file "${filePath}" is not readable.`,
+      {
+        file: filePath,
+      },
+      error,
+    );
+  }
+
+  return createInvalidInputError(
+    `Failed to inspect input file "${filePath}".`,
+    {
+      file: filePath,
+    },
+    error,
+  );
+}
+
+function createInputFileReadError(
+  filePath: string,
+  error: unknown,
+): ReturnType<typeof createInvalidInputError> {
+  if (isErrnoException(error) && error.code === 'ENOENT') {
+    return createInvalidInputError(
+      `Input file "${filePath}" was not found.`,
+      {
+        file: filePath,
+      },
+      error,
+    );
+  }
+
+  if (
+    isErrnoException(error) &&
+    ['EACCES', 'EPERM'].includes(error.code ?? '')
+  ) {
+    return createInvalidInputError(
+      `Input file "${filePath}" is not readable.`,
+      {
+        file: filePath,
+      },
+      error,
+    );
+  }
+
+  if (isErrnoException(error) && error.code === 'EISDIR') {
+    return createInvalidInputError(
+      `Input file "${filePath}" must be a regular file. Directories, symlinks, and device files are not supported.`,
+      {
+        file: filePath,
+      },
+      error,
+    );
+  }
+
+  return createInvalidInputError(
+    `Failed to read input file "${filePath}".`,
+    {
+      file: filePath,
+    },
+    error,
+  );
+}
+
 export async function resolveCommandInputText(
   options: ResolveCommandInputTextOptions,
 ): Promise<string> {
@@ -68,28 +151,40 @@ export async function resolveCommandInputText(
   assert(typeof filePath === 'string', '--file must resolve to a string path');
   assert(filePath.length > 0, '--file path must be a non-empty string');
 
+  let fileStats: Awaited<ReturnType<typeof lstat>>;
   try {
-    await access(filePath, fsConstants.F_OK);
+    fileStats = await lstat(filePath);
   } catch (error: unknown) {
+    throw createInputFileLookupError(filePath, error);
+  }
+
+  if (!fileStats.isFile()) {
     throw createInvalidInputError(
-      `Input file "${filePath}" was not found.`,
+      `Input file "${filePath}" must be a regular file. Directories, symlinks, and device files are not supported.`,
       {
         file: filePath,
       },
-      error,
     );
   }
 
   try {
-    await access(filePath, fsConstants.R_OK);
+    const contentStats = await stat(filePath);
+    if (contentStats.size > MAX_INPUT_FILE_SIZE) {
+      throw createInvalidInputError(
+        `Input file "${filePath}" exceeds the 10 MB limit for --file input.`,
+        {
+          file: filePath,
+          sizeBytes: contentStats.size,
+          maxSizeBytes: MAX_INPUT_FILE_SIZE,
+        },
+      );
+    }
   } catch (error: unknown) {
-    throw createInvalidInputError(
-      `Input file "${filePath}" is not readable.`,
-      {
-        file: filePath,
-      },
-      error,
-    );
+    if (error instanceof Error && error.name === 'CliError') {
+      throw error;
+    }
+
+    throw createInputFileLookupError(filePath, error);
   }
 
   try {
@@ -114,22 +209,6 @@ export async function resolveCommandInputText(
       throw error;
     }
 
-    if (isErrnoException(error) && error.code === 'EISDIR') {
-      throw createInvalidInputError(
-        `Input file "${filePath}" must be a file, not a directory.`,
-        {
-          file: filePath,
-        },
-        error,
-      );
-    }
-
-    throw createInvalidInputError(
-      `Failed to read input file "${filePath}".`,
-      {
-        file: filePath,
-      },
-      error,
-    );
+    throw createInputFileReadError(filePath, error);
   }
 }

src/cli/exitCodes.ts

@@ -16,6 +16,11 @@ const EXIT_CODE_BY_ERROR_CODE: Readonly<Record<string, number>> = Object.freeze(
     [ERROR_CODES.EXPORT_ERROR]: 7,
     [ERROR_CODES.STORAGE_READ_ERROR]: 8,
     [ERROR_CODES.STORAGE_WRITE_ERROR]: 8,
+    [ERROR_CODES.MANIFEST_VALIDATION_ERROR]: 8,
+    [ERROR_CODES.PROTOCOL_ERROR]: 9,
+    [ERROR_CODES.RPC_ERROR]: 9,
+    [ERROR_CODES.REPLAY_ERROR]: 10,
+    [ERROR_CODES.INTERNAL_ERROR]: 1,
   },
 );
 

src/export/asciicast.ts

@@ -1,9 +1,8 @@
 import type { EventRecord, SessionRecord } from '../protocol/schemas.js';
 
+import { DEFAULT_TERM } from '../config/defaults.js';
 import { invariant } from '../util/assert.js';
 
-const DEFAULT_TERM = 'xterm-256color';
-
 export interface AsciicastHeader {
   version: 2;
   width: number;