[github-actions]

The next agent-tty release. Merging this PR creates the release tag and GitHub Release and starts the publish pipeline.

[0.6.0] - 2026-11-10

Added

• mouse CLI/RPC command and batch step for mode-aware mouse input (clicks, drags, wheel, motion) through the native libghostty-vt backend. Adds mouse-input capability and new CAPABILITY_UNAVAILABLE error (exit 12) when the optional native package is missing or lacks mouse encoding. Also pins @coder/libghostty-vt-node to 0.1.0-beta.7 (#179, #293).
• record export --format svg [--animate] writes a browserless, byte-deterministic SVG of a session. Still exports capture the final frame; --animate uses SMIL keyed to recorded event timing. Fonts are embedded on demand (JetBrains Mono always, Noto Symbols 2 / Noto Sans Math and Nerd Font Symbols when needed). Requires the optional libghostty-vt package; no browser fallback (#171, #349).
• record diff <session-id-a> <session-id-b> offline command replays both sessions and prints a bounded LCS line diff with per-side screenHash, cols, rows, and capturedAtSeq. Supports --at-seq-a / --at-seq-b (including -1 for empty logs) for self-diffing a session against its own earlier state (#170, #300).
• wait --scope cursor-line (and a matching scope field on batch wait steps and the waitForRender RPC) restricts --text / --regex matching to the cursor row, eliminating the terminal-echo false positive and making prompt waits precise (#169).
• screenshot --out <path> writes the PNG to a chosen path while still publishing the in-session artifact. The --out resolver is shared with record export, refuses paths inside session storage, and creates missing parent folders like mkdir -p (#241, #279, #290).
• screenshot --json reports missingGlyphs (with cells and missingGlyphsTruncated) listing graphemes that Chromium drew as .notdef boxes. record export --format webm reports missingGlyphs across all painted frames (#240, #278).
• PTYs now inherit AGENT_TTY_ACTIVE=true and AGENT_TTY_SESSION_ID=<id> so shell wrappers and prompts can detect the active managed session (#166, #178).
• Default COLORTERM=truecolor in every session, and the PTY now answers XTGETTCAP (Tc, RGB, setrgbf, setrgbb) and declines DECRQSS SGR so Neovim enables termguicolors even under env -i (#231, #271).
• inspect reports eventLogStop: { reason: "bytes" | "events" | "unknown", seq } and a human line when the event log has stopped; timed-out wait and batch wait steps attach the stop to their message and details.eventLogStop (#357).
• Startup warning on an unsupported Node (checked against engines.node >=24.0.0 <27); doctor's node-runtime check now uses the same range (#245).

Changed

• Build system migrated from aube to pnpm 10.34.5. aube-lock.yaml is replaced by pnpm-lock.yaml, mise run bootstrap and bootstrap-ci use pnpm, and Dependabot now works. No resolved versions change (#176).
• Playwright bumped from 1.60.0 to 1.64.1 so Chromium installs on Ubuntu 26.04. Chromium moves from 148 to 156 and WebM export now uses VP9. After upgrading run npx playwright@1.64.1 install chromium (#192, #370).
• Default wait --timeout is now 30 s (was 600 s) for both the standalone wait command and batch wait steps; --timeout 0 still waits forever and the default is printed in --help. Impossible --idle-ms / --screen-stable-ms windows are rejected up front with INVALID_DURATION (exit 2) (#236, #250, #277).
• A timed-out wait now emits ok: false with error.code: "WAIT_TIMEOUT" while preserving result.timedOut, result.matched, and result.capturedAtSeq. Fail-fast batches print an error envelope with the failed step's code, message, and full per-step result (#232, #273, #301).
• RPC responses are accepted up to 64 MiB so snapshot --include-cells works on large live grids (up to ~1.2 million styled cells). Responses larger than the cap fail with PROTOCOL_ERROR (exit 9, not retryable). Live snapshots with cells now use a 60 s client timeout (#320, #322).
• Live render calls now stream progress back to the CLI via inline whitespace keep-alives, so a long replay (up to 250,000 events) no longer trips the 5 s HOST_TIMEOUT; queued commands behind a slow render stay alive too (#359).
• ghostty-web replay is 5-50x faster: each flush writes to the WASM terminal in one frame instead of one frame per chunk. A 20,000-event screenshot drops from ~386 s to ~7 s; viewport reads happen once per decode (#358, #365).
• WebM export shows output at its recorded time (previous recorded / accelerated modes bunched output until the next non-output event) and no longer has a hard 5-minute replay cap - it fails only when the renderer stalls for 5 minutes (#285, #356, #364).
• Per-session RPC sockets moved to /tmp/agent-tty-<uid>/ (a 0o700 per-uid root). Downgrade note: an older CLI cannot reach a host that this version started, so destroy sessions before downgrading (#288).
• CliError details now cross the host RPC, so live snapshot / screenshot errors carry the same details.path, details.errno, etc. as the offline paths. An older CLI against this host sees RPC_ERROR schema-validation errors for new fields (#313).
• The event log is now bounded in-session: writes stop at 50 MiB or 250,000 entries with a labeled marker, and every reader (snapshot, screenshot, wait, record export, record diff) names the limit in its error instead of failing with a generic message (#340).
• Empty event logs are now valid for snapshot, screenshot, render wait, and record export (asciicast and WebM): they return a blank screen / PNG / header / video at capturedAtSeq: -1 (#235, #270).

Fixed

• CLI error reporting hardened: unexpected errors, invalid session IDs, Commander usage errors, and config errors under --json now always print one INTERNAL_ERROR / INVALID_INPUT / STORAGE_READ_ERROR envelope on stdout; INTERNAL_ERROR now forces exit after flush so leaked handles cannot hang the CLI; help exits 0 (#237, #287).
• Artifact manifest writes are now locked across processes with <sessionDir>/artifacts/manifest.json.lock, so concurrent screenshot / snapshot / record export calls keep every entry. Over-the-limit lock wait fails with retryable STORAGE_WRITE_ERROR (#282).
• Repeat record export to the same seq or --out path keeps one manifest entry per exported file and replaces the earlier entry; failed screenshot --out copies roll back the in-session capture (#191, #300, #316).
• screenshot --show-cursor / --hide-cursor now actually toggle the block cursor in the PNG (ghostty-web only redrew dirty rows before) (#289).
• WebM bytes / SHA-256 are now read from the temp file before the rename, so a concurrent write to the --out path cannot lend its bytes to the manifest entry (#321).
• ghostty-web page crashes during replay (After RIS, ?47h/?1047h shows old primary-screen cells on the alternate screen, and a grapheme cluster there makes the next write over it trap ghostty-web#215) are now reported as REPLAY_ERROR (exit 10, not retryable) with the known cause named in the message, for both live and offline screenshot / snapshot / wait paths (#363).
• create now waits for a host that is still starting under heavy load (previously gave up after ~5 s of polling) and treats a transient EPIPE probe as not-ready; it also stops the host and names the session in error.details.sessionId on every readiness-wait error, and leaves a create-failed marker so a late-starting Windows host stops itself (#247, #294, #312, #362).
• destroy lifecycle: idle-timeout kills the program group like shutdown does; EPERM from a group kill no longer crashes the host; a destroy typed into the session's own shell re-runs in a new session and forwards SIGINT / SIGTERM to that copy; destroy --force ends sessions whose program group cannot be read; many race fixes in reconcile, gc, host-record, socket cleanup, and the lifecycle TLA+ model (#181, #194, #201, #216, #221, #246, #281, #283, #302, #327, #331).
• Home-registry read now drops only invalid entries, so one bad entry no longer wipes every registered Home from home list, gc, and the dashboard on the next create (#186).
• Waited run now logs its input_run event in PTY order (a concurrent type can no longer land ahead of it in the log), and mouse input gets its own renderer manager so same-cell dedup survives renderer swaps (#234).
• record export --format webm records at a stable 25 fps with fps set explicitly in Playwright recordVideo, and holds one video frame before a resize in max-speed so the pre-resize screen reliably reaches the file (#364).

Docs

• New ## Chromium section in docs/INSTALL.md with a version-pinned Playwright install command chain, plus mise and npm 12 install sections and troubleshooting for Failed to load native module: pty.node (#367, #368, #370).
• Shell-environment docs now explain that a query printed from a shell command leaves agent-tty's reply at the next prompt, breaking the next run (#298).

Breaking Changes

• Build system migrated from aube to pnpm. Bootstrap with pnpm install (or mise run bootstrap), not aube ci. aube-lock.yaml is replaced by pnpm-lock.yaml (#176).
• Playwright 1.64.1 + Chromium 156. After upgrading, run npx playwright@1.64.1 install chromium before screenshot or record export --format webm works. WebM exports are now VP9 instead of VP8 (#192).
• RPC sockets moved to /tmp/agent-tty-<uid>/<home-hash>/<session-id>. Scripts that compute the socket path from the old /tmp/agent-tty/... layout must read host.rpcSocketPath from inspect --json. An older CLI cannot reach a host that this version started; a sudo agent-tty run with a different uid cannot reach your sessions (#288).
• Timed-out wait returns ok: false with error.code: "WAIT_TIMEOUT". result.timedOut, result.matched, and result.capturedAtSeq are preserved under the envelope. Automation that branches on .ok == true must now consult error.code (#232).
• Default wait --timeout is 30 s (was 600 s). Scripts that relied on the old implicit 10-minute wait must now pass --timeout explicitly. Batch wait steps got the same 30 s default (#236, #250).
• Render wait that fails every renderer poll now exits 9 RPC_ERROR (or the underlying REPLAY_ERROR with exit 10) with the renderer's message, instead of exit 11 WAIT_TIMEOUT. WAIT_TIMEOUT now only means the timeout elapsed (#301).
• capturedAtSeq: -1 is now a valid value in snapshot, screenshot, render-wait, record diff, and record export results (and wait --after-seq) for sessions that have not printed yet. Default filenames include -1, e.g. recording--1-webm.webm. Clients that validated capturedAtSeq >= 0 must relax to >= -1 (#235, #270).
• Live host RPC now carries CliError details (RpcErrorSchema gained an optional details). An older CLI talking to a newer host will fail new error responses with RPC_ERROR "RPC response failed schema validation." - downgrades of a running session are not supported (#313).
• Supported Node range now enforced at startup: >=24.0.0 <27 prints a stderr warning on an unsupported runtime (#245).

New Contributors

• @pmarreck made their first contribution in #179
• @prmartinow made their first contribution in #166

---

Maintained by the release-please workflow. Notes are regenerated by Communique on every push to main, so manual edits to this PR are overwritten.