Repository navigation
feat(terminal): open the project in an allowlisted external terminal app - #19600
Conversation
First Principles Review (Opus 5.5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The automatic switch to the built-in terminal when a launch fails is not justified. It is also the reason for the note in Not justified as shipped
What this change shipsInventory (8 items) — 7 justifiedIntent: a desktop-app user opens their own terminal emulator in the project folder. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 52a2ca0 Description read[DESCRIPTION-READ] 3a3b17f6f4b324abeeacd61351b4eb1772b4e9d31944b7dfe94ec866272267c8 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS A maintainer should approve the new local launch boundary: a gateway-minted single-use grant that the desktop main process redeems over the internal-secret channel. The description asks for this sign-off itself. Suggestions
[DESIGN-REVIEWED] 52a2ca0 Description read[DESCRIPTION-READ] d5db2af6518edac24f4d2d50e81e7bdbd5dbff309bc5a00fef3733c779fdfe0a That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
UX Review (Opus 5.5) — ✅ human override accepted@cruisercohen overrode this lane for |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
1a1051b to
7407679
Compare
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 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: |
|
Addressed the UX review on
Not changed: retitling the existing "Open terminal in the project directory" row. With no app picked this PR keeps that menu exactly as it is today (pinned by On the First Principles note about the automatic fallback: kept. The issue asks for it ("Launch failure must degrade gracefully: fall back to the integrated panel rather than a dead click"), and the design this implements specifies it. It runs only after the user asked for a terminal in this project, and it opens the same integrated terminal the row above it opens. |
7407679 to
1ed420b
Compare
|
Addressed the second UX review on
Not changed: the existing row's hint ("A command line that starts in this project’s folder."). With no app picked this PR keeps that menu exactly as it is today, so the existing strings are left alone; the new note says "the terminal", the same word as the existing row's label. |
1ed420b to
fa6ad2c
Compare
|
Addressed the GPT 6.1 findings on
|
fa6ad2c to
8ba5781
Compare
8ba5781 to
fa305fa
Compare
|
Folded the UX Review fix into the second commit to keep the PR at the 2-commit cap. Because the fold hides the diff, here is exactly what changed from
The files touched are |
fa305fa to
3291b61
Compare
|
Answered the UX review on
The files touched are Not changed: the integrated row's hint. "A command line that starts in this project's folder." stays as it is. This PR keeps the default menu exactly as it is today, and a test pins that. The new row is the one that says where it opens: "The terminal app you picked in Settings, in a separate window". |
3291b61 to
1bc2111
Compare
56881d8 to
cdec78a
Compare
|
@iamwhatever the review points on The fold: I folded the change into the second commit, so the PR still has 2 commits.
Launch behaviour is unchanged: the desktop Dispositions:
Tests:
Screenshots: I retook the Project actions menu (dark and light) and the fallback notes (all four reasons in dark, two in light) at Auto-merge stays armed. |
cdec78a to
2895f2c
Compare
|
Dispositions for head
|
|
New head
No behaviour change: only these strings and the test label constants that quote them moved. The two Project actions screenshots (dark and light) in the description are retaken on this head. |
|
Pushed |
|
Rebased onto main only, no code change. New head: b88569f. |
|
@iamwhatever re-requesting you on your 17:06Z change request; the point-by-point dispositions are in my 18:01Z reply above, and on b88569f each point lives here: (1) detect answers a non-local window |
|
Rebased onto main 328f749 (generated ui-index regenerated after #14918); no code change. New head a48c1d3. @iamwhatever re-requesting you on your 17:06Z change request; every point of it is answered in the dispositions comment. |
|
Rebased onto main 7f7c38b (generated ui-index regenerated); no code change. New head ac2465c. range-diff: commit 1 is line-for-line identical; commit 2 differs only in the generated ui-index header lines (input digest and coverage counts that main moved). The point-by-point answers to the open change request are in the dispositions comment. |
|
/ai-review override ux ac2465c: Rebase-only head; the row label and hint copy are unchanged since 0d7636e, where UX Review passed, and b88569f's same-head UX re-run returned CONCERNS. This BLOCK repeats the reader-would-not-click point on that same copy, so it is lane sampling variance, not a new finding. |
Human judgment recorded@cruisercohen marked the ux AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
@iamwhatever where each point of your change request stands on the current head
All checks are green on this head, and auto-merge is armed. Could you take another look? |
iamwhatever
left a comment
There was a problem hiding this comment.
Requesting changes at ac2465c.
The points of our earlier change request are fixed: external-terminal:detect now answers a non-local window {apps: [], capable: false} and the panels hide the row and picker without a notice.
One defect remains, raised by the Opus 5.5 lane on this head and still unanswered. I confirmed it in the code. ipc-registrar.js#L512 passes readInternalSecret as getSecret, and redeemGrant calls getSecret() with no argument. readInternalSecret(gatewayUrl) (main.js#L237) then hands undefined to internalSecretFor, dialTarget returns null, and the secret is "". Risk: in the real desktop app every "Open in " click fails redemption and falls back to the built-in terminal, so the feature never launches anything. The tests inject a secret stub that ignores its argument, so they stay green.
Smallest fix: pass getSecret: () => readInternalSecret(backendUrl) in the registrar, and add a registrar test whose readInternalSecret stub asserts it receives backendUrl.
Separately, this PR adds a new launch boundary (gateway grant, strict internal-secret redeem route, main-process spawn). Under the maintainers' rule that goes to a human reviewer even once the fix lands. All checks on this head are green.
— crew-pr-reviewer (r106)
|
Fixed at a259f7f, folded into the first commit (6747443); the second commit is unchanged.
Test. The registrar harness stub for Earlier points. Thanks for confirming those are settled on this head; nothing else changed. Human review of the launch boundary. Understood; that sign-off stays with a maintainer. |
|
Rebased onto main at 59eb987 (conflict-only: main added
|
|
fixed
|
Adds a gateway-gated launch of the user's own terminal emulator from the desktop app. POST /api/terminal/external approves only the dashboard owner, on a direct-local request, with the integrated terminal enabled and an app picked in dashboard.terminal.external_app (unset by default), and answers a single-use grant. The Electron main process redeems the grant over the machine-only /api/terminal/external-grant route and starts the app's own executable from a fixed allowlist with a pinned argv and the realpath'd project directory as its cwd, with shell:false and no OS opener. Part of #2877
Adds "Open in <app>" to the Files tab's Project actions menu below the integrated terminal row, with a hint saying it is the user's own terminal app in a separate window. It shows only in the desktop app, for a gateway on this machine, once an app is picked and while it is still installed. Settings -> Display -> Terminal gains an "External terminal app" picker that lists only the allowlisted apps the desktop shell finds installed and saves dashboard.terminal.external_app. The desktop shell answers a window it refuses (a remote crew reached through an SSH tunnel also reads as direct-local) as not capable instead of rejecting, so that window shows neither the row nor the picker and no error; the launch itself is still refused there. A refused or failed launch opens the built-in terminal instead; the side panel shows a warning naming the app and why, above the terminal tab that took the Files tab out of view, and links to the picker when the note sends the user there. A failed check of the setting or the installed apps is reported, not read as none, and carries a Retry in both places. For change cards the new setting is one no value can widen: it names an allowlisted app, and only the owner's click starts it. Strings in every locale. Part of #2877
|
Rebased onto main 4ca0ff3 as 52a2ca0, still 2 commits. Main split the config sections module into one module per section, so this change moved with it. Behaviour is the same as on fd879da.
|
|
/ai-review override ux 52a2ca0: The row label now reads "Open in {{app}} (separate window)" in every locale, the fix UX Review itself gave on fd879da; the only other change since then moves the config entry with main's split. This BLOCK says it cannot evaluate because the screenshots predate the new label, and its "(separate app window)" restates the same fix, so it is not a new finding. |
Human judgment recorded@cruisercohen marked the ux AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
Problem / Motivation
Goal: Let a desktop-app user open their own terminal app (kitty, WezTerm, Ghostty, …) in the session's project directory, as an opt-in action beside the integrated terminal.
Developers attached to their terminal emulator (profiles, keybindings, GPU rendering, multiplexers) lose all of it in the integrated panel. Today the only way to get a shell in the project directory is the integrated PTY; there is no way to hand the project to the terminal app they actually use.
Why it matters
The Files tab already offers "Open terminal in the project directory", but only as the integrated panel. Users who live in their own terminal have to copy the path and
cdby hand every time, which is the gap the issue describes. The opt-in keeps the integrated panel the default for everyone else.Not a goal
cwd: Terminal.app and iTerm2 (both need AppleScript), Ghostty on macOS (onlyopen -nastarts it), Warp (a URL scheme). They are left out rather than reached through an OS opener.What changed (motivation → approach → change)
Design note (the launch boundary). Adds a local-only launch boundary; a maintainer should confirm it.
POST /api/terminal/external(body{cwd}) approves only when ALL of these hold, in this order: the caller is authenticated (401), is the dashboard owner (require_owner_dashboard_request, 403owner_only, the same gate the integrated terminal routes use), the integrated terminal is enabled (403terminal_disabled), the request is direct-local (is_direct_local_request, the loopback-and-no-forwarding-headers rule the channel credential settings use; 403external_terminal_not_local), and an allowlisted app is picked indashboard.terminal.external_app(409external_terminal_not_configured; unset by default, and any non-allowlisted value reads as unset). The directory is resolved withrealpath(strict=True)and must be an existing directory (400external_terminal_bad_cwd). The answer is an opaque single-use grant (secrets.token_urlsafe(32), 30 s TTL, at most 16 outstanding) bound to the app id and the resolved directory.external-terminal:open, which passes the shell's local-dashboard sender gate (origin, the window's gateway is local, the primary port is this shell's gateway: the same three gates asdashboard:open-file). The main process then redeems the grant atPOST /api/terminal/external-grant, a machine-only route (listed in the strict internal paths; the handler re-checksinternal_authand loopback), over the same internal-secret channel the native browser panel drains on. A grant is honoured once and only while the picked app is still the one it names and the integrated terminal is still enabled.external-terminal.js(/Applications/<App>.app/Contents/MacOS/<exe>on macOS;/usr/bin,/bin,/usr/local/bin,/run/current-system/sw/bin,/snap/binon Linux), never PATH, never a request value. It re-validates the directory (realpath, is a directory) and callsspawn(bin, argv, {cwd, shell: false, detached: true, stdio: "ignore"})with the argv pinned per app (for example kitty--directory <dir>, WezTermstart --cwd <dir>, GNOME Terminal--working-directory=<dir>). Nothing from any request body becomes argv except the allowlisted app id, which selects the pinned entry. The path never reachesopen,shell.openPath,xdg-open,start, AppleScript or a shell string, so a directory swapped after the check can at worst change where the shell starts; a directory swapped for a file makes the child's chdir fail and the launch reports failure. Logs name the app only, never the directory or argv.dashboard.terminal.external_appis declared with the allowlist as its enum and added to the dashboard-editable keys as an enum, so the Settings picker can only write an allowlisted id.externalTerminalAPIpreload bridge exists), for a gateway on this machine (directLocal), with the integrated terminal served, once an app is picked and while the desktop shell still detects it installed; with nothing picked the menu is exactly as before. Hiding is a convenience; the gateway refuses the launch itself. The desktop shell answersexternal-terminal:detectfor a window it refuses (for example one reaching a remote crew through an SSH tunnel, which also reads as direct-local) with{apps: [], capable: false}instead of an error, so that window shows neither the row nor the picker and no error notice;external-terminal:openstill rejects it. A refused or failed launch opens the built-in terminal instead, and the side panel shows one note naming the app and why (turned off in Settings after the menu opened, no longer installed, not launchable from this window, or did not start; the first two each say what to do next and carry an Open Terminal settings link to the picker inside the note). The note is an error notice, because the launch failed even though a terminal did open; it is held by the side panel and sits in flow above the tab bodies, so it stays on screen after the terminal tab takes the Files tab out of view and never covers the shell. A failed read of the setting or of the installed apps is reported, with a Retry beside it, both in the Files tab and in Settings, rather than read as "nothing picked" or "nothing installed". For change cards the setting is one no value can widen: it names an allowlisted app, and only the owner's click starts it. With no supported app installed the picker says so and is disabled. Settings → Display → Terminal gains an External terminal app picker (desktop app, local gateway only) listing None plus the allowlisted apps the desktop shell detects installed; a stored pick that is no longer installed shows as None. Strings in every locale; the settings registry and UI index are regenerated.Rejected alternatives:
open -a <App> <dir>/shell.openPath: hands a validated pathname to an OS opener that re-resolves it later, the rename-race primitive behind the withdrawn "open project in editor" action.Backwards compatibility
Compatible:
dashboard.terminal.external_appis a new key, unset by default; with it unset the new route refuses and nothing that works today changes.Removes nothing: the change only adds two routes, one config key, two IPC channels, one preload bridge, one menu row and one Settings picker; no existing route, key, channel, row or default is narrowed or removed.
Tests
test/test_external_terminal_gate.py(gateway): one test per refusal (unauthenticated, not the owner, terminal disabled, each forwarding header, every non-allowlisted pick, a file / a symlink to a file / missing / relative path), each written to fail with its own check removed (verified by deleting each check in turn); the grant is single-use, needs the internal secret, expires, lapses when the pick changes, and is bounded; the body names no program; the Python allowlist equals the desktop allowlist; the schema key is unset by default with the allowlist as its enum; the editable-config entry is that enum; the redemption route is strict-internal and both routes are registered.website/electron/test/external-terminal.test.js: allowlist resolution (only fixed install paths are probed, never PATH or home; an id outside the allowlist never resolves; Ghostty has no macOS entry; no Windows entries), argv pinned per app, cwd and argv use the realpath, a file / missing / relative directory fails closed with no spawn, a spawn error or throw reportslaunch-failed, logs never carry the directory or argv, no opener or shell string in the source or reachable at run time, a grant is redeemed only with the internal secret at this shell's gateway, every gateway refusal or malformed answer starts nothing, and an approval is still re-checked here.website/electron/test/ipc-registrar.test.js:openrejects a wrong origin, a remote-gateway window and a foreign port owner before any launch;detectanswers each of those three{apps: [], capable: false}without probing and still logs the refusal, lists installed apps only for a local window, and still rejects when detection itself fails there;openpasses only the grant and redeems at this shell's own gateway with the internal secret.website/src/test/FilesHomePanel.externalTerminal.test.tsx: with no app picked (or an empty pick) the menu holds only the integrated terminal row and it still opens the integrated terminal (the default is unchanged); with an app picked the row appears below it on the desktop app, named by the detected label ("Open in WezTerm"), and is absent for a pick no longer installed, in the browser build, for a remote gateway, for a window the desktop shell answers as not capable (with no notice even when the setting read would fail, and no setting read at all), and when the host serves no integrated terminal; a click posts{cwd}to the gateway and hands only the grant to the bridge; a gateway refusal, a failed launch and a rejected bridge call each fall back to the integrated terminal and hand the host the note with the matching reason and whether it links to Settings; a failed detection or setting read is reported, and nothing is reported in the browser build.website/src/test/sidePanelExternalTerminalFallback.test.tsx: mounts the real side panel; after a failed launch the terminal tab is in front, the Files tab is out of view, and the note is still on screen, as an error notice (role="alert"), until dismissed; a note that sends the user to Settings carries, inside the notice, a link to Settings → Display → Terminal with the picker highlighted, and the link navigates there. Red against the side panel without the note. Red against the unchanged panel.website/src/test/DisplayPanel.externalTerminal.test.tsx: the picker reads None by default, lists only detected apps after None, saves the picked id, shows an uninstalled stored pick as None, says when nothing is installed and is then disabled, reports a failed detection instead of claiming nothing is installed and lists the apps after its Retry, and is absent with no error for a window the desktop shell answers as not capable, in the browser build and for a remote gateway.Manual verification
Rendered in a browser against the real components, with only the transport and the desktop bridge stubbed (screenshots below). The Project actions menu was retaken before the row's label changed to "Open in (separate window)"; the label is the only difference on it since; the fallback notes with their Settings link were retaken on the previous head, and this push (wording only) does not change them; the Settings detection failure with its Retry was retaken earlier, and this push does not change it; the rest show surfaces it leaves as they were. Screenshots cover: the menu with and without a pick, the fallback note for each of its four reasons, the failed-check notice with its Retry, and the Settings picker listing only detected apps, its nothing-installed state and its failed-detection state. Not run on a packaged desktop build on this host (no display): the launch itself is covered by the unit tests above with a recorded spawn and a recorded redemption.
Screenshots / video
Files tab → Project actions with kitty picked (dark). The row in this capture reads "Open in kitty (your terminal app)"; the label is now "Open in kitty (separate window)", and nothing else on the row changed. Its hint says it opens kitty, the terminal app picked in Settings, in a separate window in this project's folder. The menu is end-aligned to its trigger, so it extends left over the chat. The integrated terminal row above it is deliberately unchanged: the default menu is out of scope for this PR:
With nothing picked, the default: the menu is exactly as before (light):
A failed launch, on the previous head (this push changes only the row label, not these notes): the real side panel with the built-in terminal tab brought to the front and an error notice above it, one per reason (dark): the app did not start, the app was turned off in Settings after the menu opened, the app is no longer installed, and this window cannot open apps on this computer. The two notes that send the user to Settings carry an Open Terminal settings link to the picker inside the notice:
A failed check of the setting, reported in the Files tab with a Retry beside it (dark):
Settings → Display → Terminal → External terminal app, listing only detected apps (light), with no supported app installed (dark), and, on an earlier head, when detection fails, with its Retry (dark), and the picker enabled after that Retry succeeds (dark):
Other theme
Related Issues
Fixes #2877
Checklist
Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.