fix(terminal): resync side-panel refs after queued external writes

A pending tool switch stored an intermediate focused-tool map in the ref.
An urgent open on another tab then updated only state, and the identity
guard never copied that tab back, so a later click on the old tool was
ignored. Committed entries now catch up without dropping a write that is
still ahead of the last render.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

application/state/hiddenTabEviction.test.ts

@@ -0,0 +1,185 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { decideHiddenTabKeepCountAction } from "../../domain/terminalHibernate.ts";
+import { retainLeavingTabAfterEviction } from "./hiddenTabEviction.ts";
+import { terminalHiddenRendererStore } from "./terminalHiddenRendererStore.ts";
+
+test("a refused eviction tries the next candidate, then full-hibernates", async () => {
+  const attempts: string[] = [];
+  const outcomes: string[] = [];
+  await retainLeavingTabAfterEviction({
+    sessionId: "leaving",
+    candidates: ["images", "plain"],
+    keepCount: 2,
+    stillWantsRetention: () => true,
+    softHide: () => outcomes.push("soft-hide"),
+    fullHibernate: () => outcomes.push("full-hibernate"),
+    evict: async (sessionId) => {
+      attempts.push(sessionId);
+      return sessionId === "plain";
+    },
+  });
+  assert.deepEqual(attempts, ["images", "plain"]);
+  assert.deepEqual(outcomes, ["soft-hide"]);
+
+  const blocked: string[] = [];
+  const blockedOutcomes: string[] = [];
+  await retainLeavingTabAfterEviction({
+    sessionId: "leaving",
+    candidates: ["images", "also-images"],
+    keepCount: 2,
+    stillWantsRetention: () => true,
+    softHide: () => blockedOutcomes.push("soft-hide"),
+    fullHibernate: () => blockedOutcomes.push("full-hibernate"),
+    evict: async (sessionId) => {
+      blocked.push(sessionId);
+      return false;
+    },
+  });
+  assert.deepEqual(blocked, ["images", "also-images"]);
+  assert.deepEqual(blockedOutcomes, ["full-hibernate"]);
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 0);
+});
+
+test("hibernate failure after the soft-hidden marker drops does not retain the leaving tab", async () => {
+  const attempts: string[] = [];
+  const outcomes: string[] = [];
+  await retainLeavingTabAfterEviction({
+    sessionId: "leaving",
+    candidates: ["victim"],
+    keepCount: 2,
+    stillWantsRetention: () => true,
+    softHide: () => outcomes.push("soft-hide"),
+    fullHibernate: () => outcomes.push("full-hibernate"),
+    evict: async (sessionId) => {
+      attempts.push(sessionId);
+      await Promise.resolve();
+      return false;
+    },
+  });
+  assert.deepEqual(attempts, ["victim"]);
+  assert.deepEqual(outcomes, ["full-hibernate"]);
+
+  const recovered: string[] = [];
+  const recoveredOutcomes: string[] = [];
+  await retainLeavingTabAfterEviction({
+    sessionId: "leaving",
+    candidates: ["victim", "next"],
+    keepCount: 2,
+    stillWantsRetention: () => true,
+    softHide: () => recoveredOutcomes.push("soft-hide"),
+    fullHibernate: () => recoveredOutcomes.push("full-hibernate"),
+    evict: async (sessionId) => {
+      recovered.push(sessionId);
+      await Promise.resolve();
+      return sessionId === "next";
+    },
+  });
+  assert.deepEqual(recovered, ["victim", "next"]);
+  assert.deepEqual(recoveredOutcomes, ["soft-hide"]);
+});
+
+test("a leaving tab that no longer wants retention is not soft-hidden or hibernated", async () => {
+  const outcomes: string[] = [];
+  await retainLeavingTabAfterEviction({
+    sessionId: "leaving",
+    candidates: ["victim"],
+    keepCount: 2,
+    stillWantsRetention: () => false,
+    softHide: () => outcomes.push("soft-hide"),
+    fullHibernate: () => outcomes.push("full-hibernate"),
+    evict: async () => true,
+  });
+  assert.deepEqual(outcomes, []);
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 0);
+});
+
+test("a pending reservation keeps a second tab from seeing spare capacity", async () => {
+  const sessions = ["victim", "other", "leaving"];
+  for (const sessionId of sessions) terminalHiddenRendererStore.clearSoftHidden(sessionId);
+  terminalHiddenRendererStore.markSoftHidden("victim");
+  terminalHiddenRendererStore.markSoftHidden("other");
+
+  const unsubscribe = terminalHiddenRendererStore.subscribe(() => {
+    if (!terminalHiddenRendererStore.consumeEvictionRequest("victim")) return;
+    terminalHiddenRendererStore.clearSoftHidden("victim");
+  });
+
+  const outcomes: string[] = [];
+  const pending = retainLeavingTabAfterEviction({
+    sessionId: "leaving",
+    candidates: ["victim"],
+    keepCount: 2,
+    stillWantsRetention: () => true,
+    softHide: () => {
+      terminalHiddenRendererStore.markSoftHidden("leaving");
+      outcomes.push("soft-hide");
+    },
+    fullHibernate: () => outcomes.push("full-hibernate"),
+    evict: (sessionId) => terminalHiddenRendererStore.evictSoftHidden(sessionId),
+  });
+
+  try {
+    assert.equal(terminalHiddenRendererStore.isSoftHidden("victim"), false);
+    assert.equal(terminalHiddenRendererStore.getSoftHiddenCount(), 1);
+    assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 2);
+    assert.deepEqual(decideHiddenTabKeepCountAction({
+      keepCount: 2,
+      softHiddenCount: terminalHiddenRendererStore.getSoftHiddenOccupancy(),
+      sessionId: "second",
+      candidatesOldestFirst: terminalHiddenRendererStore.listSoftHiddenOldestFirst(),
+    }), { action: "await-eviction", candidates: ["other"] });
+
+    terminalHiddenRendererStore.settleEviction("victim", true);
+    await pending;
+    assert.deepEqual(outcomes, ["soft-hide"]);
+    assert.equal(terminalHiddenRendererStore.getSoftHiddenCount(), 2);
+    assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 2);
+  } finally {
+    unsubscribe();
+    terminalHiddenRendererStore.settleEviction("victim", false);
+    for (const sessionId of sessions) terminalHiddenRendererStore.clearSoftHidden(sessionId);
+    await pending.catch(() => undefined);
+  }
+});
+
+test("two leaving tabs share one freed slot and stay within keep-count", async () => {
+  const sessions = ["victim", "other", "leaving-a", "leaving-b"];
+  for (const sessionId of sessions) terminalHiddenRendererStore.clearSoftHidden(sessionId);
+  terminalHiddenRendererStore.markSoftHidden("victim");
+  terminalHiddenRendererStore.markSoftHidden("other");
+
+  const unsubscribe = terminalHiddenRendererStore.subscribe(() => {
+    if (!terminalHiddenRendererStore.consumeEvictionRequest("victim")) return;
+    terminalHiddenRendererStore.clearSoftHidden("victim");
+    queueMicrotask(() => {
+      terminalHiddenRendererStore.settleEviction("victim", true);
+    });
+  });
+
+  const retained: string[] = [];
+  const hibernated: string[] = [];
+  const retain = (sessionId: string) => retainLeavingTabAfterEviction({
+    sessionId,
+    candidates: ["victim"],
+    keepCount: 2,
+    stillWantsRetention: () => true,
+    softHide: () => {
+      terminalHiddenRendererStore.markSoftHidden(sessionId);
+      retained.push(sessionId);
+    },
+    fullHibernate: () => hibernated.push(sessionId),
+  });
+
+  try {
+    await Promise.all([retain("leaving-a"), retain("leaving-b")]);
+    assert.equal(retained.length, 1);
+    assert.equal(hibernated.length, 1);
+    assert.equal(terminalHiddenRendererStore.getSoftHiddenCount(), 2);
+    assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 2);
+  } finally {
+    unsubscribe();
+    for (const sessionId of sessions) terminalHiddenRendererStore.clearSoftHidden(sessionId);
+  }
+});

application/state/hiddenTabEviction.ts

@@ -0,0 +1,45 @@
+import { terminalHiddenRendererStore } from "./terminalHiddenRendererStore.ts";
+
+/**
+ * Walk keep-count victims until one hibernate completes, then retain the
+ * leaving tab only if its reserved slot still fits.
+ *
+ * The reservation is taken before the first await. Clearing a victim marker
+ * during wake would otherwise look like spare capacity to a second hidden-tab
+ * timer, and both tabs would soft-hide once the same eviction resolved.
+ */
+export async function retainLeavingTabAfterEviction(input: {
+  sessionId: string;
+  candidates: readonly string[];
+  keepCount: number;
+  stillWantsRetention: () => boolean;
+  softHide: () => void;
+  fullHibernate: () => void;
+  evict?: (sessionId: string) => Promise<boolean> | boolean;
+}): Promise<void> {
+  const token = terminalHiddenRendererStore.reserveLeavingSlot(input.sessionId);
+  try {
+    const evict = input.evict ?? ((sessionId: string) => (
+      terminalHiddenRendererStore.evictSoftHidden(sessionId)
+    ));
+    let completed = false;
+    for (const candidate of input.candidates) {
+      if (!candidate || candidate === input.sessionId) continue;
+      if (await evict(candidate)) {
+        completed = true;
+        break;
+      }
+    }
+    if (!input.stillWantsRetention()) return;
+    if (
+      completed
+      && terminalHiddenRendererStore.leavingSlotStillFits(input.sessionId, input.keepCount)
+    ) {
+      input.softHide();
+      return;
+    }
+    input.fullHibernate();
+  } finally {
+    terminalHiddenRendererStore.releaseLeavingSlot(input.sessionId, token);
+  }
+}

