Skip to content

feat(terminal): open the project in an allowlisted external terminal app - #19600

Merged
cruisercohen merged 2 commits into
mainfrom
fix/2877-external-terminal
Oct 16, 2026
Merged

cruisercohen merged 2 commits into
mainfrom
fix/2877-external-terminal

Conversation

@cruisercohen

@cruisercohen cruisercohen commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

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 cd by 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

  • Rerouting the existing Terminal button by configuration (the issue's "same button" shape). The integrated terminal, its button and its PTY are unchanged; the external terminal is a separate, explicit row.
  • A gateway-side launch for a browser on the same machine. The gateway approves; only the desktop app's main process starts anything.
  • Apps that cannot be started with a working-directory argument or cwd: Terminal.app and iTerm2 (both need AppleScript), Ghostty on macOS (only open -na starts it), Warp (a URL scheme). They are left out rather than reached through an OS opener.
  • Windows. Windows Terminal is reached only through an alias in a user-writable directory, and the console-host launch shape is not verified, so Windows has no entry.
  • A free-form or custom app path. The allowlist is the only source of the binary.

What changed (motivation → approach → change)

Design note (the launch boundary). Adds a local-only launch boundary; a maintainer should confirm it.

  • The gateway is the gate. 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, 403 owner_only, the same gate the integrated terminal routes use), the integrated terminal is enabled (403 terminal_disabled), the request is direct-local (is_direct_local_request, the loopback-and-no-forwarding-headers rule the channel credential settings use; 403 external_terminal_not_local), and an allowlisted app is picked in dashboard.terminal.external_app (409 external_terminal_not_configured; unset by default, and any non-allowlisted value reads as unset). The directory is resolved with realpath(strict=True) and must be an existing directory (400 external_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.
  • The desktop main process acts only on that approval. The renderer hands the grant to 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 as dashboard:open-file). The main process then redeems the grant at POST /api/terminal/external-grant, a machine-only route (listed in the strict internal paths; the handler re-checks internal_auth and 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.
  • The launch. The main process resolves the app id to the app's OWN executable from fixed absolute install paths in external-terminal.js (/Applications/<App>.app/Contents/MacOS/<exe> on macOS; /usr/bin, /bin, /usr/local/bin, /run/current-system/sw/bin, /snap/bin on Linux), never PATH, never a request value. It re-validates the directory (realpath, is a directory) and calls spawn(bin, argv, {cwd, shell: false, detached: true, stdio: "ignore"}) with the argv pinned per app (for example kitty --directory <dir>, WezTerm start --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 reaches open, 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.
  • Config: dashboard.terminal.external_app is 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.
  • UI: the Files tab's Project actions menu gains Open in (separate window) (for example Open in kitty (separate window), with the hint "In a separate window: opens kitty, the terminal app you picked in Settings, in this project’s folder.") below the unchanged Open terminal in the project directory row. It shows only in the desktop app (the externalTerminalAPI preload 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 answers external-terminal:detect for 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:open still 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:

  • B, the issue's "same Terminal button routed by config": hides a new external launch behind a familiar button, with the same boundary work.
  • C, a gateway-side launch for loopback browsers: a server process starting GUI apps, confusing on any shared install.
  • 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.
  • Keeping the pick only in the desktop app's own store and launching from the main process alone: no server-side check of owner, locality or opt-in.

Backwards compatibility

Compatible: dashboard.terminal.external_app is 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 reports launch-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: open rejects a wrong origin, a remote-gateway window and a foreign port owner before any launch; detect answers 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; open passes 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:

Project actions with kitty picked

With nothing picked, the default: the menu is exactly as before (light):

Project actions with nothing picked, unchanged

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:

Fallback note: the app did not start

Fallback note: the app was turned off in Settings, with the Open Terminal settings link

Fallback note: the app is no longer installed, with the Open Terminal settings link

Fallback note: this window cannot open apps on this computer

A failed check of the setting, reported in the Files tab with a Retry beside it (dark):

Files tab reporting that the terminal app setting could not be loaded, with Retry

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):

External terminal app picker listing None and the detected apps

External terminal app picker with no supported app installed

External terminal app picker when detection fails, with Retry

External terminal app picker enabled after Retry

Other theme

Project actions with kitty picked, light

Project actions with nothing picked, dark

Fallback note: the app did not start, light

Fallback note: the app was turned off in Settings, with the link, light

Failed check with Retry, light

External terminal app picker, dark

No supported app installed, light

Detection failed, with Retry, light

Picker enabled after Retry, light

Related Issues

Fixes #2877

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (feature map row, setting help text)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 12, 2026
@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 52a2ca07a234aee1ffb538582d68d7ba4664e586 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 SidePanel.tsx that has to outlive the Files tab.

Not justified as shipped

  • Item 6 — oversized: The Goal is "open their own terminal app … as an opt-in action". When that launch fails, the diff opens the integrated terminal anyway ("A refused or failed launch opens the built-in terminal instead"). Because that switch hides the Files tab, the note has to move up into SidePanel.tsx ("held by the side panel … stays on screen after the terminal tab takes the Files tab out of view"). Nothing explains why someone who asked for kitty should get the integrated panel. The existing Open terminal in the project directory row is one line above.
    Subtraction: delete the fallback-to-integrated-terminal branch and the SidePanel.tsx note (and sidePanelExternalTerminalFallback.test.tsx). Show the failure reason inline in the Files tab where the click happened.
    Clears when: the fallback and the side-panel note are removed, or a reported case shows a failed external launch needs a shell opened without the user choosing it.

What this change ships

Inventory (8 items) — 7 justified

Intent: a desktop-app user opens their own terminal emulator in the project folder. ADDITION.

  1. New Files-tab menu row "Open in ", shown only when an app is picked — justified
  2. Settings → Display → Terminal gains an "External terminal app" picker — justified
  3. New config key dashboard.terminal.external_app (enum, unset by default) — justified
  4. New owner-only, local-only approval route POST /api/terminal/external that hands out single-use grants — justified
  5. New machine-only route where the desktop shell redeems a grant and starts the allowlisted app with a fixed argument list — justified
  6. A failed launch opens the built-in terminal plus a side-panel note — oversized: fallback has no stated need
  7. Retry controls when reading the setting or the installed apps fails — justified
  8. The key is listed as a setting no value can widen, for change cards — justified

[FIRST-PRINCIPLES-REVIEWED] 52a2ca0

Description read

[DESCRIPTION-READ] 3a3b17f6f4b324abeeacd61351b4eb1772b4e9d31944b7dfe94ec866272267c8

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 52a2ca07a234aee1ffb538582d68d7ba4664e586 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • Linux detection only looks in root-owned system directories, so Ghostty or WezTerm installed under ~/.local/bin, as an AppImage or through Flatpak never shows up. That is intended. To stop it reading as a bug, make the picker's "no supported app installed" text name the directories it checked.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ human override accepted

@cruisercohen overrode this lane for 52a2ca07a234aee1ffb538582d68d7ba4664e586 via /ai-review override (this commit only).

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 12, 2026
@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 52a2ca07a234aee1ffb538582d68d7ba4664e586 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 52a2ca0

Verdict parsed from the review's SHA-scoped output markers for commit 52a2ca07a234aee1ffb538582d68d7ba4664e586.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 52a2ca07a234aee1ffb538582d68d7ba4664e586: <one-sentence reason>

@cruisercohen
cruisercohen force-pushed the fix/2877-external-terminal branch from 1a1051b to 7407679 Compare October 12, 2026 23:33
@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 52a2ca07a234aee1ffb538582d68d7ba4664e586 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 52a2ca0

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 52a2ca07a234aee1ffb538582d68d7ba4664e586: <one-sentence reason>

@cruisercohen

Copy link
Copy Markdown
Contributor Author

Addressed the UX review on 7407679a25:

  • The row names the app. Its label is now "Open in " from the display label the desktop shell detects (for example "Open in kitty"), with the hint "Opens in its own window, in this project’s folder." Test: names the picked app by the label the desktop shell detected.
  • A pick that is no longer installed shows no row. The row appears only while the desktop shell still detects the picked app, matching the Settings picker, which shows such a pick as None. Test: shows no row for a pick that is no longer installed.
  • The picker's help text names what is on screen: "Adds a row to the ⋯ menu in the Files tab that opens this app in the project’s folder."
  • The fallback note names the app: "Couldn't open kitty, so the built-in terminal opened instead."
  • Evidence: the description now carries screenshots of the fallback note after a failed launch and of the picker with no supported app installed, in both themes.

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 leaves the Project actions menu and its terminal row exactly as they were), and the new row's app name is what tells the two apart.

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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 12, 2026
@cruisercohen
cruisercohen force-pushed the fix/2877-external-terminal branch from 7407679 to 1ed420b Compare October 13, 2026 00:11
@cruisercohen

