# G-061 Pseudoconsole expect-alternative for interactive shell testing (ConPTY + unix pty) Status: proposed Scope: test-harness support (location TBD during the work: src/tests/testsupport/ and/or a small punk module), src/tests/shell/ (capability-gated interactive suites), goals/G-061-pseudoconsole-expect.md Goal: interactive punkshell behaviour is testable headlessly and byte-accurately by driving a real shell under a pseudoconsole - ConPTY on windows, pty on unix - through an expect-like harness (spawn, send literal keys and control/arrow sequences, await patterns in the rendered ANSI byte stream with timeouts, collect transcript), giving the goals/G-044-detail preserve-list behaviours (continuation hints, raw-mode colour staging, tab markers and space dots, multiline history navigation) their durable cross-platform verification tier - complementary to G-020 capture testing (which verifies what reaches the screen; this verifies the byte stream) and to the G-001 console-seam unit tier. Acceptance: a capability-gated harness spawns a built punkshell under ConPTY on windows (and under a unix pty when run on unix or via the G-059 WSL staging pattern), sends keys including control/arrow sequences, and awaits expected patterns with timeouts and forced teardown on expiry (hang-proof per the shell-test conventions); at least three preserve-list behaviours are verified through it (e.g the in-proc `set x "{*}{"` continuation-hint sequence, raw-mode tab-marker rendering and deletion, up-arrow recall and edit of a multiline history entry); tests skip cleanly where no pseudoconsole is available; the harness API is platform-agnostic with per-OS backends; candidate synchronisation/communication mechanisms between harness and shell (including the inter-subshell beep-protocol idea) are evaluated and the chosen approach documented in the detail file. ## Context punkshell's interactive behaviour has no automated verification. The preserve-list recorded in goals/G-044-repl-command-completion.md (2026-07-11, user-specified) covers what any repl refactor must not break: info-complete-parity continuation with the Tcl quoting quirk, closing-prompt hints, raw-mode colour staging (in-progress vs submitted), literal tab acceptance with raw-mode tab markers and edit smarts, dim grey space dots (display-only - never in the submitted string), and up/down navigation + editing of multiline editbuf history entries. The verification tier model established 2026-07-11: 1. PURE layer - testable now: punk::lib::system::incomplete characterized in src/tests/modules/punk/lib/testsuites/lib/commandcomplete.test. 2. Console-seam UNIT tier - blocked on a seam: class_editbuf is console-coupled at its core (add_chunk renders via overtype::renderline against live terminal metrics - cursor-position size probing, DECRQPSR tabstops). An ::opunk::Console test double ([[G-001]]) or injectable metrics is the enabling refactor. 3. RENDERED tier: [[G-020]] screencap+input injection is the near-term windows-only bridge (verifies what reaches the screen); THIS goal is the durable, headless, cross-platform, byte-accurate mechanism (verifies the byte stream the shell emits). ## Approach ### Harness contract (platform-agnostic; per-OS backends) expect-like primitives over a REAL pseudo-terminal: - spawn: launch a built punkshell attached to a pseudoconsole (ConPTY on windows, openpty/forkpty on unix) with controlled size (cols x rows) - size control matters because raw-mode rendering is width-dependent. - send: literal keys plus control/arrow/escape sequences (up-arrow history recall, backspace over a tab marker, etc). - expect: await patterns in the rendered ANSI byte stream with timeouts; forced teardown on expiry (hang-proof, per src/tests/shell/AGENTS.md conventions - the punk_run pattern generalized to a live conversation). - transcript: full byte capture for post-hoc assertions (colour staging = SGR sequences around the in-progress vs submitted line; tab markers/space dots = the substituted glyph bytes). ### Open implementation questions (deliberately left to the work) - Driving ConPTY from Tcl: candidates include a twapi surface (if CreatePseudoConsole is reachable), a small helper executable owning the ConPTY pair and relaying bytes over stdio/sockets, or an existing tool at arm's length. The unix side is simpler (openpty via a small C/critcl shim, or driving through an existing pty-capable tool). - Synchronisation between harness and shell: pattern-awaiting alone can be racy for timing-sensitive raw-mode behaviour. Candidate: the inter-subshell communication / beep-protocol idea (user, 2026-07-11) - an in-band signalling channel the shell can emit for the harness to key off. Evaluate against simpler prompt-sentinel approaches; document the choice here. - Unix execution from the windows dev machine: the [[G-059]] WSL staging pattern (native-filesystem staging, capability constraint) extends naturally - a pty harness run inside the distro against a linux punkbin runtime/kit. ### Sequencing - [[G-001]] console-seam unit tier and [[G-020]] capture tier are complementary, not prerequisites - but preserve-list items verified at a cheaper tier need not be re-verified here beyond smoke coverage. - First verification targets (per acceptance): the in-proc `set x "{*}{"` continuation-hint sequence, raw-mode tab-marker rendering + deletion, up-arrow recall and edit of a multiline history entry. ## Notes - Related: [[G-044]] (completion/hinting - consumes this for its own verification), [[G-001]] (fake-console unit tier), [[G-020]] (screen-capture tier), [[G-059]] (WSL execution pattern), [[G-060]] (guest-driving contract - a pty harness inside a QEMU guest is the eventual cross-platform matrix combination). - ConPTY availability gates the windows side to Win10 1809+ (fine for punkshell's supported baseline); the capability probe should verify actual ConPTY function, not windows version. - Archived-goal references in this file: G-001 achieved 2026-07-11 (goals/archive/G-001-pluggable-console-backends.md);G-059 achieved 2026-07-11 (goals/archive/G-059-wsl-test-driving.md).