application/state/terminalHiddenRendererStore.test.ts

@@ -9,6 +9,106 @@ test("terminalHiddenRendererStore evicts oldest soft-hidden session", () => {
   terminalHiddenRendererStore.markSoftHidden("a");
   terminalHiddenRendererStore.markSoftHidden("b");
   assert.equal(terminalHiddenRendererStore.pickEvictionCandidate(2), "a");
+  assert.deepEqual(terminalHiddenRendererStore.listSoftHiddenOldestFirst(), ["a", "b"]);
   terminalHiddenRendererStore.clearSoftHidden("a");
   terminalHiddenRendererStore.clearSoftHidden("b");
 });
+
+test("evictSoftHidden reports refusal and drops an unconsumed request", async () => {
+  const sessions = ["images", "plain", "other"];
+  for (const sessionId of sessions) terminalHiddenRendererStore.clearSoftHidden(sessionId);
+  terminalHiddenRendererStore.markSoftHidden("images");
+  terminalHiddenRendererStore.markSoftHidden("plain");
+
+  const unsubscribe = terminalHiddenRendererStore.subscribe(() => {
+    if (terminalHiddenRendererStore.consumeEvictionRequest("images")) return;
+    if (terminalHiddenRendererStore.consumeEvictionRequest("plain")) {
+      terminalHiddenRendererStore.clearSoftHidden("plain");
+      terminalHiddenRendererStore.settleEviction("plain", true);
+    }
+  });
+
+  try {
+    assert.equal(await terminalHiddenRendererStore.evictSoftHidden("images"), false);
+    assert.equal(terminalHiddenRendererStore.isSoftHidden("images"), true);
+    assert.equal(await terminalHiddenRendererStore.evictSoftHidden("plain"), true);
+    assert.equal(terminalHiddenRendererStore.isSoftHidden("plain"), false);
+  } finally {
+    unsubscribe();
+    for (const sessionId of sessions) terminalHiddenRendererStore.clearSoftHidden(sessionId);
+  }
+
+  terminalHiddenRendererStore.markSoftHidden("images");
+  assert.equal(await terminalHiddenRendererStore.evictSoftHidden("images"), false);
+  const delivered: string[] = [];
+  const later = terminalHiddenRendererStore.subscribe(() => {
+    if (terminalHiddenRendererStore.consumeEvictionRequest("images")) delivered.push("images");
+  });
+  try {
+    terminalHiddenRendererStore.markSoftHidden("other");
+    assert.deepEqual(delivered, []);
+    assert.equal(terminalHiddenRendererStore.isSoftHidden("images"), true);
+  } finally {
+    later();
+    for (const sessionId of sessions) terminalHiddenRendererStore.clearSoftHidden(sessionId);
+  }
+});
+
+test("a reserved leaving slot counts toward occupancy until it is released", () => {
+  const sessions = ["a", "b", "c", "d"];
+  for (const sessionId of sessions) terminalHiddenRendererStore.clearSoftHidden(sessionId);
+  terminalHiddenRendererStore.markSoftHidden("a");
+  terminalHiddenRendererStore.markSoftHidden("b");
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 2);
+
+  const alreadyHidden = terminalHiddenRendererStore.reserveLeavingSlot("a");
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 2);
+  terminalHiddenRendererStore.releaseLeavingSlot("a", alreadyHidden);
+
+  const tokenC = terminalHiddenRendererStore.reserveLeavingSlot("c");
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 3);
+  assert.equal(terminalHiddenRendererStore.leavingSlotStillFits("c", 2), false);
+
+  terminalHiddenRendererStore.clearSoftHidden("a");
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 2);
+  assert.equal(terminalHiddenRendererStore.leavingSlotStillFits("c", 2), true);
+
+  const tokenD = terminalHiddenRendererStore.reserveLeavingSlot("d");
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 3);
+  assert.equal(terminalHiddenRendererStore.leavingSlotStillFits("c", 2), false);
+  assert.equal(terminalHiddenRendererStore.leavingSlotStillFits("d", 2), false);
+  terminalHiddenRendererStore.releaseLeavingSlot("c", tokenD);
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 3);
+  terminalHiddenRendererStore.releaseLeavingSlot("c", tokenC);
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 2);
+  terminalHiddenRendererStore.releaseLeavingSlot("d", tokenD);
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 1);
+
+  for (const sessionId of sessions) terminalHiddenRendererStore.clearSoftHidden(sessionId);
+  assert.equal(terminalHiddenRendererStore.getSoftHiddenOccupancy(), 0);
+});
+
+test("evictSoftHidden waits for hibernate after the marker is cleared", async () => {
+  terminalHiddenRendererStore.clearSoftHidden("victim");
+  terminalHiddenRendererStore.markSoftHidden("victim");
+  let markerClearedBeforeSettle = false;
+  const unsubscribe = terminalHiddenRendererStore.subscribe(() => {
+    if (!terminalHiddenRendererStore.consumeEvictionRequest("victim")) return;
+    terminalHiddenRendererStore.clearSoftHidden("victim");
+    markerClearedBeforeSettle = !terminalHiddenRendererStore.isSoftHidden("victim");
+    queueMicrotask(() => {
+      terminalHiddenRendererStore.markSoftHidden("victim");
+      terminalHiddenRendererStore.settleEviction("victim", false);
+    });
+  });
+
+  try {
+    const completed = await terminalHiddenRendererStore.evictSoftHidden("victim");
+    assert.equal(markerClearedBeforeSettle, true);
+    assert.equal(completed, false);
+    assert.equal(terminalHiddenRendererStore.isSoftHidden("victim"), true);
+  } finally {
+    unsubscribe();
+    terminalHiddenRendererStore.clearSoftHidden("victim");
+  }
+});

application/state/terminalHiddenRendererStore.ts

@@ -3,14 +3,85 @@ type Listener = () => void;
 const softHiddenSessions = new Map<string, number>();
 const listeners = new Set<Listener>();
 let evictionRequestSessionId: string | null = null;
+/** Leaving tabs that have claimed a keep slot while a victim hibernate is in flight. */
+const reservedLeavingSlots = new Map<string, number>();
+let reservationToken = 0;
+
+function reservedLeavingCount(): number {
+  let extra = 0;
+  for (const sessionId of reservedLeavingSlots.keys()) {
+    if (!softHiddenSessions.has(sessionId)) extra += 1;
+  }
+  return extra;
+}
+
+type EvictionWaiter = {
+  promise: Promise<boolean>;
+  resolve: (completed: boolean) => void;
+  settled: boolean;
+};
+
+const evictionWaiters = new Map<string, EvictionWaiter>();
+
+function finishEviction(sessionId: string, completed: boolean): void {
+  const waiter = evictionWaiters.get(sessionId);
+  if (!waiter || waiter.settled) return;
+  waiter.settled = true;
+  evictionWaiters.delete(sessionId);
+  if (evictionRequestSessionId === sessionId) evictionRequestSessionId = null;
+  waiter.resolve(completed);
+}
 
 function emit(): void {
   listeners.forEach((listener) => listener());
 }
 
