Repository navigation
feat(terminal): inline path completion for the web terminal - #548
Conversation
Design Review (Fable 5) — ✅ PASSAdvisory design-level review of Design-Verdict: PASS A real UX gap closed with a sound shape: screen-buffer truth over keystroke mirroring, session-scoped authority on the backend, and refuse-over-guess everywhere ambiguity exists. [DESIGN-REVIEWED] 445c24b |
Arbiter — ✅ no blocking findingsArbiter found no unresolved long-term items that require action before merging Second-order review for Review detailsBoth line-level reviewers (Opus 5 and GPT 5.6) reported no findings for this commit, and the design review passed with no CONCERNS listed — so there are no sub-threshold findings to arbitrate. Arbiter-Verdict: PASS No sub-threshold finding meets the long-term-impact bar. Both line-level reviews (Opus 5, GPT 5.6) recorded "No findings" for commit [ARBITER-REVIEWED] 445c24b False positive or not applicable? A repository writer can comment: For a broader accepted-risk deferral, apply |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
4103e82 to
45c3c52
Compare
Round 1 — all 11 GPT 5.6 findings + both Design Review concerns addressedPushed as HIGH1. Raw filenames enable terminal command injection ( Correct and the most serious of the three. Two layers, because they solve different problems. Control characters are refused, not escaped — there is no escape that makes CR/LF safe to type — filtered where the listing enters the component so such a name is never offered, never highlighted, and never feeds Tab's common prefix, with a second check in Backslashes rather than quotes, deliberately: the escaped name stays one shell word with nothing left open, so the echo still tokenises as a single word and accepting a directory can re-trigger on its contents. Wrapping in quotes would put the cursor inside a quoted region that finding #10's fix then (correctly) refuses to complete, dead-ending the walk-into-directory flow the trailing 2. Completion bypasses the sensitive-path keystone ( Correct — 3. Successful enumeration is not SEL-audited ( Correct, and the spec states it as a blocking rule. The payload is deliberately coarse: a fixed reason word and nothing else. This route fires per keystroke behind a 70 ms debounce, and the word, prefix, resolved directory and entry names are all user filesystem contents — logging them would turn the audit trail into a transcript of the user's typing and disk layout, which is a worse outcome than the coarse event. Flagging the volume tradeoff explicitly since it is a consequence of the rule rather than of this feature: one audit event per completion request. MEDIUM4. Stale suggestions survive edits and failures. Fixed both halves. 5. Mid-word completion corrupts the command. Fixed. The module docstring claimed this was out of scope but nothing enforced it; new 6. 7. Menu opens while a foreground program owns the PTY. Fixed via the alternate-screen guard rather than the process-group check you suggested — this is the one place I deviated. Design Review independently called the alt-buffer bail-out "a one-line fix [that] closes the whole failure class", and it covers vim/less/htop. Honest remaining gap: a REPL on the normal screen is not covered, and 8. No IME guard. Fixed. Keys with 9. Unbounded retention and wrong executor. Fixed both. Candidates are now pulled lazily from a generator into 10. Quoted and escaped words. Fixed. New 11. Spec not updated. Fixed. Design ReviewBoth items are covered above (alt-buffer guard → #7, spec → #11). The third, advisory, item is also done: Verification
One scope noteThe 400/413 client-validation branches are audited too ( |
45c3c52 to
d90f059
Compare
|
Round 1b — |
d90f059 to
523ef16
Compare
Round 2 — all 3 HIGH + 10 MEDIUM addressedPushed as HIGH1. Sensitive child entries bypass the gate. Correct, and my round-1 fix was the cause of the false confidence: it vetted the directory only, so completing inside 2. Path resolution blocks the event loop. Correct — 3. Leading hyphens remain executable options. Correct, and the sharpest finding in this round — escaping cannot fix it, since MEDIUM4. That decouples on-screen length from decoded length, so 5. Cached cwd survives command submission. Correct — the 0.4 s memo reintroduced, in a smaller window, the exact bug it was added to prevent. The WS binary-write branch now clears 6. 7. 8. Surrogate filenames. Both halves. Server: the filter is extended to 9. 10. 11. Combining-character cells. Fixed by suppression, not remapping, and stated as a choice: 12. 13. Manual Verification
Remaining known gap, unchanged from round 1Foreground-process-group detection is still not implemented. The alternate-screen guard covers vim/less/htop; a REPL on the normal screen is not covered, and |
Opus 5 Review — ✅ no blocking findingsReviewed No findings. Verdict recorded via the action's structured output for commit False positive or not applicable? A repository writer can comment: |
cf08548 to
03b9c11
Compare
9273bad to
74ea1f5
Compare
Round 6 —
|
74ea1f5 to
3e082b3
Compare
Round 7 —
|
The web terminal had no completion menu of its own. kiro-cli's autocomplete does not reach it: that menu is a native always-on-top window positioned via the macOS Accessibility API against a real terminal window, and xterm.js is a canvas with no OS-level text caret to anchor to. Build the equivalent natively instead. The menu is a positioned React element inside the terminal pane, driven from xterm's own screen buffer rather than a keystroke mirror, so it cannot drift out of sync with the shell's line editor (zsh tab completion, autosuggestions, Ctrl-R, paste and vi mode all rewrite the line behind our back). Prompt boundaries come from OSC 133 `B` or OSC 697 `NewCmd`/`EndPrompt` when the user's shell integration emits them, and from a prompt-terminator heuristic otherwise. Scope is paths only: directories for `cd`/`mkdir`-style commands, directories plus files elsewhere, arrow keys to select, Tab to extend to the common prefix, Enter to insert, Escape to dismiss. Accepting a directory appends `/`, which re-triggers the menu so a path can be walked without leaving the keyboard; a row that confirms the directory as typed leads the list once the word ends in a slash, so the level just chosen is reachable rather than only its children. Accepting a file ends the word and does not re-open. No per-CLI subcommand specs, history mode or fuzzy matching. Names are matched as case-insensitive substrings, not prefixes, so a long directory is reachable by its distinctive middle (`termi` finds `KiroCrew-terminal-completion`) without retyping from the start. Results rank by match offset, so a true prefix still leads, and the matched span is emphasised in the menu — a non-prefix hit is illegible otherwise. Accepting such an entry erases the typed fragment and retypes the name, since it cannot be extended in place. A fragment starting with a dot is matched as a prefix instead: the dot is what unhides entries, so searching for it as a substring would drag in every `foo.bar` and defeat the filter it just switched on. Nothing filesystem-derived is typed raw. A directory entry may legally contain a newline — `touch $'evil\nrm -rf x'` creates one — and typing it would submit the second line to the shell as a command, so names carrying a control character are refused at both the listing and the insertion end rather than sanitised, since no escape makes CR/LF safe to type. Everything else is backslash-escaped through the single choke point both insertion paths already share, against an allowlist, so a metacharacter this version has not thought of is escaped by default. Backslashes rather than quotes keep the result one shell word with nothing left open, so the echo still tokenises as one word and walking into a directory still works. The menu produces nothing rather than something plausible but wrong wherever the row cannot be reasoned about: on the alternate screen buffer, because vim/less/ htop sweep the cursor over arbitrary text where a redrawn `> cd ./src` satisfies the prompt heuristic and an open menu would then steal Escape/Enter/Tab/arrows from the TUI; on a wrapped row or one with a non-single-width cell at or before the cursor, because `translateToString` returns one physical row while `cursorX` counts cells and the two coordinate systems agree only otherwise; mid-word, where the chosen name would be inserted in front of the surviving suffix; and for words the whitespace-only tokeniser cannot parse (`cd "My D`, `cd My\ D`). Enter and Tab re-read the live word before acting and hand the key back to the shell untouched if it no longer matches what the suggestions were computed for, and a failed request closes the menu instead of leaving stale entries acceptable. Keys committing an IME composition are passed through, since swallowing that Enter would accept a path instead of the composed text. Keys the menu claims are cancelled at the DOM level. Returning false from xterm's custom key handler only stops xterm's own processing — it returns early from _keyDown without calling cancel(), so Tab would still move focus out of the terminal and Enter would still reach the PTY as a CR through the following keypress event, executing the line instead of completing it. Ctrl/Meta/Alt combinations are passed through untouched, so Ctrl-C always interrupts. Backend adds POST /api/terminal/complete. It requires an existing live PTY session id, and that is what keeps it from being a general filesystem- enumeration endpoint: the caller already owns an interactive shell with the gateway user's filesystem access, so the route grants nothing that session's own `ls` does not. Within that model the target directory is still canonicalised with realpath and refused through `is_sensitive_path()` before any scan — canonicalisation first, because a benign-named symlink whose target lands in the governance trust-root would otherwise pass a name check and be enumerated through the link. Every outcome including success emits a `terminal.complete` SEL event carrying only a fixed reason word: the route fires per keystroke, and logging the word, prefix, directory or entry names would turn the audit trail into a transcript of the user's typing and disk layout. Candidates are pulled lazily into a bounded heap and the scan itself is capped, so neither a huge directory nor a pathological one can occupy a pool thread; the listing runs on discovery_executor rather than the subprocess_executor shared with PTY teardown. The session cwd is probed directly with a 0.4 s memo rather than reused from the title poller, whose 1 s cadence would resolve a completion issued right after a `cd` against the previous directory. POSIX only, following the PTY backend.
3e082b3 to
445c24b
Compare
Round 8 —
|
…otdev#548) The web terminal had no completion menu of its own. kiro-cli's autocomplete does not reach it: that menu is a native always-on-top window positioned via the macOS Accessibility API against a real terminal window, and xterm.js is a canvas with no OS-level text caret to anchor to. Build the equivalent natively instead. The menu is a positioned React element inside the terminal pane, driven from xterm's own screen buffer rather than a keystroke mirror, so it cannot drift out of sync with the shell's line editor (zsh tab completion, autosuggestions, Ctrl-R, paste and vi mode all rewrite the line behind our back). Prompt boundaries come from OSC 133 `B` or OSC 697 `NewCmd`/`EndPrompt` when the user's shell integration emits them, and from a prompt-terminator heuristic otherwise. Scope is paths only: directories for `cd`/`mkdir`-style commands, directories plus files elsewhere, arrow keys to select, Tab to extend to the common prefix, Enter to insert, Escape to dismiss. Accepting a directory appends `/`, which re-triggers the menu so a path can be walked without leaving the keyboard; a row that confirms the directory as typed leads the list once the word ends in a slash, so the level just chosen is reachable rather than only its children. Accepting a file ends the word and does not re-open. No per-CLI subcommand specs, history mode or fuzzy matching. Names are matched as case-insensitive substrings, not prefixes, so a long directory is reachable by its distinctive middle (`termi` finds `KiroCrew-terminal-completion`) without retyping from the start. Results rank by match offset, so a true prefix still leads, and the matched span is emphasised in the menu — a non-prefix hit is illegible otherwise. Accepting such an entry erases the typed fragment and retypes the name, since it cannot be extended in place. A fragment starting with a dot is matched as a prefix instead: the dot is what unhides entries, so searching for it as a substring would drag in every `foo.bar` and defeat the filter it just switched on. Nothing filesystem-derived is typed raw. A directory entry may legally contain a newline — `touch $'evil\nrm -rf x'` creates one — and typing it would submit the second line to the shell as a command, so names carrying a control character are refused at both the listing and the insertion end rather than sanitised, since no escape makes CR/LF safe to type. Everything else is backslash-escaped through the single choke point both insertion paths already share, against an allowlist, so a metacharacter this version has not thought of is escaped by default. Backslashes rather than quotes keep the result one shell word with nothing left open, so the echo still tokenises as one word and walking into a directory still works. The menu produces nothing rather than something plausible but wrong wherever the row cannot be reasoned about: on the alternate screen buffer, because vim/less/ htop sweep the cursor over arbitrary text where a redrawn `> cd ./src` satisfies the prompt heuristic and an open menu would then steal Escape/Enter/Tab/arrows from the TUI; on a wrapped row or one with a non-single-width cell at or before the cursor, because `translateToString` returns one physical row while `cursorX` counts cells and the two coordinate systems agree only otherwise; mid-word, where the chosen name would be inserted in front of the surviving suffix; and for words the whitespace-only tokeniser cannot parse (`cd "My D`, `cd My\ D`). Enter and Tab re-read the live word before acting and hand the key back to the shell untouched if it no longer matches what the suggestions were computed for, and a failed request closes the menu instead of leaving stale entries acceptable. Keys committing an IME composition are passed through, since swallowing that Enter would accept a path instead of the composed text. Keys the menu claims are cancelled at the DOM level. Returning false from xterm's custom key handler only stops xterm's own processing — it returns early from _keyDown without calling cancel(), so Tab would still move focus out of the terminal and Enter would still reach the PTY as a CR through the following keypress event, executing the line instead of completing it. Ctrl/Meta/Alt combinations are passed through untouched, so Ctrl-C always interrupts. Backend adds POST /api/terminal/complete. It requires an existing live PTY session id, and that is what keeps it from being a general filesystem- enumeration endpoint: the caller already owns an interactive shell with the gateway user's filesystem access, so the route grants nothing that session's own `ls` does not. Within that model the target directory is still canonicalised with realpath and refused through `is_sensitive_path()` before any scan — canonicalisation first, because a benign-named symlink whose target lands in the governance trust-root would otherwise pass a name check and be enumerated through the link. Every outcome including success emits a `terminal.complete` SEL event carrying only a fixed reason word: the route fires per keystroke, and logging the word, prefix, directory or entry names would turn the audit trail into a transcript of the user's typing and disk layout. Candidates are pulled lazily into a bounded heap and the scan itself is capped, so neither a huge directory nor a pathological one can occupy a pool thread; the listing runs on discovery_executor rather than the subprocess_executor shared with PTY teardown. The session cwd is probed directly with a 0.4 s memo rather than reused from the title poller, whose 1 s cadence would resolve a completion issued right after a `cd` against the previous directory. POSIX only, following the PTY backend.
Open PR relationship auditThis is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion. Relationship findings
No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit. |
Screen.Recording.2026-07-26.at.11.18.20.PM.mov
What
Inline path completion for the built-in web terminal. Typing a path — or a bare argument to a path command — opens a menu anchored at the cursor; arrows select, Tab extends to the common prefix, Enter inserts, Escape dismisses.
Why this is built rather than reused
kiro-cli ships exactly this menu, and it does not reach our terminal. That menu is a native always-on-top window positioned via the macOS Accessibility API against a real terminal window; xterm.js is a canvas with no OS-level text caret to anchor to, and KiroCrew is not in kiro-cli's integration list. The one part that is genuinely native is the part we don't need — our whole UI is already in a webview and xterm hands us the cursor cell directly.
How
The word being completed is read back from xterm's screen buffer, not mirrored from keystrokes. A keystroke mirror drifts the moment the shell edits the line itself, which it does constantly: zsh's own Tab completion, autosuggestions,
Ctrl-R, paste, vi mode. Readingbuffer.activecannot drift because it is what the user sees.Prompt boundaries come from shell integration when it exists.
OSC 133;B(VS Code / WezTerm / starship) andOSC 697 NewCmd/EndPrompt(kiro-cli, Fig lineage) both mark where the editable region starts; either handler records the column. Without a marker we fall back to matching the last prompt terminator (❯ ➜ » $ % #) before the word — a heuristic, but a wrong answer only mis-identifies the command name, which at worst suppresses a menu that would have been offered.Two independent triggers, both deliberately narrow. A word that already looks like a path (
/,./,../,~) triggers whatever the command is; a bare word triggers only for a known path command (46 of them,cd/ls/cat/vim/…). Flags,$varsand command substitutions never trigger, and neither does the command name itself while it is being typed.Names match as case-insensitive substrings, ranked by match offset, so a long directory is reachable by its distinctive middle —
termifindsKiroCrew-terminal-completionwithout retyping from the start — while a true prefix still leads. The matched span is emphasised in the menu, because a non-prefix hit is otherwise illegible. A fragment starting with a dot is matched as a prefix instead: the dot is what unhides entries, so treating it as a substring would drag in everyfoo.barand defeat the filter it just switched on.Accepting a directory appends
/, which re-triggers the menu on its contents, so a path is walked without leaving the keyboard. Once the word ends in a slash a↪ ./row leads the list, so the level just chosen is reachable rather than only its children. Accepting a file ends the word and does not re-open.Keys the menu claims are cancelled at the DOM level. Returning
falsefrom xterm's custom key handler only stops xterm's own processing — it returns early from_keyDownwithout callingcancel(), so the browser default still runs. Left alone, Tab moved focus out of the terminal onto the page's skip link, and Enter went on to firekeypress, which xterm turns into a CR and sends to the PTY — the shell executed the line instead of the menu completing it.Ctrl/Meta/Altcombinations are always passed through, soCtrl-Cinterrupts even with the menu open.Backend
One route,
POST /api/terminal/complete, whichscandirs a directory and returns entries plus the match offset.It requires an existing terminal session id, and that is what keeps it from being a general filesystem-enumeration endpoint: the caller already owns a live PTY in this gateway — an interactive shell with the gateway user's full filesystem access — so the route grants nothing that session's own
lsdoes not. Paths therefore resolve exactly as the shell would, without a root restriction. The existing_is_enabledgate and SEL audit logging apply.The session cwd is probed directly with a 0.4 s memo rather than reused from the title poller's
last_cwd. That poller refreshes on a 1 s cadence, which is long enough for a completion issued right after acdto resolve against the previous directory. The memo also keeps a held-down key from spawning anlsofper keystroke (macOS has no/proc).Out of scope
No per-CLI subcommand/flag specs, no history mode, no fuzzy (subsequence) matching, no mouse selection — the menu is
pointer-events: noneso it never steals the terminal's own selection and drag. Words containing spaces produce no completions rather than wrong ones: quoting and backslash escapes are not interpreted.git,docker,kubectland friends need to know which argument is a path, which is what a spec tree solves; until then they work by typing./.POSIX only, following the PTY backend.
Testing
test/test_terminal_handler.py— 125 pass, 5 skipped. New coverage for word splitting, directory resolution (relative / absolute /~/..), substring matching and offset ranking, the dot-prefix rule, hidden-entry gating,folders_onlynarrowing, truncation, the cwd memo TTL, and the route's auth / disabled / malformed-body / oversized-word / unknown-session paths.website/src/test/terminalCompletion.test.ts— 31 pass. Pure trigger/tokenising logic: cursor at a word boundary, prompt-marker versus heuristic, pipelines and&&,sudo/envwrappers, flags and expansions, common prefix, insertion keystrokes.website/src/test/TerminalCompletion.test.tsx— 23 pass. Full trigger → fetch → render → keys path, including a regression test that every claimed key isdefaultPrevented, thatCtrl-Cis not, that accepting a directory re-opens on the next level, that accepting a file does not, and that a mid-name match is emphasised and replaces the typed fragment.CliPanel.fontRefit,RunInTerminalBtn,RunInTerminalBtn.security,App.terminalEnabledFlag).flake8,isort,mypy,tsc,eslintclean;npm run buildpasses.Not verified
Visual behaviour was exercised by hand on macOS with zsh + kiro-cli's OSC 697 integration (the four bugs above were all found that way). The OSC 133 path and the no-marker heuristic have unit coverage but were not driven through a real bash/fish session end to end.