@pi-archimedes/ui 2.13.0 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/ui",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Terminal UI enhancements, styled bash tool rendering, and visual presentation components for Pi",
   "type": "module",
   "main": "./src/index.ts",
@@ -28,7 +28,7 @@
     "./config": "./src/config.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.13.0"
+    "@pi-archimedes/core": "2.14.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.4.0",

package/src/index.test.ts

@@ -706,11 +706,14 @@ describe("packages/ui lifecycle and registration", () => {
       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.
+      // Teardown runs NO stop at all: `stopStartupListing()` stops the module
+      // pair of timers in `startup/index.ts`, and a session that never installed
+      // a header never armed them — so it has no claim on them (#156: that
+      // unguarded call is how a subagent child's shutdown froze the live main
+      // session's splash). The ref freeze stays 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(stopStartupListing).not.toHaveBeenCalled();
       expect(renderHeader).not.toHaveBeenCalled();
     });
   });

package/src/index.ts

@@ -56,29 +56,19 @@ export {
   type ToolStyle,
 } from "./config.js";
 
-// Module-level state for session lifecycle
-let uiRef: ListingRef | undefined;
-let uiCtx: ExtensionContext | undefined;
-
-let spinFlag = false;
-let spinInterval: ReturnType<typeof setInterval> | undefined;
-
-/**
- * Which Archimedes tool rows the current session asks for, refreshed at every
- * `session_start` and read by the renderer resolver. The resolver itself is
- * registered once per extension load — pi keeps a list of resolvers per
- * extension, so registering it from `session_start` would stack a duplicate on
- * every `/reload` — which means the settings have to be read here rather than
- * inside the resolver: `renderCall`/`renderResult` run on every frame.
- */
-let styledTools = { bash: false, codemode: false };
-
-function clearSpinInterval(): void {
-  if (spinInterval) {
-    clearInterval(spinInterval);
-    spinInterval = undefined;
-  }
-}
+// No module-scope session state (#156).
+//
+// pi caches an extension MODULE per process and re-invokes its factory with a
+// fresh `pi` per session, so anything kept at module scope is shared by every
+// session in the process — including a SUBORDINATE in-process session (a
+// subagent child, bound with no uiContext, so `ctx.hasUI` is false). When that
+// child is reaped its `session_shutdown` runs against this same module, and any
+// ref it could write or clear was the LIVE main session's: the border spinner's
+// interval cleared, `spinFlag` flipped off so the main session's own teardown
+// stopped handing pi's working row back, and the splash's timers stopped through
+// `stopStartupListing()`. Every one of those refs therefore lives in the
+// `registerUI` closure below — one set per registration — which is what makes
+// the child's teardown able to reach only the child's own state.
 
 /**
  * Draw the bash row through pi's renderer resolution (ADR 0029).
@@ -91,7 +81,10 @@ function clearSpinInterval(): void {
  * `createBashToolDefinition()` with our renderers bolted on — which also means
  * anything pi later adds to that tool cannot be silently dropped by us.
  */