+function listSoftHiddenOldestFirst(): string[] {
+  return [...softHiddenSessions.entries()]
+    .sort((left, right) => left[1] - right[1])
+    .map(([sessionId]) => sessionId);
+}
+
 export const terminalHiddenRendererStore = {
   getSoftHiddenCount: () => softHiddenSessions.size,
 
+  /**
+   * Soft-hidden markers plus leaving tabs that reserved a slot and are not
+   * yet in the marker set. Keep-count decisions use this so a second timer
+   * cannot take the slot a pending eviction already claimed.
+   */
+  getSoftHiddenOccupancy: () => softHiddenSessions.size + reservedLeavingCount(),
+
+  /**
+   * Claim one keep slot for a leaving tab before awaiting eviction.
+   * A session already in the marker set is not counted twice. A later claim
+   * for the same id replaces the token; only that token can release it.
+   */
+  reserveLeavingSlot: (sessionId: string): number => {
+    const token = ++reservationToken;
+    if (sessionId && !softHiddenSessions.has(sessionId)) {
+      reservedLeavingSlots.set(sessionId, token);
+    }
+    return token;
+  },
+
+  releaseLeavingSlot: (sessionId: string, token: number) => {
+    if (reservedLeavingSlots.get(sessionId) === token) {
+      reservedLeavingSlots.delete(sessionId);
+    }
+  },
+
+  /**
+   * True when retaining this leaving tab would stay within keepCount.
+   * Its own reservation is not counted against the slots held by others.
+   */
+  leavingSlotStillFits: (sessionId: string, keepCount: number): boolean => {
+    if (!(keepCount > 0)) return false;
+    const reservedHere = reservedLeavingSlots.has(sessionId) && !softHiddenSessions.has(sessionId);
+    const others = softHiddenSessions.size + reservedLeavingCount() - (reservedHere ? 1 : 0);
+    return others < keepCount;
+  },
+
   isSoftHidden: (sessionId: string) => softHiddenSessions.has(sessionId),
 
   markSoftHidden: (sessionId: string) => {
@@ -23,18 +94,12 @@ export const terminalHiddenRendererStore = {
     emit();
   },
 
+  listSoftHiddenOldestFirst: (): string[] => listSoftHiddenOldestFirst(),
+
   /** Returns the oldest soft-hidden session id when over the keep limit. */
   pickEvictionCandidate: (keepCount: number): string | null => {
     if (softHiddenSessions.size < keepCount) return null;
-    let oldestId: string | null = null;
-    let oldestTs = Number.POSITIVE_INFINITY;
-    for (const [sessionId, ts] of softHiddenSessions) {
-      if (ts < oldestTs) {
-        oldestTs = ts;
-        oldestId = sessionId;
-      }
-    }
-    return oldestId;
+    return listSoftHiddenOldestFirst()[0] ?? null;
   },
 
   requestEviction: (sessionId: string) => {
@@ -42,6 +107,44 @@ export const terminalHiddenRendererStore = {
     emit();
   },
 
+  /** True while this session's hibernate has been requested and not settled. */
+  hasPendingEviction: (sessionId: string): boolean => {
+    const waiter = evictionWaiters.get(sessionId);
+    return waiter != null && !waiter.settled;
+  },
+
+  /**
+   * Ask one soft-hidden session to upgrade. Resolves true only when
+   * settleEviction reports that hibernation finished. Clearing the marker
+   * during wake is not success: drain, snapshot, or alternate-screen failure
+   * can still restore that renderer. A synchronous refusal (marker still
+   * present, including inline images) resolves false and drops an unconsumed
+   * request so a later emit cannot upgrade it.
+   */
+  evictSoftHidden: (sessionId: string): Promise<boolean> => {
+    const existing = evictionWaiters.get(sessionId);
+    if (existing) return existing.promise;
+    if (!softHiddenSessions.has(sessionId)) return Promise.resolve(false);
+
+    let resolvePromise!: (completed: boolean) => void;
+    const promise = new Promise<boolean>((resolve) => {
+      resolvePromise = resolve;
+    });
+    const waiter: EvictionWaiter = { promise, resolve: resolvePromise, settled: false };
+    evictionWaiters.set(sessionId, waiter);
+    evictionRequestSessionId = sessionId;
+    emit();
+    if (!waiter.settled && softHiddenSessions.has(sessionId)) {
+      finishEviction(sessionId, false);
+    }
+    return promise;
+  },
+
+  /** Record whether the in-flight eviction's hibernate actually completed. */
+  settleEviction: (sessionId: string, completed: boolean) => {
+    finishEviction(sessionId, completed);
+  },
+
   consumeEvictionRequest: (sessionId: string): boolean => {
     if (evictionRequestSessionId !== sessionId) return false;
     evictionRequestSessionId = null;

application/state/useTerminalSidePanelLayoutState.test.tsx

@@ -1,8 +1,13 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import React from 'react';
+import React, { startTransition, useState } from 'react';
+import { flushSync } from 'react-dom';
+import { createRoot, type Root } from 'react-dom/client';
+import { JSDOM } from 'jsdom';
 import { act, create, type ReactTestRenderer } from 'react-test-renderer';
 
+import { readFileSync } from 'node:fs';
+
 import { collectSidePanelPanes } from '../../domain/sidePanelLayout.ts';
 import { useTerminalSidePanelLayoutState } from './useTerminalSidePanelLayoutState.ts';
 
@@ -130,3 +135,231 @@ test('closing the final pane removes only that terminal side panel state', async
     actEnvironment.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
   }
 });
+
+test('selecting a side panel tool commits open tabs and layout in one render', async () => {
+  const actEnvironment = globalThis as typeof globalThis & {
+    IS_REACT_ACT_ENVIRONMENT?: boolean;
+  };
+  const previousActEnvironment = actEnvironment.IS_REACT_ACT_ENVIRONMENT;
+  actEnvironment.IS_REACT_ACT_ENVIRONMENT = true;
+  let state: ReturnType<typeof useTerminalSidePanelLayoutState> | null = null;
+  let renderer: ReactTestRenderer | null = null;
+  let renders = 0;
+
+  const Probe = () => {
+    state = useTerminalSidePanelLayoutState();
+    renders += 1;
+    return null;
+  };
+
+  try {
+    await act(async () => {
+      renderer = create(React.createElement(Probe));
+    });
+    renders = 0;
+    await act(async () => {
+      state?.selectSidePanelToolForTab('terminal-a', 'notes');
+    });
+    assert.equal(renders, 1, 'open tabs and layout share one commit');
+    assert.equal(state!.sidePanelOpenTabs.get('terminal-a'), 'notes');
+    const layout = state!.sidePanelLayouts.get('terminal-a')!;
+    assert.equal(
+      collectSidePanelPanes(layout.root).find((pane) => pane.id === layout.focusedPaneId)?.tool,
+      'notes',
+    );
+
+    await act(async () => {
+      state?.splitPane('terminal-a', 'ai', 'vertical', {
+        paneId: 'pane-ai',
+        splitId: 'split-a',
+      }, 400);
+    });
+    const beforeFocus = state!.sidePanelLayouts.get('terminal-a')!;
+    await act(async () => {
+      state?.selectSidePanelToolForTab('terminal-a', 'notes');
+    });
+    const focusedExisting = state!.sidePanelLayouts.get('terminal-a')!;
+    assert.deepEqual(
+      collectSidePanelPanes(focusedExisting.root).map((pane) => pane.tool),
+      ['notes', 'ai'],
+    );
+    assert.equal(
+      collectSidePanelPanes(focusedExisting.root).find((pane) => pane.id === focusedExisting.focusedPaneId)?.tool,
+      'notes',
+    );
+    assert.equal(state!.sidePanelOpenTabs.get('terminal-a'), 'notes');
+    assert.notEqual(focusedExisting, beforeFocus);
+    assert.equal(focusedExisting.root, beforeFocus.root, 'focusing an open tool must not rebuild the split');
+
+    const settled = state!.sidePanelLayouts;
+    renders = 0;
+    await act(async () => {
+      state?.selectSidePanelToolForTab('terminal-a', 'notes');
+    });
+    assert.equal(renders, 0);
+    assert.equal(state!.sidePanelLayouts, settled);
+  } finally {
+    await act(async () => {
+      renderer?.unmount();
+    });
+    actEnvironment.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
+  }
+});
+
+test('a pending side-panel write survives an urgent render on another tab', async () => {
+  const dom = new JSDOM('<!doctype html><html><body></body></html>', { url: 'http://localhost' });
+  const previousWindow = globalThis.window;
+  const previousDocument = globalThis.document;
+  Object.defineProperty(globalThis, 'window', { configurable: true, value: dom.window });
+  Object.defineProperty(globalThis, 'document', { configurable: true, value: dom.window.document });
+  const actEnvironment = globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean };
+  const previousActEnvironment = actEnvironment.IS_REACT_ACT_ENVIRONMENT;
+  actEnvironment.IS_REACT_ACT_ENVIRONMENT = true;
+
+  let state: ReturnType<typeof useTerminalSidePanelLayoutState> | null = null;
+  let bump: ((value: number) => void) | null = null;
+  const Probe = () => {
+    state = useTerminalSidePanelLayoutState();
+    const [, setTick] = useState(0);
+    bump = setTick;
+    return null;
+  };
+
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root: Root = createRoot(container);
+  const tools = (tabId: string, fromRef = false) => {
+    const layout = fromRef
+      ? state?.sidePanelLayoutsRef.current.get(tabId)
+      : state?.sidePanelLayouts.get(tabId);
+    return layout ? collectSidePanelPanes(layout.root).map((pane) => pane.tool) : [];
+  };
+
+  try {
+    await act(async () => {
+      root.render(React.createElement(Probe));
+    });
+    await act(async () => {
+      state?.selectSidePanelToolForTab('terminal-a', 'notes');
+      state?.selectSidePanelToolForTab('terminal-b', 'scripts');
+    });
+    await act(async () => {
+      state?.splitPane('terminal-a', 'ai', 'vertical', {
+        paneId: 'pane-ai',
+        splitId: 'split-a',
+      }, 400);
+    });
+
+    await act(async () => {
+      startTransition(() => {
+        state?.selectSidePanelToolForTab('terminal-a', 'history');
+      });
+      flushSync(() => {
+        bump?.(1);
+      });
+      assert.deepEqual(tools('terminal-a'), ['notes', 'ai']);
+      assert.deepEqual(tools('terminal-a', true), ['notes', 'history']);
+      startTransition(() => {
+        state?.selectSidePanelToolForTab('terminal-b', 'sftp');
+      });
+    });
+
+    assert.deepEqual(tools('terminal-a'), ['notes', 'history']);
+    assert.equal(state!.sidePanelOpenTabs.get('terminal-a'), 'history');
+    assert.deepEqual(tools('terminal-b'), ['sftp']);
+    assert.equal(state!.sidePanelOpenTabs.get('terminal-b'), 'sftp');
+  } finally {
+    await act(async () => {
+      root.unmount();
+    });
+    actEnvironment.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: previousWindow });
+    Object.defineProperty(globalThis, 'document', { configurable: true, value: previousDocument });
+    dom.window.close();
+  }
+});
+
+test('a pending tool switch does not leave another tab ref behind an urgent open', async () => {
+  const dom = new JSDOM('<!doctype html><html><body></body></html>', { url: 'http://localhost' });
+  const previousWindow = globalThis.window;
+  const previousDocument = globalThis.document;
+  Object.defineProperty(globalThis, 'window', { configurable: true, value: dom.window });
+  Object.defineProperty(globalThis, 'document', { configurable: true, value: dom.window.document });
+  const actEnvironment = globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean };
+  const previousActEnvironment = actEnvironment.IS_REACT_ACT_ENVIRONMENT;
+  actEnvironment.IS_REACT_ACT_ENVIRONMENT = true;
+
+  let state: ReturnType<typeof useTerminalSidePanelLayoutState> | null = null;
+  const Probe = () => {
+    state = useTerminalSidePanelLayoutState();
+    return null;
+  };
+
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root: Root = createRoot(container);
+  const focusedTool = (tabId: string, fromRef = false) => {
+    const layout = fromRef
+      ? state?.sidePanelLayoutsRef.current.get(tabId)
+      : state?.sidePanelLayouts.get(tabId);
+    if (!layout) return null;
+    return collectSidePanelPanes(layout.root).find((pane) => pane.id === layout.focusedPaneId)?.tool ?? null;
+  };
+
+  try {
+    await act(async () => {
+      root.render(React.createElement(Probe));
+    });
+    await act(async () => {
+      state?.selectSidePanelToolForTab('terminal-a', 'notes');
+      state?.selectSidePanelToolForTab('terminal-b', 'scripts');
+    });
+
+    await act(async () => {
+      startTransition(() => {
+        state?.selectSidePanelToolForTab('terminal-a', 'history');
+      });
+      flushSync(() => {
+        state?.setSidePanelOpenTabs((previous) => new Map(previous).set('terminal-b', 'browser'));
+      });
+    });
+
+    assert.equal(state!.sidePanelOpenTabs.get('terminal-a'), 'history');
+    assert.equal(state!.sidePanelOpenTabs.get('terminal-b'), 'browser');
+    assert.equal(state!.sidePanelOpenTabsRef.current.get('terminal-a'), 'history');
+    assert.equal(
+      state!.sidePanelOpenTabsRef.current.get('terminal-b'),
+      'browser',
+      'B stays rendered as browser while its ref still reports the pre-queue tool',
+    );
+    assert.equal(focusedTool('terminal-b', true), 'browser');
+
+    // handleSwitchSidePanelTab returns before select when the ref already
+    // matches the clicked tool. A stale scripts ref would ignore this click.
+    assert.notEqual(state!.sidePanelOpenTabsRef.current.get('terminal-b'), 'scripts');
+    await act(async () => {
+      state?.selectSidePanelToolForTab('terminal-b', 'scripts');
+    });
+    assert.equal(state!.sidePanelOpenTabs.get('terminal-b'), 'scripts');
+    assert.equal(state!.sidePanelOpenTabsRef.current.get('terminal-b'), 'scripts');
+    assert.equal(focusedTool('terminal-b'), 'scripts');
+    assert.equal(state!.sidePanelOpenTabs.get('terminal-a'), 'history');
+  } finally {
+    await act(async () => {
+      root.unmount();
+    });
+    actEnvironment.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: previousWindow });
+    Object.defineProperty(globalThis, 'document', { configurable: true, value: previousDocument });
+    dom.window.close();
+  }
+});
+
+test('side panel icon clicks write the tool through selectSidePanelToolForTab', () => {
+  const layerSource = readFileSync(new URL('../../components/TerminalLayer.tsx', import.meta.url), 'utf8');
+  const start = layerSource.indexOf('const handleSwitchSidePanelTab = useCallback');
+  const end = layerSource.indexOf('const handleFocusSidePanelPane = useCallback');
+  const body = layerSource.slice(start, end);
+  assert.match(body, /startTransition\(\(\) => \{\s*selectSidePanelToolForTab\(tabId, tab\);/);
+  assert.doesNotMatch(body, /setSidePanelOpenTabs/);
+});

application/state/useTerminalSidePanelLayoutState.ts

@@ -13,55 +13,215 @@ import {
   type SidePanelTool,
 } from '../../domain/sidePanelLayout';
 
+function replaceMapEntry<T>(previous: Map<string, T>, key: string, value: T): Map<string, T> {
+  if (previous.get(key) === value) return previous;
+  const next = new Map(previous);
+  next.set(key, value);
+  return next;
+}
+
+function deleteMapEntry<T>(previous: Map<string, T>, key: string): Map<string, T> {
+  if (!previous.has(key)) return previous;
+  const next = new Map(previous);
+  next.delete(key);
+  return next;
+}
+
+function entryMatches<T>(left: Map<string, T>, right: Map<string, T>, key: string): boolean {
+  return left.has(key) === right.has(key) && left.get(key) === right.get(key);
+}
+
+/**
+ * Keep a ref aligned with committed state without dropping a write React has
+ * not rendered yet. An urgent update can rebase onto a transition: the
+ * transition updater stores an intermediate map in the ref, and the later
+ * updater changes only state. Copy committed entries the pending map did not
+ * change, and follow committed once it moves past that pending value.
+ */
+function syncTrackedMap<T>(
+  pending: Map<string, T>,
+  lastRendered: Map<string, T>,
+  committed: Map<string, T>,
+): Map<string, T> {
+  if (pending === lastRendered) return committed;
+  if (pending === committed) return pending;
+
+  let changed = false;
+  const merged = new Map(pending);
+
+  for (const key of committed.keys()) {
+    if (entryMatches(pending, committed, key)) continue;
+    const pendingMatchesRendered = entryMatches(pending, lastRendered, key);
+    const committedMatchesRendered = entryMatches(committed, lastRendered, key);
+    if (pendingMatchesRendered || !committedMatchesRendered) {
+      merged.set(key, committed.get(key) as T);
+      changed = true;
+    }
+  }
+
+  for (const key of pending.keys()) {
+    if (committed.has(key)) continue;
+    if (entryMatches(pending, lastRendered, key)) {
+      merged.delete(key);
+      changed = true;
+    }
+  }
+
+  return changed ? merged : pending;
+}
+
+function publishQueuedMap<T>(
+  live: Map<string, T>,
+  capturedBase: Map<string, T>,
+  previous: Map<string, T>,
+  stateNext: Map<string, T>,
+  tabId: string,
+  value: T | null,
+): Map<string, T> {
+  // The captured map is the synchronous write. Replaying it after an
+  // intervening render drops entries that render already merged. When the ref
+  // has moved ahead of this updater's base, reapply only this tab.
+  if (live === capturedBase || live === previous) return stateNext;
+  return value === null ? deleteMapEntry(live, tabId) : replaceMapEntry(live, tabId, value);
+}
+
+function reconcileSidePanelLayouts(
+  layouts: Map<string, SidePanelLayout>,
+  openTabs: Map<string, SidePanelTool>,
+): Map<string, SidePanelLayout> | null {
+  let changed = false;
+  const next = new Map(layouts);
+
+  for (const tabId of layouts.keys()) {
+    if (!openTabs.has(tabId)) {
+      next.delete(tabId);
+      changed = true;
+    }
+  }
+
+  for (const [tabId, tool] of openTabs) {
+    const current = next.get(tabId);
+    const updated = current
+      ? selectSidePanelTool(current, tool)
+      : createSidePanelLayout(tool, crypto.randomUUID());
+    if (updated !== current) {
+      next.set(tabId, updated);
+      changed = true;
+    }
+  }
+
+  return changed ? next : null;
+}
+
 export function useTerminalSidePanelLayoutState() {
   const [sidePanelOpenTabs, setSidePanelOpenTabs] = useState<Map<string, SidePanelTool>>(new Map());
   const [sidePanelLayouts, setSidePanelLayouts] = useState<Map<string, SidePanelLayout>>(new Map());
   const sidePanelOpenTabsRef = useRef(sidePanelOpenTabs);
   const sidePanelLayoutsRef = useRef(sidePanelLayouts);
-  sidePanelOpenTabsRef.current = sidePanelOpenTabs;
-  sidePanelLayoutsRef.current = sidePanelLayouts;
+  // Last maps this hook rendered. A transition can update the refs before React
+  // commits them; an urgent render in between must not copy the stale state
+  // back over that pending write. Once the queue commits, entries the pending
+  // write did not touch still have to catch up, or the ref stays on the
+  // transition updater's intermediate map.
+  const renderedOpenTabsRef = useRef(sidePanelOpenTabs);
+  const renderedLayoutsRef = useRef(sidePanelLayouts);
+  sidePanelOpenTabsRef.current = syncTrackedMap(
+    sidePanelOpenTabsRef.current,
+    renderedOpenTabsRef.current,
+    sidePanelOpenTabs,
+  );
+  renderedOpenTabsRef.current = sidePanelOpenTabs;
+  sidePanelLayoutsRef.current = syncTrackedMap(
+    sidePanelLayoutsRef.current,
+    renderedLayoutsRef.current,
+    sidePanelLayouts,
+  );
+  renderedLayoutsRef.current = sidePanelLayouts;
 
   // Legacy and external open paths write the focused-tool map. Reconcile that
   // public application boundary into the per-tab tree without disturbing the
-  // other panes in an existing layout.
+  // other panes in an existing layout. Skip the setState when the click path
+  // already stored this selection: scheduling an identical update still
+  // renders again after a paired openTabs write.
   useEffect(() => {
+    const base = sidePanelLayoutsRef.current;
+    const reconciled = reconcileSidePanelLayouts(base, sidePanelOpenTabs);
+    if (!reconciled) return;
+    sidePanelLayoutsRef.current = reconciled;
     setSidePanelLayouts((previous) => {
-      let changed = false;
-      const next = new Map(previous);
-
-      for (const tabId of previous.keys()) {
-        if (!sidePanelOpenTabs.has(tabId)) {
-          next.delete(tabId);
-          changed = true;
-        }
+      const next = previous === base
+        ? reconciled
+        : reconcileSidePanelLayouts(previous, sidePanelOpenTabs);
+      if (!next) {
+        sidePanelLayoutsRef.current = previous;
+        return previous;
       }
-
-      for (const [tabId, tool] of sidePanelOpenTabs) {
-        const current = next.get(tabId);
-        const updated = current
-          ? selectSidePanelTool(current, tool)
-          : createSidePanelLayout(tool, crypto.randomUUID());
-        if (updated !== current) {
-          next.set(tabId, updated);
-          changed = true;
-        }
-      }
-
-      if (changed) sidePanelLayoutsRef.current = next;
-      return changed ? next : previous;
+      sidePanelLayoutsRef.current = next;
+      return next;
     });
   }, [sidePanelOpenTabs]);
 
-  const commitLayout = useCallback((tabId: string, layout: SidePanelLayout) => {
-    const layouts = new Map(sidePanelLayoutsRef.current).set(tabId, layout);
-    const focusedTool = getFocusedSidePanelPane(layout).tool;
-    const openTabs = new Map(sidePanelOpenTabsRef.current).set(tabId, focusedTool);
+  const commitMap = useCallback((
+    tabId: string,
+    layout: SidePanelLayout,
+    openTab: SidePanelTool | null,
+  ) => {
+    const layoutBase = sidePanelLayoutsRef.current;
+    const openTabBase = sidePanelOpenTabsRef.current;
+    const layouts = openTab === null
+      ? deleteMapEntry(layoutBase, tabId)
+      : replaceMapEntry(layoutBase, tabId, layout);
+    const openTabs = openTab === null
+      ? deleteMapEntry(openTabBase, tabId)
+      : replaceMapEntry(openTabBase, tabId, openTab);
     sidePanelLayoutsRef.current = layouts;
     sidePanelOpenTabsRef.current = openTabs;
-    setSidePanelLayouts(layouts);
-    setSidePanelOpenTabs(openTabs);
+    setSidePanelLayouts((previous) => {
+      const next = previous === layoutBase
+        ? layouts
+        : (openTab === null ? deleteMapEntry(previous, tabId) : replaceMapEntry(previous, tabId, layout));
+      sidePanelLayoutsRef.current = publishQueuedMap(
+        sidePanelLayoutsRef.current,
+        layoutBase,
+        previous,
+        next,
+        tabId,
+        openTab === null ? null : layout,
+      );
+      return next;
+    });
+    setSidePanelOpenTabs((previous) => {
+      const next = previous === openTabBase
+        ? openTabs
+        : (openTab === null ? deleteMapEntry(previous, tabId) : replaceMapEntry(previous, tabId, openTab));
+      sidePanelOpenTabsRef.current = publishQueuedMap(
+        sidePanelOpenTabsRef.current,
+        openTabBase,
+        previous,
+        next,
+        tabId,
+        openTab,
+      );
+      return next;
+    });
   }, []);
 
+  const commitLayout = useCallback((tabId: string, layout: SidePanelLayout) => {
+    commitMap(tabId, layout, getFocusedSidePanelPane(layout).tool);
+  }, [commitMap]);
+
+  // Click path writes the focused tool and the layout together. The effect
+  // above still reconciles external openTabs writes, and skips when
+  // selectSidePanelTool returns the layout this call just stored.
+  const selectSidePanelToolForTab = useCallback((tabId: string, tool: SidePanelTool) => {
+    const current = sidePanelLayoutsRef.current.get(tabId);
+    const updated = current
+      ? selectSidePanelTool(current, tool)
+      : createSidePanelLayout(tool, crypto.randomUUID());
+    if (updated === current && sidePanelOpenTabsRef.current.get(tabId) === tool) return;
+    commitLayout(tabId, updated);
+  }, [commitLayout]);
+
   const focusPane = useCallback((tabId: string, paneId: string) => {
     const layout = sidePanelLayoutsRef.current.get(tabId);
     if (!layout) return;
@@ -97,25 +257,23 @@ export function useTerminalSidePanelLayoutState() {
       return false;
     }
 
-    const layouts = new Map(sidePanelLayoutsRef.current);
-    const openTabs = new Map(sidePanelOpenTabsRef.current);
-    layouts.delete(tabId);
-    openTabs.delete(tabId);
-    sidePanelLayoutsRef.current = layouts;
-    sidePanelOpenTabsRef.current = openTabs;
-    setSidePanelLayouts(layouts);
-    setSidePanelOpenTabs(openTabs);
+    commitMap(tabId, layout, null);
     return true;
-  }, [commitLayout]);
+  }, [commitLayout, commitMap]);
 
   const resizeSplit = useCallback((tabId: string, splitId: string, sizes: number[]) => {
     const layout = sidePanelLayoutsRef.current.get(tabId);
     if (!layout) return;
     const nextLayout = resizeSidePanelSplit(layout, splitId, sizes);
     if (nextLayout === layout) return;
-    const layouts = new Map(sidePanelLayoutsRef.current).set(tabId, nextLayout);
+    const base = sidePanelLayoutsRef.current;
+    const layouts = replaceMapEntry(base, tabId, nextLayout);
     sidePanelLayoutsRef.current = layouts;
-    setSidePanelLayouts(layouts);
+    setSidePanelLayouts((previous) => {
+      const next = previous === base ? layouts : replaceMapEntry(previous, tabId, nextLayout);
+      sidePanelLayoutsRef.current = next;
+      return next;
+    });
   }, []);
 
   return {
@@ -129,5 +287,6 @@ export function useTerminalSidePanelLayoutState() {
     splitPane,
     closePane,
     resizeSplit,
+    selectSidePanelToolForTab,
   };
 }

components/Terminal.tsx

@@ -243,6 +243,7 @@ import {
 import {
   canHibernateTerminalRuntimeSession,
   canHibernateTerminalRuntimeStatus,
+  decideHiddenTabKeepCountAction,
   isTerminalFileTransferActive,
   resolveHibernateKeepRendererCount,
   resolveHibernatePreferWasmSerialize,
@@ -254,6 +255,7 @@ import {
 } from "../domain/terminalHibernate";
 import { getLastChar, removeLastChar } from "../domain/serialCharMetrics";
 import { stringCellWidth } from "./terminal/autocomplete/terminalStringCellWidth";
+import { retainLeavingTabAfterEviction } from "../application/state/hiddenTabEviction";
 import { terminalHiddenRendererStore } from "../application/state/terminalHiddenRendererStore";
 import {
   wakeTerminalFromHibernate,
@@ -522,6 +524,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   const hibernateAlternateScreenRef = useRef(false);
   const hibernateRetryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const fullHibernateRuntimeRef = useRef<(() => Promise<boolean>) | null>(null);
+  const hibernateEvictionAttemptRef = useRef(0);
   const wakeSoftHiddenRuntimeRef = useRef<(() => void) | null>(null);
   const resumeRendererAfterCancelledHibernateUpgradeRef = useRef<(() => void) | null>(null);
   const wakeInProgressRef = useRef(false);
@@ -2297,20 +2300,6 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   ]);
   fullHibernateRuntimeRef.current = fullHibernateRuntime;
 
-  const upgradeSoftHiddenRuntimeToHibernate = useCallback(() => {
-    if (!wakeSoftHiddenRuntimeRef.current) return;
-    wakeSoftHiddenRuntimeRef.current?.();
-    void fullHibernateRuntime().then(
-      (completed) => {
-        if (!completed) resumeRendererAfterCancelledHibernateUpgradeRef.current?.();
-      },
-      (error) => {
-        logger.error("[Terminal] Failed to upgrade soft-hidden runtime to hibernate", { sessionId, error });
-        resumeRendererAfterCancelledHibernateUpgradeRef.current?.();
-      },
-    );
-  }, [fullHibernateRuntime, sessionId]);
-
   const hideRuntimeOnly = useCallback(() => {
     if (hibernatedRef.current || softHiddenRef.current || !hasRuntimeRef.current) return;
     xtermRuntimeRef.current?.suspendWebglRenderer();
@@ -2319,6 +2308,39 @@ const TerminalComponent: React.FC<TerminalProps> = ({
     logger.info("[Terminal] Soft-hidden runtime", { sessionId });
   }, [sessionId]);
 
+  const upgradeSoftHiddenRuntimeToHibernate = useCallback(() => {
+    const pendingEviction = terminalHiddenRendererStore.hasPendingEviction(sessionId);
+    if (!wakeSoftHiddenRuntimeRef.current) {
+      terminalHiddenRendererStore.settleEviction(sessionId, false);
+      return;
+    }
+    wakeSoftHiddenRuntimeRef.current?.();
+    void fullHibernateRuntime().then(
+      (completed) => {
+        if (!completed) {
+          resumeRendererAfterCancelledHibernateUpgradeRef.current?.();
+          // Wake already dropped the marker. Restore the soft-hidden slot only
+          // while this tab is still hidden and hibernate is still enabled.
+          // Selecting the victim during the drain makes fullHibernateRuntime
+          // return false because the tab is visible; soft-hiding it again
+          // would hide the tab the user just opened.
+          if (pendingEviction && !isVisibleRef.current && hibernateEnabledRef.current) {
+            hideRuntimeOnly();
+          }
+        }
+        terminalHiddenRendererStore.settleEviction(sessionId, completed);
+      },
+      (error) => {
+        logger.error("[Terminal] Failed to upgrade soft-hidden runtime to hibernate", { sessionId, error });
+        resumeRendererAfterCancelledHibernateUpgradeRef.current?.();
+        if (pendingEviction && !isVisibleRef.current && hibernateEnabledRef.current) {
+          hideRuntimeOnly();
+        }
+        terminalHiddenRendererStore.settleEviction(sessionId, false);
+      },
+    );
+  }, [fullHibernateRuntime, hideRuntimeOnly, sessionId]);
+
   const hibernateRuntime = useCallback(() => {
     if (hibernatedRef.current || !termRef.current) return;
 
@@ -2343,16 +2365,40 @@ const TerminalComponent: React.FC<TerminalProps> = ({
     const keepCount = statusRef.current === "connected"
       ? resolveHibernateKeepRendererCount(terminalSettings)
       : 0;
-    if (keepCount > 0 && terminalHiddenRendererStore.getSoftHiddenCount() < keepCount) {
+    const keepDecision = decideHiddenTabKeepCountAction({
+      keepCount,
+      softHiddenCount: terminalHiddenRendererStore.getSoftHiddenOccupancy(),
+      sessionId,
+      candidatesOldestFirst: keepCount > 0
+        ? terminalHiddenRendererStore.listSoftHiddenOldestFirst()
+        : [],
+    });
+    if (keepDecision.action === "soft-hide") {
       hideRuntimeOnly();
       return;
     }
-
-    if (keepCount > 0) {
-      const victim = terminalHiddenRendererStore.pickEvictionCandidate(keepCount);
-      if (victim && victim !== sessionId) {
-        terminalHiddenRendererStore.requestEviction(victim);
-      }
+    if (keepDecision.action === "await-eviction") {
+      const attempt = ++hibernateEvictionAttemptRef.current;
+      // Reserves this tab's slot before the first await, then soft-hides only
+      // if a victim hibernate completes and the slot still fits. A sync marker
+      // clear is not enough: alt-screen and drain/snapshot failure restore the
+      // victim, and this tab stays out of the soft-hidden set.
+      void retainLeavingTabAfterEviction({
+        sessionId,
+        candidates: keepDecision.candidates,
+        keepCount,
+        stillWantsRetention: () => (
+          hibernateEvictionAttemptRef.current === attempt
+          && !isVisibleRef.current
+          && !hibernatedRef.current
+          && !softHiddenRef.current
+        ),
+        softHide: () => hideRuntimeOnly(),
+        fullHibernate: () => {
+          void fullHibernateRuntime();
+        },
+      });
+      return;
     }
 
     void fullHibernateRuntime();

components/TerminalLayer.tsx

@@ -319,6 +319,7 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
     splitPane: splitSidePanelPaneForTab,
     closePane: closeSidePanelPaneForTab,
     resizeSplit: resizeSidePanelSplitForTab,
+    selectSidePanelToolForTab,
   } = useTerminalSidePanelLayoutState();
   useEffect(() => {
     pruneComposeBarHistory(sessions.map((session) => session.id));
@@ -1752,13 +1753,9 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
     if (!prepareSidePanelTool(tabId, tab)) return;
 
     startTransition(() => {
-      setSidePanelOpenTabs(prev => {
-        const next = new Map(prev);
-        next.set(tabId, tab);
-        return next;
-      });
+      selectSidePanelToolForTab(tabId, tab);
     });
-  }, [prepareSidePanelTool, setSidePanelOpenTabs, sidePanelOpenTabsRef]);
+  }, [prepareSidePanelTool, selectSidePanelToolForTab, sidePanelOpenTabsRef]);
 
   const handleFocusSidePanelPane = useCallback((paneId: string) => {
     const tabId = activeTabIdRef.current;

components/notes/NotesManager.perf.test.ts

@@ -43,6 +43,26 @@ test("note content drafts stay in refs so MDX keystrokes do not rebuild the shel
   );
 });
 
+test("hidden notes flush drafts on the isActive edge without rebuilding the tree", () => {
+  assert.match(
+    managerSource,
+    /useLayoutEffect\(\(\) => \{\s*if \(isActive\) return;\s*flushNoteDraftRef\.current\(\);\s*\}, \[isActive\]\);/,
+  );
+  assert.match(managerSource, /const NotesTreePane = memo\(/);
+  assert.match(managerSource, /notesTreePanePropsEqual/);
+  assert.match(managerSource, /prev\.selectedNoteId === next\.selectedNoteId/);
+  assert.match(managerSource, /prev\.editingNoteId === next\.editingNoteId/);
+  assert.match(managerSource, /prev\.editingGroupPath === next\.editingGroupPath/);
+  assert.match(managerSource, /prev\.expandedGroups === next\.expandedGroups/);
+  assert.match(managerSource, /<NotesTreePane/);
+  assert.doesNotMatch(managerSource, /key=\{isActive\}/);
+  assert.doesNotMatch(
+    managerSource,
+    /if \(!isActive\) return null;/,
+    "hiding notes must not unmount NotesManager",
+  );
+});
+
 test("NotesManager teardown flush uses a stable ref under StrictMode", () => {
   assert.match(managerSource, /flushNoteDraftRef\.current = flushNoteDraft/);
   assert.match(
@@ -73,6 +93,21 @@ test("hidden terminal notes side panel does not subscribe to notes publishes", (
     "utf8",
   );
   assert.match(slotsSource, /useNotesStore\(\{\s*enabled:\s*isVisible\s*\}\)/);
+  const notesSlot = slotsSource.slice(
+    slotsSource.indexOf("function SidePanelNotesSlotInner"),
+    slotsSource.indexOf("export const SidePanelNotesSlot"),
+  );
+  assert.doesNotMatch(notesSlot, /if \(!isVisible\) return null/);
+  assert.match(notesSlot, /<NotesManager/);
+  const notesStoreSource = readFileSync(
+    new URL("../../application/state/notesStore.ts", import.meta.url),
+    "utf8",
+  );
+  assert.doesNotMatch(
+    notesStoreSource,
+    /enabled \? getNotesSnapshot : getEmptyNotesSnapshot/,
+    "enabled:false must keep the live snapshot so reopen does not flash empty",
+  );
 });
 
 test("notes manager prefetches the MDXEditor chunk when becoming active", () => {

components/notes/NotesManager.test.tsx

@@ -22,7 +22,9 @@ import {
   isNoteFolderTreeSelected,
   isNoteEditorMode,
   normalizeNoteEditorMode,
+  notesTreePanePropsEqual,
   NotesManager,
+  type NotesTreePaneProps,
 } from "./NotesManager.tsx";
 
 const note = (overrides: Partial<VaultNote> = {}): VaultNote => ({
@@ -369,10 +371,40 @@ test("NotesManager flushes drafts when retained mounts become inactive", () => {
   const source = readFileSync(new URL("./NotesManager.tsx", import.meta.url), "utf8");
   assert.match(source, /isActive\?: boolean/);
   assert.match(source, /if \(isActive\) return;/);
-  assert.match(source, /useLayoutEffect\(\(\) => \{\s*if \(isActive\) return;/);
+  assert.match(source, /useLayoutEffect\(\(\) => \{\s*if \(isActive\) return;\s*flushNoteDraftRef\.current\(\);/);
   assert.match(source, /visibilitychange/);
 });
 
+const treePaneProps = (overrides: Partial<NotesTreePaneProps> = {}): NotesTreePaneProps => ({
+  notes: [note()],
+  noteGroups: ["Ops"],
+  selectedNoteId: "note-1",
+  selectedGroup: null,
+  expandedGroups: new Set(["Ops"]),
+  editingNoteId: null,
+  editingGroupPath: null,
+  query: "",
+  locale: "en",
+  hosts: [],
+  draggingNoteId: null,
+  draggingGroupPath: null,
+  creatingGroupParent: undefined,
+  isSidebarMode: true,
+  renderRows: () => null,
+  ...overrides,
+});
+
+test("notes tree pane equality ignores render callbacks and compares selection state", () => {
+  const base = treePaneProps();
+  assert.equal(notesTreePanePropsEqual(base, { ...base, renderRows: () => "other" }), true);
+  assert.equal(notesTreePanePropsEqual(base, { ...base, selectedNoteId: "note-2" }), false);
+  assert.equal(notesTreePanePropsEqual(base, { ...base, selectedGroup: "Ops" }), false);
+  assert.equal(notesTreePanePropsEqual(base, { ...base, editingNoteId: "note-1" }), false);
+  assert.equal(notesTreePanePropsEqual(base, { ...base, editingGroupPath: "Ops" }), false);
+  assert.equal(notesTreePanePropsEqual(base, { ...base, expandedGroups: new Set(["Ops"]) }), false);
+  assert.equal(notesTreePanePropsEqual(base, { ...base, notes: [note({ title: "Renamed" })] }), false);
+});
+
 test("NotesManager tree rename allows clearing note titles", () => {
   const source = readFileSync(new URL("./NotesManager.tsx", import.meta.url), "utf8");
   const renameBlock = source.match(/onRenameCommit=\{\(name\) => \{[\s\S]*?\}\}/)?.[0] ?? "";

components/notes/NotesManager.tsx

@@ -16,7 +16,7 @@ import {
   Upload,
   X,
 } from "lucide-react";
-import React, { lazy, Suspense, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import React, { lazy, memo, Suspense, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { useI18n } from "../../application/i18n/I18nProvider";
 import { useApplicationBackend } from "../../application/state/useApplicationBackend";
 import { useStoredNumber } from "../../application/state/useStoredNumber";
@@ -357,6 +357,57 @@ export const getValidatedNoteSelectionState = (
   return null;
 };
 
+export type NotesTreePaneProps = {
+  notes: VaultNote[];
+  noteGroups: string[];
+  selectedNoteId: string | null;
+  selectedGroup: string | null;
+  expandedGroups: ReadonlySet<string>;
+  editingNoteId: string | null;
+  editingGroupPath: string | null;
+  query: string;
+  locale: string;
+  hosts: Host[];
+  draggingNoteId: string | null;
+  draggingGroupPath: string | null;
+  creatingGroupParent: string | null | undefined;
+  isSidebarMode: boolean;
+  /**
+   * Row elements. Identity changes every parent render; equality ignores it so
+   * a visibility flip does not rebuild the tree. Event handlers close over the
+   * render that last changed one of the compared fields.
+   */
+  renderRows: () => React.ReactNode;
+};
+
+/**
+ * Hide/show passes a new `isActive` into NotesManager, but that flag is not a
+ * tree input. Equality therefore keys off the data the rows actually paint.
+ * `selected` / `editing` / `expanded` are required so a memo bailout cannot
+ * freeze selection, rename, or folder expansion.
+ */
+export function notesTreePanePropsEqual(prev: NotesTreePaneProps, next: NotesTreePaneProps): boolean {
+  return prev.notes === next.notes
+    && prev.noteGroups === next.noteGroups
+    && prev.selectedNoteId === next.selectedNoteId
+    && prev.selectedGroup === next.selectedGroup
+    && prev.expandedGroups === next.expandedGroups
+    && prev.editingNoteId === next.editingNoteId
+    && prev.editingGroupPath === next.editingGroupPath
+    && prev.query === next.query
+    && prev.locale === next.locale
+    && prev.hosts === next.hosts
+    && prev.draggingNoteId === next.draggingNoteId
+    && prev.draggingGroupPath === next.draggingGroupPath
+    && prev.creatingGroupParent === next.creatingGroupParent
+    && prev.isSidebarMode === next.isSidebarMode;
+}
+
+const NotesTreePane = memo(function NotesTreePane({ renderRows }: NotesTreePaneProps) {
+  return <>{renderRows()}</>;
+}, notesTreePanePropsEqual);
+NotesTreePane.displayName = "NotesTreePane";
+
 export const getNotesGroupDropAction = (
   sourceGroup: string | null,
   targetGroup: string,
@@ -381,7 +432,7 @@ export const NotesManager: React.FC<NotesManagerProps> = ({
   openNoteRequestId = null,
   onOpenNoteIdHandled,
 }) => {
-  const { t } = useI18n();
+  const { t, locale } = useI18n();
   const { openExternal } = useApplicationBackend();
   const isSidebarMode = displayMode === "sidebar";
   const initialOpenNoteId = openNoteId && notes.some((note) => note.id === openNoteId)
@@ -561,10 +612,12 @@ export const NotesManager: React.FC<NotesManagerProps> = ({
     flushNoteDraftRef.current();
   }, []);
 
+  // Hide edge only. The ref is the latest flush, so this does not subscribe
+  // the tree render to draft-writer identity, and it does not remount the editor.
   useLayoutEffect(() => {
     if (isActive) return;
-    flushNoteDraft();
-  }, [flushNoteDraft, isActive]);
+    flushNoteDraftRef.current();
+  }, [isActive]);
 
   useEffect(() => {
     if (!isActive) return;
@@ -1486,11 +1539,28 @@ export const NotesManager: React.FC<NotesManagerProps> = ({
     );
   };
 
-  const visibleRootNotes = noteTree.rootNotes.filter(noteMatches);
-  const visibleTree = noteTree.children
-    .map((child) => renderFolderRow(child, 0))
-    .filter(Boolean);
-  const treeIsEmpty = visibleRootNotes.length === 0 && visibleTree.length === 0;
+  // Built only when NotesTreePane's compared props change. isActive / the
+  // hidden class stay on the parent, so a side-panel hide does not reconcile rows.
+  const renderTreeRows = () => {
+    const visibleRootNotes = noteTree.rootNotes.filter(noteMatches);
+    const visibleTree = noteTree.children
+      .map((child) => renderFolderRow(child, 0))
+      .filter(Boolean);
+    const treeIsEmpty = visibleRootNotes.length === 0 && visibleTree.length === 0;
+    return (
+      <>
+        {renderCreateGroupRow(null, 0)}
+        {visibleTree}
+        {visibleRootNotes.map((note) => renderNoteRow(note, 0))}
+        {treeIsEmpty && (
+          <div className="rounded-lg border border-dashed border-border/70 p-4 text-center text-sm text-muted-foreground">
+            <Search size={20} className="mx-auto mb-2 opacity-60" />
+            {query.trim() ? t("notes.search.noResults") : t("notes.empty.group")}
+          </div>
+        )}
+      </>
+    );
+  };
   const hasSearch = query.trim().length > 0;
   const canExpandCollapse = allGroupPaths.length > 0 && !hasSearch;
   const shouldShowNotesTree = isSidebarMode || sortedNotes.length > 0;
@@ -1750,15 +1820,23 @@ export const NotesManager: React.FC<NotesManagerProps> = ({
               }}
               onDrop={(event) => handleGroupDrop(null, event)}
             >
-              {renderCreateGroupRow(null, 0)}
-              {visibleTree}
-              {visibleRootNotes.map((note) => renderNoteRow(note, 0))}
-              {treeIsEmpty && (
-                <div className="rounded-lg border border-dashed border-border/70 p-4 text-center text-sm text-muted-foreground">
-                  <Search size={20} className="mx-auto mb-2 opacity-60" />
-                  {query.trim() ? t("notes.search.noResults") : t("notes.empty.group")}
-                </div>
-              )}
+              <NotesTreePane
+                notes={sortedNotes}
+                noteGroups={groups}
+                selectedNoteId={selectedNoteId}
+                selectedGroup={selectedGroup}
+                expandedGroups={expandedGroups}
+                editingNoteId={editingNoteId}
+                editingGroupPath={editingGroupPath}
+                query={query}
+                locale={locale}
+                hosts={hosts}
+                draggingNoteId={draggingNoteId}
+                draggingGroupPath={draggingGroupPath}
+                creatingGroupParent={creatingGroupParent}
+                isSidebarMode={isSidebarMode}
+                renderRows={renderTreeRows}
+              />
             </div>
           </ScrollArea>
           </div>
@@ -2048,6 +2126,7 @@ export const NotesManager: React.FC<NotesManagerProps> = ({
         )}
       </div>
 
+      {/* Kept mounted while the panel is hidden. Do not key this on isActive. */}
       {isSidebarMode && overlayNoteView && (
         <div className="absolute inset-0 z-30 flex min-h-0 flex-col bg-background text-foreground">
           <div className={cn(

components/terminal/inlineImageRendering.test.ts

@@ -84,7 +84,7 @@ test("a session holding inline images degrades to soft-hide instead of full hibe
   const gateIndex = hibernateBody.indexOf("if (runtimeHasInlineImages()) {");
   const softHideIndex = hibernateBody.indexOf("hideRuntimeOnly();", gateIndex);
   const keepCountIndex = hibernateBody.indexOf("resolveHibernateKeepRendererCount(terminalSettings)");
-  const evictionIndex = hibernateBody.indexOf("terminalHiddenRendererStore.pickEvictionCandidate(");
+  const evictionIndex = hibernateBody.indexOf("retainLeavingTabAfterEviction(");
   const fullHibernateIndex = hibernateBody.indexOf("void fullHibernateRuntime()");
 
   assert.notEqual(gateIndex, -1, "hibernate must check for inline images");

components/terminal/terminalHibernateFlush.test.ts

@@ -239,6 +239,16 @@ test("a cancelled soft-hidden upgrade resumes its renderer", () => {
   assert.match(helperBody, /ensureWebglRenderer\(\)/);
   assert.match(helperBody, /clearTextureAtlas\(\)/);
   assert.match(helperBody, /safeFitRef\.current\(\{ force: true \}\)/);
+  const restoreGuard = "if (pendingEviction && !isVisibleRef.current && hibernateEnabledRef.current)";
+  assert.equal(
+    upgradeBody.split(restoreGuard).length - 1,
+    2,
+    "both the failed hibernate and the rejection path must skip soft-hide when the tab is visible or hibernate is off",
+  );
+  assert.ok(
+    upgradeBody.indexOf(restoreGuard) > upgradeIndex,
+    "the visibility guard belongs on the settled upgrade, after the renderer was resumed",
+  );
 });
 
 test("snapshot and handoff paths reject output that misses the settle deadline", () => {
@@ -282,3 +292,29 @@ test("snapshot and handoff paths reject output that misses the settle deadline",
     /const flushed = await flushPendingTerminalWritesBeforeHibernate\(snapshotTerm\);\s*if \(!flushed\) \{\s*throw new Error\("Terminal output did not settle before closing the attached display"\);\s*\}/,
   );
 });
+
+test("a full keep count soft-hides the leaving session instead of snapshotting it", () => {
+  const source = readFileSync(new URL("../Terminal.tsx", import.meta.url), "utf8");
+  const body = readFunctionBody(source, "const hibernateRuntime = useCallback(() =>");
+  const imageGate = body.indexOf("if (runtimeHasInlineImages()) {");
+  const alternateGate = body.indexOf("shouldSkipHibernateForActiveAlternateScreen(termRef.current)");
+  const decision = body.indexOf("decideHiddenTabKeepCountAction(");
+  const softHide = body.indexOf('if (keepDecision.action === "soft-hide")');
+  const hide = body.indexOf("hideRuntimeOnly();", softHide);
+  const full = body.indexOf("void fullHibernateRuntime()");
+
+  assert.ok(alternateGate !== -1 && alternateGate < imageGate);
+  assert.ok(imageGate !== -1 && imageGate < decision);
+  assert.ok(decision < softHide && softHide < hide && hide < full);
+  const awaited = body.indexOf("retainLeavingTabAfterEviction({");
+  assert.ok(awaited > decision, "a full keep set retains the leaving tab from the application eviction walk");
+  assert.match(body, /getSoftHiddenOccupancy\(\)/);
+  assert.match(body, /stillWantsRetention:/);
+  assert.match(body, /softHide: \(\) => hideRuntimeOnly\(\)/);
+  assert.doesNotMatch(body, /resolveHiddenTabEviction/);
+  assert.doesNotMatch(body, /requestEviction\(keepDecision/);
+  assert.match(
+    body,
+    /if \(softHiddenRef\.current\) \{\s*if \(statusRef\.current === "disconnected"\) \{\s*upgradeSoftHiddenRuntimeToHibernate\(\);\s*\}\s*return;\s*\}/,
+  );
+});

components/terminalLayer/terminalLayerViewMemo.test.ts

@@ -1,7 +1,9 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
 
 import type { Workspace } from "../../types";
+import { terminalPaneSessionsEqual } from "../../domain/terminalPaneSessionsEqual.ts";
 import {
   terminalLayerFocusSidebarPropsEqual,
   terminalLayerSidePanelCtxEqual,
@@ -102,6 +104,27 @@ test("terminal layer memo ignores activeWorkspace-only tab flips (live store own
   );
 });
 
+test("solo tab id change still invalidates workspace ctx; panes host does not read it", () => {
+  const sessions = [{ id: "session-a" }, { id: "session-b" }];
+  assert.equal(
+    terminalLayerWorkspaceCtxEqual(
+      { activeTabId: "session-a", sessions },
+      { activeTabId: "session-b", sessions },
+    ),
+    false,
+  );
+
+  const hostSource = readFileSync(new URL("./TerminalLayerSupport.tsx", import.meta.url), "utf8");
+  const equalStart = hostSource.indexOf("const terminalPanesHostPropsAreEqual");
+  const equalEnd = hostSource.indexOf("export const TerminalPanesHost");
+  const equalBody = hostSource.slice(equalStart, equalEnd);
+  assert.ok(equalStart !== -1 && equalEnd > equalStart);
+  assert.doesNotMatch(equalBody, /prev\.activeTabId/);
+  assert.doesNotMatch(equalBody, /next\.activeTabId/);
+  assert.match(equalBody, /terminalPaneSessionsEqual\(prev\.sessions, next\.sessions\)/);
+  assert.equal(terminalPaneSessionsEqual(sessions, sessions), true);
+});
+
 test("terminal layer memo re-renders when active resizers change", () => {
   const base = {
     activeResizers: [

components/terminalLayer/terminalLayerViewMemo.ts

@@ -343,6 +343,11 @@ const SIDE_PANEL_STABLE_CTX_KEYS = [
 ] as const;
 
 const WORKSPACE_CTX_KEYS = [
+  // Stay. Solo SSH A->B already keeps TerminalPanesHost equal when the sessions
+  // ref is unchanged (this compare does not feed the panes host). The visible
+  // pane still pays reveal flush + repaint, and focus retries at 50ms.
+  // Dropping activeTabId only skips one workspace-section pass; the live-store
+  // host/theme update still renders the section. That is not the settle cost.
   'activeTabId',
   'workspaceInnerRef',
   'workspaceOuterRef',

domain/terminalHibernate.test.ts

@@ -6,6 +6,7 @@ import {
   canHibernateTerminalRuntimeStatus,
   capHibernateBuffer,
   capHibernateBufferByLines,
+  decideHiddenTabKeepCountAction,
   isTerminalFileTransferActive,
   normalizeHibernateHiddenTabsDelaySec,
   resolveTerminalHibernateDelayMs,
@@ -92,6 +93,54 @@ test("normalizeHibernateHiddenTabsDelaySec clamps to the allowed range", () => {
   assert.equal(normalizeHibernateHiddenTabsDelaySec(9999), TERMINAL_HIBERNATE_DELAY_SEC_MAX);
 });
 
+test("a full keep-count lists eviction candidates and does not evict them itself", () => {
+  assert.deepEqual(decideHiddenTabKeepCountAction({
+    keepCount: 2,
+    softHiddenCount: 1,
+    sessionId: "leaving",
+    candidatesOldestFirst: ["older"],
+  }), { action: "soft-hide", candidates: [] });
+
+  assert.deepEqual(decideHiddenTabKeepCountAction({
+    keepCount: 2,
+    softHiddenCount: 2,
+    sessionId: "leaving",
+    candidatesOldestFirst: ["oldest", "newer"],
+  }), { action: "await-eviction", candidates: ["oldest", "newer"] });
+
+  assert.deepEqual(decideHiddenTabKeepCountAction({
+    keepCount: 2,
+    softHiddenCount: 3,
+    sessionId: "leaving",
+    candidatesOldestFirst: ["oldest"],
+  }), { action: "await-eviction", candidates: ["oldest"] });
+});
+
+test("keep-count zero still full-hibernates and does not evict", () => {
+  assert.deepEqual(decideHiddenTabKeepCountAction({
+    keepCount: 0,
+    softHiddenCount: 4,
+    sessionId: "leaving",
+    candidatesOldestFirst: ["oldest"],
+  }), { action: "full-hibernate", candidates: [] });
+});
+
+test("a full keep-count does not evict the session that is deciding", () => {
+  assert.deepEqual(decideHiddenTabKeepCountAction({
+    keepCount: 2,
+    softHiddenCount: 2,
+    sessionId: "leaving",
+    candidatesOldestFirst: ["leaving"],
+  }), { action: "full-hibernate", candidates: [] });
+
+  assert.deepEqual(decideHiddenTabKeepCountAction({
+    keepCount: 2,
+    softHiddenCount: 2,
+    sessionId: "leaving",
+    candidatesOldestFirst: ["leaving", "other"],
+  }), { action: "await-eviction", candidates: ["other"] });
+});
+
 test("resolveTerminalHibernateDelayMs converts seconds to milliseconds", () => {
   assert.equal(resolveTerminalHibernateDelayMs(), TERMINAL_HIBERNATE_DELAY_SEC_DEFAULT * 1000);
   assert.equal(resolveTerminalHibernateDelayMs({ hibernateHiddenTabsDelaySec: 10 }), 10_000);

domain/terminalHibernate.ts

@@ -158,6 +158,50 @@ export function shouldSkipHibernateForAltScreen(
   return alternateScreen && resolveHibernateSkipAltScreen(settings);
 }
 
+export type HiddenTabKeepCountDecision = {
+  /**
+   * Soft-hide immediately when the keep set has room. Await eviction when it
+   * is full. Full-hibernate when keepCount is 0 or no other candidate exists.
+   * Callers retain the leaving tab only after a victim's hibernate completes.
+   */
+  action: "soft-hide" | "full-hibernate" | "await-eviction";
+  /** Oldest-first victims to try when action is await-eviction. */
+  candidates: readonly string[];
+};
+
+/**
+ * Keep-count policy for a hidden session that is not already soft-hidden.
+ * Callers still handle alternate screen, inline images, and a soft-hidden
+ * session that later disconnects before asking. keepCount 0 (disconnected, or
+ * the setting) full-hibernates. When the soft-hide set is full this only
+ * lists candidates. It does not evict, reserve a slot, or touch renderer
+ * lifecycle. Waking a victim clears its marker before hibernate finishes, so
+ * the caller awaits that outside this helper. Wake replay order stays in
+ * resolveHibernateWakeHistory (#2762). Atlas clear on a soft wake stays in
+ * wakeSoftHiddenRuntime (#1063).
+ */
+export function decideHiddenTabKeepCountAction(input: {
+  keepCount: number;
+  softHiddenCount: number;
+  sessionId: string;
+  /** Oldest soft-hidden session first. Snapshot this before eviction mutates it. */
+  candidatesOldestFirst: readonly string[];
+}): HiddenTabKeepCountDecision {
+  if (!(input.keepCount > 0)) {
+    return { action: "full-hibernate", candidates: [] };
+  }
+  if (input.softHiddenCount < input.keepCount) {
+    return { action: "soft-hide", candidates: [] };
+  }
+  const candidates = input.candidatesOldestFirst.filter((candidate) => (
+    Boolean(candidate) && candidate !== input.sessionId
+  ));
+  if (candidates.length === 0) {
+    return { action: "full-hibernate", candidates: [] };
+  }
+  return { action: "await-eviction", candidates };
+}
+
 /** Snapshot + buffered output to replay when recreating xterm after hibernate. */
 export type TerminalHibernateWakePayload = {
   /** Full serialized terminal state -- preferred wake history (coherent ANSI). */