Copy link
Copy Markdown
Contributor Author

Addressed the second UX review on 1ed420bb5e:

  • The row says it is a terminal app. The label stays "Open in kitty" (the app's own name, as the first review asked), and the hint under it now reads "Your own terminal app, in a separate window, in this project’s folder." I did not put "terminal" into the label itself: two allowlisted apps are named GNOME Terminal and Xfce Terminal, so a templated " terminal" label would read "Open in GNOME Terminal terminal".
  • The fallback note gives the reason from the launch result, one sentence each: "kitty is no longer picked or installed, …", "This window can't open apps on this computer, …", or "kitty didn't start, …", each ending "so the terminal opened in a new tab here instead." That also says where the integrated terminal opened. Tests: falls back to the integrated terminal when the gateway refuses, … when the launch fails, says the app is gone when the gateway finds no app picked.
  • The picker is disabled when no supported app is installed, under the "No supported terminal app was found on this computer." line. Test: says so when no supported app is installed.
  • Screenshots in the description are re-captured for this head (menu, fallback note, picker, nothing-installed state).

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.

@cruisercohen
cruisercohen force-pushed the fix/2877-external-terminal branch from 1ed420b to fa6ad2c Compare October 13, 2026 00:30
@cruisercohen

Copy link
Copy Markdown
Contributor Author

Addressed the GPT 6.1 findings on fa6ad2c4c2:

  • F1, a failed lookup read as "nothing installed". detectExternalTerminals now rejects when the desktop shell refuses or answers without an app list (it returns empty only in a browser tab, where there is no bridge). Settings shows "Couldn't check which terminal apps are installed on this computer." on a failed detection and keeps "No supported terminal app was found…" for a successful empty answer. The Files tab reports a failed setting read or a failed detection with "Couldn't check the external terminal app, so its row may be missing from the ⋯ menu." (hand-off on, as for the tab's reveal failure: the Files tab holds no draft). Tests: reports a failed detection instead of claiming nothing is installed, reports a failed detection instead of silently dropping the row, reports a failed setting read the same way, reports nothing in the browser build, where nothing is checked.
  • F2, the fallback note unmounted with the Files tab. The note now belongs to the side panel: the Files tab hands it over through onExternalTerminalFailed before it opens the integrated terminal, and the side panel renders it in flow above the tab bodies (so it does not cover the shell), until dismissed. No hand-off there: the adjacent chat composer can hold unsent text. Test: sidePanelExternalTerminalFallback.test.tsx mounts the real side panel and checks the note is still on screen with the terminal tab in front and the Files tab out of view; it fails against the side panel without this change. The description carries a screenshot of that state.

@cruisercohen
cruisercohen force-pushed the fix/2877-external-terminal branch from fa6ad2c to 8ba5781 Compare October 13, 2026 01:08
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 13, 2026
@cruisercohen
cruisercohen force-pushed the fix/2877-external-terminal branch from 8ba5781 to fa305fa Compare October 13, 2026 01:48
@cruisercohen

Copy link
Copy Markdown
Contributor Author

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 8ba5781c5b to fa305fabbb. The first commit is untouched.

  • The "Open in " hint now says it is "The terminal app you picked in Settings". This was the blocking UX finding.
  • The check-failed notice now says plainly that the option is hidden. It also gets a Refresh button beside it that re-runs both checks, reusing the existing "Refresh" string.
  • The Settings description no longer calls the menu entry a "row".
  • These three strings are updated in en.manual.json, en-XA and all 11 translated catalogs.
  • FilesHomePanel.externalTerminal.test.tsx now asserts the new hint and notice text. A new test makes the first detection fail, clicks Refresh, and asserts that detection runs again and the row then appears.

The files touched are FilesHomePanel.tsx, its external-terminal test, and the 13 locale files. No gateway, Electron launcher, allowlist or security-gate code changed.

@cruisercohen
cruisercohen force-pushed the fix/2877-external-terminal branch from fa305fa to 3291b61 Compare October 13, 2026 02:28
@cruisercohen

Copy link
Copy Markdown
Contributor Author

Answered the UX review on fa305fabbb by folding the fix into the second commit, which keeps the PR at the 2-commit cap. Because the fold hides the diff, here is exactly what changed from fa305fabbb to 3291b6170a. The first commit is untouched.

  • Retry, not Refresh. The button beside the check-failed notice now says "Retry". It re-runs only the two checks, so it no longer reads like the file list's own refresh. It uses a new filesHome.retry key whose value in each locale is copied from that locale's existing "Retry" string (the informal form in bn and hi). The external-terminal test now clicks "Retry", and fails against the old label.
  • Screenshots. The description now has 16 stills, all taken on this head:
    • the new menu hint and the new check-failed copy with Retry;
    • the new Settings description;
    • the Settings failed-detection state;
    • the fallback note for all three reasons: did not start, no longer picked or installed, and not launchable from this window.

The files touched are FilesHomePanel.tsx, its external-terminal test, and the 13 locale files. No gateway, Electron launcher, allowlist or security-gate code changed.

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".

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 13, 2026
@cruisercohen
cruisercohen force-pushed the fix/2877-external-terminal branch from 3291b61 to 1bc2111 Compare October 13, 2026 02:52
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 13, 2026
@cruisercohen
cruisercohen force-pushed the fix/2877-external-terminal branch from 56881d8 to cdec78a Compare October 13, 2026 19:27
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 13, 2026
@cruisercohen

Copy link
Copy Markdown
Contributor Author

@iamwhatever the review points on 56881d8874 are addressed on the new head cdec78a3b6f5f5b45534e9065f79b094e3a990ec. This is the last push of this round.

The fold: I folded the change into the second commit, so the PR still has 2 commits. git range-diff shows the first commit (469554817a) unchanged. The fold changes only:

  • copy in the 13 locale files (en-XA regenerated) and the feature-map row;
  • the side panel's fallback note;
  • the two tests that pin those.

Launch behaviour is unchanged: the desktop detect/open handlers, the gateway's launch and grant routes, grant redemption and their audit records are untouched.

Dispositions:

  1. Opus 5.5 and GPT 6.1 lanes, errors-use-error-notice (side panel fallback note): fixed. A refused or failed launch now shows in an ErrorNotice (role="alert") instead of a warn-toned StatusNotice. I kept the no-hand-off decision, because the chat composer next to it can hold unsent text. This reverses the earlier warning tone, which I had chosen after a UX-lane concern; the blocking rule takes precedence.
  2. UX Review blocker, the row doesn't say it is the app you picked: fixed. The hint now reads "In a separate window: opens kitty, the terminal app you picked in Settings, in this project's folder." This is in every locale.
  3. UX Watch, the Settings link floats outside the notice: fixed. "Open Terminal settings" is now inside the error notice, as its footer.
  4. UX Watch, the "no longer picked" note reads as a contradiction: fixed. It now reads "kitty was turned off in Settings after this menu opened, so the built-in terminal opened in a new tab instead. To use it, pick it again in Settings → Display → Terminal." The feature-map row matches.
  5. UX Watch, the two menu rows look like the same thing: fixed. The new hint starts with the difference: "In a separate window:".
  6. UX suggestion, name the "External terminal app" label in the notes: not taken. The two notes that send the user to Settings now carry a link, inside the notice, that opens Settings → Display → Terminal with the External terminal app picker highlighted. The user lands on the control without having to look for its label. This last push was also scoped to the blocker and the three Watch items. I can add the label in a follow-up if you'd like it.

Tests:

  • The external-terminal suites (side panel, Files tab, Settings picker) pass, 34/34.
  • Red without the fix: I reverted the side panel change and kept the updated tests. The 2 side-panel tests fail (the note must be role="alert", and the link must be inside the notice).
  • Type check, eslint, i18n:check and the UI index generator are clean.

Screenshots: I retook the Project actions menu (dark and light) and the fallback notes (all four reasons in dark, two in light) at cdec78a3b6, then swapped them into the description. The longer hint makes the menu wider than the side panel. It is aligned to its trigger, so it extends left over the chat, and the menu shots use a wider window to show it whole. The Settings picker shots are unchanged, because this push doesn't touch the picker.

Auto-merge stays armed.

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 13, 2026
@cruisercohen
cruisercohen force-pushed the fix/2877-external-terminal branch from cdec78a to 2895f2c Compare October 13, 2026 20:28
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 13, 2026
@cruisercohen

cruisercohen commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor Author

Dispositions for head 6de3f8dd50d4e3ba09b1af6e3b85135f254f05bb:

  • GPT 6.1, frontend-tests-are-deterministic (fixed): every wait for the external terminal row in the Files tab and side-panel fallback suites now uses one named timeout, EXTERNAL_ROW_WAIT = { timeout: 5000 }, with a comment naming the chain it waits on (detection answers capable, then the config read runs, then the row renders). Test files only, no product code change.
  • Rebase: rebased onto current main to clear a conflict in the generated UI index (main version taken, generator re-run). Commit 1 is unchanged and commit 2 differs only in that generated file; the PR still has 2 commits.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

New head 4f8af4cd6ff83009a11e9d5ca2a3f4e586b73c65 (wording only, folded into the second commit; the first commit is unchanged and the PR still has 2 commits):

  • UX Review block (the row does not say what kind of app it opens): fixed. The row now reads "Open in {{app}} (your terminal app)", for example "Open in kitty (your terminal app)", in all 13 locales (en-XA regenerated).
  • Setting help text: fixed. The External terminal app setting's help now says it adds "Open in " to the Project actions menu, instead of "Open in external terminal", so it matches what the menu shows. The config baseline is regenerated.

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.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

Pushed 0d7636ee52656c1e324ccaab05c0c3b576c1d945, test-only, folded into the second commit (the first commit is unchanged). GPT 6.1 frontend-tests-are-deterministic finding (the two config-call waits and the config-failure notice wait used the default timeout): fixed. Every waitFor and findBy* in the three external-terminal test suites, 57 call sites, now passes the named EXTERNAL_ROW_WAIT ceiling, and each suite comments the chains those waits sit behind. No product code change.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

Rebased onto main only, no code change. New head: b88569f.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

@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 {apps: [], capable: false} without throwing, in electron/ipc-registrar.js, test "external-terminal:detect answers a window that is not the local dashboard as not capable" (ipc-registrar.test.js); (2) the Files tab hides the row with no notice, in FilesHomePanel.tsx, tests "is absent, with no notice, for a window the desktop shell answers as not capable" and "reports no failed setting read for a window the desktop shell answers as not capable" (FilesHomePanel.externalTerminal.test.tsx); (3) Settings hides the picker with no error, in DisplayPanel.tsx, test "is absent, with no error, for a window the desktop shell answers as not capable" (DisplayPanel.externalTerminal.test.tsx); (4) the UX concerns: the Settings detection error now has a Retry (same file, test "retries a failed detection from its notice and then lists the apps"), and the fallback note is an ErrorNotice with the Settings link inside it, as the blocking errors-use-error-notice rule requires, in SidePanel.tsx, test "links a note that sends the user to Settings straight to the terminal app picker" (sidePanelExternalTerminalFallback.test.tsx).

@cruisercohen

Copy link
Copy Markdown
Contributor Author

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.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

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.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

/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.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@cruisercohen marked the ux AI finding as false positive, not applicable, or explicitly accepted for ac2465c490a4083e0b03921c741885c9f3e09b4a.

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.

This decision applies only to this commit. A new push requires a new judgment.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

@iamwhatever where each point of your change request stands on the current head ac2465c490a4083e0b03921c741885c9f3e09b4a. This head is a rebase of b88569f onto current main with no code change: git range-diff shows commit 1 differing only in a context line main moved in the feature map, and commit 2 only in the generated UI index header.

  1. detect on a desktop window reaching a remote crew through an SSH tunnel: fixed as you proposed. external-terminal:detect still runs the three-gate local-dashboard check, and logs the refusal, before probing anything. A refused window now gets { apps: [], capable: false } instead of an error. A local window gets { apps, capable: true }. external-terminal:open still rejects a non-local window at the same gate. The gateway's launch and grant routes are unchanged. Code: electron/ipc-registrar.js. Test: "external-terminal:detect answers a window that is not the local dashboard as not capable" (ipc-registrar.test.js). It covers a remote origin, a remote gateway behind a tunnel, and a foreign port holder.
  2. No new notice on the Files tab for that window: fixed. The renderer reads capable: false as "not capable". It shows no row and no notice, and it skips the config read. Code: FilesHomePanel.tsx. Tests: "is absent, with no notice, for a window the desktop shell answers as not capable" and "reports no failed setting read for a window the desktop shell answers as not capable" (FilesHomePanel.externalTerminal.test.tsx).
  3. No detection error in Settings for that window: fixed. The picker waits for the shell's answer. A not-capable window shows no picker and no error. Code: DisplayPanel.tsx. Test: "is absent, with no error, for a window the desktop shell answers as not capable" (DisplayPanel.externalTerminal.test.tsx).
  4. The UX CONCERNS with no disposition: answered.
    • No Retry in Settings: fixed. A failed detection in Settings now has a Retry that runs detection again. Test: "retries a failed detection from its notice and then lists the apps" (same file).
    • The red fallback note: it stays an ErrorNotice. I first moved it to a warning tone. The blocking errors-use-error-notice rule then required an error notice, because the launch did fail, so I reversed that. The notes that send the user to Settings carry an "Open Terminal settings" link inside the notice. The link opens Settings → Display → Terminal with the picker highlighted. Test: "links a note that sends the user to Settings straight to the terminal app picker" (sidePanelExternalTerminalFallback.test.tsx).

All checks are green on this head, and auto-merge is armed. Could you take another look?

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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)

@cruisercohen

Copy link
Copy Markdown
Contributor Author

Fixed at a259f7f, folded into the first commit (6747443); the second commit is unchanged.

getSecret called with no URL. Confirmed: redeemGrant calls getSecret() with no argument, so passing readInternalSecret directly read the secret for an undefined gateway URL and redeemed with "". The registrar now passes getSecret: () => readInternalSecret(backendUrl) (website/electron/ipc-registrar.js line 512).

Test. The registrar harness stub for readInternalSecret now behaves like the real one: it records the URL it is asked for and returns the secret only for the shell's own gateway URL. A new test, external-terminal:open reads the internal secret for this shell's own gateway URL, calls getSecret() the way redeemGrant does and asserts both the secret and that the read named http://localhost:5476. On ac2465c that test and the existing grant test both fail with actual: ''; on this head the electron suite passes (2446 tests, 0 failures).

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.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 59eb987 (conflict-only: main added onOpenFolder beside this PR's onExternalTerminalFailed prop in FilesHomePanel.tsx and SidePanel.tsx; both are kept). The first commit is unchanged, and the second differs from a259f7f only in those resolved lines. Here is where each point of the r106 review stands on this head.

  1. Earlier change request (external-terminal:detect on a non-local window, rows hidden without a notice). Unchanged from the head you confirmed.
  2. getSecret called with no URL. Fixed in the first commit (dc7d5954e9): the registrar passes getSecret: () => readInternalSecret(backendUrl), and the registrar test stub returns the secret only for the gateway URL it is asked for. That test fails on ac2465c with actual: '' and passes here, and the two desktop test files that cover the launch pass 64 of 64.
  3. Human review of the new launch boundary. Agreed that the gateway grant, the strict internal-secret redeem route and the main-process spawn need a human maintainer's review. Could a maintainer review that path on this head?

@cruisercohen

Copy link
Copy Markdown
Contributor Author

fixed

  • Evidence gap: no screenshot of the save-failure notice

Covered by a new test at fd879da: says so when saving the pick fails, and keeps the picker usable in website/src/test/DisplayPanel.externalTerminal.test.tsx.
It makes the config write reject, picks kitty, and asserts "Could not save the external terminal app" renders; it then asserts the picker is still enabled and that a second pick writes again.
With the save's onFailure wiring removed the test fails because the notice never renders. No production code changed.

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
@cruisercohen

Copy link
Copy Markdown
Contributor Author

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.

  • EXTERNAL_TERMINAL_APPS and the dashboard.terminal.external_app settings entry now live in config/sections_dashboard.py. config/sections.py re-exports EXTERNAL_TERMINAL_APPS alongside the other names it binds. The help-text line from commit 2 is in that same entry.
  • One copy change, from UX Review's suggestion: the row label is now "Open in {{app}} (separate window)" in every locale, with "(separate window)" in each locale's existing wording. The tests that find the row by its label, and the feature map, now use the new label. The PR body now notes that the menu screenshots were taken before this label change.
  • Checked on this head: the config, settings-registry and UI-index generators leave the tree unchanged. Python 168 passed (external-terminal gate, config schema and module boundaries, sections facade), desktop 64/64, and the web i18n and external-terminal tests 1095 passed. black, flake8, isort, mypy, tsc and eslint are clean.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

/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.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@cruisercohen marked the ux AI finding as false positive, not applicable, or explicitly accepted for 52a2ca07a234aee1ffb538582d68d7ba4664e586.

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.

This decision applies only to this commit. A new push requires a new judgment.

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.

Option to open an external terminal app in place of the integrated panel (IntelliJ-style)

2 participants