[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-09

Added

• record diff <session-a> <session-b> replays two sessions offline and reports an LCS line diff between their canonical visible screens, with --at-seq-a/--at-seq-b for self-diffs against earlier state (#170).
• record export --format svg [--animate] writes a deterministic, byte-stable SVG (SMIL-animated or still) with no browser or ffmpeg; bundles JetBrains Mono and symbol-font subsets (#171, #349).
• screenshot --out <path> writes the PNG to an explicit path (relative or absolute), with a shared --out resolver that also refuses paths inside session storage (#241).
• screenshot --out and record export --out now create missing parent folders like mkdir -p, except inside sessions/ (#290).
• mouse CLI/RPC command and batch step: mode-aware native mouse input (clicks, drags, wheel) through the libghostty-vt backend, logged as input_mouse events; introduces the CAPABILITY_UNAVAILABLE error (exit 12) (#179).
• wait --scope cursor-line matches --text/--regex against the cursor row only, avoiding echo-of-command false positives; also available on batch wait steps (#169).
• screenshot --json reports glyphs drawn as .notdef boxes in missingGlyphs with their cells, plus missingGlyphsTruncated; record export --format webm reports the same per-code-point list (#240, #278).
• Noto Sans Symbols 2 and Noto Sans Math subsets are now bundled and fall back after host monospace, so many previously-boxed symbols render without changing text-default emoji (#278).
• Session programs now get AGENT_TTY_ACTIVE=true and AGENT_TTY_SESSION_ID=<uuid> in their environment (#166).
• Sessions now default COLORTERM=truecolor, and the PTY query responder answers XTGETTCAP Tc/RGB/setrgbf/setrgbb and declines DECRQSS SGR, so programs like Neovim enable 24-bit color under env -i or --env COLORTERM= (#231, #271).
• inspect --json reports eventLogStop (reason, seq) when the host has stopped appending at a limit; WAIT_TIMEOUT and offline REPLAY_ERROR messages/details name the stop (#340, #357).

Changed

• Build: migrated from aube to pnpm (10.34.5); contributors run pnpm install / mise run bootstrap and Dependabot can now update pnpm-lock.yaml (#176).
• wait default timeout is now 30 s (was 600 s); wait --help shows the default. Windows that cannot finish inside the timeout (--idle-ms, --screen-stable-ms) are rejected up front with INVALID_DURATION. Batch wait steps share the same default and the same window rule (#236, #250, #277).
• Timed-out wait now returns an error envelope with ok: false, error.code: "WAIT_TIMEOUT" (exit 11 unchanged), while preserving result.timedOut/matched. Fail-fast batch failures emit the matching error envelope with step details (#232, #273, #301).
• A render wait that fails every poll now stops with the renderer's error (for example REPLAY_ERROR) instead of reporting WAIT_TIMEOUT (#301).
• Unexpected errors print one INTERNAL_ERROR JSON envelope on stdout under --json, and the CLI exits promptly after it instead of hanging on open handles. Empty/invalid session IDs return INVALID_SESSION_ID (exit 2) on every command. Commander usage errors emit an INVALID_INPUT envelope under --json (#237, #287).
• Live-command errors from the session host now carry details across RPC (e.g. details.path, details.errno), matching offline errors (#313).
• Node version is checked against engines.node (>=24.0.0 <27) at startup with a one-line stderr warning; doctor fails on versions outside that range (#245).
• snapshot --include-cells now accepts RPC responses up to 64 MiB (previously capped at 1 MiB); larger successes return PROTOCOL_ERROR with the size (#320).
• config.json errors are typed: unreadable → STORAGE_READ_ERROR, invalid JSON/schema → INVALID_INPUT. list on an unreadable sessions dir returns STORAGE_READ_ERROR. help exits 0 (#287).
• screenshot/record export with a non-folder or dangling symlink at artifacts/ now give STORAGE_WRITE_ERROR (exit 8) with a clear message (#287, #301).
• WebM exports no longer impose a total 5-minute replay deadline. The replay fails only when the renderer makes no progress for 5 minutes, and the error names the window and the last event (#356).
• record export --format webm on a session that printed nothing exits 0 with a blank video at capturedAtSeq: -1; asciicast reports -1 instead of 0 (#270).
• destroy typed into the session's own shell now forwards SIGINT/SIGTERM to its detached re-run copy and exits 130/143 to match (#281).
• destroy --force records a session as destroyed when the program-group read fails twice with EACCES/EPERM/EIO/EISDIR/ENOTDIR/ELOOP/ENAMETOOLONG, or when it cannot read the program group at all (#327, #331, #334).

Fixed

• snapshot/screenshot on a session that has printed nothing now return an empty screen or blank PNG at capturedAtSeq: -1 instead of failing with RPC_ERROR (#235).
• screenshot --hide-cursor actually hides the block cursor in the PNG (was previously byte-identical to --show-cursor) (#289).
• WebM output now shows printed lines at their recorded time instead of batching to the next non-output event (#285).
• ghostty-web replay is roughly 50x faster: 20,000-event screenshots dropped from ~386 s to ~7 s. Each replay flush now writes in one animation frame; max-speed WebM respects recorded time and holds one video frame before resizes (#358, #364).
• Live screenshot/snapshot --renderer ghostty-web on long logs no longer time out at 5 s: the host streams keep-alives and replays the backlog in bounded slices, so clients wait as long as replay progresses (#359).
• A ghostty-web page crash during replay is now reported as REPLAY_ERROR (exit 10, retryable: false) on live and offline paths with a message that names the known cause, instead of RPC_ERROR/INTERNAL_ERROR with retries that can never succeed (#363).
• create under heavy host load now waits for the detached host as long as it is alive (up to 30 s on a monotonic clock) and treats first-probe EPIPE as "not ready yet", instead of failing with HOST_UNREACHABLE after a fixed 50-poll budget (#362).
• create that gives up on its host now instructs that host to stop the session, so no orphan running session is left behind (#247).
• Concurrent captures no longer drop entries from artifacts/manifest.json: appends run under a cross-process lock with stale-owner recovery (#282).
• Multiple session-lifecycle race fixes across create/reconcile/gc/destroy: hosts record pids up front, writeManifest no longer resurrects removed session folders, gc keeps exited sessions whose program group still runs (so destroy can end them), and destroy --force provably covers unshared/hidden-proc cases (#181, #194, #200, #201, #216, #221, #302, #312).
• Event log stops gracefully at the 50 MiB / 250,000-event limit with a labeled stop marker instead of crashing the host or failing every subsequent export/snapshot (#340).
• pty no longer leaks an outer session id into session-less PTYs (#178).
• Waited run input is now logged in PTY order, and mouse motion dedup state is preserved across renderer swaps (#234).
• Repeated captures keep earlier artifact files instead of clobbering each other; exports are taken from their temp file to avoid races (#191, #316, #321).
• Per-session sockets are now rooted under a per-uid path and dead-host sockets are removed; host.json refuses to grow a hostname-mismatched stub (#239, #288, #305).
• RPC: request id capped at 128 chars; response cap raised to 64 MiB with PROTOCOL_ERROR above; truncated error messages no longer split surrogate pairs; older-host oversize responses are reported as PROTOCOL_ERROR (#315, #319, #320, #322).
• create validates cwd and shell before creating the session directory (#188).
• --out writes retry against a swapped output folder and refuse unsearchable parents, and a failed screenshot --out undoes its in-session capture (#279, #300).
• SVG export now succeeds as a still when the session clock stepped backward; --animate surfaces a clear EXPORT_ERROR naming the first bad event (#349).
• Numerous additional host, storage, destroy, verify-skill and lifecycle-model fixes — see the full changelog for the complete list.

Breaking Changes

• wait default timeout dropped from 600 s to 30 s (#236). Scripts that relied on waiting longer than 30 s must pass --timeout explicitly (or --timeout 0 to wait without a limit). Batch wait steps share the new default (#250).
• Timed-out wait returns ok: false with error.code: "WAIT_TIMEOUT"; consumers checking .ok === true on a timeout will now see false. .result.timedOut/matched still carry the old fields. Fail-fast batch failures also now emit ok: false (#232).
• Render wait on persistent renderer failure now exits 9 RPC_ERROR (or the renderer's own CliError code such as REPLAY_ERROR), not exit 11 WAIT_TIMEOUT (#301).
• Inherited COLORTERM from the shell that runs agent-tty create no longer reaches the session; sessions see COLORTERM=truecolor unless overridden with --env COLORTERM=<value> (#231).
• Invalid session IDs on most commands now return exit 2 INVALID_SESSION_ID instead of exit 1 with a stack trace (#237).
• Downgrade compatibility note: an older CLI against a new host may see RPC_ERROR "RPC result failed validation" for new optional fields such as eventLogStop, mouse-input capability, or details on live errors; newer CLI against older hosts works fine (#179, #313, #357).
• record export --format asciicast on an empty log names its file recording--1-asciicast.cast (was recording-0-asciicast.cast); capturedAtSeq can now be -1 in result schemas (#235, #270).
• screenshot/record export --out paths that resolve inside sessions/ are rejected with exit 7 EXPORT_ERROR (previously accepted for record export) (#241).

---

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