Flip G-007 (location-transparent punk::console) to achieved 2026-07-05 in the
GOALS.md index and detail file. Interactive verification on built punksys
(tcl 8.6) and punk902z (tcl 9) kits (punk::console 0.7.0, opunk::console
0.4.0; punk902z also rerun via src launch against dev modules): fact parity
and immediate cross-context visibility in both directions; brokered terminal
queries from the code interp succeed and cooperate with the repl reader in
raw mode with typed-ahead preserved; a chan-pipe console anchored from the
code interp registers its codethread as owner, operates locally, and clears
its registry entry on forget.
Detail-file Notes record the verification and characterize line-mode reader
cooperation (out of scope, no routing regression - brokered and owner-side
queries behave identically): on tcl 9, complete typed-ahead lines survive
with cosmetic garbling while incomplete typed-ahead starves the query raw
window and leaks responses as phantom input; on tcl 8.6 every line-mode
query fails that way, owner-side included (repro:
repl eval {punk::console::get_cursor_pos}) - candidate owner-side regression
to investigate separately. Also noted: the leaked stderr diagnostics are the
traffic G-011's per-console err channel would house.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Acceptance now names the discovery fact (console_fact_get fact key err,
returning the effective err channel name) so the clause is testable like
G-007's named facts. Detail file additions: "every -console site" is
satisfied at the module's documented resolution choke points
(console_spec_resolve, hybrid_console_spec, opt_console_* helpers,
spec_to_channelpair, shared PUNKARGS fragments) rather than by per-site
audit; the two consumer-shaped acceptance clauses' division of labour is
stated (internal diagnostics migration = first consumer, external consumer
= public emit form); G-001 backends wanting a distinct diagnostic stream
must set err explicitly (default merges into out); and
previous_stty_state_stderr stays as-is (stty-state restoration, orthogonal
to diagnostic routing).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
punk::console models two channels per console ({in out}); its own
diagnostics fall back to raw puts stderr and subshell/backend/theme goals
(G-001/G-008/G-009) inherit the dual-channel assumption. G-011 defines err
as an attribute of the canonical {in out} console identity: {in out err}
specs accepted everywhere -console is, a nullable err field on
opunk::Console, err defaulting to process stderr for the default console
and to the console's out channel elsewhere, console-directed diagnostics
and an emit-to-err path, and cross-thread discovery via console_fact_get.
Ownership/fact/mode-cache keys stay canonical {in out}, so the G-007 work
is untouched.
Detail file records the gap analysis, the rejected shapes (err-in-identity
triple key, scope-boundary-only, uniform err==out, unset-means-none) and
the G-001 sequencing interaction.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
A terminal query (internal::get_ansi_response_payload and every query proc
layered above it - get_cursor_pos, dec_get_mode, ...) on the process-default
console {stdin stdout} issued by a thread that is not the registered owner is
now forwarded whole to the owning thread via synchronous thread::send, so the
query queueing, raw-mode cycling, cooperative reader handling
(input_chunks_waiting) and settled can_respond gating all execute in the
owner's context. Owner-side errors propagate to the caller with routing
context. Routing happens before the local can_respond gate deliberately: a
non-owner context's anchored view of the default console may be unsettled
while the owner's is settled.
New internal::console_route_owner makes the decision: routing applies to the
default console pair only - non-std channel names are thread-local, so an
{in out} pair spec always names the calling thread's own console and operates
locally (a console constructed and owned by code-interp/worker code
round-trips nowhere). Unregistered, owner==caller and dead-owner
(liveness-validated) cases also operate locally, preserving single-interp
behaviour exactly.
The synchronous send relies on the owner servicing events while the caller
blocks - the property the repl-installed vt52/colour/mode aliases already
depend on. Those aliases are unaffected: a call arriving in the owner
resolves to owner==self and takes the local path, so no double-hop and no
ping-pong.
Tests: new ownerrouting.test covers the routing decision (unregistered/self/
other-live-thread/non-default-pair/dead-owner) and the transport (recorder in
a worker-thread owner: args marshalled intact, execution in the owner thread,
query procs above the choke point inherit the routing, owner-side error
propagation). Full suite passes (baseline exec-14.3 only).
G-007 remains active: the remaining acceptance verification is interactive -
a terminal query from a live punk session's code interp against the default
console (cooperating with the repl reader), which needs a real responding
terminal.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Per-console facts are now visible to every thread of a punk session: the
default console {stdin stdout} keeps its legacy namespace variables as
authoritative local storage, with write traces mirroring every write
(including direct variable writes) into tsv punk_console_facts; non-default
consoles store facts only in tsv with owner-qualified keys (non-std channel
names are thread-local and would otherwise alias). console_fact_set from a
non-owner thread forwards to the owning thread (vt52-alias transport) and
always writes the tsv mirror itself (covers unreachable or older-version
owners). New console_fact_clear for tests/maintenance.
New console ownership registry (console_owner_register/get/forget, tsv
punk_console_owners keyed by canonical {in out} pair): ownership is captured
when an opunk::console instance is anchored - via the new pluggable
::opunk::console::lifecycle_callback (opunk::console 0.4.0, base class
unchanged) wired by ensure_object_integration - and by default_console.
Consult-time liveness validation clears entries for exited threads. For
{stdin stdout} first registration wins and only the owner's forget releases
the entry, so a thread anchoring a local view cannot steal ownership.
dec_has_mode/ansi_has_mode caches moved to tsv punk_console_modecache
(single-key atomic entries shared process-wide).
Infrastructure tsv arrays are now punk_-prefixed to avoid collisions with
application tsv usage in subshells: console -> punk_console (is_raw), with
call-site patches in punk::repl 0.2.1, punk::lib 0.2.1, punk::basictelnet
0.1.1 (rule recorded in src/modules/AGENTS.md; legacy repl/codethread_*/
zzzload_pkg* arrays left for a coordinated follow-up).
punk::console is now loadable in secondary threads without ::argv0
(powershell consolemode fallback guarded).
Tests: consolefacts gains ownership-registry and cross-thread visibility
coverage (worker-thread punk::console load, trace-mirror, forwarded set with
deadline-polled sync - see comments re runtests child-interp topology);
cleanups use console_fact_clear / tsv instead of poking removed internal
stores. Full suite passes (baseline exec-14.3 only).
G-007 flipped proposed -> active (user-confirmed); remaining acceptance work
is the choke-point brokering slice.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Migration plan phase 4 (final phase):
- get_cursor_pos, get_cursor_pos_list, get_checksum_rect,
get_device_status, get_device_attributes,
get_device_attributes_tertiary, get_terminal_id, get_tabstops,
get_tabstop_apparent_width, get_dimensions, get_xterm_size,
get_xterm_pixels, dec_get_mode_line_wrap and ansi_get_mode_LNM
accept -console <consolespec> (any spec form) or the legacy
trailing positional, parsed by new internal::hybrid_console_spec;
each carries a PUNKARGS definition (@leaders per the Argument
Order rule)
- get_size refactored onto internal::hybrid_console_spec
(behaviour unchanged)
- documentation-only PUNKARGS for input_at_eof,
is_input_console_or_tty, size_via_query_mechanisms,
console_size_provider and the get_size_using_* mechanism helpers
(signatures unchanged - internal size mechanisms remain
canonical-pair only, per the updated AGENTS.md contract)
AGENTS.md migration bullet rewritten from 'incrementally migrating'
to the completed-state contract. New queryprocs.test (6 tests,
fed-response coverage for every converted proc across spec forms);
full console suite 58/58 on Tcl 9.0.3.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Index entries in GOALS.md plus detail files, all proposed:
- G-007 location-transparent punk::console across repl and code
interps: punk-side tsv-backed ownership registry, fact/cache
visibility, choke-point brokering generalising the vt52 alias;
detail records rejected alternatives (audience namespace split,
owner field on ::opunk::Console, opunk-package-namespace registry)
- G-008 scoped console state for same-console subshells: activatable
per-subshell state sets (journal-on-write, re-emit on activation)
rather than a LIFO undo stack, so later tree switching works;
restore of tabstops/modes/palette on quit; opt-in, shared behaviour
stays default
- G-009 themed subshell profiles: poshinfo schemes bound to
restriction aspects (G-003 limits/hidden commands, punk::island) so
restricted subshells are visually distinct; terminal effects ride
the G-008 state set
- G-010 subshell suspend/resume and tree navigation: switch to any
live subshell (grandparent, cross-branch) via attachment handoff +
G-008 state activation; navigation commands governed by G-003
hide/expose; depends on G-002's non-nested model
Sequencing: G-007 -> G-008 -> G-009/G-010, with G-002 prerequisite
for G-010.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Migration plan phase 1:
- dec_set_mode/dec_unset_mode/ansi_set_mode/ansi_unset_mode and
cursor_style resolve -console via console_spec_resolve instead of
'[lindex $terminal 1]' - anchored opunk::console instance names and
::opunk::Console object values now work (previously silently wrote
to the wrong target)
- the fourteen '-console -type list -minsize 2' declarations replaced
with new shared fragment ::punk::console::argdoc::console_opts (the
-minsize 2 constraint rejected 1-element instance-name specs at
parse time); show_input_response and cell_size -console docs unified
on the fragment
- dec_has_mode/ansi_has_mode cache on the canonical {in out} pair -
all spec forms addressing the same console share one cache entry
- test_is_vt52 option -inoutchannels renamed to -console per the
documented convention (experimental/broken proc, no callers)
- set/unset mode argdocs corrected: <codes> are semicolon delimited
AGENTS.md records the fragment usage and the -minsize 2 prohibition.
3 new tests in consolespec.test (setter spec forms, cache
canonicalisation via mixed specs, test_is_vt52 -console); full console
suite 52/52 on Tcl 9.0.3.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
From 'tclsh src/make.tcl bootsupport' run after commit 0ee66dce -
correctly stamped and containing the final 0.3.0 content (per-console
facts + PUNKARGS @leaders restructure).
Note: the punk.shell-0.1 layout retains console-0.1.0.tm and
console-0.2.0.tm alongside the new 0.3.0 - the prune kept them (no
qualifying punkcheck install record); pending manual removal if
unwanted, per the established prune-leftovers handling.
Copies produced by the developer's src/make.tcl runs alongside the
punk::console work:
- _vfscommon.vfs: punk/console 0.1.7 -> 0.3.0 (final content),
punk/lib 0.1.6 -> 0.2.0, punk/repl 0.1.6 -> 0.2.0,
punk/tcltestrun 0.1.0 -> 0.3.0 (matching their committed source)
- bootsupport (root + punk.project/punk.shell layouts): punk/console
0.1.7 -> 0.2.0. NOTE: this snapshot was taken mid-development - it is
stamped 0.2.0 but already contains the 0.3.0 per-console facts code
(without the final PUNKARGS @leaders restructure). The next
'make.tcl bootsupport' run will supersede it with a true 0.3.0 copy.
Root AGENTS.md closeout now includes a step to re-check modified .tm files for new procs lacking PUNKARGS argdoc blocks. src/modules/AGENTS.md Work Guidance explicitly requires argdoc blocks for all new procs in .tm files (documentation-only is acceptable). The Documentation section clarifies that 'user-facing' includes developer-facing utility procs. A new 'Argument Order In PUNKARGS' section explains the distinction between @leaders, @opts, and @values and why putting a leading argument in @values produces an incorrect synopsis. Verification section adds a check for PUNKARGS argdoc blocks on new procs. The interp_sync.test file contains 6 tcltest tests for the new punk::lib helper procs.
The new 'src' package_mode loads unbuilt modules and libraries from the project's src/ tree (src/modules, src/lib, src/bootsupport, src/vendormodules) instead of built output. It differs from 'dev' mode which points at built <projectroot>/modules. The src mode also runs an inline #modpod package-ifneeded scanner using Tcl builtins only (since no punk modules are loaded at boot time) and sets package prefer latest so 999999.0a1.0 dev modules are preferred over stable bootsupport/vendored copies. The exhaustive permutation switch for package_mode parsing was replaced with token-by-token validation that scales to any number of modes. Verified: punk902z src launches an interactive shell with package provide punk returning 999999.0a1.0.
The codethread init_script now propagates package prefer via a new %packageprefer% scriptmap entry. The code interp (punk/0 repltype) creation replaces the manual epoch-only copy with punk::lib::interp_sync_package_paths code -libunknown 1, which propagates tm list, auto_path, package prefer, and libunknown epoch+init from the codethread to the code interp. This fixes the issue where package prefer latest set in punk_main.tcl was not inherited by the REPL's code interp, causing 999999.0a1.0 dev modules to be passed over in favour of stable VFS-bundled versions.
snapshot_package_paths returns a script string reproducing the caller's tcl:™️:list, auto_path, and package prefer for use in thread::create init scripts. With -libunknown 1 it also copies the punk::libunknown epoch and sources+inits libunknown in the target. interp_sync_package_paths now propagates package prefer (was missing) and accepts optional -libunknown 1 flag for epoch copy + libunknown init in the child interp. Both procs have PUNKARGS argdoc documentation. Includes 6 tcltest tests covering basic propagation, version selection with package prefer latest, ordering preservation, snapshot script validity, -libunknown flag, and regression.
Both tm_path_additional_ifneeded call sites now pass \ as required by the 0.3.0 API. The second call site also passed the wrong path (../modules instead of ../modules_tcl\) due to a copy-paste bug, so Tcl-major-specific #modpod modules were never scanned. Added a zipper #modpod verification test that confirms package require zipper resolves to the 999999.0a1.0 #modpod version via the ifneeded mechanism and that initialize/addentry/finalize work correctly. All 4 tests pass under tclsh90.
tm_path_additional_ifneeded referenced an out-of-scope \ variable that was never a parameter or local, causing 'can't read project_root: no such variable' whenever a #modpod module was found. The proc now requires project_root as a 2nd parameter. Additionally, the #modpod directory pattern was hardcoded to 999999.0a1.0 which the build system replaces with the real version (e.g 0.3.0) during make.tcl modules — breaking pattern matching in built bootsupport copies that looked for #modpod-*-0.3.0 directories which don't exist on disk. The proc now extracts both modname and version dynamically from the #modpod-<modname>-<version> directory name by splitting on the last dash, making it version-agnostic. Punk::lib::tm_version_magic convention was considered but dynamic extraction is preferred here as it will also work in the future src package_mode boot context where punk modules aren't loaded yet.
runtests_failure_summaries now includes errorinfo, result_was, and result_expected when present in the parsed testdict, so the json report (which iterates keys) and downstream consumers get the full failure context. runtests_print_failure_details prints an errorInfo fenced block for ERROR-status failures and result_was/result_expected fenced blocks for FAILED-status mismatches, with full multi-line text. The compact report appends one-line truncated message=, actual=, and expected= fields (120/80/80 chars) so compact mode stays compact while still being actionable for agents. src/tests/AGENTS.md Local Contracts and Work Guidance updated to document the new failure-detail surfacing.
parse_testrun now keeps the full Tcl errorInfo in testcase_fails entries for ERROR-status failures (previously parsed then discarded), and captures the actual vs expected result blocks for FAILED-status result mismatches via a new result_stage sub-state. Test name extraction in the took/PASSED/SKIPPED handlers is fixed to use the full substring between the structural delimiters instead of lindex \ 1, which corrupted timing associations and testcase_passes/testcase_constraintskips keys for any test name containing spaces; the took handler uses string last to allow test names that themselves contain the word 'took'. The closing-FAILED microseconds lookup now keys on \ (authoritative) instead of the stale \. New dict keys are additive; existing consumers using dict exists/dict get are unaffected.
- disableAnsi was defined as a duplicate enableAnsi in the windows
no-twapi branch, leaving disableAnsi undefined there
- get_size_using_cursormove flushed stdout instead of the supplied
output channel
- get_size_using_chanconfigure: removed unreachable code after its
unconditional error
- cell_size: query path now passes its -console spec to get_size
instead of always querying the default console; bad-format error
message named punk::sixel instead of punk::console
- test_string_cursor: undefined $test_string reference in the no-ansi
path; rowoffset/columnoffset return labels were swapped
- ansi::move_emit vt52 branch called nonexistent punk::ansi::v52move_emit
(now vt52move_emit)
- move_emit_return re-expanded {*}$args inside its per-triple loop,
duplicating emissions when extra row/col/data triples were supplied
- dec_has_mode unknown-mode error message named dec_get_mode
Console module test suites pass (27/27, Tcl 9.0.3).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Agents must not add new executable binaries (or zip-based .tm modules
embedding executables). Existing committed binaries are intentional
interim state pending goals G-004/G-005/G-006 and must not be flagged
or 'fixed'; the rule does not block the developer's own interim commits.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Index entries in GOALS.md plus detail files. G-004 targets a binary-free
committed tree, achievable once G-005 (zig-based build of binary deps from
source) or G-006 (consent-gated download of pre-built artifacts) provides
the replacement supply of the previously committed binaries.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
G-001 pluggable console backends for non-detectable terminals (ssh channel, tk widget) via ::opunk::Console subclasses. G-002 non-nested subshell with console targeting and inter-subshell comms, including thread::send -async routing to the code sub-interp and the canonical launch API design (subshell as sole entry point, interp alias as context signal). G-003 configurable resource limits (command-count, time via interp limit) and sandboxing spectrum (interp hide/expose/alias, safe::interpCreate) on subshell interps, downstream of G-002's asymmetry fix.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Assisted-by: harness=opencode; primary-model=unknown; api-location=unknown
Harness-agnostic technical project goal system. GOALS.md holds the canonical one-line index with format spec, status taxonomy, maintenance rules, and an agent-authoring workflow so agents asked to 'help me write a goal for X' ask the right questions. GOALS-archive.md is the achieved-goals archive stub. goals/AGENTS.md is the DOX child doc covering naming (G-<id>-<slug>.md), when a detail file is warranted, and the no-orphans/archive rule. goals/archive/.gitkeep tracks the archive dir.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Assisted-by: harness=opencode; primary-model=unknown; api-location=unknown
Resolves the build-maintenance TODO: built module trees no longer accumulate
superseded intermediate versions, and .punkcheck state stays consistent because
every deletion is recorded through punkcheck's event mechanism.
punkcheck (0.3.0):
- installsource_add_virtual + installevent method targetset_addsource_virtual:
'virtual' named-value SOURCE records (-type virtual -path virtual:<id> -value <v>)
compared by stored value, participating in targetset_source_changes. Needed
because successive module versions are built from the same physical source
files - the recorded virtual module_name/module_version identify which
product of the source fileset a target is, at install and delete time.
punk::mix::cli (0.5.0):
- lib::prune_superseded_target_modules: deletes lower-version .tm siblings only
when records prove the same module line (virtual module_name match, or legacy
fallback: recorded sources share the keep-version's source folder(s) and name
prefix). Unrecorded files are never deleted - reported to stderr instead.
- lib::prune_sourcevanished_targets: mirror-prune of recorded targets whose
recorded source files no longer exist (layout bootsupport copies, vendormodule
copies) - intentional multi-version vendoring is preserved.
- build_modules_from_source_to_base prunes after each module install/skip and
records virtual module identity sources on installs.
make.tcl:
- bootsupport: non-glob include_modules.config entries track only the latest
version - superseded recorded snapshot versions pruned; project-layout copies
mirror-pruned; virtual identity recorded on snapshot installs. Calls guarded
(info commands) so a stale bootsupport snapshot degrades to a warning and the
two-pass modules+bootsupport bootstrap self-heals.
- vendormodule copies in root modules*/ mirror-pruned after install.
docs/config:
- include_modules.config headers now document the entry format (non-glob =
latest-only + prune; glob chars = keep all matches; unrecorded never pruned)
- src/AGENTS.md TODO replaced with the durable prune contract;
src/bootsupport/AGENTS.md + src/tests/modules/AGENTS.md updated
tests: src/tests/modules/punk/mix/testsuites/cli/prune.test (19 tests) covering
virtual source recording/comparison and prune identity/safety rules.
Suites: punkcheck 64/64, full suite under Tcl 9.0.3 green except pre-existing
exec-14.3.
payload sync: bootsupport snapshots, project layouts and _vfscommon.vfs pruned
of superseded intermediates (~570k lines of stale .tm copies removed).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
opunk::console (0.3.0):
- base size method resolution order: -winsize fast path -> capability gate (settled or heuristic
can_respond; unresponsive consoles get default_size with no query emission) -> pluggable
::opunk::console::size_query_provider -> default_size. The provider hook follows the
waiting-store pattern: the class carries no punk::console dependency, and non-channel
subclasses (tk widget / channel-environment terminals) simply override size.
punk::console (0.1.7):
- get_size dispatches object-governed calls through the virtual ::opunk::Console::size method
after first-use settling - subclass size overrides are honoured from every punk::console
call site
- ANSI/tput mechanisms + per-pair timing cache factored into size_via_query_mechanisms, shared
by the legacy channel-pair path and the registered provider (console_size_provider)
- integration wiring consolidated into once-latched ensure_object_integration (probe-byte store
redirect + provider registration, respecting customised providers), invoked from
default_console, console_spec_resolve lazy-require sites and the get_size object path
- legacy path returns the documented 80x24 fallback instead of erroring when undetermined
tests: WidgetishConsole subclass override returned through punk::console::get_size for both
anchored-name and object-value specs; class-level provider consultation/capability-gating with
a counting fake provider; provider registration assert. Console suites 27/27 + 10/10; 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
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
