punkshell/goals/G-038-piped-error-retention.md

G-038 Piped-phase errors inspectable in the restarted interactive shell

Status: proposed Scope: src/lib/app-punkshell/punkshell.tcl (eof-restart handover), src/modules/punk/repl-999999.0a1.0.tm (error capture at the reporting site and/or teardown), src/modules/punk/repl/codethread-999999.0a1.0.tm (as needed for code-interp access) Acceptance: 'puts test;error xxxx' | <punkexe> shell then, at the first interactive prompt, a documented command or variable yields the xxxx message, its errorInfo traceback and errorCode from the piped phase, and the first prompt is preceded by a one-line notice that a piped-phase error was retained; the retained record survives boot-time caught-error noise (proven against the motivating transcript, where plain set errorInfo showed virtchannel's can't unset "timer" instead); an error-free piped phase produces no notice and an explicitly-empty record; plain ::errorInfo semantics are otherwise unchanged; verified on both Tcl generations.

Context

Motivating transcript (user, 2026-07-08): 'puts test;error xxxx' | punk902z shell - the piped phase prints test then the xxxx error, EOF triggers app-punkshell's CONIN$ restart, and at the interactive prompt set errorInfo shows an unrelated can't unset "timer": no such variable ... "unset timer" instead of the xxxx traceback. The user had hoped the piped error would be retained for interactive inspection.

Two mechanisms defeat the natural expectation:

1. Restart boundary: the restarted shell is a fresh repl::init/repl::start with a new codethread and code interp (app-punkshell do_shell). The piped phase's ::errorInfo lives in run-1's code interp, which is torn down with its codethread. Nothing carries it across.
2. ::errorInfo is boot-noise-prone anyway: a caught error still stamps ::errorInfo. tcllib's virtchannel_core/events.tcl (tcl::chan::events) runs catch { unset timer } as ordinary control flow, and the repl-exec log tee construction (fifo2 stacks during repl::init) triggers it in the fresh code interp - so a brand-new shell's resident ::errorInfo is whatever internal caught error happened last during boot. Restoring the retained error into plain ::errorInfo would be clobbered by the same noise, hence the punk-owned record in the goal statement (or injection strictly after boot completes - but a dedicated record is robust and self-describing).

Approach (design points)

• Capture at the reporting site, not by scraping ::errorInfo at teardown: the repl already distinguishes command errors when it renders the tcl-err (lowercase p%) prompt path - that is the natural place to record {message errorInfo errorCode command-string timestamp} for the most recent errored command. Teardown-time capture of the code interp's ::errorInfo is the fallback but inherits the noise problem above.
• Handover: the record must cross thread/interp teardown - candidates: tsv (already used by the repl for runchunks), or app-punkshell capturing it from the run-1 exitinfo/donevalue plumbing and seeding the run-2 code interp after init.
• Surface: a documented variable in the code interp (e.g. ::punk::last_pipeline_error) or a small command; the first-prompt notice should be one line and only appear when a retained error exists (piped runs that end cleanly stay quiet - agents/CI pipe scripts constantly).
• Scope question to settle: retain only across the piped->interactive restart, or also expose "last error of the previous run" generally (subshell exits, repl::start restarts)? The goal commits only to the piped->interactive case; wider retention can be recorded here if it falls out naturally.
• Note the errorInfo-noise observation stands alone too: even without retention, set errorInfo in a fresh punk shell reports internals' caught errors. Out of scope to "fix" tcllib, but the dedicated-record design sidesteps it and the doc/help for the new record can mention the caveat.

Notes

• Related: G-036 detail (same eof-restart machinery, where the codethread/interp lifecycle is mapped); G-015 (script subcommand is the agent-facing piped path and already reports errors on stderr with honest exit codes - this goal is about the shell subcommand's interactive restart, a human-facing convenience).