@pi-archimedes/ui 2.10.3 → 2.11.0

package/src/index.test.ts

@@ -9,26 +9,25 @@ import type { TUI, EditorTheme, Component } from "@earendil-works/pi-tui";
 
 // ── Mock modules ─────────────────────────────────────────────────────────────
 
-vi.mock("@pi-archimedes/core/settings-io", () => ({
-  loadConfig: vi.fn(),
-  saveConfig: vi.fn(),
-  removeConfig: vi.fn(),
-}));
-
-vi.mock("./config.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("./config.js")>();
+// Real `readEffectiveSettings`, so the harness's `pi.getSettings()` is what the
+// splash's `quietStartup` read actually goes through; the namespace helpers are
+// stubbed because every other settings read in these tests is about `ui`'s own
+// config.
+vi.mock("@pi-archimedes/core/settings-io", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@pi-archimedes/core/settings-io")>();
   return {
     ...actual,
-    loadUIConfig: vi.fn(),
+    loadConfig: vi.fn(),
+    saveConfig: vi.fn(),
+    removeConfig: vi.fn(),
   };
 });
 
-vi.mock("./startup/capture.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("./startup/capture.js")>();
+vi.mock("./config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./config.js")>();
   return {
     ...actual,
-    patchConsoleLog: vi.fn(),
-    unpatchConsoleLog: vi.fn(),
+    loadUIConfig: vi.fn(),
   };
 });
 
@@ -46,6 +45,8 @@ vi.mock("./startup/index.js", async (importOriginal) => {
     ...actual,
     renderHeader: vi.fn(() => ["header line"]),
     patchStartupListing: vi.fn(),
+    revealStartupListing: vi.fn(),
+    stopStartupListing: vi.fn(),
   };
 });
 
@@ -56,32 +57,27 @@ vi.mock("./migration.js", () => ({
   UI_CONFIG_KEYS: [],
 }));
 
-vi.mock("./bash/index.js", () => ({
-  registerBashToolOverride: vi.fn(),
-  clearActiveBashIntervals: vi.fn(),
-}));
-
-vi.mock("./codemode/index.js", () => ({
-  registerCodemodeToolOverride: vi.fn(async () => true),
-  clearActiveCodemodeIntervals: vi.fn(),
-}));
-
+// The renderers stay real: the resolver hands them straight to pi, so the
+// tests can assert on their identity.
 import defaultExport, {
   registerUI,
-  unpatchConsoleLog,
   getUISettingsItems,
   loadUIConfig,
   saveUIConfig,
   DEFAULT_UI_CONFIG,
   ANIMATION_STYLES,
 } from "./index.js";
-import { patchConsoleLog } from "./startup/capture.js";
 import { migrateCoreToUIConfig } from "./migration.js";
-import { registerBashToolOverride, clearActiveBashIntervals } from "./bash/index.js";
-import { registerCodemodeToolOverride, clearActiveCodemodeIntervals } from "./codemode/index.js";
+import { renderBashCall, renderBashResult } from "./bash/index.js";
+import { renderCodemodeCall, renderCodemodeResult } from "./codemode/index.js";
 import { patchThinkingRenderer } from "./thinking/patch.js";
 import { transformThinkingContent } from "./thinking/transform.js";
-import { renderHeader, patchStartupListing } from "./startup/index.js";
+import {
+  renderHeader,
+  patchStartupListing,
+  revealStartupListing,
+  stopStartupListing,
+} from "./startup/index.js";
 
 // ── Test helpers ─────────────────────────────────────────────────────────────
 
