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

Added

• Mode-aware native mouse input: new mouse CLI/RPC command and batch step for clicks, drags, motion, and wheel events through the libghostty-vt backend, plus a mouse-input capability and CAPABILITY_UNAVAILABLE (exit 12) when the native encoder is missing (#179, #234, #293).
• wait --scope cursor-line (and matching scope field on batch wait steps and the waitForRender RPC) matches --text/--regex only against the cursor row, avoiding echo-of-command false positives (#169).
• record diff <sid-a> <sid-b> replays two session event logs offline and emits a canonical line diff with --at-seq-a/--at-seq-b seek support and strict RecordDiffResultSchema output (#170, #300).
• screenshot --out <path> writes the PNG to an arbitrary path, sharing the record export --out resolver and rules; missing parent folders are auto-created like mkdir -p, but paths inside the Home's sessions/ folder are rejected (#241, #290).
• screenshot --json and record export --format webm --json now report .notdef-boxed glyphs in missingGlyphs (and missingGlyphsTruncated), with per-face classification via CDP postScriptName. Bundled WOFF2 subsets of Noto Sans Symbols 2 and Noto Sans Math (~378 KB, OFL-1.1) extend the default stack (#240, #278).
• PTY sessions now expose AGENT_TTY_ACTIVE=true and AGENT_TTY_SESSION_ID=<id> to spawned processes, so shell profiles can detect the managed session and reference its id (#166).
• PTY sets COLORTERM=truecolor by default and answers XTGETTCAP (Tc, RGB, setrgbf, setrgbb) and declines DECRQSS SGR, so Neovim under env -i now turns on termguicolors (#231, #271).

Changed

• Standalone wait without --timeout now defaults to 30 s (was 600 s) and the wait --help text names the default; batch wait steps default to the same 30 s (#236, #250).
• A timed-out wait now returns an ok: false envelope with error.code: "WAIT_TIMEOUT" while keeping .result.timedOut; fail-fast batch failures now emit an error envelope carrying the step's code, error.details.stepIndex, and the per-step result (exit codes unchanged) (#232).
• A render wait whose render polls all fail now exits with the renderer's RPC_ERROR/REPLAY_ERROR instead of masking the failure as WAIT_TIMEOUT (#301).
• wait rejects idle/screen-stable windows that cannot finish within the effective timeout with INVALID_DURATION before calling the host; batch applies the same screenStableMs rule (#277).
• CLI envelopes: unexpected errors become one INTERNAL_ERROR envelope on stdout under --json (exit 1) and the process exits once streams flush; empty or path-like session ids return INVALID_SESSION_ID (exit 2) instead of a stack trace; usage errors emit INVALID_INPUT envelopes; help/help <cmd> exit 0; config.json read/parse failures now map to STORAGE_READ_ERROR/INVALID_INPUT (#237, #287).
• CliError.details now travel across the session host RPC, so live snapshot/screenshot errors carry the same details as offline (#313).
• RPC response cap raised to 64 MiB (from 1 MiB); snapshot --include-cells now works on live ~500×200 sessions, with oversize success responses refused with PROTOCOL_ERROR (#320, #322).
• Startup warns on unsupported Node versions (checked against engines.node) and doctor uses the same range (#245).
• Per-session host socket moved under /tmp/agent-tty-<uid>/ with strict 0o700 ownership checks; inspect --json reports the new host.rpcSocketPath and a legacy-path fallback covers in-flight hosts from older versions (#288).
• snapshot and screenshot on a session that has printed nothing now succeed with capturedAtSeq: -1; record export accepts the same empty state for asciicast and WebM; --after-seq accepts -1 (#235, #270).
• record export --format webm now paces output on a recorded-time schedule, so continuous output no longer flushes all at once at the next non-output event (#285).
• Session-less PTYs (e.g. doctor's probe) no longer inherit AGENT_TTY_ACTIVE/AGENT_TTY_SESSION_ID from the caller (#178).
• Human-mode WAIT_TIMEOUT message names the effective timeout and, for the default, hints at --timeout <ms>/--timeout 0 (#273); batch wait-step timeout messages do the same (#301).

Fixed

• Close long-standing races between create, reconcile, and gc that could mark starting sessions failed or delete them mid-launch; the first manifest write always carries the host pid and uses one serial writer (#181).
• create that gives up on its host now stops that host (Linux/macOS) and carries details.sessionId on every post-launch error, so no orphan host keeps serving a failed session (#247, #294).
• destroy reliability across many scenarios: idle timeout, EPERM group kills, re-run in a new session when invoked inside the program's session (including bash jobs where AGENT_TTY_SESSION_ID is unset, Linux and BSD), unreadable /proc/self/stat, zombie programs, and proper SIGINT/SIGTERM forwarding to the re-run copy with 130/143 exit codes (#216, #221, #233, #246, #259, #260, #274, #275, #276, #281, #283, #284, #291, #303, #305, #312).
• destroy on the program group (SIGHUP then SIGKILL) so processes that ignore SIGHUP and background children actually stop (#201).
• writeManifest no longer recreates a gc-removed session folder, so terminal state stays terminal (#200); ensureArtifactsDir and gc's rm close the same gap for artifact writes (#212).
• Empty socket directory is removed once the last session ends, so Homes used as one-shots no longer accumulate folders under /tmp/agent-tty/ (#239).
• Artifact manifest is now protected by a cross-process lock around publish+append, so concurrent screenshot/snapshot/record export captures stop dropping entries, including from a dead breaker, stopped waiter, or on large artifacts/ folders; the publish step keeps earlier files on repeat captures and never replaces them (#191, #282, #299, #316, #318).
• --out hardening for screenshot and record export: refuse folders you cannot search (0200 parents), detect parent-folder swap between the preflight and the rename, undo a failed screenshot --out capture, and take the WebM's bytes from the temp file before rename (#279, #300, #321).
• screenshot --hide-cursor and the default now actually hide the block cursor in the PNG; the canvas is force-redrawn when cursor visibility toggles (#289).
• Mouse same-cell motion dedup now survives program output and renderer swaps (bumps @coder/libghostty-vt-node to 0.1.0-beta.7) (#234, #293).
• Waited run input is recorded in PTY order, not append-promise order (#234).
• allocateSession validates cwd, shell, and command segments before creating the session directory, so bad inputs no longer leak empty session folders (#188).
• Home registry keeps valid entries when one is invalid, so a single bad homes.json entry no longer wipes the others on the next create (#186).
• Bundle tools (validate-bundle, Hero Demo promote) reject canonical symlink escapes and leak-check before writing (#187).
• RPC request id capped at 128 chars, long error messages no longer split surrogate pairs, request/response size invariants documented, and oversize success responses refused with PROTOCOL_ERROR (#315, #319, #320, #322).
• Eval-home cleanup refuses to delete the temp root and schema parity is enforced (#190).

Breaking Changes

• A timed-out wait now returns ok: false (exit still 11). Automation that branched on .ok == true for a timed-out wait or a failed fail-fast batch must now read error.code/.result.timedOut (#232).
• wait without --timeout returns in 30 s instead of 600 s; batch wait steps now default to 30 s as well. Pass --timeout 0 for an unbounded wait (#236, #250).
• Render-wait failures no longer surface as WAIT_TIMEOUT; the renderer's own error (typically RPC_ERROR, exit 9) is returned instead (#301).
• Host RPC socket moved to /tmp/agent-tty-<uid>/<home>/<id>. An older CLI cannot reach a session started by this version; destroy running sessions before downgrading. A CLI running as a different uid (e.g. sudo agent-tty) cannot reach your sessions (#288).
• capturedAtSeq and --after-seq can now be -1 for sessions that have printed nothing; consumers that assumed >= 0 must accept -1 (#235, #270).
• screenshot --out and record export --out refuse paths inside the Home's sessions/ folder (previously record export accepted them) (#241).
• The default renderer profile hash changes because two Noto fallback fonts are now bundled; glyphs previously drawn by a host fallback font may come from Noto Sans Symbols 2 or Noto Sans Math (#278).

---

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