fix(terminal): let the daemon own what a program has negotiated about the keyboard (#290)

[Bidthedog]

Linked issue

Related to #290. Deliberately not a closing reference — see What is still open below, which is
the part worth reading before this is merged and the issue ticked off.

• This issue exists and a maintainer explicitly agreed it in a comment — the maintainer asked
  for [Observation] Terminal scrolling dies after a project switch until the window is resized #290 to be worked, and chose this approach over the two alternatives offered.
• The issue is labelled — bug, plus area:terminal and area:projects.

Intent (what & why, in human terms)

#290: after throng has been running a while, switching projects leaves a terminal that accepts input
and paints new output but will not scroll by any route — wheel, PageUp/PageDown,
Ctrl+Home/Ctrl+End. A window resize fixes it every time; Ctrl+F5 never does.

Two sessions had looked at this and could not reproduce it. What follows is a reproduction, a root
cause, and a fix — but not, honestly, a complete account of every symptom in the report.

Outcomes (what changed, in human terms)

A terminal whose program has finished with the keyboard gives the scrollback keys back.

The root cause: the negotiation was applied twice, not missed

The symptom is a belief, not a pixel. use-terminal.ts decides on every keydown:

const programOwnsKeyboard = kittyKeyboardActive(kitty) || altBuffer;

While that is wrongly true on the normal buffer, Ctrl+Home/Ctrl+End are no longer reserved for
scrollback and plain PageUp/PageDown skip the term.scrollPages(...) branch, which is gated on
!programOwnsKeyboard. Two routes die from one boolean.

The interesting part is why the boolean is stale, because it is not the obvious reason. Rebuilding
a view restored the saved state from keyboard-mode-store and then replayed the daemon's
scrollback tail — which still contains the very sequences that produced that state, verbatim,
because appendScrollback preserves control bytes. The kitty protocol is a stack:
CSI > flags u pushes, CSI < n u pops. Two pushes against one pop leaves it enabled, so when the
program finally turned the protocol off, its pop only cancelled the duplicate.

That also explains the recovery behaviour nothing else did. A repaint cannot help, because the belief
is not in the pixels. A resize helps every time because — as this file's own reset comment already
records — programs re-assert their setup after one, and a mounted view parses the re-negotiation
live.

How it was pinned down

Four E2E probes, each differing from the last by one variable, reading
window.__throngTerminalDiagnostics() after a real Ctrl+Home. A fixture Node program negotiates on
cue, so nothing depends on catching a real Claude Code session in the act.

Probe	Program	Panel during the pop	kitty	programOwnsKeyboard	reserved
C (control)	push, pop	mounted	false	false	true
B	push, pop, ~84 KiB filler	unmounted	true	true	false
D	push, pop, ~700 B filler	unmounted	true	true	false
E	push, pop twice, ~700 B	unmounted	false	false	true

• C vs B — same fixture, same sequence; the only difference is whether a view existed to parse
  the pop. So the pop is well-formed and the unmount is what breaks it.
• B vs D — 84 KiB of filler versus 700 bytes, and no difference. This killed the
  MAX_SCROLLBACK-ageing theory I had posted on the issue earlier the same day; I was wrong, and D
  is what showed it. __throngLastReplayBytes was 12,460, so the tail was replayed and did
  contain the pop.
• E — the prediction that follows from double-counting, and it holds exactly. Two pops clear it,
  because the first is eaten by the duplicate push.

The fix: one authority instead of two derivations

• core gains scanKeyboardNegotiation, reading the negotiation out of the raw output stream. It
  is the sibling of trackAltScreen and exists for the same reason — the daemon sees every byte
  whether or not a view is mounted. Unlike trackAltScreen it carries an unterminated trailing
  sequence across chunk boundaries: a lost 1049 self-corrects on the next screen switch, whereas a
  lost pop is permanent and would silently re-create this very defect.
• the daemon tracks it per session and returns it on attach, beside altScreen.
• the view adopts that answer rather than reconstructing it, and mutes the negotiation handlers
  for the span of the replayed tail. The replay is paint; the daemon is truth.

keyboard-mode-store keeps a narrower job — the value a view starts from before the attach resolves
— and its comment now says so instead of claiming to be the authority.

Both halves are load-bearing, and that was measured rather than assumed

Each was disabled in turn, rebuilt, and the regression test re-run:

adoption of res.keyboard disabled   RED   Error: Ctrl+Home did not reach the top of the scrollback (#290)
replay suppression disabled         RED   Error: one pop did not undo one push — the rebuilt view was
                                          carrying a duplicate on its negotiation stack

The observable assertions run before the diagnostics read, deliberately, and that is what those
messages are. A red used to say an internal boolean had the wrong value — true, less useful, and one
inference away from what actually happened to the person who filed the issue.

The first run of that A/B is the part worth keeping, because it found a hole in the test rather
than in the code: with suppression disabled the test still passed. A tail holding both a push and
its pop replays balanced, so the flag lands right by luck — what it gets wrong is the stack depth,
and nothing observable goes wrong until the program pops again, one program exit later than anyone
would think to look. The test grew a second phase that negotiates, rebuilds, then pops live. That
phase is what pins the suppression, and without the A/B it would have shipped as dead code with a
confident comment on it.

Every route the report names is asserted, as the user would see it

The reporter, on the frozen state:

it was CTRL+Home / End, PGUP / PGDN etc, I did not exhaustively test control keys, but typing in to
the prompt worked OK

All of those die from the one boolean, so asserting the boolean would have been enough to make the
test go red. That is an argument, not coverage, so each is asserted directly:

Route	Asserted as
Ctrl+Home	the viewport reaches TOP_OF_HISTORY
Ctrl+End	it returns to the live bottom
plain PageUp / PageDown	off the live bottom, and back — plain, not Shift+, because that is the pair use-terminal.ts gates on !programOwnsKeyboard
typing	echo STILL_ALIVE still reaches the shell

"Typing worked OK" is not a throwaway detail — it is the signature. A stale programOwnsKeyboard
affects the reserved chords and the pager keys and nothing else; ordinary characters never consult
it. Scroll dead, typing fine is exactly what this defect looks like and is what distinguishes it from
a wedged or disconnected terminal. It is asserted for that reason, as the reporter's own control.

What is still open — please read before closing #290

The routes above are fixed and proven. The WHEEL is not addressed, and I will not claim it is.

decideWheel keys off altBuffer and mouseReporting, not off programOwnsKeyboard, so nothing in
this change touches the wheel route. Either it dies by a second mechanism — mouseReporting is
rebuilt from the replayed tail and is not persisted at all, which is the same family of bug from a
different direction — or those sessions also had the alternate screen or DEC mouse modes in play.

So this PR is Related to, not Closes. The check worth doing with a real session in front of you:
when it next happens, confirm whether the wheel alone is still dead once the keyboard chords
work. If it is, that is a follow-up issue and I would take it.

Testing (observed passing — paste/attach evidence)

• npm run test:unit — green
• npm run test:integration — green
• npm run test:contract — green
• npm run test:e2e — green
• Any user-facing UI change ships passing E2E coverage — the regression test is E2E, and the
  file explains why nothing cheaper can hold it: the double-count needs a real daemon with a
  scrollback tail, a view genuinely torn down and rebuilt, and a program emitting negotiation while
  no view exists to parse it. A component test would pass with the defect present.
• New OS-abstraction seams have contract tests — n/a, no new seam; scanKeyboardNegotiation
  is pure and unit-tested in core (12 cases, including every split offset of a push/pop pair).
• @admin / elevation-dependent behaviour verified under an elevated run — n/a.

Test output

Full npm run gate — all eight stages, no flaky retries (205 parallel + 354 serial E2E tests):

[gate] ----------------------------------------------
[gate]  ok  lint           14.5s
[gate]  ok  typecheck       5.3s
[gate]  ok  build           9.4s
[gate]  ok  unit           16.8s
[gate]  ok  component      32.5s
[gate]  ok  integration   3m 12s
[gate]  ok  contract       25.7s
[gate]  ok  e2e          19m 22s
[gate] ----------------------------------------------

[gate] GREEN — all 8 stages passed in 24m 20s.

The core parser on its own — 12 cases, including every split offset of a push/pop pair, so a PTY
chunk boundary cannot swallow a pop:

Test Files  1 passed (1)
     Tests  12 passed (12)

Red before, green after, on the same test and the same command:

before   Error: the rebuilt view still believes the program wants enhanced key reporting, after the
                program turned it off while the panel was unmounted (#290)
         Expected: false   Received: true
         1 failed

after    1 passed

Documentation

• README.md — n/a: no user-facing behaviour, setup, architecture or capability changed
  beyond the defect itself.
• docs/ — n/a, and checked rather than assumed: no guide documents the keyboard
  negotiation (grep -rln "kitty\|negotiat" docs/ returns nothing). The explanation lives where the
  next reader will be standing — negotiation-scan.ts, keyboard-mode-store.ts, and the spec — and
  inventing a docs page for it would be inventing a surface the repo does not have.
• CONTRIBUTING.md — n/a, no process, toolchain, testing bar or setup change.

Constitution compliance

• Change complies with the project constitution.
• SOLID/DRY/YAGNI (VIII), constructor DI via one composition root per boundary (IX), and injected
  configuration (X) are respected. Principle II is the one this change is really about: the parsing
  is a pure function in @throng/core with no OS or DOM in it, the daemon owns the stream, and the
  renderer is told rather than inferring. Principle V is respected in the direction that costs
  something — the parser is unit-tested and only the wiring is E2E.

Toolchain & review

• Authoring (tick one):
  • Produced with Claude Code + Superpowers + Spec Kit + the Superpowers Bridge, driven by
    Claude Opus 4.8 or a more capable model. Model used: claude-opus-5
  • Hand-written / non-AI
• Every artifact passed human review before commit.

AI Code -> Spec Kit artifacts

Spec directory: none — a defect fix with a reproduction, not spec work, so the branch carries no
S segment and creates no specs/NNN-*/. The checklist below is n/a for that reason rather than
skipped.

• spec.md is fully specified — n/a
• /speckit-clarify was run — n/a
• /speckit-plan produced plan.md, research.md, data-model.md, contracts/ — n/a
• /speckit-tasks produced a dependency-ordered tasks.md — n/a
• /speckit-analyze was run — n/a
• Implemented via /speckit-superpowers-bridge — n/a
• /speckit-converge was run — n/a
• Manual testing of all new features carried out — n/a, no feature; the verification is the four
  probes, the red/green pair, the two-way A/B, and the full gate.

Licensing

• I have read and agree to the Contributor Licence Agreement.
• My contribution is my original work, and preserves any upstream copyright/license notices.