diff --git a/CLAUDE.md b/CLAUDE.md index 9472b727..ae326564 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -228,7 +228,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph **Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the whole tmux scrollback ALONE (`source='mux-full-history'`), superseding the byte buffer. First load of each non-shell TUI session requests it (`_fullHistoryLoaded`); Shell selection, drop recovery, clear and a tile's load use `SHELL_LOAD_QUERY` (constants.js), a bounded window of tmux's RENDERED history (`?full=1&tail=1MiB&alt=recording&lines=10000`), never the raw byte recording, whose full-screen repaints replayed at another pane height push copies of their top row into scrollback; the route reports a client `lines=` bound below the history ceiling that left lines in tmux as `truncationReason: 'tail'`, and `alt=recording` falls back to the visible frame over the tailed byte recording when the pane is in the alternate screen (a nested tmux in a remote or Docker case keeps no tmux history; vim/less take it too while open). A Shell scroll-to-top pulls a bounded `?full=1&tail=` window (a window no longer than the browser's buffer is skipped before the downgrade guard, so it never marks the session exhausted); the unbounded pull stays behind **Load full history**. A Shell split-pane Pane B has its own copy of the bounded pull against its own xterm (`TerminalTile._pullHistory`, terminal-tile.js); keep the two in step. → [architecture-invariants#split-pane-sessions](docs/architecture-invariants.md#split-pane-sessions) ⚠️ The capture ends with a RELATIVE cursor move back to the pane's caret (never `CUP`), so no line-deleting transform may run over it; those skips key on `isFullCapture`, never on `?full=1` alone. ⚠️ A re-pull must never shrink the buffer (`_replayWouldShrinkBuffer()`). ⚠️ `captureCols`/`captureRows` are absent when no frame was positioned: test `Number.isFinite`, never truthiness. ⚠️ A frame dropped at the 128 KiB render cap MUST be recovered, and the recovery verifies itself: `_scheduleDroppedOutputRecovery` re-arms (bounded by `DROP_RECOVERY_MAX_ATTEMPTS`) while `_onSessionNeedsRefresh` reports no repaint, but never after a capture-fetch `'deadline'`. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay) -**Terminal scrollback strip + wheel/touch forwarding**: codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed opencode, copilot and pi get the MIDDLE strip (alt-screen toggles + mouse DECSETs, `3J` kept); every other tmux-backed mode (shell/antigravity/grok/deepseek/omp) gets the NARROW strip (alt-screen toggles only). Table: `CliCapabilities.altScreen` JSDoc, pinned in test/claude-scrollback-strip.test.ts. ⚠️ Gated on `useMux`: direct-PTY sessions must keep the alt screen. Wheel and touch forward only with observed `cliMouseTracking`: **Claude ≥ 2.1.187, tracked Codex, tracked Copilot, or tracked Pi**. Codex 0.163.0 fullscreen was measured with `alternate_on=1`, `mouse_any_flag=1`: one SGR report moves one transcript row; see the fresh measurement in architecture-invariants. Inline/untracked Codex retains local history or the capability-gated paging fallback. Copilot has no version gate; a stale/false tracking flag falls back to PageUp/PageDown. Pi has no version gate either, and is fullscreen by default since 1.0.0: it enables tracking once at start, so the flag is what survives a tab switch or reload (xterm's own mode does not). ⚠️ Pi deliberately has no `transcriptPageKeys`: its `tuiMode: regular` binds those keys to the editor, so paging there moves a draft's caret. Touch alone has one more branch (`_shouldForwardTouchToApp`): in any mode, a drag also forwards as SGR wheel reports while xterm ITSELF tracks the mouse with SGR encoding (an app in the pane asked for it; a tracking mode other than `x10` and `coreMouseService.activeEncoding === 'SGR'`, so DEFAULT, X10 and SGR-pixel apps fail closed), because xterm encodes a wheel there but the touch listeners consume the drag. ⚠️ `getClaudeCliVersion()` must never cache a FAILED probe. ⚠️ Hand-report clicks only while the CLI has mouse tracking on: `_shouldReportMouseToCli()` gates all three report sites on `cliMouseTracking` (from `_recordStrippedMouseMode()`, session.ts), or a plain shell prints the reports as literal text. ⚠️ A `TerminalTile` (grid tile, split Pane B) forwards the wheel as SGR reports, pages it and reports clicks through these SAME gates with itself as the target (its terminal, its session, never `activeSessionId`), and scrolls Shift+wheel itself (xterm makes it a horizontal no-op); never copy the mode lists into terminal-tile.js. ⚠️ The hollow-buffer PageUp/PageDown fallback (`_maybePageCliTranscript`) stands down when the last capture reported tmux scrollback (`paneHistoryLines` > 0: a tail replayed after a server restart carries only the attach repaint), so the gesture scrolls locally and the scroll-to-top pull loads `full=1`; 0 and unknown keep paging. Read `_logScrollRouting()` before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding) +**Terminal scrollback strip + wheel/touch forwarding**: codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed opencode, copilot and pi get the MIDDLE strip (alt-screen toggles + mouse DECSETs, `3J` kept); every other tmux-backed mode (shell/antigravity/grok/deepseek/omp) gets the NARROW strip (alt-screen toggles only). Table: `CliCapabilities.altScreen` JSDoc, pinned in test/claude-scrollback-strip.test.ts. ⚠️ Gated on `useMux`: direct-PTY sessions must keep the alt screen. Wheel and touch forward only with observed `cliMouseTracking`: **Claude ≥ 2.1.187, tracked Codex, tracked Copilot, or tracked Pi**. Which CLIs forward is the registry's `wheelForward`, published as `window.__codemanWheelForward` and never an id list in the gate, so a custom `clis.json` entry opts in with it plus `altScreen: 'strip-mux-and-mouse'` (`docs/cli-registry.md`). Codex 0.163.0 fullscreen was measured with `alternate_on=1`, `mouse_any_flag=1`: one SGR report moves one transcript row; see the fresh measurement in architecture-invariants. Inline/untracked Codex retains local history or the capability-gated paging fallback. Copilot has no version gate; a stale/false tracking flag falls back to PageUp/PageDown. Pi has no version gate either, and is fullscreen by default since 1.0.0: it enables tracking once at start, so the flag is what survives a tab switch or reload (xterm's own mode does not). ⚠️ Pi deliberately has no `transcriptPageKeys`: its `tuiMode: regular` binds those keys to the editor, so paging there moves a draft's caret. Touch alone has one more branch (`_shouldForwardTouchToApp`): in any mode, a drag also forwards as SGR wheel reports while xterm ITSELF tracks the mouse with SGR encoding (an app in the pane asked for it; a tracking mode other than `x10` and `coreMouseService.activeEncoding === 'SGR'`, so DEFAULT, X10 and SGR-pixel apps fail closed), because xterm encodes a wheel there but the touch listeners consume the drag. ⚠️ `getClaudeCliVersion()` must never cache a FAILED probe. ⚠️ Hand-report clicks only while the CLI has mouse tracking on: `_shouldReportMouseToCli()` gates all three report sites on `cliMouseTracking` (from `_recordStrippedMouseMode()`, session.ts), or a plain shell prints the reports as literal text. ⚠️ A `TerminalTile` (grid tile, split Pane B) forwards the wheel as SGR reports, pages it and reports clicks through these SAME gates with itself as the target (its terminal, its session, never `activeSessionId`), and scrolls Shift+wheel itself (xterm makes it a horizontal no-op); never copy the mode lists into terminal-tile.js. ⚠️ The hollow-buffer PageUp/PageDown fallback (`_maybePageCliTranscript`) stands down when the last capture reported tmux scrollback (`paneHistoryLines` > 0: a tail replayed after a server restart carries only the attach repaint), so the gesture scrolls locally and the scroll-to-top pull loads `full=1`; 0 and unknown keep paging. Read `_logScrollRouting()` before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding) **Detached start + service install**: `codeman web -d` relaunches the same entry script `detached:true` (setsid); `nohup` is not what makes it survive. ⚠️ Both `-d` and `service install` must REFUSE when a server is already up on this data dir (pidfile + `/api/status` probe), or a second instance attaches to the first one's live sessions. ⚠️ Never report success not observed: poll `/api/status` until the child answers or dies. `--stop` must verify the pid still looks like Codeman (`ps -o command=`) before signalling. Unit/label names live only in `config/service-names.ts`. `service install` bakes the installing shell's PATH into the unit and never writes `CODEMAN_PASSWORD` into it. → [architecture-invariants#detached-start-and-service-install](docs/architecture-invariants.md#detached-start-and-service-install) **Self-update** (App Settings → System → Updates): in-app updater for git-clone installs under a supervisor (`systemd`, `launchd`, `launchd-daemon`, `docker-compose`, else `none`). The work runs in a DETACHED `scripts/self-update.sh` writing `update-status.json`, polled across the restart; pure helpers in `src/web/self-update.ts`. ⚠️ Compose: the restart kills the script, so nothing may be appended after the `restarting` marker; the repo must stay a host bind mount over `/opt/codeman` and the image must keep devDependencies + toolchain. ⚠️ `evaluateEnvironmentGate()` refuses releases that change `server.Dockerfile`/`docker-compose.yaml` or add `.env.example` keys, re-evaluated on `POST /api/system/update`; unknowns fail OPEN, but the exit-to-restart needs `--restart-by-exit 1` (`CODEMAN_RESTART_BY_EXIT=1` only in the Compose file). ⚠️ An install with no git checkout (`install.sh` on a machine without a working git leaves the marker `.install-source`) is kind `archive`: it cannot update in place, and both the check and the UI tell it to re-run the installer, never the npm line. ⚠️ Keep the agent CLIs in `server.Dockerfile` pinned. → [docs/docker-self-update.md](docs/docker-self-update.md), [architecture-invariants#self-update](docs/architecture-invariants.md#self-update) diff --git a/docs/architecture-invariants.md b/docs/architecture-invariants.md index e17a089b..8119d385 100644 --- a/docs/architecture-invariants.md +++ b/docs/architecture-invariants.md @@ -135,7 +135,7 @@ Further detail: ⚠️ An ADOPTED container may back SEVERAL cases at different ⚠️ **`param` is TWO namespaces.** `launch.params` keys, `env.configSetenv[].fromParam` and `capabilities.privilegedParams[].param` all name a LAUNCH PARAM; the legacy `Config` wire field is a separate namespace, bridged only by `launch.legacyConfigAliases`. Getting `privilegedParams[].param` wrong is SILENT — it is the multi-user bypass clamp's only handle on a CLI's privilege switch, and a wrong name clamps nothing with no load error and no failing test — so `schema.ts` rejects an entry naming a param it never declared. Codex is the entry where the two names differ (`bypassApprovals` vs `dangerouslyBypassApprovals`) and therefore the one that catches a regression. -⚠️ Five fields are DECLARED-FOR-LATER and read by nothing (`accent`, `capabilities.echo`/`wheelForward`/`keyboardAccessory`/`maxFrameBytes`): all frontend behaviour, transcribed rather than measured (except `accent`, measured against styles.css on 2026-09-21), so re-measure before wiring one up; the list is pinned so it cannot quietly grow. (`shortBadge` left the list when the Settings CLI management list started showing it.) +⚠️ Four fields are DECLARED-FOR-LATER and read by nothing (`accent`, `capabilities.echo`/`keyboardAccessory`/`maxFrameBytes`): all frontend behaviour, transcribed rather than measured (except `accent`, measured against styles.css on 2026-09-21), so re-measure before wiring one up; the list is pinned so it cannot quietly grow. (`shortBadge` left the list when the Settings CLI management list started showing it, and `wheelForward` when the browser's wheel gate started reading it.) Spawn commands are pinned as literal strings in `test/cli-registry-spawn-golden.test.ts`, remote/docker pane commands in `test/location-overlay-commands.test.ts`. ⚠️ That second golden no longer covers **remote claude or remote omp**: both now have their own arm in `buildRemoteLaunchCommand` (a `--session-id || --resume` pair, and `--continue`, so a respawn continues the same conversation) and never reach `defaultRemoteCommandForMode`, which is what that test asserts. Their real pins are `toContain` substrings in `test/tmux-manager.test.ts` and `test/remote-shared-sessions.test.ts`; changing either arm will NOT fail the golden. @@ -267,7 +267,7 @@ Further detail: the `: ` form (`w3-myapp: fix the login redirect` ⚠️ **What a mouse-DECSET strip (full or mouse) removes, it must REMEMBER.** Stripping the mouse DECSETs means xterm's `modes.mouseTrackingMode` is permanently `'none'` for those modes, so the browser hand-encodes click reports to compensate (`_sendSyntheticSgrTap`). With no state to consult it did that on EVERY click, which delivered mouse reports to programs that never asked for them: the same pane runs a plain shell whenever the CLI has exited or a `shell` was started inside a claude-mode session, and a shell prints the report as literal text (`[<0;88;20M`), garbling the next line typed. `_recordStrippedMouseMode()` therefore records each stripped sequence as it goes and publishes `cliMouseTracking` through `toState()`, and `_shouldReportMouseToCli()` requires it. ⚠️ Only the TRACKING modes count (1000/1001/1002/1003): 1005/1006 select an ENCODING and 1007 is alt-scroll, and counting those would put the stray reports straight back. ⚠️ The change broadcasts IMMEDIATELY rather than through `broadcastSessionStateDebounced`, because the flag flips when a dialog opens and the user can click that dialog inside the 500ms debounce window. Measured on a live claude 2.x: the CLI holds a tracking mode on continuously in fullscreen (so clicks keep being reported exactly as before; the default inline renderer holds none, measured on 2.1.283 even with `/model` open), while a bash prompt in the same stripped mode reports nothing. Fails toward silence: after a server restart the flag is false until the CLI re-emits, which tmux does at client attach. -**Wheel forwarding requires observed mouse tracking: Claude ≥ 2.1.187, tracked Codex, tracked Copilot or tracked Pi** (`terminal-ui.js:_shouldForwardWheelToApp`). The original #227 measurement remains valid for **Codex 0.147.0 inline**: `alternate_on=0`, `mouse_any_flag=0`, growing tmux history, and SGR wheel reports do nothing. Claude 2.1.280 inline similarly reports `alternate_on=0`, `mouse_any_flag=0`; forwarding there swallows gestures, so it keeps local scrollback. Fullscreen Claude (`CLAUDE_CODE_NO_FLICKER=1` or `"tui": "fullscreen"`) enables mouse tracking and accepts reports. **Fresh Codex 0.163.0 fullscreen measurement (2026-10-18, isolated local tmux pane)**: `alternate_on=1`, `mouse_any_flag=1`; one `\x1b[<64;10;10M` report moves the transcript one row upward, and `\x1b[<65;10;10M` restores the original screen. This is capability evidence, not a minimum-version promise: untracked Codex (including a 0.162.0 measurement (2026-10) with `mouse_any_flag=0`) keeps local history or the hollow-pane paging fallback. Codex does not publish the Claude-only CLI version field, so its gate requires the observed flag rather than a Claude version. The registry records this as `wheelForward.mode: 'always'` (observed mouse tracking is still required); Claude remains `version-gated`. A stale/false flag after startup cannot authorize forwarding. ⚠️ A strip mode alone is not evidence that a CLI consumes SGR reports. Verify with a real `\x1b[<64;c;rM` write into a live pane before adding a mode here. Hand-encoded SGR taps remain independently gated by `_shouldReportMouseToCli()`; the older #325 no-op measurement describes untracked inline Codex and must not be generalized to newer tracked fullscreen renderers. Shift/local-history opt-outs and xterm's native mouse/alternate-screen handling remain intact. +**Wheel forwarding requires observed mouse tracking: Claude ≥ 2.1.187, tracked Codex, tracked Copilot or tracked Pi** (`terminal-ui.js:_shouldForwardWheelToApp`). The original #227 measurement remains valid for **Codex 0.147.0 inline**: `alternate_on=0`, `mouse_any_flag=0`, growing tmux history, and SGR wheel reports do nothing. Claude 2.1.280 inline similarly reports `alternate_on=0`, `mouse_any_flag=0`; forwarding there swallows gestures, so it keeps local scrollback. Fullscreen Claude (`CLAUDE_CODE_NO_FLICKER=1` or `"tui": "fullscreen"`) enables mouse tracking and accepts reports. **Fresh Codex 0.163.0 fullscreen measurement (2026-10-18, isolated local tmux pane)**: `alternate_on=1`, `mouse_any_flag=1`; one `\x1b[<64;10;10M` report moves the transcript one row upward, and `\x1b[<65;10;10M` restores the original screen. This is capability evidence, not a minimum-version promise: untracked Codex (including a 0.162.0 measurement (2026-10) with `mouse_any_flag=0`) keeps local history or the hollow-pane paging fallback. Codex does not publish the Claude-only CLI version field, so its gate requires the observed flag rather than a Claude version. The registry records this as `wheelForward.mode: 'always'` (observed mouse tracking is still required); Claude remains `version-gated`. That field is the gate's only per-CLI rule: `renderIndexHtml` publishes every CLI's `wheelForward` (disabled ones included, since their sessions keep running; `never` left out) as `window.__codemanWheelForward`, so a custom `clis.json` entry forwards under its own id, and a `minVersion` that is not `MAJOR.MINOR.PATCH` refuses forwarding. A stale/false flag after startup cannot authorize forwarding. ⚠️ A strip mode alone is not evidence that a CLI consumes SGR reports. Verify with a real `\x1b[<64;c;rM` write into a live pane before adding a mode here. Hand-encoded SGR taps remain independently gated by `_shouldReportMouseToCli()`; the older #325 no-op measurement describes untracked inline Codex and must not be generalized to newer tracked fullscreen renderers. Shift/local-history opt-outs and xterm's native mouse/alternate-screen handling remain intact. **Copilot also receives forwarded reports** (1.0.95 measured in tmux: alt screen, `mouse_any_flag=1`): its mouse DECSETs are stripped so a drag selects, which also stops xterm encoding the wheel for it, so `_shouldForwardWheelToApp` sends the same SGR reports by hand while `cliMouseTracking` is true; six `\x1b[<64;…M` reports moved its transcript 18 lines, a phone swipe takes the same gate, and there is NO version gate. diff --git a/docs/cli-registry.md b/docs/cli-registry.md index 23c3d684..b1c4f11c 100644 --- a/docs/cli-registry.md +++ b/docs/cli-registry.md @@ -300,7 +300,7 @@ This matters because it is invisible when it is wrong. `capabilities.privilegedP ## Fields declared for later -`accent`, `capabilities.echo`, `capabilities.wheelForward`, `capabilities.keyboardAccessory` and `capabilities.maxFrameBytes` are **declared but not yet read**. (`shortBadge` was on this list until the CLI management list in Settings started showing it.) They all describe frontend behaviour, and the frontend is deliberately untouched here: `app.js`, `terminal-ui.js` and `styles.css` keep their own hand-authored per-CLI rules, and moving them is its own piece of work verified by a browser/mobile suite the CI gate cannot see. +`accent`, `capabilities.echo`, `capabilities.keyboardAccessory` and `capabilities.maxFrameBytes` are **declared but not yet read**. (`shortBadge` was on this list until the CLI management list in Settings started showing it, and `capabilities.wheelForward` until the browser's wheel gate started reading it, see below.) They all describe frontend behaviour, and the frontend is deliberately untouched here: `app.js`, `terminal-ui.js` and `styles.css` keep their own hand-authored per-CLI rules, and moving them is its own piece of work verified by a browser/mobile suite the CI gate cannot see. Treat those values as **transcribed, not authoritative** — nothing enforces that `echo.policy` matches `_updateLocalEchoState`'s fallthrough, so re-measure before wiring one up. `accent` is the one exception: it was measured against styles.css on 2026-09-21 (method in the comment above `CLAUDE` in `stock.ts`), though nothing keeps it in step with the CSS either. A field that is both wrong and unread is worse than an absent one, because the next reader trusts it; `test/cli-registry-no-id-branching.test.ts` pins the list so it cannot quietly grow, and wiring one up makes its line there fail, which is the direction you want. @@ -308,6 +308,10 @@ Treat those values as **transcribed, not authoritative** — nothing enforces th Everything else in the interface is live, including `overlays.remote` / `overlays.docker`, which back `defaultRemoteCommandForMode()` and `defaultDockerCommandForMode()` directly. Those two used to be hardcoded `Record<…CommandMode, string>` tables duplicating the registry with nothing keeping the two in step; `test/location-overlay-commands.test.ts` pins every resulting command as a literal string. +### Wheel forwarding for a custom full-screen CLI + +`capabilities.wheelForward` reaches the browser as `window.__codemanWheelForward` (id to rule, every CLI whose mode is not `never`, disabled ones included, since disabling a CLI leaves its running sessions open), and `_shouldForwardWheelToApp` in terminal-ui.js reads only that map, so a custom entry gets the same wheel as a stock one under its own id. A full-screen TUI that turns mouse tracking on itself (a wrapper around pi, for example) needs two values in its `clis.json` entry, the ones stock pi carries: `"altScreen": "strip-mux-and-mouse"` (the server strips its mouse DECSETs and publishes `cliMouseTracking`, and a drag selects locally) and `"wheelForward": { "mode": "always" }` (the wheel goes to the CLI as SGR reports while that flag is on). With the custom-entry defaults (`strip-mux-only`, `never`) the DECSETs reach xterm, which handles the wheel only until a tab switch or reload replays the pane without them; from then on the wheel scrolls an empty local buffer. ⚠️ Saving the entry from the Settings form rebuilds its capabilities from those defaults, so both values have to be set again in the file after an edit there. + ## Consumers outside the server Two things need the catalogue but cannot import TypeScript, so `npm run generate:cli-catalog` diff --git a/src/config/cli-registry/types.ts b/src/config/cli-registry/types.ts index 00cff24d..6411871d 100644 --- a/src/config/cli-registry/types.ts +++ b/src/config/cli-registry/types.ts @@ -596,10 +596,14 @@ export interface CliCapabilities { * Forwarding the wheel to the CLI's own transcript. 'never' keeps local scrollback; * 'version-gated' forwards from `minVersion` on; 'always' forwards at any version. Either * forwarding mode applies only while the CLI has mouse tracking on (`cliMouseTracking`). + * Read by the browser's gate (`_shouldForwardWheelToApp` in terminal-ui.js) through + * `window.__codemanWheelForward`, which the server builds from this field for every CLI + * whose mode is not `never`, disabled ones included (their running sessions stay open). * - * ⚠️ Declared only: nothing reads this field yet (see DECLARED-FOR-LATER below). The browser's - * gate is `_shouldForwardWheelToApp` in terminal-ui.js, which keeps its own hand-written - * per-CLI rules, so changing a value here changes nothing until that gate is changed too. + * ⚠️ `cliMouseTracking` is only ever set for a CLI whose mouse DECSETs the server strips + * (`altScreen: 'strip-full'` or `'strip-mux-and-mouse'`), so a forwarding mode on any other + * `altScreen` never forwards: xterm keeps the DECSETs and encodes the wheel itself, until a + * replay drops its mouse mode. */ wheelForward: { mode: 'never' | 'version-gated' | 'always'; minVersion?: string }; /** @@ -1009,14 +1013,15 @@ export interface CliOverlays { /** * ⚠️ DECLARED-FOR-LATER: fields no code reads yet. * - * `accent`, `overlays.credStore`, `capabilities.echo`, `capabilities.wheelForward`, - * `capabilities.keyboardAccessory` and `capabilities.maxFrameBytes` all describe FRONTEND + * `accent`, `overlays.credStore`, `capabilities.echo`, `capabilities.keyboardAccessory` and + * `capabilities.maxFrameBytes` all describe FRONTEND * behaviour, and most of the frontend is deliberately untouched by the change that introduced * this registry — `app.js`, `terminal-ui.js`, `styles.css` and friends keep their own * hand-authored per-CLI rules, and moving them is its own piece of work with its own way of * being verified (a mobile/browser suite the CI gate cannot see). `shortBadge` graduated out of * this list (docs/cli-enable-disable-plan.md, Phase 2): `GET /api/clis` reads it for the - * CLI-management Settings list. + * CLI-management Settings list, and so did `capabilities.wheelForward`, which the browser's wheel + * gate reads through `window.__codemanWheelForward`. * * They are declared now because each entry should describe its CLI completely, and because * transcribing them while the hand-written source is still on screen is when the values are diff --git a/src/web/public/terminal-ui.js b/src/web/public/terminal-ui.js index eab9a73e..0031bd49 100644 --- a/src/web/public/terminal-ui.js +++ b/src/web/public/terminal-ui.js @@ -6016,12 +6016,16 @@ Object.assign(CodemanApp.prototype, { // True when a parsed CLI version string ('2.1.187' — banner-parsed on the // server, delivered via session:cliInfo / SessionState.cliVersion) is known // AND >= the minimum. Unknown or unparseable versions return false so - // callers keep the conservative behavior. + // callers keep the conservative behavior, and so does an unparseable + // minimum: it can come from a user's clis.json (`wheelForward.minVersion`). _cliVersionAtLeast(version, minimum) { - if (typeof version !== 'string') return false; - const parts = version.trim().replace(/^v/, '').split('.').map(Number); - if (parts.length !== 3 || parts.some((n) => !Number.isFinite(n))) return false; - const min = minimum.split('.').map(Number); + const parse = (v) => { + const m = typeof v === 'string' ? /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v.trim()) : null; + return m ? m.slice(1).map(Number) : null; + }; + const parts = parse(version); + const min = parse(minimum); + if (!parts || !min) return false; for (let i = 0; i < 3; i++) { if (parts[i] !== min[i]) return parts[i] > min[i]; } @@ -6081,24 +6085,26 @@ Object.assign(CodemanApp.prototype, { if (mode && mode !== 'none') return false; const session = this.sessions?.get(target.sessionId || this.activeSessionId); const sessionMode = session?.mode || 'claude'; - // GitHub Copilot CLI (and pi, fullscreen by default) scrolls its own transcript on SGR wheel - // reports (checked with xterm encoding them natively). Their mouse DECSETs are stripped - // server-side so a drag selects locally (strip-mux-and-mouse), which also means xterm no longer - // encodes the wheel: send the same reports by hand, but only while the CLI is actually tracking - // the mouse. Not gated on a version. On Copilot a stale-false flag falls through to the - // PageUp/PageDown fallback like claude's; pi has none on purpose (the `transcriptPageKeys` note - // in stock.ts), so there the wheel does nothing until the flag is back. - if (sessionMode === 'copilot' || sessionMode === 'pi') return session?.cliMouseTracking === true; - if (sessionMode !== 'claude' && sessionMode !== 'codex') return false; - if (sessionMode === 'claude' && !this._cliVersionAtLeast(session?.cliVersion, '2.1.187')) return false; - // Only while Claude or Codex is actually listening for the mouse. Claude's - // inline renderer (2.1.280 measured: alternate_on=0, mouse_any_flag=0), like - // older inline Codex, keeps its transcript in real scrollback; SGR reports are - // ignored, so forwarding made every swipe and wheel tick dead. Fullscreen - // (CLAUDE_CODE_NO_FLICKER=1, or "tui": "fullscreen" in ~/.claude/settings.json) - // turns on alt-screen + mode 1003/1006, which the server records as - // cliMouseTracking. A stale-false flag after a server restart falls through - // to _maybePageCliTranscript, so it never goes dead. + // Which CLIs scroll their own transcript on SGR wheel reports is the registry's + // `wheelForward` rule, published by renderIndexHtml as `window.__codemanWheelForward` + // (id -> rule, `never` left out; a page rendered without the map forwards nothing), so a + // custom clis.json entry shaped like pi forwards under its own id. Stock: claude from + // 2.1.187 (older versions take the wheel as menu navigation), codex, copilot and pi always. + // Their mouse DECSETs are stripped server-side (a drag selects locally), so xterm never + // encodes the wheel for them and the reports are sent by hand. + const rule = window.__codemanWheelForward?.[sessionMode]; + if (!rule || (rule.mode !== 'always' && rule.mode !== 'version-gated')) return false; + if (rule.mode === 'version-gated' && !this._cliVersionAtLeast(session?.cliVersion, rule.minVersion)) return false; + // Only while the CLI is actually listening for the mouse. Claude's inline renderer + // (2.1.280 measured: alternate_on=0, mouse_any_flag=0), like older inline Codex and pi's + // `tuiMode: regular`, keeps its transcript in real scrollback; SGR reports are ignored, so + // forwarding made every swipe and wheel tick dead. Fullscreen (CLAUDE_CODE_NO_FLICKER=1, or + // "tui": "fullscreen" in ~/.claude/settings.json; pi's default since 1.0.0) turns on + // alt-screen + mouse tracking, which the server records as cliMouseTracking. That flag is + // what survives a tab switch or reload, where xterm's own mouse mode does not. A stale-false + // flag falls through to _maybePageCliTranscript (PageUp/PageDown for a CLI declaring + // `transcriptPageKeys`); pi declares none on purpose (the note in stock.ts), so there the + // wheel does nothing until the flag is back. if (session?.cliMouseTracking !== true) return false; // Deliberately NOT gated on _terminalViewportAtBottom(). It used to be, so // that leaving the bottom handed the wheel back to local scrollback and both diff --git a/src/web/server.ts b/src/web/server.ts index c1acda86..e4238eb9 100644 --- a/src/web/server.ts +++ b/src/web/server.ts @@ -2133,6 +2133,19 @@ export class WebServer extends EventEmitter { '</head>', () => `<script>window.__codemanKeyboardHoldModes=${JSON.stringify(keyboardHoldClis)};</script>\n</head>` ); + // Which run modes take the wheel as SGR reports while they track the mouse + // (`_shouldForwardWheelToApp`), keyed by id with the `wheelForward` rule itself, so a + // custom clis.json entry shaped like pi forwards under its own id. `never` is left out. + // Disabled entries are kept (`listClis`, not `enabledClis`): disabling a CLI never ends + // its running sessions, and their wheel must keep working across a reload. + // `minVersion` is a free string a user's clis.json sets, hence the script escaper. + const wheelForwardClis = Object.fromEntries( + listClis() + .filter((entry) => entry.capabilities.wheelForward.mode !== 'never') + .map((entry) => [entry.id, entry.capabilities.wheelForward]) + ); + const wheelForwardJson = escapeScriptJson(JSON.stringify(wheelForwardClis)); + html = html.replace('</head>', () => `<script>window.__codemanWheelForward=${wheelForwardJson};</script>\n</head>`); if (!soloSessionId && process.env.CODEMAN_GESTURE === '1') { html = html.replace('</head>', () => `<script>window.__codemanGestureAvailable=true;</script>\n</head>`); if (settings.gestureControlEnabled === true) { diff --git a/test/cli-registry-no-id-branching.test.ts b/test/cli-registry-no-id-branching.test.ts index 99f818d6..9714ac66 100644 --- a/test/cli-registry-no-id-branching.test.ts +++ b/test/cli-registry-no-id-branching.test.ts @@ -435,7 +435,6 @@ describe('declared-for-later fields', () => { const DECLARED_FOR_LATER = [ 'accent', 'capabilities.echo', - 'capabilities.wheelForward', 'capabilities.keyboardAccessory', 'capabilities.maxFrameBytes', // The Docker credential-seeding path still reads its own CRED_STORES table: this shape diff --git a/test/render-index-html.test.ts b/test/render-index-html.test.ts index fb880257..27e9a8d3 100644 --- a/test/render-index-html.test.ts +++ b/test/render-index-html.test.ts @@ -181,6 +181,78 @@ describe('WebServer.renderIndexHtml', () => { } }); + it('injects the wheelForward rules of every CLI that forwards, custom and disabled entries included', async () => { + // A custom clis.json entry shaped like pi (its mouse DECSETs stripped, wheel forwarded) + // must reach the browser's gate by its own id, and every `never` stays out. A DISABLED + // entry stays in: disabling a CLI never ends its running sessions, so a fullscreen copilot + // tab opened before the switch still needs its wheel after a reload (and an entry enabled + // after the page loaded already has its rule). A solo window scrolls a terminal too, so + // it gets the same map. + const path = dataPath('clis.json'); + mkdirSync(dirname(path), { recursive: true }); + const custom = { + label: 'PiD', + shortBadge: 'PL', + accent: '#6b7280', + enabled: true, + order: 120, + kind: 'agent', + discovery: { binaries: ['pi-locked'], searchDirs: [], install: { command: {} } }, + launch: { params: {}, variants: [{ id: 'default', args: [{ lit: 'pi-locked' }] }] }, + env: { exports: [], unset: [], tmuxSetenvKeys: [], dockerExecEnvNames: [], allowedPrefixes: [], allowedKeys: [] }, + capabilities: { + external: true, + requiresMux: true, + hooks: 'none', + transcript: 'none', + altScreen: 'strip-mux-and-mouse', + echo: { policy: 'buffer', anchor: { kind: 'none' } }, + wheelForward: { mode: 'always' }, + keyboardAccessory: 'agent', + privilegedCommandGate: false, + startMode: 'interactive', + stripInkBloat: false, + ralph: false, + respawn: false, + effort: false, + agentSkillInjection: false, + statusLineTelemetry: false, + model: { source: 'none' }, + privilegedParams: [], + privilegedEnvKeys: [], + gates: {}, + customModelInjection: { kind: 'unsupported' }, + }, + overlays: {}, + }; + writeFileSync( + path, + JSON.stringify({ schemaVersion: 1, clis: { copilot: { enabled: false }, 'pi-locked': custom } }), + { + mode: 0o600, + } + ); + reloadCliRegistry(); + try { + for (const solo of [undefined, 'sess-123']) { + const { server } = makeServer({}); + const html = await render(server, solo); + const match = html.match(/window\.__codemanWheelForward=(\{[^<]*\});/); + expect(match, String(solo)).not.toBeNull(); + expect(JSON.parse(match![1])).toEqual({ + claude: { mode: 'version-gated', minVersion: '2.1.187' }, + codex: { mode: 'always' }, + pi: { mode: 'always' }, + copilot: { mode: 'always' }, + 'pi-locked': { mode: 'always' }, + }); + } + } finally { + writeFileSync(path, JSON.stringify({ clis: {} }, null, 2), { mode: 0o600 }); + reloadCliRegistry(); + } + }); + it('injects the keyboard-hold modes from the keyboardHold capability: inline Claude, never full-height codex', async () => { for (const solo of [undefined, 'sess-123']) { const { server } = makeServer(); diff --git a/test/server-index-title.test.ts b/test/server-index-title.test.ts index b1cb7379..ed3a5ae8 100644 --- a/test/server-index-title.test.ts +++ b/test/server-index-title.test.ts @@ -117,7 +117,9 @@ describe('WebServer index.html <title> templating (#82)', () => { // Likewise the page-key mode list: an array, possibly empty, always injected. .replace(/<script>window\.__codemanTranscriptPageKeys=\[.*?\];<\/script>\n/, '') // And the keyboard-hold mode list, built the same way. - .replace(/<script>window\.__codemanKeyboardHoldModes=\[.*?\];<\/script>\n/, ''); + .replace(/<script>window\.__codemanKeyboardHoldModes=\[.*?\];<\/script>\n/, '') + // And the wheel-forwarding rules: an object keyed by run mode, always injected. + .replace(/<script>window\.__codemanWheelForward=\{.*?\};<\/script>\n/, ''); const beforeTitle = rawTemplate.split('<title>Codeman')[0]; const afterTitle = rawTemplate.split('Codeman')[1]; expect(html.startsWith(beforeTitle)).toBe(true); diff --git a/test/terminal-scroll-routing.test.ts b/test/terminal-scroll-routing.test.ts index 990f3454..26bb1cf9 100644 --- a/test/terminal-scroll-routing.test.ts +++ b/test/terminal-scroll-routing.test.ts @@ -28,8 +28,19 @@ import { STOCK_CLIS } from '../src/config/cli-registry/stock.js'; */ const PAGE_KEY_MODES = STOCK_CLIS.filter((e) => e.capabilities.transcriptPageKeys === true).map((e) => e.id); +/** + * The run modes that take the wheel as SGR reports, read off the shipped registry the way + * the server builds `__codemanWheelForward` (every `wheelForward` other than `never`). + */ +const WHEEL_FORWARD = Object.fromEntries( + STOCK_CLIS.filter((e) => e.capabilities.wheelForward.mode !== 'never').map((e) => [e.id, e.capabilities.wheelForward]) +); + function loadTerminalUiHarness( - windowGlobals: Record = { __codemanTranscriptPageKeys: PAGE_KEY_MODES } + windowGlobals: Record = { + __codemanTranscriptPageKeys: PAGE_KEY_MODES, + __codemanWheelForward: WHEEL_FORWARD, + } ) { const CodemanApp = function CodemanApp(this: any) {}; const logs: string[] = []; @@ -927,6 +938,96 @@ describe('pi wheel forwarding (fullscreen by default since 1.0.0)', () => { }); }); +describe('wheel forwarding read from the injected wheelForward map, for any CLI id', () => { + // A custom CLI (clis.json, e.g. a pi wrapper under its own id) that strips its mouse + // DECSETs gets `cliMouseTracking` like pi, but the gate used to name copilot and pi by id, + // so its wheel hit an empty local buffer after every tab switch or reload. + function customApp( + map: Record | undefined, + session: { mode: string; cliMouseTracking?: boolean; cliVersion?: string } + ) { + const globals: Record = { __codemanTranscriptPageKeys: PAGE_KEY_MODES }; + if (map) globals.__codemanWheelForward = map; + const { app } = loadTerminalUiHarness(globals); + app.activeSessionId = 'sess-1'; + app.sessions = new Map([['sess-1', session]]); + app.terminal = { + rows: 36, + modes: { mouseTrackingMode: 'none' }, + buffer: { active: { type: 'normal', viewportY: 0, baseY: 0, length: 36 } }, + }; + return app; + } + + it('forwards a custom id the map lists as always, only while it tracks the mouse', () => { + const map = { 'pi-locked': { mode: 'always' } }; + const tracking = customApp(map, { mode: 'pi-locked', cliMouseTracking: true }); + expect(tracking._shouldForwardWheelToApp({ shiftKey: false })).toBe(true); + expect(tracking._shouldForwardWheelToApp({ shiftKey: true })).toBe(false); + expect(customApp(map, { mode: 'pi-locked', cliMouseTracking: false })._shouldForwardWheelToApp({})).toBe(false); + expect(customApp(map, { mode: 'pi-locked' })._shouldForwardWheelToApp({})).toBe(false); + }); + + it('applies a version-gated rule to a custom id: at or above minVersion only, unknown version never', () => { + const map = { 'my-cli': { mode: 'version-gated', minVersion: '2.0.0' } }; + const at = (cliVersion?: string) => + customApp(map, { mode: 'my-cli', cliMouseTracking: true, cliVersion })._shouldForwardWheelToApp({}); + expect(at('1.9.9')).toBe(false); + expect(at('2.0.0')).toBe(true); + expect(at('2.0.1')).toBe(true); + expect(at(undefined)).toBe(false); + }); + + it('a version-gated rule whose minVersion is not three numbers forwards nothing, whatever the CLI version', () => { + // The schema takes any string up to 20 characters. A minimum that cannot be read as + // MAJOR.MINOR.PATCH must refuse, the conservative answer an unreadable session version gets. + for (const minVersion of ['', '0', '2.0', '1.2.3.4', '0.bad.999', 'x.y.z', '2..0', '+2.0.0', '0x1.0.0']) { + const app = customApp( + { 'my-cli': { mode: 'version-gated', minVersion } }, + { mode: 'my-cli', cliMouseTracking: true, cliVersion: '9.9.9' } + ); + expect(app._shouldForwardWheelToApp({}), JSON.stringify(minVersion)).toBe(false); + } + // A well-formed minimum keeps working, a leading `v` and surrounding spaces included. + for (const minVersion of ['9.9.9', 'v2.0.0', ' 2.0.0 ']) { + const app = customApp( + { 'my-cli': { mode: 'version-gated', minVersion } }, + { mode: 'my-cli', cliMouseTracking: true, cliVersion: '9.9.9' } + ); + expect(app._shouldForwardWheelToApp({}), JSON.stringify(minVersion)).toBe(true); + } + }); + + it('a version-gated rule with no minVersion (the schema allows it) forwards nothing and does not throw', () => { + const app = customApp( + { 'my-cli': { mode: 'version-gated' } }, + { mode: 'my-cli', cliMouseTracking: true, cliVersion: '9.9.9' } + ); + expect(app._shouldForwardWheelToApp({})).toBe(false); + }); + + it('never forwards an id the map leaves out, and nothing at all from a page rendered without the map', () => { + expect( + customApp( + { 'pi-locked': { mode: 'always' } }, + { mode: 'other', cliMouseTracking: true } + )._shouldForwardWheelToApp({}) + ).toBe(false); + for (const mode of ['claude', 'codex', 'copilot', 'pi']) { + expect( + customApp(undefined, { mode, cliMouseTracking: true, cliVersion: '9.9.9' })._shouldForwardWheelToApp({}), + mode + ).toBe(false); + } + }); + + it('a map entry of mode never forwards, even for a stock id', () => { + expect( + customApp({ pi: { mode: 'never' } }, { mode: 'pi', cliMouseTracking: true })._shouldForwardWheelToApp({}) + ).toBe(false); + }); +}); + describe('the paging gates asked for another pane (a TerminalTile)', () => { it('exports the paging math, and the primary pane runs on it', () => { const { app, sent, windowRef } = hollowApp(); diff --git a/test/terminal-tile-scroll.test.ts b/test/terminal-tile-scroll.test.ts index fff39738..006490ca 100644 --- a/test/terminal-tile-scroll.test.ts +++ b/test/terminal-tile-scroll.test.ts @@ -49,6 +49,11 @@ const fetchMock = vi.fn(); */ const PAGE_KEY_MODES = STOCK_CLIS.filter((e) => e.capabilities.transcriptPageKeys === true).map((e) => e.id); +/** The wheel-forwarding rules, read off the registry as the server builds `window.__codemanWheelForward`. */ +const WHEEL_FORWARD = Object.fromEntries( + STOCK_CLIS.filter((e) => e.capabilities.wheelForward.mode !== 'never').map((e) => [e.id, e.capabilities.wheelForward]) +); + /** * The clock both panes read gesture gaps from (`performance.now()`). Real time by * default; a test that needs a pause or a burst moves it by hand. @@ -62,6 +67,7 @@ function loadContext() { removeEventListener: vi.fn(), CodemanBase: { base: '' }, __codemanTranscriptPageKeys: PAGE_KEY_MODES, + __codemanWheelForward: WHEEL_FORWARD, }; const context = vm.createContext({ console: { ...console, log: vi.fn(), debug: vi.fn() }, diff --git a/test/terminal-touch-tap.test.ts b/test/terminal-touch-tap.test.ts index 695f4060..77551a25 100644 --- a/test/terminal-touch-tap.test.ts +++ b/test/terminal-touch-tap.test.ts @@ -2,6 +2,12 @@ import { readFileSync } from 'node:fs'; import { resolve } from 'node:path'; import vm from 'node:vm'; import { describe, expect, it, vi } from 'vitest'; +import { STOCK_CLIS } from '../src/config/cli-registry/stock.js'; + +/** The wheel-forwarding rules, read off the registry as the server builds `window.__codemanWheelForward`. */ +const WHEEL_FORWARD = Object.fromEntries( + STOCK_CLIS.filter((e) => e.capabilities.wheelForward.mode !== 'never').map((e) => [e.id, e.capabilities.wheelForward]) +); function loadTerminalUiHarness() { const CodemanApp = function CodemanApp(this: any) {}; @@ -10,7 +16,7 @@ function loadTerminalUiHarness() { let activeElement: unknown = null; // The module hangs its constants off window (CodemanTerminalInput) and the URL branch of // the link provider opens through window.open, so tests need a handle on the same object. - const windowRef: Record = {}; + const windowRef: Record = { __codemanWheelForward: WHEEL_FORWARD }; const context = vm.createContext({ window: windowRef, document: {