probe-byte store unification + first-use settling for all query paths

opunk::console (0.2.0):
- probe-byte waiting store changed from dict to array (::opunk::console::waiting_chunks) and made
  pluggable via waiting_chunks_arrayvar: integrating layers redirect it to their established
  cooperative store so bytes consumed by opunk::Console probe reads stay visible to active readers.
  The class remains free of punk::console dependencies - redirection is the integrator's act.

punk::console (0.1.6):
- default_console redirects the opunk::console store to punk::console::input_chunks_waiting
  (closing the split-store hazard that previously made opunk-level probes invisible to the
  punk repl reader)
- get_ansi_response_payload performs first-use active settling for persistable console specs,
  guarded by a recursion latch around settle_can_respond's own probe: every query path
  (get_cursor_pos, get_device_status, ...) now pays at most one settling probe instead of a
  fresh timeout per call on unsettled ambiguous consoles

punk::repl (0.1.6):
- repl::init routes default console construction through punk::console::default_console
  (deduplicates creation logic and gains the store unification)

tests: store-unification and get_cursor_pos first-use settling cases in consolespec.test
(zero-emission and persistence asserts); consoleclass.test store assertions converted to array
form. Console suites 25/25 + 9/9; punkexe 6/6, goals 8/8; full suite green except pre-existing
exec-14.3.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

src/bootsupport/modules/opunk/console-0.2.0.tm

@@ -0,0 +1,372 @@
+# -*- tcl -*-
+# Maintenance Instruction: leave the 999999.xxx.x as is and use punkshell 'dev make' or bin/punkmake  to update from <pkg>-buildversion.txt
+# module template: shellspy/src/decktemplates/vendor/punk/modules/template_module-0.0.4.tm
+#
+# Please consider using a BSD or MIT style license for greatest compatibility with the Tcl ecosystem.
+# Code using preferred Tcl licenses can be eligible for inclusion in Tcllib, Tklib and the punk package repository.
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# (C) 2026
+#
+# @@ Meta Begin
+# Application opunk::console 0.2.0
+# Meta platform     tcl
+# Meta license      BSD
+# @@ Meta End
+
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+##  Requirements
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+
+package require Tcl 8.6-
+
+package require voo
+package require punk::args
+
+#opunk::Console - a voo (value-based) representation of a console: an in/out channel pair claimed to
+#belong to one responding endpoint, together with settled capability facts about that endpoint.
+#
+#Motivation (see punk::console get_size / get_ansi_response_payload history):
+#ANSI query mechanisms assume the input channel receives what the output channel's device emits in
+#response. When stdio is redirected that pairing silently breaks - queries go to a terminal whose
+#replies land in some other process's input. A console object makes the pairing an explicit,
+#construction-time property instead of a per-query-site guess.
+#
+#Design notes:
+# - Objects are voo values (plain lists). Consoles are entities, not values - so canonical instances
+#   are anchored at well-known namespace variables (::opunk::console::instances::<name>) and the value
+#   semantics serve as cheap snapshots. Mutation (settling capabilities) goes through the anchor via
+#   the lowercase ::opunk::console wrapper procs.
+# - The class is -virtual: slot 0 of each value carries the concrete class namespace, so channel
+#   environments that respond like terminals but aren't platform consoles can subclass
+#   (-extends ::opunk::Console) and override the capability/size methods, with existing holders of
+#   console values dispatching correctly.
+# - This first cut is standalone and passive: capability detection is heuristic (channel options,
+#   probed eof, terminal env hints) and size uses chan -winsize else the default size. Active ANSI
+#   query probing arrives with punk::console integration (which will delegate here rather than the
+#   class depending on punk::console).
+
+tcl::namespace::eval ::opunk::console {
+    variable PUNKARGS
+
+    #well-known cooperative store for bytes consumed by probe reads on pipe-like channels:
+    #an array keyed by channel name -> list of chunks. Readers taking over a channel should consume
+    #and clear any entry for that channel first.
+    #The store is PLUGGABLE via waiting_chunks_arrayvar: environments with an established cooperative
+    #store (e.g punk::console::input_chunks_waiting, which the punk repl reader consults) redirect it
+    #so probe-consumed bytes are never invisible to the active reader. The class itself stays free of
+    #any punk::console dependency - redirection is performed by the integrating layer.
+    variable waiting_chunks
+    if {![array exists waiting_chunks]} {
+        array set waiting_chunks {}
+    }
+    variable waiting_chunks_arrayvar
+    if {![info exists waiting_chunks_arrayvar]} {
+        set waiting_chunks_arrayvar ::opunk::console::waiting_chunks
+    }
+}
+
+voo::class ::opunk::Console -virtual {
+    private {
+        #o_ prefix per opunk voo convention (distinguishes fields from locals in -update methods,
+        #and matches tclOO-style implementations elsewhere for easier code movement).
+        #Note the class is -virtual: slot 0 of the object value is the concrete class namespace tag.
+        string_t    o_in                stdin
+        string_t    o_out               stdout
+        string_t    o_terminal_class    "" ;#e.g windows-console, tty, pipe - "" until classified
+        list_t      o_size_mechanism    [list] ;#preferred size mechanism try-order - empty until timed/settled
+        dict_t      o_default_size      [dict create columns 80 rows 24]
+    }
+    public {
+        #settled response capability: -1 unknown, 0 cannot respond, 1 can respond.
+        #public accessors (get.o_can_respond / set.o_can_respond) so the anchored-mutation wrappers in
+        #::opunk::console can settle it without reaching into private my.* accessors.
+        int_t       o_can_respond       -1
+
+        method in {} {
+            my.get.o_in $this
+        }
+        method out {} {
+            my.get.o_out $this
+        }
+        method channels {} {
+            list [my.get.o_in $this] [my.get.o_out $this]
+        }
+        method terminal_class {} {
+            my.get.o_terminal_class $this
+        }
+        method default_size {} {
+            my.get.o_default_size $this
+        }
+
+        #Certainty test: is the input channel closed or at eof (and so can never deliver a response)?
+        #A consumed/half-closed pipe may not flag eof until a read is attempted, so pipe-like channels
+        #get a non-blocking 1-byte probe. A probed byte is preserved in the cooperative waiting store
+        #(array named by ::opunk::console::waiting_chunks_arrayvar - redirectable by the integrating
+        #layer to e.g punk::console::input_chunks_waiting so active readers can find it).
+        #Console/tty channels are never probed (must not consume a keystroke).
+        method at_eof {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set in [my.get.o_in $this]
+            if {[catch {chan eof $in} is_eof]} {
+                return 1 ;#closed/invalid channel - unusable
+            }
+            if {$is_eof} {
+                return 1
+            }
+            if {[catch {chan configure $in} conf]} {
+                return 1
+            }
+            if {[dict exists $conf -inputmode] || [dict exists $conf -mode]} {
+                return 0
+            }
+            if {[catch {
+                set prior_blocking [dict get $conf -blocking]
+                chan configure $in -blocking 0
+                set probe [read $in 1]
+                chan configure $in -blocking $prior_blocking
+            }]} {
+                return 1
+            }
+            if {$probe ne ""} {
+                upvar #0 $::opunk::console::waiting_chunks_arrayvar wchunks
+                lappend wchunks($in) $probe
+            }
+            return [chan eof $in]
+        }
+
+        #Heuristic: could the input channel be connected to a terminal able to answer queries?
+        #Returns 0 only when reasonably confident it cannot. mintty without winpty presents a
+        #terminal's stdin as a plain pipe, so env hints (MSYSTEM, TERM_PROGRAM) prevent false
+        #negatives there at the cost of false positives for genuinely piped-but-open input.
+        method is_console_or_tty {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set in [my.get.o_in $this]
+            if {[catch {chan configure $in} conf]} {
+                return 0
+            }
+            if {[dict exists $conf -inputmode]} {
+                return 1
+            }
+            if {[dict exists $conf -mode]} {
+                return 1
+            }
+            if {[at_eof $this]} {
+                return 0
+            }
+            if {[info exists ::env(TERM_PROGRAM)] || [info exists ::env(MSYSTEM)]} {
+                return 1
+            }
+            return 0
+        }
+
+        #Response capability: settled value if known, else computed heuristically (without settling -
+        #this method is pure; use ::opunk::console::can_respond <name> to settle an anchored instance
+        #heuristically, or punk::console::settle_can_respond <spec> for active-probe settling - the
+        #probe machinery lives in punk::console so this class stays free of that dependency).
+        method can_respond {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set settled [get.o_can_respond $this]
+            if {$settled != -1} {
+                return $settled
+            }
+            return [is_console_or_tty $this]
+        }
+
+        #Size of the console: chan -winsize on the output channel when available (fast, no query),
+        #else the configured default size. ANSI cursor-report mechanisms are deliberately absent from
+        #this standalone class - they arrive via punk::console integration and subclasses.
+        method size {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set out [my.get.o_out $this]
+            if {![catch {chan configure $out} oconf]} {
+                if {[dict exists $oconf -winsize]} {
+                    lassign [dict get $oconf -winsize] cols lines
+                    if {[string is integer -strict $cols] && [string is integer -strict $lines]} {
+                        return [dict create columns $cols rows $lines]
+                    }
+                }
+            }
+            return [my.get.o_default_size $this]
+        }
+    }
+
+    constructor {in out} {
+        #new() supplies the class defaults including the virtual class tag at slot 0
+        set obj [new()]
+        my.set.o_in  obj $in
+        my.set.o_out obj $out
+        return $obj
+    }
+}
+
+#make introspection (with i and punk::ns::cmdinfo) easier by making the class namespace an ensemble - we can still access it as ::opunk::Console
+namespace eval ::opunk::Console {
+    namespace ensemble create
+}
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# Anchored instances - the 'consoles are entities' layer
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+tcl::namespace::eval ::opunk::console {
+    tcl::namespace::export {[a-z]*}  ;# Convention: export all lowercase
+
+    namespace eval instances {
+        #one variable per anchored console instance - the canonical location of each console object.
+        #Access via the sibling procs; methods needing to mutate an instance go through these anchors.
+    }
+
+    proc create {name in out} {
+        if {![string is wordchar -strict $name]} {
+            error "opunk::console::create name must be alphanumeric/underscore, got '$name'"
+        }
+        set [namespace current]::instances::$name [::opunk::Console::new $in $out]
+        return [namespace current]::instances::$name
+    }
+    proc instancevar {name} {
+        set v [namespace current]::instances::$name
+        if {![info exists $v]} {
+            error "opunk::console: no anchored console instance named '$name' (known: [names])"
+        }
+        return $v
+    }
+    proc instance {name} {
+        set [instancevar $name]
+    }
+    proc names {} {
+        set result [list]
+        foreach v [info vars [namespace current]::instances::*] {
+            lappend result [namespace tail $v]
+        }
+        return $result
+    }
+    proc forget {name} {
+        unset [instancevar $name]
+        return
+    }
+
+    #settle-and-cache response capability on the anchored instance.
+    #The class method is pure (value-in) - this wrapper owns the mutation via the anchor.
+    proc can_respond {name} {
+        upvar #0 [instancevar $name] obj
+        set settled [::opunk::Console::get.o_can_respond $obj]
+        if {$settled != -1} {
+            return $settled
+        }
+        set r [::opunk::Console::can_respond $obj]
+        ::opunk::Console::set.o_can_respond obj $r
+        return $r
+    }
+    proc size {name} {
+        ::opunk::Console::size [instance $name]
+    }
+}
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+
+
+# == === === === === === === === === === === === === === ===
+# Sample 'about' function with punk::args documentation
+# == === === === === === === === === === === === === === ===
+tcl::namespace::eval ::opunk::console {
+    variable PUNKARGS
+    variable PUNKARGS_aliases
+
+    lappend PUNKARGS [list {
+            @id     -id "(package)opunk::console"
+            @package    -name "opunk::console" -help\
+            "voo class ::opunk::Console representing a console as an in/out channel pair with settled
+            response-capability facts, plus anchored canonical instances under ::opunk::console::instances."
+        }]
+
+    namespace eval argdoc {
+        proc package_name {} {
+            return opunk::console
+        }
+        proc about_topics {} {
+            set topic_funs [info commands [namespace current]::get_topic_*]
+            set about_topics [list]
+            foreach f $topic_funs {
+                set tail [namespace tail $f]
+                lappend about_topics [string range $tail [string length get_topic_] end]
+            }
+            return [lsort $about_topics]
+        }
+        proc default_topics {} {return [list Description *]}
+
+        proc get_topic_Description {} {
+             punk::args::lib::tstr [string trim {
+                package opunk::console
+                voo class for consoles as channel-pair objects with anchored canonical instances.
+            } \n]
+        }
+        proc get_topic_License {} {
+            return "BSD"
+        }
+        proc get_topic_Version {} {
+            return "$::opunk::console::version"
+        }
+        proc get_topic_Contributors {} {
+            set authors {{"Julian Noble" "julian@precisium.com.au"}}
+            set contributors ""
+            foreach a $authors {
+                append contributors $a \n
+            }
+            if {[string index $contributors end] eq "\n"} {
+                set contributors [string range $contributors 0 end-1]
+            }
+            return $contributors
+        }
+        proc get_topic_classes {} {
+            punk::args::lib::tstr -return string {
+                opunk::Console "virtual class for consoles as in/out channel pairs"
+            }
+        }
+    }
+
+    set overrides [dict create]
+    dict set overrides @id  -id   "::opunk::console::about"
+    dict set overrides @cmd -name "opunk::console::about"
+    dict set overrides @cmd -help [string trim [punk::args::lib::tstr {
+                            About opunk::console
+                            }] \n]
+    dict set overrides topic -choices           [list {*}[opunk::console::argdoc::about_topics] *]
+    dict set overrides topic -choicerestricted  1
+    dict set overrides topic -default [opunk::console::argdoc::default_topics]
+    set newdef [punk::args::resolved_def -antiglobs -package_about_namespace -override $overrides ::punk::args::package::standard_about *]
+    lappend PUNKARGS [list $newdef]
+    proc about {args} {
+        package require punk::args
+        set argd [punk::args::parse $args withid ::opunk::console::about]
+        lassign [dict values $argd] _leaders opts values _received
+        punk::args::package::standard_about -package_about_namespace ::opunk::console::argdoc {*}$opts {*}[dict get $values topic]
+    }
+}
+# end of sample 'about' function
+# == === === === === === === === === === === === === === ===
+
+
+# -----------------------------------------------------------------------------
+#    register namespace(s) to have PUNKARGS,PUNKARGS_aliases variables checked
+# -----------------------------------------------------------------------------
+namespace eval ::punk::args::register {
+    #use fully qualified so 8.6 doesn't find existing var in global namespace
+    lappend ::punk::args::register::NAMESPACES ::opunk::console ::opunk::Console
+}
+# -----------------------------------------------------------------------------
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+##  Ready
+package provide opunk::console [tcl::namespace::eval ::opunk::console {
+    variable pkg opunk::console
+    variable version
+    set version 0.2.0
+}]
+return

