Skip to content

fix(terminal): answer run-in-terminal from every route, not only chat - #10708

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
nathanyi96:fix/run-in-terminal-shell-level
Oct 22, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
nathanyi96:fix/run-in-terminal-shell-level

Conversation

@nathanyi96

@nathanyi96 nathanyi96 commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make the existing mc:run-in-terminal action work from every dashboard route, not only /chat.

"Run in terminal" only worked from the Chat page. On /apps/<id>, /projects, or /settings, the request had no receiver, so no terminal tab opened and the caller eventually reported that no terminal was available.

Why it matters

The dock terminal is app-wide, and app panels use this event to run a command in the user's own shell. Requiring callers to navigate to /chat first introduced visible flicker and a race with the lazy Chat chunk, while still providing no benefit to the dock.

Not a goal

  • Changing the RunInTerminalBtn confirmation or sensitive-command checks.
  • Adding a new terminal API or changing the mc:run-in-terminal event contract.
  • Changing dock terminal limits, PTY behavior, terminal rendering, or command formatting.

What changed (motivation → approach → change)

A shell code block outside every chat (an app page, a knowledge doc) sends a run request with no scope. Since #16358, only the chat page answers those, so off /chat the button still times out.

This rebuild sits on #16358's shared hook, website/src/hooks/useRunInTerminalBridge.ts, instead of adding a second one. The hook gains an unscopedFallback option. The app shell calls website/src/shell/runInTerminalShellBridge.tsx, one more receiver that answers unscoped requests in the selected session's project, in the main window only (popout and embed windows have no dock). It stands down while the chat page is mounted. So one click opens one terminal on every route.

The chat page keeps its own unscoped answer on purpose. On /chat its failures show above the composer with an Ask Agent hand-off, which is safe there. The shell notice must be dismiss-only, because it can sit over an unsaved edit. The chat page also answers inside embed windows, where no shell receiver runs.

Failures from that receiver show in a notice fixed at the top of the page, since the page under it can be any route. The next successful run clears it, except the notice that the reuse setting could not be read, which a successful run does not fix. The notice can only be dismissed: an Ask Agent hand-off would navigate to chat and could drop an unsaved edit on the current page.

Backwards compatibility

Compatible: the mc:run-in-terminal request and result events are unchanged, and the chat and Crewmates pages answer exactly the requests they did before.

Removes nothing: the change only adds a receiver for requests that had none.

