@@ -29,64 +29,117 @@ You shouldn't add scope, or break the existing user ux contract.
2929 # Harness first
3030
3131 Captures are worthless if the run isn't reproducible. Pin these before the first
32-walk:
33-
34-- Run the TUI in a tmux pane at a fixed geometry and record that geometry with
35- every capture. The pane's `TERM` must be a real terminal (`xterm-256color`,
36- `screen-256color`): the app emits SGR, enables bracketed paste, and requests
37- kitty keyboard flag 1, so a dumb terminal captures the wrong screen.
38-- Drive keys through tmux: `send-keys -l` for literal text, `send-keys` for named
39- keys (`Enter`, `Escape`, `C-c`, `C-d`, `Tab`, `C-j`, `BTab`, `Up`, `M-b`).
40- For a multi-line paste, use `set-buffer` + `paste-buffer -p` so the app sees
41- real bracketed-paste markers; typing a newline through `send-keys -l` is a
42- different input path. Enable `extended-keys` in the pane for `Shift+Enter`,
43- but test that key once with extended keys off too, since that is what most
44- users' terminals do.
45-- Capture the pane, not the screen: `tmux capture-pane -p -e` keeps styling and
46- `-S -` includes the scrollback above the live region. One capture per state,
47- named `<state>-<geometry>-<step>.txt`; diffing captures between steps is how
48- you see exactly what one keypress changed.
49-- Record one full session at the byte level with `script -q -O run.log` inside
50- the pane. That log is the only artifact showing the erase and redraw traffic
51- the app actually emitted, which is where ghost rows, bad anchors, and
52- duplicated scrollback show up.
32+walk. This environment has **no `tmux`**: the pane *is* a kitty window, driven
33+through kitty's own remote control. Verified present: `kitty` 0.49.1,
34+`spectacle`, `script`, ImageMagick (`identify`/`convert`), `python3`. Not
35+installed: `tmux`, `xdotool`, `wmctrl`, `grim`, `slurp`. Wayland/KDE, display
36+2560x1440 at scale 1. The repo is `/mnt/storage/repos/mini-coder`; `node` v26.8.2
37+runs the TypeScript entrypoint directly.
38+
39+- Launch one kitty instance per geometry, on a private socket, sized in cells
40+ before the app starts:
41+
42+ kitty --detach --listen-on unix:/tmp/uxw-<date> \
43+ -o allow_remote_control=yes -o remember_window_size=no \
44+ -o initial_window_width=100c -o initial_window_height=30c \
45+ --title uxw-walk env PS1='\n$ ' bash --norc --noprofile -i
46+
47+ Then `K() { kitty @ --to unix:/tmp/uxw-<date> "$@"; }` is the whole harness,
48+ and the window id comes from `K ls` — do not assume `id:1`. The app runs on the
49+ kitty pty itself, so `TERM=xterm-kitty`: a real terminal that emits SGR, enables
50+ bracketed paste, and answers the kitty keyboard flag the app requests.
51+- Geometry: `K resize-os-window -m id:N --action resize --unit cells --width W
52+ --height H` resizes the OS window in whole cells, and `K ls` reads the real grid
53+ back (`columns`/`lines` per window) — record that with every capture. Resizes
54+ below two cells are silently ignored, so 1x1 is reachable only by *launching*
55+ at that size (`initial_window_width=1c initial_window_height=1c`, verified);
56+ 80x2, 5x24 and the rest resize fine. There is no status line, so window height
57+ is the pane height.
58+- Keys: `K send-text -m id:N 'literal'` (Python escapes: `\e`, `\n`, `\u21fa`)
59+ for literal text, `K send-key -m id:N <key>...` for named keys — `enter escape
60+ ctrl+c ctrl+d ctrl+a ctrl+e ctrl+w tab shift+tab up down home end ctrl+home
61+ ctrl+end alt+b ctrl+left ctrl+right delete bspace shift+enter`. The app enables
62+ kitty keyboard flag 1 and kitty answers the query itself, so `Shift+Enter`
63+ arrives as its own key; a terminal without the protocol sends the plain-Enter
64+ byte instead, which is reproduced exactly by writing that byte as text. Test
65+ both, since the plain byte is what most users' terminals do.
66+- Paste: `K send-text -m id:N` with the literal `ESC[200~` before the text and
67+ `ESC[201~` after it puts real bracketed-paste markers on the wire (verified
68+ byte-for-byte with `od`), one chunk per call — the replacement for tmux's
69+ `paste-buffer -p`. Build the argument with bash `$'...'` so the escapes stay
70+ literal; typing a newline without the markers is a different input path.
71+- Capture the pane, not the screen: `K get-text -m id:N --extent=all --ansi`
72+ keeps styling and includes the scrollback above the live region;
73+ `--extent=screen` is the live screen alone, `--add-cursor` appends the caret's
74+ exact cell (`ESC[?25h ESC[<row>;<col>H`), and `--add-wrap-markers` separates a
75+ soft wrap from a real newline. One capture per state, named
76+ `<state>-<geometry>-<step>.txt`; diffing captures between steps is how you see
77+ exactly what one keypress changed. A call costs ~25 ms, so a burst loop at
78+ 50-80 ms catches the short-lived phases.
79+- Record one full session at the byte level with `script -q -f -O <run>/sNN.log
80+ -c 'node <repo>/src/cli.ts'` typed into the pane (`-f` flushes, so the log is
81+ readable while the app still runs). It is the only artifact showing the erase
82+ and redraw traffic the app actually emitted — where ghost rows, bad anchors, and
83+ duplicated scrollback show up — and it carries `ESC[?2004h ESC[>1u ESC[?u` on
84+ start, `ESC[<u ESC[?2004l` on stop, and `COMMAND_EXIT_CODE`, which is the exit
85+ code to quote.
5386 - Keep everything the walk produces in one untracked run directory next to the
54- report — `ux-walk-<date>/{captures,shots,sessions}/` — and run every test
55- session with that directory as mini-coder's cwd: `sessionsDir` is left unset,
56- so sessions land in `./sessions` under wherever mini-coder was started. Never
57- start it at the repo root, or the walk writes into the development sessions.
58- Running from the run directory also keeps the model's own `bash` and `edit`
59- calls out of the repo. No config changes, no flags. Afterwards, confirm the
60- development `sessions/` and the repo are untouched.
87+ report — `ux-walk-<date>/{captures,shots}/` plus the logs — and run every test
88+ session with that directory as mini-coder's cwd. `sessionsDir` **is** set in
89+ `~/.config/mini-coder/config.json` (`~/.local/state/mini-coder/sessions`), so
90+ sessions no longer land in the cwd; the run dir is still the right cwd because
91+ it keeps the model's own `bash`/`edit` calls out of the repo and because
92+ `<cwd>/AGENTS.md` is the only resource file read from the cwd (there is no
93+ walk-up), so the repo's `AGENTS.md` is not injected. Attribute the walk's
94+ sessions by the `cwd` field of each `session.jsonl` header and snapshot the
95+ directory before and after: the 28 pre-existing dirs must not change.
96+ - The persistence-failure path is reached by making the *configured* directory
97+ unwritable — `chmod 500 ~/.local/state/mini-coder/sessions`, submit, then
98+ `chmod 700` — not by changing config. It crashes out of `Session.ensure`
99+ without running the app's terminal teardown, so the terminal check after it
100+ matters.
101+- No config changes, no flags. Afterwards confirm the repo is untouched: the
102+ previous walk's artifacts are now tracked, so the new run dir is the one
103+ untracked entry in `git status --short`.
61104 - Images are required, not a nicety: they are what the walk is judged on.
62- Attach the tmux client to a GUI terminal at a fixed size, and take one image
63- per state with `spectacle -a -b -n -o <run>/shots/<state>.png` — it grabs the
64- focused window, so the terminal must be the active window (verified working on
65- this Wayland/KDE session; under X11 `import -window <id>` is the fallback).
66- If the window grab keeps missing, take `spectacle -f -b -n -o full.png` and
67- crop with `convert -crop WxH+X+Y`.
68- - Never assume the geometry: read the real pane size back
69- (`tmux display -p '#{window_width}x#{window_height}'`) and record it next to
70- the image, since window managers, remembered window sizes, and HiDPI scaling
71- all change it. Size the GUI terminal yourself (`kitty -o
72- remember_window_size=no -o initial_window_width=100c -o
73- initial_window_height=30c`) so runs are comparable.
105+ `K screenshot -m id:N <run>/shots/<state>.png` has kitty write a PNG of its own
106+ surface — no window focus needed, no window decoration, and it does include the
107+ text cursor (verified). Cross-check the states where the composited view matters
108+ with `spectacle -a -b -n -o <run>/shots/<state>.png`: it grabs the focused OS
109+ window with title bar and shadows, so the kitty window must be the active one
110+ (verified on this Wayland/KDE session). If a window grab keeps missing, take
111+ `spectacle -f -b -n -o full.png` and crop with `convert -crop WxH+X+Y`.
112+ - Never assume the geometry: read it back from `K ls` and record it next to the
113+ image, and record the measured cell size too (default font here: 9x20 px, so
114+ 100x30 → 900x600 px), since font, scale and padding all move it. Size the
115+ terminal yourself (`initial_window_width=100c initial_window_height=30c`) so
116+ runs are comparable.
74117 - Verify every shot before moving on: `identify` it and look at it. A
75118 screenshot of the wrong window, a stale frame, or a half-drawn pane is worse
76119 than no screenshot, because it goes into the report as evidence.
77120 - Cover what a pixel grab uniquely shows: light theme and dark theme, cursor
78- visibility and position, the spinner frame, dim versus normal intensity,
79- wide characters and emoji, wrapped-token edges, and colors that text
80- captures flatten into escapes.
81-- Use the provider and model already configured in `~/.config/mini-coder`, with
82- short single-purpose prompts — one prompt per state you want to reach — so
83- streaming, reasoning, tool calls, and usage numbers are all genuine. Reach the
84- hostile shapes through the model too: ask it to run a command that prints a few
85- hundred lines, to edit a file large enough to show a full diff, to read an
86- image, to run something slow enough to catch mid-tool phases, or to write a
87- long reply so you can interrupt it mid-stream. Coverage you cannot reach with
88- the real provider (a provider error, a stalled stream) is reported as not
89- covered rather than faked.
121+ visibility and position, the spinner frame, dim versus normal intensity, wide
122+ characters and emoji, wrapped-token edges, and colors that text captures
123+ flatten into escapes. Switch the host theme in place with `K set-colors -a
124+ background=#ffffff foreground=#000000 cursor=#000000`; the app paints its own
125+ palette, so the light-theme check is that no row leaks the host's colours.
126+- Use the provider and model already configured in `~/.config/mini-coder`
127+ (`opencode-go/deepseek-v4.1-flash`, default effort `medium`), with short
128+ single-purpose prompts — one prompt per state you want to reach — so streaming,
129+ reasoning, tool calls, and usage numbers are all genuine. Reach the hostile
130+ shapes through the model too: ask it to run a command that prints a few hundred
131+ lines, to edit a file large enough to show a full diff, to read an image, to run
132+ something slow enough to catch mid-tool phases, or to write a long reply so you
133+ can interrupt it mid-stream. Two states this configuration cannot reach, to be
134+ reported as not covered rather than faked: the `read` of an image on a model
135+ that does *not* accept image input (this model declares image input, so the
136+ other case needs a different provider/model), and a provider error or stalled
137+ stream. Note also that `thinkingLevelMap.medium` is `null`, so the request
138+ carries no thinking level and the dimmed reasoning preview appears only for
139+ prompts that make the model think.
140+- Hazard: with a live turn, the model's own `bash` tool can reach this pane
141+ (`kitty @ --to unix:/tmp/uxw-<date> send-key ...`), so prompts must be
142+ self-contained, and the pane must be re-read rather than assumed to hold still.
90143
91144 # States to walk
92145
@@ -98,10 +151,10 @@ Startup and idle
98151 - banner `mini-coder · <provider>/<model>`, empty scrollback, status row showing
99152 only the context readout, cursor at column 0 of the editor.
100153 - editor: empty draft, one line wrapping past the width, more lines than the
101- viewport, caret at each wrap boundary, Home/End, Ctrl+A/Ctrl+E,
102- Ctrl+Home/Ctrl+End, word motions, backspace/delete across a line join, Ctrl+W
103- at line start, Tab on a non-command draft, paste of multi-line text and of a
104- fence.
154+ viewport, caret at each wrap boundary (read it with `--add-cursor`), Home/End,
155+ Ctrl+A/Ctrl+E, Ctrl+Home/Ctrl+End, word motions, backspace/delete across a line
156+ join, Ctrl+W at line start, Tab on a non-command draft, paste of multi-line text
157+ and of a fence.
105158 - command input: `/help` output, Tab completion on `/` and `/h`, `/unknown` on
106159 Enter (stays a model message), `/help` with trailing args.
107160
@@ -115,8 +168,8 @@ Turn lifecycle
115168 - a tool call whose result never arrives (cancel between the two), several calls
116169 in one assistant message, and call lines in execution order.
117170 - terminal states: `[complete · Ns]`, `! cancelled`, `! <provider error>`,
118- `! <tool error>`; plus the persistence failure path (unwritable
119- `sessionsDir`), which must stop the turn.
171+ `! <tool error>`; plus the persistence failure path (unwritable `sessionsDir`),
172+ which must stop the turn.
120173
121174 Tool rendering
122175
@@ -137,11 +190,13 @@ Terminal and process
137190 - exit: Ctrl+D on an empty draft, Ctrl+D with a draft, Ctrl+C at idle with a
138191 draft, SIGTERM/SIGINT mid-turn. Afterwards check the terminal is still usable:
139192 bracketed paste and kitty flags released, cursor visible, no live region left
140- behind, final scrollback intact, exit code sane.
193+ behind, final scrollback intact, exit code sane (the `script` log records
194+ `COMMAND_EXIT_CODE`).
141195 - geometry: at least 40x12, 80x24, 100x30, 200x50, plus 80x5, 80x2, 20x24, 5x24,
142- 1x1. Resize mid-stream, mid-tool, and while paused, narrow to wide and back.
143- Run one session long enough that the live region re-anchors. Every geometry
144- gets both a text capture and an image.
196+ 1x1 (1x1 needs a fresh launch; kitty refuses sub-two-cell resizes). Resize
197+ mid-stream, mid-tool, and while paused, narrow to wide and back. Run one session
198+ long enough that the live region re-anchors. Every geometry gets both a text
199+ capture and an image.
145200 - scrollback integrity: exactly one blank row between blocks and never two in a
146201 row, nothing rewritten or lost, no orphan rows above the live region after a
147202 commit scrolls the pane, and copying a block out of the terminal yields the