Skip to content

feat(gpui): a bindable clear-screen action for the terminal - #653

Open
zher52 wants to merge 52 commits into
Kuddev:mainfrom
zher52:feat/gpui-clear-terminal-action
Open

zher52 wants to merge 52 commits into
Kuddev:mainfrom
zher52:feat/gpui-clear-terminal-action

Conversation

@zher52

@zher52 zher52 commented Oct 15, 2026

Copy link
Copy Markdown

Result / 用户结果

Users can now bind a clear-screen shortcut themselves. The GPUI shell had no clear-screen action at all: the macOS config table's ⌘K → ClearHistory default executes only in the legacy shell, so after unbinding the Shell picker row ⌘K stayed inert and no settings row offered clear screen — the known limitation recorded in the 2026-09-21 macOS command-key aliases note ("⌘K after unbinding does not clear the screen").

Settings → Key Bindings gains a Terminal-group "Clear screen / 清屏" row. No default shortcut changes on any platform: ⌘K stays on the Shell picker, and the feature is opt-in through a user keybind= row (e.g. keybind=cmd+k:ClearHistory) that applies without restart.

Design / 设计边界

  • Responsibility and affected modules: gpui_shell/workspace/keyboard_bindings.rs maps config::Action::ClearHistory to a new ClearTerminal workspace action (alongside the SelectTab/QuitApp adapter actions); gpui_shell/terminal/view.rs implements the pane-level clear; display/keymap.rs owns the editable row; catalogs add common.clear_screen. The existing keymap authority (config table + MACOS_COMMAND_ALIASES unbind vocabulary) is reused unchanged.
  • After an instant app-side wipe of the viewport and scrollback (ClearMode::All + Saved), the action branches on the pane's foreground state:
    • Shell at a prompt (OSC 133 nebula_prompt_active): writes ^L to that pane's PTY so the shell repaints its prompt on the fresh screen with its line state in sync (same visible behavior as the legacy ⌘K pair).
    • Command running: no PTY write — a queued ^L would clear the screen a second time when the command exits, wiping the output produced in between. The view moves the terminal cursor home app-side; sequential output continues from the top.
    • Alternate screen (vim/less): no-op; ^L is a redraw there, not a clear.
  • Dependency, data-format, threading, or lifetime changes: none. ^L is a direct PTY write on the focused pane, not a user-input event, so broadcast fan-out is untouched.
  • Compatibility and migration/fallback: the legacy shell is unaffected; Windows/Linux gain an unbound row; without shell integration the prompt probe reads false and clears take the cursor-home branch (the next Enter restores the prompt). Decision record: architecture/notes/nebula_app/gpui_shell/2026-10-14-terminal-clear-action.md.

Evidence / 验证依据

  • cargo fmt --all -- --check; cargo check -p nebula --bin pebrel --features gpui-shell --tests --locked (0 errors); keyboard_bindings 25 passed (including the gpui-test-support dispatch module), display::keymap 46 passed, settings_pane 24 passed, i18n contract 24 passed, nebula-settings 99 passed, file_line_budget 2 passed; python3 scripts/check_architecture.py --base <merge-base 13659697> passes with budgets unchanged — the new action lives in keyboard_bindings.rs specifically because workspace.rs sits at its ratcheted 2773-line budget.
  • Regression tests: clear_history_maps_to_the_clear_terminal_action fails without the adapter arm (a user-bound clear must win over the static ⌘K picker binding while Ctrl+K stays on the picker); clear_screen_shortcut_dispatches_and_stays_out_of_the_terminal_stream fails without the dispatch path (the key must not enter the PTY input stream); clear_screen_is_editable_and_localized_through_the_typed_message fails without the catalog entries.
  • UI changes: exercised manually on macOS 26 x64 (debug build, isolated PEBREL_CONFIG_DIR): prompt clear repaints at the top-left, clear during a running command keeps output flowing from the top, vim is untouched, the Shell picker keeps Ctrl+K, and the binding survives restart. Platform/feature coverage limitation: Windows/Linux paths rely on the shared keymap tests and CI; no native manual run there.
  • Not a hot-path change (keystroke-triggered cold path).

Required Review / 必须确认

  • I followed CONTRIBUTING.md, docs/architecture.md, and docs/project-constraints.md.
  • I split responsibilities, not arbitrary line ranges; no duplicate behavior authority was added.
  • python3 scripts/check_architecture.py --base <PR-base-commit> passes; budgets were not inflated to fit the change.
  • Tests cover success and failure; platform/feature coverage limitations are stated.
  • New messages use typed i18n IDs and matching placeholders; untranslated content has an explicit fallback.

