punkshell/goals/G-076-tcl9-deadconsole-fix-adoption.md

G-076 Adopt upstream tcl9 dead-console fix: shared version gate for watchdog and help tcl warning

Status: active Scope: src/modules/punk/lib-999999.0a1.0.tm (punk::lib::check), src/modules/punk/repl-999999.0a1.0.tm (repl::start watchdog arming), src/modules/punk/AGENTS.md, src/tests/modules/punk/lib/testsuites/lib/checkbugs.test Goal: the tcl9 dead-console defect (upstream ticket f10d91c2d3, root-caused in G-039) is surfaced by 'help tcl' via a has_tclbug_* check, and that check and the repl dead-console watchdog arming share a single version gate, so that runtimes at or past the first released Tcl containing the verified upstream fix neither warn nor arm the watchdog, while all earlier Tcl 9 windows runtimes keep both. Acceptance: 'help tcl' on an affected runtime shows the warning with the f10d91c2d3 link and mitigation note; the applicability decision is a pure facts-in/verdict-out classifier proc with tests (libbug_udp_threadexit_applies precedent); repl::start arms the watchdog only when the same classifier reports the runtime affected, with live-console/piped/8.6 behaviour unchanged; the fixed-in constant is set only after the G-039 kill procedure, re-run on a released runtime containing the fix with the watchdog disabled, shows the repl exiting cleanly via the script-visible eof path - until then every Tcl 9 windows runtime is treated as affected.

Context

G-039 (achieved 2026-07-12, goals/archive/G-039-orphan-console-spin.md) root-caused an orphaned-shell CPU spin to a Tcl 9 core defect pair in win/tclWinConsole.c: (a) ConsoleEventProc drops the error/EOF notification for a dead console so the script-level fileevent never fires; (b) ConsoleReaderThread busy-loops on the persistent error. The script-level mitigation is repl::console_watchdog (punk::repl 0.5.0). The upstream ticket https://core.tcl-lang.org/tcl/tktview/f10d91c2d3 was filed 2026-07-12 and has since been updated upstream with a fix branch in the Tcl repository (observed 2026-07-13).

This goal tracks adoption of the eventual released fix: surfacing the defect through the existing 'help tcl' has_tclbug_* auto-discovery, and making the watchdog version-conditional so runtimes carrying the released fix don't warn and don't arm the probe.

Approach

• punk::lib::check gains a pure classifier tclbug_console_deadspin_applies {platform tclversion} (facts in, verdict out, testable - same pattern as libbug_udp_threadexit_applies from G-036, achieved - see goals/archive/G-036-tcl9-udp-console-worker-wedge.md) and a has_tclbug_console_deadspin wrapper returning the standard buginfo dict (bugref f10d91c2d3, level major, description noting punkshell's watchdog mitigation).
• Detection is version-based only: a behavioural probe is impossible (it would require killing a console). The classifier compares against a tclbug_console_deadspin_fixed_in namespace variable; empty means "no fixed release known" and every Tcl 9 windows runtime classifies as affected.
• repl::start's watchdog arming consults the same classifier as an additional AND-term, so setting the fixed-in constant once flips both the 'help tcl' warning and the watchdog together.
• Error direction is safe: a trunk/dev build carrying the fix under an old-looking patchlevel merely arms a harmless 5s read-only probe.
• The fixed-in flip is deliberately gated on verification, not on the upstream branch: G-039 found TWO defects, and the watchdog is only redundant if the notification defect (a) is fixed - i.e. the script actually sees EOF on console death. Before setting fixed_in, re-run the G-039 kill procedure (documented in the archived detail file) on the fixed released runtime with the watchdog disabled and confirm the repl exits via the normal fileevent/eof path. If upstream fixes only the spin, the watchdog stays necessary and the check's description changes instead.

Notes

• G-039 (archived) recorded the reproduction/kill procedure and the two-defect mechanism - see goals/archive/G-039-orphan-console-spin.md. Full ticket text with repro scripts: TEMP_REFERENCE/tcl9-dead-console-spin-TICKET-DRAFT.md.
• 8.6 remains out of scope (different console driver; per G-039 user decision 2026-07-12).

Progress

2026-07-13 classifier + help tcl surfacing + watchdog gating (initial increment)

Landed (punk::lib 0.4.2, punk::repl 0.5.1):

• punk::lib::check: tclbug_console_deadspin_applies {platform tclversion fixed_in} pure classifier + has_tclbug_console_deadspin wrapper (bugref f10d91c2d3, level major, description notes the punk::repl watchdog mitigation) + gate variable tclbug_console_deadspin_fixed_in (empty = all Tcl 9 windows affected).
• repl::start watchdog arming gained the [dict get [punk::lib::check::has_tclbug_console_deadspin] bug] AND-term; console_watchdog argdoc and src/modules/punk/AGENTS.md note updated.
• Tests: checkbugs.test +2 (classifier truth table incl. fixed_in comparisons; live-check/classifier consistency + bugref).

Verification (2026-07-13, native tclsh 9.0.3 runtests + punk902z kit 9.0.2 in src mode):

• lib checkbugs.test 5/5 pass; repl consolebackends.test 3/3 pass; make.tcl modules builds clean.
• Live check on tclsh 9.0.3: bug=1; setting fixed_in to the running version flips bug=0.
• 'help tcl' | punk902z src (piped, PUNK_PIPE_EOF=exit): major warning displayed with description, mitigation note and f10d91c2d3 hyperlink.

2026-07-13 mitigated/mitigation buginfo axis (punk::lib 0.4.3, punk 0.2.6)

• buginfo dicts gain an optional axis orthogonal to level: mitigated boolean + mitigation text. 'help tcl' renders a triggered mitigated check as "warning level: (mitigated)" in subdued grey (term-grey foreground) instead of the level colour, with an indented "mitigated: " block; unmitigated warnings render unchanged.
• has_tclbug_console_deadspin populates it: mitigated when punk::repl >= 0.5.0 is available to the runtime (version discovery without loading, udp-check precedent), mitigation text noting the watchdog scope (non-repl console reads remain exposed). Severity stays major.
• checkbugs.test extended (axis key presence/boolean/consistency rules incl. the generic every-check sweep); 5/5 pass under native tclsh 9.0.3. Piped 'help tcl' | punk902z src verified: grey (38;5;8 fg) mitigated rendering with mitigation block and ticket hyperlink.

Remaining for acceptance:

• When a released Tcl contains the merged upstream fix: re-run the G-039 kill procedure on that runtime with the watchdog disabled, confirm clean script-visible eof exit, then set punk::lib::check::tclbug_console_deadspin_fixed_in to that version (one edit flips both consumers) and update the AGENTS.md note.