-function registerToolRenderers(pi: ExtensionAPI): void {
+function registerToolRenderers(
+  pi: ExtensionAPI,
+  styled: () => { bash: boolean; codemode: boolean },
+): void {
   // Capability check, not a version wish: on a host without the API there is
   // nothing to resolve through, and pi's own rows stand in.
   if (typeof pi.registerToolRenderer !== "function") return;
@@ -100,10 +93,18 @@ function registerToolRenderers(pi: ExtensionAPI): void {
     // `next()` is spread first so that whatever the built-in definition
     // declares besides the two renderers — `renderShell` is the one that matters
     // today — survives resolution instead of being silently dropped by us.
+    //
+    // `styled()` is read HERE rather than captured at registration: the resolver
+    // is registered once per `registerUI` (pi keeps a list per extension, so
+    // registering it from `session_start` would stack a duplicate on every
+    // `/reload`), while the settings are deliberately re-read every
+    // `session_start` so a change made between sessions takes effect. A getter,
+    // not a value, is what keeps those two lifetimes compatible.
+    const styledNow = styled();
     const ours =
-      toolName === "bash" && styledTools.bash
+      toolName === "bash" && styledNow.bash
         ? { renderCall: renderBashCall, renderResult: renderBashResult }
-        : toolName === "codemode" && styledTools.codemode
+        : toolName === "codemode" && styledNow.codemode
           ? { renderCall: renderCodemodeCall, renderResult: renderCodemodeResult }
           : undefined;
     return ours ? { ...next(), ...ours } : next();
@@ -119,8 +120,51 @@ export function registerUI(pi: ExtensionAPI): void {
   // would make /plugins report an enabled package that did nothing.
   reportPiSupport("ui", "1.2.0");
 
+  // ── This registration's session state (#156) ────────────────────────────────
+  //
+  // Everything a single session owns, held per `registerUI` call rather than at
+  // module scope — see the note above `registerToolRenderers`.
+
+  /** The splash ref this session installed (`undefined` = no splash on screen). */
+  let uiRef: ListingRef | undefined;
+  /** The ctx of the last `session_start` THIS registration handled. */
+  let uiCtx: ExtensionContext | undefined;
+  /** Whether this session hid pi's working row for the border spinner. */
+  let spinFlag = false;
+  /** The border spinner's interval, handed over by `HephaestusEditor`. */
+  let spinInterval: ReturnType<typeof setInterval> | undefined;
+  /**
+   * Which Archimedes tool rows this session asks for, refreshed at every
+   * `session_start` and read by the renderer resolver through the getter below
+   * (ADR 0029).
+   */
+  let styledTools = { bash: false, codemode: false };
+  /**
+   * Whether THIS registration put the splash in pi's header slot and has not
+   * handed it back — the ownership flag that scopes `stopStartupListing()`.
+   *
+   * `stopStartupListing()` stops the frame/reveal timers in
+   * `./startup/index.js`, and those two stay module-scope there on purpose (see
+   * the note in that file: one splash is on screen at a time, and pi disposes
+   * the header it is replacing before it builds the next, so a module pair of
+   * timers cannot leak a second animation). What must not be module-scope is the
+   * *decision to ask that pair to stop*: on a shutdown that does not own the
+   * splash — a subagent child reaped while the main session's logo is still
+   * animating — calling it freezes the parent's animation mid-reveal. So the
+   * call is gated on having installed the header ourselves, which is also why
+   * `startup/index.ts` needed no change at all.
+   */
+  let weInstalledTheSplash = false;
+
+  function clearSpinInterval(): void {
+    if (spinInterval) {
+      clearInterval(spinInterval);
+      spinInterval = undefined;
+    }
+  }
+
   // Registered once per extension load, before any session exists (ADR 0029).
-  registerToolRenderers(pi);
+  registerToolRenderers(pi, () => styledTools);
 
   // One-time migration of any legacy core config to UI config
   migrateCoreToUIConfig();
@@ -137,6 +181,11 @@ export function registerUI(pi: ExtensionAPI): void {
 
   // session_shutdown handler (top-level to prevent accumulation on /reload)
   pi.on("session_shutdown", (_event, ctx) => {
+    // `uiCtx` is the closure ref of THIS registration, so the fallback can only
+    // ever find the ctx this instance last saw — a foreign session's shutdown
+    // cannot reach another instance's ctx through it (#156). The shape is kept
+    // rather than reduced to `ctx`: pi hands a ctx built off its own runner, and
+    // asserting its defaults verbatim is exactly what ADR 0031 refuses to do.
     const targetCtx = ctx?.hasUI ? ctx : uiCtx;
     if (targetCtx?.hasUI) {
       // Give back what this session took: the row we hid for the border spinner,
@@ -155,10 +204,17 @@ export function registerUI(pi: ExtensionAPI): void {
     spinFlag = false;
 
     // The splash: stop the frame/reveal timers, then freeze the ref so a late
-    // render of a header still on screen cannot restart the animation. Nothing
-    // else to undo — the startup listing interception and the console.log patch
-    // this used to un-install are gone (pi 1.x alignment, Task 8).
-    stopStartupListing();
+    // render of a header still on screen cannot restart the animation. Only if
+    // THIS session installed the header and has not handed it back — the timers
+    // `stopStartupListing()` stops are module state in `startup/index.ts`, so an
+    // unguarded call here let a subagent child's shutdown freeze the live main
+    // session's logo mid-reveal (#156). Nothing else to undo — the startup
+    // listing interception and the console.log patch this used to un-install are
+    // gone (pi 1.x alignment, Task 8).
+    if (weInstalledTheSplash) {
+      stopStartupListing();
+      weInstalledTheSplash = false;
+    }
     if (uiRef) {
       uiRef.settled = true;
     }
@@ -234,6 +290,9 @@ export function registerUI(pi: ExtensionAPI): void {
       if (!startupSplash) {
         ctx.ui.setHeader(undefined);
         uiRef = undefined;
+        // The slot is pi's again (or was never ours) — this session owns no
+        // splash, so its teardown must not stop the animation module's timers.
+        weInstalledTheSplash = false;
       } else if (quietStartup === true) {
         // pi's own header is an empty component in this mode. Handing ours back
         // is what keeps that silence: a splash left installed from an earlier
@@ -241,6 +300,7 @@ export function registerUI(pi: ExtensionAPI): void {
         // otherwise animate over it.
         ctx.ui.setHeader(undefined);
         uiRef = undefined;
+        weInstalledTheSplash = false;
       } else {
         // What the splash reveals after the logo. The version row belongs to
         // the header itself; the model scope is a startup *detail*, so it
@@ -293,6 +353,10 @@ export function registerUI(pi: ExtensionAPI): void {
             // component, whose timers then run until they settle themselves.
             dispose(): void {
               stopStartupListing();
+              // We no longer own the animation: pi is replacing (or removing)
+              // the header, so the timers are already stopped and a later
+              // `session_shutdown` has nothing left to stop here.
+              weInstalledTheSplash = false;
             },
           };
           patchStartupListing(tui, ref);
@@ -300,6 +364,10 @@ export function registerUI(pi: ExtensionAPI): void {
           return comp;
         };
         ctx.ui.setHeader(headerFactory);
+        // From here on this registration owns the splash: it is the one that put
+        // the animation in pi's header slot, so it is the only one allowed to
+        // stop it on the way out (`session_shutdown`, or `dispose()` above).
+        weInstalledTheSplash = true;
       }
 
       clearSpinInterval();

package/src/session-isolation.test.ts

@@ -0,0 +1,317 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { Mock } from "vitest";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  KeybindingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { TUI, EditorTheme } from "@earendil-works/pi-tui";
+
+// ── One module instance, two sessions (#156) ────────────────────────────────
+//
+// pi caches an extension MODULE per process and re-invokes its factory with a
+// fresh `pi` per session. Anything `registerUI` keeps at module scope is
+// therefore shared by every session in the process, and a SUBORDINATE in-process
+// session — a subagent child, bound with no uiContext, so `hasUI` is false —
+// tears the LIVE main session's state down when it is reaped: its
+// `session_shutdown` clears the spinner interval the main session's border
+// spinner is running on, stops the main session's splash animation, and can hand
+// back the main session's editor row through a ref the child overwrote.
+//
+// The three cases below drive TWO registrations against ONE module instance and
+// fake the clock, because the damage is a timer that stops: `index.test.ts` runs
+// on real timers and so cannot see the spinner handle at all — which is exactly
+// why the leak survived it. `startup-splash-gate.test.ts` uses fake timers but
+// stubs nothing in `./startup/index.js`, and neither does this file: "the timer
+// is still armed" is only evidence when the real animation module armed it.
+
+vi.mock("@pi-archimedes/core/settings-io", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@pi-archimedes/core/settings-io")>();
+  return {
+    ...actual,
+    loadConfig: vi.fn(),
+    saveConfig: vi.fn(),
+    removeConfig: vi.fn(),
+  };
+});
+
+vi.mock("./config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./config.js")>();
+  return { ...actual, loadUIConfig: vi.fn() };
+});
+
+// Not under test here, and both touch state outside this module (pi's thinking
+// renderer prototype, message content).
+vi.mock("./thinking/patch.js", () => ({ patchThinkingRenderer: vi.fn() }));
+vi.mock("./thinking/transform.js", () => ({ transformThinkingContent: vi.fn() }));
+vi.mock("./migration.js", () => ({
+  migrateCoreToUIConfig: vi.fn(),
+  migrateCompactThinkingToStyle: vi.fn(),
+  migrateRemovedToolPatch: vi.fn(),
+  UI_CONFIG_KEYS: [],
+}));
+
+import { registerUI } from "./index.js";
+import { loadUIConfig, DEFAULT_UI_CONFIG, type UIConfig } from "./config.js";
+import { stopStartupListing } from "./startup/index.js";
+
+// ── Harness ─────────────────────────────────────────────────────────────────
+
+/** What a session's `ui` surface must offer; everything else answers a no-op. */
+interface UiSpies {
+  setHeader: Mock;
+  setEditorComponent: Mock;
+  setWorkingVisible: Mock;
+  setHiddenThinkingLabel: Mock;
+  notify: Mock;
+  onTerminalInput: Mock;
+}
+
+interface Session {
+  /** The per-session `pi` handle pi builds for a runner. */
+  pi: ExtensionAPI;
+  /** The ctx pi hands that runner's handlers. */
+  ctx: ExtensionContext;
+  ui: UiSpies;
+  start: (uiConfig?: Partial<UIConfig>) => void;
+  /**
+   * Fire `session_shutdown`. `withCtx` replaces the ctx pi hands the handler —
+   * pass a UI-less one to model a shutdown that arrives after the UI context is
+   * gone, which is the case the `uiCtx` fallback exists for.
+   */
+  shutdown: (withCtx?: unknown) => void;
+}
+
+/**
+ * One registration + one session, driven the way pi drives it: `registerUI(pi)`
+ * with a fresh `pi`, then `session_start` / `session_shutdown` with that
+ * session's own ctx (`emit()` builds a ctx off the runner and passes it, so the
+ * ctx a handler sees belongs to the session that emitted the event).
+ */
+function makeSession(hasUI: boolean): Session {
+  const listeners: Record<string, ((event: any, ctx: any) => void)[]> = {};
+  const pi = {
+    on: vi.fn((event: string, handler: (event: any, ctx: any) => void) => {
+      (listeners[event] ??= []).push(handler);
+    }),
+    registerTool: vi.fn(),
+    registerToolRenderer: vi.fn(),
+    // `quietStartup` is what the splash gate reads out of this; `{}` is pi's
+    // default (`false` = header and details shown).
+    getSettings: vi.fn(() => ({})),
+  } as unknown as ExtensionAPI;
+
+  const ui: UiSpies = {
+    setHeader: vi.fn(),
+    setEditorComponent: vi.fn(),
+    setWorkingVisible: vi.fn(),
+    setHiddenThinkingLabel: vi.fn(),
+    notify: vi.fn(),
+    onTerminalInput: vi.fn(() => () => {}),
+  };
+  // The `ui` object pi hands a context is a fixed surface; anything this suite
+  // has not spelled out answers an inert spy rather than throwing.
+  const uiSurface = new Proxy(ui as unknown as Record<string, unknown>, {
+    get(target, prop) {
+      if (prop === "theme") return theme;
+      if (prop in target) return target[prop as string];
+      return vi.fn();
+    },
+    has: () => true,
+  });
+
+  const ctx = {
+    hasUI,
+    mode: hasUI ? "tui" : "print",
+    cwd: "/workspace/test-project",
+    ui: uiSurface,
+    isIdle: vi.fn(() => true),
+    shutdown: vi.fn(),
+    scopedModels: [],
+  } as unknown as ExtensionContext;
+
+  const fire = (
+    event: string,
+    config?: Partial<UIConfig>,
+    eventCtx: unknown = ctx,
+  ): void => {
+    if (event === "session_start") {
+      vi.mocked(loadUIConfig).mockReturnValue({
+        ...DEFAULT_UI_CONFIG,
+        ...config,
+      } as UIConfig);
+    }
+    for (const handler of listeners[event] ?? []) {
+      handler({ type: event, reason: "quit" }, eventCtx);
+    }
+  };
+
+  return {
+    pi,
+    ctx,
+    ui,
+    start: (config) => fire("session_start", config),
+    shutdown: (eventCtx) => fire("session_shutdown", undefined, eventCtx),
+  };
+}
+
+const theme = {
+  fg: (_token: string, text: string) => text,
+  bg: (_token: string, text: string) => text,
+  bold: (text: string) => text,
+  getBgAnsi: () => "",
+} as unknown as Theme;
+
+/** A renderer the editor and the splash can both be handed. */
+function makeTui(): TUI & { requestRender: Mock } {
+  return {
+    terminal: { rows: 24, cols: 80 },
+    requestRender: vi.fn(),
+    add: vi.fn(),
+    remove: vi.fn(),
+    start: vi.fn(),
+    stop: vi.fn(),
+  } as unknown as TUI & { requestRender: Mock };
+}
+
+/** Build the editor pi was handed, so the border spinner's interval is armed. */
+function buildEditor(session: Session, tui: TUI): { dispose(): void } {
+  const factory = session.ui.setEditorComponent.mock.calls[0]![0] as (
+    tui: TUI,
+    editorTheme: EditorTheme,
+    keybindings: KeybindingsManager,
+  ) => { dispose(): void };
+  return factory(tui, { borderColor: (s: string) => s } as unknown as EditorTheme, {} as KeybindingsManager);
+}
+
+/** Build the header pi was handed, i.e. put the splash where pi puts it. */
+function buildHeader(session: Session, tui: TUI): { dispose(): void } {
+  const factory = session.ui.setHeader.mock.calls.at(-1)![0] as (
+    tui: TUI,
+    theme: Theme,
+  ) => { dispose(): void };
+  return factory(tui, theme);
+}
+
+describe("session isolation: one module instance, several sessions (#156)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    // The splash's timers are module state in `startup/index.ts`; a test that
+    // leaves one armed would leak it into the next file's timer counts.
+    stopStartupListing();
+    vi.useRealTimers();
+  });
+
+  it("a foreign session's shutdown does not stop the main session's border spinner", () => {
+    // The main session: interactive, spinner on, no splash (so the ONLY timer in
+    // the process is the border spinner's).
+    const main = makeSession(true);
+    registerUI(main.pi);
+    main.start({ startupSplash: false, editorSpinBorder: true });
+
+    const tui = makeTui();
+    buildEditor(main, tui);
+    const armed = vi.getTimerCount();
+    expect(armed, "the harness armed no timer — the editor factory was never invoked").toBeGreaterThan(0);
+
+    // A subagent child in the SAME process: registered through the same module,
+    // bound with no uiContext (`hasUI: false`), and now reaped by its parent.
+    const child = makeSession(false);
+    registerUI(child.pi);
+    child.start();
+    child.shutdown();
+
+    // The child's teardown killed nothing of the main session's.
+    expect(vi.getTimerCount()).toBe(armed);
+
+    // The control: the same shutdown on the session that OWNS the spinner does
+    // clear it, so the assertion above is not passing because nothing was ever
+    // armed or because the handler never runs.
+    main.shutdown();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("a UI-less session_start does not replace the main session's ctx", () => {
+    // Main: interactive, spinner on. It hid pi's working row and installed our
+    // editor — both of which its own teardown has to hand back.
+    const main = makeSession(true);
+    registerUI(main.pi);
+    main.start({ startupSplash: false, editorSpinBorder: true });
+    buildEditor(main, makeTui());
+    expect(main.ui.setWorkingVisible).toHaveBeenLastCalledWith(false);
+
+    // The UI-less session starts (the subagent child's `session_start`), and is
+    // then reaped. Its `session_start` is the assignment that, at module scope,
+    // moved the ref every later handler falls back to.
+    const child = makeSession(false);
+    registerUI(child.pi);
+    child.start();
+    child.shutdown();
+
+    // Nothing of the handback happened on the main ctx while the child was being
+    // reaped — the child never took any of it.
+    expect(main.ui.setEditorComponent).not.toHaveBeenCalledWith(undefined);
+    expect(main.ui.setWorkingVisible).not.toHaveBeenCalledWith(true);
+
+    // Now the main session's own shutdown: the handback reaches the main ctx,
+    // and it still happens — the spinner was on when the child tore itself down,
+    // which at module scope had flipped the shared "we hid the row" flag off.
+    main.shutdown();
+    expect(main.ui.setEditorComponent).toHaveBeenLastCalledWith(undefined);
+    expect(main.ui.setWorkingVisible).toHaveBeenLastCalledWith(true);
+
+    // The same teardown arriving with a UI-less ctx (pi hands the ctx built off
+    // its runner, so this is what a shutdown looks like once the UI context is
+    // gone): the handler falls back to the ref it kept, and that ref has to be
+    // THIS registration's main ctx. At module scope the child's `session_start`
+    // had overwritten it, so the handback went to the child instead.
+    const before = main.ui.setEditorComponent.mock.calls.length;
+    main.shutdown({ hasUI: false, ui: main.ui, isIdle: () => true });
+    expect(main.ui.setEditorComponent.mock.calls.length).toBe(before + 1);
+    expect(main.ui.setEditorComponent).toHaveBeenLastCalledWith(undefined);
+    // And it stayed off the child's ctx, which has nothing of ours to hand back.
+    expect(child.ui.setEditorComponent).not.toHaveBeenCalled();
+  });
+
+  it("the splash's dispose() path survives a foreign shutdown, and the splash outlives one", () => {
+    // Main with the splash on: pi's header slot holds our animated header, so
+    // the real animation module has its frame + reveal timers armed.
+    const main = makeSession(true);
+    registerUI(main.pi);
+    main.start({ startupSplash: true, editorSpinBorder: false });
+    const tui = makeTui();
+    const comp = buildHeader(main, tui);
+    const armed = vi.getTimerCount();
+    expect(armed, "the harness armed no splash timer — no header was built").toBeGreaterThan(0);
+
+    const child = makeSession(false);
+    registerUI(child.pi);
+    child.start();
+
+    // The child's shutdown must not stop an animation it never installed.
+    child.shutdown();
+    expect(vi.getTimerCount()).toBe(armed);
+
+    // pi replaces or removes the header → the component's `dispose()` runs, and
+    // that IS ours to act on: it stops the splash and records that we no longer
+    // own it.
+    expect(() => comp.dispose()).not.toThrow();
+    expect(vi.getTimerCount()).toBe(0);
+
+    // The plan's ordering, and the one no existing test combines: a foreign
+    // shutdown AFTER our own dispose() handed the animation back. Nothing to
+    // stop, nothing to throw.
+    expect(() => child.shutdown()).not.toThrow();
+    expect(vi.getTimerCount()).toBe(0);
+
+    // And the main session's own teardown, with the splash already disposed, is
+    // still safe.
+    expect(() => main.shutdown()).not.toThrow();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});