@zher52
zher52 requested a review from Kuddev as a code owner October 15, 2026 06:18
@zher52
zher52 force-pushed the feat/gpui-clear-terminal-action branch 3 times, most recently from 1b43c7e to 2bec420 Compare October 15, 2026 07:56
The GPUI shell had no clear-screen action at all: the macOS config
table's ⌘K ClearHistory default executes only in the legacy shell, so
after unbinding the Shell picker row ⌘K stayed inert and no settings
row offered clear screen — the known limitation recorded in the
2026-09-21 macOS command-key aliases note.

Map config::Action::ClearHistory to a new ClearTerminal workspace
action and expose it as a Terminal-group row on the settings keymap
page. No default shortcut changes on any platform: ⌘K stays on the
Shell picker, and the feature is opt-in through a user keybind= row
that applies without restart. After an instant app-side wipe of the
viewport and scrollback, the action branches on the pane's foreground
state: at a prompt it writes ^L to the pane's PTY so the shell
repaints its prompt on the fresh screen; while a command runs it
moves the terminal cursor home app-side so sequential output
continues from the top; on the alternate screen it does nothing. The
row label uses a typed i18n message (zh/en catalogs, English fallback
elsewhere).

Adds adapter, dispatch-probe and label regressions, and the decision
note architecture/notes/nebula_app/gpui_shell/2026-10-14-terminal-clear-action.md
(recording why pre-existing files need one re-record after upgrading,
and why an app-side cursor-home and an unconditional ^L were rejected).
…trol group

The platform-cfg ratchet counts cfg! macros outside platform/ and the
clear-screen adapter regression added one. Build the static default
keymap identically on every platform instead: the precedence being
tested is source-tier, not platform-specific, and the macOS-only
registration behavior stays guarded by its own runtime-platform test.
…policy

Upstream cf77ccd releases plain Control-character workspace defaults on
macOS, so the Shell picker's Ctrl+K default may legitimately be absent.
Derive the Ctrl+K expectation from the control group's own shape instead
of asserting it unconditionally; the user clear binding must neither
steal a present default nor resurrect a released key.
@zher52
zher52 force-pushed the feat/gpui-clear-terminal-action branch from 10520b6 to 94cdb39 Compare October 19, 2026 02:35
@Kuddev

Kuddev commented Oct 19, 2026

Copy link
Copy Markdown
Owner

Added focused maintainer fixes at 92516fe and merged the current main baseline. The actual TerminalView tests now cover prompt-only Ctrl+L delivery, no PTY input while a command runs, cursor-home/history/selection clearing, and an unchanged alternate screen plus primary history. The macOS keymap regression preserves Command+K ownership for the Shell picker; the stale note has been corrected.

Windows validation: cargo test --locked -p nebula --bin pebrel --features gpui-test-support clear_screen -- --test-threads=1 passed all 4 matched tests. Architecture and whitespace checks passed. The previous macOS failure was in the unchanged ai_hook::unix::tests::local_hook_socket_routes_identity_and_releases_its_private_directory shutdown call (ENOTCONN); the new head is now running the full native matrix, so this is not yet a claim that all platform checks pass.

The action is user-triggered: it reuses the terminal's existing bounded grid/history clear operations and adds one prompt-state branch, with no polling or background work. Native shell redraw acceptance remains distinct from the standalone PTY regression fixtures.

Kuddev
Kuddev previously approved these changes Oct 19, 2026

@Kuddev Kuddev left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed db35ebd. All five actual Native tests jobs and both macOS release workspace checks passed on this head. The clear action now reaches the focused GPUI terminal; focused regression cases verify prompt-only Ctrl+L, running-command cursor reset without PTY input, cleared viewport/history/selection, and an unchanged alternate screen. The shortcut policy retains Command+K for the macOS Shell picker, with Clear screen unbound until explicitly assigned.

This is a user-triggered operation using the existing grid/history clear primitives, with no polling, extra subprocess, or per-frame work. Windows focused tests and architecture checks passed locally. The standalone PTY fixture proves dispatched bytes and terminal state; it is not a claim that every third-party shell redraw behavior was exercised.

@zher52

zher52 commented Oct 22, 2026

Copy link
Copy Markdown
Author

