Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): show a starting state while the terminal comes up (PRD-8313) (#3898)

Andrew Mikofalvy29ced0fbbb72
diff --git a/.changeset/terminal-starting-notice.md b/.changeset/terminal-starting-notice.md
new file mode 100644
index 000000000..19af3aa67
--- /dev/null
+++ b/.changeset/terminal-starting-notice.md
@@ -0,0 +1,7 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+The terminal now says it is starting instead of showing an empty pane. Opening a terminal has always had a gap between the moment you ask for it and the moment the shell prints its first prompt: the project's local settings have to sync, the terminal's code has to load, a PTY host has to start, and your login shell has to run its startup files. On a cold start with a large project that gap can run for seconds, and the pane stayed completely blank for all of it, which is indistinguishable from a keystroke that did nothing. People reasonably concluded it had not worked and opened the terminal again, and again, ending up with several shells they did not want. The pane now shows a "Starting terminal" status for as long as it is waiting, and gets out of the way the moment the shell produces output. The notice fades in only if the wait is long enough to notice, so a fast terminal still opens without a flash, and it sits over the terminal area only, so the "Connect tools" and "Get Claude Code" prompts stay visible and clickable while the shell starts.
+
+The wait itself is also shorter. Loading the terminal's code and syncing the project's settings do not depend on each other, but the code fetch only used to begin once the settings had arrived. It now starts right away, so the two happen at the same time instead of one after the other.
diff --git a/packages/app/src/components/TerminalGate.dom.test.tsx b/packages/app/src/components/TerminalGate.dom.test.tsx
index c4228b370..ba6e30795 100644
--- a/packages/app/src/components/TerminalGate.dom.test.tsx
+++ b/packages/app/src/components/TerminalGate.dom.test.tsx
@@ -45,13 +45,20 @@ vi.doMock('@/hooks/use-terminal-enabled', () => ({
// biome-ignore lint/suspicious/noExplicitAny: captured mock-component props, asserted structurally
let lastPanelProps: Record<string, any> | null = null;
-vi.doMock('./TerminalPanel', () => ({
+// Named so the Suspense-fallback test below — which calls vi.resetModules() and
+// registers its own deferred ./TerminalPanel stub to get a fresh module graph —
+// can put the file-level stub back afterward. Without that restore the registry
+// mutation leaks and what a later `import('./TerminalGate')` resolves to depends
+// on test order. (The two preload tests reset the registry too, but they replace
+// `@/lib/lazy-with-preload` rather than this module.)
+const mockPanelModule = () => ({
// biome-ignore lint/suspicious/noExplicitAny: test stub
TerminalPanel: (props: any) => {
lastPanelProps = props;
return <span data-testid="terminal-panel" />;
},
-}));
+});
+vi.doMock('./TerminalPanel', mockPanelModule);
const { TerminalGate } = await import('./TerminalGate');
@@ -76,7 +83,15 @@ describe('TerminalGate', () => {
toastErrors.length = 0;
lastPanelProps = null;
});
- afterEach(() => cleanup());
+ afterEach(() => {
+ cleanup();
+ // Restore what the module-registry tests replaced, so nothing here is
+ // order-dependent: the file-level panel stub, and the real lazy-with-preload
+ // that the two preload tests swap for a spy.
+ vi.doUnmock('@/lib/lazy-with-preload');
+ vi.doMock('./TerminalPanel', mockPanelModule);
+ vi.resetModules();
+ });
test('default (enabled === null) mounts the terminal — available with no dialog', async () => {
consentState = { enabled: null, synced: true };
@@ -143,6 +158,96 @@ describe('TerminalGate', () => {
expect(notice()).toBeNull();
});
+ test('announces that the terminal is starting while the binding syncs (PRD-8313)', () => {
+ // Holding the mount is right; rendering nothing while we hold it is not. A
+ // featureless pane is indistinguishable from "the keystroke did nothing", so
+ // a user whose cold start runs long re-invokes and stacks up tabs. The pane
+ // must say a shell is coming for as long as it withholds one.
+ consentState = { enabled: null, synced: false };
+ renderGate();
+ expect(screen.queryByTestId('terminal-panel')).toBeNull();
+ expect(screen.getByTestId('terminal-starting-notice')).toBeTruthy();
+ });
+
+ // Both preload tests spy on `.preload()` rather than counting module-factory
+ // invocations. The opt-out case is a NEGATIVE assertion, so it needs a
+ // synchronous observation point — effects flush inside `render`'s `act`, and
+ // there is no settle window to await — and the spy gives both tests the same
+ // mechanism. It also removes a dependency on vitest resolving a
+ // freshly-registered module on its own schedule, which the earlier counting
+ // version had to poll for and which was observed timing out. The
+ // Suspense-fallback test below crosses that same boundary safely because it
+ // OWNS the resolution: it awaits a promise the test itself releases.
+ //
+ // The spy resolves like the real `preload` (`Promise<{ default }>`) even
+ // though the call site discards it, so adding a `.catch()` there later does
+ // not surface as a TypeError thrown inside a passive effect.
+ async function importGateWithPreloadSpy() {
+ vi.resetModules();
+ const preload = vi.fn(() => Promise.resolve({ default: () => null }));
+ vi.doMock('@/lib/lazy-with-preload', () => ({
+ lazyWithPreload: () =>
+ Object.assign(() => <span data-testid="terminal-panel" />, { preload }),
+ }));
+ const { TerminalGate: FreshGate } = await import('./TerminalGate');
+ return { FreshGate, preload };
+ }
+
+ test('warms the panel chunk while the binding is still syncing (PRD-8313)', async () => {
+ // The preload is the one part of this change that alters TIMING rather than
+ // rendering, so it is the part a later "this looks redundant" cleanup can
+ // silently undo.
+ const { FreshGate, preload } = await importGateWithPreloadSpy();
+
+ consentState = { enabled: null, synced: false };
+ render(<FreshGate bridge={bridge} />);
+
+ expect(preload).toHaveBeenCalledTimes(1);
+ // Warming the chunk must not weaken what the gate withholds: no PTY-spawning
+ // panel is mounted while the binding is unsynced.
+ expect(screen.queryByTestId('terminal-panel')).toBeNull();
+ expect(screen.getByTestId('terminal-starting-notice')).toBeTruthy();
+ });
+
+ test('does not warm the panel chunk for a project that opted out (PRD-8313)', async () => {
+ const { FreshGate, preload } = await importGateWithPreloadSpy();
+
+ consentState = { enabled: false, synced: true };
+ render(<FreshGate bridge={bridge} />);
+
+ expect(screen.getByRole('region', { name: 'Terminal disabled' })).toBeTruthy();
+ expect(preload).not.toHaveBeenCalled();
+ });
+
+ test('the lazy-chunk Suspense fallback shows the same starting notice (PRD-8313)', async () => {
+ // The other pre-mount branch. It is only reachable in a module graph where
+ // `lazy()` has not already resolved TerminalPanel — once loaded it never
+ // suspends again — so this test builds a fresh graph whose panel module
+ // stays pending until we release it.
+ vi.resetModules();
+ let releasePanel: () => void = () => {};
+ const panelGate = new Promise<void>((resolve) => {
+ releasePanel = resolve;
+ });
+ vi.doMock('./TerminalPanel', async () => {
+ await panelGate;
+ return { TerminalPanel: () => <span data-testid="terminal-panel" /> };
+ });
+ const { TerminalGate: FreshGate } = await import('./TerminalGate');
+
+ consentState = { enabled: null, synced: true };
+ render(<FreshGate bridge={bridge} />);
+
+ // Synced, so the gate is open and the shell is wanted — but the chunk has
+ // not arrived, which is stage 2 of the cold start.
+ expect(screen.getByTestId('terminal-starting-notice')).toBeTruthy();
+ expect(screen.queryByTestId('terminal-panel')).toBeNull();
+
+ releasePanel();
+ expect(await screen.findByTestId('terminal-panel')).toBeTruthy();
+ expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
+ });
+
test('re-enabling from the notice grants via the writer, then mounts the terminal', async () => {
consentState = { enabled: false, synced: true };
const view = render(<TerminalGate bridge={bridge} />);
diff --git a/packages/app/src/components/TerminalGate.tsx b/packages/app/src/components/TerminalGate.tsx
index 906d52147..d631ea27d 100644
--- a/packages/app/src/components/TerminalGate.tsx
+++ b/packages/app/src/components/TerminalGate.tsx
@@ -9,26 +9,32 @@
*
* The mount waits for the project-local binding to sync, so an opted-out project
* never flashes the shell (nor fires a PTY spawn the main backstop would refuse)
- * during the cold-start window before the real value is known.
+ * during the cold-start window before the real value is known. That wait is
+ * unbounded — the binding syncs over the collab WebSocket, and a congested cold
+ * start can hold it for seconds — so both pre-mount states render a pending
+ * notice rather than an empty pane: withholding the shell is right, but saying
+ * nothing while withholding it reads as a dead keystroke and gets re-invoked.
*
* Opting out while a shell is running unmounts TerminalPanel, whose cleanup kills
* the PTY — turning the terminal off takes effect immediately.
*/
import { useLingui } from '@lingui/react/macro';
-import { lazy, Suspense } from 'react';
+import { Suspense, useEffect } from 'react';
import { ErrorBoundary, type FallbackProps } from 'react-error-boundary';
import { toast } from 'sonner';
import { Button } from '@/components/ui/button';
import { useTerminalConsentState, useTerminalEnabledWriter } from '@/hooks/use-terminal-enabled';
import type { OkDesktopBridge } from '@/lib/desktop-bridge-types';
+import { lazyWithPreload } from '@/lib/lazy-with-preload';
import type { TerminalLaunchIntent } from './EditorPane';
import type { TerminalCommandId } from './handoff/terminal-command-events';
+import { TerminalStartingNotice } from './TerminalStartingNotice';
// xterm + its addons + xterm.css (a heavy, WebGL-bearing payload) import only
// through TerminalPanel, so lazy-loading it keeps them out of the initial
// bundle — including the web host, where the bridge is null and the terminal
// can never render.
-const TerminalPanel = lazy(() =>
+const TerminalPanel = lazyWithPreload(() =>
import('./TerminalPanel').then((m) => ({ default: m.TerminalPanel })),
);
@@ -65,6 +71,30 @@ export function TerminalGate({
const optedOut = synced && enabled === false;
+ // Warm the panel chunk without waiting for the gate to open. Plain `lazy()`
+ // runs its factory only when the lazy element first renders, and that render
+ // sits behind `synced` — so the chunk fetch and the binding sync, which have
+ // no dependency on each other, ran back to back. Preloading spawns no PTY, so
+ // it does not weaken what the gate withholds; it only stops the two waits from
+ // being serialized. `.preload()` is idempotent, so repeat calls are free.
+ //
+ // Skipped once the project is known to have opted out. `synced` is NOT
+ // monotonic — ConfigProvider re-keys its bindings on `[collabUrl,
+ // serverInstanceId]` and every rebuild nulls the state, so it goes back to
+ // false on the boot-time epoch landing, on a server respawn, and on a project
+ // switch. So this is a best-effort skip, not a guarantee: `optedOut` reads
+ // false during each of those windows and the warm proceeds. The cost when it
+ // does is a chunk fetched and never mounted — genuinely new here, since plain
+ // `lazy()` only ran its factory from inside the opened gate and so an
+ // opted-out project fetched nothing at all. It stays bounded because
+ // `.preload()` memoizes: one fetch per renderer, worst case. What the guard
+ // buys is the common dock-reveal case on an opted-out project, where the
+ // value is already known at mount.
+ useEffect(() => {
+ if (optedOut) return;
+ TerminalPanel.preload();
+ }, [optedOut]);
+
function handleEnable() {
if (writer === null) {
toast.error(t`Terminal settings not loaded yet — try again in a moment.`);
@@ -93,7 +123,7 @@ export function TerminalGate({
);
}}
>
- <Suspense fallback={<div className="h-full w-full bg-background" aria-hidden="true" />}>
+ <Suspense fallback={<TerminalStartingNotice />}>
<TerminalPanel
bridge={bridge}
className="h-full"
@@ -112,7 +142,7 @@ export function TerminalGate({
return optedOut ? (
<TerminalNotEnabledNotice onEnable={handleEnable} />
) : (
- <div className="h-full w-full bg-background" aria-hidden="true" />
+ <TerminalStartingNotice />
);
}
diff --git a/packages/app/src/components/TerminalPanel.dom.test.tsx b/packages/app/src/components/TerminalPanel.dom.test.tsx
index 9106f95f6..d65a7d43a 100644
--- a/packages/app/src/components/TerminalPanel.dom.test.tsx
+++ b/packages/app/src/components/TerminalPanel.dom.test.tsx
@@ -454,6 +454,11 @@ describe('TerminalPanel', () => {
// main-process test pins on the producing side.
expect(lastTerm?.write).toHaveBeenCalledWith('REPLAYED-SCREEN-BYTES');
expect(terminal.create).not.toHaveBeenCalled();
+ // Replayed bytes are output, so the pending notice must clear. Without the
+ // markFirstOutput() call on this path a reload-recovered terminal would sit
+ // under a permanent "Starting terminal…" over already-restored content until
+ // the shell happened to emit a fresh byte.
+ expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
});
test('reload rehydration: a refused adopt (session died in the gap) falls through to a fresh create', async () => {
@@ -564,6 +569,63 @@ describe('TerminalPanel', () => {
expect(terminal.drain).toHaveBeenCalledWith('pty-1', payload.length);
});
+ test('says the terminal is starting until the first shell byte, then gets out of the way (PRD-8313)', async () => {
+ const { bridge, terminal, pushData } = makeBridge({ ok: true, ptyId: 'pty-1' });
+ render(<TerminalPanel bridge={bridge} />);
+
+ // Attached — a ptyId came back, so the status machine already reads
+ // 'running'. But the PTY host still has to fork and the login shell still
+ // has to source its rc chain, and until a byte arrives the pane is empty.
+ // This is the window the user reads as "my keystroke did nothing".
+ await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
+ expect(screen.getByTestId('terminal-starting-notice')).toBeTruthy();
+
+ act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
+
+ // The shell is talking; the notice must not sit on top of live output.
+ expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
+ });
+
+ test('the starting notice never covers or click-blocks the readiness banner (PRD-8313)', async () => {
+ const { bridge, pushData } = makeBridge(
+ { ok: true, ptyId: 'pty-1' },
+ { claude: 'present', mcp: 'needs-rewire' },
+ );
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);
+
+ // The readiness verdict is resolved BEFORE create() returns a ptyId, so a
+ // banner-bearing launch always has the banner mounted for the whole
+ // pre-first-byte window. The two coexist by construction, not by race.
+ const banner = await screen.findByTestId('terminal-readiness-banner');
+ const notice = screen.getByTestId('terminal-starting-notice');
+
+ // jsdom has no layout engine, so occlusion itself cannot be measured here
+ // (a click on a covered button still "succeeds"). What it can pin are the
+ // two properties whose absence caused it. First: the overlay's CONTAINING
+ // BLOCK — the positioned ancestor `inset-0` resolves against — must not span
+ // the banner. Asserting on the notice itself would be a tautology, since the
+ // broken tree had banner and notice as SIBLINGS: the occlusion never came
+ // from nesting, it came from the containing block being the whole column.
+ const containingBlock = notice.parentElement;
+ expect(containingBlock).not.toBeNull();
+ expect(containingBlock?.contains(banner)).toBe(false);
+ // ...and it must actually BE the containing block. Without this, dropping
+ // `relative` from the canvas wrapper re-resolves `inset-0` against the
+ // column wrapper one level up — which spans the banner strips — while
+ // `parentElement` still points at the now-unpositioned canvas box and every
+ // other assertion here stays green. That is the column-wide overlay
+ // occlusion this test exists to kill, reachable by deleting one class.
+ // Token match, not substring: `sm:relative` would satisfy `toContain` while
+ // leaving the wrapper unpositioned below the breakpoint.
+ expect(containingBlock?.className.split(/\s+/)).toContain('relative');
+ // Second: even where it does overlay, it must not intercept pointer events.
+ expect(notice.className).toContain('pointer-events-none');
+ expect(screen.getByRole('button', { name: 'Connect tools' })).toBeTruthy();
+
+ act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
+ expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
+ });
+
test('forwards user keystrokes to the PTY via input', async () => {
const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
render(<TerminalPanel bridge={bridge} />);
@@ -1390,7 +1452,7 @@ describe('TerminalPanel', () => {
fireEvent.click(screen.getByRole('button', { name: 'Connect tools' }));
expect(rewireClaudeMcp).toHaveBeenCalledTimes(1);
// The banner hands off to the consent dialog and dismisses itself.
- await waitFor(() => expect(screen.queryByRole('status')).toBeNull());
+ await waitFor(() => expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull());
});
test('a claude launch shows no readiness banner when claude is present and OK tools are wired', async () => {
@@ -1401,7 +1463,7 @@ describe('TerminalPanel', () => {
await act(async () => {
await Promise.resolve();
});
- expect(screen.queryByRole('status')).toBeNull();
+ expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
});
test('the readiness banner is dismissible', async () => {
diff --git a/packages/app/src/components/TerminalPanel.tsx b/packages/app/src/components/TerminalPanel.tsx
index 42de52b47..14d48a755 100644
--- a/packages/app/src/components/TerminalPanel.tsx
+++ b/packages/app/src/components/TerminalPanel.tsx
@@ -28,6 +28,7 @@ import { TerminalCliMissingBanner } from './TerminalCliMissingBanner';
import { TerminalCliUnverifiedBanner } from './TerminalCliUnverifiedBanner';
import { type TerminalExitInfo, TerminalExitNotice } from './TerminalExitNotice';
import { TerminalRefusalNotice } from './TerminalRefusalNotice';
+import { TerminalStartingNotice } from './TerminalStartingNotice';
import { createTerminalFileLinkProvider } from './terminal-link-provider';
import { createRecentOpenGuard, type TerminalLinkTarget } from './terminal-links';
import { createSameFrameRepaint } from './terminal-render-flush';
@@ -217,6 +218,12 @@ function TerminalSession({
// theme changes flow through the dedicated effect below.
const initialXtermThemeRef = useRef(xtermTheme);
const [status, setStatus] = useState<SessionStatus>('starting');
+ // Whether any shell byte has landed yet. `status` cannot answer this: it flips
+ // to 'running' the instant a ptyId comes back, which is BEFORE the utility
+ // process forks a PTY host and the login shell sources its rc chain — the
+ // seconds a user actually waits. Without this the pane looks identical whether
+ // a shell is coming or nothing happened at all.
+ const [hasOutput, setHasOutput] = useState(false);
const [readiness, setReadiness] = useState<ClaudeReadiness | null>(null);
const [exitInfo, setExitInfo] = useState<TerminalExitInfo | null>(null);
// Live PTY id, mirrored out of the mount effect for the keyboard handlers.
@@ -653,6 +660,20 @@ function TerminalSession({
return false;
});
+ // First byte from the shell: drop the pending notice. Idempotent — the data
+ // subscription fires per chunk, and an adopted session replays its retained
+ // screen through here too. The guard is a plain effect-scoped `let` because
+ // nothing outside this effect reads it; a ref would work identically (every
+ // new session is a fresh TerminalSession instance, so a ref could not carry
+ // state across sessions either), it just puts an instance-lifetime cell
+ // where an effect-lifetime one is what the code means.
+ let sawFirstOutput = false;
+ const markFirstOutput = () => {
+ if (sawFirstOutput) return;
+ sawFirstOutput = true;
+ setHasOutput(true);
+ };
+
// Wire a now-live ptyId (freshly created OR adopted from a survivor) into
// this session: route xterm I/O, exit, and resize through it, and focus it.
// The wiring is identical for both acquisition paths — only how the id is
@@ -673,6 +694,7 @@ function TerminalSession({
unsubData = bridge.terminal.onData((msg) => {
if (msg.ptyId !== ptyId) return;
+ markFirstOutput();
// Ack consumed code units only once xterm has processed the chunk, so
// the main-side backpressure window tracks real consumption.
term.write(msg.data, () => bridge.terminal.drain(msg.ptyId, msg.data.length));
@@ -859,7 +881,10 @@ function TerminalSession({
// comes back blank (the shell reconnects but its
// screen is gone). Written synchronously here, ahead of attachSession's
// onData subscription, so no live byte can interleave before the replay.
- if (adopted.replay) term.write(adopted.replay);
+ if (adopted.replay) {
+ markFirstOutput();
+ term.write(adopted.replay);
+ }
attachSession(adoptPtyId);
// Nudge the surviving shell to repaint at the current viewport so a
// full-screen TUI (claude, vim) redraws its screen after the reload.
@@ -1137,7 +1162,21 @@ function TerminalSession({
<TerminalCliUnverifiedBanner cli={cliNotice.cli} onDismiss={() => setCliNotice(null)} />
)
) : null}
- <div ref={containerRef} data-terminal-status={status} className="min-h-0 flex-1 px-1.5" />
+ {/* This wrapper exists so the pending notice covers the CANVAS only. The
+ readiness / CLI banners above are gated on `status === 'running'`, and
+ `resolveLaunchCommand` sets their verdicts BEFORE `create()` resolves,
+ so on any CLI launch with a banner due the banner is mounted for the
+ whole pre-first-byte window — a column-wide overlay hid it. The
+ wrapper one level up in TerminalPanel would have served as a
+ containing block, but it spans the column, and spanning the column is
+ the bug. Per-class rationale lives on `TerminalStartingNotice`'s
+ `className` prop. */}
+ <div className="relative min-h-0 flex-1">
+ <div ref={containerRef} data-terminal-status={status} className="h-full w-full px-1.5" />
+ {status === 'starting' || (status === 'running' && !hasOutput) ? (
+ <TerminalStartingNotice className="pointer-events-none absolute inset-0 z-20" />
+ ) : null}
+ </div>
{status === 'exited' && exitInfo ? (
<TerminalExitNotice info={exitInfo} onRestart={onRestart} />
) : null}
diff --git a/packages/app/src/components/TerminalStartingNotice.tsx b/packages/app/src/components/TerminalStartingNotice.tsx
new file mode 100644
index 000000000..05eb4dd7b
--- /dev/null
+++ b/packages/app/src/components/TerminalStartingNotice.tsx
@@ -0,0 +1,63 @@
+/**
+ * Pending affordance for a terminal that has been asked for but has produced no
+ * shell output yet.
+ *
+ * What it replaces was a featureless `aria-hidden` div, which reads to a user
+ * exactly like a keystroke that did nothing — so a cold start that runs long
+ * gets re-invoked, and every re-invocation stacks another tab and another login
+ * shell, making the contention worse. The pane must say a shell is coming for
+ * as long as it is withholding one.
+ *
+ * The fade-in is a CSS `animation-delay`, not a JS timer: a start that wins the
+ * race never flashes the notice, and there is no timer to leak when the shell
+ * arrives and unmounts this. Under `motion-reduce` the delay is preserved and
+ * only the fade is collapsed (`duration-0`) — clearing the whole animation would
+ * hand reduced-motion users the flash the delay exists to prevent.
+ *
+ * A11y note, deliberately not overclaimed: `opacity: 0` keeps the node in the
+ * accessibility tree, but a `role="status"` subtree mounted with its text
+ * already present is announced inconsistently across screen reader and browser
+ * pairs, because there is no content mutation to observe. `editor/SelectionAnnouncer`
+ * is this repo's prior art for guaranteeing announcement — it holds a persistent
+ * empty region and writes `textContent` on a later tick. Adopting that shape here
+ * has not been done and the announcement has not been tested against a real
+ * screen reader, so treat reliable announcement as unverified. What IS fixed
+ * relative to the old pane is that the region is no longer `aria-hidden`.
+ */
+import { useLingui } from '@lingui/react/macro';
+import { Spinner } from '@/components/ui/spinner';
+import { cn } from '@/lib/utils';
+
+interface TerminalStartingNoticeProps {
+ /**
+ * Extra classes. The canvas overlay in `TerminalPanel` passes
+ * `pointer-events-none absolute inset-0 z-20`, and the three do separate jobs:
+ * `absolute inset-0` resolves against the canvas wrapper, which is what keeps
+ * the notice off the readiness / CLI banner strips (they are in-flow siblings
+ * ABOVE that box, so nothing overlaps them and nothing else has to protect
+ * them); `pointer-events-none` earns its place purely over the canvas, where
+ * the notice really does sit on top of the xterm helper textarea that
+ * `attachSession` focuses in this same window; and `z-20` matches the exit /
+ * refusal overlays that already stack against xterm's positioned layers.
+ * `TerminalGate` passes nothing — there it is the whole pane, not an overlay.
+ */
+ readonly className?: string;
+}
+
+export function TerminalStartingNotice({ className }: TerminalStartingNoticeProps) {
+ const { t } = useLingui();
+ return (
+ <div
+ role="status"
+ data-testid="terminal-starting-notice"
+ className={cn(
+ 'flex h-full w-full items-center justify-center gap-2.5 bg-background px-6 text-center text-muted-foreground text-sm',
+ 'fade-in-0 animate-in duration-200 [animation-delay:400ms] [animation-fill-mode:backwards] motion-reduce:duration-0',
+ className,
+ )}
+ >
+ <Spinner aria-hidden="true" />
+ {t`Starting terminal…`}
+ </div>
+ );
+}
diff --git a/packages/app/src/lib/terminal-telemetry.ts b/packages/app/src/lib/terminal-telemetry.ts
index 62fd5780a..af2376c88 100644
--- a/packages/app/src/lib/terminal-telemetry.ts
+++ b/packages/app/src/lib/terminal-telemetry.ts
@@ -5,8 +5,8 @@
* `open-knowledge-app` tracer: the panel opening (adoption) and the user
* granting shell consent (intent to run Claude Code in-app). Span names share
* the `ok.desktop.*` convention with the main-side lifecycle spans
- * (`packages/desktop/src/main/terminal-telemetry.ts`) so the four terminal
- * events read as one family across the two tracers.
+ * (`packages/desktop/src/main/terminal-telemetry.ts`) so the terminal events
+ * read as one family across the two tracers.
*
* `@opentelemetry/api` returns a no-op tracer when no SDK is registered, so
* these are zero-cost unless `VITE_OTEL_ENABLED='true'`. Never captures command
diff --git a/packages/app/src/locales/ar/messages.json b/packages/app/src/locales/ar/messages.json
index 92bde2cd8..99a458fae 100644
--- a/packages/app/src/locales/ar/messages.json
+++ b/packages/app/src/locales/ar/messages.json
@@ -1481,6 +1481,7 @@
],
"GBQjiV": ["إضافة مهارة"],
"GDvlUT": ["الدور"],
+ "GEyl32": ["جارٍ بدء تشغيل الطرفية…"],
"GGsM4y": ["محدَّد في الرسم البياني"],
"GH02QY": ["إبقاؤه مفتوحًا"],
"GHsJb8": ["إظهار مجلدات .ok"],
diff --git a/packages/app/src/locales/ar/messages.po b/packages/app/src/locales/ar/messages.po
index e1db0dca8..7dc7cf619 100644
--- a/packages/app/src/locales/ar/messages.po
+++ b/packages/app/src/locales/ar/messages.po
@@ -12514,6 +12514,10 @@ msgstr "يجري بدء الاستنساخ"
msgid "Starting sign-in flow"
msgstr "يجري بدء تدفق تسجيل الدخول"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "جارٍ بدء تشغيل الطرفية…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "يجري تشغيل الوكيل…"
diff --git a/packages/app/src/locales/bn/messages.json b/packages/app/src/locales/bn/messages.json
index eb1bd2503..39059e599 100644
--- a/packages/app/src/locales/bn/messages.json
+++ b/packages/app/src/locales/bn/messages.json
@@ -1255,6 +1255,7 @@
],
"GBQjiV": ["স্কিল যোগ করুন"],
"GDvlUT": ["ভূমিকা"],
+ "GEyl32": ["টার্মিনাল চালু হচ্ছে…"],
"GGsM4y": ["গ্রাফে নির্বাচিত"],
"GH02QY": ["খোলা রাখুন"],
"GHsJb8": [".ok ফোল্ডার দেখান"],
diff --git a/packages/app/src/locales/bn/messages.po b/packages/app/src/locales/bn/messages.po
index 75dc0205d..be381fbf8 100644
--- a/packages/app/src/locales/bn/messages.po
+++ b/packages/app/src/locales/bn/messages.po
@@ -12510,6 +12510,10 @@ msgstr "ক্লোন শুরু করা হচ্ছে"
msgid "Starting sign-in flow"
msgstr "সাইন-ইন প্রক্রিয়া শুরু করা হচ্ছে"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "টার্মিনাল চালু হচ্ছে…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "এজেন্ট শুরু করা হচ্ছে…"
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index c7ca22530..983fe7553 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -1283,6 +1283,7 @@
],
"GBQjiV": ["Add skill"],
"GDvlUT": ["Role"],
+ "GEyl32": ["Starting terminal…"],
"GGsM4y": ["Selected in graph"],
"GH02QY": ["Keep open"],
"GHsJb8": ["Show .ok folders"],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index ec33c8419..b50b260df 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -12514,6 +12514,10 @@ msgstr "Starting clone"
msgid "Starting sign-in flow"
msgstr "Starting sign-in flow"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "Starting terminal…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "Starting the agent…"
diff --git a/packages/app/src/locales/es/messages.json b/packages/app/src/locales/es/messages.json
index 73c3c7802..3a7a3f7f0 100644
--- a/packages/app/src/locales/es/messages.json
+++ b/packages/app/src/locales/es/messages.json
@@ -1492,6 +1492,7 @@
],
"GBQjiV": ["Añadir habilidad"],
"GDvlUT": ["Función"],
+ "GEyl32": ["Iniciando terminal…"],
"GGsM4y": ["Seleccionado en el grafo"],
"GH02QY": ["Mantener abierto"],
"GHsJb8": ["Mostrar las carpetas .ok"],
diff --git a/packages/app/src/locales/es/messages.po b/packages/app/src/locales/es/messages.po
index 15cdacb08..3c8ea8d87 100644
--- a/packages/app/src/locales/es/messages.po
+++ b/packages/app/src/locales/es/messages.po
@@ -12514,6 +12514,10 @@ msgstr "Empezando la clonación"
msgid "Starting sign-in flow"
msgstr "Iniciando el flujo de inicio de sesión"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "Iniciando terminal…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "Iniciando el agente…"
diff --git a/packages/app/src/locales/fr/messages.json b/packages/app/src/locales/fr/messages.json
index 869ce3fa3..b97c27961 100644
--- a/packages/app/src/locales/fr/messages.json
+++ b/packages/app/src/locales/fr/messages.json
@@ -1519,6 +1519,7 @@
],
"GBQjiV": ["Ajouter une compétence"],
"GDvlUT": ["Rôle"],
+ "GEyl32": ["Démarrage du terminal…"],
"GGsM4y": ["Sélectionné dans le graphe"],
"GH02QY": ["Garder ouvert"],
"GHsJb8": ["Afficher les dossiers .ok"],
diff --git a/packages/app/src/locales/fr/messages.po b/packages/app/src/locales/fr/messages.po
index 2c5e17167..a6ee0e73a 100644
--- a/packages/app/src/locales/fr/messages.po
+++ b/packages/app/src/locales/fr/messages.po
@@ -12514,6 +12514,10 @@ msgstr "Démarrage du clonage"
msgid "Starting sign-in flow"
msgstr "Démarrage du processus de connexion"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "Démarrage du terminal…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "Démarrage de l'agent…"
diff --git a/packages/app/src/locales/hi/messages.json b/packages/app/src/locales/hi/messages.json
index b78cb3ca9..893e8b616 100644
--- a/packages/app/src/locales/hi/messages.json
+++ b/packages/app/src/locales/hi/messages.json
@@ -1251,6 +1251,7 @@
],
"GBQjiV": ["स्किल जोड़ें"],
"GDvlUT": ["भूमिका"],
+ "GEyl32": ["टर्मिनल शुरू हो रहा है…"],
"GGsM4y": ["ग्राफ़ में चयनित"],
"GH02QY": ["खुला रखें"],
"GHsJb8": [".ok फ़ोल्डर दिखाएँ"],
diff --git a/packages/app/src/locales/hi/messages.po b/packages/app/src/locales/hi/messages.po
index eceac5a2c..202be1986 100644
--- a/packages/app/src/locales/hi/messages.po
+++ b/packages/app/src/locales/hi/messages.po
@@ -12510,6 +12510,10 @@ msgstr "क्लोन शुरू किया जा रहा है"
msgid "Starting sign-in flow"
msgstr "साइन-इन प्रक्रिया शुरू की जा रही है"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "टर्मिनल शुरू हो रहा है…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "एजेंट शुरू किया जा रहा है…"
diff --git a/packages/app/src/locales/id/messages.json b/packages/app/src/locales/id/messages.json
index 45eba45f0..3b59f9d99 100644
--- a/packages/app/src/locales/id/messages.json
+++ b/packages/app/src/locales/id/messages.json
@@ -1283,6 +1283,7 @@
],
"GBQjiV": ["Tambahkan keterampilan"],
"GDvlUT": ["Peran"],
+ "GEyl32": ["Memulai terminal…"],
"GGsM4y": ["Terpilih di graf"],
"GH02QY": ["Biarkan terbuka"],
"GHsJb8": ["Tampilkan folder .ok"],
diff --git a/packages/app/src/locales/id/messages.po b/packages/app/src/locales/id/messages.po
index 18038b3b0..a48aa1ed7 100644
--- a/packages/app/src/locales/id/messages.po
+++ b/packages/app/src/locales/id/messages.po
@@ -12510,6 +12510,10 @@ msgstr "Memulai kloning"
msgid "Starting sign-in flow"
msgstr "Memulai alur masuk"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "Memulai terminal…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "Memulai agennya…"
diff --git a/packages/app/src/locales/ko/messages.json b/packages/app/src/locales/ko/messages.json
index d4687f304..c680fc519 100644
--- a/packages/app/src/locales/ko/messages.json
+++ b/packages/app/src/locales/ko/messages.json
@@ -1236,6 +1236,7 @@
],
"GBQjiV": ["스킬 추가"],
"GDvlUT": ["역할"],
+ "GEyl32": ["터미널 시작 중…"],
"GGsM4y": ["그래프에서 선택됨"],
"GH02QY": ["열어 두기"],
"GHsJb8": [".ok 폴더 표시"],
diff --git a/packages/app/src/locales/ko/messages.po b/packages/app/src/locales/ko/messages.po
index fb4c5bc40..3d3cea09c 100644
--- a/packages/app/src/locales/ko/messages.po
+++ b/packages/app/src/locales/ko/messages.po
@@ -12514,6 +12514,10 @@ msgstr "클론 시작 중"
msgid "Starting sign-in flow"
msgstr "로그인 흐름 시작 중"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "터미널 시작 중…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "에이전트 시작 중…"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 8621ca1f5..bd48a4d0f 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -1283,6 +1283,7 @@
],
"GBQjiV": ["Àďď śķĩĺĺ"],
"GDvlUT": ["Ŕōĺē"],
+ "GEyl32": ["Śţàŕţĩńĝ ţēŕḿĩńàĺ…"],
"GGsM4y": ["Śēĺēćţēď ĩń ĝŕàƥĥ"],
"GH02QY": ["Ķēēƥ ōƥēń"],
"GHsJb8": ["Śĥōŵ .ōķ ƒōĺďēŕś"],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index 744792f82..f07e53094 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -12510,6 +12510,10 @@ msgstr ""
msgid "Starting sign-in flow"
msgstr ""
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr ""
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr ""
diff --git a/packages/app/src/locales/pt-BR/messages.json b/packages/app/src/locales/pt-BR/messages.json
index 0908e96bb..00784a132 100644
--- a/packages/app/src/locales/pt-BR/messages.json
+++ b/packages/app/src/locales/pt-BR/messages.json
@@ -1470,6 +1470,7 @@
],
"GBQjiV": ["Adicionar habilidade"],
"GDvlUT": ["Função"],
+ "GEyl32": ["Iniciando terminal…"],
"GGsM4y": ["Selecionado no grafo"],
"GH02QY": ["Manter aberto"],
"GHsJb8": ["Mostrar as pastas .ok"],
diff --git a/packages/app/src/locales/pt-BR/messages.po b/packages/app/src/locales/pt-BR/messages.po
index 19b7509fe..52399ef16 100644
--- a/packages/app/src/locales/pt-BR/messages.po
+++ b/packages/app/src/locales/pt-BR/messages.po
@@ -12510,6 +12510,10 @@ msgstr "Começando a clonagem"
msgid "Starting sign-in flow"
msgstr "Iniciando o fluxo de login"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "Iniciando terminal…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "Iniciando o agente…"
diff --git a/packages/app/src/locales/ur/messages.json b/packages/app/src/locales/ur/messages.json
index 1bf699d58..fe7f58e85 100644
--- a/packages/app/src/locales/ur/messages.json
+++ b/packages/app/src/locales/ur/messages.json
@@ -1309,6 +1309,7 @@
],
"GBQjiV": ["مہارت شامل کریں"],
"GDvlUT": ["کردار"],
+ "GEyl32": ["ٹرمینل شروع ہو رہا ہے…"],
"GGsM4y": ["گراف میں منتخب"],
"GH02QY": ["کھلا رکھیں"],
"GHsJb8": [".ok فولڈرز دکھائیں"],
diff --git a/packages/app/src/locales/ur/messages.po b/packages/app/src/locales/ur/messages.po
index 7ad7a0a42..995a95999 100644
--- a/packages/app/src/locales/ur/messages.po
+++ b/packages/app/src/locales/ur/messages.po
@@ -12514,6 +12514,10 @@ msgstr "کلون شروع کیا جا رہا ہے"
msgid "Starting sign-in flow"
msgstr "سائن اِن کا عمل شروع کیا جا رہا ہے"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "ٹرمینل شروع ہو رہا ہے…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "ایجنٹ شروع کیا جا رہا ہے…"
diff --git a/packages/app/src/locales/zh-Hans/messages.json b/packages/app/src/locales/zh-Hans/messages.json
index 268502d8c..4ecfcaa3e 100644
--- a/packages/app/src/locales/zh-Hans/messages.json
+++ b/packages/app/src/locales/zh-Hans/messages.json
@@ -1134,6 +1134,7 @@
"GBEqoP": ["你的 Git 配置中指定了 ", ["declaredLogin"], ",但无法使用该账户的凭据。"],
"GBQjiV": ["添加技能"],
"GDvlUT": ["角色"],
+ "GEyl32": ["正在启动终端…"],
"GGsM4y": ["在关系图中已选中"],
"GH02QY": ["保持打开"],
"GHsJb8": ["显示 .ok 文件夹"],
diff --git a/packages/app/src/locales/zh-Hans/messages.po b/packages/app/src/locales/zh-Hans/messages.po
index b255ed165..9fea6bf03 100644
--- a/packages/app/src/locales/zh-Hans/messages.po
+++ b/packages/app/src/locales/zh-Hans/messages.po
@@ -12514,6 +12514,10 @@ msgstr "正在开始克隆"
msgid "Starting sign-in flow"
msgstr "正在启动登录流程"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "正在启动终端…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "正在启动智能体…"
diff --git a/packages/app/src/locales/zh-Hant/messages.json b/packages/app/src/locales/zh-Hant/messages.json
index 306d880e5..8b7f09765 100644
--- a/packages/app/src/locales/zh-Hant/messages.json
+++ b/packages/app/src/locales/zh-Hant/messages.json
@@ -1144,6 +1144,7 @@
"GBEqoP": ["你的 Git 設定中指定了 ", ["declaredLogin"], ",但無法使用該帳戶的憑證。"],
"GBQjiV": ["新增技能"],
"GDvlUT": ["角色"],
+ "GEyl32": ["正在啟動終端機…"],
"GGsM4y": ["在關係圖中已選取"],
"GH02QY": ["保持開啟"],
"GHsJb8": ["顯示 .ok 資料夾"],
diff --git a/packages/app/src/locales/zh-Hant/messages.po b/packages/app/src/locales/zh-Hant/messages.po
index cae7ab1e6..37defe357 100644
--- a/packages/app/src/locales/zh-Hant/messages.po
+++ b/packages/app/src/locales/zh-Hant/messages.po
@@ -12514,6 +12514,10 @@ msgstr "正在開始複製"
msgid "Starting sign-in flow"
msgstr "正在啟動登入流程"
+#: src/components/TerminalStartingNotice.tsx
+msgid "Starting terminal…"
+msgstr "正在啟動終端機…"
+
#: src/components/acp/ThreadView.tsx
msgid "Starting the agent…"
msgstr "正在啟動代理…"
diff --git a/packages/desktop/tests/smoke/terminal-dock.e2e.ts b/packages/desktop/tests/smoke/terminal-dock.e2e.ts
index cca865b97..2084e3ffe 100644
--- a/packages/desktop/tests/smoke/terminal-dock.e2e.ts
+++ b/packages/desktop/tests/smoke/terminal-dock.e2e.ts
@@ -1136,7 +1136,15 @@ test.describe('Docked terminal — live Electron', () => {
// Apostrophe-free substring (same rationale as the not-found banner) — distinctive
// to the MCP-rewire banner variant, which the 'Connect tools' affordance below confirms.
await expect(banner).toContainText('OpenKnowledge tools');
- await expect(page.getByRole('button', { name: 'Connect tools' })).toBeVisible();
+ // Trial click, not `toBeVisible()`: this is the only tier with a real layout
+ // engine, so it is the only one whose hit-target check can catch the button
+ // being painted over by an overlay — `toBeVisible()` passes on a covered
+ // element, and jsdom has no layout at all. `trial: true` runs the full
+ // actionability sequence (attached / visible / stable / receives-events /
+ // enabled) and then skips the dispatch, so it buys the occlusion signal
+ // without invoking `rewireClaudeMcp` and dismissing the banner on the way
+ // out, neither of which this test asserts anything about.
+ await page.getByRole('button', { name: 'Connect tools' }).click({ trial: true });
});
// A renderer reload (View → Reload, or an OS resume-triggered reload) must