chore(lint): enable no-floating-promises in all five ESLint scopes

A floated promise is invisible at review time — the call reads like an
awaited one minus four characters — and the unhandled rejection it
produces surfaces in a different test, in a different file, as a stack
pointing at SDK internals. In #1947 two un-held `callTool` calls made
`npm run ci` unpassable and took a full investigation to attribute; the
fix was two lines. `@typescript-eslint/no-floating-promises` catches the
class outright, so enable it at `error` everywhere.

The rule is type-aware and `tseslint.configs.recommended` is not, so each
scope's config gains a parser project. The four clients name their own
tsconfig projects (both of them — `src` and `__tests__`/`server` live in
different ones). The root scope has no tsconfig at all, so add
`tsconfig.lint.json`: a lint-only project covering `core/**`,
`test-servers/src/**`, and `vitest.shared.mts`, emitting nothing and
gating nothing. It sets `moduleResolution: bundler` deliberately — under
NodeNext `core/`'s extensionless imports fail to resolve, every import
degrades to `any`, and the rule silently stops seeing promises at all.

Measured surface, and the fixes:

- core (2) — `stream.close()` in two Hono `onAbort` listeners. Hono
  invokes subscribers with a bare `subscriber()`, so a promise returned
  from the listener is floated one layer up; `closeAbortedStream` owns
  the rejection where it can actually be owned.
- tui (5) — `handleDisconnect` had no catch of its own and its only
  caller is a key handler that cannot await, so a failing disconnect was
  a live unhandled rejection; it now surfaces the message the way
  `handleConnect` does. The rest are `void` at callers that genuinely
  cannot await, over callees that already own their failures.
- web (92) — 83 are Storybook `expect(...)`, which is instrumented and
  returns a promise, now awaited (`scrollAreaStoryAssertions` is async
  for the same reason). Two tests were asserting against a provider call
  they never awaited. `open(url)` in both web servers now warns instead
  of escaping a synchronous callback.
- cli, launcher — already clean.

Type-aware linting costs time: `clients/web`'s `eslint .` goes from ~8s
to ~19s, inside `validate`. Narrowing the loaded projects is the lever if
that needs reducing later; dropping the rule is not.

Closes #1959

Signed-off-by: cliffhall <cliff@futurescale.com>

.github/copilot-instructions.md