The Full native tests failure on the previous head was the Windows-only nebula_terminal::tty::windows::test::bash_input::git_bash_wrapped_input_can_be_fully_erased_in_byte_and_utf8_locales case. It is not touched by this PR — the branch changes nothing under nebula_terminal/, so the test and the code under test in this branch are byte-identical to upstream main, where the full Windows native suite is green on the latest runs (e.g. the merge of #694). The test drives a real Git Bash subprocess through a PTY with 5 ms polling and fixed 2 s / 10 s capture windows, so it is timing-sensitive on shared runners; the failure output shows its own Ctrl-L diagnostic capture reporting a mid-redraw state.

Re-running via an empty push; if it fails again consistently, it reproduces independently of this branch and likely needs a look upstream.

@zher52

zher52 commented Oct 22, 2026

Copy link
Copy Markdown
Author

The re-run failed on the same case: nebula_terminal::tty::windows::test::bash_input::git_bash_wrapped_input_can_be_fully_erased_in_byte_and_utf8_locales, panicking at bash_input.rs:142, both times on the windows-11-arm native runner (run 1, run 2); the windows-2022 native job passed in the same runs, and the remaining red jobs are the aggregate policy reports.

This branch changes nothing under nebula_terminal/, so the failing test and the code under test are identical to upstream main, where the Windows native suites are green on the latest runs (including windows-11-arm, e.g. the #694 merge). The test drives a real Git Bash subprocess through a PTY with fixed 2 s capture and 10 s wait windows; on windows-11-arm the x64 Git Bash binary runs under emulation, which makes those deadlines sensitive to runner load.

Since PR authors cannot re-run upstream jobs, could a maintainer re-run the failed job once? If it keeps failing there while main stays green, the flake reproduces independently of this PR and likely needs a look at the test's timing budget on emulated runners — happy to help dig.

@zher52

zher52 commented Oct 27, 2026

Copy link
Copy Markdown
Author

Friendly ping for a re-review. Your Oct 19 approval was dismissed as stale by the follow-up pushes (the repo requires approval of the latest reviewable push), and PR authors cannot re-request reviewers, so this comment is the nudge.

The branch is now conflict-free against main (merged through #694-era changes, v2.2.2 and v2.3.0 included) and every check is green on the latest head (4022ff2). Relative to the reviewed db35ebd, the behavioral diff is small: main's keymap refactor replaced action_label with the action_message typed-message table and the Clear screen row joined that table; the terminal clear semantics and the regressions are unchanged. Details in the merge commit and the decision note.

@Kuddev Kuddev left a comment •

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

复核了 554235a8。F9 重绘与 F11 粘贴已拆开;此前 Bash 的普通后缀反例,以及 zsh 字符串宏和同名 widget 的反例均已解决。33 项 Bash/zsh 回归测试通过。两个真实 PTY 用例和一处源码检查仍发现绑定所有权误判:

  1. Bash:匹配子串仍可能认错键。 grep -qF 会把另一行里的固定子串当成完整绑定。在已有重绘声明的会话中运行:

    bind '"\C-x\"\e[46~": clear-screen'
    bind '"\e[46~": "QUOTED-KEY-MACRO"'

    下一提示符仍声明重绘,发送目标键实际插入 QUOTED-KEY-MACRO。临时改成 grep -qxF 后,同一 PTY 用例正确撤销声明,相关的 3 项 Bash 测试也通过。

  2. zsh:提示符期间切换 Vi 键表后仍会发送原来的键。 bindkey 查询 在提示符处验证主键表。在真实 PTY 中,viins 的 \e[46~ 绑定 .clear-screen,vicmd 的同一键绑定用户 widget。提示符先声明重绘,输入时切到 vicmd 没有撤销;此时发送重绘键实际调用用户 widget。请覆盖同一提示符内的键表切换:当前绑定无法确认时撤销或不声明,并保留用户的 vicmd 绑定。

  3. PowerShell:Function 是显示用的描述,不能证明处理程序是内建函数。 安装和复查 都接受 Function == 'ClearScreen'。PSReadLine 2.3.6 接受脚本块的自定义 BriefDescription,并将该描述写入查询结果的 Function,也用它计算 Group。按这条代码路径,-ScriptBlock { … } -BriefDescription ClearScreen 在启动前可能被覆盖,启动后重新绑定则会继续被当成原生重绘。源码路径和下方实测均指向这一问题;请补上同名脚本块在启动前和重新绑定后的测试。

补充实测(同一提交 554235a8): 在 Linux 真 PTY 中使用 PowerShell 7.6.8 / PSReadLine 2.4.5。启动前确认 Ctrl+Shift+F9 已绑定描述为 ClearScreen 的用户脚本块,集成启动后仍覆盖成原生清屏。启动后再把 F9 绑回该脚本块,下一提示符仍声明支持重绘;发送 Ctrl+Shift+F9 实际向编辑缓冲区插入了脚本块的 USER-F9 文本。

该提交已有的四项 PowerShell 重绘和粘贴用例均通过;同名脚本块是它们没覆盖的反例。

…tches

The Bash probe matched the clear-screen entry as a fixed substring, so a
lookalike binding line that merely contains it kept a revoked chord
announced while a quoted macro on the key fired user text. The probe now
matches the complete binding line.

The zsh probe validated only the prompt-time keymap; switching to vicmd
inside the same prompt could route the byte into a user widget while the
redraw capability stayed announced. Ownership now requires the built-in
widget (or an inert unbound key) in every keymap one prompt can reach;
the probe only reads, so user bindings stay untouched.

PowerShell accepted Function == ClearScreen as ownership, but Function is
PSReadLine's display description: a scriptblock with BriefDescription
ClearScreen could take the chord before startup or rebind it afterwards
and still count as native redraw. The installation now tags its binding
with a Description token and both the startup probe and the per-prompt
re-check match that token; anything else on the chord is user-owned and
stays untouched.
@zher52

zher52 commented Nov 12, 2026

Copy link
Copy Markdown
Author

All three points are addressed on head 90860de (branch also merged current main first):

  1. Bash: the probe now matches the complete binding line. grep -qF became grep -qxF, so a lookalike line that merely contains "\\e[46~": clear-screen (your \\C-x\\"\\e[46~ repro) no longer satisfies the probe once the real entry is gone. The rebind regression grew exactly your PTY case: the containment decoy plus bind '"\\e[46~": "QUOTED-KEY-MACRO"' must revoke the announcement and the macro must still fire into the line.

  2. zsh: ownership now holds in every keymap one prompt can reach. __pebrel_redraw_owned still requires .clear-screen in the current keymap, then enumerates bindkey -l and queries \\e[46~ per keymap: the built-in widget (or unbound — an unbound key is inert, no user code runs) keeps ownership, while a string macro or a user widget in any keymap — your vicmd case included — revokes it. The probe only reads, so the user's vicmd binding stays. New regression test_ssh_zsh_redraw_keymap_switch_in_the_same_prompt_revokes: a vi-mode session with the chord bound to a user widget in vicmd must never announce the token (only the empty revocation), and ESC mid-line must route the chord into the user's widget.

  3. PowerShell: identity is the binding we installed, not the Function display. The installation tags its native ClearScreen binding with a Description token (PebrelRedraw:<shell token>), drops the Function -eq 'ClearScreen' acceptance, and Test-PebrelRedrawBinding requires both Function -eq 'ClearScreen' and the current token — -BriefDescription ClearScreen on a scriptblock no longer proves anything, and a chord held by anything else is left untouched as user-owned. Two tests cover your scenarios: a same-name scriptblock bound before startup (not overwritten, never advertised, keeps firing USER-F9) and the same scriptblock bound after startup (empty revocation on the next prompt, USER-F9 still inserted).

Environment note: this machine has zsh but neither pwsh nor Bash ≥ 4, so the zsh keymap-switch suite ran locally (completion editor 21 tests + shell suites 44, green); the Bash-5 decoy path and both PowerShell cases run on the Linux CI runner, same as the previous rounds. cargo fmt --all -- --check and scripts/check_architecture.py --base origin/main are clean.

@Kuddev Kuddev left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

复核了 90860de9。Linux 真 PTY 上,Bash/zsh 的 21 项编辑器测试通过,包括上一轮的 Bash 相似绑定和 zsh 普通 Vi widget。PowerShell 7.6.8 / PSReadLine 2.4.5 有 7 个断言失败和 1 个错误;3 个旧版编辑器用例因未配置旧模块跳过。需要修复三处:

  1. PowerShell:安装重绘时中断了后续编辑器初始化。 completion.ps1 把 -Function ClearScreen 和 -Description 用在同一个调用。PSReadLine 2.4.5 的两个参数属于不同参数集,实际返回 Parameter 'Function' cannot be specified in parameter set 'ScriptBlock'. 默认空闲的 F9 无法安装,后续原生指针初始化也没走完;清屏声明消失,鼠标位置查询返回 unsupported。同一环境用 554235a8 跑清屏/粘贴并存和 Unicode 光标定位,两项均通过。请用 PSReadLine 支持的绑定方式验证所有权,并把重绘安装失败隔离在可选重绘功能里。
  2. zsh:其他键表里的字符串宏仍可能被当成未绑定。 *undefined-key* 也接受内容里有 undefined-key 的带引号宏。真 PTY 中,插入模式是内置清屏,命令模式是同一键上的 aundefined-key 宏,提示符仍声明重绘;按 Esc 切过去后发送重绘键,缓冲区变为 echo tailundefined-key。请只接受未加引号的 undefined-key 结果,并对无法查询的键表撤销声明。
  3. Bash:也有同一个提示符内切到 Vi 命令键表的路径。 目前只查提示符时的默认键表。在 Bash 5.2.21 的真 PTY 上,vi-insert 绑定清屏、vi-command 绑定字符串宏,启动仍声明重绘;Esc 后发送重绘键会执行用户宏并插入文本。请同时验证可在同一提示符切换到的 Readline 键表。

PSReadLine 2.4.5 keeps -Function and -Description in different parameter
sets, so the redraw install threw ('Parameter Function cannot be
specified in parameter set ScriptBlock.') and the outer catch killed the
whole editor and pointer init with it. The redraw now installs through
the ScriptBlock set — a handler performing the native ClearScreen work
(erase display and scrollback, re-prompt) — carrying the session token
in -Description inside its own try, so a refusing PSReadLine only leaves
the redraw advertisement off. Identity moves with it: the per-prompt
re-check matches the Description token alone, since Function is a
display name scriptblocks imitate.

The zsh ownership probe accepted any report containing undefined-key,
so a quoted vicmd macro whose body merely contains the word stayed
announced and fired user text; the probe now matches the bare
space-anchored undefined-key tail an unbound keymap reports and revokes
keymaps it cannot query.

The bash probe validated only the prompt-time keymap; the probe now
walks every keymap reachable within one prompt (emacs-standard/-ctlx/
-meta, vi-insert, vi-command, vi-move) inside a single subshell,
anchoring entries to the key's complete binding line and restoring the
original keymap before returning, so a user macro waiting in vi-command
revokes while an unbound chord elsewhere stays inert.

The PowerShell and bash-5 paths run on the Linux CI as before; the zsh
editor suite is green locally.
@zher52

zher52 commented Nov 12, 2026

Copy link
Copy Markdown
Author

All three points are addressed on head 30b5aed (branch also merged current main first):

  1. PowerShell: the install no longer crosses parameter sets, and its failure stays optional. -Function ClearScreen -Description … was indeed throwing on PSReadLine 2.4.5 (Parameter 'Function' cannot be specified in parameter set 'ScriptBlock.'), and the outer catch then killed the rest of the editor init with it — which is exactly the unsupported pointer query and the missing clear-screen announcement you saw. The redraw now installs through the ScriptBlock set: a handler that performs the native ClearScreen work itself (erase display and scrollback, then InvokePrompt()), carrying the session token in -Description, wrapped in its own try so a refusing PSReadLine only leaves the redraw advertisement off. Identity moves with it — Test-PebrelRedrawBinding matches the Description token alone, since Function is a display name scriptblocks imitate. New tests: test_redraw_install_failure_is_isolated_from_the_editor refuses the F9 install through a fixture stub and asserts query, completion and pointer init keep working with no redraw advertisement; test_redraw_identity_is_the_description_token pins the token plus the buffer-preserving clear; test_production_load_order_keeps_paste_and_redraw_independent now asserts the token instead of the display name. These cover the 7 failures + 1 error the last run showed on ubuntu's PSReadLine 2.4.5.

  2. zsh: an unbound keymap is a bare, space-anchored tail. The queried key renders before the value, so an unbound keymap reports "<seq>" undefined-key while a macro never ends in that exact undefined-key tail — your quoted aundefined-key repro included. A keymap the probe cannot query reports nothing, which revokes. test_ssh_zsh_quoted_macro_in_another_keymap_revokes runs the vicmd macro in a real PTY: the prompt revokes with the empty value and ESC routes the chord into the macro.

  3. Bash: the probe walks every keymap reachable within one prompt. After confirming the current keymap still lists our exact binding line (unchanged revocation semantics for a chord the user unbound), it switches through emacs-standard/-ctlx/-meta, vi-insert, vi-command and vi-move inside a single subshell, anchoring each table's entries to the key's complete binding line — a lookalike sequence ending in \e[46~ still can't trip it — and restores the original keymap before returning. Anything that is not our binding revokes (your vi-command string-macro case), an unbound chord elsewhere stays owned (inert, no user code runs). test_ssh_bash_redraw_macro_in_the_vi_command_keymap_revokes covers install into vi-ins, ESC, macro fires.

Environment note: this machine has zsh but neither pwsh nor Bash ≥ 4, so the zsh editor suite (11 tests) ran locally green along with a probe smoke test; the bash-5 and PowerShell paths run on the Linux CI as before. I did not touch the red run on 90860de — this push supersedes it.

@Kuddev Kuddev left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

复核了 30b5aed9。本机 Linux 真 PTY 上,Bash Vi 键表和 zsh 字符串宏的新增反例都通过;PowerShell 7.6.8 / PSReadLine 2.4.5 的两处失败与 Ubuntu CI 一致。两个对照都只调整测试时序或夹具,未改生产脚本:

  1. test_redraw_install_failure_is_isolated_from_the_editor 的正则没有匹配实际的 Ctrl+Shift+F9 参数,安装没有被拒绝。改用 $args -contains 'Ctrl+Shift+F9' 并断言拒绝标记后,重绘声明未发出,编辑器查询和指针初始化都成功。
  2. test_rebinding_to_a_same_name_scriptblock_revokes_the_advertisement 等到 PS> 就立即发 F9,缓冲区收到 ~;。等下一次 qa_ready 并完成 PTY 的光标位置握手后,撤销声明与用户绑定都通过,缓冲区收到 USER-F9。

请让夹具明确断言故障已注入,并等待下一次编辑器读取就绪,再重跑原生检查。当前 Ubuntu 和两个 macOS 原生检查仍为失败。

… the handshake

The isolation fixture's refusal never fired: the stub pattern went
through two escaping layers and became a regex matching a literal
backslash, so Ctrl+Shift+F9 slipped through to the real cmdlet and the
redraw advertised anyway. Match the argument with -contains instead and
emit a SetUserVar marker before throwing, which the test asserts before
the isolation conditions — a silently-passing stub can no longer hide.

Rebinding-to-a-scriptblock keyed the raw chord as soon as the prompt
appeared, inside the read's cursor-position handshake, so the escape
sequence reached the editor split and the buffer received "~;". Wait
for the next editor read to announce itself and settle the handshake
before keying the chord; the revocation and USER-F9 assertions then
hold.
@zher52

zher52 commented Nov 13, 2026

Copy link
Copy Markdown
Author

Both are fixed on head 8a743a0, production scripts untouched:

  1. The stub now matches the argument with $args -contains 'Ctrl+Shift+F9' (my original pattern went through two escaping layers and became a regex for a literal backslash, so the refusal never fired), and it emits a qa_redraw_refused SetUserVar marker before throwing. The test asserts that marker first, so the isolation conditions can no longer pass against a silently-skipped injection.

  2. test_rebinding_to_a_same_name_scriptblock_revokes_the_advertisement waits for the next qa_ready announcement and settles the cursor-position handshake before keying the chord; the revocation assertion and the USER-F9 buffer check both hold against the same session.

@Kuddev Kuddev left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

复核了 8a743a01。Bash、zsh 和 PowerShell 7.6.8 的真实 PTY 套件有 35 项通过、3 项旧 PSReadLine 用例因缺模块跳过。上轮两处 PowerShell 夹具问题已修复。

新反例:zsh 启用 bindkey -v 且没有自定义重绘键时,当前实现仍会声明重绘能力:viins 有 .clear-screen,vicmd 的 undefined-key 也被视为安全。我在真实 zsh PTY 输入 printf 'LINE:%s\n' original,按 Esc 进入 vicmd,随后发送应用实际使用的 ESC [ 46 ~。按 Enter 后输出 LINE:originaL;省略清屏键或在 vicmd 也绑定原生 .clear-screen 时,均输出 LINE:original。未绑定的多字节序列并不一定会整体被忽略,尾部的 ~ 可以被 Vi 当作切换大小写命令。

请只在可到达的键表都能完整消费该重绘序列时声明能力,或在无法确认时回退到应用侧清屏。请把无自定义按键的 Vi 模式也纳入回归。当前 PR 保留待修改。

…he chord

A multi-byte chord is not consumed as a whole in an unbound keymap: zsh
vicmd and readline vi-command keep the trailing "~" bound to the
invert-case command, so a redraw sent into a merely-unbound keymap
rewrote the user's line ("original" became "originaL" in the review
reproduction). "Unbound is inert" is gone from the contract.

Installation now scans every reachable keymap and either installs the
built-in clear-screen into each of them — vi users keep the capability,
with vicmd / vi-command consuming the full chord mid-line — or, when any
keymap holds a user binding, installs nothing and the capability stays
off. zsh protected keymaps (.safe) refuse binding and cannot be reached
through a typed chord, so they are excluded from the contract instead of
killing it, and the per-prompt probe re-verifies exactly the recorded
keymap set: a rebind, an unbind, a macro or an unbound keymap all revoke
the announcement to the app-side cursor home.

The plain-vi-mode review reproduction is a regression now: the chord is
announced, sent after ESC, and the line must survive as LINE:original.
@zher52

zher52 commented Nov 13, 2026

Copy link
Copy Markdown
Author

Handled on head 0aa8f10 (the branch also merged current main first). The ownership contract is now all-or-nothing across keymaps — your read of the hazard was exactly right, and "unbound is inert" is gone from both shells:

  • The probe requires our binding everywhere. zsh re-verifies every keymap recorded at install time: only the built-in .clear-screen tail counts — a string macro (quoted body, even reading "undefined-key"), a user widget, an unbound keymap and an unqueryable one all revoke. Bash walks the six reachable keymaps after the startup-keymap check and requires the exact clear-screen line in each — the anchored full-line match from earlier rounds is kept, so lookalike chords still can't satisfy it.
  • Installation covers vi users instead of dropping the capability. The install scans every keymap first: any user binding anywhere keeps the whole capability off and the key untouched (the two user-binding counterexamples now assert the announcement is completely absent — no token and no empty revocation, since nothing was installed). If every keymap is free, the built-in is installed into each of them, so vicmd / vi-command consume the full chord mid-line.
  • zsh protected keymaps (zsh refuses to bind into .safe and friends): they can never carry our binding and are not reachable through a typed chord, so the install records exactly the keymaps it could bind and the probe re-verifies that recorded set — a protected keymap is excluded from the contract instead of killing it. The query-only fixture withdrawal now spans every keymap for the same reason.
  • Your plain-vi-mode repro is the regression: test_ssh_zsh_plain_vi_mode_fully_consumes_the_redraw_chord — plain bindkey -v session, capability announced, printf 'LINE:%s\n' original, ESC, chord, Enter → LINE:original asserted and originaL asserted absent. The symmetric bash vi-mode case rides along (bash ≥ 5 on CI). A later rebind in any covered keymap still revokes through the recorded-set re-verification.

The all-or-nothing decision is recorded as an amendment in the clear-action design note. Locally the editor suite (25 tests, both new vi-mode cases included) is green; the bash-5 and PowerShell paths run on the Linux CI as before.

- ShellSession.wait attributes each read window exactly up to its sentinel
  and carries the remainder into the next window; a read block that
  coalesced a command's sentinel with the following prompt's precmd
  markers could swallow the editor-ready marker into the previous
  command's output, which failed the zsh rebind revocation test on loaded
  macOS runners.
- application_drag_stays_with_the_original_pane advances past the resize
  debounce gates before reading expectations or firing gestures; the
  pixel-driven grid resize could land between the read and the drag and
  encode one column past view.cols.
- check_redraw_vi_mode_plain waits for the rendered newline it asserts.
@zher52

zher52 commented Nov 16, 2026

Copy link
Copy Markdown
Author

Both CI failures on head c93b4ac (run 43674994798) are test-timing races, fixed on head a3833cb. No product code changed — between the green head 476ae02 and the red head the only delta was main's ai_sessions.rs, and both failures reproduce only under runner load.

  1. test_ssh_zsh_rebinding_the_redraw_chord_revokes_the_advertisement (macos-26, job 132693202123) — the PTY harness, not the shell. ShellSession.wait() returned every byte it happened to read, so a read block that coalesced REBIND-DONE\r\n with the following prompt's precmd markers consumed the pebrel_editor_ready marker into the previous command's output; the REBOUND window then showed the empty redraw revocation without the ready marker — exactly the captured bytes. wait() now attributes each window exactly up to its first sentinel and carries the remainder into the next one (session.output stays the full stream, so cumulative assertions are unchanged), and check_redraw_vi_mode_plain now waits for the rendered newline it asserts instead of relying on the old over-read. The zsh editor suite passes 3×25 green locally; the bash-5 and PowerShell paths ride the Linux CI as before.

  2. application_drag_stays_with_the_original_pane (macos-26-intel, job 132693202194) — the test, not the product. The two-pane fixture reads view.cols for the expected clamp column after a single draw, but the pixel-driven grid resize (40→41 columns for the 800 px window) commits only after the trailing-edge RESIZE_SETTLE_DELAY debounce. When the commit landed between the read and the drag, the encode clamped to the widened grid (column 41) while the expectation still said 40 — the observed <32;41;1M vs <32;40;1M mismatch (the sibling legacy_drag... test never races because mark_structural_resize() commits immediately). The test now advances past STARTUP_GRID_GRACE + RESIZE_SETTLE_DELAY, parks and redraws before reading expectations or firing gestures: 8× green locally and the whole application_mouse module 16/16.

cargo fmt --all -- --check (pinned 1.97.1) and scripts/check_architecture.py --base origin/main are clean. This push supersedes the failed run on c93b4ac.

@zher52

zher52 commented Nov 16, 2026

Copy link
Copy Markdown
Author

Follow-up on head f093a23: the only change is formatting. The lint job's stable rustfmt breaks the settle chain differently than the pinned 1.97.1 (cx.executor().advance_clock(…) must become a two-line method chain), so the previous push failed lint and skipped the native matrix with it. Reformatted to the stable form — 1.97.1's cargo fmt --all -- --check accepts it too — and the target test still passes; no code change.

…nal-action

# Conflicts:
#	architecture/notes/pebrel_app/gpui_shell/2026-10-14-terminal-clear-action.md
#	pebrel_app/src/gpui_shell/terminal/view.rs
The macos-26-intel CI failure (Missing SetUserVar=pebrel_editor=) was a
harness turn overlap, not an editor flake: the snapshot chord landed
inside the previous chord's render burst, PSReadLine tore the ESC
prefix into a standalone Escape plus literal tail keys (line reverted,
buffer littered with ; / [ / ~), and the handler never ran. A
byte-level trace of a failing run pinned the overlap (304 ms of zero
output between two chord writes), and a 4-way parallel stress loop
reproduced the signature in 23/40 runs.

The harness now waits for the editor's first reaction byte after each
write and drains the burst before the next chord, and answers cursor
probes on a 20 ms poll instead of 100 ms. Assertions are unchanged;
the same stress shows 0/40 tear failures afterwards. Evidence and the
rejected alternatives are recorded in
architecture/notes/pebrel_terminal/tty/2026-11-17-pointer-chord-turn-serialization.md.
@zher52

zher52 commented Nov 17, 2026

Copy link
Copy Markdown
Author

Root-caused on head 79001f6: the remaining native-test failures on this PR are a test-harness defect, not an editor flake — as suspected, ours.

Diagnosis. In the failing run (43903487733, macos-26-intel) a byte-level trace of both PTY directions shows the numeric query completing normally, then the move chord and the snapshot chord written 304 ms apart with zero output between them: pwsh had not yet reacted to the move chord when the snapshot chord landed inside its in-flight render burst. PSReadLine accepts an ESC-prefixed chord only while the rest of the sequence is already readable, so the burst overlap tears it into a standalone Escape plus literal tail keys — the captured renders show the line reverted to empty (Windows-mode Escape → RevertLine), [ ; ~residues inserted (digits swallowed by DigitArgument / Meta-digit), and nopebrel_editor` var ever emitted. This is a different mechanism from the PTY read-overrun races fixed earlier on a3833cb.

A 4-way parallel stress loop on macOS x64 reproduces the exact signature in 23/40 runs; without load it never reproduces, which matches the intermittent CI picture.

Fix (79001f6). The harness now serializes protocol turns: before writing any chord it waits (bounded) for the editor's first reaction byte to the previous write, then drains the burst to quiet (PowerShellSession.turn), and cursor-position replies move to a 20 ms poll instead of 100 ms. Assertions are unchanged — no coverage removed. Under the identical stress loop the tear signature drops to 0/40 (the remaining local failures are pwsh cold starts starved by four concurrent instances, never seen in CI's serial jobs). The full test_powershell_pointer file passes 15/15 (3 legacy skips) locally, and scripts/check_architecture.py --base origin/main is clean.

The decision, rejected alternatives (retry-masking, longer quiet windows, chord redesign) and the production-exposure caveat (the GUI sends the same chords over a real PTY; the protocol's query/snapshot replies let it detect a desynchronized editor) are recorded in architecture/notes/pebrel_terminal/tty/2026-11-17-pointer-chord-turn-serialization.md. The branch also merged current main first (e76c27b); the previous run's macos-26-intel failure did not recur there, but the harness fix above removes the latent cause rather than waiting for the next roll.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants