From 518b779e2a772d58cac80593170206ab3155be2d Mon Sep 17 00:00:00 2001
From: Nicolas Borges <nickdb@amazon.com>
Date: Tue, 29 Sep 2026 20:14:36 -0400
Subject: [PATCH 1/5] refactor(TUI): improve command menu scroll and resize
 mechanics

---
 src/components/BrandBanner.tsx       |   3 +
 src/components/Layout.tsx            |  33 ++++-
 src/components/RouterScreen.test.tsx |  18 +++
 src/components/RouterScreen.tsx      | 198 ++++++++++++++++-----------
 src/tui/index.tsx                    |  10 +-
 src/tui/resize.ts                    | 132 +++++++++++++++---
 src/tui/tui.test.tsx                 |  29 ++--
 7 files changed, 309 insertions(+), 114 deletions(-)

diff --git a/src/components/BrandBanner.tsx b/src/components/BrandBanner.tsx
index 7fc38bf339..fb6a81904a 100644
--- a/src/components/BrandBanner.tsx
+++ b/src/components/BrandBanner.tsx
@@ -10,6 +10,9 @@ const LOGO: string[] = [
   "▀ ▀ ▀▀▀ ▀▀▀ ▀ ▀  ▀  ▀▀▀ ▀▀▀ ▀ ▀ ▀▀▀   ▀▀▀ ▀▀▀ ▀▀▀",
 ];
 
+export const MIN_BANNER_COLUMNS = 80;
+export const MIN_BANNER_ROWS = 30;
+
 export interface BrandBannerProps {
   terminalProgram?: string;
   theme?: InkUITheme;
diff --git a/src/components/Layout.tsx b/src/components/Layout.tsx
index 8bf012f798..376ba98b93 100644
--- a/src/components/Layout.tsx
+++ b/src/components/Layout.tsx
@@ -8,6 +8,13 @@ import type { KeyHintProps } from "./ui/key-hint";
 export interface LayoutProps {
   // banner is content rendered above the standard breadcrumb header.
   banner?: React.ReactNode;
+  // bannerHeight is the number of terminal rows occupied by the banner.
+  bannerHeight?: number;
+  // hideBanner suppresses the banner regardless of terminal dimensions.
+  hideBanner?: boolean;
+  // bannerMinColumns/bannerMinRows suppress the banner below these dimensions.
+  bannerMinColumns?: number;
+  bannerMinRows?: number;
   // breadcrumb is passed through to the Header.
   breadcrumb: HeaderProps["breadcrumb"];
   // description is passed through to the Header, shown dimmed after the breadcrumb.
@@ -15,27 +22,47 @@ export interface LayoutProps {
   // keyHints is passed through to the Footer (KeyHint) row.
   keyHints: KeyHintProps["keys"];
   // children fill the content area between the header and footer.
-  children: React.ReactNode;
+  children:
+    | React.ReactNode
+    | ((dimensions: {
+        columns: number;
+        rows: number;
+        contentRows: number;
+        bannerVisible: boolean;
+      }) => React.ReactNode);
 }
 
+const FRAME_ROWS = 4;
+
 // Layout is the standard full-screen frame: a breadcrumb Header at the top, a
 // KeyHint Footer at the bottom, and a flexible content area in between that grows
 // to fill the remaining terminal height.
 export const Layout: React.FC<LayoutProps> = ({
   banner,
+  bannerHeight = 0,
+  hideBanner = false,
+  bannerMinColumns = 0,
+  bannerMinRows = 0,
   breadcrumb,
   description,
   keyHints,
   children,
 }) => {
   const { columns, rows } = useWindowSize();
+  const bannerVisible =
+    Boolean(banner) && !hideBanner && columns >= bannerMinColumns && rows >= bannerMinRows;
+  const contentRows = Math.max(0, rows - FRAME_ROWS - (bannerVisible ? bannerHeight : 0));
+  const content =
+    typeof children === "function"
+      ? children({ columns, rows, contentRows, bannerVisible })
+      : children;
 
   return (
     <Box width={columns} height={rows} flexDirection="column">
-      {banner}
+      {bannerVisible ? banner : null}
       <Header breadcrumb={breadcrumb} description={description} />
       <Box flexGrow={1} flexShrink={1} minHeight={0} flexDirection="column">
-        {children}
+        {content}
       </Box>
       <Footer keys={keyHints} />
     </Box>
diff --git a/src/components/RouterScreen.test.tsx b/src/components/RouterScreen.test.tsx
index d36bea0754..4a9c067d01 100644
--- a/src/components/RouterScreen.test.tsx
+++ b/src/components/RouterScreen.test.tsx
@@ -49,6 +49,10 @@ describe("menu rendering", () => {
     const entries = menuEntries(frame);
     expect(entries.screens).toContain("create");
     expect(entries.screens).toContain("eval");
+    expect(frame.split("\n").filter((line) => line.includes("❯ "))).toHaveLength(1);
+    expect(new Set([...entries.screens, ...entries.cliOnly]).size).toBe(
+      entries.screens.length + entries.cliOnly.length,
+    );
     expect(frame).toContain("config");
     expect(frame).toContain("read/write global config values");
     r.unmount();
@@ -135,6 +139,20 @@ describe("menu rendering", () => {
     nested.unmount();
   });
 
+  test("hides the brand banner when the terminal is short and restores it when enlarged", async () => {
+    const version = `v${PACKAGE_VERSION}`;
+    const r = renderScreen("/agentcore");
+    await waitForText(r.lastFrame, version);
+
+    await r.resize(80, 24);
+    expect(r.lastFrame()).not.toContain(version);
+    expect(r.lastFrame()).toContain("[enter] select");
+
+    await r.resize(100, 40);
+    await waitForText(r.lastFrame, version);
+    r.unmount();
+  });
+
   test("renders the harness subcommands when mounted at the harness path", async () => {
     const r = renderScreen("/agentcore/harness");
     await waitForText(r.lastFrame, "list");
diff --git a/src/components/RouterScreen.tsx b/src/components/RouterScreen.tsx
index cc5757a045..0a8266c7cb 100644
--- a/src/components/RouterScreen.tsx
+++ b/src/components/RouterScreen.tsx
@@ -1,6 +1,5 @@
-import React, { useContext, useEffect, useMemo, useRef, useState } from "react";
-import { Box, Text, measureElement, useApp, useInput, useStdin, type DOMElement } from "ink";
-import { useWindowSize } from "./ui/useWindowSize";
+import React, { useContext, useEffect, useMemo, useState } from "react";
+import { Box, Text, useApp, useInput, useStdin } from "ink";
 import type { Command } from "commander";
 import { Navigate, useNavigate } from "react-router";
 import {
@@ -9,17 +8,20 @@ import {
   isListedInMenu,
   isTuiCommandSupported,
 } from "../router";
+import { MIN_BANNER_COLUMNS, MIN_BANNER_ROWS, shouldHideBrandBanner } from "./BrandBanner";
 import { Layout } from "./Layout";
 import { Divider } from "./ui/divider";
 import { TextInput } from "./ui/text-input";
 import { darkTheme, glyphs } from "./ui/_core.js";
 import type { ScreenProps } from "../handlers/types";
 import { RegionPinContext } from "../handlers/utils";
-import { useScrollWindow } from "./scrollWindow";
+import { scrollWindow } from "./scrollWindow";
 
 const theme = darkTheme;
 const PLACEHOLDER = "type to choose a command";
 const CLI_ONLY_SECTION = "cli";
+const BANNER_ROWS = 4;
+const FILTER_ROWS = 2;
 
 // rootCommand walks up to the top of the Commander tree.
 function rootCommand(c: Command): Command {
@@ -152,21 +154,6 @@ function CommandMenu({
   // match is index 0, which is what a fresh query resets to.
   const highlight = Math.min(index, Math.max(0, filtered.length - 1));
 
-  // The list gets whatever height the screen leaves it (the root menu adds a
-  // banner, a long header can wrap), so measure it whenever the terminal
-  // changes size rather than subtracting a fixed count of chrome rows. The
-  // list fills that space whatever it holds, so its contents don't matter.
-  // Until the first measurement the list is clipped to the terminal height.
-  const { columns, rows } = useWindowSize();
-  const listRef = useRef<DOMElement>(null);
-  const [listRows, setListRows] = useState<number>();
-  useEffect(() => {
-    if (!listRef.current) return;
-    setListRows(measureElement(listRef.current).height);
-  }, [columns, rows]);
-  const sections = useMemo(() => filtered.map((o) => o.section), [filtered]);
-  const view = useScrollWindow(sections, highlight, listRows ?? rows);
-
   const base = "/" + path.join("/");
 
   // Width of the name column so descriptions line up (longest name + a gap).
@@ -213,6 +200,10 @@ function CommandMenu({
   return (
     <Layout
       banner={banner}
+      bannerHeight={BANNER_ROWS}
+      hideBanner={Boolean(banner) && shouldHideBrandBanner(process.env.TERM_PROGRAM)}
+      bannerMinColumns={MIN_BANNER_COLUMNS}
+      bannerMinRows={MIN_BANNER_ROWS}
       breadcrumb={path}
       description={command.description()}
       keyHints={[
@@ -224,71 +215,122 @@ function CommandMenu({
         { key: "ctrl+c", label: "quit" },
       ]}
     >
-      <Box flexDirection="column" flexGrow={1} flexShrink={1} minHeight={0}>
-        {/* Filter input. TextInput owns text editing; the highlight resets to
-            the best match whenever the query changes. */}
-        <Box paddingX={1} flexShrink={0}>
-          <TextInput
-            value={query}
-            onChange={(v) => {
-              setQuery(v);
-              setIndex(0);
-            }}
-            placeholder={PLACEHOLDER}
-            prompt="/ "
-            focus={Boolean(isRawModeSupported)}
-          />
-        </Box>
+      {({ columns, contentRows }) => (
+        <CommandMenuBody
+          columns={columns}
+          contentRows={contentRows}
+          filtered={filtered}
+          highlight={highlight}
+          isRawModeSupported={Boolean(isRawModeSupported)}
+          nameWidth={nameWidth}
+          query={query}
+          onQueryChange={(value) => {
+            setQuery(value);
+            setIndex(0);
+          }}
+        />
+      )}
+    </Layout>
+  );
+}
+
+interface CommandMenuBodyProps {
+  columns: number;
+  contentRows: number;
+  filtered: Option[];
+  highlight: number;
+  isRawModeSupported: boolean;
+  nameWidth: number;
+  query: string;
+  onQueryChange: (value: string) => void;
+}
 
-        <Divider />
+function CommandMenuBody({
+  columns,
+  contentRows,
+  filtered,
+  highlight,
+  isRawModeSupported,
+  nameWidth,
+  query,
+  onQueryChange,
+}: CommandMenuBodyProps) {
+  const sections = useMemo(() => filtered.map((option) => option.section), [filtered]);
+  const menuHeight = Math.max(0, contentRows - FILTER_ROWS);
+  const windowStart = Math.max(0, highlight - Math.floor(menuHeight / 2));
+  const view = scrollWindow({
+    sections,
+    highlight,
+    start: windowStart,
+    budget: menuHeight,
+  });
 
-        {/* Options */}
-        <Box
-          ref={listRef}
-          flexDirection="column"
-          flexGrow={1}
-          flexShrink={1}
-          minHeight={0}
-          overflow="hidden"
-        >
-          {filtered.length === 0 ? (
-            <Box paddingX={1} flexShrink={0}>
-              <Text color={theme.colors.text}>No matches</Text>
-            </Box>
-          ) : (
-            view.rows.map((row) => {
-              if (row.kind === "section") {
-                return <Divider key={`section:${row.title}`} title={row.title} />;
-              }
-              if (row.kind !== "item") {
-                return (
-                  <Box key={row.kind} paddingX={1} flexShrink={0}>
-                    <Text color={theme.colors.muted}>
-                      {`  ${row.kind === "more-above" ? "↑" : "↓"} ${row.count} more`}
-                    </Text>
-                  </Box>
-                );
-              }
-              const o = filtered[row.index]!;
-              const isHl = row.index === highlight;
+  return (
+    <Box flexDirection="column" height={contentRows} overflow="hidden">
+      <Box paddingX={1} height={1} overflow="hidden" flexShrink={0}>
+        <TextInput
+          value={query}
+          onChange={onQueryChange}
+          placeholder={PLACEHOLDER}
+          prompt="/ "
+          focus={isRawModeSupported}
+        />
+      </Box>
+
+      <Divider />
+
+      <Box flexDirection="column" height={menuHeight} overflow="hidden">
+        {filtered.length === 0 ? (
+          <Box paddingX={1} height={1} overflow="hidden">
+            <Text color={theme.colors.text}>No matches</Text>
+          </Box>
+        ) : (
+          view.rows.map((row) => {
+            if (row.kind === "section") {
+              return <Divider key={`section:${row.title}`} title={row.title} />;
+            }
+            if (row.kind !== "item") {
               return (
-                <Box key={o.name} paddingX={1} flexShrink={0}>
-                  <Text color={theme.colors.focus}>{isHl ? `${glyphs.pointer} ` : "  "}</Text>
-                  <Text
-                    bold={isHl}
-                    color={
-                      isHl ? theme.colors.focus : o.cliOnly ? theme.colors.muted : theme.colors.text
-                    }
-                  >
-                    {o.name.padEnd(nameWidth)}
+                <Box key={row.kind} paddingX={1} height={1} overflow="hidden" flexShrink={0}>
+                  <Text color={theme.colors.muted}>
+                    {`  ${row.kind === "more-above" ? "↑" : "↓"} ${row.count} more`}
                   </Text>
-                  <Text color={theme.colors.muted}>{o.description}</Text>
                 </Box>
               );
-            })
-          )}
-        </Box>
+            }
+
+            const option = filtered[row.index]!;
+            const isHighlighted = row.index === highlight;
+            return (
+              <Box
+                key={option.name}
+                paddingX={1}
+                width={columns}
+                height={1}
+                overflow="hidden"
+                flexShrink={0}
+              >
+                <Text color={theme.colors.focus}>
+                  {isHighlighted ? `${glyphs.pointer} ` : "  "}
+                </Text>
+                <Text
+                  bold={isHighlighted}
+                  color={
+                    isHighlighted
+                      ? theme.colors.focus
+                      : option.cliOnly
+                        ? theme.colors.muted
+                        : theme.colors.text
+                  }
+                >
+                  {option.name.padEnd(nameWidth)}
+                </Text>
+                <Text color={theme.colors.muted}>{option.description}</Text>
+              </Box>
+            );
+          })
+        )}
       </Box>
-    </Layout>
+    </Box>
   );
 }
diff --git a/src/tui/index.tsx b/src/tui/index.tsx
index a2244af003..4186440411 100644
--- a/src/tui/index.tsx
+++ b/src/tui/index.tsx
@@ -14,7 +14,7 @@ import type { Core } from "../handlers/types";
 import { JsonKey } from "../handlers/keys";
 import { ExitCode, InvalidEnvironmentError } from "../errors";
 import { TuiExitMessageKey } from "./exitMessage";
-import { clearScreenOnNarrowing } from "./resize";
+import { createResizeGate } from "./resize";
 
 // renderJson pretty-prints a value as indented JSON. It is the output
 // counterpart to renderTui: handlers call it to emit machine-readable results
@@ -62,19 +62,19 @@ export async function renderTuiAt(
 
   // alternateScreen switches the terminal to its alternate buffer so the TUI
   // takes over the screen and the prior scrollback is restored on exit (like Vim).
-  const stopClearingOnResize = clearScreenOnNarrowing(io.stdout);
+  const resizeGate = createResizeGate(io.stdout);
   const { waitUntilExit } = render(<Root path={path} ctx={tuiContext} core={core} />, {
     stdin: io.stdin,
-    stdout: io.stdout,
+    stdout: resizeGate.stdout,
     stderr: io.stderr,
     interactive: true,
     alternateScreen: true,
-    incrementalRendering: true,
+    incrementalRendering: false,
   });
   try {
     await waitUntilExit();
   } finally {
-    stopClearingOnResize();
+    resizeGate.dispose();
   }
   if (exitMessage !== undefined) {
     io.stdout.write(exitMessage.endsWith("\n") ? exitMessage : `${exitMessage}\n`);
diff --git a/src/tui/resize.ts b/src/tui/resize.ts
index 81c82ac209..c301c02d16 100644
--- a/src/tui/resize.ts
+++ b/src/tui/resize.ts
@@ -1,26 +1,120 @@
+import { EventEmitter } from "node:events";
+
 const ERASE_SCREEN_AND_HOME = "\u001B[2J\u001B[H";
+const RESIZE_SETTLE_MS = 100;
+
+type Listener = (...args: unknown[]) => void;
+
+export interface ResizeGate {
+  stdout: NodeJS.WriteStream;
+  dispose(): void;
+}
+
+// Ink renders synchronously for every stdout resize event, bypassing its normal
+// frame-rate throttle. During a width reduction that both repaints every column
+// and races the terminal's own line wrapping. This facade lets growth through
+// immediately, but holds a shrinking size until the resize gesture settles.
+// Ink then sees one resize event and redraws once at the final dimensions.
+export function createResizeGate(stdout: NodeJS.WriteStream): ResizeGate {
+  const resizeEvents = new EventEmitter();
+  let columns = stdout.columns;
+  let rows = stdout.rows;
+  let pendingColumns = columns;
+  let pendingRows = rows;
+  let shrinking = false;
+  let settleTimer: ReturnType<typeof setTimeout> | undefined;
+  let gatedStdout: NodeJS.WriteStream;
+
+  const addListener = (
+    method: "on" | "once" | "prependListener" | "prependOnceListener",
+    event: string | symbol,
+    listener: Listener,
+  ): NodeJS.WriteStream => {
+    if (event === "resize") resizeEvents[method](event, listener);
+    else stdout[method](event, listener);
+    return gatedStdout;
+  };
+
+  const removeListener = (event: string | symbol, listener: Listener): NodeJS.WriteStream => {
+    if (event === "resize") resizeEvents.off(event, listener);
+    else stdout.off(event, listener);
+    return gatedStdout;
+  };
+
+  gatedStdout = new Proxy(stdout, {
+    get(target, property) {
+      if (property === "columns") return columns;
+      if (property === "rows") return rows;
+      if (property === "on" || property === "addListener") {
+        return (event: string | symbol, listener: Listener) => addListener("on", event, listener);
+      }
+      if (property === "once") {
+        return (event: string | symbol, listener: Listener) => addListener("once", event, listener);
+      }
+      if (property === "prependListener") {
+        return (event: string | symbol, listener: Listener) =>
+          addListener("prependListener", event, listener);
+      }
+      if (property === "prependOnceListener") {
+        return (event: string | symbol, listener: Listener) =>
+          addListener("prependOnceListener", event, listener);
+      }
+      if (property === "off" || property === "removeListener") {
+        return removeListener;
+      }
+      if (property === "listenerCount") {
+        return (event: string | symbol) =>
+          event === "resize" ? resizeEvents.listenerCount(event) : stdout.listenerCount(event);
+      }
+
+      const value: unknown = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  }) as NodeJS.WriteStream;
+
+  const publish = (clear: boolean) => {
+    const changed = columns !== pendingColumns || rows !== pendingRows;
+    if (!changed) return;
+
+    if (clear) stdout.write(ERASE_SCREEN_AND_HOME);
+    columns = pendingColumns;
+    rows = pendingRows;
+    resizeEvents.emit("resize");
+  };
+
+  const settle = () => {
+    settleTimer = undefined;
+    const narrowed =
+      pendingColumns !== undefined && columns !== undefined && pendingColumns < columns;
+    publish(narrowed);
+    shrinking = false;
+  };
 
-// clearScreenOnNarrowing wipes the whole alternate screen whenever the terminal
-// gets narrower. Ink erases its previous frame by moving up one row per frame
-// line, but the terminal has already rewrapped any line wider than the new
-// width onto several rows, so that erase falls short and leaves stale copies of
-// full-width rows (dividers, the key-hint rule) stacked above the next frame.
-// The listener is prepended so it runs before Ink's own resize handler, which
-// on narrowing forgets its previous frame and repaints the whole frame from the
-// home position this leaves the cursor at. Widening needs nothing: no line
-// wraps, and Ink keeps diffing against its previous frame, so clearing there
-// would blank the rows it does not rewrite. Returns the unsubscribe function.
-export function clearScreenOnNarrowing(stdout: NodeJS.WriteStream): () => void {
-  let lastColumns = stdout.columns;
   const onResize = () => {
-    const columns = stdout.columns;
-    if (columns && lastColumns && columns < lastColumns) {
-      stdout.write(ERASE_SCREEN_AND_HOME);
+    pendingColumns = stdout.columns;
+    pendingRows = stdout.rows;
+    const narrowed =
+      pendingColumns !== undefined && columns !== undefined && pendingColumns < columns;
+    const shortened = pendingRows !== undefined && rows !== undefined && pendingRows < rows;
+
+    if (shrinking || narrowed || shortened) {
+      shrinking = true;
+      if (settleTimer) clearTimeout(settleTimer);
+      settleTimer = setTimeout(settle, RESIZE_SETTLE_MS);
+      return;
     }
-    lastColumns = columns;
+
+    publish(false);
   };
-  stdout.prependListener("resize", onResize);
-  return () => {
-    stdout.off("resize", onResize);
+
+  stdout.on("resize", onResize);
+
+  return {
+    stdout: gatedStdout,
+    dispose() {
+      if (settleTimer) clearTimeout(settleTimer);
+      stdout.off("resize", onResize);
+      resizeEvents.removeAllListeners();
+    },
   };
 }
diff --git a/src/tui/tui.test.tsx b/src/tui/tui.test.tsx
index 98fd4aaa9f..993133b25b 100644
--- a/src/tui/tui.test.tsx
+++ b/src/tui/tui.test.tsx
@@ -117,12 +117,13 @@ describe("TUI stream boundary", () => {
 describe("TUI resize", () => {
   const ERASE_SCREEN = "\u001B[2J\u001B[H";
 
-  function resize(stdout: NodeJS.WriteStream, columns: number) {
+  function resize(stdout: NodeJS.WriteStream, columns: number, rows = stdout.rows) {
     Object.defineProperty(stdout, "columns", { configurable: true, value: columns });
+    Object.defineProperty(stdout, "rows", { configurable: true, value: rows });
     stdout.emit("resize");
   }
 
-  test("narrowing wipes the screen before the frame is repainted", async () => {
+  test("shrinking redraws once after resizing settles", async () => {
     const { streams, stdin } = ttyTestIO(120, 40);
     const root = createRootHandler(new TestCoreClient(), {
       io: streams.io,
@@ -131,17 +132,27 @@ describe("TUI resize", () => {
     });
     const routePromise = root.route(["node", "agentcore"]);
     await waitFor(() => streams.stdout().includes("deploy"));
+    await tick();
 
     const beforeNarrow = streams.stdout().length;
-    resize(streams.io.stdout, 60);
-    await waitFor(() => streams.stdout().slice(beforeNarrow).includes("deploy"));
-    const narrowed = streams.stdout().slice(beforeNarrow);
-    expect(narrowed.startsWith(ERASE_SCREEN)).toBe(true);
-    expect(narrowed.indexOf("deploy")).toBeGreaterThan(0);
+    resize(streams.io.stdout, 110, 38);
+    await tick(25);
+    resize(streams.io.stdout, 100, 35);
+    await tick(25);
+    resize(streams.io.stdout, 90, 30);
+    await tick(25);
+    expect(streams.stdout()).toHaveLength(beforeNarrow);
+
+    await waitFor(() => {
+      const resized = streams.stdout().slice(beforeNarrow);
+      const clearAt = resized.indexOf(ERASE_SCREEN);
+      return clearAt >= 0 && resized.indexOf("deploy", clearAt) > clearAt;
+    });
+    expect(streams.stdout().slice(beforeNarrow).split(ERASE_SCREEN)).toHaveLength(2);
 
     const beforeWiden = streams.stdout().length;
-    resize(streams.io.stdout, 100);
-    await tick();
+    resize(streams.io.stdout, 100, 35);
+    await waitFor(() => streams.stdout().length > beforeWiden);
     expect(streams.stdout().slice(beforeWiden)).not.toContain(ERASE_SCREEN);
 
     stdin.write(String.fromCharCode(3));

From ba8306e67a15273a345f006d537ad29374a0c16c Mon Sep 17 00:00:00 2001
From: Nicolas Borges <nickdb@amazon.com>
Date: Tue, 29 Sep 2026 20:46:23 -0400
Subject: [PATCH 2/5] refactor(tui): centralize banner height

---
 src/components/BrandBanner.tsx  |  1 +
 src/components/RouterScreen.tsx | 10 +++++++---
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/src/components/BrandBanner.tsx b/src/components/BrandBanner.tsx
index fb6a81904a..dfb84aaa8e 100644
--- a/src/components/BrandBanner.tsx
+++ b/src/components/BrandBanner.tsx
@@ -12,6 +12,7 @@ const LOGO: string[] = [
 
 export const MIN_BANNER_COLUMNS = 80;
 export const MIN_BANNER_ROWS = 30;
+export const BRAND_BANNER_ROWS = LOGO.length + 1;
 
 export interface BrandBannerProps {
   terminalProgram?: string;
diff --git a/src/components/RouterScreen.tsx b/src/components/RouterScreen.tsx
index 0a8266c7cb..614567abd0 100644
--- a/src/components/RouterScreen.tsx
+++ b/src/components/RouterScreen.tsx
@@ -8,7 +8,12 @@ import {
   isListedInMenu,
   isTuiCommandSupported,
 } from "../router";
-import { MIN_BANNER_COLUMNS, MIN_BANNER_ROWS, shouldHideBrandBanner } from "./BrandBanner";
+import {
+  BRAND_BANNER_ROWS,
+  MIN_BANNER_COLUMNS,
+  MIN_BANNER_ROWS,
+  shouldHideBrandBanner,
+} from "./BrandBanner";
 import { Layout } from "./Layout";
 import { Divider } from "./ui/divider";
 import { TextInput } from "./ui/text-input";
@@ -20,7 +25,6 @@ import { scrollWindow } from "./scrollWindow";
 const theme = darkTheme;
 const PLACEHOLDER = "type to choose a command";
 const CLI_ONLY_SECTION = "cli";
-const BANNER_ROWS = 4;
 const FILTER_ROWS = 2;
 
 // rootCommand walks up to the top of the Commander tree.
@@ -200,7 +204,7 @@ function CommandMenu({
   return (
     <Layout
       banner={banner}
-      bannerHeight={BANNER_ROWS}
+      bannerHeight={BRAND_BANNER_ROWS}
       hideBanner={Boolean(banner) && shouldHideBrandBanner(process.env.TERM_PROGRAM)}
       bannerMinColumns={MIN_BANNER_COLUMNS}
       bannerMinRows={MIN_BANNER_ROWS}

From c8fb2805eb8122715d180b320977b9990cd692de Mon Sep 17 00:00:00 2001
From: Nicolas Borges <nickdb@amazon.com>
Date: Tue, 29 Sep 2026 20:46:54 -0400
Subject: [PATCH 3/5] fix(tui): account for wrapped headers

---
 src/components/Layout.tsx            | 17 +++++++++++++----
 src/components/RouterScreen.test.tsx | 14 ++++++++++++++
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/src/components/Layout.tsx b/src/components/Layout.tsx
index 376ba98b93..0b8e5854e9 100644
--- a/src/components/Layout.tsx
+++ b/src/components/Layout.tsx
@@ -1,5 +1,5 @@
 import React from "react";
-import { Box } from "ink";
+import { Box, useBoxMetrics, type DOMElement } from "ink";
 import { useWindowSize } from "./ui/useWindowSize";
 import { Header, type HeaderProps } from "./Header";
 import { Footer } from "./Footer";
@@ -32,7 +32,8 @@ export interface LayoutProps {
       }) => React.ReactNode);
 }
 
-const FRAME_ROWS = 4;
+const DEFAULT_HEADER_ROWS = 2;
+const FOOTER_ROWS = 2;
 
 // Layout is the standard full-screen frame: a breadcrumb Header at the top, a
 // KeyHint Footer at the bottom, and a flexible content area in between that grows
@@ -49,9 +50,15 @@ export const Layout: React.FC<LayoutProps> = ({
   children,
 }) => {
   const { columns, rows } = useWindowSize();
+  const headerRef = React.useRef<DOMElement>(null);
+  const { height: measuredHeaderRows, hasMeasured: hasMeasuredHeader } = useBoxMetrics(headerRef);
   const bannerVisible =
     Boolean(banner) && !hideBanner && columns >= bannerMinColumns && rows >= bannerMinRows;
-  const contentRows = Math.max(0, rows - FRAME_ROWS - (bannerVisible ? bannerHeight : 0));
+  const headerRows = hasMeasuredHeader ? measuredHeaderRows : DEFAULT_HEADER_ROWS;
+  const contentRows = Math.max(
+    0,
+    rows - headerRows - FOOTER_ROWS - (bannerVisible ? bannerHeight : 0),
+  );
   const content =
     typeof children === "function"
       ? children({ columns, rows, contentRows, bannerVisible })
@@ -60,7 +67,9 @@ export const Layout: React.FC<LayoutProps> = ({
   return (
     <Box width={columns} height={rows} flexDirection="column">
       {bannerVisible ? banner : null}
-      <Header breadcrumb={breadcrumb} description={description} />
+      <Box ref={headerRef} flexShrink={0}>
+        <Header breadcrumb={breadcrumb} description={description} />
+      </Box>
       <Box flexGrow={1} flexShrink={1} minHeight={0} flexDirection="column">
         {content}
       </Box>
diff --git a/src/components/RouterScreen.test.tsx b/src/components/RouterScreen.test.tsx
index 4a9c067d01..d1b5d5eb18 100644
--- a/src/components/RouterScreen.test.tsx
+++ b/src/components/RouterScreen.test.tsx
@@ -433,6 +433,20 @@ describe("short terminals", () => {
     r.unmount();
   });
 
+  test("accounts for a wrapped header when scrolling a narrow terminal", async () => {
+    const full = await fullMenu();
+    const r = renderScreen("/agentcore");
+    await waitForText(r.lastFrame, "❯ create");
+    await r.resize(40, ROWS);
+
+    for (let i = 0; i < full.names.length; i++) {
+      if (i > 0) await r.press("down");
+      expect(r.lastFrame()).toMatch(new RegExp(`❯\\s*${full.names[i]}`));
+    }
+
+    r.unmount();
+  });
+
   test("a nested menu, without the banner, uses the rows the banner would take", async () => {
     const r = renderScreen("/agentcore/harness");
     await waitForText(r.lastFrame, "❯ ");

From 9ec340f6da941322f2dec58bce083b9004dc6a19 Mon Sep 17 00:00:00 2001
From: Nicolas Borges <nickdb@amazon.com>
Date: Tue, 29 Sep 2026 20:47:08 -0400
Subject: [PATCH 4/5] fix(tui): repaint after restored resize

---
 src/tui/resize.ts    | 18 +++++++++++++++---
 src/tui/tui.test.tsx | 28 ++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/src/tui/resize.ts b/src/tui/resize.ts
index c301c02d16..d2fc106604 100644
--- a/src/tui/resize.ts
+++ b/src/tui/resize.ts
@@ -84,9 +84,21 @@ export function createResizeGate(stdout: NodeJS.WriteStream): ResizeGate {
 
   const settle = () => {
     settleTimer = undefined;
-    const narrowed =
-      pendingColumns !== undefined && columns !== undefined && pendingColumns < columns;
-    publish(narrowed);
+    const changed = columns !== pendingColumns || rows !== pendingRows;
+    if (changed) {
+      publish(true);
+    } else if (columns !== undefined && columns > 1) {
+      // Ink caches the last rendered frame. If a shrink gesture returns to its
+      // starting size, a same-size resize event is skipped after we clear the
+      // terminal. Briefly publish a safe, narrower width to invalidate that
+      // cache, then publish the real dimensions. Both renders happen only after
+      // the gesture settles, and the synthetic width never exceeds the terminal.
+      stdout.write(ERASE_SCREEN_AND_HOME);
+      columns--;
+      resizeEvents.emit("resize");
+      columns = pendingColumns;
+      resizeEvents.emit("resize");
+    }
     shrinking = false;
   };
 
diff --git a/src/tui/tui.test.tsx b/src/tui/tui.test.tsx
index 993133b25b..b9249151ab 100644
--- a/src/tui/tui.test.tsx
+++ b/src/tui/tui.test.tsx
@@ -159,4 +159,32 @@ describe("TUI resize", () => {
     await expect(routePromise).resolves.toBeUndefined();
     expect(streams.io.stdout.listenerCount("resize")).toBe(0);
   });
+
+  test("repaints when a shrink gesture returns to the cached size", async () => {
+    const { streams, stdin } = ttyTestIO(100, 40);
+    const root = createRootHandler(new TestCoreClient(), {
+      io: streams.io,
+      logger: createSilentLogger(),
+      globalConfigAccessor: new TestGlobalConfigAccessor(),
+    });
+    const routePromise = root.route(["node", "agentcore"]);
+    await waitFor(() => streams.stdout().includes("deploy"));
+    await tick();
+
+    const beforeResize = streams.stdout().length;
+    resize(streams.io.stdout, 100, 15);
+    await tick(25);
+    resize(streams.io.stdout, 100, 40);
+    await tick(25);
+    expect(streams.stdout()).toHaveLength(beforeResize);
+
+    await waitFor(() => {
+      const resized = streams.stdout().slice(beforeResize);
+      const clearAt = resized.indexOf(ERASE_SCREEN);
+      return clearAt >= 0 && resized.indexOf("deploy", clearAt) > clearAt;
+    });
+
+    stdin.write(String.fromCharCode(3));
+    await expect(routePromise).resolves.toBeUndefined();
+  });
 });

From c247255326d74af69c60f9d814f59c56d7e22dad Mon Sep 17 00:00:00 2001
From: Nicolas Borges <nickdb@amazon.com>
Date: Tue, 29 Sep 2026 20:57:04 -0400
Subject: [PATCH 5/5] test(tui): avoid platform-sensitive resize timing

---
 src/tui/tui.test.tsx | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/src/tui/tui.test.tsx b/src/tui/tui.test.tsx
index b9249151ab..6af737c136 100644
--- a/src/tui/tui.test.tsx
+++ b/src/tui/tui.test.tsx
@@ -136,11 +136,8 @@ describe("TUI resize", () => {
 
     const beforeNarrow = streams.stdout().length;
     resize(streams.io.stdout, 110, 38);
-    await tick(25);
     resize(streams.io.stdout, 100, 35);
-    await tick(25);
     resize(streams.io.stdout, 90, 30);
-    await tick(25);
     expect(streams.stdout()).toHaveLength(beforeNarrow);
 
     await waitFor(() => {
@@ -173,9 +170,7 @@ describe("TUI resize", () => {
 
     const beforeResize = streams.stdout().length;
     resize(streams.io.stdout, 100, 15);
-    await tick(25);
     resize(streams.io.stdout, 100, 40);
-    await tick(25);
     expect(streams.stdout()).toHaveLength(beforeResize);
 
     await waitFor(() => {