Tests

  • website/src/test/RunInTerminalShellBridge.test.tsx: an unscoped run opens one dock terminal in the selected project, or the server default with no project; a request scoped to another host, an empty command and a missing command are ignored; with a chat-page stand-in mounted, one click opens one terminal (the chat page's), and after it unmounts the shell answers again; a window with no dock answers nothing; a full terminal cap answers ok: false and shows a dismiss-only notice; a later successful run clears that notice, another failure keeps it, and a config-read failure notice survives its own successful run.
  • website/src/test/App.terminalNavActive.test.tsx: on /logs (no chat page), an unscoped run opens the dock terminal. Red on main without the App.tsx mount, green with it.
  • Determinism: both files ran 3 times in a row plus once with --sequence.shuffle, all green.

Manual verification

N/A — the receiver is covered by the tests above, and the notice is shown below in the desktop and mobile layouts.

Screenshots / video

The new terminal-dispatch failure notice, over the Logs page:

Terminal dispatch failure notice — desktop

Terminal dispatch failure notice — mobile

Related Issues

No linked issue — this was found while wiring an app panel's existing "Run in terminal" button and tracing why its dispatch was dropped outside /chat. Builds on #16358, which handles the Crewmates page and lists this PR as the owner of routes with no chat.

Pattern harvest

Rule candidate: review-prompt
Pattern: a shell-level event listener mounted by a route page leaves the event without a receiver on every other route.

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 (if applicable) — N/A, the receiver location is an implementation detail
  • No secrets, credentials, or internal references in the diff

@nathanyi96
nathanyi96 requested review from a team and hoang-phan98 September 14, 2026 05:24
@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Sep 14, 2026
@nathanyi96

Copy link
Copy Markdown
Contributor Author

Intent: Make mc:run-in-terminal work from every dashboard route by mounting its listener at the shell (App) instead of ChatPage, with no change to what the listener does.
Not a goal: Changing how the dock terminal is scoped, capped, or rendered; adding a new API for apps; touching the RunInTerminal button itself.

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

github-actions Bot commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 97b619a25774565714c9137589e65a264ef238e7 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

In the screenshot, the fixed z-[80] notice covers the page title and part of the top bar. Check it doesn't hide controls a user needs before dismissing it.

[DESIGN-REVIEWED] 97b619a

Description read

[DESCRIPTION-READ] 9fa8b9c953d540f09db83abc8496d1d3fe8c31d63daa7cbf4dad41fb53edd9c9

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 Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 97b619a25774565714c9137589e65a264ef238e7 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 97b619a

@github-actions

github-actions Bot commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — 🟡 CONCERNS

UX-level review of 97b619a25774565714c9137589e65a264ef238e7 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

The new failure notice is fixed over the top bar and page header. It stays until dismissed and covers whatever controls sit under it on any route.

Watch

  • Notice covers page chrome. The diff places it with fixed left-1/2 top-safe-offset-3 z-[80] w-[min(640px,…)] on every route. In attachment-01 it hides the "Live Logs" title and runs into the top bar's status icons. In attachment-02 (mobile) it covers the page title entirely. It only goes away on dismiss or on a later successful run, so on pages whose header holds actions (apps, artifacts) the user has to close it before they can use them. Severity: low frequency (failures only) × moderate friction × lasts until dismissed. Smallest fix: anchor it below the top bar or the page header so it doesn't overlap them, or render it in the region just above the dock terminal, where the failed run happened.
  • Not cold-read. This fork lane has no blind read, so nobody has checked whether a first-time reader understands the notice's copy and dismiss-only behaviour. That caps the verdict at CONCERNS.

[UX-REVIEWED] 97b619a

Description read

[DESCRIPTION-READ] 2928489d77051fc21f7df1481d51d09aa615f5ffe073fdf12e4066d487e60cfb

That sha256 names everything this verdict read: the PR description, plus the 5 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 Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 97b619a25774565714c9137589e65a264ef238e7 via the fork AI-review pipeline — 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: PASS

Check whether the chat page should stay an unscoped receiver. Keeping it is the only reason the module-level unscopedHosts counter exists.

What this change ships

Inventory (6 items) — 6 justified

Intent: let a user press "Run in terminal" on a code block on any dashboard route and get a dock terminal, with no detour through /chat. FIX: App.terminalNavActive.test.tsx is described as red on main.

  1. "Run in terminal" from a code block on /apps, /logs, /settings and other non-chat routes now opens one dock terminal in the selected session's project — justified
  2. A failed run off-chat shows a "Couldn't run in terminal" notice pinned to the top of the page, which can only be dismissed — justified
  3. The next successful run clears that notice, except the notice that the reuse setting could not be read — justified
  4. While the chat page is mounted, the shell receiver stays silent, so one click opens one terminal (unscopedFallback plus a counter of mounted unscoped hosts) — justified
  5. Popout and embed windows run nothing from the shell receiver, since they have no dock — justified
  6. New unscopedFallback option on the shared useRunInTerminalBridge hook (one consumer, a boolean) — justified

[FIRST-PRINCIPLES-REVIEWED] 97b619a

Description read

[DESCRIPTION-READ] 7ce17538363a7e27b28ec0dc4b860810097b55634818df6c91f03d4f385c47ae

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 Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 97b619a25774565714c9137589e65a264ef238e7 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 97b619a

@nathanyi96
nathanyi96 force-pushed the fix/run-in-terminal-shell-level branch from 7d04761 to 04a8729 Compare September 14, 2026 05:43
@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 Sep 14, 2026
@nathanyi96

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: bridge answers ok:false immediately in windows without a dock (popout/embed) instead of not listening there

  • Popout/embed: answer ok:false immediately instead of leaving the request unanswered — fixed in 04a8729.

The !isPopout && !isEmbed guard no longer skips installing the listener. It now selects between two answers: with a dock, mint a tab and race the PTY as before; without one, emit(false) at once and mint nothing (useRunInTerminalBridge.ts, hasDock param).
The requester therefore sees its failure state immediately in popout/embed windows rather than after its own 8 s fallback. The settled latch still guarantees exactly one answer per request.
Pinned by the hasDock=false test: immediate {reqId, ok:false}, zero tabs, and no second answer after the timeout window.

@nathanyi96
nathanyi96 force-pushed the fix/run-in-terminal-shell-level branch from 04a8729 to 652d55e Compare September 14, 2026 07:21
@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 Sep 14, 2026
@nathanyi96
nathanyi96 force-pushed the fix/run-in-terminal-shell-level branch from 652d55e to b56ec4e Compare September 14, 2026 08:17
@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 Sep 14, 2026
@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 Sep 15, 2026
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Sep 15, 2026
@iamwhatever

iamwhatever commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor
  • Is the chat page unmounted on other routes? — verified, yes.

App.tsx renders ChatPage only as the element of /chat/:slug? (and the two /embed routes); there is no keep-alive wrapper, so leaving /chat unmounts it and its cleanup drops the counter to 0.
App.terminalNavActive.test.tsx 'answers Run in terminal on a route with no chat page' renders App on /logs and sees the dock terminal open; it is red on main without the shell mount.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 20, 2026
@iamwhatever
iamwhatever force-pushed the fix/run-in-terminal-shell-level branch from 4db9d29 to ed488ad Compare October 20, 2026 04:42
@iamwhatever

Copy link
Copy Markdown
Contributor
  • span=981d6938c10b Old error outlives a successful retry — fixed in ed488ad.

The shell bridge now listens for mc:run-in-terminal-result and clears its notice on any ok:true answer; another failure keeps it.
Pinned by RunInTerminalShellBridge.test.tsx 'clears the failure notice once a later run succeeds, and keeps it on another failure'.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • span=3b64b48d402b The notice covers the page title — rebutted.

It shows only after a failed run, has a dismiss button, and now also clears on the next successful run (ed488ad).
It covers the page heading, not a control needed to recover; the dock terminal it talks about sits at the bottom, uncovered.
A top-centre fixed notice is where the shell already shows route-independent notices; moving it is a placement change outside this PR's goal.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • span=f70e41217c9b No blind reader has read the copy — rebutted.

The notice adds no new strings: every message is an existing pages.chatPage.run_in_terminal_* i18n string the chat page already ships for these same failures.
This PR changes where those strings show, not what they say; rewording them would change the chat page too and is outside the goal.

@iamwhatever

iamwhatever commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor
  • Remote-instance panes and the module-level counter — verified.

InstancesViewport renders each remote dashboard in a cross-origin iframe (same SPA, tunnel port): a separate document with its own module state, its own App, its own dock and its own shell receiver.
A chat page and a code block in that pane talk to that pane's receivers only, since window events do not cross documents.
So the counter needs to be per-document, which a module-level variable is.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor
  • span=b57aa9777e1d Shell ErrorNotice turns off Ask Agent without a No hand-off comment — fixed in 18e98b0.

Added a {/* No hand-off: ... */} comment above the notice naming the draft it protects: /artifacts/'s document editor with unsaved edits (ArtifactDetailPage's dirty edit buffer, which navigating away destroys); Ask Agent navigates to /chat and would discard it.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • span=336b45ac9018 The notice covers page chrome — rebutted.