src/modules/opunk/AGENTS.md

@@ -16,6 +16,7 @@ Modules under the `opunk::*` namespace explore value-based class implementations
 - voo makes each field name a class-namespace variable holding the field's list index — avoid `variable o_<field>` in method bodies.
 - Classes intended for behavioral subclassing are declared `-virtual` (slot 0 of each value is the concrete class namespace tag); behaviour-differentiating methods are declared `-virtual` so calls through the base class dispatch on the tag.
 - Entity-like objects (e.g. consoles) anchor canonical instances at well-known namespace variables (`::opunk::console::instances::<name>`) with lowercase wrapper procs owning mutation; the value semantics serve as snapshots/copies where cheap.
+- Cooperative shared state is pluggable rather than hardwired: the probe-byte waiting store is the array named by `::opunk::console::waiting_chunks_arrayvar` (default `::opunk::console::waiting_chunks`); integrating layers redirect it to their established store (punk::console::default_console points it at `punk::console::input_chunks_waiting`) so probe-consumed bytes stay visible to active readers.
 - Method-entry validity guards use `[llength $this] < N` (not `!= N`) so field-adding subclasses keep working.
 - Module filenames use the `-999999.0a1.0.tm` magic suffix with `<modulename>-buildversion.txt` per parent conventions.
 - `opunk::console` (with its dependency `voo`) is included in bootsupport via `src/bootsupport/modules/include_modules.config` for eventual boot/repl-startup console objects; after releasing a new version, rebuild with `make.tcl modules` then refresh the snapshot with `make.tcl bootsupport`.

src/modules/opunk/console-999999.0a1.0.tm