@@ -11,6 +11,7 @@ The Inspector ships as one package with three clients (**Web**, **CLI**, **TUI**
 - **Avoid double casts (`as unknown as T`).** They erase all type safety and usually mean the real type is being worked around. Prefer a type guard, a narrower single cast, or fixing the underlying type. If genuinely unavoidable (a documented gap in a third-party type, or bridging structurally-identical shapes TS can't relate), it **must** carry an inline comment justifying why it's safe and why nothing better exists. An unjustified `as unknown as` is not acceptable in review.
 - Prefer inference, type guards, and precise annotations over assertions.
 - An `_` prefix is the intentionally-unused marker (`argsIgnorePattern` / `varsIgnorePattern` / `caughtErrorsIgnorePattern`).
+- **Never float a promise.** `@typescript-eslint/no-floating-promises` is `error` in all five ESLint scopes, so every promise must be awaited, `.catch(…)`-terminated, returned, or explicitly discarded with `void`. Prefer **holding and settling** it — a floated rejection surfaces in an unrelated file as an SDK-internal stack, which is how two un-held `callTool` calls failed the whole `npm run ci` chain (#1947). Reach for `void` only when the callee already owns its failures (it ends in a `catch`) or the caller genuinely cannot await (a sync effect body, an Ink key handler), and say which in a comment. In Storybook play functions, `expect(...)` from `storybook/test` is instrumented and returns a promise — it must be awaited.
 
 ## React and UI (web client)
 

AGENTS.md

@@ -719,6 +719,12 @@ The ⚠️ option-deletion hazard, the snapshot rule, and the recovery recipe ab
 - Use type guards and type assertions to handle potential type mismatches and ensure type safety
 - Take advantage of TypeScript's advanced features like generics, type aliases, and conditional types to write more expressive and reusable code
 - Regularly review and refactor TypeScript code to ensure it remains well-structured and adheres to evolving best practices
+- **NEVER leave a promise floating.** `@typescript-eslint/no-floating-promises` is enabled at `error` in **all five** ESLint scopes — `clients/{web,cli,tui,launcher}` and the root `core/` + shared gate (#1959). Every promise must be awaited, returned, terminated with `.catch(…)`, or explicitly discarded with the `void` operator.
+  - **The class it catches is invisible at review time.** A floated call reads like an awaited one minus four characters, and the unhandled rejection it produces surfaces somewhere else entirely — a different test, a different file, a stack pointing at SDK internals. Two un-held `client.callTool(...)` promises made `npm run ci` unpassable in #1947: `disconnect()` rejected them with `Connection closed`, the unhandled rejection failed the whole vitest run, and the chain aborted at `coverage`, silently skipping `verify:build-gate`, `smoke`, and Storybook. Attributing it took a full investigation; the fix was two lines.
+  - **Prefer holding and settling the promise.** `void` is an escape hatch, not a fix — it is visible at review time (strictly better than nothing) but still discards the rejection. Reach for it only when the callee already owns its failures (it ends in a `catch` that surfaces the message) or the caller genuinely cannot await — a synchronous `useEffect` body, an Ink `useInput` key handler, a Hono `stream.onAbort` listener. Say **which** of those it is in a one-line comment; an unexplained `void` is a review finding. Where the callee does *not* own its failures, give it a `catch` rather than voiding the call (see `handleDisconnect` in `clients/tui/src/App.tsx`), or terminate with `.catch(…)` at the call site (see `open(url)` in `clients/web/server/{server,vite-hono-plugin}.ts`).
+  - **In Storybook play functions, `expect(...)` from `storybook/test` returns a promise.** Storybook instruments it so the interactions panel can trace each assertion, so every `expect` in a play function is awaited — as is any shared helper that wraps one (`src/test/scrollAreaStoryAssertions.ts` is `async` for this reason).
+  - **The rule is type-aware, so each scope's ESLint config carries a parser project.** The four clients point at their own tsconfig projects (both of them, since `src` and `__tests__`/`server` live in different ones); the root config points at **`tsconfig.lint.json`**, which exists solely to give the parser a program covering `core/**`, `test-servers/src/**`, and `vitest.shared.mts` — none of which is rooted in a tsconfig of its own. That file emits nothing and gates nothing: type *checking* for those sources stays where it was (`core/` through `clients/web`'s `tsc -b`, `test-servers/src` through `clients/cli`'s test project). It sets `moduleResolution: bundler` deliberately — `core/` uses extensionless relative imports, which NodeNext fails to resolve, degrading every import to `any` so the rule silently stops seeing promises at all. **When adding a first-party TS location to the root lint scope, add it to `tsconfig.lint.json`'s `include` too**, or the parser fails it outright with "was not found in any of the provided project(s)". Note also that a tsconfig `include` does **not** expand braces — `core/**/*.{ts,tsx}` matches nothing; list the extensions separately.
+  - Type-aware linting costs real time: `clients/web`'s `eslint .` went from ~8s to ~19s, and `lint` runs inside `validate`, the fast inner-loop check. That is the price of the guarantee; if it needs reducing later, narrowing the projects each scope loads is the lever, not dropping the rule.
 
 ## Web source layout: `src/lib` vs `src/utils`
 

README.md

@@ -307,6 +307,8 @@ Each client self-validates from its own folder; the root scripts chain them. The
 
 Per-client scripts exist too (`validate:web`, `coverage:cli`, `smoke:tui`, …), plus root `validate:core` / `format:core` for the shared `core/` package, `format:scripts` for the root `scripts/` tooling, and `format:shared` / `lint:shared` for the root "shared" surface (`test-servers/src/**`, `vitest.shared.mts`, the root `eslint.config.js`). Run `npm run format` before committing — the root `format` fixes `core/`, the root `scripts/`, the shared surface, and every client; `validate` runs the non-fixing `format:check` and fails CI on any unformatted file.
 
+**Linting is type-aware.** All five ESLint scopes (`clients/{web,cli,tui,launcher}` plus the root `core/` + shared gate) enable `@typescript-eslint/no-floating-promises` at `error`, so a promise that is neither awaited, returned, `.catch(…)`-terminated, nor explicitly discarded with `void` fails `lint` — and therefore `validate` ([#1959](https://github.com/modelcontextprotocol/inspector/issues/1959)). The rule needs type information, so each scope's config names a parser project; the root scope's is **`tsconfig.lint.json`**, a lint-only project covering `core/**`, `test-servers/src/**`, and `vitest.shared.mts`, which have no tsconfig of their own. It emits nothing and changes no typecheck — but a new first-party TS location added to the root lint scope must be added to its `include`. See **TypeScript instructions** in [`AGENTS.md`](./AGENTS.md) for when `void` is acceptable.
+
 For the full testing rules — the ≥90% per-file gate, where test files live, the unit vs. integration vs. storybook projects, and the `v8 ignore` policy — see [`AGENTS.md`](./AGENTS.md).
 
 ## Publishing

clients/cli/eslint.config.js

@@ -16,4 +16,22 @@ export default defineConfig([
       globals: globals.node,
     },
   },
+  {
+    // Type-aware pass for `no-floating-promises` (#1959). The rule needs type
+    // information, which `tseslint.configs.recommended` does not provide, and
+    // the parser needs a project that literally contains the linted file — so
+    // both of this client's tsconfig projects are listed, exactly as
+    // `npm run typecheck` runs them (`src` is in the first, `__tests__` only
+    // in the second).
+    files: ["**/*.ts"],
+    languageOptions: {
+      parserOptions: {
+        project: ["./tsconfig.json", "./tsconfig.test.json"],
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-floating-promises": "error",
+    },
+  },
 ]);

clients/launcher/eslint.config.js

@@ -16,4 +16,19 @@ export default defineConfig([
       globals: globals.node,
     },
   },
+  {
+    // Type-aware pass for `no-floating-promises` (#1959) — see the CLI config
+    // for the reasoning. Both tsconfig projects are listed because `src` and
+    // `__tests__` live in different ones.
+    files: ["**/*.{ts,mts}"],
+    languageOptions: {
+      parserOptions: {
+        project: ["./tsconfig.json", "./tsconfig.test.json"],
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-floating-promises": "error",
+    },
+  },
 ]);

clients/tui/__tests__/App.test.tsx

@@ -661,6 +661,35 @@ describe("App (foundation)", () => {
     expect(h.disconnect).toHaveBeenCalled();
   });
 
+  it("surfaces a disconnect failure instead of floating the rejection", async () => {
+    // 'd' is a key handler, so it cannot await handleDisconnect — the handler
+    // has to own the failure itself or it escapes as an unhandled rejection
+    // and fails the whole run from somewhere else (#1959).
+    // There is nothing to assert on screen — the message only renders once the
+    // client reports `status: "error"`, which a rejected disconnect does not
+    // do. The assertion is the run itself: vitest fails on an unhandled
+    // rejection, so this test passing is the proof the catch owns it.
+    h.ctrl.status = "connected";
+    h.disconnect.mockRejectedValue(new Error("discfail"));
+    const { stdin } = await mount(oneStdio());
+    stdin.write("d");
+    await tick();
+    await tick();
+    expect(h.disconnect).toHaveBeenCalled();
+  });
+
+  it("owns a non-Error disconnect rejection too", async () => {
+    // The catch stringifies a non-Error rejection rather than reading
+    // `.message` off it; a throw here would escape the same way.
+    h.ctrl.status = "connected";
+    h.disconnect.mockRejectedValue("plainstring");
+    const { stdin } = await mount(oneStdio());
+    stdin.write("d");
+    await tick();
+    await tick();
+    expect(h.disconnect).toHaveBeenCalled();
+  });
+
   it("switches tabs via accelerator keys", async () => {
     const r = await mount(stdioServer());
     await press(r, ["t"]); // tools tab (server is auto-selected)

clients/tui/__tests__/tsupConfig.test.ts

@@ -207,7 +207,9 @@ describe("tui tsup config", () => {
     // the double cast is bridging a real structural gap, not hiding a mismatch.
     // A hook the patch called but the stub lacks fails as undefined here rather
     // than passing silently.
-    inkFormLabelPatch.setup(
+    // esbuild types `setup` as `void | Promise<void>`; await it so the
+    // assertions below can't run before an async setup has registered.
+    await inkFormLabelPatch.setup(
       build as unknown as Parameters<typeof inkFormLabelPatch.setup>[0],
     );
 

clients/tui/eslint.config.js

@@ -30,4 +30,19 @@ export default defineConfig([
       "react-hooks/exhaustive-deps": "warn",
     },
   },
+  {
+    // Type-aware pass for `no-floating-promises` (#1959) — see the CLI config
+    // for the reasoning. Both tsconfig projects are listed because `src` and
+    // `__tests__` live in different ones.
+    files: ["**/*.{ts,tsx}"],
+    languageOptions: {
+      parserOptions: {
+        project: ["./tsconfig.json", "./tsconfig.test.json"],
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-floating-promises": "error",
+    },
+  },
 ]);

clients/tui/src/App.tsx

@@ -887,8 +887,15 @@ function App({
   // Disconnect handler
   const handleDisconnect = useCallback(async () => {
     if (!selectedServer) return;
-    await disconnectInspector();
-    // InspectorClient will update status automatically, and data is preserved
+    try {
+      await disconnectInspector();
+      // InspectorClient will update status automatically, and data is preserved
+    } catch (err) {
+      // Nothing above this catches: the only caller is the key handler, which
+      // cannot await. Surface the failure the same way handleConnect does
+      // rather than letting it escape as an unhandled rejection.
+      setConnectError(err instanceof Error ? err.message : String(err));
+    }
   }, [selectedServer, disconnectInspector]);
 
   const handleClearOAuth = useCallback(async () => {
@@ -1428,12 +1435,15 @@ function App({
         input.toLowerCase() === "c" &&
         (inspectorStatus === "disconnected" || inspectorStatus === "error")
       ) {
-        handleConnect();
+        // Both handlers own their failures internally (each ends in a catch
+        // that surfaces the message), so there is nothing left for a key
+        // handler — which cannot await — to do with the promise.
+        void handleConnect();
       } else if (
         input.toLowerCase() === "d" &&
         (inspectorStatus === "connected" || inspectorStatus === "connecting")
       ) {
-        handleDisconnect();
+        void handleDisconnect();
       }
     }
   });

clients/tui/src/components/PromptsTab.tsx

@@ -53,8 +53,10 @@ export function PromptsTab({
         if (selectedPrompt.arguments && selectedPrompt.arguments.length > 0) {
           onFetchPrompt(selectedPrompt);
         } else {
-          // No arguments, fetch directly
-          (async () => {
+          // No arguments, fetch directly. The IIFE catches everything it can
+          // throw, so there is no rejection for this key handler — which
+          // cannot await — to own.
+          void (async () => {
             try {
               const invocation = await inspectorClient.getPrompt(
                 selectedPrompt.name,

clients/tui/src/components/ResourcesTab.tsx

@@ -186,7 +186,9 @@ export function ResourcesTab({
       }
     };
 
-    fetchContent();
+    // An effect body is synchronous, and fetchContent already catches
+    // everything it can throw, so there is no rejection left to own.
+    void fetchContent();
   }, [shouldFetchResource, inspectorClient, onAuthRecoveryRequired]);
 
   const listWidth = Math.floor(width * 0.4);

clients/web/eslint.config.js

@@ -31,5 +31,32 @@ export default defineConfig([
       "react-refresh/only-export-components": "off",
     },
   },
+  {
+    // Type-aware pass for `no-floating-promises` (#1959). The rule needs type
+    // information, which `tseslint.configs.recommended` does not provide, and
+    // the parser needs a project that literally contains the linted file — so
+    // all four leaf projects are listed (`tsconfig.json` itself is a
+    // solution file with `files: []`, so it contains nothing).
+    //
+    // `.d.ts` is excluded: `vitest.shims.d.ts` is pulled in through a `types`
+    // reference rather than an `include`, so no project owns it, and a
+    // declaration file cannot float a promise anyway.
+    files: ["**/*.{ts,tsx}"],
+    ignores: ["**/*.d.ts"],
+    languageOptions: {
+      parserOptions: {
+        project: [
+          "./tsconfig.app.json",
+          "./tsconfig.node.json",
+          "./tsconfig.storybook.json",
+          "./tsconfig.test.json",
+        ],
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-floating-promises": "error",
+    },
+  },
   ...storybook.configs["flat/recommended"],
 ]);

clients/web/server/server.ts

@@ -125,7 +125,13 @@ export async function startHonoServer(
         sandboxUrl ?? undefined,
       );
       if (config.autoOpen) {
-        open(url);
+        // A headless or otherwise browser-less host rejects here. The server
+        // is already listening and the banner above printed the URL, so warn
+        // and carry on rather than letting the rejection escape this
+        // synchronous listen callback and take the process down.
+        open(url).catch((err: unknown) => {
+          console.warn("Could not open a browser automatically:", err);
+        });
       }
     },
   );

clients/web/server/vite-hono-plugin.ts

@@ -114,7 +114,12 @@ export function honoMiddlewarePlugin(config: WebServerConfig): Plugin {
         );
 
         if (config.autoOpen) {
-          open(url);
+          // Same as the prod server: a browser-less host rejects, the dev
+          // server is already up, and the banner above printed the URL — so
+          // warn rather than let the rejection escape this sync helper.
+          open(url).catch((err: unknown) => {
+            console.warn("Could not open a browser automatically:", err);
+          });
         }
       };
 

clients/web/src/components/elements/CategoryBadge/CategoryBadge.stories.tsx

@@ -14,7 +14,7 @@ export const Transport: Story = {
   args: { category: "transport" },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText("transport")).toBeInTheDocument();
+    await expect(canvas.getByText("transport")).toBeInTheDocument();
   },
 };
 
@@ -22,6 +22,6 @@ export const Auth: Story = {
   args: { category: "auth" },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText("auth")).toBeInTheDocument();
+    await expect(canvas.getByText("auth")).toBeInTheDocument();
   },
 };

clients/web/src/components/elements/EmbeddableScrollArea/EmbeddableScrollArea.stories.tsx

@@ -24,7 +24,7 @@ export const FullSize: Story = {
   ),
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText("Row 1")).toBeInTheDocument();
+    await expect(canvas.getByText("Row 1")).toBeInTheDocument();
   },
 };
 
@@ -38,6 +38,6 @@ export const Embedded: Story = {
   ),
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText("Row 1")).toBeInTheDocument();
+    await expect(canvas.getByText("Row 1")).toBeInTheDocument();
   },
 };

clients/web/src/components/elements/ExpandToggle/ExpandToggle.stories.tsx

@@ -15,7 +15,9 @@ export const Collapsed: Story = {
   args: { expanded: false },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByRole("button", { name: "Expand" })).toBeInTheDocument();
+    await expect(
+      canvas.getByRole("button", { name: "Expand" }),
+    ).toBeInTheDocument();
   },
 };
 
@@ -23,7 +25,7 @@ export const Expanded: Story = {
   args: { expanded: true },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(
+    await expect(
       canvas.getByRole("button", { name: "Collapse" }),
     ).toBeInTheDocument();
   },

clients/web/src/components/elements/McpErrorBadge/McpErrorBadge.stories.tsx

@@ -14,7 +14,7 @@ export const HeaderMismatch: Story = {
   args: { code: -32020, name: "HeaderMismatch" },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText("-32020 HeaderMismatch")).toBeInTheDocument();
+    await expect(canvas.getByText("-32020 HeaderMismatch")).toBeInTheDocument();
   },
 };
 
