Add ptywright wait revisions and mode-aware special keys

[rgarcia]

Summary

ptywright waits could miss a PTY update that arrived between the snapshot check and once("update"). Each session now bumps a revision on I/O/exit/resize and rechecks before sleeping.

press() is still raw bytes (KeyArrowUp stays CSI A). New SpecialKey values plus pressKey() encode arrows/home/end/page/insert/delete/escape/backtab from Ghostty's live modes (setopt_from_terminal), so DECCKM application cursor keys produce SS3.

Test plan

• npx tsx --test packages/ptywright/src/test/*.test.ts
• in-memory DECCKM encode: CSI vs SS3
• real PTY: press(KeyArrowUp) still writes 1b5b41; pressKey(SpecialArrowUp) follows DECCKM

---

Note

Medium Risk
Touches native Ghostty key encoding and session wait timing used by CLI/TUI tests; behavior change is intentional but could affect flaky-test assumptions if callers relied on raw Key* for app-cursor modes.

Overview
PtySession wait helpers no longer miss updates that land between a snapshot check and subscribing to update: each session bumps a revision on PTY I/O, resize, exit, and close, and waitForUpdate rechecks before sleeping.

press() now accepts either raw Key* strings (unchanged pass-through) or new SpecialKey / Special* tokens. Special keys are encoded through Ghostty’s key encoder with setopt_from_terminal, so sequences follow live modes (e.g. DECCKM: SS3 vs CSI for arrows). The native bridge adds encodeSpecialKey, a per-terminal key encoder, and C API ptywright_ghostty_terminal_encode_special_key.

CI runs npm test --workspace @onkernel/ptywright; tests run via tsx --test src/test/*.test.ts with coverage for raw vs special arrow keys and DECCKM. README documents Special* vs Key*.

^{Reviewed by Cursor Bugbot for commit 0a267ac. Bugbot is set up for automated code reviews on this repo. Configure here.}

[rgarcia]

addressed the review:

• wait revision now rechecks after registering once("update"), so a PTY update between snapshot and sleep wakes the waiter
• dropped the silent CSI fallback; empty encode writes nothing
• pressKey and query replies share writeBytes()
• npm test --workspace @onkernel/ptywright runs via tsx and is wired into the cli-unit CI job

[rgarcia]

folded pressKey into press(string | SpecialKey). strings stay raw; SpecialArrowUp and friends encode from live modes.