@@ -49,12 +49,20 @@ package require punk::args
 tcl::namespace::eval ::opunk::console {
     variable PUNKARGS
 
-    #well-known cooperative store for bytes consumed by probe reads on pipe-like channels
-    #dict keyed by channel name -> list of chunks. Readers taking over a channel should consume
-    #and clear any entry for that channel first. (analogous to punk::console::input_chunks_waiting)
+    #well-known cooperative store for bytes consumed by probe reads on pipe-like channels:
+    #an array keyed by channel name -> list of chunks. Readers taking over a channel should consume
+    #and clear any entry for that channel first.
+    #The store is PLUGGABLE via waiting_chunks_arrayvar: environments with an established cooperative
+    #store (e.g punk::console::input_chunks_waiting, which the punk repl reader consults) redirect it
+    #so probe-consumed bytes are never invisible to the active reader. The class itself stays free of
+    #any punk::console dependency - redirection is performed by the integrating layer.
     variable waiting_chunks
-    if {![info exists waiting_chunks]} {
-        set waiting_chunks [dict create]
+    if {![array exists waiting_chunks]} {
+        array set waiting_chunks {}
+    }
+    variable waiting_chunks_arrayvar
+    if {![info exists waiting_chunks_arrayvar]} {
+        set waiting_chunks_arrayvar ::opunk::console::waiting_chunks
     }
 }
 
@@ -93,8 +101,10 @@ voo::class ::opunk::Console -virtual {
 
         #Certainty test: is the input channel closed or at eof (and so can never deliver a response)?
         #A consumed/half-closed pipe may not flag eof until a read is attempted, so pipe-like channels
-        #get a non-blocking 1-byte probe. A probed byte is preserved in ::opunk::console::waiting_chunks
-        #for cooperating readers. Console/tty channels are never probed (must not consume a keystroke).
+        #get a non-blocking 1-byte probe. A probed byte is preserved in the cooperative waiting store
+        #(array named by ::opunk::console::waiting_chunks_arrayvar - redirectable by the integrating
+        #layer to e.g punk::console::input_chunks_waiting so active readers can find it).
+        #Console/tty channels are never probed (must not consume a keystroke).
         method at_eof {} -virtual {
             if {[llength $this] < 7} {
                 error "invalid object $this"
@@ -121,7 +131,8 @@ voo::class ::opunk::Console -virtual {
                 return 1
             }
             if {$probe ne ""} {
-                dict lappend ::opunk::console::waiting_chunks $in $probe
+                upvar #0 $::opunk::console::waiting_chunks_arrayvar wchunks
+                lappend wchunks($in) $probe
             }
             return [chan eof $in]
         }

src/modules/opunk/console-buildversion.txt

@@ -1,4 +1,5 @@
-0.1.1
+0.2.0
 #First line must be a semantic version number
 #all other lines are ignored.
 #0.1.1 - can_respond method docs reference punk::console::settle_can_respond for active-probe settling (no behaviour change)
+#0.2.0 - probe-byte waiting store changed from dict to array (::opunk::console::waiting_chunks) and made pluggable via waiting_chunks_arrayvar so integrating layers can redirect to an established cooperative store (e.g punk::console::input_chunks_waiting)

src/modules/punk/console-999999.0a1.0.tm

@@ -352,11 +352,25 @@ namespace eval punk::console {
 
             #-console accepts a channel pair, an anchored opunk::console instance name, or an
             #::opunk::Console object value - resolve to the canonical channel pair (and object if any)
+            set consolespec $inoutchannels
             set cinfo [punk::console::console_spec_resolve $inoutchannels]
             set inoutchannels [list [dict get $cinfo in] [dict get $cinfo out]]
             lassign $inoutchannels input output
-            if {[dict get $cinfo object] ne "" && [::opunk::Console::get.o_can_respond [dict get $cinfo object]] == 0} {
-                error "punk::console::get_ansi_response_payload console object for '$input' '$output' is settled as unable to respond (can_respond=0) - refusing to emit query"
+            set governing_obj [dict get $cinfo object]
+            if {$governing_obj ne ""} {
+                set governing_cr [::opunk::Console::get.o_can_respond $governing_obj]
+                if {$governing_cr == -1 && !$::punk::console::can_respond_settling} {
+                    #first-use active settling so unsettled ambiguous consoles pay one probe rather
+                    #than a fresh timeout per query. Persistable specs only (anchored instance name,
+                    #or the auto-attached default instance) - the latch prevents recursion when the
+                    #settle probe itself passes through here.
+                    if {[llength $consolespec] == 1 || ([info exists ::opunk::console::instances::default] && $governing_obj eq [set ::opunk::console::instances::default])} {
+                        set governing_cr [punk::console::settle_can_respond $consolespec]
+                    }
+                }
+                if {$governing_cr == 0} {
+                    error "punk::console::get_ansi_response_payload console object for '$input' '$output' is settled as unable to respond (can_respond=0) - refusing to emit query"
+                }
             }
 
             #A closed or eof input channel can never deliver a terminal response - fail fast rather than
@@ -1678,11 +1692,16 @@ namespace eval punk::console {
     #during repl::init. console_spec_resolve auto-attaches it for matching channel pairs.
     proc default_console {} {
         if {[info exists ::opunk::console::instances::default]} {
+            #instance exists => opunk::console is loaded - ensure the store unification below applies
+            set ::opunk::console::waiting_chunks_arrayvar ::punk::console::input_chunks_waiting
             return default
         }
         if {[catch {package require opunk::console}]} {
             return ""
         }
+        #unify the class's probe-byte store with our cooperative store so bytes consumed by
+        #opunk::Console probe reads are visible to active readers (punk repl etc)
+        set ::opunk::console::waiting_chunks_arrayvar ::punk::console::input_chunks_waiting
         opunk::console::create default stdin stdout
         return default
     }
@@ -1694,6 +1713,12 @@ namespace eval punk::console {
     if {![info exists can_respond_probe_timeout_ms]} {
         set can_respond_probe_timeout_ms 500
     }
+    #latch: true while settle_can_respond's own probe is in flight, so get_ansi_response_payload's
+    #first-use settling trigger cannot recurse into another settle
+    variable can_respond_settling
+    if {![info exists can_respond_settling]} {
+        set can_respond_settling 0
+    }
 
     punk::args::define {
         @id -id ::punk::console::settle_can_respond
@@ -1768,13 +1793,19 @@ namespace eval punk::console {
             set verdict 0
         } else {
             #layer 3 - active probe (ambiguous zone only): cursor position report
+            variable can_respond_settling
             set capturingregex {(.*)(\x1b\[([0-9]+;[0-9]+)R)$}
-            if {[catch {
-                punk::console::internal::get_ansi_response_payload -expected_ms $timeout_ms -console [list $in $out] "\033\[6n" $capturingregex
-            } payload]} {
-                set verdict 0
-            } else {
-                set verdict [expr {$payload ne "" ? 1 : 0}]
+            set can_respond_settling 1
+            try {
+                if {[catch {
+                    punk::console::internal::get_ansi_response_payload -expected_ms $timeout_ms -console [list $in $out] "\033\[6n" $capturingregex
+                } payload]} {
+                    set verdict 0
+                } else {
+                    set verdict [expr {$payload ne "" ? 1 : 0}]
+                }
+            } finally {
+                set can_respond_settling 0
             }
         }
 

src/modules/punk/console-buildversion.txt

@@ -1,6 +1,7 @@
-0.1.5
+0.1.6
 #First line must be a semantic version number
 #all other lines are ignored.
+#0.1.6 - get_ansi_response_payload performs first-use active settling (with recursion latch) so all query paths pay one probe instead of a timeout per call on unsettled ambiguous consoles; default_console unifies the opunk::console probe-byte store with input_chunks_waiting
 #0.1.5 - settle_can_respond: layered active settling of console response capability (certainty/heuristic without emission, CSI 6n probe with timeout in the ambiguous zone); get_size triggers it at first use for anchored/default console specs; new variable can_respond_probe_timeout_ms
 #0.1.5 - get_ansi_response_payload only cycles console raw mode when the input channel is a console/tty - pipe-targeted probes no longer flip the process console mode (also fixes a repeat-cycle deadlock under captured-channel environments)
 #0.1.4 - new default_console proc; console_spec_resolve auto-attaches the anchored opunk::console instance (name: default) for matching channel pairs

src/modules/punk/repl-999999.0a1.0.tm

@@ -3115,10 +3115,9 @@ namespace eval repl {
         #not find it - risking loss of the first byte of piped input. Ambiguous/non-interactive cases
         #stay unsettled (-1) and are settled at first console use by punk::console::settle_can_respond
         #(layered: certainty/heuristic without emission, active CSI 6n probe only in the ambiguous zone).
-        if {![catch {package require opunk::console}]} {
-            if {![info exists ::opunk::console::instances::default]} {
-                opunk::console::create default stdin stdout
-            }
+        if {[punk::console::default_console] ne ""} {
+            #(default_console also redirects the opunk::console probe-byte store to
+            # punk::console::input_chunks_waiting so active readers see probe-consumed bytes)
             upvar #0 [opunk::console::instancevar default] dconsole
             if {[::opunk::Console::get.o_can_respond $dconsole] == -1 && [punk::repl::is_interactive]} {
                 ::opunk::Console::set.o_can_respond dconsole 1

src/modules/punk/repl-buildversion.txt

@@ -1,6 +1,7 @@
-0.1.5
+0.1.6
 #First line must be a semantic version number
 #all other lines are ignored.
+#0.1.6 - repl::init routes default console construction through punk::console::default_console (also gains the probe-byte store unification)
 #0.1.5 - repl::init comment updated: ambiguous capability settles at first console use via punk::console::settle_can_respond (no behaviour change)
 #0.1.4 - repl::init constructs the process-default console object (opunk::console instance: default) and settles can_respond 1 for interactive stdin (negative settle deliberately not done at init - see comment)
 #0.1.3 - repl::start now cancels the deferred (after idle) stdin reader registration when the repl finishes, preventing a stale registration re-attaching a reader to a completed repl

src/project_layouts/custom/_project/punk.project-0.1/src/bootsupport/modules/opunk/console-0.2.0.tm

@@ -0,0 +1,372 @@
+# -*- tcl -*-
+# Maintenance Instruction: leave the 999999.xxx.x as is and use punkshell 'dev make' or bin/punkmake  to update from <pkg>-buildversion.txt
+# module template: shellspy/src/decktemplates/vendor/punk/modules/template_module-0.0.4.tm
+#
+# Please consider using a BSD or MIT style license for greatest compatibility with the Tcl ecosystem.
+# Code using preferred Tcl licenses can be eligible for inclusion in Tcllib, Tklib and the punk package repository.
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# (C) 2026
+#
+# @@ Meta Begin
+# Application opunk::console 0.2.0
+# Meta platform     tcl
+# Meta license      BSD
+# @@ Meta End
+
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+##  Requirements
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+
+package require Tcl 8.6-
+
+package require voo
+package require punk::args
+
+#opunk::Console - a voo (value-based) representation of a console: an in/out channel pair claimed to
+#belong to one responding endpoint, together with settled capability facts about that endpoint.
+#
+#Motivation (see punk::console get_size / get_ansi_response_payload history):
+#ANSI query mechanisms assume the input channel receives what the output channel's device emits in
+#response. When stdio is redirected that pairing silently breaks - queries go to a terminal whose
+#replies land in some other process's input. A console object makes the pairing an explicit,
+#construction-time property instead of a per-query-site guess.
+#
+#Design notes:
+# - Objects are voo values (plain lists). Consoles are entities, not values - so canonical instances
+#   are anchored at well-known namespace variables (::opunk::console::instances::<name>) and the value
+#   semantics serve as cheap snapshots. Mutation (settling capabilities) goes through the anchor via
+#   the lowercase ::opunk::console wrapper procs.
+# - The class is -virtual: slot 0 of each value carries the concrete class namespace, so channel
+#   environments that respond like terminals but aren't platform consoles can subclass
+#   (-extends ::opunk::Console) and override the capability/size methods, with existing holders of
+#   console values dispatching correctly.
+# - This first cut is standalone and passive: capability detection is heuristic (channel options,
+#   probed eof, terminal env hints) and size uses chan -winsize else the default size. Active ANSI
+#   query probing arrives with punk::console integration (which will delegate here rather than the
+#   class depending on punk::console).
+
+tcl::namespace::eval ::opunk::console {
+    variable PUNKARGS
+
+    #well-known cooperative store for bytes consumed by probe reads on pipe-like channels:
+    #an array keyed by channel name -> list of chunks. Readers taking over a channel should consume
+    #and clear any entry for that channel first.
+    #The store is PLUGGABLE via waiting_chunks_arrayvar: environments with an established cooperative
+    #store (e.g punk::console::input_chunks_waiting, which the punk repl reader consults) redirect it
+    #so probe-consumed bytes are never invisible to the active reader. The class itself stays free of
+    #any punk::console dependency - redirection is performed by the integrating layer.
+    variable waiting_chunks
+    if {![array exists waiting_chunks]} {
+        array set waiting_chunks {}
+    }
+    variable waiting_chunks_arrayvar
+    if {![info exists waiting_chunks_arrayvar]} {
+        set waiting_chunks_arrayvar ::opunk::console::waiting_chunks
+    }
+}
+
+voo::class ::opunk::Console -virtual {
+    private {
+        #o_ prefix per opunk voo convention (distinguishes fields from locals in -update methods,
+        #and matches tclOO-style implementations elsewhere for easier code movement).
+        #Note the class is -virtual: slot 0 of the object value is the concrete class namespace tag.
+        string_t    o_in                stdin
+        string_t    o_out               stdout
+        string_t    o_terminal_class    "" ;#e.g windows-console, tty, pipe - "" until classified
+        list_t      o_size_mechanism    [list] ;#preferred size mechanism try-order - empty until timed/settled
+        dict_t      o_default_size      [dict create columns 80 rows 24]
+    }
+    public {
+        #settled response capability: -1 unknown, 0 cannot respond, 1 can respond.
+        #public accessors (get.o_can_respond / set.o_can_respond) so the anchored-mutation wrappers in
+        #::opunk::console can settle it without reaching into private my.* accessors.
+        int_t       o_can_respond       -1
+
+        method in {} {
+            my.get.o_in $this
+        }
+        method out {} {
+            my.get.o_out $this
+        }
+        method channels {} {
+            list [my.get.o_in $this] [my.get.o_out $this]
+        }
+        method terminal_class {} {
+            my.get.o_terminal_class $this
+        }
+        method default_size {} {
+            my.get.o_default_size $this
+        }
+
+        #Certainty test: is the input channel closed or at eof (and so can never deliver a response)?
+        #A consumed/half-closed pipe may not flag eof until a read is attempted, so pipe-like channels
+        #get a non-blocking 1-byte probe. A probed byte is preserved in the cooperative waiting store
+        #(array named by ::opunk::console::waiting_chunks_arrayvar - redirectable by the integrating
+        #layer to e.g punk::console::input_chunks_waiting so active readers can find it).
+        #Console/tty channels are never probed (must not consume a keystroke).
+        method at_eof {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set in [my.get.o_in $this]
+            if {[catch {chan eof $in} is_eof]} {
+                return 1 ;#closed/invalid channel - unusable
+            }
+            if {$is_eof} {
+                return 1
+            }
+            if {[catch {chan configure $in} conf]} {
+                return 1
+            }
+            if {[dict exists $conf -inputmode] || [dict exists $conf -mode]} {
+                return 0
+            }
+            if {[catch {
+                set prior_blocking [dict get $conf -blocking]
+                chan configure $in -blocking 0
+                set probe [read $in 1]
+                chan configure $in -blocking $prior_blocking
+            }]} {
+                return 1
+            }
+            if {$probe ne ""} {
+                upvar #0 $::opunk::console::waiting_chunks_arrayvar wchunks
+                lappend wchunks($in) $probe
+            }
+            return [chan eof $in]
+        }
+
+        #Heuristic: could the input channel be connected to a terminal able to answer queries?
+        #Returns 0 only when reasonably confident it cannot. mintty without winpty presents a
+        #terminal's stdin as a plain pipe, so env hints (MSYSTEM, TERM_PROGRAM) prevent false
+        #negatives there at the cost of false positives for genuinely piped-but-open input.
+        method is_console_or_tty {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set in [my.get.o_in $this]
+            if {[catch {chan configure $in} conf]} {
+                return 0
+            }
+            if {[dict exists $conf -inputmode]} {
+                return 1
+            }
+            if {[dict exists $conf -mode]} {
+                return 1
+            }
+            if {[at_eof $this]} {
+                return 0
+            }
+            if {[info exists ::env(TERM_PROGRAM)] || [info exists ::env(MSYSTEM)]} {
+                return 1
+            }
+            return 0
+        }
+
+        #Response capability: settled value if known, else computed heuristically (without settling -
+        #this method is pure; use ::opunk::console::can_respond <name> to settle an anchored instance
+        #heuristically, or punk::console::settle_can_respond <spec> for active-probe settling - the
+        #probe machinery lives in punk::console so this class stays free of that dependency).
+        method can_respond {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set settled [get.o_can_respond $this]
+            if {$settled != -1} {
+                return $settled
+            }
+            return [is_console_or_tty $this]
+        }
+
+        #Size of the console: chan -winsize on the output channel when available (fast, no query),
+        #else the configured default size. ANSI cursor-report mechanisms are deliberately absent from
+        #this standalone class - they arrive via punk::console integration and subclasses.
+        method size {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set out [my.get.o_out $this]
+            if {![catch {chan configure $out} oconf]} {
+                if {[dict exists $oconf -winsize]} {
+                    lassign [dict get $oconf -winsize] cols lines
+                    if {[string is integer -strict $cols] && [string is integer -strict $lines]} {
+                        return [dict create columns $cols rows $lines]
+                    }
+                }
+            }
+            return [my.get.o_default_size $this]
+        }
+    }
+
+    constructor {in out} {
+        #new() supplies the class defaults including the virtual class tag at slot 0
+        set obj [new()]
+        my.set.o_in  obj $in
+        my.set.o_out obj $out
+        return $obj
+    }
+}
+
+#make introspection (with i and punk::ns::cmdinfo) easier by making the class namespace an ensemble - we can still access it as ::opunk::Console
+namespace eval ::opunk::Console {
+    namespace ensemble create
+}
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# Anchored instances - the 'consoles are entities' layer
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+tcl::namespace::eval ::opunk::console {
+    tcl::namespace::export {[a-z]*}  ;# Convention: export all lowercase
+
+    namespace eval instances {
+        #one variable per anchored console instance - the canonical location of each console object.
+        #Access via the sibling procs; methods needing to mutate an instance go through these anchors.
+    }
+
+    proc create {name in out} {
+        if {![string is wordchar -strict $name]} {
+            error "opunk::console::create name must be alphanumeric/underscore, got '$name'"
+        }
+        set [namespace current]::instances::$name [::opunk::Console::new $in $out]
+        return [namespace current]::instances::$name
+    }
+    proc instancevar {name} {
+        set v [namespace current]::instances::$name
+        if {![info exists $v]} {
+            error "opunk::console: no anchored console instance named '$name' (known: [names])"
+        }
+        return $v
+    }
+    proc instance {name} {
+        set [instancevar $name]
+    }
+    proc names {} {
+        set result [list]
+        foreach v [info vars [namespace current]::instances::*] {
+            lappend result [namespace tail $v]
+        }
+        return $result
+    }
+    proc forget {name} {
+        unset [instancevar $name]
+        return
+    }
+
+    #settle-and-cache response capability on the anchored instance.
+    #The class method is pure (value-in) - this wrapper owns the mutation via the anchor.
+    proc can_respond {name} {
+        upvar #0 [instancevar $name] obj
+        set settled [::opunk::Console::get.o_can_respond $obj]
+        if {$settled != -1} {
+            return $settled
+        }
+        set r [::opunk::Console::can_respond $obj]
+        ::opunk::Console::set.o_can_respond obj $r
+        return $r
+    }
+    proc size {name} {
+        ::opunk::Console::size [instance $name]
+    }
+}
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+
+
+# == === === === === === === === === === === === === === ===
+# Sample 'about' function with punk::args documentation
+# == === === === === === === === === === === === === === ===
+tcl::namespace::eval ::opunk::console {
+    variable PUNKARGS
+    variable PUNKARGS_aliases
+
+    lappend PUNKARGS [list {
+            @id     -id "(package)opunk::console"
+            @package    -name "opunk::console" -help\
+            "voo class ::opunk::Console representing a console as an in/out channel pair with settled
+            response-capability facts, plus anchored canonical instances under ::opunk::console::instances."
+        }]
+
+    namespace eval argdoc {
+        proc package_name {} {
+            return opunk::console
+        }
+        proc about_topics {} {
+            set topic_funs [info commands [namespace current]::get_topic_*]
+            set about_topics [list]
+            foreach f $topic_funs {
+                set tail [namespace tail $f]
+                lappend about_topics [string range $tail [string length get_topic_] end]
+            }
+            return [lsort $about_topics]
+        }
+        proc default_topics {} {return [list Description *]}
+
+        proc get_topic_Description {} {
+             punk::args::lib::tstr [string trim {
+                package opunk::console
+                voo class for consoles as channel-pair objects with anchored canonical instances.
+            } \n]
+        }
+        proc get_topic_License {} {
+            return "BSD"
+        }
+        proc get_topic_Version {} {
+            return "$::opunk::console::version"
+        }
+        proc get_topic_Contributors {} {
+            set authors {{"Julian Noble" "julian@precisium.com.au"}}
+            set contributors ""
+            foreach a $authors {
+                append contributors $a \n
+            }
+            if {[string index $contributors end] eq "\n"} {
+                set contributors [string range $contributors 0 end-1]
+            }
+            return $contributors
+        }
+        proc get_topic_classes {} {
+            punk::args::lib::tstr -return string {
+                opunk::Console "virtual class for consoles as in/out channel pairs"
+            }
+        }
+    }
+
+    set overrides [dict create]
+    dict set overrides @id  -id   "::opunk::console::about"
+    dict set overrides @cmd -name "opunk::console::about"
+    dict set overrides @cmd -help [string trim [punk::args::lib::tstr {
+                            About opunk::console
+                            }] \n]
+    dict set overrides topic -choices           [list {*}[opunk::console::argdoc::about_topics] *]
+    dict set overrides topic -choicerestricted  1
+    dict set overrides topic -default [opunk::console::argdoc::default_topics]
+    set newdef [punk::args::resolved_def -antiglobs -package_about_namespace -override $overrides ::punk::args::package::standard_about *]
+    lappend PUNKARGS [list $newdef]
+    proc about {args} {
+        package require punk::args
+        set argd [punk::args::parse $args withid ::opunk::console::about]
+        lassign [dict values $argd] _leaders opts values _received
+        punk::args::package::standard_about -package_about_namespace ::opunk::console::argdoc {*}$opts {*}[dict get $values topic]
+    }
+}
+# end of sample 'about' function
+# == === === === === === === === === === === === === === ===
+
+
+# -----------------------------------------------------------------------------
+#    register namespace(s) to have PUNKARGS,PUNKARGS_aliases variables checked
+# -----------------------------------------------------------------------------
+namespace eval ::punk::args::register {
+    #use fully qualified so 8.6 doesn't find existing var in global namespace
+    lappend ::punk::args::register::NAMESPACES ::opunk::console ::opunk::Console
+}
+# -----------------------------------------------------------------------------
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+##  Ready
+package provide opunk::console [tcl::namespace::eval ::opunk::console {
+    variable pkg opunk::console
+    variable version
+    set version 0.2.0
+}]
+return

src/project_layouts/custom/_project/punk.shell-0.1/src/bootsupport/modules/opunk/console-0.2.0.tm

@@ -0,0 +1,372 @@
+# -*- tcl -*-
+# Maintenance Instruction: leave the 999999.xxx.x as is and use punkshell 'dev make' or bin/punkmake  to update from <pkg>-buildversion.txt
+# module template: shellspy/src/decktemplates/vendor/punk/modules/template_module-0.0.4.tm
+#
+# Please consider using a BSD or MIT style license for greatest compatibility with the Tcl ecosystem.
+# Code using preferred Tcl licenses can be eligible for inclusion in Tcllib, Tklib and the punk package repository.
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# (C) 2026
+#
+# @@ Meta Begin
+# Application opunk::console 0.2.0
+# Meta platform     tcl
+# Meta license      BSD
+# @@ Meta End
+
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+##  Requirements
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+
+package require Tcl 8.6-
+
+package require voo
+package require punk::args
+
+#opunk::Console - a voo (value-based) representation of a console: an in/out channel pair claimed to
+#belong to one responding endpoint, together with settled capability facts about that endpoint.
+#
+#Motivation (see punk::console get_size / get_ansi_response_payload history):
+#ANSI query mechanisms assume the input channel receives what the output channel's device emits in
+#response. When stdio is redirected that pairing silently breaks - queries go to a terminal whose
+#replies land in some other process's input. A console object makes the pairing an explicit,
+#construction-time property instead of a per-query-site guess.
+#
+#Design notes:
+# - Objects are voo values (plain lists). Consoles are entities, not values - so canonical instances
+#   are anchored at well-known namespace variables (::opunk::console::instances::<name>) and the value
+#   semantics serve as cheap snapshots. Mutation (settling capabilities) goes through the anchor via
+#   the lowercase ::opunk::console wrapper procs.
+# - The class is -virtual: slot 0 of each value carries the concrete class namespace, so channel
+#   environments that respond like terminals but aren't platform consoles can subclass
+#   (-extends ::opunk::Console) and override the capability/size methods, with existing holders of
+#   console values dispatching correctly.
+# - This first cut is standalone and passive: capability detection is heuristic (channel options,
+#   probed eof, terminal env hints) and size uses chan -winsize else the default size. Active ANSI
+#   query probing arrives with punk::console integration (which will delegate here rather than the
+#   class depending on punk::console).
+
+tcl::namespace::eval ::opunk::console {
+    variable PUNKARGS
+
+    #well-known cooperative store for bytes consumed by probe reads on pipe-like channels:
+    #an array keyed by channel name -> list of chunks. Readers taking over a channel should consume
+    #and clear any entry for that channel first.
+    #The store is PLUGGABLE via waiting_chunks_arrayvar: environments with an established cooperative
+    #store (e.g punk::console::input_chunks_waiting, which the punk repl reader consults) redirect it
+    #so probe-consumed bytes are never invisible to the active reader. The class itself stays free of
+    #any punk::console dependency - redirection is performed by the integrating layer.
+    variable waiting_chunks
+    if {![array exists waiting_chunks]} {
+        array set waiting_chunks {}
+    }
+    variable waiting_chunks_arrayvar
+    if {![info exists waiting_chunks_arrayvar]} {
+        set waiting_chunks_arrayvar ::opunk::console::waiting_chunks
+    }
+}
+
+voo::class ::opunk::Console -virtual {
+    private {
+        #o_ prefix per opunk voo convention (distinguishes fields from locals in -update methods,
+        #and matches tclOO-style implementations elsewhere for easier code movement).
+        #Note the class is -virtual: slot 0 of the object value is the concrete class namespace tag.
+        string_t    o_in                stdin
+        string_t    o_out               stdout
+        string_t    o_terminal_class    "" ;#e.g windows-console, tty, pipe - "" until classified
+        list_t      o_size_mechanism    [list] ;#preferred size mechanism try-order - empty until timed/settled
+        dict_t      o_default_size      [dict create columns 80 rows 24]
+    }
+    public {
+        #settled response capability: -1 unknown, 0 cannot respond, 1 can respond.
+        #public accessors (get.o_can_respond / set.o_can_respond) so the anchored-mutation wrappers in
+        #::opunk::console can settle it without reaching into private my.* accessors.
+        int_t       o_can_respond       -1
+
+        method in {} {
+            my.get.o_in $this
+        }
+        method out {} {
+            my.get.o_out $this
+        }
+        method channels {} {
+            list [my.get.o_in $this] [my.get.o_out $this]
+        }
+        method terminal_class {} {
+            my.get.o_terminal_class $this
+        }
+        method default_size {} {
+            my.get.o_default_size $this
+        }
+
+        #Certainty test: is the input channel closed or at eof (and so can never deliver a response)?
+        #A consumed/half-closed pipe may not flag eof until a read is attempted, so pipe-like channels
+        #get a non-blocking 1-byte probe. A probed byte is preserved in the cooperative waiting store
+        #(array named by ::opunk::console::waiting_chunks_arrayvar - redirectable by the integrating
+        #layer to e.g punk::console::input_chunks_waiting so active readers can find it).
+        #Console/tty channels are never probed (must not consume a keystroke).
+        method at_eof {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set in [my.get.o_in $this]
+            if {[catch {chan eof $in} is_eof]} {
+                return 1 ;#closed/invalid channel - unusable
+            }
+            if {$is_eof} {
+                return 1
+            }
+            if {[catch {chan configure $in} conf]} {
+                return 1
+            }
+            if {[dict exists $conf -inputmode] || [dict exists $conf -mode]} {
+                return 0
+            }
+            if {[catch {
+                set prior_blocking [dict get $conf -blocking]
+                chan configure $in -blocking 0
+                set probe [read $in 1]
+                chan configure $in -blocking $prior_blocking
+            }]} {
+                return 1
+            }
+            if {$probe ne ""} {
+                upvar #0 $::opunk::console::waiting_chunks_arrayvar wchunks
+                lappend wchunks($in) $probe
+            }
+            return [chan eof $in]
+        }
+
+        #Heuristic: could the input channel be connected to a terminal able to answer queries?
+        #Returns 0 only when reasonably confident it cannot. mintty without winpty presents a
+        #terminal's stdin as a plain pipe, so env hints (MSYSTEM, TERM_PROGRAM) prevent false
+        #negatives there at the cost of false positives for genuinely piped-but-open input.
+        method is_console_or_tty {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set in [my.get.o_in $this]
+            if {[catch {chan configure $in} conf]} {
+                return 0
+            }
+            if {[dict exists $conf -inputmode]} {
+                return 1
+            }
+            if {[dict exists $conf -mode]} {
+                return 1
+            }
+            if {[at_eof $this]} {
+                return 0
+            }
+            if {[info exists ::env(TERM_PROGRAM)] || [info exists ::env(MSYSTEM)]} {
+                return 1
+            }
+            return 0
+        }
+
+        #Response capability: settled value if known, else computed heuristically (without settling -
+        #this method is pure; use ::opunk::console::can_respond <name> to settle an anchored instance
+        #heuristically, or punk::console::settle_can_respond <spec> for active-probe settling - the
+        #probe machinery lives in punk::console so this class stays free of that dependency).
+        method can_respond {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set settled [get.o_can_respond $this]
+            if {$settled != -1} {
+                return $settled
+            }
+            return [is_console_or_tty $this]
+        }
+
+        #Size of the console: chan -winsize on the output channel when available (fast, no query),
+        #else the configured default size. ANSI cursor-report mechanisms are deliberately absent from
+        #this standalone class - they arrive via punk::console integration and subclasses.
+        method size {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set out [my.get.o_out $this]
+            if {![catch {chan configure $out} oconf]} {
+                if {[dict exists $oconf -winsize]} {
+                    lassign [dict get $oconf -winsize] cols lines
+                    if {[string is integer -strict $cols] && [string is integer -strict $lines]} {
+                        return [dict create columns $cols rows $lines]
+                    }
+                }
+            }
+            return [my.get.o_default_size $this]
+        }
+    }
+
+    constructor {in out} {
+        #new() supplies the class defaults including the virtual class tag at slot 0
+        set obj [new()]
+        my.set.o_in  obj $in
+        my.set.o_out obj $out
+        return $obj
+    }
+}
+
+#make introspection (with i and punk::ns::cmdinfo) easier by making the class namespace an ensemble - we can still access it as ::opunk::Console
+namespace eval ::opunk::Console {
+    namespace ensemble create
+}
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# Anchored instances - the 'consoles are entities' layer
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+tcl::namespace::eval ::opunk::console {
+    tcl::namespace::export {[a-z]*}  ;# Convention: export all lowercase
+
+    namespace eval instances {
+        #one variable per anchored console instance - the canonical location of each console object.
+        #Access via the sibling procs; methods needing to mutate an instance go through these anchors.
+    }
+
+    proc create {name in out} {
+        if {![string is wordchar -strict $name]} {
+            error "opunk::console::create name must be alphanumeric/underscore, got '$name'"
+        }
+        set [namespace current]::instances::$name [::opunk::Console::new $in $out]
+        return [namespace current]::instances::$name
+    }
+    proc instancevar {name} {
+        set v [namespace current]::instances::$name
+        if {![info exists $v]} {
+            error "opunk::console: no anchored console instance named '$name' (known: [names])"
+        }
+        return $v
+    }
+    proc instance {name} {
+        set [instancevar $name]
+    }
+    proc names {} {
+        set result [list]
+        foreach v [info vars [namespace current]::instances::*] {
+            lappend result [namespace tail $v]
+        }
+        return $result
+    }
+    proc forget {name} {
+        unset [instancevar $name]
+        return
+    }
+
+    #settle-and-cache response capability on the anchored instance.
+    #The class method is pure (value-in) - this wrapper owns the mutation via the anchor.
+    proc can_respond {name} {
+        upvar #0 [instancevar $name] obj
+        set settled [::opunk::Console::get.o_can_respond $obj]
+        if {$settled != -1} {
+            return $settled
+        }
+        set r [::opunk::Console::can_respond $obj]
+        ::opunk::Console::set.o_can_respond obj $r
+        return $r
+    }
+    proc size {name} {
+        ::opunk::Console::size [instance $name]
+    }
+}
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+
+
+# == === === === === === === === === === === === === === ===
+# Sample 'about' function with punk::args documentation
+# == === === === === === === === === === === === === === ===
+tcl::namespace::eval ::opunk::console {
+    variable PUNKARGS
+    variable PUNKARGS_aliases
+
+    lappend PUNKARGS [list {
+            @id     -id "(package)opunk::console"
+            @package    -name "opunk::console" -help\
+            "voo class ::opunk::Console representing a console as an in/out channel pair with settled
+            response-capability facts, plus anchored canonical instances under ::opunk::console::instances."
+        }]
+
+    namespace eval argdoc {
+        proc package_name {} {
+            return opunk::console
+        }
+        proc about_topics {} {
+            set topic_funs [info commands [namespace current]::get_topic_*]
+            set about_topics [list]
+            foreach f $topic_funs {
+                set tail [namespace tail $f]
+                lappend about_topics [string range $tail [string length get_topic_] end]
+            }
+            return [lsort $about_topics]
+        }
+        proc default_topics {} {return [list Description *]}
+
+        proc get_topic_Description {} {
+             punk::args::lib::tstr [string trim {
+                package opunk::console
+                voo class for consoles as channel-pair objects with anchored canonical instances.
+            } \n]
+        }
+        proc get_topic_License {} {
+            return "BSD"
+        }
+        proc get_topic_Version {} {
+            return "$::opunk::console::version"
+        }
+        proc get_topic_Contributors {} {
+            set authors {{"Julian Noble" "julian@precisium.com.au"}}
+            set contributors ""
+            foreach a $authors {
+                append contributors $a \n
+            }
+            if {[string index $contributors end] eq "\n"} {
+                set contributors [string range $contributors 0 end-1]
+            }
+            return $contributors
+        }
+        proc get_topic_classes {} {
+            punk::args::lib::tstr -return string {
+                opunk::Console "virtual class for consoles as in/out channel pairs"
+            }
+        }
+    }
+
+    set overrides [dict create]
+    dict set overrides @id  -id   "::opunk::console::about"
+    dict set overrides @cmd -name "opunk::console::about"
+    dict set overrides @cmd -help [string trim [punk::args::lib::tstr {
+                            About opunk::console
+                            }] \n]
+    dict set overrides topic -choices           [list {*}[opunk::console::argdoc::about_topics] *]
+    dict set overrides topic -choicerestricted  1
+    dict set overrides topic -default [opunk::console::argdoc::default_topics]
+    set newdef [punk::args::resolved_def -antiglobs -package_about_namespace -override $overrides ::punk::args::package::standard_about *]
+    lappend PUNKARGS [list $newdef]
+    proc about {args} {
+        package require punk::args
+        set argd [punk::args::parse $args withid ::opunk::console::about]
+        lassign [dict values $argd] _leaders opts values _received
+        punk::args::package::standard_about -package_about_namespace ::opunk::console::argdoc {*}$opts {*}[dict get $values topic]
+    }
+}
+# end of sample 'about' function
+# == === === === === === === === === === === === === === ===
+
+
+# -----------------------------------------------------------------------------
+#    register namespace(s) to have PUNKARGS,PUNKARGS_aliases variables checked
+# -----------------------------------------------------------------------------
+namespace eval ::punk::args::register {
+    #use fully qualified so 8.6 doesn't find existing var in global namespace
+    lappend ::punk::args::register::NAMESPACES ::opunk::console ::opunk::Console
+}
+# -----------------------------------------------------------------------------
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+##  Ready
+package provide opunk::console [tcl::namespace::eval ::opunk::console {
+    variable pkg opunk::console
+    variable version
+    set version 0.2.0
+}]
+return

src/tests/modules/opunk/console/testsuites/console/consoleclass.test

@@ -69,7 +69,7 @@ namespace eval ::testspace {
             puts -nonewline $wr "x"
             flush $wr
             lappend result [::opunk::Console::at_eof $c]
-            dict unset ::opunk::console::waiting_chunks $rd
+            array unset ::opunk::console::waiting_chunks $rd
             chan configure $rd -blocking 0
             read $rd
             chan close $wr
@@ -90,7 +90,7 @@ namespace eval ::testspace {
         -cleanup {
             catch {chan close $wr}
             catch {chan close $rd}
-            dict unset ::opunk::console::waiting_chunks $rd
+            array unset ::opunk::console::waiting_chunks $rd
         }\
         -result [list\
             0\
@@ -107,9 +107,9 @@ namespace eval ::testspace {
             flush $wr
             lappend result [::opunk::Console::at_eof $c]
             set waiting ""
-            if {[dict exists $::opunk::console::waiting_chunks $rd]} {
-                set waiting [join [dict get $::opunk::console::waiting_chunks $rd] ""]
-                dict unset ::opunk::console::waiting_chunks $rd
+            if {[info exists ::opunk::console::waiting_chunks($rd)]} {
+                set waiting [join $::opunk::console::waiting_chunks($rd) ""]
+                array unset ::opunk::console::waiting_chunks $rd
             }
             chan close $wr
             chan configure $rd -blocking 0
@@ -118,7 +118,7 @@ namespace eval ::testspace {
         -cleanup {
             catch {chan close $wr}
             catch {chan close $rd}
-            dict unset ::opunk::console::waiting_chunks $rd
+            array unset ::opunk::console::waiting_chunks $rd
         }\
         -result [list\
             0\
@@ -152,7 +152,7 @@ namespace eval ::testspace {
         } $hints_restore {
             catch {chan close $wr}
             catch {chan close $rd}
-            dict unset ::opunk::console::waiting_chunks $rd
+            array unset ::opunk::console::waiting_chunks $rd
         }]\
         -result [list\
             0\
@@ -219,7 +219,7 @@ namespace eval ::testspace {
         } $hints_restore {
             catch {opunk::console::forget testanchor2}
             catch {chan close $rd}
-            dict unset ::opunk::console::waiting_chunks $rd
+            array unset ::opunk::console::waiting_chunks $rd
         }]\
         -result [list\
             -1\

src/tests/modules/punk/console/testsuites/console/consolespec.test

@@ -334,5 +334,58 @@ namespace eval ::testspace {
             {}\
         ]
 
+    test settle_store_unification {default_console redirects opunk probe-byte store to input_chunks_waiting}\
+        -setup [string cat $common $hints_save $probe_setup]\
+        -body {
+            catch {opunk::console::forget default}
+            punk::console::default_console ;#sets ::opunk::console::waiting_chunks_arrayvar
+            lappend result [expr {$::opunk::console::waiting_chunks_arrayvar eq "::punk::console::input_chunks_waiting"}]
+            #an opunk-level probe read on any console must now park bytes where punk readers look
+            opunk::console::create teststore1 $rdi $wro
+            puts -nonewline $wri "Z"
+            flush $wri
+            lappend result [::opunk::Console::at_eof [opunk::console::instance teststore1]]
+            set waiting ""
+            if {[info exists ::punk::console::input_chunks_waiting($rdi)]} {
+                set waiting [join $::punk::console::input_chunks_waiting($rdi) ""]
+            }
+            lappend result $waiting
+        }\
+        -cleanup [string cat {
+            set ::opunk::console::waiting_chunks_arrayvar ::opunk::console::waiting_chunks
+            catch {opunk::console::forget teststore1}
+            catch {opunk::console::forget default}
+        } $hints_restore $probe_cleanup]\
+        -result [list\
+            1\
+            0\
+            Z\
+        ]
+
+    test settle_query_first_use {get_cursor_pos on unsettled default console settles at first use then refuses (no per-call timeouts)}\
+        -setup [string cat $common $hints_save $probe_setup]\
+        -body {
+            catch {opunk::console::forget default}
+            opunk::console::create default $rdi $wro
+            #no hints, open pipe: settling resolves 0 via heuristic layer (no emission), query refused
+            set ms_start [clock milliseconds]
+            lappend result [catch {punk::console::get_cursor_pos [list $rdi $wro]} emsg]
+            set elapsed [expr {[clock milliseconds] - $ms_start}]
+            lappend result [expr {$elapsed < 2000}]
+            lappend result [string match "*unable to respond*" $emsg]
+            lappend result [::opunk::Console::get.o_can_respond [opunk::console::instance default]]
+            lappend result [read $rdo] ;#no query bytes may have been emitted
+        }\
+        -cleanup [string cat {
+            catch {opunk::console::forget default}
+        } $hints_restore $probe_cleanup]\
+        -result [list\
+            1\
+            1\
+            1\
+            0\
+            {}\
+        ]
+
 }
 tcltest::cleanupTests ;#needed to produce test summary.

src/vfs/_vfscommon.vfs/modules/opunk/console-0.2.0.tm

@@ -0,0 +1,372 @@
+# -*- tcl -*-
+# Maintenance Instruction: leave the 999999.xxx.x as is and use punkshell 'dev make' or bin/punkmake  to update from <pkg>-buildversion.txt
+# module template: shellspy/src/decktemplates/vendor/punk/modules/template_module-0.0.4.tm
+#
+# Please consider using a BSD or MIT style license for greatest compatibility with the Tcl ecosystem.
+# Code using preferred Tcl licenses can be eligible for inclusion in Tcllib, Tklib and the punk package repository.
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# (C) 2026
+#
+# @@ Meta Begin
+# Application opunk::console 0.2.0
+# Meta platform     tcl
+# Meta license      BSD
+# @@ Meta End
+
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+##  Requirements
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+
+package require Tcl 8.6-
+
+package require voo
+package require punk::args
+
+#opunk::Console - a voo (value-based) representation of a console: an in/out channel pair claimed to
+#belong to one responding endpoint, together with settled capability facts about that endpoint.
+#
+#Motivation (see punk::console get_size / get_ansi_response_payload history):
+#ANSI query mechanisms assume the input channel receives what the output channel's device emits in
+#response. When stdio is redirected that pairing silently breaks - queries go to a terminal whose
+#replies land in some other process's input. A console object makes the pairing an explicit,
+#construction-time property instead of a per-query-site guess.
+#
+#Design notes:
+# - Objects are voo values (plain lists). Consoles are entities, not values - so canonical instances
+#   are anchored at well-known namespace variables (::opunk::console::instances::<name>) and the value
+#   semantics serve as cheap snapshots. Mutation (settling capabilities) goes through the anchor via
+#   the lowercase ::opunk::console wrapper procs.
+# - The class is -virtual: slot 0 of each value carries the concrete class namespace, so channel
+#   environments that respond like terminals but aren't platform consoles can subclass
+#   (-extends ::opunk::Console) and override the capability/size methods, with existing holders of
+#   console values dispatching correctly.
+# - This first cut is standalone and passive: capability detection is heuristic (channel options,
+#   probed eof, terminal env hints) and size uses chan -winsize else the default size. Active ANSI
+#   query probing arrives with punk::console integration (which will delegate here rather than the
+#   class depending on punk::console).
+
+tcl::namespace::eval ::opunk::console {
+    variable PUNKARGS
+
+    #well-known cooperative store for bytes consumed by probe reads on pipe-like channels:
+    #an array keyed by channel name -> list of chunks. Readers taking over a channel should consume
+    #and clear any entry for that channel first.
+    #The store is PLUGGABLE via waiting_chunks_arrayvar: environments with an established cooperative
+    #store (e.g punk::console::input_chunks_waiting, which the punk repl reader consults) redirect it
+    #so probe-consumed bytes are never invisible to the active reader. The class itself stays free of
+    #any punk::console dependency - redirection is performed by the integrating layer.
+    variable waiting_chunks
+    if {![array exists waiting_chunks]} {
+        array set waiting_chunks {}
+    }
+    variable waiting_chunks_arrayvar
+    if {![info exists waiting_chunks_arrayvar]} {
+        set waiting_chunks_arrayvar ::opunk::console::waiting_chunks
+    }
+}
+
+voo::class ::opunk::Console -virtual {
+    private {
+        #o_ prefix per opunk voo convention (distinguishes fields from locals in -update methods,
+        #and matches tclOO-style implementations elsewhere for easier code movement).
+        #Note the class is -virtual: slot 0 of the object value is the concrete class namespace tag.
+        string_t    o_in                stdin
+        string_t    o_out               stdout
+        string_t    o_terminal_class    "" ;#e.g windows-console, tty, pipe - "" until classified
+        list_t      o_size_mechanism    [list] ;#preferred size mechanism try-order - empty until timed/settled
+        dict_t      o_default_size      [dict create columns 80 rows 24]
+    }
+    public {
+        #settled response capability: -1 unknown, 0 cannot respond, 1 can respond.
+        #public accessors (get.o_can_respond / set.o_can_respond) so the anchored-mutation wrappers in
+        #::opunk::console can settle it without reaching into private my.* accessors.
+        int_t       o_can_respond       -1
+
+        method in {} {
+            my.get.o_in $this
+        }
+        method out {} {
+            my.get.o_out $this
+        }
+        method channels {} {
+            list [my.get.o_in $this] [my.get.o_out $this]
+        }
+        method terminal_class {} {
+            my.get.o_terminal_class $this
+        }
+        method default_size {} {
+            my.get.o_default_size $this
+        }
+
+        #Certainty test: is the input channel closed or at eof (and so can never deliver a response)?
+        #A consumed/half-closed pipe may not flag eof until a read is attempted, so pipe-like channels
+        #get a non-blocking 1-byte probe. A probed byte is preserved in the cooperative waiting store
+        #(array named by ::opunk::console::waiting_chunks_arrayvar - redirectable by the integrating
+        #layer to e.g punk::console::input_chunks_waiting so active readers can find it).
+        #Console/tty channels are never probed (must not consume a keystroke).
+        method at_eof {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set in [my.get.o_in $this]
+            if {[catch {chan eof $in} is_eof]} {
+                return 1 ;#closed/invalid channel - unusable
+            }
+            if {$is_eof} {
+                return 1
+            }
+            if {[catch {chan configure $in} conf]} {
+                return 1
+            }
+            if {[dict exists $conf -inputmode] || [dict exists $conf -mode]} {
+                return 0
+            }
+            if {[catch {
+                set prior_blocking [dict get $conf -blocking]
+                chan configure $in -blocking 0
+                set probe [read $in 1]
+                chan configure $in -blocking $prior_blocking
+            }]} {
+                return 1
+            }
+            if {$probe ne ""} {
+                upvar #0 $::opunk::console::waiting_chunks_arrayvar wchunks
+                lappend wchunks($in) $probe
+            }
+            return [chan eof $in]
+        }
+
+        #Heuristic: could the input channel be connected to a terminal able to answer queries?
+        #Returns 0 only when reasonably confident it cannot. mintty without winpty presents a
+        #terminal's stdin as a plain pipe, so env hints (MSYSTEM, TERM_PROGRAM) prevent false
+        #negatives there at the cost of false positives for genuinely piped-but-open input.
+        method is_console_or_tty {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set in [my.get.o_in $this]
+            if {[catch {chan configure $in} conf]} {
+                return 0
+            }
+            if {[dict exists $conf -inputmode]} {
+                return 1
+            }
+            if {[dict exists $conf -mode]} {
+                return 1
+            }
+            if {[at_eof $this]} {
+                return 0
+            }
+            if {[info exists ::env(TERM_PROGRAM)] || [info exists ::env(MSYSTEM)]} {
+                return 1
+            }
+            return 0
+        }
+
+        #Response capability: settled value if known, else computed heuristically (without settling -
+        #this method is pure; use ::opunk::console::can_respond <name> to settle an anchored instance
+        #heuristically, or punk::console::settle_can_respond <spec> for active-probe settling - the
+        #probe machinery lives in punk::console so this class stays free of that dependency).
+        method can_respond {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set settled [get.o_can_respond $this]
+            if {$settled != -1} {
+                return $settled
+            }
+            return [is_console_or_tty $this]
+        }
+
+        #Size of the console: chan -winsize on the output channel when available (fast, no query),
+        #else the configured default size. ANSI cursor-report mechanisms are deliberately absent from
+        #this standalone class - they arrive via punk::console integration and subclasses.
+        method size {} -virtual {
+            if {[llength $this] < 7} {
+                error "invalid object $this"
+            }
+            set out [my.get.o_out $this]
+            if {![catch {chan configure $out} oconf]} {
+                if {[dict exists $oconf -winsize]} {
+                    lassign [dict get $oconf -winsize] cols lines
+                    if {[string is integer -strict $cols] && [string is integer -strict $lines]} {
+                        return [dict create columns $cols rows $lines]
+                    }
+                }
+            }
+            return [my.get.o_default_size $this]
+        }
+    }
+
+    constructor {in out} {
+        #new() supplies the class defaults including the virtual class tag at slot 0
+        set obj [new()]
+        my.set.o_in  obj $in
+        my.set.o_out obj $out
+        return $obj
+    }
+}
+
+#make introspection (with i and punk::ns::cmdinfo) easier by making the class namespace an ensemble - we can still access it as ::opunk::Console
+namespace eval ::opunk::Console {
+    namespace ensemble create
+}
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# Anchored instances - the 'consoles are entities' layer
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+tcl::namespace::eval ::opunk::console {
+    tcl::namespace::export {[a-z]*}  ;# Convention: export all lowercase
+
+    namespace eval instances {
+        #one variable per anchored console instance - the canonical location of each console object.
+        #Access via the sibling procs; methods needing to mutate an instance go through these anchors.
+    }
+
+    proc create {name in out} {
+        if {![string is wordchar -strict $name]} {
+            error "opunk::console::create name must be alphanumeric/underscore, got '$name'"
+        }
+        set [namespace current]::instances::$name [::opunk::Console::new $in $out]
+        return [namespace current]::instances::$name
+    }
+    proc instancevar {name} {
+        set v [namespace current]::instances::$name
+        if {![info exists $v]} {
+            error "opunk::console: no anchored console instance named '$name' (known: [names])"
+        }
+        return $v
+    }
+    proc instance {name} {
+        set [instancevar $name]
+    }
+    proc names {} {
+        set result [list]
+        foreach v [info vars [namespace current]::instances::*] {
+            lappend result [namespace tail $v]
+        }
+        return $result
+    }
+    proc forget {name} {
+        unset [instancevar $name]
+        return
+    }
+
+    #settle-and-cache response capability on the anchored instance.
+    #The class method is pure (value-in) - this wrapper owns the mutation via the anchor.
+    proc can_respond {name} {
+        upvar #0 [instancevar $name] obj
+        set settled [::opunk::Console::get.o_can_respond $obj]
+        if {$settled != -1} {
+            return $settled
+        }
+        set r [::opunk::Console::can_respond $obj]
+        ::opunk::Console::set.o_can_respond obj $r
+        return $r
+    }
+    proc size {name} {
+        ::opunk::Console::size [instance $name]
+    }
+}
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+
+
+# == === === === === === === === === === === === === === ===
+# Sample 'about' function with punk::args documentation
+# == === === === === === === === === === === === === === ===
+tcl::namespace::eval ::opunk::console {
+    variable PUNKARGS
+    variable PUNKARGS_aliases
+
+    lappend PUNKARGS [list {
+            @id     -id "(package)opunk::console"
+            @package    -name "opunk::console" -help\
+            "voo class ::opunk::Console representing a console as an in/out channel pair with settled
+            response-capability facts, plus anchored canonical instances under ::opunk::console::instances."
+        }]
+
+    namespace eval argdoc {
+        proc package_name {} {
+            return opunk::console
+        }
+        proc about_topics {} {
+            set topic_funs [info commands [namespace current]::get_topic_*]
+            set about_topics [list]
+            foreach f $topic_funs {
+                set tail [namespace tail $f]
+                lappend about_topics [string range $tail [string length get_topic_] end]
+            }
+            return [lsort $about_topics]
+        }
+        proc default_topics {} {return [list Description *]}
+
+        proc get_topic_Description {} {
+             punk::args::lib::tstr [string trim {
+                package opunk::console
+                voo class for consoles as channel-pair objects with anchored canonical instances.
+            } \n]
+        }
+        proc get_topic_License {} {
+            return "BSD"
+        }
+        proc get_topic_Version {} {
+            return "$::opunk::console::version"
+        }
+        proc get_topic_Contributors {} {
+            set authors {{"Julian Noble" "julian@precisium.com.au"}}
+            set contributors ""
+            foreach a $authors {
+                append contributors $a \n
+            }
+            if {[string index $contributors end] eq "\n"} {
+                set contributors [string range $contributors 0 end-1]
+            }
+            return $contributors
+        }
+        proc get_topic_classes {} {
+            punk::args::lib::tstr -return string {
+                opunk::Console "virtual class for consoles as in/out channel pairs"
+            }
+        }
+    }
+
+    set overrides [dict create]
+    dict set overrides @id  -id   "::opunk::console::about"
+    dict set overrides @cmd -name "opunk::console::about"
+    dict set overrides @cmd -help [string trim [punk::args::lib::tstr {
+                            About opunk::console
+                            }] \n]
+    dict set overrides topic -choices           [list {*}[opunk::console::argdoc::about_topics] *]
+    dict set overrides topic -choicerestricted  1
+    dict set overrides topic -default [opunk::console::argdoc::default_topics]
+    set newdef [punk::args::resolved_def -antiglobs -package_about_namespace -override $overrides ::punk::args::package::standard_about *]
+    lappend PUNKARGS [list $newdef]
+    proc about {args} {
+        package require punk::args
+        set argd [punk::args::parse $args withid ::opunk::console::about]
+        lassign [dict values $argd] _leaders opts values _received
+        punk::args::package::standard_about -package_about_namespace ::opunk::console::argdoc {*}$opts {*}[dict get $values topic]
+    }
+}
+# end of sample 'about' function
+# == === === === === === === === === === === === === === ===
+
+
+# -----------------------------------------------------------------------------
+#    register namespace(s) to have PUNKARGS,PUNKARGS_aliases variables checked
+# -----------------------------------------------------------------------------
+namespace eval ::punk::args::register {
+    #use fully qualified so 8.6 doesn't find existing var in global namespace
+    lappend ::punk::args::register::NAMESPACES ::opunk::console ::opunk::Console
+}
+# -----------------------------------------------------------------------------
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+##  Ready
+package provide opunk::console [tcl::namespace::eval ::opunk::console {
+    variable pkg opunk::console
+    variable version
+    set version 0.2.0
+}]
+return