@@ -22,7 +22,7 @@ export const MissingCapability: Story = {
   args: { code: -32021, name: "MissingRequiredClientCapability" },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(
+    await expect(
       canvas.getByText("-32021 MissingRequiredClientCapability"),
     ).toBeInTheDocument();
   },
@@ -32,7 +32,7 @@ export const UnsupportedVersion: Story = {
   args: { code: -32022, name: "UnsupportedProtocolVersion" },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(
+    await expect(
       canvas.getByText("-32022 UnsupportedProtocolVersion"),
     ).toBeInTheDocument();
   },
@@ -47,6 +47,6 @@ export const MethodNotFound: Story = {
   },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText("-32601 MethodNotFound")).toBeInTheDocument();
+    await expect(canvas.getByText("-32601 MethodNotFound")).toBeInTheDocument();
   },
 };

clients/web/src/components/elements/MessageDirectionBadge/MessageDirectionBadge.stories.tsx

@@ -14,7 +14,7 @@ export const Outgoing: Story = {
   args: { direction: "outgoing" },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText("client → server")).toBeInTheDocument();
+    await expect(canvas.getByText("client → server")).toBeInTheDocument();
   },
 };
 
@@ -22,6 +22,6 @@ export const Incoming: Story = {
   args: { direction: "incoming" },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText("server → client")).toBeInTheDocument();
+    await expect(canvas.getByText("server → client")).toBeInTheDocument();
   },
 };

clients/web/src/components/elements/MethodBadge/MethodBadge.stories.tsx

@@ -14,7 +14,7 @@ export const ToolsList: Story = {
   args: { method: "tools/list" },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText("tools/list")).toBeInTheDocument();
+    await expect(canvas.getByText("tools/list")).toBeInTheDocument();
   },
 };
 
@@ -22,6 +22,6 @@ export const TasksList: Story = {
   args: { method: "tasks/list" },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText("tasks/list")).toBeInTheDocument();
+    await expect(canvas.getByText("tasks/list")).toBeInTheDocument();
   },
 };