It shows only after a failed run, has a dismiss button, and clears itself on the next successful run.
It covers the heading area, not the control needed to recover: the dock terminal it talks about sits at the bottom, uncovered.
Reserving layout space for a rare failure would shift every page; that is a placement change outside this PR's goal.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • span=5f96dc0cd2dc The notice follows the user to other pages — rebutted.

By design: the failure is about the app-wide dock terminal, which also stays across routes, and the probe can fail seconds after the click, often after the user moved on.
Clearing on navigation would hide exactly those late failures, the silent outcome errors-use-error-notice exists to prevent.
The title names the action (Couldn't run in terminal) and the dock tab it refers to is on screen.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • Does the z-[80] notice cover a modal or the update banner? — verified, no.

Dashboard modals and the update overlay use fixed inset-0 at z-[89] to z-[9999] (UpdateModal overlay z-[100]), so they sit above the notice.
The notification banner is z-[59], below it; the notice does not cover a modal on any viewport.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • Should an app page's run start in activeSlotProject? — kept, verified.

RunInTerminalBtn sends no cwd, so the receiver must pick one; activeSlotProject is what the shell's own Terminal nav row opens in (toggleBottomTerminal(activeSlotProject) in App.tsx).
Letting an app pick a directory would add a field to the mc:run-in-terminal contract, which the PR's Not a goal excludes.

A code block outside every chat (an app page, a knowledge doc) sends its
run request with no scope. Only the chat page answered those, so on any
other route the button timed out. The app shell now mounts a fallback
receiver that answers unscoped requests while no chat page is mounted,
in the selected session's project, and shows failures in a dismiss-only
notice fixed over the page.

Co-authored-by: Nathan <61266668+nathanyi96@users.noreply.github.com>
@iamwhatever

Copy link
Copy Markdown
Contributor
  • span=5a4ed40739f7 A successful run erases the config-read-failure notice — fixed in 97b619a.

The ok:true listener now keeps the notice when it is run_in_terminal_config_read_failed_error; every other notice still clears on success.
Pinned by RunInTerminalShellBridge.test.tsx 'keeps the config-read failure notice when that same run succeeds' (red with the old clear, green now).

@iamwhatever

Copy link
Copy Markdown
Contributor
  • span=234269952e9f The notice covers the top bar and the page title — rebutted.

It shows only after a failed run, has a dismiss button, and clears on the next successful run.
It covers the heading area, not the control needed to recover: the dock terminal it talks about sits at the bottom, uncovered.
Reserving layout space for a rare failure would shift every page; that placement change is outside this PR's goal.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • Clearing the shell notice on any host's ok:true result — kept on purpose.

Every host runs in the same app-wide dock, so any successful run proves the dock terminal now works, which is what the failure notice was about.
The one exception, the config-read failure, is now kept (97b619a), since a successful run does not fix that read.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • Are remote instance panes iframes? — verified, yes.

InstancesViewport renders each warm instance as an <iframe> (InstancesViewport.tsx, the warmIds.map block): a separate document with its own module state.
So the module-level unscopedHosts counter is per-window by construction, which is what the stand-down needs.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • span=5ba369f288d1 Notice covers page chrome — rebutted.

It shows only after a failed run, has a dismiss button, and clears on the next successful run.
What it covers is the page heading and the top bar's status icons, none of which is needed to recover; the dock terminal it talks about sits at the bottom, uncovered.
Reserving layout space for a rare failure would shift every page; that placement change is outside this PR's goal.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • span=13ce8679cc3b Not cold-read — rebutted.

The notice adds no new copy: every message is an existing pages.chatPage.run_in_terminal_* string the chat page already ships for these same failures, under the existing Couldn't run in terminal title.
The fork lane's missing blind read is a lane cap, not a defect this PR can fix in code.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • Does the notice hide controls a user needs before dismissing it? — verified, no.

It covers the page title and the centre of the top bar (status icons); the dismiss button is on the notice itself and the dock terminal it refers to is at the bottom, uncovered.
Modals and the update overlay sit above it (z-[89] and up), so it never blocks a dialog.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • Should the chat page stay an unscoped receiver? — kept, answered on the earlier head.

On /chat a failure shows above the composer with an Ask Agent hand-off; the shell notice must stay dismiss-only because it can cover an unsaved artifact edit.
Embed windows mount ChatPage but no shell receiver (hasDock=false), so dropping it there loses the answer. The counter is the cost of keeping both.

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

APPROVE at 97b619a25774565714c9137589e65a264ef238e7.

The shell now answers unscoped mc:run-in-terminal requests on every route in the main window, and stands down while a chat page that answers them itself is mounted. The count is read when the event fires, so one click opens one terminal however the listeners were ordered. Popout and embed windows answer nothing. Failures show in a dismiss-only notice that cannot navigate away from an unsaved edit. The event contract and the chat page's own handling are unchanged.

Every Design, First Principles and UX item on this head has a disposition. The UX placement concern is rebutted reasonably: the notice appears only after a failure, can be dismissed, and is cleared by the next successful run. CI is green on this head.

}: RunInTerminalBridgeOptions): string {
const scope = useId()
useEffect(() => {
if (!acceptUnscoped) return
unscopedHosts += 1
return () => { unscopedHosts -= 1 }
}, [acceptUnscoped])
useEffect(() => {
const answersUnscoped = () => acceptUnscoped || (unscopedFallback && unscopedHosts === 0)
const handler = (e: Event) => {
const detail = (e as CustomEvent).detail || {}
const code: string = detail.code
const reqId: string = detail.reqId
const lang: string | undefined = typeof detail.lang === 'string' ? detail.lang : undefined
// Another host's chat (or an emitter outside every scope that another
// host answers, or that this host never answers): not ours to answer.
if (typeof detail.scope === 'string' ? detail.scope !== scope : !answersUnscoped()) return
if (typeof code !== 'string' || !code) return

— crew-pr-reviewer (r115)

@buluoray buluoray 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.

Approving 97b619a.

Still needed on current main: only the chat page (acceptUnscoped: true in pages/chat/page/eventBridges.ts) answers an unscoped mc:run-in-terminal, so off /chat the button still times out. The branch is 249 commits behind but merges cleanly. After the App.tsx split (#21953), activeSlotProject, isPopout and isEmbed are still in scope where the hook is called, and the notice still sits inside LocalOverlayRoot. tsc -p tsconfig.app.json --noEmit passes on the merged tree.

The stand-down is read at event time from a mounted-host count, so one click opens one terminal whichever listener was added first. The popout and embed exclusion is explicit.

On the merged tree, RunInTerminalShellBridge.test.tsx, App.terminalNavActive.test.tsx and MembersPage.runInTerminal.test.tsx pass. Each of these turns a named test red: dropping the mounted-host check, never counting the chat host, ignoring hasDock, and either change to the clear-on-success rule.

Non-blocking test gaps: two mutations in App.tsx leave the suite green: passing hasDock=true in popout/embed windows, and passing no cwd instead of activeSlotProject. A case in App.terminalNavActive.test.tsx that asserts the opened terminal's cwd, plus one rendering App as a popout, would pin both.

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

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

8 participants