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

Added

• agent-tty mouse command and batch step for native mouse input (left/middle/right press, release, motion, wheel) with modifier/held-button state, encoded in the child program's negotiated tracking mode. New mouse-input capability and CAPABILITY_UNAVAILABLE error (exit 12) when the libghostty-vt native encoder is unavailable. Pins @coder/libghostty-vt-node to 0.1.0-beta.7 (#179, follow-ups #234, #293).
• record export --format svg [--animate] writes a browserless, deterministic, byte-stable SVG of a session replay (SMIL discrete animation for --animate). JetBrains Mono is always embedded; Noto Sans Symbols 2 / Math subsets are embedded on demand (#171, #349).
• record diff <session-id-a> <session-id-b> replays both sessions offline from their event logs and emits a unified LCS line diff of the canonical visible screen, with --at-seq-a/--at-seq-b for self-diffs against earlier state (#170).
• wait --scope cursor-line matches --text/--regex only against the row the cursor is on, so prompt waits (--regex 'READY> $' --scope cursor-line) no longer false-match the echoed command line. Also available on batch wait steps and the waitForRender RPC (#169).
• screenshot --out <path> writes the PNG to a chosen path (mirroring record export --out), with creation of missing parent folders for both commands. Paths inside <home>/sessions/ are refused (#241, #279, #290).
• screenshot --json reports glyphs drawn as .notdef boxes in missingGlyphs with their cells (missingGlyphsTruncated when capped). record export --format webm --json reports missingGlyphs across painted frames. Judges per font face, so host-covered glyphs are not listed (#240, #278).
• Spawned PTYs now set AGENT_TTY_ACTIVE=true and AGENT_TTY_SESSION_ID=<id> so shells, prompts, and wrappers inside a managed session can detect and identify themselves (#166, #178).
• PTYs now default COLORTERM=truecolor, and the terminal query responder answers XTGETTCAP (Tc, RGB, setrgbf, setrgbb) and declines DECRQSS SGR, so programs started under env -i (e.g. Neovim) enable termguicolors (#231, #271).

Changed

• Build: migrated from aube to pnpm@10.34.5 (pnpm-lock.yaml replaces aube-lock.yaml, mise/CI/docs updated, Dependabot added for npm + actions) (#176).
• Breaking (wait): a standalone wait without --timeout now times out after 30 s instead of 600 s, matching run --timeout. The help text names the default; --timeout 0 still waits forever (#236). Batch wait steps also default to 30 s (#250).
• Breaking (wait envelope): a timed-out wait now emits ok: false with error.code: "WAIT_TIMEOUT", while still carrying the existing result.timedOut / matched / capturedAtSeq. Fail-fast batches that fail on a step emit an error envelope too, with the per-step result attached. Exit code (11 / step-specific) unchanged (#232).
• Breaking (wait renderer failures): when every render poll fails, wait now rejects with the renderer's own error (typically RPC_ERROR / REPLAY_ERROR, exit 9/10) instead of reporting WAIT_TIMEOUT. WAIT_TIMEOUT now means the timeout elapsed (#301).
• wait now rejects --idle-ms / --screen-stable-ms windows that cannot finish within the effective timeout, with exit 2 INVALID_DURATION, before contacting the host (#277).
• The RPC response cap is raised to 64 MiB so snapshot --include-cells works on large live sessions; an oversized success is refused with PROTOCOL_ERROR (not retryable). The snapshot-with-cells RPC timeout is raised to 60 s (#320, #322).
• The CLI now warns on startup when the running Node is outside engines.node (>=24.0.0 <27), and doctor enforces the same range instead of a hard-coded 24+ (#245).
• snapshot, screenshot, and record export now succeed on an empty event log, returning capturedAtSeq: -1. record diff --at-seq-a/-b -1 accepts the empty-log seq. An empty-log WebM/asciicast is a blank video / header-only cast (#235, #270, #300).
• record export --format webm paces output at the recorded time instead of flushing in bursts when a non-output event follows (#285).
• Per-session RPC sockets live under a per-uid root (/tmp/agent-tty-<uid>), and a dead host's socket is removed (#288, #239).
• destroy typed into or run inside its own session re-runs as a detached copy in a new session; SIGINT/SIGTERM to the original now forward to the copy (128+signum exit) (#216, #281).
• destroy --force of a session whose host is gone now succeeds when the program group cannot be read (EACCES, EPERM, EIO, EISDIR, ENOTDIR, ELOOP, ENAMETOOLONG); gc keeps such sessions and names destroy --force as the way out (#327).
• gc now keeps an exited session while its program group still has live processes (reports the session's program group still runs (destroy ends it) in skippedSessions[].reason) (#302).
• --out writes now re-check the parent folder (device + inode) immediately before rename and refuse a parent that can be written but not searched (chmod 0200) (#279).
• Event log is capped at 50 MB / 250,000 entries; on reach, one marker records the limit (agent-tty: event log limit reached (… bytes|events); later events are not recorded), the program keeps running, and reader commands name the cap in their error details (#340).

Fixed

• Session lifecycle: large-scale hardening of create, reconcile, destroy, and gc closing races between concurrent agents sharing a Home, including host-pid-first manifest writes, serialized session.json writes, destroy marker overrides, group-freeze probes for fork chains, cross-time-namespace host records, surviving unreadable /proc/self/stat, and socket-directory cleanup. Lifecycle TLA+ model runs now gate CI (#181, #188, #194, #201, #210, #212, #216, #221, #233, #246, #256, #259, #260, #274, #275, #276, #283, #284, #288, #291, #302, #303, #305, #312, #324, #326, #330, #331, #333, #334).
• create cleanup: when create gives up on its host readiness loop, it now stops the host (SIGTERM) and every create error after session allocation includes error.details.sessionId (#247, #294, #312, #324).
• Artifacts: concurrent captures no longer drop manifest entries — <sessionDir>/artifacts/manifest.json.lock serializes publishes across processes with stale-owner judgement (#282). Repeat captures keep earlier artifact files (#191). Later writes replacing an export's file keep the right manifest entry via file-identity checks (#300, #316, #321).
• Screenshot cursor: --hide-cursor / --show-cursor now actually toggle the canvas cursor; previously every screenshot drew a block cursor regardless of the setting (#289).
• Mouse motion: same-cell mouse move is deduplicated (reported: false) across program output and renderer swaps (#234, #293).
• CLI errors under --json: unexpected errors and Commander usage errors now emit exactly one INTERNAL_ERROR / INVALID_INPUT envelope on stdout; empty/invalid session IDs return INVALID_SESSION_ID instead of an assertion stack; the process exits promptly after INTERNAL_ERROR (#237, #287).
• Human-mode WAIT_TIMEOUT names the effective timeout (e.g. Wait timed out after 30000 ms (the default; pass --timeout <ms>, or --timeout 0 to wait without a limit).) (#273). Batch wait-timeout messages name their own ms (#301).
• RPC: CliError details now cross the session-host RPC (e.g. details.errno, details.path); error messages are safely truncated at 65,536 chars without splitting surrogate pairs; request id is capped at 128 chars; a build/send failure in the host response path no longer crashes the host (#313, #315, #319).
• record export --format webm --out computes its SHA-256 and byte count from the temp file before rename, so a concurrent replacement cannot lend its bytes to the manifest entry (#321).
• Waited run logs its input_run event in PTY order (no interleaving with concurrent type/paste/send-keys) (#234).
• Storage read under a symlinked Home now resolves consistently before and after the Home exists (#210); writeManifest cannot recreate a removed session folder (#200, #212); one invalid homes.json entry no longer wipes the registry (#186); tool paths are leak-checked for canonical symlink escapes before writing hero-demo bundles (#187).
• npm run clean now removes the TS build-info files so a fresh build emits dist/cli/main.js (#348).

Breaking Changes

• wait default timeout drops from 600 s to 30 s; a timed-out wait returns ok: false with error.code: "WAIT_TIMEOUT" and carries result.timedOut on the error envelope. Fail-fast batch step failures now also use ok: false envelopes. Scripts branching on .ok of a wait or fail-fast batch must be updated (#236, #232, #250).
• A render wait whose polls all fail now exits with the renderer's own code (typically RPC_ERROR/REPLAY_ERROR, exit 9/10) instead of WAIT_TIMEOUT (exit 11) (#301).
• capturedAtSeq can now be -1 (empty event log). Consumers that required >= 0 must accept -1 (#235, #270).
• record export --out inside <home>/sessions/ is now refused (exit 7 EXPORT_ERROR); previously it was accepted (#241).
• The bundled render-profile hash changes because two Noto symbol-font subsets join the font stack; byte-identical screenshots remain for host-covered glyphs (#278).
• PROMPT_EOL_MARK / COLORTERM defaults are applied at PTY spawn; an inherited COLORTERM from the outer shell no longer reaches the session. Opt out per session with --env COLORTERM=<other> or --env COLORTERM= (#231).
• The optional native dependency bumps from @coder/libghostty-vt-node@0.1.0-beta.0 to 0.1.0-beta.7; the linux-x64 prebuild still requires AVX2 (#179, #293).
• Dropped aube: contributor tooling is now pnpm@10.34.5 via mise. No runtime impact on the published npm package (#176).

New Contributors

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

---

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