@@ -89,6 +85,9 @@ interface UiSpies {
   setHeader: ReturnType<typeof vi.fn>;
   setEditorComponent: ReturnType<typeof vi.fn>;
   setWorkingVisible: ReturnType<typeof vi.fn>;
+  setWorkingIndicator: ReturnType<typeof vi.fn>;
+  notify: ReturnType<typeof vi.fn>;
+  setHiddenThinkingLabel: ReturnType<typeof vi.fn>;
 }
 
 function makeCtx(hasUI = true): { ctx: ExtensionContext; ui: UiSpies } {
@@ -96,6 +95,9 @@ function makeCtx(hasUI = true): { ctx: ExtensionContext; ui: UiSpies } {
     setHeader: vi.fn(),
     setEditorComponent: vi.fn(),
     setWorkingVisible: vi.fn(),
+    setWorkingIndicator: vi.fn(),
+    notify: vi.fn(),
+    setHiddenThinkingLabel: vi.fn(),
   };
   const ctx = {
     hasUI,
@@ -103,29 +105,67 @@ function makeCtx(hasUI = true): { ctx: ExtensionContext; ui: UiSpies } {
     ui: { ...ui, theme: {} as Theme },
     isIdle: vi.fn(() => true),
     shutdown: vi.fn(),
+    scopedModels: [],
   } as unknown as ExtensionContext;
   return { ctx, ui };
 }
 
-function setupHarness(): {
+/** Stand-in for what `next()` hands back: pi's own renderers for the tool. */
+const NATIVE = Object.freeze({ native: true });
+
+/** What a resolver resolves for a tool name, and whether it called `next()`. */
+function resolve(
+  resolver: ((name: string, next: () => any) => any) | undefined,
+  toolName: string,
+): { result: unknown; nextCalls: number } {
+  let nextCalls = 0;
+  const result = resolver?.(toolName, () => {
+    nextCalls++;
+    return NATIVE;
+  });
+  return { result, nextCalls };
+}
+
+/** A `pi` handle whose `getSettings()` answers what pi would apply. */
+function makePi(settings: Record<string, unknown> = {}): {
   pi: ExtensionAPI;
-  triggerStart: (ctx: ExtensionContext) => void;
-  triggerShutdown: (ctx: ExtensionContext) => void;
-  triggerMessageEnd: (msg: unknown) => void;
+  listeners: Record<string, ((event: any, ctx: any) => void)[]>;
+  renderers: ((name: string, next: () => any) => any)[];
 } {
   const listeners: Record<string, ((event: any, ctx: any) => void)[]> = {};
+  const renderers: ((name: string, next: () => any) => any)[] = [];
   const pi = {
     on: vi.fn((event: string, handler: (event: any, ctx: any) => void) => {
       listeners[event] = listeners[event] ?? [];
       listeners[event]!.push(handler);
     }),
     registerTool: vi.fn(),
+    registerToolRenderer: vi.fn(
+      (resolver: (name: string, next: () => any) => any) => {
+        renderers.push(resolver);
+      },
+    ),
+    getSettings: vi.fn(() => settings),
   } as unknown as ExtensionAPI;
+  return { pi, listeners, renderers };
+}
+
+function setupHarness(
+  settings: Record<string, unknown> = {},
+): {
+  pi: ExtensionAPI;
+  renderers: ((name: string, next: () => any) => any)[];
+  triggerStart: (ctx: ExtensionContext) => void;
+  triggerShutdown: (ctx: ExtensionContext) => void;
+  triggerMessageEnd: (msg: unknown) => void;
+} {
+  const { pi, listeners, renderers } = makePi(settings);
 
   registerUI(pi);
 
   return {
     pi,
+    renderers,
     triggerStart: (ctx: ExtensionContext) => {
       for (const h of listeners["session_start"] ?? []) {
         h(null, ctx);
@@ -147,7 +187,11 @@ function setupHarness(): {
 describe("packages/ui lifecycle and registration", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    vi.mocked(loadUIConfig).mockReturnValue({ ...DEFAULT_UI_CONFIG });
+    // The splash is opt-in (`startupSplash` defaults to off), and this file is
+    // where the splash's installation and teardown are asserted — so the
+    // harness asks for it. The default-off path, and the whole
+    // `startupSplash` × `quietStartup` table, is `startup-splash-gate.test.ts`.
+    vi.mocked(loadUIConfig).mockReturnValue({ ...DEFAULT_UI_CONFIG, startupSplash: true });
   });
 
   afterEach(() => {
@@ -156,7 +200,6 @@ describe("packages/ui lifecycle and registration", () => {
 
   describe("exports", () => {
     it("re-exports expected functions and constants", () => {
-      expect(typeof unpatchConsoleLog).toBe("function");
       expect(typeof getUISettingsItems).toBe("function");
       expect(typeof loadUIConfig).toBe("function");
       expect(typeof saveUIConfig).toBe("function");
@@ -166,35 +209,146 @@ describe("packages/ui lifecycle and registration", () => {
     });
 
     it("default export delegates to registerUI", () => {
-      const pi = { on: vi.fn() } as unknown as ExtensionAPI;
+      const pi = { on: vi.fn(), getSettings: vi.fn(() => ({})) } as unknown as ExtensionAPI;
       defaultExport(pi);
       expect(migrateCoreToUIConfig).toHaveBeenCalled();
-      expect(patchConsoleLog).toHaveBeenCalled();
     });
   });
 
   describe("registerUI initialization", () => {
-    it("calls migrateCoreToUIConfig and patchConsoleLog", () => {
+    it("calls migrateCoreToUIConfig and leaves the console alone", () => {
       const { pi } = setupHarness();
       expect(migrateCoreToUIConfig).toHaveBeenCalledTimes(1);
-      expect(patchConsoleLog).toHaveBeenCalledTimes(1);
+      // Nobody may wrap console.log to watch pi's startup output: the scrape is
+      // gone, and a wrapped log both smears the frame and hides pi's own line.
+      expect(console.log.name).toBe("log");
       expect(pi.on).toHaveBeenCalledWith("session_shutdown", expect.any(Function));
       expect(pi.on).toHaveBeenCalledWith("session_start", expect.any(Function));
     });
   });
 
-  describe("session_start with interactive UI (hasUI: true)", () => {
-    it("configures bash tool override, codemode tool override, header, editor, and thinking renderer", () => {
-      const { triggerStart } = setupHarness();
-      const { ctx, ui } = makeCtx(true);
+  // ADR 0029: presentation is resolved through `pi.registerToolRenderer()`,
+  // so the styling settings choose between our row and pi's native row inside
+  // one resolver, instead of re-registering the tool.
+  describe("tool renderer resolution", () => {
+    it("resolves bash to the Archimedes renderers when styling is on", () => {
+      const { renderers, triggerStart } = setupHarness();
+      const { ctx } = makeCtx(true);
 
       triggerStart(ctx);
 
-      // Bash tool override
-      expect(registerBashToolOverride).toHaveBeenCalledWith(expect.anything(), "/workspace/test-project");
+      expect(renderers.length).toBe(1);
+      const { result, nextCalls } = resolve(renderers[0], "bash");
+      expect(result).toMatchObject({
+        renderCall: renderBashCall,
+        renderResult: renderBashResult,
+      });
+      // `next()` is consulted and spread first, so a key the built-in
+      // definition declares besides our two — `renderShell` is the one that
+      // matters today — survives resolution instead of being dropped.
+      expect(nextCalls).toBe(1);
+      expect(result).toHaveProperty("native", true);
+    });
 
-      // Codemode tool override (fire-and-forget)
-      expect(registerCodemodeToolOverride).toHaveBeenCalledWith(expect.anything());
+    it("gives back pi's native bash row when bashToolStyling is off", () => {
+      vi.mocked(loadUIConfig).mockReturnValue({
+        ...DEFAULT_UI_CONFIG,
+        bashToolStyling: false,
+      });
+      const { renderers, triggerStart } = setupHarness();
+      const { ctx } = makeCtx(true);
+
+      triggerStart(ctx);
+
+      const { result, nextCalls } = resolve(renderers[0], "bash");
+      expect(result).toBe(NATIVE);
+      expect(nextCalls).toBe(1);
+    });
+
+    it("gives back pi's native bash row when toolStyle is Native", () => {
+      vi.mocked(loadUIConfig).mockReturnValue({
+        ...DEFAULT_UI_CONFIG,
+        toolStyle: "Native",
+      });
+      const { renderers, triggerStart } = setupHarness();
+      const { ctx } = makeCtx(true);
+
+      triggerStart(ctx);
+
+      expect(resolve(renderers[0], "bash")).toEqual({ result: NATIVE, nextCalls: 1 });
+    });
+
+    it("follows a settings change made between sessions", () => {
+      const { renderers, triggerStart } = setupHarness();
+      const { ctx } = makeCtx(true);
+
+      triggerStart(ctx);
+      expect(resolve(renderers[0], "bash").result).toMatchObject({ renderCall: renderBashCall });
+
+      // The user turns bash styling off in `/archimedes` and starts a session.
+      vi.mocked(loadUIConfig).mockReturnValue({
+        ...DEFAULT_UI_CONFIG,
+        bashToolStyling: false,
+      });
+      triggerStart(ctx);
+
+      expect(resolve(renderers[0], "bash")).toEqual({ result: NATIVE, nextCalls: 1 });
+    });
+
+    it("leaves every other tool to the remaining resolvers", () => {
+      const { renderers, triggerStart } = setupHarness();
+      const { ctx } = makeCtx(true);
+
+      triggerStart(ctx);
+
+      for (const name of ["read", "edit", "write", "grep", "todo"]) {
+        expect(resolve(renderers[0], name)).toEqual({ result: NATIVE, nextCalls: 1 });
+      }
+    });
+
+    it("resolves codemode to the Archimedes renderers when styling is on", () => {
+      const { renderers, triggerStart } = setupHarness();
+      const { ctx } = makeCtx(true);
+
+      triggerStart(ctx);
+
+      expect(resolve(renderers[0], "codemode").result).toMatchObject({
+        renderCall: renderCodemodeCall,
+        renderResult: renderCodemodeResult,
+        native: true,
+      });
+    });
+
+    it("gives back pi's own codemode row when codemodeToolStyling is off", () => {
+      vi.mocked(loadUIConfig).mockReturnValue({
+        ...DEFAULT_UI_CONFIG,
+        codemodeToolStyling: false,
+      });
+      const { renderers, triggerStart } = setupHarness();
+      const { ctx } = makeCtx(true);
+
+      triggerStart(ctx);
+
+      expect(resolve(renderers[0], "codemode")).toEqual({ result: NATIVE, nextCalls: 1 });
+    });
+
+    it("registers the resolver once even across repeated session_start (/reload)", () => {
+      const { renderers, triggerStart } = setupHarness();
+      const { ctx } = makeCtx(true);
+
+      triggerStart(ctx);
+      triggerStart(ctx);
+
+      expect(renderers.length).toBe(1);
+    });
+  });
+
+  describe("session_start with interactive UI (hasUI: true)", () => {
+    it("configures the header, editor and thinking renderer", () => {
+      const { renderers, triggerStart } = setupHarness();
+      const { ctx, ui } = makeCtx(true);
+
+      triggerStart(ctx);
 
       // Header installation
       expect(ui.setHeader).toHaveBeenCalledTimes(1);
@@ -204,11 +358,16 @@ describe("packages/ui lifecycle and registration", () => {
       const comp = headerFactory(fakeTui, fakeTheme);
       expect(typeof comp.render).toBe("function");
       comp.render(80);
-      expect(renderHeader).toHaveBeenCalledWith(fakeTheme, expect.any(Object), 80, 21);
-      expect(patchStartupListing).toHaveBeenCalledWith(fakeTui, fakeTheme, expect.any(Object));
-
-      // Working visibility and Editor component
-      expect(ui.setWorkingVisible).toHaveBeenCalledWith(false); // spinFlag is true by default
+      expect(renderHeader).toHaveBeenCalledWith(fakeTheme, expect.any(Object), 80);
+      expect(patchStartupListing).toHaveBeenCalledWith(fakeTui, expect.any(Object));
+
+      // Working indicator and Editor component. pi's working row ("Working",
+      // plus its own animated indicator) and our border spinner say the same
+      // thing — `editorSpinLabel` defaults to "Working" too — so with the spinner
+      // on the row is hidden through pi's own API rather than left showing an
+      // indicator-less label.
+      expect(ui.setWorkingVisible).toHaveBeenCalledWith(false);
+      expect(ui.setWorkingIndicator).toHaveBeenCalledWith(undefined);
       expect(ui.setEditorComponent).toHaveBeenCalledTimes(1);
       const editorFactory = ui.setEditorComponent.mock.calls[0]![0];
       const editorInstance = editorFactory(fakeTui, { borderColor: (s: string) => s } as EditorTheme, {} as KeybindingsManager);
@@ -224,33 +383,41 @@ describe("packages/ui lifecycle and registration", () => {
           autoCollapseThinking: false,
           thinkingStyle: "Full",
         }),
+        // The user-facing surface is injected: `patch.ts` has no ctx of its
+        // own, and a skipped patch must not be a silent feature loss.
+        expect.any(Function),
       );
-
-      // Master gate (default toolStyle is Minimal): both overrides registered
-      expect(registerBashToolOverride).toHaveBeenCalled();
-      expect(registerCodemodeToolOverride).toHaveBeenCalled();
+      const patchNotify = vi.mocked(patchThinkingRenderer).mock.calls[0]![2] as (m: string) => void;
+      patchNotify("patch skipped");
+      expect(ui.notify).toHaveBeenCalledWith("patch skipped", "warning");
+
+      // Master gate (default toolStyle is Minimal): both rows are ours.
+      expect(resolve(renderers[0], "bash").result).toMatchObject({ renderCall: renderBashCall });
+      expect(resolve(renderers[0], "codemode").result).toMatchObject({
+        renderCall: renderCodemodeCall,
+      });
     });
 
-    it("skips the tool overrides entirely when toolStyle is Native", () => {
+    it("yields pi's native rows for every tool when toolStyle is Native", () => {
       vi.mocked(loadUIConfig).mockReturnValue({
         ...DEFAULT_UI_CONFIG,
         toolStyle: "Native",
       });
 
-      const { triggerStart } = setupHarness();
+      const { renderers, triggerStart } = setupHarness();
       const { ctx, ui } = makeCtx(true);
 
       triggerStart(ctx);
 
-      // Native = no archimedes tool styling: neither override is registered
-      // (pi's native rendering stands, no built-in-takeover notice).
-      expect(registerBashToolOverride).not.toHaveBeenCalled();
-      expect(registerCodemodeToolOverride).not.toHaveBeenCalled();
+      // Native = no archimedes tool styling: both rows go back through
+      // `next()`, so pi's own rendering stands and nothing is taken over.
+      expect(resolve(renderers[0], "bash")).toEqual({ result: NATIVE, nextCalls: 1 });
+      expect(resolve(renderers[0], "codemode")).toEqual({ result: NATIVE, nextCalls: 1 });
       // The rest of the UI still comes up.
       expect(ui.setHeader).toHaveBeenCalledTimes(1);
     });
 
-    it("respects editorSpinBorder: false by leaving workingVisible=true and not installing editor component", () => {
+    it("respects editorSpinBorder: false by leaving pi's indicator running and installing no editor component", () => {
       vi.mocked(loadUIConfig).mockReturnValue({
         ...DEFAULT_UI_CONFIG,
         editorSpinBorder: false,
@@ -261,22 +428,144 @@ describe("packages/ui lifecycle and registration", () => {
 
       triggerStart(ctx);
 
+      // No border spinner, so pi's own working row comes back, looking exactly
+      // like pi's default: visible, with its own animated indicator (omitting the
+      // argument is how pi restores the default frames).
       expect(ui.setWorkingVisible).toHaveBeenCalledWith(true);
+      expect(ui.setWorkingIndicator).toHaveBeenCalledWith(undefined);
       expect(ui.setEditorComponent).not.toHaveBeenCalled();
     });
 
-    it("skips bashToolOverride when bashToolStyling is false", () => {
+    it("puts the configured thinking label on hidden blocks through pi", () => {
       vi.mocked(loadUIConfig).mockReturnValue({
         ...DEFAULT_UI_CONFIG,
-        bashToolStyling: false,
+        labelText: "Pondering...",
       });
 
       const { triggerStart } = setupHarness();
+      const { ctx, ui } = makeCtx(true);
+
+      triggerStart(ctx);
+
+      // The hidden row is pi's own (`AssistantMessageComponent` reads the label
+      // pi was given), so the setting is handed to pi rather than rebuilt here.
+      expect(ui.setHiddenThinkingLabel).toHaveBeenCalledWith("Pondering...");
+    });
+
+    it("hands the hidden-thinking label back to pi when the setting is empty", () => {
+      vi.mocked(loadUIConfig).mockReturnValue({
+        ...DEFAULT_UI_CONFIG,
+        labelText: "   ",
+      });
+
+      const { triggerStart } = setupHarness();
+      const { ctx, ui } = makeCtx(true);
+
+      triggerStart(ctx);
+
+      expect(ui.setHiddenThinkingLabel).toHaveBeenCalledWith(undefined);
+    });
+
+    it("gives the working row and the thinking label back to pi on shutdown", () => {
+      const { triggerStart, triggerShutdown } = setupHarness();
+      const { ctx, ui } = makeCtx(true);
+
+      triggerStart(ctx);
+      triggerShutdown(ctx);
+
+      expect(ui.setWorkingIndicator).toHaveBeenLastCalledWith(undefined);
+      expect(ui.setHiddenThinkingLabel).toHaveBeenLastCalledWith(undefined);
+      expect(ui.setWorkingVisible).toHaveBeenLastCalledWith(true);
+    });
+
+    // The working row is pi's "Working" line above the editor; our border spinner
+    // lives in the editor's own top border and its default label is "Working" as
+    // well. With both on screen the word appeared twice, which is what the
+    // maintainer's screenshot shows. The setting that decides is
+    // `editorSpinBorder`, and the row is handed back and taken through pi's own
+    // `setWorkingVisible()` — `types.d.ts:88`.
+    describe("pi's working row and the border spinner", () => {
+      it("hides pi's working row while the border spinner carries the announcement", () => {
+        vi.mocked(loadUIConfig).mockReturnValue({ ...DEFAULT_UI_CONFIG, editorSpinBorder: true });
+        const { triggerStart } = setupHarness();
+        const { ctx, ui } = makeCtx(true);
+
+        triggerStart(ctx);
+
+        expect(ui.setWorkingVisible).toHaveBeenLastCalledWith(false);
+        // No indicator configuration is needed once the row is hidden — and
+        // nothing here asks pi for `frames: []` any more, so the row that *is*
+        // shown (spinner off) is pi's default down to its spinner.
+        expect(ui.setWorkingIndicator).toHaveBeenCalledWith(undefined);
+        expect(ui.setWorkingIndicator).not.toHaveBeenCalledWith({ frames: [] });
+      });
+
+      it("shows pi's working row, with pi's own indicator, when the spinner is off", () => {
+        vi.mocked(loadUIConfig).mockReturnValue({ ...DEFAULT_UI_CONFIG, editorSpinBorder: false });
+        const { triggerStart } = setupHarness();
+        const { ctx, ui } = makeCtx(true);
+
+        triggerStart(ctx);
+
+        expect(ui.setWorkingVisible).toHaveBeenLastCalledWith(true);
+        expect(ui.setWorkingIndicator).toHaveBeenCalledWith(undefined);
+      });
+
+      it("re-reads the setting for every session, so a replaced session gets the row back", () => {
+        // pi resets the extension UI on session replacement (`resetExtensionUI()`,
+        // interactive-mode.js:1921 sets `workingVisible = true` again), and the
+        // setting can change between sessions, so the answer has to be read from
+        // the config each time rather than remembered from the first install.
+        vi.mocked(loadUIConfig).mockReturnValue({ ...DEFAULT_UI_CONFIG, editorSpinBorder: true });
+        const { triggerStart } = setupHarness();
+        const spinnerOn = makeCtx(true);
+        triggerStart(spinnerOn.ctx);
+
+        vi.mocked(loadUIConfig).mockReturnValue({ ...DEFAULT_UI_CONFIG, editorSpinBorder: false });
+        const spinnerOff = makeCtx(true);
+        triggerStart(spinnerOff.ctx);
+
+        // Two sessions, two answers: the row went away and came back.
+        const calls = spinnerOn.ui.setWorkingVisible.mock.calls.map((c) => c[0]);
+        expect(calls).toEqual([false]);
+        expect(spinnerOff.ui.setWorkingVisible.mock.calls.map((c) => c[0])).toEqual([true]);
+      });
+
+      it("hides the row for a session installed on a second pi handle", () => {
+        // pi caches an extension's factory and only clears that cache on some
+        // reloads: `/new`, `/fork` and `/resume` build a fresh loader and run the
+        // same module instance against a NEW handle. Nothing the first handle did
+        // may suppress the second one's answer (#106 learned this the hard way).
+        vi.mocked(loadUIConfig).mockReturnValue({ ...DEFAULT_UI_CONFIG, editorSpinBorder: true });
+        const first = setupHarness();
+        const firstCtx = makeCtx(true);
+        first.triggerStart(firstCtx.ctx);
+
+        const second = setupHarness();
+        const secondCtx = makeCtx(true);
+        second.triggerStart(secondCtx.ctx);
+
+        expect(firstCtx.ui.setWorkingVisible).toHaveBeenLastCalledWith(false);
+        expect(secondCtx.ui.setWorkingVisible).toHaveBeenLastCalledWith(false);
+      });
+    });
+
+    it("registers no bash tool and yields pi's native row when bashToolStyling is false", () => {
+      vi.mocked(loadUIConfig).mockReturnValue({
+        ...DEFAULT_UI_CONFIG,
+        bashToolStyling: false,
+      });
+
+      const { pi, renderers, triggerStart } = setupHarness();
       const { ctx } = makeCtx(true);
 
       triggerStart(ctx);
 
-      expect(registerBashToolOverride).not.toHaveBeenCalled();
+      // The take-over is gone: nothing re-registers `bash`, and the resolver
+      // hands the row back through `next()` — the first time this setting can
+      // genuinely give back pi's own rendering.
+      expect(pi.registerTool).not.toHaveBeenCalled();
+      expect(resolve(renderers[0], "bash")).toEqual({ result: NATIVE, nextCalls: 1 });
     });
 
     it("skips the codemode tool override when codemodeToolStyling is false", () => {
@@ -285,12 +574,15 @@ describe("packages/ui lifecycle and registration", () => {
         codemodeToolStyling: false,
       });
 
-      const { triggerStart } = setupHarness();
+      const { pi, renderers, triggerStart } = setupHarness();
       const { ctx } = makeCtx(true);
 
       triggerStart(ctx);
 
-      expect(registerCodemodeToolOverride).not.toHaveBeenCalled();
+      // Nothing re-registers `codemode`, so pi's built-in extension stays
+      // loaded; the resolver hands the row to pi's own renderer.
+      expect(pi.registerTool).not.toHaveBeenCalled();
+      expect(resolve(renderers[0], "codemode")).toEqual({ result: NATIVE, nextCalls: 1 });
     });
 
     it("does not accumulate message_end listeners on repeated session_start (simulating /reload)", () => {
@@ -330,73 +622,186 @@ describe("packages/ui lifecycle and registration", () => {
   });
 
   describe("session_start in non-interactive mode (hasUI: false)", () => {
-    it("still registers bashToolOverride but skips UI setup", () => {
-      const { triggerStart } = setupHarness();
+    it("registers no tool and skips UI setup", () => {
+      const { pi, triggerStart } = setupHarness();
       const { ctx, ui } = makeCtx(false);
 
       triggerStart(ctx);
 
-      expect(registerBashToolOverride).toHaveBeenCalledWith(expect.anything(), "/workspace/test-project");
+      expect(pi.registerTool).not.toHaveBeenCalled();
       expect(ui.setHeader).not.toHaveBeenCalled();
       expect(ui.setEditorComponent).not.toHaveBeenCalled();
       expect(patchThinkingRenderer).not.toHaveBeenCalled();
     });
   });
 
+  describe("startup header: the splash is opt-in (default off)", () => {
+    // `startup-splash-gate.test.ts` drives the real animation module; this uses
+    // the stubbed one so the claim "nothing of the splash runs" is the absence
+    // of calls into it, which is the direct form of "no logo work":
+    // `renderHeader` is what asks `logo.ts` for a frame, and the two listing
+    // calls are what arm the animation.
+    it("hands the header to pi and touches no part of the splash module", () => {
+      // The default config, unmodified: this is what a settings file with no
+      // `startupSplash` key resolves to.
+      vi.mocked(loadUIConfig).mockReturnValue({ ...DEFAULT_UI_CONFIG });
+      const { triggerStart, triggerShutdown } = setupHarness({});
+      const { ctx, ui } = makeCtx(true);
+
+      triggerStart(ctx);
+
+      expect(ui.setHeader).toHaveBeenCalledTimes(1);
+      expect(ui.setHeader).toHaveBeenCalledWith(undefined);
+      expect(renderHeader).not.toHaveBeenCalled();
+      expect(patchStartupListing).not.toHaveBeenCalled();
+      expect(revealStartupListing).not.toHaveBeenCalled();
+
+      // Teardown still runs its one unconditional stop — cheap and idempotent —
+      // while the ref freeze is guarded on there being a ref, so an off session
+      // cannot resurrect an animation that was never built.
+      triggerShutdown(ctx);
+      expect(stopStartupListing).toHaveBeenCalledTimes(1);
+      expect(renderHeader).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("startup header: quietStartup and ctx.scopedModels", () => {
+    // pi 1.x owns the startup screen: `quietStartup` (`false` / `"header"` /
+    // `true`) decides what is shown, and `ctx.scopedModels` is the session's
+    // model scope — the same set `/scoped-models` lists. Both are read, neither
+    // is scraped any more.
+    const scopedModels = [
+      { model: { id: "claude-sonnet-4-5" } },
+      { model: { id: "gpt-5" }, thinkingLevel: "high" },
+    ];
+    let fetchSpy: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      fetchSpy = vi.fn(async () => ({ ok: true, json: async () => ({}) }) as never);
+      vi.stubGlobal("fetch", fetchSpy);
+    });
+
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    /** Register, start a session and invoke the header factory pi was given. */
+    function startHeader(settings: Record<string, unknown>, models: unknown[] = scopedModels) {
+      const { triggerStart } = setupHarness(settings);
+      const { ctx, ui } = makeCtx(true);
+      (ctx as unknown as { scopedModels: unknown[] }).scopedModels = models;
+
+      triggerStart(ctx);
+      const headerFactory = ui.setHeader.mock.calls[0]![0];
+      const tui = { terminal: { rows: 24 }, requestRender: vi.fn() } as unknown as TUI;
+      headerFactory(tui, {} as Theme);
+      return { ui, tui };
+    }
+
+    it("reveals the model scope from ctx.scopedModels with console.log untouched", () => {
+      const { tui } = startHeader({});
+
+      expect(revealStartupListing).toHaveBeenCalledTimes(1);
+      expect(revealStartupListing).toHaveBeenCalledWith(tui, expect.any(Object), [
+        { name: "Models", items: ["claude-sonnet-4-5", "gpt-5:high"] },
+      ]);
+      expect(console.log.name).toBe("log");
+    });
+
+    it('quietStartup: "header" keeps the splash and drops the model scope', () => {
+      startHeader({ quietStartup: "header" });
+
+      // The header is ours (the splash stays), but the details half is not.
+      expect(revealStartupListing).toHaveBeenCalledTimes(1);
+      expect(revealStartupListing).toHaveBeenCalledWith(expect.anything(), expect.any(Object), []);
+    });
+
+    it("quietStartup: true hands the header back to pi and starts no splash", () => {
+      const { triggerStart } = setupHarness({ quietStartup: true });
+      const { ctx, ui } = makeCtx(true);
+
+      triggerStart(ctx);
+
+      // pi replaces its own header with an empty component for a quiet start;
+      // restoring ours is what leaves that silence in place.
+      expect(ui.setHeader).toHaveBeenCalledWith(undefined);
+      expect(patchStartupListing).not.toHaveBeenCalled();
+      expect(revealStartupListing).not.toHaveBeenCalled();
+    });
+
+    it("reveals nothing but the version block when the session has no model scope", () => {
+      startHeader({}, []);
+
+      expect(revealStartupListing).toHaveBeenCalledWith(expect.anything(), expect.any(Object), []);
+    });
+
+    it("asks the network nothing at startup", () => {
+      startHeader({});
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+  });
+
   describe("session_shutdown teardown", () => {
-    it("restores unpatchConsoleLog, workingVisible, and clears editor component", () => {
+    it("stops the splash, restores workingVisible, and clears editor component", () => {
       const { triggerStart, triggerShutdown } = setupHarness();
       const { ctx, ui } = makeCtx(true);
 
       triggerStart(ctx);
 
-      // Verify startup
-      expect(ui.setWorkingVisible).toHaveBeenCalledWith(false);
+      // Verify startup: with the border spinner on, pi's working row was hidden.
+      expect(ui.setWorkingVisible).toHaveBeenLastCalledWith(false);
 
       // Now trigger shutdown
       triggerShutdown(ctx);
 
-      expect(unpatchConsoleLog).toHaveBeenCalledTimes(1);
-      expect(clearActiveBashIntervals).toHaveBeenCalledTimes(1);
-      expect(clearActiveCodemodeIntervals).toHaveBeenCalledTimes(1);
+      expect(stopStartupListing).toHaveBeenCalledTimes(1);
       expect(ui.setWorkingVisible).toHaveBeenLastCalledWith(true);
       expect(ui.setEditorComponent).toHaveBeenLastCalledWith(undefined);
     });
 
-    it("cleans up patched TUI container children on shutdown", () => {
+    it("stops the splash when pi disposes the header (header replaced, session restart)", () => {
       const { triggerStart, triggerShutdown } = setupHarness();
       const { ctx, ui } = makeCtx(true);
 
       triggerStart(ctx);
-
       const headerFactory = ui.setHeader.mock.calls[0]![0];
-      const PATCHED_LISTING = Symbol.for("splashscreen:listingPatched");
-      const ORIG_ADD_CHILD = Symbol.for("splashscreen:origAddChild");
-      const ANIM_INTERVAL = Symbol.for("splashscreen:animInterval");
-      const DEBOUNCE_TIMER = Symbol.for("splashscreen:debounceTimer");
-
-      const origAddChildFn = vi.fn();
-      const patchedChild = {
-        [PATCHED_LISTING]: true,
-        [ORIG_ADD_CHILD]: origAddChildFn,
-        [ANIM_INTERVAL]: setInterval(() => {}, 10000),
-        [DEBOUNCE_TIMER]: setTimeout(() => {}, 10000),
-        addChild: vi.fn(),
-      };
-
-      const fakeTui = {
-        terminal: { rows: 24 },
-        children: [patchedChild],
-      } as unknown as TUI;
+      const comp = headerFactory({ terminal: { rows: 24 } } as TUI, {} as Theme);
 
-      headerFactory(fakeTui, {} as Theme);
+      expect(typeof comp.dispose).toBe("function");
+      comp.dispose!();
+      expect(stopStartupListing).toHaveBeenCalledTimes(1);
 
-      // Now trigger shutdown
       triggerShutdown(ctx);
+    });
+  });
+
+  // The header component's own contract with pi, independent of lifecycle: pi
+  // tells a component to drop cached rendering state by calling
+  // `invalidate()` — `onThemeChange()` does it for the whole tree
+  // (`interactive-mode.js:792`), as does the theme file watcher — and the
+  // splash caches its finished lines, which carry the theme's colours.
+  describe("header component contract", () => {
+    it("drops the cached header lines when pi invalidates it (theme change)", () => {
+      const { triggerStart } = setupHarness();
+      const { ctx, ui } = makeCtx(true);
+
+      triggerStart(ctx);
+      const headerFactory = ui.setHeader.mock.calls[0]![0];
+      const comp = headerFactory({ terminal: { rows: 24 } } as TUI, {} as Theme);
+
+      comp.render(80);
+      const ref = vi.mocked(renderHeader).mock.calls.at(-1)![1] as {
+        settled: boolean;
+        cachedLines?: string[];
+      };
+      // The state a finished splash leaves behind (the mocked `renderHeader`
+      // does not fill it in, so the test does what the real one would).
+      ref.settled = true;
+      ref.cachedLines = ["\x1b[90mv1.2.0\x1b[0m"];
+
+      comp.invalidate();
 
-      expect(patchedChild.addChild).toBe(origAddChildFn);
-      expect(patchedChild[PATCHED_LISTING]).toBe(false);
-      expect(patchedChild[ORIG_ADD_CHILD]).toBeUndefined();
+      expect(ref.cachedLines).toBeUndefined();
     });
   });
 });