lael-labs/t3code

apps/mobile/src/features/terminal/NativeTerminalSurface.tsx+12−1

-import { memo, useCallback } from "react";
+import { memo, useCallback, useEffect } from "react";
 import {
   Pressable,
   ScrollView,
   getPierreTerminalTheme,
   type TerminalTheme,
 } from "./terminalTheme";
+import { terminalDebugLog } from "./terminalDebugLog";
 interface TerminalInputEvent {
   readonly data: string;
   const theme = props.theme ?? getPierreTerminalTheme(appearanceScheme);
   const { onInput, onResize } = props;
   const NativeTerminalSurfaceView = resolveNativeTerminalSurfaceView();
+  const hasNativeSurface = Boolean(NativeTerminalSurfaceView);
+  useEffect(() => {
+    terminalDebugLog("native:surface", {
+      terminalKey: props.terminalKey,
+      native: hasNativeSurface,
+      bufferLen: props.buffer.length,
+      isRunning: props.isRunning,
+    });
+  }, [hasNativeSurface, props.buffer.length, props.isRunning, props.terminalKey]);
   const handleNativeInput = useCallback(
     (event: NativeSyntheticEvent<TerminalInputEvent>) => {
       onInput(event.nativeEvent.data);

apps/mobile/src/features/terminal/ThreadTerminalPanel.tsx+11−0

 } from "../../state/use-terminal-session";
 import { TerminalSurface } from "./NativeTerminalSurface";
 import { hasNativeTerminalSurface } from "./nativeTerminalModule";
+import { terminalDebugLog } from "./terminalDebugLog";
 interface ThreadTerminalPanelProps {
   readonly environmentId: EnvironmentId;
     const client = getEnvironmentClient(props.environmentId);
     if (!client) {
+      terminalDebugLog("panel:attach-skip", {
+        reason: "no-environment-client",
+        environmentId: props.environmentId,
+      });
       return;
     }
+    terminalDebugLog("panel:attach", {
+      environmentId: props.environmentId,
+      threadId: props.threadId,
+      terminalId,
+    });
     return attachTerminalSession({
       environmentId: props.environmentId,
       client,

apps/mobile/src/features/terminal/ThreadTerminalRouteScreen.tsx+223−61

-import { DEFAULT_TERMINAL_ID, EnvironmentId, ThreadId } from "@t3tools/contracts";
+import {
+  DEFAULT_TERMINAL_ID,
+  EnvironmentId,
+  type TerminalAttachStreamEvent,
+  ThreadId,
+} from "@t3tools/contracts";
+import type { KnownTerminalSession } from "@t3tools/client-runtime";
 import { Stack, useLocalSearchParams, useRouter } from "expo-router";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Pressable, ScrollView, Text as RNText, View, useColorScheme } from "react-native";
 import { EmptyState } from "../../components/EmptyState";
 import { LoadingScreen } from "../../components/LoadingScreen";
-import { buildThreadTerminalRoutePath } from "../../lib/routes";
+import { buildThreadTerminalNavigation } from "../../lib/routes";
 import {
   getEnvironmentClient,
   useRemoteEnvironmentState,
 import { TerminalSurface } from "./NativeTerminalSurface";
 import { getPierreTerminalTheme } from "./terminalTheme";
 import { loadPreferences, savePreferencesPatch } from "../../lib/storage";
+import { terminalDebugLog } from "./terminalDebugLog";
 import {
   getTerminalBufferReplayKey,
   getTerminalSurfaceReplayBuffer,
 import {
   basename,
   buildTerminalMenuSessions,
-  getTerminalLabel,
   getTerminalStatusLabel,
-  nextTerminalId,
+  nextOpenTerminalId,
+  resolveTerminalSessionLabel,
+  type TerminalMenuSession,
 } from "./terminalMenu";
 import {
   DEFAULT_TERMINAL_FONT_SIZE,
       readonly modifier: PendingModifier;
     };
-interface TerminalMenuSession {
-  readonly terminalId: string;
-  readonly cwd: string | null;
-  readonly status: "starting" | "running" | "exited" | "error" | "closed";
-  readonly updatedAt: string | null;
-}
 function getTerminalStatusTone(input: {
   readonly status: TerminalMenuSession["status"];
   readonly hasRunningSubprocess?: boolean;
   return /^#[0-9a-f]{6}$/i.test(hexColor) ? `${hexColor}${alpha}` : hexColor;
 }
+function pickRunningTerminalSessionForBootstrap(
+  sessions: ReadonlyArray<KnownTerminalSession>,
+): KnownTerminalSession | null {
+  const running = sessions.filter(
+    (session) => session.state.status === "running" || session.state.status === "starting",
+  );
+  if (running.length === 0) {
+    return null;
+  }
+  return (
+    running.find((session) => session.target.terminalId === DEFAULT_TERMINAL_ID) ??
+    running[0] ??
+    null
+  );
+}
 export function ThreadTerminalRouteScreen() {
   const router = useRouter();
   const keyboard = useAnimatedKeyboard();
   const [fontSize, setFontSize] = useState(cachedFontSize ?? DEFAULT_TERMINAL_FONT_SIZE);
   const hasOpenedRef = useRef(false);
   const bufferReplayTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const attachStreamLogCountRef = useRef(0);
+  const firstNonEmptyBufferLoggedRef = useRef(false);
   const lastBufferReplayKeyRef = useRef<string | null>(null);
   const [readyBufferReplayKey, setReadyBufferReplayKey] = useState<string | null>(null);
   const [hasResolvedFontPreference, setHasResolvedFontPreference] = useState(
     cachedFontSize !== null,
   );
-  const [hasMeasuredSurface, setHasMeasuredSurface] = useState(cachedRouteGridSize !== null);
+  /** Default grid is always valid for attach; onResize refines cols/rows. Requiring a cached size blocked bootstrap for new terminal routes. */
+  const [hasMeasuredSurface, setHasMeasuredSurface] = useState(true);
   const [pendingModifierState, setPendingModifierState] = useState<{
     readonly terminalId: string;
     readonly value: PendingModifier | null;
     readyReplayKey: readyBufferReplayKey,
   });
   const isRunning = terminal.status === "running" || terminal.status === "starting";
+  useEffect(() => {
+    terminalDebugLog("surface:props", {
+      terminalKey,
+      atomBufferLen: terminal.buffer.length,
+      surfaceBufferLen: terminalSurfaceBuffer.length,
+      replayKey: bufferReplayKey,
+      readyReplayKey: readyBufferReplayKey,
+      status: terminal.status,
+      version: terminal.version,
+    });
+  }, [
+    bufferReplayKey,
+    readyBufferReplayKey,
+    terminal.buffer.length,
+    terminal.status,
+    terminal.version,
+    terminalKey,
+    terminalSurfaceBuffer.length,
+  ]);
+  useEffect(() => {
+    terminalDebugLog("session:status", {
+      terminalKey,
+      status: terminal.status,
+      error: terminal.error,
+      summary: terminal.summary?.cwd ?? null,
+      bufferLen: terminal.buffer.length,
+      version: terminal.version,
+    });
+  }, [
+    terminal.buffer.length,
+    terminal.error,
+    terminal.status,
+    terminal.summary?.cwd,
+    terminal.version,
+    terminalKey,
+  ]);
+  useEffect(() => {
+    if (terminal.buffer.length === 0 || firstNonEmptyBufferLoggedRef.current) {
+      return;
+    }
+    firstNonEmptyBufferLoggedRef.current = true;
+    terminalDebugLog("session:first-nonempty-buffer", {
+      terminalKey,
+      length: terminal.buffer.length,
+      preview: terminal.buffer.slice(0, 160),
+    });
+  }, [terminal.buffer, terminal.buffer.length, terminalKey]);
   const cwd = terminal.summary?.cwd ?? selectedThreadProject?.workspaceRoot ?? null;
   const hostPlatform = useMemo(
     () => inferHostPlatform(selectedEnvironmentConnection?.environmentLabel ?? null),
     [selectedEnvironmentConnection?.environmentLabel],
   );
   const runningSession = useMemo(
-    () =>
+    () => pickRunningTerminalSessionForBootstrap(knownSessions),
-      knownSessions.find(
-        (session) => session.state.status === "running" || session.state.status === "starting",
-      ) ?? null,
     [knownSessions],
   );
   const activeKnownSession = useMemo(
     () => knownSessions.find((session) => session.target.terminalId === terminalId) ?? null,
     [knownSessions, terminalId],
   );
+  const terminalAttachLaunchHintsRef = useRef({
+    terminalSummary: terminal.summary,
+    activeKnownSummary: activeKnownSession?.state.summary ?? null,
+  });
+  terminalAttachLaunchHintsRef.current = {
+    terminalSummary: terminal.summary,
+    activeKnownSummary: activeKnownSession?.state.summary ?? null,
+  };
   const terminalStatusTone = useMemo(
     () =>
       getTerminalStatusTone({
           cwd: cwd ?? null,
           status: terminal.status,
           hasRunningSubprocess: terminal.hasRunningSubprocess,
+          displayLabel: resolveTerminalSessionLabel(terminalId, terminal.summary),
           updatedAt: terminal.updatedAt,
         },
       }),
       knownSessions,
       selectedThreadProject?.workspaceRoot,
       terminal.hasRunningSubprocess,
+      terminal.summary,
       terminal.status,
       terminal.updatedAt,
       terminalId,
     ],
   );
+  const logAttachStreamEvent = useCallback((event: TerminalAttachStreamEvent) => {
+    const n = ++attachStreamLogCountRef.current;
+    if (event.type === "output" && n > 32 && n % 64 !== 0) {
+      return;
+    }
+    if (event.type === "snapshot") {
+      terminalDebugLog("attach:stream", {
+        n,
+        type: event.type,
+        status: event.snapshot.status,
+        historyLen: event.snapshot.history.length,
+        cwd: event.snapshot.cwd,
+      });
+      return;
+    }
+    if (event.type === "output") {
+      terminalDebugLog("attach:stream", { n, type: event.type, dataLen: event.data.length });
+      return;
+    }
+    terminalDebugLog("attach:stream", { n, type: event.type });
+  }, []);
   const attachTerminal = useCallback(() => {
     if (!selectedThread || !selectedThreadProject?.workspaceRoot) {
+      terminalDebugLog("attach:abort", { reason: "no-thread-or-workspace" });
       return null;
     }
     const client = getEnvironmentClient(selectedThread.environmentId);
     if (!client) {
+      terminalDebugLog("attach:abort", {
+        reason: "no-environment-client",
+        environmentId: selectedThread.environmentId,
+      });
       return null;
     }
             worktreePath: pendingLaunch.worktreePath,
           }
         : resolveTerminalOpenLocation({
-            terminalLocation: terminal.summary,
+            terminalLocation: terminalAttachLaunchHintsRef.current.terminalSummary,
-            activeSessionLocation: activeKnownSession?.state.summary ?? null,
+            activeSessionLocation: terminalAttachLaunchHintsRef.current.activeKnownSummary,
             workspaceRoot: selectedThreadProject.workspaceRoot,
             threadShellWorktreePath: selectedThread.worktreePath ?? null,
             threadDetailWorktreePath: selectedThreadDetail?.worktreePath ?? null,
           });
+      terminalDebugLog("attach:start", {
+        terminalId,
+        threadId: selectedThread.id,
+        cols: lastGridSize.cols,
+        rows: lastGridSize.rows,
+        cwd: launchLocation.cwd,
+        worktreePath: launchLocation.worktreePath,
+      });
       return attachTerminalSession({
         environmentId: selectedThread.environmentId,
         client,
           rows: lastGridSize.rows,
           env: pendingLaunch?.env,
         },
+        onEvent: logAttachStreamEvent,
         onSnapshot: () => {
           if (!pendingLaunch?.initialInput || initialInputSent) {
             return;
         },
       });
     } catch (error) {
+      terminalDebugLog("attach:error", {
+        message: error instanceof Error ? error.message : String(error),
+      });
       if (pendingLaunch) {
         stagePendingTerminalLaunch({
           target: pendingLaunchTarget,
   }, [
     lastGridSize.cols,
     lastGridSize.rows,
-    activeKnownSession?.state.summary,
+    logAttachStreamEvent,
     selectedThreadDetail?.worktreePath,
     selectedThread,
     selectedThreadProject?.workspaceRoot,
-    terminal.summary,
     terminalId,
   ]);
+  const attachTerminalRef = useRef(attachTerminal);
+  attachTerminalRef.current = attachTerminal;
+  const selectedThreadRef = useRef(selectedThread);
+  selectedThreadRef.current = selectedThread;
+  const selectedThreadProjectBootstrapRef = useRef(selectedThreadProject);
+  selectedThreadProjectBootstrapRef.current = selectedThreadProject;
+  const runningSessionRef = useRef(runningSession);
+  runningSessionRef.current = runningSession;
+  const terminalBootstrapRef = useRef({
+    status: terminal.status,
+    bufferLen: terminal.buffer.length,
+  });
+  terminalBootstrapRef.current = {
+    status: terminal.status,
+    bufferLen: terminal.buffer.length,
+  };
   useEffect(() => {
     hasOpenedRef.current = false;
+    attachStreamLogCountRef.current = 0;
+    firstNonEmptyBufferLoggedRef.current = false;
   }, [terminalKey]);
   const clearBufferReplayTimer = useCallback(() => {
   const scheduleBufferReplayReady = useCallback(() => {
     clearBufferReplayTimer();
     const replayKey = bufferReplayKey;
+    terminalDebugLog("replay:schedule-ready", {
+      replayKey,
+      delayMs: TERMINAL_BUFFER_REPLAY_STABILITY_DELAY_MS,
+    });
     bufferReplayTimerRef.current = setTimeout(() => {
       bufferReplayTimerRef.current = null;
       setReadyBufferReplayKey(replayKey);
+      terminalDebugLog("replay:ready", { replayKey });
     }, TERMINAL_BUFFER_REPLAY_STABILITY_DELAY_MS);
   }, [bufferReplayKey, clearBufferReplayTimer]);
         rows: DEFAULT_TERMINAL_ROWS,
       },
     );
-    setHasMeasuredSurface(
+    setHasMeasuredSurface(true);
-      getCachedTerminalGridSize({
-        environmentId: routeEnvironmentId,
-        threadId: routeThreadId,
-        terminalId,
-      }) !== null,
-    );
   }, [routeEnvironmentId, routeThreadId, terminalId]);
-  useEffect(() => {
-    setHasMeasuredSurface(
-      routeEnvironmentId !== null &&
-        routeThreadId !== null &&
-        getCachedTerminalGridSize({
-          environmentId: routeEnvironmentId,
-          threadId: routeThreadId,
-          terminalId,
-        }) !== null,
-    );
-  }, [fontSize, routeEnvironmentId, routeThreadId, terminalId]);
   useEffect(() => {
     let cancelled = false;
     });
   }, [fontSize, hasResolvedFontPreference]);
+  // Subscribes `terminal.attach` once per route+terminal until thread/env/attach args change.
+  // Use refs for `attachTerminal` / `selectedThread` / `runningSession`: their identities change when
+  // unrelated store updates (e.g. terminal buffer) re-render the parent, which was firing cleanup
+  // → detach immediately after the first snapshot.
   useEffect(() => {
     if (!hasResolvedFontPreference || !hasMeasuredSurface) {
       return;
     }
+    const thread = selectedThreadRef.current;
+    const project = selectedThreadProjectBootstrapRef.current;
+    const running = runningSessionRef.current;
+    const termSnap = terminalBootstrapRef.current;
     const bootstrapAction = resolveTerminalRouteBootstrap({
-      hasThread: selectedThread !== null,
+      hasThread: thread !== null,
-      hasWorkspaceRoot: Boolean(selectedThreadProject?.workspaceRoot),
+      hasWorkspaceRoot: Boolean(project?.workspaceRoot),
       hasOpened: hasOpenedRef.current,
       requestedTerminalId,
       currentTerminalId: terminalId,
-      runningTerminalId: runningSession?.target.terminalId ?? null,
+      runningTerminalId: running?.target.terminalId ?? null,
-      currentTerminalStatus: terminal.status,
+      currentTerminalStatus: termSnap.status,
-      hasCurrentTerminalHydration: terminal.summary !== null || terminal.buffer.length > 0,
+      // Metadata summary (cwd/status) is not scrollback. Only `terminal.attach` fills `buffer`;
+      // treating summary as "hydrated" skipped attach while status was running → empty surface.
+      hasCurrentTerminalHydration: termSnap.bufferLen > 0,
     });
-    if (bootstrapAction.kind === "idle" || !selectedThread) {
+    if (bootstrapAction.kind !== "idle") {
+      terminalDebugLog("bootstrap:action", {
+        kind: bootstrapAction.kind,
+        hasOpenedBefore: hasOpenedRef.current,
+        hasHydration: termSnap.bufferLen > 0,
+        terminalStatus: termSnap.status,
+        bufLen: termSnap.bufferLen,
+      });
+    }
+    if (bootstrapAction.kind === "idle" || !thread) {
       return;
     }
     if (bootstrapAction.kind === "redirect") {
-      router.replace(buildThreadTerminalRoutePath(selectedThread, bootstrapAction.terminalId));
+      router.replace(buildThreadTerminalNavigation(thread, bootstrapAction.terminalId));
       return;
     }
     hasOpenedRef.current = true;
     try {
-      return attachTerminal() ?? undefined;
+      const detach = attachTerminalRef.current();
-    } catch {
+      terminalDebugLog("bootstrap:subscribe", { hasDetach: Boolean(detach) });
+      if (!detach) {
+        hasOpenedRef.current = false;
+        return;
+      }
+      return () => {
+        detach();
+        hasOpenedRef.current = false;
+        terminalDebugLog("bootstrap:unsubscribe");
+      };
+    } catch (error) {
       hasOpenedRef.current = false;
+      terminalDebugLog("bootstrap:attach-threw", {
+        message: error instanceof Error ? error.message : String(error),
+      });
       return;
     }
   }, [
-    attachTerminal,
+    hasMeasuredSurface,
+    hasResolvedFontPreference,
     requestedTerminalId,
     router,
-    runningSession,
+    selectedThread?.environmentId,
-    selectedThread,
+    selectedThread?.id,
     selectedThreadProject?.workspaceRoot,
-    terminal.buffer.length,
-    terminal.summary,
-    terminal.status,
     terminalId,
-    hasMeasuredSurface,
-    hasResolvedFontPreference,
   ]);
   const writeInput = useCallback(
   const handleResize = useCallback(
     (size: { readonly cols: number; readonly rows: number }) => {
+      terminalDebugLog("native:onResize", {
+        cols: size.cols,
+        rows: size.rows,
+        terminalKey,
+      });
       setHasMeasuredSurface(true);
       if (readyBufferReplayKey !== bufferReplayKey) {
         scheduleBufferReplayReady();
       scheduleBufferReplayReady,
       selectedThread,
       terminalId,
+      terminalKey,
     ],
   );
         return;
       }
-      router.replace(buildThreadTerminalRoutePath(selectedThread, nextTerminalId));
+      router.replace(buildThreadTerminalNavigation(selectedThread, nextTerminalId));
     },
     [router, selectedThread, terminalId],
   );
     }
     router.replace(
-      buildThreadTerminalRoutePath(
+      buildThreadTerminalNavigation(
         selectedThread,
-        nextTerminalId(terminalMenuSessions.map((session) => session.terminalId)),
+        nextOpenTerminalId({
+          listedTerminalIds: terminalMenuSessions.map((session) => session.terminalId),
+          activeRouteTerminalId: terminalId,
+        }),
       ),
     );
-  }, [router, selectedThread, terminalMenuSessions]);
+  }, [router, selectedThread, terminalId, terminalMenuSessions]);
   const adjustFontSize = useCallback((delta: number) => {
     setTimeout(() => {
                 .filter(Boolean)
                 .join(" · ")}
             >
-              <Stack.Toolbar.Label>{getTerminalLabel(session.terminalId)}</Stack.Toolbar.Label>
+              <Stack.Toolbar.Label>{session.displayLabel}</Stack.Toolbar.Label>
             </Stack.Toolbar.MenuAction>
           ))}
           <Stack.Toolbar.MenuAction

apps/mobile/src/features/terminal/terminalBufferReplay.test.ts+2−2

@@ -12,7 +12,7 @@ describe("terminalBufferReplay", () => { · 11 unmodified lines
12	).toBe("env-1:thread-1:default:10");	12	).toBe("env-1:thread-1:default:10");
13	});	13	});
14		14
15	it("holds back terminal history until the measured surface is ready", () => {	15	it("shows terminal history while replay key is unset (initial mount / after key change)", () => {
16	const replayKey = getTerminalBufferReplayKey({	16	const replayKey = getTerminalBufferReplayKey({
17	terminalKey: "env-1:thread-1:default",	17	terminalKey: "env-1:thread-1:default",
18	fontSize: 10,	18	fontSize: 10,
@@ -24,7 +24,7 @@ describe("terminalBufferReplay", () => { · 5 unmodified lines
24	replayKey,	24	replayKey,
25	readyReplayKey: null,	25	readyReplayKey: null,
26	}),	26	}),
27	).toBe("");	27	).toBe("fastfetch output");
28	expect(	28	expect(
29	getTerminalSurfaceReplayBuffer({	29	getTerminalSurfaceReplayBuffer({
30	buffer: "fastfetch output",	30	buffer: "fastfetch output",

apps/mobile/src/features/terminal/terminalBufferReplay.ts+14−1

@@ -1,3 +1,5 @@
		1	import { terminalDebugLog } from "./terminalDebugLog";
		2
1	export const TERMINAL_BUFFER_REPLAY_STABILITY_DELAY_MS = 180;	3	export const TERMINAL_BUFFER_REPLAY_STABILITY_DELAY_MS = 180;
2		4
3	export function getTerminalBufferReplayKey(input: {	5	export function getTerminalBufferReplayKey(input: {
@@ -12,5 +14,16 @@ export function getTerminalSurfaceReplayBuffer(input: { · 8 unmodified lines
12	readonly replayKey: string;	14	readonly replayKey: string;
13	readonly readyReplayKey: string \| null;	15	readonly readyReplayKey: string \| null;
14	}): string {	16	}): string {
15	return input.readyReplayKey === input.replayKey ? input.buffer : "";	17	// Pass live buffer whenever ready key is unset or matches. Only return "" when ready key is
		18	// stale vs current replay key (e.g. mid font-size transition).
		19	if (input.readyReplayKey !== null && input.readyReplayKey !== input.replayKey) {
		20	terminalDebugLog("replay:stale-key-hiding-buffer", {
		21	replayKey: input.replayKey,
		22	readyReplayKey: input.readyReplayKey,
		23	bufferLen: input.buffer.length,
		24	});
		25	return "";
		26	}
		27
		28	return input.buffer;
16	}	29	}

apps/mobile/src/features/terminal/terminalDebugLog.ts+24−0

@@ -0,0 +1,24 @@
	1	/**
	2	* Debug logging for the mobile terminal pipeline. Prefix: `[t3-terminal]`.
	3	*
	4	* Enabled when `__DEV__` is true, or set `globalThis.__T3_TERMINAL_DEBUG__ = true` in a JS
	5	* debugger / Metro console to trace release/TestFlight builds.
	6	*/
	7	export function isTerminalDebugEnabled(): boolean {
	8	return (
	9	(typeof __DEV__ !== "undefined" && __DEV__) \|\|
	10	(typeof globalThis !== "undefined" &&
	11	(globalThis as { __T3_TERMINAL_DEBUG__?: boolean }).__T3_TERMINAL_DEBUG__ === true)
	12	);
	13	}
	14
	15	export function terminalDebugLog(message: string, data?: Record<string, unknown>): void {
	16	if (!isTerminalDebugEnabled()) {
	17	return;
	18	}
	19	if (data !== undefined) {
	20	console.log(`[t3-terminal] ${message}`, data);
	21	} else {
	22	console.log(`[t3-terminal] ${message}`);
	23	}
	24	}

apps/mobile/src/features/terminal/terminalMenu.test.ts+48−16

 import type { KnownTerminalSession } from "@t3tools/client-runtime";
 import { DEFAULT_TERMINAL_ID, EnvironmentId, ThreadId } from "@t3tools/contracts";
-import { buildTerminalMenuSessions, resolveProjectScriptTerminalId } from "./terminalMenu";
+import { getTerminalLabel } from "@t3tools/shared/terminalLabels";
+import {
+  buildTerminalMenuSessions,
+  nextOpenTerminalId,
+  nextTerminalId,
+  resolveProjectScriptTerminalId,
+} from "./terminalMenu";
 function makeKnownSession(input: {
   readonly terminalId: string;
             exitCode: null,
             exitSignal: null,
             hasRunningSubprocess: false,
+            label: getTerminalLabel(input.terminalId),
             updatedAt: input.updatedAt ?? "2026-04-15T20:00:00.000Z",
           }
         : null,
 }
 describe("buildTerminalMenuSessions", () => {
-  it("keeps the default shell and only includes running sessions by default", () => {
+  it("only lists server-known sessions that are running or starting (plus current)", () => {
     expect(
       buildTerminalMenuSessions({
         knownSessions: [
         workspaceRoot: "/workspace/root",
       }),
     ).toEqual([
-      {
-        terminalId: DEFAULT_TERMINAL_ID,
-        cwd: "/workspace/root",
-        status: "closed",
-        hasRunningSubprocess: false,
-        updatedAt: null,
-      },
       {
         terminalId: "term-3",
         cwd: "/workspace/feature",
         status: "running",
         hasRunningSubprocess: false,
+        displayLabel: "Terminal 3",
         updatedAt: "2026-04-15T20:05:00.000Z",
       },
     ]);
           cwd: "/workspace/exited",
           status: "exited",
           hasRunningSubprocess: false,
+          displayLabel: "Terminal 4",
           updatedAt: "2026-04-15T20:07:00.000Z",
         },
       }),
     ).toEqual([
-      {
-        terminalId: DEFAULT_TERMINAL_ID,
-        cwd: "/workspace/root",
-        status: "closed",
-        hasRunningSubprocess: false,
-        updatedAt: null,
-      },
       {
         terminalId: "term-4",
         cwd: "/workspace/exited",
         status: "exited",
         hasRunningSubprocess: false,
+        displayLabel: "Terminal 4",
         updatedAt: "2026-04-15T20:07:00.000Z",
       },
     ]);
   });
 });
+describe("nextTerminalId", () => {
+  it("uses the primary id when no terminals are listed yet", () => {
+    expect(nextTerminalId([])).toBe(DEFAULT_TERMINAL_ID);
+  });
+  it("allocates term-2 when only the primary shell exists", () => {
+    expect(nextTerminalId([DEFAULT_TERMINAL_ID])).toBe("term-2");
+  });
+});
+describe("nextOpenTerminalId", () => {
+  it("matches nextTerminalId when not on a terminal route", () => {
+    expect(nextOpenTerminalId({ listedTerminalIds: [] })).toBe(DEFAULT_TERMINAL_ID);
+    expect(nextOpenTerminalId({ listedTerminalIds: [DEFAULT_TERMINAL_ID] })).toBe("term-2");
+  });
+  it("avoids the mounted primary tab when the session list is still empty", () => {
+    expect(
+      nextOpenTerminalId({
+        listedTerminalIds: [],
+        activeRouteTerminalId: DEFAULT_TERMINAL_ID,
+      }),
+    ).toBe("term-2");
+  });
+  it("does not double-count when the route id is already listed", () => {
+    expect(
+      nextOpenTerminalId({
+        listedTerminalIds: [DEFAULT_TERMINAL_ID],
+        activeRouteTerminalId: DEFAULT_TERMINAL_ID,
+      }),
+    ).toBe("term-2");
+  });
+});
 describe("resolveProjectScriptTerminalId", () => {
   it("reuses the default shell when no terminal is running", () => {
     expect(

apps/mobile/src/features/terminal/terminalMenu.ts+28−39

 import type { KnownTerminalSession } from "@t3tools/client-runtime";
 import { DEFAULT_TERMINAL_ID, type ProjectScript } from "@t3tools/contracts";
+import { nextTerminalId, resolveTerminalSessionLabel } from "@t3tools/shared/terminalLabels";
+export {
+  getTerminalLabel,
+  nextTerminalId,
+  resolveTerminalSessionLabel,
+} from "@t3tools/shared/terminalLabels";
 export interface TerminalMenuSession {
   readonly terminalId: string;
   readonly cwd: string | null;
   readonly status: "starting" | "running" | "exited" | "error" | "closed";
   readonly hasRunningSubprocess: boolean;
+  /** Server-authoritative title with the same fallback rules as web. */
+  readonly displayLabel: string;
   readonly updatedAt: string | null;
 }
   return segments[segments.length - 1] ?? normalized;
 }
-export function getTerminalLabel(terminalId: string): string {
-  if (terminalId === DEFAULT_TERMINAL_ID) {
-    return "Main shell";
-  }
-  const numericSuffix = /^term(?:inal)?-(\d+)$/i.exec(terminalId)?.[1];
-  if (numericSuffix) {
-    return `Terminal ${numericSuffix}`;
-  }
-  return terminalId;
-}
 export function getTerminalStatusLabel(input: {
   readonly status: TerminalMenuSession["status"];
   readonly hasRunningSubprocess?: boolean;
   return "Not started";
 }
-export function nextTerminalId(existingTerminalIds: ReadonlyArray<string>): string {
+/**
-  const usedIds = new Set(existingTerminalIds);
+ * Picks an id for "open another shell". Counts the terminal screen already mounted
-  let nextIndex = 2;
+ * (`activeRouteTerminalId`) as occupied so an empty session list on the primary route
-  while (usedIds.has(`term-${nextIndex}`)) {
+ * still advances to `term-2` instead of `replace`-navigating to the same `default` tab.
-    nextIndex += 1;
+ */
+export function nextOpenTerminalId(input: {
+  readonly listedTerminalIds: ReadonlyArray<string>;
+  readonly activeRouteTerminalId?: string | null;
+}): string {
+  const listed = input.listedTerminalIds.filter((id) => id.trim().length > 0);
+  const routeId = input.activeRouteTerminalId?.trim() ? input.activeRouteTerminalId : null;
+  if (!routeId || listed.includes(routeId)) {
+    return nextTerminalId(listed);
   }
-  return `term-${nextIndex}`;
+  return nextTerminalId([...listed, routeId]);
 }
 export function buildTerminalMenuSessions(input: {
 }): ReadonlyArray<TerminalMenuSession> {
   const sessionsById = new Map<string, TerminalMenuSession>();
-  sessionsById.set(DEFAULT_TERMINAL_ID, {
-    terminalId: DEFAULT_TERMINAL_ID,
-    cwd: input.workspaceRoot,
-    status: "closed",
-    hasRunningSubprocess: false,
-    updatedAt: null,
-  });
   for (const session of input.knownSessions) {
     if (
       session.state.status !== "running" &&
       cwd: session.state.summary?.cwd ?? input.workspaceRoot,
       status: session.state.status,
       hasRunningSubprocess: session.state.hasRunningSubprocess,
+      displayLabel: resolveTerminalSessionLabel(session.target.terminalId, session.state.summary),
       updatedAt: session.state.updatedAt,
     });
   }
     sessionsById.set(input.currentSession.terminalId, input.currentSession);
   }
-  return Array.from(sessionsById.values()).sort((left, right) => {
+  return Array.from(sessionsById.values()).sort((left, right) =>
-    if (left.terminalId === DEFAULT_TERMINAL_ID) return -1;
+    left.terminalId.localeCompare(right.terminalId, undefined, { numeric: true }),
-    if (right.terminalId === DEFAULT_TERMINAL_ID) return 1;
+  );
-    const leftUpdatedAt = left.updatedAt ? Date.parse(left.updatedAt) : 0;
-    const rightUpdatedAt = right.updatedAt ? Date.parse(right.updatedAt) : 0;
-    if (leftUpdatedAt !== rightUpdatedAt) {
-      return rightUpdatedAt - leftUpdatedAt;
-    }
-    return left.terminalId.localeCompare(right.terminalId);
-  });
 }
 export function resolveProjectScriptTerminalId(input: {

apps/mobile/src/features/terminal/terminalRouteBootstrap.ts+1−0

@@ -6,6 +6,7 @@ export function resolveTerminalRouteBootstrap(input: { · 5 unmodified lines
6	readonly currentTerminalId: string;	6	readonly currentTerminalId: string;
7	readonly runningTerminalId: string \| null;	7	readonly runningTerminalId: string \| null;
8	readonly currentTerminalStatus: "starting" \| "running" \| "exited" \| "error" \| "closed";	8	readonly currentTerminalStatus: "starting" \| "running" \| "exited" \| "error" \| "closed";
		9	/** True once the attach stream has populated scrollback (`buffer` non-empty), not merely metadata. */
9	readonly hasCurrentTerminalHydration: boolean;	10	readonly hasCurrentTerminalHydration: boolean;
10	}):	11	}):
11	\| { readonly kind: "idle" }	12	\| { readonly kind: "idle" }

apps/mobile/src/features/threads/ThreadGitControls.tsx+32−39

 import { buildThreadReviewRoutePath } from "../../lib/routes";
 import {
   basename,
-  getTerminalLabel,
   getTerminalStatusLabel,
   projectScriptMenuIcon,
   projectScriptMenuLabel,
     <Stack.Toolbar placement="right">
       <Stack.Toolbar.Menu icon="terminal" disabled={!props.canOpenTerminal} separateBackground>
         {props.projectScripts.length > 0 ? (
-          <Stack.Toolbar.Menu icon="play" inline title="Project scripts">
+          props.projectScripts.map((script) => (
-            <Stack.Toolbar.Label>Project scripts</Stack.Toolbar.Label>
+            <Stack.Toolbar.MenuAction
-            {props.projectScripts.map((script) => (
+              key={script.id}
-              <Stack.Toolbar.MenuAction
+              icon={projectScriptMenuIcon(script.icon)}
-                key={script.id}
+              onPress={() => void props.onRunProjectScript(script)}
-                icon={projectScriptMenuIcon(script.icon)}
+              subtitle={script.command}
-                onPress={() => void props.onRunProjectScript(script)}
+            >
-                subtitle={script.command}
+              <Stack.Toolbar.Label>{projectScriptMenuLabel(script)}</Stack.Toolbar.Label>
-              >
+            </Stack.Toolbar.MenuAction>
-                <Stack.Toolbar.Label>{projectScriptMenuLabel(script)}</Stack.Toolbar.Label>
+          ))
-              </Stack.Toolbar.MenuAction>
-            ))}
-          </Stack.Toolbar.Menu>
         ) : (
           <Stack.Toolbar.MenuAction
             icon="play"
             <Stack.Toolbar.Label>No project scripts</Stack.Toolbar.Label>
           </Stack.Toolbar.MenuAction>
         )}
-        <Stack.Toolbar.Menu icon="terminal" inline title="Terminals">
+        {props.terminalSessions.map((session) => (
-          <Stack.Toolbar.Label>Terminals</Stack.Toolbar.Label>
-          {props.terminalSessions.map((session) => (
-            <Stack.Toolbar.MenuAction
-              key={session.terminalId}
-              icon="terminal"
-              onPress={() => props.onOpenTerminal(session.terminalId)}
-              subtitle={[
-                getTerminalStatusLabel({
-                  status: session.status,
-                  hasRunningSubprocess: session.hasRunningSubprocess,
-                }),
-                basename(session.cwd),
-              ]
-                .filter(Boolean)
-                .join(" · ")}
-            >
-              <Stack.Toolbar.Label>{getTerminalLabel(session.terminalId)}</Stack.Toolbar.Label>
-            </Stack.Toolbar.MenuAction>
-          ))}
           <Stack.Toolbar.MenuAction
-            icon="plus"
+            key={session.terminalId}
-            onPress={props.onOpenNewTerminal}
+            icon="terminal"
-            subtitle="Start another shell for this thread"
+            onPress={() => props.onOpenTerminal(session.terminalId)}
+            subtitle={[
+              getTerminalStatusLabel({
+                status: session.status,
+                hasRunningSubprocess: session.hasRunningSubprocess,
+              }),
+              basename(session.cwd),
+            ]
+              .filter(Boolean)
+              .join(" · ")}
           >
-            <Stack.Toolbar.Label>Open new terminal</Stack.Toolbar.Label>
+            <Stack.Toolbar.Label>{session.displayLabel}</Stack.Toolbar.Label>
           </Stack.Toolbar.MenuAction>
-        </Stack.Toolbar.Menu>
+        ))}
+        <Stack.Toolbar.MenuAction
+          icon="plus"
+          onPress={props.onOpenNewTerminal}
+          subtitle="Start another shell for this thread"
+        >
+          <Stack.Toolbar.Label>Open new terminal</Stack.Toolbar.Label>
+        </Stack.Toolbar.MenuAction>
       </Stack.Toolbar.Menu>
       <Stack.Toolbar.Menu icon="point.topleft.down.curvedto.point.bottomright.up">
         <Stack.Toolbar.MenuAction

apps/mobile/src/features/threads/ThreadRouteScreen.tsx+38−6

 import { EmptyState } from "../../components/EmptyState";
 import { LoadingScreen } from "../../components/LoadingScreen";
-import { buildThreadRoutePath, buildThreadTerminalRoutePath } from "../../lib/routes";
+import { buildThreadRoutePath, buildThreadTerminalNavigation } from "../../lib/routes";
 import { scopedThreadKey } from "../../lib/scopedEntities";
 import { connectionTone } from "../connection/connectionTone";
 import { GitActionProgressOverlay } from "./GitActionProgressOverlay";
 import {
   buildTerminalMenuSessions,
-  nextTerminalId,
+  nextOpenTerminalId,
   resolveProjectScriptTerminalId,
 } from "../terminal/terminalMenu";
 import {
   resolvePreferredThreadWorktreePath,
   stagePendingTerminalLaunch,
 } from "../terminal/terminalLaunchContext";
+import { terminalDebugLog } from "../terminal/terminalDebugLog";
 import { ThreadDetailScreen } from "./ThreadDetailScreen";
 import { ThreadGitControls } from "./ThreadGitControls";
 import { ThreadNavigationDrawer } from "./ThreadNavigationDrawer";
   const handleOpenTerminal = useCallback(
     (nextTerminalId?: string | null) => {
+      terminalDebugLog("terminal-menu:open-existing", {
+        terminalId: nextTerminalId ?? null,
+        hasThread: Boolean(selectedThread),
+        hasWorkspaceRoot: Boolean(selectedThreadProject?.workspaceRoot),
+      });
       if (!selectedThread || !selectedThreadProject?.workspaceRoot) {
         return;
       }
-      void router.push(buildThreadTerminalRoutePath(selectedThread, nextTerminalId));
+      void router.push(buildThreadTerminalNavigation(selectedThread, nextTerminalId));
     },
     [router, selectedThread, selectedThreadProject?.workspaceRoot],
   );
   const handleOpenNewTerminal = useCallback(() => {
+    terminalDebugLog("terminal-menu:open-new", {
+      hasThread: Boolean(selectedThread),
+      hasWorkspaceRoot: Boolean(selectedThreadProject?.workspaceRoot),
+      listedTerminalIds: terminalMenuSessions.map((session) => session.terminalId),
+    });
     if (!selectedThread || !selectedThreadProject?.workspaceRoot) {
       return;
     }
-    const nextId = nextTerminalId(terminalMenuSessions.map((session) => session.terminalId));
+    const nextId = nextOpenTerminalId({
-    void router.push(buildThreadTerminalRoutePath(selectedThread, nextId));
+      listedTerminalIds: terminalMenuSessions.map((session) => session.terminalId),
+    });
+    void router.push(buildThreadTerminalNavigation(selectedThread, nextId));
   }, [router, selectedThread, selectedThreadProject?.workspaceRoot, terminalMenuSessions]);
   const handleRunProjectScript = useCallback(
     async (script: ProjectScript) => {
+      terminalDebugLog("project-script:press", {
+        scriptId: script.id,
+        command: script.command,
+        hasThread: Boolean(selectedThread),
+        hasWorkspaceRoot: Boolean(selectedThreadProject?.workspaceRoot),
+      });
       if (!selectedThread || !selectedThreadProject?.workspaceRoot) {
+        terminalDebugLog("project-script:abort", {
+          scriptId: script.id,
+          reason: "no-thread-or-workspace",
+        });
         return;
       }
           initialInput: `${script.command}\r`,
         },
       });
+      terminalDebugLog("project-script:staged", {
+        scriptId: script.id,
+        terminalId: targetTerminalId,
+        cwd,
+        worktreePath: preferredWorktreePath,
+      });
-      void router.push(buildThreadTerminalRoutePath(selectedThread, targetTerminalId));
+      void router.push(buildThreadTerminalNavigation(selectedThread, targetTerminalId));
     },
     [
       router,

apps/mobile/src/lib/routes.ts+28−1

@@ -1,4 +1,4 @@
1	import type { Router } from "expo-router";	1	import type { Href, Router } from "expo-router";
2		2
3	import type { SelectedThreadRef } from "../state/remote-runtime-types";	3	import type { SelectedThreadRef } from "../state/remote-runtime-types";
4	import { EnvironmentScopedThreadShell } from "@t3tools/client-runtime";	4	import { EnvironmentScopedThreadShell } from "@t3tools/client-runtime";
@@ -41,6 +41,33 @@ export function buildThreadTerminalRoutePath( · 36 unmodified lines
41	return `${basePath}?terminalId=${encodeURIComponent(terminalId)}`;	41	return `${basePath}?terminalId=${encodeURIComponent(terminalId)}`;
42	}	42	}
43		43
		44	/**
		45	* Prefer this over {@link buildThreadTerminalRoutePath} with `router.push(string)` — Expo Router
		46	* often does not merge query strings into `useLocalSearchParams`, which breaks terminal bootstrap
		47	* (`requestedTerminalId` stays null while the UI assumes `default`).
		48	*/
		49	export function buildThreadTerminalNavigation(
		50	input: ThreadRouteInput \| PlainThreadRouteInput,
		51	terminalId?: string \| null,
		52	): Href {
		53	const environmentId = String(input.environmentId);
		54	const threadId = String("threadId" in input ? input.threadId : input.id);
		55
		56	const params: { environmentId: string; threadId: string; terminalId?: string } = {
		57	environmentId,
		58	threadId,
		59	};
		60
		61	if (terminalId != null && terminalId !== "") {
		62	params.terminalId = terminalId;
		63	}
		64
		65	return {
		66	pathname: "/threads/[environmentId]/[threadId]/terminal",
		67	params,
		68	};
		69	}
		70
44	export function dismissRoute(router: Router) {	71	export function dismissRoute(router: Router) {
45	if (router.canGoBack()) {	72	if (router.canGoBack()) {
46	router.back();	73	router.back();

apps/mobile/src/state/use-remote-environment-registry.ts+4−0

 import { pipe } from "effect/Function";
 import { Atom } from "effect/unstable/reactivity";
 import { type SavedRemoteConnection, bootstrapRemoteConnection } from "../lib/connection";
+import { terminalDebugLog } from "../features/terminal/terminalDebugLog";
 import { clearSavedConnection, loadSavedConnections, saveConnection } from "../lib/storage";
 import { appAtomRegistry } from "./atom-registry";
 import { type ConnectedEnvironmentSummary, type EnvironmentSession } from "./remote-runtime-types";
       client,
     }),
   );
+  terminalDebugLog("registry:terminal-metadata-subscribed", {
+    environmentId: connection.environmentId,
+  });
   notifyEnvironmentConnectionListeners();
   try {

apps/mobile/src/state/use-terminal-session.ts+3−0

 import type {
   EnvironmentId,
   TerminalAttachInput,
+  TerminalAttachStreamEvent,
   TerminalMetadataStreamEvent,
   TerminalSessionSnapshot,
 } from "@t3tools/contracts";
   readonly client: Parameters<typeof terminalSessionManager.attach>[0]["client"];
   readonly terminal: TerminalAttachInput;
   readonly onSnapshot?: (snapshot: TerminalSessionSnapshot) => void;
+  readonly onEvent?: (event: TerminalAttachStreamEvent) => void;
 }) {
   return terminalSessionManager.attach({
     environmentId: input.environmentId,
     client: input.client,
     terminal: input.terminal,
     ...(input.onSnapshot ? { onSnapshot: input.onSnapshot } : {}),
+    ...(input.onEvent ? { onEvent: input.onEvent } : {}),
   });
 }

apps/server/src/project/Layers/ProjectSetupScriptRunner.test.ts+1−0

@@ -91,6 +91,7 @@ describe("ProjectSetupScriptRunner", () => { · 90 unmodified lines
91	history: "",	91	history: "",
92	exitCode: null,	92	exitCode: null,
93	exitSignal: null,	93	exitSignal: null,
		94	label: "setup-setup",
94	updatedAt: "2026-01-01T00:00:00.000Z",	95	updatedAt: "2026-01-01T00:00:00.000Z",
95	}),	96	}),
96	);	97	);

apps/server/src/server.test.ts+1−0

@@ -3929,6 +3929,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => { · 3928 unmodified lines
3929	history: "",	3929	history: "",
3930	exitCode: null,	3930	exitCode: null,
3931	exitSignal: null,	3931	exitSignal: null,
		3932	label: "Primary",
3932	updatedAt: new Date().toISOString(),	3933	updatedAt: new Date().toISOString(),
3933	};	3934	};
3934		3935

apps/server/src/terminal/Layers/Manager.test.ts+29−13

   shellResolver?: () => string;
   platform?: NodeJS.Platform;
   env?: NodeJS.ProcessEnv;
-  subprocessChecker?: (terminalPid: number) => Effect.Effect<boolean>;
+  subprocessInspector?: (terminalPid: number) => Effect.Effect<{
+    readonly hasRunningSubprocess: boolean;
+    readonly childCommand: string | null;
+  }>;
   subprocessPollIntervalMs?: number;
   processKillGraceMs?: number;
   maxRetainedInactiveSessions?: number;
         ...(options.shellResolver !== undefined ? { shellResolver: options.shellResolver } : {}),
         ...(options.platform !== undefined ? { platform: options.platform } : {}),
         ...(options.env !== undefined ? { env: options.env } : {}),
-        ...(options.subprocessChecker !== undefined
+        ...(options.subprocessInspector !== undefined
-          ? { subprocessChecker: options.subprocessChecker }
+          ? { subprocessInspector: options.subprocessInspector }
           : {}),
         ...(options.subprocessPollIntervalMs !== undefined
           ? { subprocessPollIntervalMs: options.subprocessPollIntervalMs }
       const third = yield* manager.open(openInput());
       assert.equal(first.threadId, "thread-1");
-      assert.equal(first.terminalId, "default");
+      assert.equal(first.terminalId, DEFAULT_TERMINAL_ID);
       assert.equal(second.threadId, "thread-1");
       assert.equal(third.threadId, "thread-1");
       expect(ptyAdapter.spawnInputs).toHaveLength(1);
           (event) =>
             event.type === "cleared" &&
             event.threadId === "thread-1" &&
-            event.terminalId === "default",
+            event.terminalId === DEFAULT_TERMINAL_ID,
         ),
       ).toBe(true);
     }),
   it.effect("emits subprocess activity events when child-process state changes", () =>
     Effect.gen(function* () {
-      let hasRunningSubprocess = false;
+      let inspect: {
+        readonly hasRunningSubprocess: boolean;
+        readonly childCommand: string | null;
+      } = { hasRunningSubprocess: false, childCommand: null };
       const { manager, getEvents } = yield* createManager(5, {
-        subprocessChecker: () => Effect.succeed(hasRunningSubprocess),
+        subprocessInspector: () => Effect.succeed(inspect),
         subprocessPollIntervalMs: 20,
       });
       yield* manager.open(openInput());
       expect((yield* getEvents).some((event) => event.type === "activity")).toBe(false);
-      hasRunningSubprocess = true;
+      inspect = { hasRunningSubprocess: true, childCommand: "vim" };
       yield* waitFor(
         Effect.map(getEvents, (events) =>
-          events.some((event) => event.type === "activity" && event.hasRunningSubprocess === true),
+          events.some(
+            (event) =>
+              event.type === "activity" &&
+              event.hasRunningSubprocess === true &&
+              event.label === "vim",
+          ),
         ),
         "1200 millis",
       );
-      hasRunningSubprocess = false;
+      inspect = { hasRunningSubprocess: false, childCommand: null };
       yield* waitFor(
         Effect.map(getEvents, (events) =>
-          events.some((event) => event.type === "activity" && event.hasRunningSubprocess === false),
+          events.some(
+            (event) =>
+              event.type === "activity" &&
+              event.hasRunningSubprocess === false &&
+              event.label === "Terminal 1",
+          ),
         ),
         "1200 millis",
       );
     Effect.gen(function* () {
       let checks = 0;
       const { manager } = yield* createManager(5, {
-        subprocessChecker: () => {
+        subprocessInspector: () => {
           checks += 1;
-          return Effect.succeed(false);
+          return Effect.succeed({ hasRunningSubprocess: false, childCommand: null });
         },
         subprocessPollIntervalMs: 20,
       });

apps/server/src/terminal/Layers/Manager.ts+188−52

@@ -12,6 +12,7 @@ import { · 11 unmodified lines
12	type TerminalSummary,	12	type TerminalSummary,
13	} from "@t3tools/contracts";	13	} from "@t3tools/contracts";
14	import { makeKeyedCoalescingWorker } from "@t3tools/shared/KeyedCoalescingWorker";	14	import { makeKeyedCoalescingWorker } from "@t3tools/shared/KeyedCoalescingWorker";
		15	import { getTerminalLabel } from "@t3tools/shared/terminalLabels";
15	import {	16	import {
16	Effect,	17	Effect,
17	Encoding,	18	Encoding,
@@ -58,6 +59,7 @@ const DEFAULT_MAX_RETAINED_INACTIVE_SESSIONS = 128; · 40 unmodified lines
58	const DEFAULT_OPEN_COLS = 120;	59	const DEFAULT_OPEN_COLS = 120;
59	const DEFAULT_OPEN_ROWS = 30;	60	const DEFAULT_OPEN_ROWS = 30;
60	const TERMINAL_ENV_BLOCKLIST = new Set(["PORT", "ELECTRON_RENDERER_PORT", "ELECTRON_RUN_AS_NODE"]);	61	const TERMINAL_ENV_BLOCKLIST = new Set(["PORT", "ELECTRON_RENDERER_PORT", "ELECTRON_RUN_AS_NODE"]);
		62	const MAX_TERMINAL_LABEL_LENGTH = 128;
61		63
62	class TerminalSubprocessCheckError extends Schema.TaggedErrorClass<TerminalSubprocessCheckError>()(	64	class TerminalSubprocessCheckError extends Schema.TaggedErrorClass<TerminalSubprocessCheckError>()(
63	"TerminalSubprocessCheckError",	65	"TerminalSubprocessCheckError",
@@ -78,8 +80,15 @@ class TerminalProcessSignalError extends Schema.TaggedErrorClass<TerminalProcess · 14 unmodified lines
78	},	80	},
79	) {}	81	) {}
80		82
81	interface TerminalSubprocessChecker {	83	interface TerminalSubprocessInspectResult {
82	(terminalPid: number): Effect.Effect<boolean, TerminalSubprocessCheckError>;	84	readonly hasRunningSubprocess: boolean;
		85	readonly childCommand: string \| null;
		86	}
		87
		88	interface TerminalSubprocessInspector {
		89	(
		90	terminalPid: number,
		91	): Effect.Effect<TerminalSubprocessInspectResult, TerminalSubprocessCheckError>;
83	}	92	}
84		93
85	interface ShellCandidate {	94	interface ShellCandidate {
@@ -119,6 +128,8 @@ interface TerminalSessionState { · 33 unmodified lines
119	unsubscribeData: (() => void) \| null;	128	unsubscribeData: (() => void) \| null;
120	unsubscribeExit: (() => void) \| null;	129	unsubscribeExit: (() => void) \| null;
121	hasRunningSubprocess: boolean;	130	hasRunningSubprocess: boolean;
		131	/** Normalized child command name when `hasRunningSubprocess`; cleared when idle. */
		132	childCommandLabel: string \| null;
122	runtimeEnv: Record<string, string> \| null;	133	runtimeEnv: Record<string, string> \| null;
123	}	134	}
124		135
@@ -154,6 +165,38 @@ interface TerminalManagerState { · 29 unmodified lines
154	killFibers: Map<PtyProcess, Fiber.Fiber<void, never>>;	165	killFibers: Map<PtyProcess, Fiber.Fiber<void, never>>;
155	}	166	}
156		167
		168	function truncateTerminalWireLabel(value: string): string {
		169	if (value.length <= MAX_TERMINAL_LABEL_LENGTH) return value;
		170	return value.slice(0, MAX_TERMINAL_LABEL_LENGTH);
		171	}
		172
		173	function normalizeChildCommandName(raw: string, platform: NodeJS.Platform): string \| null {
		174	let trimmed = raw.trim();
		175	if (trimmed.length === 0) return null;
		176	if (
		177	(trimmed.startsWith("[") && trimmed.endsWith("]")) \|\|
		178	(trimmed.startsWith("(") && trimmed.endsWith(")"))
		179	) {
		180	trimmed = trimmed.slice(1, -1).trim();
		181	}
		182	const firstToken = (trimmed.split(/\s+/)[0] ?? trimmed).trim();
		183	if (firstToken.length === 0) return null;
		184	const base = platform === "win32" ? path.win32.basename(firstToken) : path.basename(firstToken);
		185	const withoutExe =
		186	platform === "win32" && base.toLowerCase().endsWith(".exe") ? base.slice(0, -4) : base;
		187	return withoutExe.length > 0 ? withoutExe : null;
		188	}
		189
		190	function terminalWireLabel(session: TerminalSessionState): string {
		191	if (session.hasRunningSubprocess && session.childCommandLabel) {
		192	const trimmed = session.childCommandLabel.trim();
		193	if (trimmed.length > 0) {
		194	return truncateTerminalWireLabel(trimmed);
		195	}
		196	}
		197	return truncateTerminalWireLabel(getTerminalLabel(session.terminalId));
		198	}
		199
157	function snapshot(session: TerminalSessionState): TerminalSessionSnapshot {	200	function snapshot(session: TerminalSessionState): TerminalSessionSnapshot {
158	return {	201	return {
159	threadId: session.threadId,	202	threadId: session.threadId,
@@ -165,6 +208,7 @@ function snapshot(session: TerminalSessionState): TerminalSessionSnapshot { · 5 unmodified lines
165	history: session.history,	208	history: session.history,
166	exitCode: session.exitCode,	209	exitCode: session.exitCode,
167	exitSignal: session.exitSignal,	210	exitSignal: session.exitSignal,
		211	label: terminalWireLabel(session),
168	updatedAt: session.updatedAt,	212	updatedAt: session.updatedAt,
169	sequence: session.eventSequence,	213	sequence: session.eventSequence,
170	};	214	};
@@ -181,6 +225,7 @@ function summary(session: TerminalSessionState): TerminalSummary { · 10 unmodified lines
181	exitCode: session.exitCode,	225	exitCode: session.exitCode,
182	exitSignal: session.exitSignal,	226	exitSignal: session.exitSignal,
183	hasRunningSubprocess: session.hasRunningSubprocess,	227	hasRunningSubprocess: session.hasRunningSubprocess,
		228	label: terminalWireLabel(session),
184	updatedAt: session.updatedAt,	229	updatedAt: session.updatedAt,
185	};	230	};
186	}	231	}
@@ -426,13 +471,25 @@ function isRetryableShellSpawnError(error: PtySpawnError): boolean { · 239 unmodified lines
426	);	471	);
427	}	472	}
428		473
429	function checkWindowsSubprocessActivity(	474	function parseFirstChildPidFromPgrep(stdout: string): number \| null {
		475	for (const line of stdout.split(/\r?\n/g)) {
		476	const n = Number.parseInt(line.trim(), 10);
		477	if (Number.isInteger(n) && n > 0) {
		478	return n;
		479	}
		480	}
		481	return null;
		482	}
		483
		484	function windowsInspectSubprocess(
430	terminalPid: number,	485	terminalPid: number,
431	): Effect.Effect<boolean, TerminalSubprocessCheckError> {	486	platform: NodeJS.Platform,
		487	): Effect.Effect<TerminalSubprocessInspectResult, TerminalSubprocessCheckError> {
432	const command = [	488	const command = [
433	`$children = Get-CimInstance Win32_Process -Filter "ParentProcessId = ${terminalPid}" -ErrorAction SilentlyContinue`,	489	`$c = Get-CimInstance Win32_Process -Filter "ParentProcessId = ${terminalPid}" -ErrorAction SilentlyContinue \| Select-Object -First 1`,
434	"if ($children) { exit 0 }",	490	"if ($null -eq $c) { exit 1 }",
435	"exit 1",	491	"Write-Output $c.Name",
		492	"exit 0",
436	].join("; ");	493	].join("; ");
437	return Effect.tryPromise({	494	return Effect.tryPromise({
438	try: () =>	495	try: () =>
@@ -444,17 +501,33 @@ function checkWindowsSubprocessActivity( · 5 unmodified lines
444	}),	501	}),
445	catch: (cause) =>	502	catch: (cause) =>
446	new TerminalSubprocessCheckError({	503	new TerminalSubprocessCheckError({
447	message: "Failed to check Windows terminal subprocess activity.",	504	message: "Failed to inspect Windows terminal subprocesses.",
448	cause,	505	cause,
449	terminalPid,	506	terminalPid,
450	command: "powershell",	507	command: "powershell",
451	}),	508	}),
452	}).pipe(Effect.map((result) => result.code === 0));	509	}).pipe(
		510	Effect.map((result) => {
		511	if (result.code !== 0) {
		512	return { hasRunningSubprocess: false, childCommand: null } as const;
		513	}
		514	const name = result.stdout.trim().split(/\r?\n/)[0]?.trim() ?? "";
		515	if (name.length === 0) {
		516	return { hasRunningSubprocess: true, childCommand: null } as const;
		517	}
		518	const normalized = normalizeChildCommandName(name, platform);
		519	return {
		520	hasRunningSubprocess: true,
		521	childCommand: normalized ? truncateTerminalWireLabel(normalized) : null,
		522	} as const;
		523	}),
		524	);
453	}	525	}
454		526
455	const checkPosixSubprocessActivity = Effect.fn("terminal.checkPosixSubprocessActivity")(function* (	527	const posixInspectSubprocess = Effect.fn("terminal.posixInspectSubprocess")(function* (
456	terminalPid: number,	528	terminalPid: number,
457	): Effect.fn.Return<boolean, TerminalSubprocessCheckError> {	529	platform: NodeJS.Platform,
		530	): Effect.fn.Return<TerminalSubprocessInspectResult, TerminalSubprocessCheckError> {
458	const runPgrep = Effect.tryPromise({	531	const runPgrep = Effect.tryPromise({
459	try: () =>	532	try: () =>
460	runProcess("pgrep", ["-P", String(terminalPid)], {	533	runProcess("pgrep", ["-P", String(terminalPid)], {
@@ -489,45 +562,94 @@ const checkPosixSubprocessActivity = Effect.fn("terminal.checkPosixSubprocessAct · 28 unmodified lines
489	}),	562	}),
490	});	563	});
491		564
		565	let childPid: number \| null = null;
		566
492	const pgrepResult = yield* Effect.exit(runPgrep);	567	const pgrepResult = yield* Effect.exit(runPgrep);
493	if (pgrepResult._tag === "Success") {	568	if (pgrepResult._tag === "Success") {
494	if (pgrepResult.value.code === 0) {	569	if (pgrepResult.value.code === 0) {
495	return pgrepResult.value.stdout.trim().length > 0;	570	childPid = parseFirstChildPidFromPgrep(pgrepResult.value.stdout);
496	}	571	} else if (pgrepResult.value.code === 1) {
497	if (pgrepResult.value.code === 1) {	572	return { hasRunningSubprocess: false, childCommand: null };
498	return false;
499	}	573	}
500	}	574	}
501		575
502	const psResult = yield* Effect.exit(runPs);	576	if (childPid === null) {
503	if (psResult._tag === "Failure" \|\| psResult.value.code !== 0) {	577	const psResult = yield* Effect.exit(runPs);
504	return false;	578	if (psResult._tag === "Failure" \|\| psResult.value.code !== 0) {
		579	return { hasRunningSubprocess: false, childCommand: null };
		580	}
		581	for (const line of psResult.value.stdout.split(/\r?\n/g)) {
		582	const [pidRaw, ppidRaw] = line.trim().split(/\s+/g);
		583	const pid = Number(pidRaw);
		584	const ppid = Number(ppidRaw);
		585	if (!Number.isInteger(pid) \|\| !Number.isInteger(ppid)) continue;
		586	if (ppid === terminalPid) {
		587	childPid = pid;
		588	break;
		589	}
		590	}
505	}	591	}
506		592
507	for (const line of psResult.value.stdout.split(/\r?\n/g)) {	593	if (childPid === null) {
508	const [pidRaw, ppidRaw] = line.trim().split(/\s+/g);	594	return { hasRunningSubprocess: false, childCommand: null };
509	const pid = Number(pidRaw);
510	const ppid = Number(ppidRaw);
511	if (!Number.isInteger(pid) \|\| !Number.isInteger(ppid)) continue;
512	if (ppid === terminalPid) {
513	return true;
514	}
515	}	595	}
516	return false;
517	});
518		596
519	const defaultSubprocessChecker = Effect.fn("terminal.defaultSubprocessChecker")(function* (	597	const runComm = Effect.tryPromise({
520	terminalPid: number,	598	try: () =>
521	): Effect.fn.Return<boolean, TerminalSubprocessCheckError> {	599	runProcess("ps", ["-p", String(childPid), "-o", "comm="], {
522	if (!Number.isInteger(terminalPid) \|\| terminalPid <= 0) {	600	timeoutMs: 1_000,
523	return false;	601	allowNonZeroExit: true,
		602	maxBufferBytes: 8_192,
		603	outputMode: "truncate",
		604	}),
		605	catch: () => null,
		606	});
		607
		608	const commResult = yield* Effect.exit(runComm);
		609	let rawComm: string \| null = null;
		610	if (commResult._tag === "Success" && commResult.value && commResult.value.code === 0) {
		611	rawComm = commResult.value.stdout.trim();
524	}	612	}
525	if (process.platform === "win32") {	613
526	return yield* checkWindowsSubprocessActivity(terminalPid);	614	if (!rawComm \|\| rawComm.length === 0) {
		615	const runArgs = Effect.tryPromise({
		616	try: () =>
		617	runProcess("ps", ["-p", String(childPid), "-o", "args="], {
		618	timeoutMs: 1_000,
		619	allowNonZeroExit: true,
		620	maxBufferBytes: 16_384,
		621	outputMode: "truncate",
		622	}),
		623	catch: () => null,
		624	});
		625	const argsResult = yield* Effect.exit(runArgs);
		626	if (argsResult._tag === "Success" && argsResult.value && argsResult.value.code === 0) {
		627	const first = argsResult.value.stdout.trim().split(/\s+/)[0] ?? "";
		628	rawComm = first.length > 0 ? first : null;
		629	}
527	}	630	}
528	return yield* checkPosixSubprocessActivity(terminalPid);	631
		632	const normalized = rawComm ? normalizeChildCommandName(rawComm, platform) : null;
		633	return {
		634	hasRunningSubprocess: true,
		635	childCommand: normalized ? truncateTerminalWireLabel(normalized) : null,
		636	};
529	});	637	});
530		638
		639	function defaultSubprocessInspectorForPlatform(
		640	platform: NodeJS.Platform,
		641	): TerminalSubprocessInspector {
		642	return Effect.fn("terminal.defaultSubprocessInspector")(function* (terminalPid: number) {
		643	if (!Number.isInteger(terminalPid) \|\| terminalPid <= 0) {
		644	return { hasRunningSubprocess: false, childCommand: null };
		645	}
		646	if (platform === "win32") {
		647	return yield* windowsInspectSubprocess(terminalPid, platform);
		648	}
		649	return yield* posixInspectSubprocess(terminalPid, platform);
		650	});
		651	}
		652
531	function capHistory(history: string, maxLines: number): string {	653	function capHistory(history: string, maxLines: number): string {
532	if (history.length === 0) return history;	654	if (history.length === 0) return history;
533	const hasTrailingNewline = history.endsWith("\n");	655	const hasTrailingNewline = history.endsWith("\n");
@@ -775,7 +897,7 @@ interface TerminalManagerOptions { · 241 unmodified lines
775	shellResolver?: () => string;	897	shellResolver?: () => string;
776	platform?: NodeJS.Platform;	898	platform?: NodeJS.Platform;
777	env?: NodeJS.ProcessEnv;	899	env?: NodeJS.ProcessEnv;
778	subprocessChecker?: TerminalSubprocessChecker;	900	subprocessInspector?: TerminalSubprocessInspector;
779	subprocessPollIntervalMs?: number;	901	subprocessPollIntervalMs?: number;
780	processKillGraceMs?: number;	902	processKillGraceMs?: number;
781	maxRetainedInactiveSessions?: number;	903	maxRetainedInactiveSessions?: number;
@@ -801,7 +923,8 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 19 unmodified lines
801	const platform = options.platform ?? process.platform;	923	const platform = options.platform ?? process.platform;
802	const baseEnv = options.env ?? process.env;	924	const baseEnv = options.env ?? process.env;
803	const shellResolver = options.shellResolver ?? (() => defaultShellResolver(platform, baseEnv));	925	const shellResolver = options.shellResolver ?? (() => defaultShellResolver(platform, baseEnv));
804	const subprocessChecker = options.subprocessChecker ?? defaultSubprocessChecker;	926	const subprocessInspector =
		927	options.subprocessInspector ?? defaultSubprocessInspectorForPlatform(platform);
805	const subprocessPollIntervalMs =	928	const subprocessPollIntervalMs =
806	options.subprocessPollIntervalMs ?? DEFAULT_SUBPROCESS_POLL_INTERVAL_MS;	929	options.subprocessPollIntervalMs ?? DEFAULT_SUBPROCESS_POLL_INTERVAL_MS;
807	const processKillGraceMs = options.processKillGraceMs ?? DEFAULT_PROCESS_KILL_GRACE_MS;	930	const processKillGraceMs = options.processKillGraceMs ?? DEFAULT_PROCESS_KILL_GRACE_MS;
@@ -1290,6 +1413,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 482 unmodified lines
1290	session.process = null;	1413	session.process = null;
1291	session.pid = null;	1414	session.pid = null;
1292	session.hasRunningSubprocess = false;	1415	session.hasRunningSubprocess = false;
		1416	session.childCommandLabel = null;
1293	session.status = "exited";	1417	session.status = "exited";
1294	session.pendingHistoryControlSequence = "";	1418	session.pendingHistoryControlSequence = "";
1295	session.pendingProcessEvents = [];	1419	session.pendingProcessEvents = [];
@@ -1358,6 +1482,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 62 unmodified lines
1358	session.process = null;	1482	session.process = null;
1359	session.pid = null;	1483	session.pid = null;
1360	session.hasRunningSubprocess = false;	1484	session.hasRunningSubprocess = false;
		1485	session.childCommandLabel = null;
1361	session.status = "exited";	1486	session.status = "exited";
1362	session.pendingHistoryControlSequence = "";	1487	session.pendingHistoryControlSequence = "";
1363	session.pendingProcessEvents = [];	1488	session.pendingProcessEvents = [];
@@ -1451,6 +1576,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 87 unmodified lines
1451	session.exitCode = null;	1576	session.exitCode = null;
1452	session.exitSignal = null;	1577	session.exitSignal = null;
1453	session.hasRunningSubprocess = false;	1578	session.hasRunningSubprocess = false;
		1579	session.childCommandLabel = null;
1454	session.pendingProcessEvents = [];	1580	session.pendingProcessEvents = [];
1455	session.pendingProcessEventIndex = 0;	1581	session.pendingProcessEventIndex = 0;
1456	session.processEventDrainRunning = false;	1582	session.processEventDrainRunning = false;
@@ -1528,6 +1654,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 71 unmodified lines
1528	session.unsubscribeData = null;	1654	session.unsubscribeData = null;
1529	session.unsubscribeExit = null;	1655	session.unsubscribeExit = null;
1530	session.hasRunningSubprocess = false;	1656	session.hasRunningSubprocess = false;
		1657	session.childCommandLabel = null;
1531	session.pendingProcessEvents = [];	1658	session.pendingProcessEvents = [];
1532	session.pendingProcessEventIndex = 0;	1659	session.pendingProcessEventIndex = 0;
1533	session.processEventDrainRunning = false;	1660	session.processEventDrainRunning = false;
@@ -1608,7 +1735,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 74 unmodified lines
1608	session: TerminalSessionState & { pid: number },	1735	session: TerminalSessionState & { pid: number },
1609	) {	1736	) {
1610	const terminalPid = session.pid;	1737	const terminalPid = session.pid;
1611	const hasRunningSubprocess = yield* subprocessChecker(terminalPid).pipe(	1738	const inspectResult = yield* subprocessInspector(terminalPid).pipe(
1612	Effect.map(Option.some),	1739	Effect.map(Option.some),
1613	Effect.catch((reason) =>	1740	Effect.catch((reason) =>
1614	Effect.logWarning("failed to check terminal subprocess activity", {	1741	Effect.logWarning("failed to check terminal subprocess activity", {
@@ -1616,14 +1743,17 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 1 unmodified line
1616	terminalId: session.terminalId,	1743	terminalId: session.terminalId,
1617	terminalPid,	1744	terminalPid,
1618	reason,	1745	reason,
1619	}).pipe(Effect.as(Option.none<boolean>())),	1746	}).pipe(Effect.as(Option.none<TerminalSubprocessInspectResult>())),
1620	),	1747	),
1621	);	1748	);
1622		1749
1623	if (Option.isNone(hasRunningSubprocess)) {	1750	if (Option.isNone(inspectResult)) {
1624	return;	1751	return;
1625	}	1752	}
1626		1753
		1754	const next = inspectResult.value;
		1755	const nextChildLabel = next.hasRunningSubprocess ? next.childCommand : null;
		1756
1627	const event = yield* modifyManagerState((state) => {	1757	const event = yield* modifyManagerState((state) => {
1628	const liveSession: Option.Option<TerminalSessionState> = Option.fromNullishOr(	1758	const liveSession: Option.Option<TerminalSessionState> = Option.fromNullishOr(
1629	state.sessions.get(toSessionKey(session.threadId, session.terminalId)),	1759	state.sessions.get(toSessionKey(session.threadId, session.terminalId)),
@@ -1632,12 +1762,14 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 2 unmodified lines
1632	Option.isNone(liveSession) \|\|	1762	Option.isNone(liveSession) \|\|
1633	liveSession.value.status !== "running" \|\|	1763	liveSession.value.status !== "running" \|\|
1634	liveSession.value.pid !== terminalPid \|\|	1764	liveSession.value.pid !== terminalPid \|\|
1635	liveSession.value.hasRunningSubprocess === hasRunningSubprocess.value	1765	(liveSession.value.hasRunningSubprocess === next.hasRunningSubprocess &&
		1766	liveSession.value.childCommandLabel === nextChildLabel)
1636	) {	1767	) {
1637	return [Option.none(), state] as const;	1768	return [Option.none(), state] as const;
1638	}	1769	}
1639		1770
1640	liveSession.value.hasRunningSubprocess = hasRunningSubprocess.value;	1771	liveSession.value.hasRunningSubprocess = next.hasRunningSubprocess;
		1772	liveSession.value.childCommandLabel = nextChildLabel;
1641	const eventStamp = advanceEventSequence(liveSession.value);	1773	const eventStamp = advanceEventSequence(liveSession.value);
1642		1774
1643	return [	1775	return [
@@ -1646,7 +1778,8 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 2 unmodified lines
1646	threadId: liveSession.value.threadId,	1778	threadId: liveSession.value.threadId,
1647	terminalId: liveSession.value.terminalId,	1779	terminalId: liveSession.value.terminalId,
1648	sequence: eventStamp.sequence,	1780	sequence: eventStamp.sequence,
1649	hasRunningSubprocess: hasRunningSubprocess.value,	1781	hasRunningSubprocess: next.hasRunningSubprocess,
		1782	label: terminalWireLabel(liveSession.value),
1650	}),	1783	}),
1651	state,	1784	state,
1652	] as const;	1785	] as const;
@@ -1711,7 +1844,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 58 unmodified lines
1711	);	1844	);
1712		1845
1713	const openLocked = Effect.fn("terminal.openLocked")(function* (input: TerminalOpenInput) {	1846	const openLocked = Effect.fn("terminal.openLocked")(function* (input: TerminalOpenInput) {
1714	const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;	1847	const terminalId = input.terminalId;
1715	yield* assertValidCwd(input.cwd);	1848	yield* assertValidCwd(input.cwd);
1716		1849
1717	const sessionKey = toSessionKey(input.threadId, terminalId);	1850	const sessionKey = toSessionKey(input.threadId, terminalId);
@@ -1743,6 +1876,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 25 unmodified lines
1743	unsubscribeData: null,	1876	unsubscribeData: null,
1744	unsubscribeExit: null,	1877	unsubscribeExit: null,
1745	hasRunningSubprocess: false,	1878	hasRunningSubprocess: false,
		1879	childCommandLabel: null,
1746	runtimeEnv: normalizedRuntimeEnv(input.env),	1880	runtimeEnv: normalizedRuntimeEnv(input.env),
1747	};	1881	};
1748		1882
@@ -1839,7 +1973,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 90 unmodified lines
1839	withThreadLock(	1973	withThreadLock(
1840	input.threadId,	1974	input.threadId,
1841	Effect.gen(function* () {	1975	Effect.gen(function* () {
1842	const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;	1976	const terminalId = input.terminalId;
1843	const existing = yield* getSession(input.threadId, terminalId);	1977	const existing = yield* getSession(input.threadId, terminalId);
1844		1978
1845	if (Option.isNone(existing)) {	1979	if (Option.isNone(existing)) {
@@ -1918,10 +2052,12 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 72 unmodified lines
1918	let unsubscribe: (() => void) \| null = null;	2052	let unsubscribe: (() => void) \| null = null;
1919		2053
1920	return Effect.gen(function* () {	2054	return Effect.gen(function* () {
1921	const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;
1922	const bufferedEvents: TerminalEvent[] = [];	2055	const bufferedEvents: TerminalEvent[] = [];
1923	let deliverLive = false;	2056	let deliverLive = false;
1924		2057
		2058	const initialSnapshot = yield* openOrAttachForStream(input);
		2059	const terminalId = initialSnapshot.terminalId;
		2060
1925	unsubscribe = yield* subscribe((event) => {	2061	unsubscribe = yield* subscribe((event) => {
1926	if (event.threadId !== input.threadId \|\| event.terminalId !== terminalId) {	2062	if (event.threadId !== input.threadId \|\| event.terminalId !== terminalId) {
1927	return Effect.void;	2063	return Effect.void;
@@ -1936,7 +2072,6 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 8 unmodified lines
1936	return attachEvent ? listener(attachEvent) : Effect.void;	2072	return attachEvent ? listener(attachEvent) : Effect.void;
1937	});	2073	});
1938		2074
1939	const initialSnapshot = yield* openOrAttachForStream(input);
1940	yield* listener({	2075	yield* listener({
1941	type: "snapshot",	2076	type: "snapshot",
1942	snapshot: initialSnapshot,	2077	snapshot: initialSnapshot,
@@ -2044,7 +2179,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 101 unmodified lines
2044	};	2179	};
2045		2180
2046	const write: TerminalManagerShape["write"] = Effect.fn("terminal.write")(function* (input) {	2181	const write: TerminalManagerShape["write"] = Effect.fn("terminal.write")(function* (input) {
2047	const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;	2182	const terminalId = input.terminalId;
2048	const session = yield* requireSession(input.threadId, terminalId);	2183	const session = yield* requireSession(input.threadId, terminalId);
2049	const process = session.process;	2184	const process = session.process;
2050	if (!process \|\| session.status !== "running") {	2185	if (!process \|\| session.status !== "running") {
@@ -2058,7 +2193,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 7 unmodified lines
2058	});	2193	});
2059		2194
2060	const resize: TerminalManagerShape["resize"] = Effect.fn("terminal.resize")(function* (input) {	2195	const resize: TerminalManagerShape["resize"] = Effect.fn("terminal.resize")(function* (input) {
2061	const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;	2196	const terminalId = input.terminalId;
2062	const session = yield* requireSession(input.threadId, terminalId);	2197	const session = yield* requireSession(input.threadId, terminalId);
2063	const process = session.process;	2198	const process = session.process;
2064	if (!process \|\| session.status !== "running") {	2199	if (!process \|\| session.status !== "running") {
@@ -2077,7 +2212,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 12 unmodified lines
2077	withThreadLock(	2212	withThreadLock(
2078	input.threadId,	2213	input.threadId,
2079	Effect.gen(function* () {	2214	Effect.gen(function* () {
2080	const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;	2215	const terminalId = input.terminalId;
2081	const session = yield* requireSession(input.threadId, terminalId);	2216	const session = yield* requireSession(input.threadId, terminalId);
2082	session.history = "";	2217	session.history = "";
2083	session.pendingHistoryControlSequence = "";	2218	session.pendingHistoryControlSequence = "";
@@ -2100,7 +2235,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 16 unmodified lines
2100	input.threadId,	2235	input.threadId,
2101	Effect.gen(function* () {	2236	Effect.gen(function* () {
2102	yield* increment(terminalRestartsTotal, { scope: "thread" });	2237	yield* increment(terminalRestartsTotal, { scope: "thread" });
2103	const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;	2238	const terminalId = input.terminalId;
2104	yield* assertValidCwd(input.cwd);	2239	yield* assertValidCwd(input.cwd);
2105		2240
2106	const sessionKey = toSessionKey(input.threadId, terminalId);	2241	const sessionKey = toSessionKey(input.threadId, terminalId);
@@ -2131,6 +2266,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith · 24 unmodified lines
2131	unsubscribeData: null,	2266	unsubscribeData: null,
2132	unsubscribeExit: null,	2267	unsubscribeExit: null,
2133	hasRunningSubprocess: false,	2268	hasRunningSubprocess: false,
		2269	childCommandLabel: null,
2134	runtimeEnv: normalizedRuntimeEnv(input.env),	2270	runtimeEnv: normalizedRuntimeEnv(input.env),
2135	};	2271	};
2136	const createdSession = session;	2272	const createdSession = session;

apps/web/src/components/ChatView.browser.tsx+22−0

@@ -993,6 +993,7 @@ function resolveWsRpc(body: NormalizedWsRpcRequestBody): unknown { · 992 unmodified lines
993	history: "",	993	history: "",
994	exitCode: null,	994	exitCode: null,
995	exitSignal: null,	995	exitSignal: null,
		996	label: "Terminal 1",
996	updatedAt: NOW_ISO,	997	updatedAt: NOW_ISO,
997	};	998	};
998	}	999	}
@@ -1767,6 +1768,26 @@ describe("ChatView timeline estimator parity (full app)", () => { · 768 unmodified lines
1767	const mounted = await mountChatView({	1768	const mounted = await mountChatView({
1768	viewport: DEFAULT_VIEWPORT,	1769	viewport: DEFAULT_VIEWPORT,
1769	snapshot,	1770	snapshot,
		1771	configureFixture: (nextFixture) => {
		1772	nextFixture.terminalMetadataEvents = [
		1773	{
		1774	type: "upsert",
		1775	terminal: {
		1776	threadId: THREAD_ID,
		1777	terminalId: DEFAULT_TERMINAL_ID,
		1778	cwd: "/repo/project",
		1779	worktreePath: null,
		1780	status: "running",
		1781	pid: 123,
		1782	exitCode: null,
		1783	exitSignal: null,
		1784	hasRunningSubprocess: false,
		1785	label: "Terminal 1",
		1786	updatedAt: isoAt(0),
		1787	},
		1788	},
		1789	];
		1790	},
1770	});	1791	});
1771		1792
1772	try {	1793	try {
@@ -3550,6 +3571,7 @@ describe("ChatView timeline estimator parity (full app)", () => { · 1777 unmodified lines
3550	exitCode: null,	3571	exitCode: null,
3551	exitSignal: null,	3572	exitSignal: null,
3552	hasRunningSubprocess: true,	3573	hasRunningSubprocess: true,
		3574	label: "Terminal 1",
3553	updatedAt: isoAt(1_200),	3575	updatedAt: isoAt(1_200),
3554	},	3576	},
3555	},	3577	},

apps/web/src/components/ChatView.tsx+267−35

@@ -29,6 +29,7 @@ import { · 28 unmodified lines
29	import { applyClaudePromptEffortPrefix, createModelSelection } from "@t3tools/shared/model";	29	import { applyClaudePromptEffortPrefix, createModelSelection } from "@t3tools/shared/model";
30	import { projectScriptCwd, projectScriptRuntimeEnv } from "@t3tools/shared/projectScripts";	30	import { projectScriptCwd, projectScriptRuntimeEnv } from "@t3tools/shared/projectScripts";
31	import { truncate } from "@t3tools/shared/String";	31	import { truncate } from "@t3tools/shared/String";
		32	import { nextTerminalId, resolveTerminalSessionLabel } from "@t3tools/shared/terminalLabels";
32	import { Debouncer } from "@tanstack/react-pacer";	33	import { Debouncer } from "@tanstack/react-pacer";
33	import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";	34	import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
34	import { useNavigate, useSearch } from "@tanstack/react-router";	35	import { useNavigate, useSearch } from "@tanstack/react-router";
@@ -100,7 +101,7 @@ import { resolveShortcutCommand, shortcutLabelForCommand } from "../keybindings" · 65 unmodified lines
100	import PlanSidebar from "./PlanSidebar";	101	import PlanSidebar from "./PlanSidebar";
101	import ThreadTerminalDrawer from "./ThreadTerminalDrawer";	102	import ThreadTerminalDrawer from "./ThreadTerminalDrawer";
102	import { ChevronDownIcon } from "lucide-react";	103	import { ChevronDownIcon } from "lucide-react";
103	import { cn, randomUUID } from "~/lib/utils";	104	import { cn } from "~/lib/utils";
104	import { toastManager } from "./ui/toast";	105	import { toastManager } from "./ui/toast";
105	import { decodeProjectScriptKeybindingRule } from "~/lib/projectScriptKeybindings";	106	import { decodeProjectScriptKeybindingRule } from "~/lib/projectScriptKeybindings";
106	import { type NewProjectScriptInput } from "./ProjectScriptsControl";	107	import { type NewProjectScriptInput } from "./ProjectScriptsControl";
@@ -133,7 +134,7 @@ import { · 26 unmodified lines
133	type TerminalContextSelection,	134	type TerminalContextSelection,
134	} from "../lib/terminalContext";	135	} from "../lib/terminalContext";
135	import { selectThreadTerminalUiState, useTerminalUiStateStore } from "../terminalUiStateStore";	136	import { selectThreadTerminalUiState, useTerminalUiStateStore } from "../terminalUiStateStore";
136	import { useThreadRunningTerminalIds } from "../terminalSessionState";	137	import { useKnownTerminalSessions, useThreadRunningTerminalIds } from "../terminalSessionState";
137	import { ChatComposer, type ChatComposerHandle } from "./chat/ChatComposer";	138	import { ChatComposer, type ChatComposerHandle } from "./chat/ChatComposer";
138	import { ExpandedImageDialog } from "./chat/ExpandedImageDialog";	139	import { ExpandedImageDialog } from "./chat/ExpandedImageDialog";
139	import { PullRequestThreadDialog } from "./PullRequestThreadDialog";	140	import { PullRequestThreadDialog } from "./PullRequestThreadDialog";
@@ -408,6 +409,45 @@ function useLocalDispatchState(input: { · 268 unmodified lines
408	};	409	};
409	}	410	}
410		411
		412	/** Same terminal ids (order ignored) — avoids reconcile when only server session ordering differs. */
		413	function terminalIdListsEqual(left: readonly string[], right: readonly string[]): boolean {
		414	if (left.length !== right.length) {
		415	return false;
		416	}
		417	if (left.length === 0) {
		418	return true;
		419	}
		420	const sortedLeft = [...left].sort((a, b) => a.localeCompare(b));
		421	const sortedRight = [...right].sort((a, b) => a.localeCompare(b));
		422	for (let index = 0; index < sortedLeft.length; index += 1) {
		423	if (sortedLeft[index] !== sortedRight[index]) {
		424	return false;
		425	}
		426	}
		427	return true;
		428	}
		429
		430	/**
		431	* Server knows about fewer sessions than the client, but every server id still exists locally.
		432	* Typical right after `terminal.open`: known-session list lags; reconciling would drop the new id
		433	* and later re-add it as a separate group (no split layout).
		434	*/
		435	function serverTerminalIdsStrictSubsetOfClient(
		436	serverIds: readonly string[],
		437	clientIds: readonly string[],
		438	): boolean {
		439	if (serverIds.length >= clientIds.length \|\| clientIds.length === 0) {
		440	return false;
		441	}
		442	const clientSet = new Set(clientIds);
		443	for (const id of serverIds) {
		444	if (!clientSet.has(id)) {
		445	return false;
		446	}
		447	}
		448	return true;
		449	}
		450
411	interface PersistentThreadTerminalDrawerProps {	451	interface PersistentThreadTerminalDrawerProps {
412	threadRef: { environmentId: EnvironmentId; threadId: ThreadId };	452	threadRef: { environmentId: EnvironmentId; threadId: ThreadId };
413	threadId: ThreadId;	453	threadId: ThreadId;
@@ -444,11 +484,42 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra · 30 unmodified lines
444	const terminalUiState = useTerminalUiStateStore((state) =>	484	const terminalUiState = useTerminalUiStateStore((state) =>
445	selectThreadTerminalUiState(state.terminalUiStateByThreadKey, threadRef),	485	selectThreadTerminalUiState(state.terminalUiStateByThreadKey, threadRef),
446	);	486	);
		487	const knownTerminalSessions = useKnownTerminalSessions({
		488	environmentId: threadRef.environmentId,
		489	threadId,
		490	});
		491	const terminalLabelsById = useMemo(() => {
		492	const next = new Map<string, string>();
		493	for (const session of knownTerminalSessions) {
		494	next.set(
		495	session.target.terminalId,
		496	resolveTerminalSessionLabel(session.target.terminalId, session.state.summary),
		497	);
		498	}
		499	return next;
		500	}, [knownTerminalSessions]);
		501	const serverOrderedTerminalIds = useMemo(
		502	() => knownTerminalSessions.map((session) => session.target.terminalId),
		503	[knownTerminalSessions],
		504	);
447	const storeSetTerminalHeight = useTerminalUiStateStore((state) => state.setTerminalHeight);	505	const storeSetTerminalHeight = useTerminalUiStateStore((state) => state.setTerminalHeight);
448	const storeSplitTerminal = useTerminalUiStateStore((state) => state.splitTerminal);	506	const storeSplitTerminal = useTerminalUiStateStore((state) => state.splitTerminal);
449	const storeNewTerminal = useTerminalUiStateStore((state) => state.newTerminal);	507	const storeNewTerminal = useTerminalUiStateStore((state) => state.newTerminal);
450	const storeSetActiveTerminal = useTerminalUiStateStore((state) => state.setActiveTerminal);	508	const storeSetActiveTerminal = useTerminalUiStateStore((state) => state.setActiveTerminal);
451	const storeCloseTerminal = useTerminalUiStateStore((state) => state.closeTerminal);	509	const storeCloseTerminal = useTerminalUiStateStore((state) => state.closeTerminal);
		510	const reconcileTerminalIds = useTerminalUiStateStore((state) => state.reconcileTerminalIds);
		511
		512	useEffect(() => {
		513	if (terminalIdListsEqual(serverOrderedTerminalIds, terminalUiState.terminalIds)) {
		514	return;
		515	}
		516	if (
		517	serverTerminalIdsStrictSubsetOfClient(serverOrderedTerminalIds, terminalUiState.terminalIds)
		518	) {
		519	return;
		520	}
		521	reconcileTerminalIds(threadRef, serverOrderedTerminalIds);
		522	}, [reconcileTerminalIds, serverOrderedTerminalIds, terminalUiState.terminalIds, threadRef]);
452	const [localFocusRequestId, setLocalFocusRequestId] = useState(0);	523	const [localFocusRequestId, setLocalFocusRequestId] = useState(0);
453	const worktreePath = serverThread?.worktreePath ?? draftThread?.worktreePath ?? null;	524	const worktreePath = serverThread?.worktreePath ?? draftThread?.worktreePath ?? null;
454	const effectiveWorktreePath = useMemo(() => {	525	const effectiveWorktreePath = useMemo(() => {
@@ -494,14 +565,68 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra · 39 unmodified lines
494	);	565	);
495		566
496	const splitTerminal = useCallback(() => {	567	const splitTerminal = useCallback(() => {
497	storeSplitTerminal(threadRef, `terminal-${randomUUID()}`);	568	const api = readEnvironmentApi(threadRef.environmentId);
		569	if (!api \|\| !cwd) {
		570	return;
		571	}
		572	const terminalId = nextTerminalId(serverOrderedTerminalIds);
		573	storeSplitTerminal(threadRef, terminalId);
498	bumpFocusRequestId();	574	bumpFocusRequestId();
499	}, [bumpFocusRequestId, storeSplitTerminal, threadRef]);	575	void (async () => {
		576	try {
		577	await api.terminal.open({
		578	threadId,
		579	terminalId,
		580	cwd,
		581	...(effectiveWorktreePath != null ? { worktreePath: effectiveWorktreePath } : {}),
		582	env: runtimeEnv,
		583	});
		584	} catch {
		585	// Opening failed; the tab is already in the store — user can retry or close it.
		586	}
		587	})();
		588	}, [
		589	bumpFocusRequestId,
		590	cwd,
		591	effectiveWorktreePath,
		592	runtimeEnv,
		593	serverOrderedTerminalIds,
		594	storeSplitTerminal,
		595	threadId,
		596	threadRef,
		597	]);
500		598
501	const createNewTerminal = useCallback(() => {	599	const createNewTerminal = useCallback(() => {
502	storeNewTerminal(threadRef, `terminal-${randomUUID()}`);	600	const api = readEnvironmentApi(threadRef.environmentId);
		601	if (!api \|\| !cwd) {
		602	return;
		603	}
		604	const terminalId = nextTerminalId(serverOrderedTerminalIds);
		605	storeNewTerminal(threadRef, terminalId);
503	bumpFocusRequestId();	606	bumpFocusRequestId();
504	}, [bumpFocusRequestId, storeNewTerminal, threadRef]);	607	void (async () => {
		608	try {
		609	await api.terminal.open({
		610	threadId,
		611	terminalId,
		612	cwd,
		613	...(effectiveWorktreePath != null ? { worktreePath: effectiveWorktreePath } : {}),
		614	env: runtimeEnv,
		615	});
		616	} catch {
		617	// Opening failed; the tab is already in the store — user can retry or close it.
		618	}
		619	})();
		620	}, [
		621	bumpFocusRequestId,
		622	cwd,
		623	effectiveWorktreePath,
		624	runtimeEnv,
		625	serverOrderedTerminalIds,
		626	storeNewTerminal,
		627	threadId,
		628	threadRef,
		629	]);
505		630
506	const activateTerminal = useCallback(	631	const activateTerminal = useCallback(
507	(terminalId: string) => {	632	(terminalId: string) => {
@@ -537,13 +662,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra · 29 unmodified lines
537	storeCloseTerminal(threadRef, terminalId);	662	storeCloseTerminal(threadRef, terminalId);
538	bumpFocusRequestId();	663	bumpFocusRequestId();
539	},	664	},
540	[	665	[bumpFocusRequestId, storeCloseTerminal, terminalUiState.terminalIds, threadId, threadRef],
541	bumpFocusRequestId,
542	storeCloseTerminal,
543	terminalUiState.terminalIds.length,
544	threadId,
545	threadRef,
546	],
547	);	666	);
548		667
549	const handleAddTerminalContext = useCallback(	668	const handleAddTerminalContext = useCallback(
@@ -570,6 +689,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra · 20 unmodified lines
570	runtimeEnv={runtimeEnv}	689	runtimeEnv={runtimeEnv}
571	visible={visible}	690	visible={visible}
572	height={terminalUiState.terminalHeight}	691	height={terminalUiState.terminalHeight}
		692	// Known-session order is MRU and changes on focus; persisted store order keeps sidebar labels stable.
573	terminalIds={terminalUiState.terminalIds}	693	terminalIds={terminalUiState.terminalIds}
574	activeTerminalId={terminalUiState.activeTerminalId}	694	activeTerminalId={terminalUiState.activeTerminalId}
575	terminalGroups={terminalUiState.terminalGroups}	695	terminalGroups={terminalUiState.terminalGroups}
@@ -585,6 +705,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra · 9 unmodified lines
585	onCloseTerminal={closeTerminal}	705	onCloseTerminal={closeTerminal}
586	onHeightChange={setTerminalHeight}	706	onHeightChange={setTerminalHeight}
587	onAddTerminalContext={handleAddTerminalContext}	707	onAddTerminalContext={handleAddTerminalContext}
		708	terminalLabelsById={terminalLabelsById}
588	/>	709	/>
589	</div>	710	</div>
590	);	711	);
@@ -797,11 +918,52 @@ export default function ChatView(props: ChatViewProps) { · 206 unmodified lines
797	environmentId: activeThread?.environmentId ?? null,	918	environmentId: activeThread?.environmentId ?? null,
798	threadId: activeThreadId,	919	threadId: activeThreadId,
799	});	920	});
		921	const activeThreadKnownSessionsRaw = useKnownTerminalSessions({
		922	environmentId: activeThread?.environmentId ?? null,
		923	threadId: activeThreadId,
		924	});
		925	const activeThreadKnownSessions = useMemo(() => {
		926	if (activeThreadId === null) {
		927	return [];
		928	}
		929	return activeThreadKnownSessionsRaw.filter(
		930	(session) => session.target.threadId === activeThreadId,
		931	);
		932	}, [activeThreadId, activeThreadKnownSessionsRaw]);
		933	const activeServerOrderedTerminalIds = useMemo(
		934	() => activeThreadKnownSessions.map((session) => session.target.terminalId),
		935	[activeThreadKnownSessions],
		936	);
		937	const reconcileTerminalIds = useTerminalUiStateStore((state) => state.reconcileTerminalIds);
800	const activeThreadRef = useMemo(	938	const activeThreadRef = useMemo(
801	() => (activeThread ? scopeThreadRef(activeThread.environmentId, activeThread.id) : null),	939	() => (activeThread ? scopeThreadRef(activeThread.environmentId, activeThread.id) : null),
802	[activeThread],	940	[activeThread],
803	);	941	);
804	const activeThreadKey = activeThreadRef ? scopedThreadKey(activeThreadRef) : null;	942	const activeThreadKey = activeThreadRef ? scopedThreadKey(activeThreadRef) : null;
		943
		944	useEffect(() => {
		945	if (!activeThreadRef) {
		946	return;
		947	}
		948	if (terminalIdListsEqual(activeServerOrderedTerminalIds, terminalUiState.terminalIds)) {
		949	return;
		950	}
		951	if (
		952	serverTerminalIdsStrictSubsetOfClient(
		953	activeServerOrderedTerminalIds,
		954	terminalUiState.terminalIds,
		955	)
		956	) {
		957	return;
		958	}
		959	reconcileTerminalIds(activeThreadRef, activeServerOrderedTerminalIds);
		960	}, [
		961	activeThreadRef,
		962	activeServerOrderedTerminalIds,
		963	reconcileTerminalIds,
		964	terminalUiState.terminalIds,
		965	]);
		966
805	const existingOpenTerminalThreadKeys = useMemo(() => {	967	const existingOpenTerminalThreadKeys = useMemo(() => {
806	const existingThreadKeys = new Set<string>([...serverThreadKeys, ...draftThreadKeys]);	968	const existingThreadKeys = new Set<string>([...serverThreadKeys, ...draftThreadKeys]);
807	return openTerminalThreadKeys.filter((nextThreadKey) => existingThreadKeys.has(nextThreadKey));	969	return openTerminalThreadKeys.filter((nextThreadKey) => existingThreadKeys.has(nextThreadKey));
@@ -1581,22 +1743,93 @@ export default function ChatView(props: ChatViewProps) { · 773 unmodified lines
1581	setTerminalOpen(!terminalUiState.terminalOpen);	1743	setTerminalOpen(!terminalUiState.terminalOpen);
1582	}, [activeThreadRef, setTerminalOpen, terminalUiState.terminalOpen]);	1744	}, [activeThreadRef, setTerminalOpen, terminalUiState.terminalOpen]);
1583	const splitTerminal = useCallback(() => {	1745	const splitTerminal = useCallback(() => {
1584	if (!activeThreadRef \|\| hasReachedSplitLimit) return;	1746	if (!activeThreadRef \|\| hasReachedSplitLimit \|\| !activeThreadId \|\| !activeProject) {
1585	const terminalId = `terminal-${randomUUID()}`;	1747	return;
		1748	}
		1749	const cwdForOpen = gitCwd ?? activeProject.cwd;
		1750	if (!cwdForOpen) {
		1751	return;
		1752	}
		1753	const api = readEnvironmentApi(environmentId);
		1754	if (!api) {
		1755	return;
		1756	}
		1757	const terminalId = nextTerminalId(activeServerOrderedTerminalIds);
1586	storeSplitTerminal(activeThreadRef, terminalId);	1758	storeSplitTerminal(activeThreadRef, terminalId);
1587	setTerminalFocusRequestId((value) => value + 1);	1759	setTerminalFocusRequestId((value) => value + 1);
1588	}, [activeThreadRef, hasReachedSplitLimit, storeSplitTerminal]);	1760	void (async () => {
		1761	try {
		1762	await api.terminal.open({
		1763	threadId: activeThreadId,
		1764	terminalId,
		1765	cwd: cwdForOpen,
		1766	...(activeThreadWorktreePath != null ? { worktreePath: activeThreadWorktreePath } : {}),
		1767	env: projectScriptRuntimeEnv({
		1768	project: { cwd: activeProject.cwd },
		1769	worktreePath: activeThreadWorktreePath,
		1770	}),
		1771	});
		1772	} catch {
		1773	// Opening failed; the tab is already in the store — user can retry or close it.
		1774	}
		1775	})();
		1776	}, [
		1777	activeProject,
		1778	activeServerOrderedTerminalIds,
		1779	activeThreadId,
		1780	activeThreadRef,
		1781	activeThreadWorktreePath,
		1782	environmentId,
		1783	gitCwd,
		1784	hasReachedSplitLimit,
		1785	storeSplitTerminal,
		1786	]);
1589	const createNewTerminal = useCallback(() => {	1787	const createNewTerminal = useCallback(() => {
1590	if (!activeThreadRef) return;	1788	if (!activeThreadRef \|\| !activeThreadId \|\| !activeProject) {
1591	const terminalId = `terminal-${randomUUID()}`;	1789	return;
		1790	}
		1791	const cwdForOpen = gitCwd ?? activeProject.cwd;
		1792	if (!cwdForOpen) {
		1793	return;
		1794	}
		1795	const api = readEnvironmentApi(environmentId);
		1796	if (!api) {
		1797	return;
		1798	}
		1799	const terminalId = nextTerminalId(activeServerOrderedTerminalIds);
1592	storeNewTerminal(activeThreadRef, terminalId);	1800	storeNewTerminal(activeThreadRef, terminalId);
1593	setTerminalFocusRequestId((value) => value + 1);	1801	setTerminalFocusRequestId((value) => value + 1);
1594	}, [activeThreadRef, storeNewTerminal]);	1802	void (async () => {
		1803	try {
		1804	await api.terminal.open({
		1805	threadId: activeThreadId,
		1806	terminalId,
		1807	cwd: cwdForOpen,
		1808	...(activeThreadWorktreePath != null ? { worktreePath: activeThreadWorktreePath } : {}),
		1809	env: projectScriptRuntimeEnv({
		1810	project: { cwd: activeProject.cwd },
		1811	worktreePath: activeThreadWorktreePath,
		1812	}),
		1813	});
		1814	} catch {
		1815	// Opening failed; the tab is already in the store — user can retry or close it.
		1816	}
		1817	})();
		1818	}, [
		1819	activeProject,
		1820	activeServerOrderedTerminalIds,
		1821	activeThreadId,
		1822	activeThreadRef,
		1823	activeThreadWorktreePath,
		1824	environmentId,
		1825	gitCwd,
		1826	storeNewTerminal,
		1827	]);
1595	const closeTerminal = useCallback(	1828	const closeTerminal = useCallback(
1596	(terminalId: string) => {	1829	(terminalId: string) => {
1597	const api = readEnvironmentApi(environmentId);	1830	const api = readEnvironmentApi(environmentId);
1598	if (!activeThreadId \|\| !api) return;	1831	if (!activeThreadId \|\| !api \|\| !activeThreadRef) return;
1599	const isFinalTerminal = terminalUiState.terminalIds.length <= 1;	1832	const isFinalTerminal = activeServerOrderedTerminalIds.length <= 1;
1600	const fallbackExitWrite = () =>	1833	const fallbackExitWrite = () =>
1601	api.terminal	1834	api.terminal
1602	.write({ threadId: activeThreadId, terminalId, data: "exit\n" })	1835	.write({ threadId: activeThreadId, terminalId, data: "exit\n" })
@@ -1617,17 +1850,15 @@ export default function ChatView(props: ChatViewProps) { · 14 unmodified lines
1617	} else {	1850	} else {
1618	void fallbackExitWrite();	1851	void fallbackExitWrite();
1619	}	1852	}
1620	if (activeThreadRef) {	1853	storeCloseTerminal(activeThreadRef, terminalId);
1621	storeCloseTerminal(activeThreadRef, terminalId);
1622	}
1623	setTerminalFocusRequestId((value) => value + 1);	1854	setTerminalFocusRequestId((value) => value + 1);
1624	},	1855	},
1625	[	1856	[
1626	activeThreadId,	1857	activeThreadId,
1627	activeThreadRef,	1858	activeThreadRef,
		1859	activeServerOrderedTerminalIds,
1628	environmentId,	1860	environmentId,
1629	storeCloseTerminal,	1861	storeCloseTerminal,
1630	terminalUiState.terminalIds.length,
1631	],	1862	],
1632	);	1863	);
1633	const runProjectScript = useCallback(	1864	const runProjectScript = useCallback(
@@ -1652,14 +1883,11 @@ export default function ChatView(props: ChatViewProps) { · 18 unmodified lines
1652	const targetCwd = options?.cwd ?? gitCwd ?? activeProject.cwd;	1883	const targetCwd = options?.cwd ?? gitCwd ?? activeProject.cwd;
1653	const baseTerminalId =	1884	const baseTerminalId =
1654	terminalUiState.activeTerminalId \|\|	1885	terminalUiState.activeTerminalId \|\|
1655	terminalUiState.terminalIds[0] \|\|	1886	activeServerOrderedTerminalIds[0] \|\|
1656	DEFAULT_THREAD_TERMINAL_ID;	1887	DEFAULT_THREAD_TERMINAL_ID;
1657	const isBaseTerminalBusy = runningTerminalIds.includes(baseTerminalId);	1888	const isBaseTerminalBusy = runningTerminalIds.includes(baseTerminalId);
1658	const wantsNewTerminal = Boolean(options?.preferNewTerminal) \|\| isBaseTerminalBusy;	1889	const wantsNewTerminal = Boolean(options?.preferNewTerminal) \|\| isBaseTerminalBusy;
1659	const shouldCreateNewTerminal = wantsNewTerminal;	1890	const shouldCreateNewTerminal = wantsNewTerminal;
1660	const targetTerminalId = shouldCreateNewTerminal
1661	? `terminal-${randomUUID()}`
1662	: baseTerminalId;
1663	const targetWorktreePath = options?.worktreePath ?? activeThread.worktreePath ?? null;	1891	const targetWorktreePath = options?.worktreePath ?? activeThread.worktreePath ?? null;
1664		1892
1665	setTerminalUiLaunchContext({	1893	setTerminalUiLaunchContext({
@@ -1671,11 +1899,6 @@ export default function ChatView(props: ChatViewProps) { · 5 unmodified lines
1671	if (!activeThreadRef) {	1899	if (!activeThreadRef) {
1672	return;	1900	return;
1673	}	1901	}
1674	if (shouldCreateNewTerminal) {
1675	storeNewTerminal(activeThreadRef, targetTerminalId);
1676	} else {
1677	storeSetActiveTerminal(activeThreadRef, targetTerminalId);
1678	}
1679	setTerminalFocusRequestId((value) => value + 1);	1902	setTerminalFocusRequestId((value) => value + 1);
1680		1903
1681	const runtimeEnv = projectScriptRuntimeEnv({	1904	const runtimeEnv = projectScriptRuntimeEnv({
@@ -1685,6 +1908,9 @@ export default function ChatView(props: ChatViewProps) { · 3 unmodified lines
1685	worktreePath: targetWorktreePath,	1908	worktreePath: targetWorktreePath,
1686	...(options?.env ? { extraEnv: options.env } : {}),	1909	...(options?.env ? { extraEnv: options.env } : {}),
1687	});	1910	});
		1911	const targetTerminalId = shouldCreateNewTerminal
		1912	? nextTerminalId(activeServerOrderedTerminalIds)
		1913	: baseTerminalId;
1688	const openTerminalInput: TerminalOpenInput = shouldCreateNewTerminal	1914	const openTerminalInput: TerminalOpenInput = shouldCreateNewTerminal
1689	? {	1915	? {
1690	threadId: activeThreadId,	1916	threadId: activeThreadId,
@@ -1703,6 +1929,12 @@ export default function ChatView(props: ChatViewProps) { · 12 unmodified lines
1703	env: runtimeEnv,	1929	env: runtimeEnv,
1704	};	1930	};
1705		1931
		1932	if (shouldCreateNewTerminal) {
		1933	storeNewTerminal(activeThreadRef, targetTerminalId);
		1934	} else {
		1935	storeSetActiveTerminal(activeThreadRef, targetTerminalId);
		1936	}
		1937
1706	try {	1938	try {
1707	await api.terminal.open(openTerminalInput);	1939	await api.terminal.open(openTerminalInput);
1708	await api.terminal.write({	1940	await api.terminal.write({
@@ -1729,9 +1961,9 @@ export default function ChatView(props: ChatViewProps) { · 20 unmodified lines
1729	storeSetActiveTerminal,	1961	storeSetActiveTerminal,
1730	setLastInvokedScriptByProjectId,	1962	setLastInvokedScriptByProjectId,
1731	environmentId,	1963	environmentId,
		1964	activeServerOrderedTerminalIds,
1732	runningTerminalIds,	1965	runningTerminalIds,
1733	terminalUiState.activeTerminalId,	1966	terminalUiState.activeTerminalId,
1734	terminalUiState.terminalIds,
1735	],	1967	],
1736	);	1968	);
1737		1969

apps/web/src/components/ThreadTerminalDrawer.browser.tsx+4−3

     terminal: {
       open: vi.fn(async () => ({
         threadId: THREAD_ID,
-        terminalId: "default",
+        terminalId: "term-1",
         cwd: "/repo/project",
         worktreePath: null,
         status: "running" as const,
         history: "",
         exitCode: null,
         exitSignal: null,
+        label: "Terminal 1",
         updatedAt: "2026-04-07T00:00:00.000Z",
       })),
       write: vi.fn(async () => undefined),
     <TerminalViewport
       threadRef={props.threadRef}
       threadId={THREAD_ID}
-      terminalId="default"
+      terminalId="term-1"
       terminalLabel="Terminal"
       cwd="/repo/project"
       onSessionExited={() => undefined}
         <TerminalViewport
           threadRef={nextProps.threadRef}
           threadId={THREAD_ID}
-          terminalId="default"
+          terminalId="term-1"
           terminalLabel="Terminal"
           cwd="/repo/project"
           onSessionExited={() => undefined}

apps/web/src/components/ThreadTerminalDrawer.tsx+63−30

   type TerminalSessionSnapshot,
   type ThreadId,
 } from "@t3tools/contracts";
+import { getTerminalLabel } from "@t3tools/shared/terminalLabels";
 import { Terminal, type ITheme } from "@xterm/xterm";
 import {
   type PointerEvent as ReactPointerEvent,
 } from "../keybindings";
 import {
   DEFAULT_THREAD_TERMINAL_HEIGHT,
-  DEFAULT_THREAD_TERMINAL_ID,
   MAX_TERMINALS_PER_GROUP,
   type ThreadTerminalGroup,
 } from "../types";
   onHeightChange: (height: number) => void;
   onAddTerminalContext: (selection: TerminalContextSelection) => void;
   keybindings: ResolvedKeybindingsConfig;
+  /** Prefer server-provided tab titles when present (e.g. active subprocess name). */
+  terminalLabelsById?: ReadonlyMap<string, string>;
 }
 interface TerminalActionButtonProps {
   onHeightChange,
   onAddTerminalContext,
   keybindings,
+  terminalLabelsById,
 }: ThreadTerminalDrawerProps) {
   const [drawerHeight, setDrawerHeight] = useState(() => clampDrawerHeight(height));
   const [resizeEpoch, setResizeEpoch] = useState(0);
   const didResizeDuringDragRef = useRef(false);
   const normalizedTerminalIds = useMemo(() => {
-    const cleaned = [...new Set(terminalIds.map((id) => id.trim()).filter((id) => id.length > 0))];
+    return [...new Set(terminalIds.map((id) => id.trim()).filter((id) => id.length > 0))];
-    return cleaned.length > 0 ? cleaned : [DEFAULT_THREAD_TERMINAL_ID];
   }, [terminalIds]);
-  const resolvedActiveTerminalId = normalizedTerminalIds.includes(activeTerminalId)
+  const resolvedActiveTerminalId =
-    ? activeTerminalId
+    normalizedTerminalIds.length === 0
-    : (normalizedTerminalIds[0] ?? DEFAULT_THREAD_TERMINAL_ID);
+      ? ""
+      : normalizedTerminalIds.includes(activeTerminalId)
+        ? activeTerminalId
+        : (normalizedTerminalIds[0] ?? "");
   const resolvedTerminalGroups = useMemo(() => {
+    if (normalizedTerminalIds.length === 0) {
+      return [];
+    }
     const validTerminalIdSet = new Set(normalizedTerminalIds);
     const assignedTerminalIds = new Set<string>();
     const usedGroupIds = new Set<string>();
       const baseGroupId =
         terminalGroup.id.trim().length > 0
           ? terminalGroup.id.trim()
-          : `group-${nextTerminalIds[0] ?? DEFAULT_THREAD_TERMINAL_ID}`;
+          : `group-${nextTerminalIds[0] ?? normalizedTerminalIds[0] ?? ""}`;
       nextGroups.push({
         id: assignUniqueGroupId(baseGroupId),
         terminalIds: nextTerminalIds,
       });
     }
-    if (nextGroups.length > 0) {
+    const terminalOrderIndex = new Map(
-      return nextGroups;
+      normalizedTerminalIds.map((id, index) => [id, index] as const),
-    }
+    );
+    nextGroups.sort((left, right) => {
+      const rank = (ids: readonly string[]) =>
+        Math.min(...ids.map((id) => terminalOrderIndex.get(id) ?? Number.POSITIVE_INFINITY));
+      return rank(left.terminalIds) - rank(right.terminalIds);
+    });
-    return [
+    return nextGroups;
-      {
+  }, [normalizedTerminalIds, terminalGroups]);
-        id: `group-${resolvedActiveTerminalId}`,
-        terminalIds: [resolvedActiveTerminalId],
-      },
-    ];
-  }, [normalizedTerminalIds, resolvedActiveTerminalId, terminalGroups]);
   const resolvedActiveGroupIndex = useMemo(() => {
     const indexById = resolvedTerminalGroups.findIndex(
     return indexByTerminal >= 0 ? indexByTerminal : 0;
   }, [activeTerminalGroupId, resolvedActiveTerminalId, resolvedTerminalGroups]);
-  const visibleTerminalIds = resolvedTerminalGroups[resolvedActiveGroupIndex]?.terminalIds ?? [
+  const visibleTerminalIds =
-    resolvedActiveTerminalId,
+    resolvedTerminalGroups[resolvedActiveGroupIndex]?.terminalIds ??
-  ];
+    (normalizedTerminalIds.length > 0 ? [resolvedActiveTerminalId] : []);
   const hasTerminalSidebar = normalizedTerminalIds.length > 1;
   const isSplitView = visibleTerminalIds.length > 1;
   const showGroupHeaders =
     resolvedTerminalGroups.length > 1 ||
     resolvedTerminalGroups.some((terminalGroup) => terminalGroup.terminalIds.length > 1);
   const hasReachedSplitLimit = visibleTerminalIds.length >= MAX_TERMINALS_PER_GROUP;
-  const terminalLabelById = useMemo(
+  const terminalLabelById = useMemo(() => {
-    () =>
+    const next = new Map<string, string>();
-      new Map(
+    for (const terminalId of normalizedTerminalIds) {
-        normalizedTerminalIds.map((terminalId, index) => [terminalId, `Terminal ${index + 1}`]),
+      next.set(terminalId, terminalLabelsById?.get(terminalId) ?? getTerminalLabel(terminalId));
-      ),
+    }
-    [normalizedTerminalIds],
+    return next;
-  );
+  }, [normalizedTerminalIds, terminalLabelsById]);
   const splitTerminalActionLabel = hasReachedSplitLimit
     ? `Split Terminal (max ${MAX_TERMINALS_PER_GROUP} per group)`
     : splitShortcutLabel
     };
   }, [syncHeight]);
+  if (normalizedTerminalIds.length === 0) {
+    return (
+      <aside
+        className="thread-terminal-drawer relative flex min-w-0 shrink-0 flex-col overflow-hidden border-t border-border/80 bg-background"
+        style={{ height: `${drawerHeight}px` }}
+      >
+        <div
+          className="absolute inset-x-0 top-0 z-20 h-1.5 cursor-row-resize"
+          onPointerDown={handleResizePointerDown}
+          onPointerMove={handleResizePointerMove}
+          onPointerUp={handleResizePointerEnd}
+          onPointerCancel={handleResizePointerEnd}
+        />
+        <div className="flex min-h-0 flex-1 flex-col items-center justify-center gap-3 px-4 py-6 text-center text-sm text-muted-foreground">
+          <p>No terminal sessions for this thread yet.</p>
+          <button
+            type="button"
+            className="rounded-md border border-border/80 bg-background px-3 py-1.5 text-xs font-medium text-foreground transition-colors hover:bg-accent"
+            onClick={onNewTerminalAction}
+          >
+            {newTerminalActionLabel}
+          </button>
+        </div>
+      </aside>
+    );
+  }
   return (
     <aside
       className="thread-terminal-drawer relative flex min-w-0 shrink-0 flex-col overflow-hidden border-t border-border/80 bg-background"
                           }`}
                           onClick={() => onActiveTerminalChange(groupActiveTerminalId)}
                         >
-                          {terminalGroup.terminalIds.length > 1
+                          Group {groupIndex + 1}
-                            ? `Split ${groupIndex + 1}`
-                            : `Terminal ${groupIndex + 1}`}
                         </button>
                       )}

apps/web/src/environments/runtime/service.threadSubscriptions.test.ts+65−0

@@ -1,4 +1,5 @@
1	import { QueryClient } from "@tanstack/react-query";	1	import { QueryClient } from "@tanstack/react-query";
		2	import type { WsRpcClient } from "@t3tools/client-runtime";
2	import {	3	import {
3	EnvironmentId,	4	EnvironmentId,
4	ProjectId,	5	ProjectId,
@@ -67,6 +68,70 @@ vi.mock("../../rpc/wsRpcClient", () => ({ · 62 unmodified lines
67	createWsRpcClient: mockCreateWsRpcClient,	68	createWsRpcClient: mockCreateWsRpcClient,
68	}));	69	}));
69		70
		71	vi.mock("@t3tools/client-runtime", async (importOriginal) => {
		72	const actual = await importOriginal<typeof import("@t3tools/client-runtime")>();
		73	const stubWsClient: WsRpcClient = {
		74	dispose: async () => undefined,
		75	reconnect: async () => undefined,
		76	orchestration: {
		77	dispatchCommand: vi.fn(),
		78	getTurnDiff: vi.fn(),
		79	getFullThreadDiff: vi.fn(),
		80	subscribeShell: vi.fn(() => () => undefined),
		81	subscribeThread: mockSubscribeThread,
		82	},
		83	terminal: {
		84	open: vi.fn(),
		85	attach: vi.fn(() => () => undefined),
		86	write: vi.fn(),
		87	resize: vi.fn(),
		88	clear: vi.fn(),
		89	restart: vi.fn(),
		90	close: vi.fn(),
		91	onMetadata: vi.fn(() => () => undefined),
		92	},
		93	projects: {
		94	searchEntries: vi.fn(),
		95	writeFile: vi.fn(),
		96	},
		97	filesystem: {
		98	browse: vi.fn(),
		99	},
		100	shell: {
		101	openInEditor: vi.fn(),
		102	},
		103	git: {
		104	pull: vi.fn(),
		105	refreshStatus: vi.fn(),
		106	onStatus: vi.fn(() => () => undefined),
		107	runStackedAction: vi.fn(),
		108	listBranches: vi.fn(),
		109	createWorktree: vi.fn(),
		110	removeWorktree: vi.fn(),
		111	createBranch: vi.fn(),
		112	checkout: vi.fn(),
		113	init: vi.fn(),
		114	resolvePullRequest: vi.fn(),
		115	preparePullRequestThread: vi.fn(),
		116	getReviewDiffs: vi.fn(),
		117	},
		118	server: {
		119	getConfig: vi.fn(),
		120	refreshProviders: vi.fn(),
		121	upsertKeybinding: vi.fn(),
		122	getSettings: vi.fn(),
		123	updateSettings: vi.fn(),
		124	subscribeConfig: vi.fn(() => () => undefined),
		125	subscribeLifecycle: vi.fn(() => () => undefined),
		126	subscribeAuthAccess: vi.fn(() => () => undefined),
		127	},
		128	};
		129	return {
		130	...actual,
		131	createWsRpcClient: vi.fn(() => stubWsClient),
		132	};
		133	});
		134
70	vi.mock("../../rpc/wsTransport", () => ({	135	vi.mock("../../rpc/wsTransport", () => ({
71	WsTransport: MockWsTransport,	136	WsTransport: MockWsTransport,
72	}));	137	}));

apps/web/src/lib/terminalFocus.test.ts+18−1

@@ -11,7 +11,13 @@ class MockHTMLElement { · 10 unmodified lines
11	};	11	};
12		12
13	closest(selector: string): MockHTMLElement \| null {	13	closest(selector: string): MockHTMLElement \| null {
14	return selector === ".thread-terminal-drawer .xterm" && this.isConnected ? this : null;	14	if (!this.isConnected) {
		15	return null;
		16	}
		17	if (selector === ".thread-terminal-drawer .xterm" \|\| selector === ".thread-terminal-drawer") {
		18	return this;
		19	}
		20	return null;
15	}	21	}
16	}	22	}
17		23
@@ -53,4 +59,15 @@ describe("isTerminalFocused", () => { · 35 unmodified lines
53		59
54	expect(isTerminalFocused()).toBe(true);	60	expect(isTerminalFocused()).toBe(true);
55	});	61	});
		62
		63	it("returns true for focus inside the terminal drawer (e.g. sidebar)", () => {
		64	const sidebarButton = new MockHTMLElement();
		65	sidebarButton.className = "terminal-sidebar-button";
		66	sidebarButton.isConnected = true;
		67
		68	globalThis.HTMLElement = MockHTMLElement as unknown as typeof HTMLElement;
		69	globalThis.document = { activeElement: sidebarButton } as Document;
		70
		71	expect(isTerminalFocused()).toBe(true);
		72	});
56	});	73	});

apps/web/src/lib/terminalFocus.ts+3−1

@@ -3,5 +3,7 @@ export function isTerminalFocused(): boolean { · 2 unmodified lines
3	if (!(activeElement instanceof HTMLElement)) return false;	3	if (!(activeElement instanceof HTMLElement)) return false;
4	if (!activeElement.isConnected) return false;	4	if (!activeElement.isConnected) return false;
5	if (activeElement.classList.contains("xterm-helper-textarea")) return true;	5	if (activeElement.classList.contains("xterm-helper-textarea")) return true;
6	return activeElement.closest(".thread-terminal-drawer .xterm") !== null;	6	if (activeElement.closest(".thread-terminal-drawer .xterm") !== null) return true;
		7	// Sidebar / toolbar / resize affordances: still "terminal UI" for split vs diff.toggle (⌘D).
		8	return activeElement.closest(".thread-terminal-drawer") !== null;
7	}	9	}

apps/web/src/localApi.test.ts+1−0

@@ -341,6 +341,7 @@ describe("wsApi", () => { · 340 unmodified lines
341	exitCode: null,	341	exitCode: null,
342	exitSignal: null,	342	exitSignal: null,
343	hasRunningSubprocess: true,	343	hasRunningSubprocess: true,
		344	label: "terminal-1",
344	updatedAt: "2026-02-24T00:00:00.000Z",	345	updatedAt: "2026-02-24T00:00:00.000Z",
345	},	346	},
346	} satisfies TerminalMetadataStreamEvent;	347	} satisfies TerminalMetadataStreamEvent;

apps/web/src/terminalUiStateStore.test.ts+51−31

     });
   });
-  it("returns a closed default terminal UI state for unknown threads", () => {
+  it("returns an empty default terminal UI state for unknown threads", () => {
     const terminalUiState = selectThreadTerminalUiState(
       useTerminalUiStateStore.getState().terminalUiStateByThreadKey,
       THREAD_REF,
     expect(terminalUiState).toEqual({
       terminalOpen: false,
       terminalHeight: 280,
-      terminalIds: ["default"],
+      terminalIds: [],
-      activeTerminalId: "default",
+      activeTerminalId: "",
-      terminalGroups: [{ id: "group-default", terminalIds: ["default"] }],
+      terminalGroups: [],
-      activeTerminalGroupId: "group-default",
+      activeTerminalGroupId: "",
     });
   });
       THREAD_REF,
     );
     expect(terminalUiState.terminalOpen).toBe(true);
-    expect(terminalUiState.terminalIds).toEqual(["default", "terminal-2"]);
+    expect(terminalUiState.terminalIds).toEqual(["terminal-2"]);
     expect(terminalUiState.activeTerminalId).toBe("terminal-2");
     expect(terminalUiState.terminalGroups).toEqual([
-      { id: "group-default", terminalIds: ["default", "terminal-2"] },
+      { id: "group-terminal-2", terminalIds: ["terminal-2"] },
     ]);
   });
     store.splitTerminal(THREAD_REF, "terminal-3");
     store.splitTerminal(THREAD_REF, "terminal-4");
     store.splitTerminal(THREAD_REF, "terminal-5");
+    store.splitTerminal(THREAD_REF, "terminal-6");
     const terminalUiState = selectThreadTerminalUiState(
       useTerminalUiStateStore.getState().terminalUiStateByThreadKey,
       THREAD_REF,
     );
     expect(terminalUiState.terminalIds).toEqual([
-      "default",
       "terminal-2",
       "terminal-3",
       "terminal-4",
+      "terminal-5",
     ]);
     expect(terminalUiState.terminalGroups).toEqual([
-      { id: "group-default", terminalIds: ["default", "terminal-2", "terminal-3", "terminal-4"] },
+      {
+        id: "group-terminal-2",
+        terminalIds: ["terminal-2", "terminal-3", "terminal-4", "terminal-5"],
+      },
     ]);
   });
       useTerminalUiStateStore.getState().terminalUiStateByThreadKey,
       THREAD_REF,
     );
-    expect(terminalUiState.terminalIds).toEqual(["default", "terminal-2"]);
+    expect(terminalUiState.terminalIds).toEqual(["terminal-2"]);
     expect(terminalUiState.activeTerminalId).toBe("terminal-2");
     expect(terminalUiState.activeTerminalGroupId).toBe("group-terminal-2");
     expect(terminalUiState.terminalGroups).toEqual([
-      { id: "group-default", terminalIds: ["default"] },
       { id: "group-terminal-2", terminalIds: ["terminal-2"] },
     ]);
   });
       THREAD_REF,
     );
     expect(terminalUiState.terminalOpen).toBe(true);
-    expect(terminalUiState.terminalIds).toEqual(["default", "setup-setup"]);
+    expect(terminalUiState.terminalIds).toEqual(["setup-setup"]);
     expect(terminalUiState.activeTerminalId).toBe("setup-setup");
     expect(terminalUiState.terminalGroups).toEqual([
-      { id: "group-default", terminalIds: ["default"] },
       { id: "group-setup-setup", terminalIds: ["setup-setup"] },
     ]);
   });
         useTerminalUiStateStore.getState().terminalUiStateByThreadKey,
         OTHER_THREAD_REF,
       ).terminalIds,
-    ).toEqual(["default", "env-b-terminal"]);
+    ).toEqual(["env-b-terminal"]);
   });
-  it("migrates legacy persisted terminal UI state using the stored version", () => {
+  it("drops persisted entries whose thread keys are not valid scoped keys", () => {
     const migrated = migratePersistedTerminalUiStateStoreState(
       {
         terminalStateByThreadKey: {
           [scopedThreadKey(THREAD_REF)]: {
             terminalOpen: true,
             terminalHeight: 320,
-            terminalIds: ["default"],
+            terminalIds: ["term-1"],
-            activeTerminalId: "default",
+            activeTerminalId: "term-1",
-            terminalGroups: [{ id: "group-default", terminalIds: ["default"] }],
+            terminalGroups: [{ id: "group-term-1", terminalIds: ["term-1"] }],
-            activeTerminalGroupId: "group-default",
+            activeTerminalGroupId: "group-term-1",
           },
           "legacy-thread-id": {
             terminalOpen: true,
             terminalHeight: 320,
-            terminalIds: ["default"],
+            terminalIds: ["term-1"],
-            activeTerminalId: "default",
+            activeTerminalId: "term-1",
-            terminalGroups: [{ id: "group-default", terminalIds: ["default"] }],
+            terminalGroups: [{ id: "group-term-1", terminalIds: ["term-1"] }],
-            activeTerminalGroupId: "group-default",
+            activeTerminalGroupId: "group-term-1",
           },
         },
       },
         [scopedThreadKey(THREAD_REF)]: {
           terminalOpen: true,
           terminalHeight: 320,
-          terminalIds: ["default"],
+          terminalIds: ["term-1"],
-          activeTerminalId: "default",
+          activeTerminalId: "term-1",
-          terminalGroups: [{ id: "group-default", terminalIds: ["default"] }],
+          terminalGroups: [{ id: "group-term-1", terminalIds: ["term-1"] }],
-          activeTerminalGroupId: "group-default",
+          activeTerminalGroupId: "group-term-1",
         },
       },
     });
   it("resets to default and clears persisted entry when closing the last terminal", () => {
     const store = useTerminalUiStateStore.getState();
-    store.closeTerminal(THREAD_REF, "default");
+    store.newTerminal(THREAD_REF, "terminal-only");
+    store.closeTerminal(THREAD_REF, "terminal-only");
     expect(
       useTerminalUiStateStore.getState().terminalUiStateByThreadKey[scopedThreadKey(THREAD_REF)],
         useTerminalUiStateStore.getState().terminalUiStateByThreadKey,
         THREAD_REF,
       ).terminalIds,
-    ).toEqual(["default"]);
+    ).toEqual([]);
   });
   it("keeps a valid active terminal after closing an active split terminal", () => {
       THREAD_REF,
     );
     expect(terminalUiState.activeTerminalId).toBe("terminal-2");
-    expect(terminalUiState.terminalIds).toEqual(["default", "terminal-2"]);
+    expect(terminalUiState.terminalIds).toEqual(["terminal-2"]);
+    expect(terminalUiState.terminalGroups).toEqual([
+      { id: "group-terminal-2", terminalIds: ["terminal-2"] },
+    ]);
+  });
+  it("reconciles terminal ids from an external ordered list", () => {
+    const store = useTerminalUiStateStore.getState();
+    store.setTerminalOpen(THREAD_REF, true);
+    store.reconcileTerminalIds(THREAD_REF, ["term-a", "term-b"]);
+    const terminalUiState = selectThreadTerminalUiState(
+      useTerminalUiStateStore.getState().terminalUiStateByThreadKey,
+      THREAD_REF,
+    );
+    expect(terminalUiState.terminalIds).toEqual(["term-a", "term-b"]);
+    expect(terminalUiState.activeTerminalId).toBe("term-a");
     expect(terminalUiState.terminalGroups).toEqual([
-      { id: "group-default", terminalIds: ["default", "terminal-2"] },
+      { id: "group-term-a", terminalIds: ["term-a"] },
+      { id: "group-term-b", terminalIds: ["term-b"] },
     ]);
   });

apps/web/src/terminalUiStateStore.ts+60−44

@@ -12,7 +12,6 @@ import { createJSONStorage, persist } from "zustand/middleware"; · 11 unmodified lines
12	import { resolveStorage } from "./lib/storage";	12	import { resolveStorage } from "./lib/storage";
13	import {	13	import {
14	DEFAULT_THREAD_TERMINAL_HEIGHT,	14	DEFAULT_THREAD_TERMINAL_HEIGHT,
15	DEFAULT_THREAD_TERMINAL_ID,
16	MAX_TERMINALS_PER_GROUP,	15	MAX_TERMINALS_PER_GROUP,
17	type ThreadTerminalGroup,	16	type ThreadTerminalGroup,
18	} from "./types";	17	} from "./types";
@@ -36,20 +35,22 @@ interface PersistedTerminalUiStateStoreState { · 17 unmodified lines
36		35
37	export function migratePersistedTerminalUiStateStoreState(	36	export function migratePersistedTerminalUiStateStoreState(
38	persistedState: unknown,	37	persistedState: unknown,
39	version: number,	38	_version: number,
40	): PersistedTerminalUiStateStoreState {	39	): PersistedTerminalUiStateStoreState {
41	if (version <= 2 && persistedState && typeof persistedState === "object") {	40	if (!persistedState \|\| typeof persistedState !== "object") {
42	const candidate = persistedState as PersistedTerminalUiStateStoreState;	41	return { terminalUiStateByThreadKey: {} };
43	const persistedUiStateByThreadKey =
44	candidate.terminalUiStateByThreadKey ?? candidate.terminalStateByThreadKey ?? {};
45	const nextTerminalUiStateByThreadKey = Object.fromEntries(
46	Object.entries(persistedUiStateByThreadKey).filter(([threadKey]) =>
47	parseScopedThreadKey(threadKey),
48	),
49	);
50	return { terminalUiStateByThreadKey: nextTerminalUiStateByThreadKey };
51	}	42	}
52	return { terminalUiStateByThreadKey: {} };	43
		44	const candidate = persistedState as PersistedTerminalUiStateStoreState;
		45	const persistedUiStateByThreadKey =
		46	candidate.terminalUiStateByThreadKey ?? candidate.terminalStateByThreadKey ?? {};
		47	const terminalUiStateByThreadKey = Object.fromEntries(
		48	Object.entries(persistedUiStateByThreadKey).filter(([threadKey]) =>
		49	parseScopedThreadKey(threadKey),
		50	),
		51	);
		52
		53	return { terminalUiStateByThreadKey };
53	}	54	}
54		55
55	function createTerminalUiStateStorage() {	56	function createTerminalUiStateStorage() {
@@ -57,8 +58,7 @@ function createTerminalUiStateStorage() { · 1 unmodified line
57	}	58	}
58		59
59	function normalizeTerminalIds(terminalIds: string[]): string[] {	60	function normalizeTerminalIds(terminalIds: string[]): string[] {
60	const ids = [...new Set(terminalIds.map((id) => id.trim()).filter((id) => id.length > 0))];	61	return [...new Set(terminalIds.map((id) => id.trim()).filter((id) => id.length > 0))];
61	return ids.length > 0 ? ids : [DEFAULT_THREAD_TERMINAL_ID];
62	}	62	}
63		63
64	function fallbackGroupId(terminalId: string): string {	64	function fallbackGroupId(terminalId: string): string {
@@ -91,6 +91,10 @@ function normalizeTerminalGroups( · 26 unmodified lines
91	terminalGroups: ThreadTerminalGroup[],	91	terminalGroups: ThreadTerminalGroup[],
92	terminalIds: string[],	92	terminalIds: string[],
93	): ThreadTerminalGroup[] {	93	): ThreadTerminalGroup[] {
		94	if (terminalIds.length === 0) {
		95	return [];
		96	}
		97
94	const validTerminalIdSet = new Set(terminalIds);	98	const validTerminalIdSet = new Set(terminalIds);
95	const assignedTerminalIds = new Set<string>();	99	const assignedTerminalIds = new Set<string>();
96	const nextGroups: ThreadTerminalGroup[] = [];	100	const nextGroups: ThreadTerminalGroup[] = [];
@@ -109,7 +113,7 @@ function normalizeTerminalGroups( · 12 unmodified lines
109	const baseGroupId =	113	const baseGroupId =
110	group.id.trim().length > 0	114	group.id.trim().length > 0
111	? group.id.trim()	115	? group.id.trim()
112	: fallbackGroupId(groupTerminalIds[0] ?? DEFAULT_THREAD_TERMINAL_ID);	116	: fallbackGroupId(groupTerminalIds[0] ?? terminalIds[0] ?? "");
113	nextGroups.push({	117	nextGroups.push({
114	id: assignUniqueGroupId(baseGroupId, usedGroupIds),	118	id: assignUniqueGroupId(baseGroupId, usedGroupIds),
115	terminalIds: groupTerminalIds,	119	terminalIds: groupTerminalIds,
@@ -124,15 +128,6 @@ function normalizeTerminalGroups( · 8 unmodified lines
124	});	128	});
125	}	129	}
126		130
127	if (nextGroups.length === 0) {
128	return [
129	{
130	id: fallbackGroupId(DEFAULT_THREAD_TERMINAL_ID),
131	terminalIds: [DEFAULT_THREAD_TERMINAL_ID],
132	},
133	];
134	}
135
136	return nextGroups;	131	return nextGroups;
137	}	132	}
138		133
@@ -173,15 +168,10 @@ function threadTerminalUiStateEqual( · 34 unmodified lines
173	const DEFAULT_THREAD_TERMINAL_UI_STATE: ThreadTerminalUiState = Object.freeze({	168	const DEFAULT_THREAD_TERMINAL_UI_STATE: ThreadTerminalUiState = Object.freeze({
174	terminalOpen: false,	169	terminalOpen: false,
175	terminalHeight: DEFAULT_THREAD_TERMINAL_HEIGHT,	170	terminalHeight: DEFAULT_THREAD_TERMINAL_HEIGHT,
176	terminalIds: [DEFAULT_THREAD_TERMINAL_ID],	171	terminalIds: [],
177	activeTerminalId: DEFAULT_THREAD_TERMINAL_ID,	172	activeTerminalId: "",
178	terminalGroups: [	173	terminalGroups: [],
179	{	174	activeTerminalGroupId: "",
180	id: fallbackGroupId(DEFAULT_THREAD_TERMINAL_ID),
181	terminalIds: [DEFAULT_THREAD_TERMINAL_ID],
182	},
183	],
184	activeTerminalGroupId: fallbackGroupId(DEFAULT_THREAD_TERMINAL_ID),
185	});	175	});
186		176
187	function createDefaultThreadTerminalUiState(): ThreadTerminalUiState {	177	function createDefaultThreadTerminalUiState(): ThreadTerminalUiState {
@@ -197,11 +187,10 @@ function getDefaultThreadTerminalUiState(): ThreadTerminalUiState { · 9 unmodified lines
197	}	187	}
198		188
199	function normalizeThreadTerminalUiState(state: ThreadTerminalUiState): ThreadTerminalUiState {	189	function normalizeThreadTerminalUiState(state: ThreadTerminalUiState): ThreadTerminalUiState {
200	const terminalIds = normalizeTerminalIds(state.terminalIds);	190	const nextTerminalIds = normalizeTerminalIds(state.terminalIds);
201	const nextTerminalIds = terminalIds.length > 0 ? terminalIds : [DEFAULT_THREAD_TERMINAL_ID];
202	const activeTerminalId = nextTerminalIds.includes(state.activeTerminalId)	191	const activeTerminalId = nextTerminalIds.includes(state.activeTerminalId)
203	? state.activeTerminalId	192	? state.activeTerminalId
204	: (nextTerminalIds[0] ?? DEFAULT_THREAD_TERMINAL_ID);	193	: (nextTerminalIds[0] ?? "");
205	const terminalGroups = normalizeTerminalGroups(state.terminalGroups, nextTerminalIds);	194	const terminalGroups = normalizeTerminalGroups(state.terminalGroups, nextTerminalIds);
206	const activeGroupIdFromState = terminalGroups.some(	195	const activeGroupIdFromState = terminalGroups.some(
207	(group) => group.id === state.activeTerminalGroupId,	196	(group) => group.id === state.activeTerminalGroupId,
@@ -221,10 +210,7 @@ function normalizeThreadTerminalUiState(state: ThreadTerminalUiState): ThreadTer · 13 unmodified lines
221	activeTerminalId,	210	activeTerminalId,
222	terminalGroups,	211	terminalGroups,
223	activeTerminalGroupId:	212	activeTerminalGroupId:
224	activeGroupIdFromState ??	213	activeGroupIdFromState ?? activeGroupIdFromTerminal ?? terminalGroups[0]?.id ?? "",
225	activeGroupIdFromTerminal ??
226	terminalGroups[0]?.id ??
227	fallbackGroupId(DEFAULT_THREAD_TERMINAL_ID),
228	};	214	};
229	return threadTerminalUiStateEqual(state, normalized) ? state : normalized;	215	return threadTerminalUiStateEqual(state, normalized) ? state : normalized;
230	}	216	}
@@ -255,6 +241,7 @@ function upsertTerminalIntoGroups( · 24 unmodified lines
255	mode: "split" \| "new",	241	mode: "split" \| "new",
256	): ThreadTerminalUiState {	242	): ThreadTerminalUiState {
257	const normalized = normalizeThreadTerminalUiState(state);	243	const normalized = normalizeThreadTerminalUiState(state);
		244	const effectiveMode: "split" \| "new" = normalized.terminalIds.length === 0 ? "new" : mode;
258	if (!isValidTerminalId(terminalId)) {	245	if (!isValidTerminalId(terminalId)) {
259	return normalized;	246	return normalized;
260	}	247	}
@@ -275,7 +262,7 @@ function upsertTerminalIntoGroups( · 14 unmodified lines
275	}	262	}
276	}	263	}
277		264
278	if (mode === "new") {	265	if (effectiveMode === "new") {
279	const usedGroupIds = new Set(terminalGroups.map((group) => group.id));	266	const usedGroupIds = new Set(terminalGroups.map((group) => group.id));
280	const nextGroupId = assignUniqueGroupId(fallbackGroupId(terminalId), usedGroupIds);	267	const nextGroupId = assignUniqueGroupId(fallbackGroupId(terminalId), usedGroupIds);
281	terminalGroups.push({ id: nextGroupId, terminalIds: [terminalId] });	268	terminalGroups.push({ id: nextGroupId, terminalIds: [terminalId] });
@@ -411,7 +398,7 @@ function closeThreadTerminal( · 129 unmodified lines
411	normalized.activeTerminalId === terminalId	398	normalized.activeTerminalId === terminalId
412	? (remainingTerminalIds[Math.min(closedTerminalIndex, remainingTerminalIds.length - 1)] ??	399	? (remainingTerminalIds[Math.min(closedTerminalIndex, remainingTerminalIds.length - 1)] ??
413	remainingTerminalIds[0] ??	400	remainingTerminalIds[0] ??
414	DEFAULT_THREAD_TERMINAL_ID)	401	"")
415	: normalized.activeTerminalId;	402	: normalized.activeTerminalId;
416		403
417	const terminalGroups = normalized.terminalGroups	404	const terminalGroups = normalized.terminalGroups
@@ -436,6 +423,32 @@ function closeThreadTerminal( · 18 unmodified lines
436	});	423	});
437	}	424	}
438		425
		426	function reconcileThreadTerminalSessionIds(
		427	state: ThreadTerminalUiState,
		428	nextIds: string[],
		429	): ThreadTerminalUiState {
		430	const normalized = normalizeThreadTerminalUiState(state);
		431	if (arraysEqual(normalized.terminalIds, nextIds)) {
		432	return normalized;
		433	}
		434
		435	const nextActiveTerminalId = nextIds.includes(normalized.activeTerminalId)
		436	? normalized.activeTerminalId
		437	: (nextIds[0] ?? "");
		438
		439	const terminalGroups = normalizeTerminalGroups(normalized.terminalGroups, nextIds);
		440	const activeGroupIdFromTerminal =
		441	terminalGroups.find((group) => group.terminalIds.includes(nextActiveTerminalId))?.id ?? null;
		442
		443	return normalizeThreadTerminalUiState({
		444	...normalized,
		445	terminalIds: nextIds,
		446	activeTerminalId: nextActiveTerminalId,
		447	terminalGroups,
		448	activeTerminalGroupId: activeGroupIdFromTerminal ?? terminalGroups[0]?.id ?? "",
		449	});
		450	}
		451
439	export function selectThreadTerminalUiState(	452	export function selectThreadTerminalUiState(
440	terminalUiStateByThreadKey: Record<string, ThreadTerminalUiState>,	453	terminalUiStateByThreadKey: Record<string, ThreadTerminalUiState>,
441	threadRef: ScopedThreadRef \| null \| undefined,	454	threadRef: ScopedThreadRef \| null \| undefined,
@@ -491,6 +504,7 @@ interface TerminalUiStateStoreState { · 49 unmodified lines
491	) => void;	504	) => void;
492	setActiveTerminal: (threadRef: ScopedThreadRef, terminalId: string) => void;	505	setActiveTerminal: (threadRef: ScopedThreadRef, terminalId: string) => void;
493	closeTerminal: (threadRef: ScopedThreadRef, terminalId: string) => void;	506	closeTerminal: (threadRef: ScopedThreadRef, terminalId: string) => void;
		507	reconcileTerminalIds: (threadRef: ScopedThreadRef, nextIds: string[]) => void;
494	clearTerminalUiState: (threadRef: ScopedThreadRef) => void;	508	clearTerminalUiState: (threadRef: ScopedThreadRef) => void;
495	removeTerminalUiState: (threadRef: ScopedThreadRef) => void;	509	removeTerminalUiState: (threadRef: ScopedThreadRef) => void;
496	removeOrphanedTerminalUiStates: (activeThreadKeys: Set<string>) => void;	510	removeOrphanedTerminalUiStates: (activeThreadKeys: Set<string>) => void;
@@ -553,6 +567,8 @@ export const useTerminalUiStateStore = create<TerminalUiStateStoreState>()( · 56 unmodified lines
553	updateTerminal(threadRef, (state) => setThreadActiveTerminal(state, terminalId)),	567	updateTerminal(threadRef, (state) => setThreadActiveTerminal(state, terminalId)),
554	closeTerminal: (threadRef, terminalId) =>	568	closeTerminal: (threadRef, terminalId) =>
555	updateTerminal(threadRef, (state) => closeThreadTerminal(state, terminalId)),	569	updateTerminal(threadRef, (state) => closeThreadTerminal(state, terminalId)),
		570	reconcileTerminalIds: (threadRef, nextIds) =>
		571	updateTerminal(threadRef, (state) => reconcileThreadTerminalSessionIds(state, nextIds)),
556	clearTerminalUiState: (threadRef) =>	572	clearTerminalUiState: (threadRef) =>
557	set((state) => {	573	set((state) => {
558	const nextTerminalUiStateByThreadKey = updateTerminalUiStateByThreadKey(	574	const nextTerminalUiStateByThreadKey = updateTerminalUiStateByThreadKey(
@@ -600,7 +616,7 @@ export const useTerminalUiStateStore = create<TerminalUiStateStoreState>()( · 41 unmodified lines
600	},	616	},
601	{	617	{
602	name: TERMINAL_UI_STATE_STORAGE_KEY,	618	name: TERMINAL_UI_STATE_STORAGE_KEY,
603	version: 3,	619	version: 4,
604	storage: createJSONStorage(createTerminalUiStateStorage),	620	storage: createJSONStorage(createTerminalUiStateStorage),
605	migrate: migratePersistedTerminalUiStateStoreState,	621	migrate: migratePersistedTerminalUiStateStoreState,
606	partialize: (state) => ({	622	partialize: (state) => ({

apps/web/src/types.ts+1−1

@@ -22,7 +22,7 @@ export const DEFAULT_RUNTIME_MODE: RuntimeMode = "full-access"; · 21 unmodified lines
22		22
23	export const DEFAULT_INTERACTION_MODE: ProviderInteractionMode = "default";	23	export const DEFAULT_INTERACTION_MODE: ProviderInteractionMode = "default";
24	export const DEFAULT_THREAD_TERMINAL_HEIGHT = 280;	24	export const DEFAULT_THREAD_TERMINAL_HEIGHT = 280;
25	export const DEFAULT_THREAD_TERMINAL_ID = "default";	25	export const DEFAULT_THREAD_TERMINAL_ID = "term-1";
26	export const MAX_TERMINALS_PER_GROUP = 4;	26	export const MAX_TERMINALS_PER_GROUP = 4;
27	export type ProjectScript = ContractProjectScript;	27	export type ProjectScript = ContractProjectScript;
28		28

packages/client-runtime/src/terminalSessionState.test.ts+26−4

 const TARGET = {
   environmentId: EnvironmentId.make("env-local"),
   threadId: ThreadId.make("thread-1"),
-  terminalId: "default",
+  terminalId: "term-1",
 } as const;
 const BASE_SNAPSHOT: TerminalSessionSnapshot = {
   history: "hello",
   exitCode: null,
   exitSignal: null,
+  label: "Terminal 1",
   updatedAt: "2026-04-01T00:00:00.000Z",
 };
     const otherTarget = {
       environmentId: EnvironmentId.make("env-remote"),
       threadId: ThreadId.make("thread-1"),
-      terminalId: "default",
+      terminalId: "term-1",
     } as const;
     for (const target of [TARGET, otherTarget]) {
     expect(manager.getSnapshot(otherTarget).buffer).toBe("env-remote");
   });
-  it("lists known sessions for a thread ordered by recency", () => {
+  it("lists known sessions for a thread ordered by terminal id (numeric-aware)", () => {
     const manager = createTerminalSessionManager({
       getRegistry: () => atomRegistry,
     });
       {
         type: "snapshot",
         terminals: [
+          {
+            threadId: TARGET.threadId,
+            terminalId: "term-10",
+            cwd: "/repo",
+            worktreePath: null,
+            status: "running",
+            pid: 125,
+            exitCode: null,
+            exitSignal: null,
+            updatedAt: "2026-04-01T00:00:05.000Z",
+            hasRunningSubprocess: false,
+            label: "Terminal 10",
+          },
           {
             threadId: TARGET.threadId,
             terminalId: TARGET.terminalId,
             exitSignal: null,
             updatedAt: "2026-04-01T00:00:00.000Z",
             hasRunningSubprocess: false,
+            label: "Terminal 1",
           },
           {
             threadId: TARGET.threadId,
             exitSignal: null,
             updatedAt: "2026-04-01T00:00:02.000Z",
             hasRunningSubprocess: false,
+            label: "Terminal 2",
           },
         ],
       },
           threadId: TARGET.threadId,
         })
         .map((session) => session.target.terminalId),
-    ).toEqual(["term-2", "default"]);
+    ).toEqual(["term-1", "term-2", "term-10"]);
   });
   it("drops known sessions when an environment is invalidated", () => {
           exitSignal: null,
           updatedAt: BASE_SNAPSHOT.updatedAt,
           hasRunningSubprocess: false,
+          label: "Terminal 1",
         },
       },
     ]);
           snapshot: {
             ...BASE_SNAPSHOT,
             terminalId: "term-2",
+            label: "Terminal 2",
             updatedAt: "2026-04-01T00:00:02.000Z",
           },
         },
             exitSignal: null,
             updatedAt: "2026-04-01T00:00:05.000Z",
             hasRunningSubprocess: true,
+            label: "Terminal 2",
           },
         ],
       },
           exitSignal: null,
           updatedAt: BASE_SNAPSHOT.updatedAt,
           hasRunningSubprocess: false,
+          label: "Terminal 1",
         },
       },
     ]);
           exitSignal: null,
           updatedAt: "2026-04-01T00:00:05.000Z",
           hasRunningSubprocess: true,
+          label: "Terminal 1",
         },
       },
     ]);
           exitSignal: null,
           updatedAt: BASE_SNAPSHOT.updatedAt,
           hasRunningSubprocess: true,
+          label: "Terminal 1",
         },
       },
     ]);

packages/client-runtime/src/terminalSessionState.ts+6−15

   TerminalSummary,
   EnvironmentId,
 } from "@t3tools/contracts";
-import { DEFAULT_TERMINAL_ID, ThreadId, type TerminalAttachInput } from "@t3tools/contracts";
+import { ThreadId, type TerminalAttachInput } from "@t3tools/contracts";
 import { Atom, type AtomRegistry } from "effect/unstable/reactivity";
 export interface TerminalSessionState {
 export interface TerminalAttachClient {
   readonly terminal: {
     readonly attach: (
-      input: TerminalAttachInput & { readonly terminalId: string },
+      input: TerminalAttachInput,
       listener: (event: TerminalAttachStreamEvent) => void,
       options?: { readonly onResubscribe?: () => void },
     ) => () => void;
       target,
       state: combineSessionState(summary, getBuffer(target)),
     }))
-    .sort((left, right) => {
+    .sort((left, right) =>
-      const leftUpdatedAt = left.state.updatedAt ? Date.parse(left.state.updatedAt) : 0;
+      left.target.terminalId.localeCompare(right.target.terminalId, undefined, { numeric: true }),
-      const rightUpdatedAt = right.state.updatedAt ? Date.parse(right.state.updatedAt) : 0;
+    );
-      if (leftUpdatedAt !== rightUpdatedAt) {
-        return rightUpdatedAt - leftUpdatedAt;
-      }
-      return left.target.terminalId.localeCompare(right.target.terminalId);
-    });
 }
 export const terminalSessionStateAtom = Atom.family((target: KnownTerminalSessionTarget) =>
     readonly onEvent?: (event: TerminalAttachStreamEvent) => void;
     readonly options?: { readonly onResubscribe?: () => void };
   }): () => void {
-    const terminal = {
-      ...input.terminal,
-      terminalId: input.terminal.terminalId ?? DEFAULT_TERMINAL_ID,
-    };
     return input.client.terminal.attach(
-      terminal,
+      input.terminal,
       (event) => {
         applyAttachEvent({ environmentId: input.environmentId }, event);
         input.onEvent?.(event);

packages/contracts/src/terminal.test.ts+43−9

     expect(
       decodes(TerminalOpenInput, {
         threadId: "thread-1",
+        terminalId: DEFAULT_TERMINAL_ID,
         cwd: "/tmp/project",
         cols: 120,
         rows: 40,
     expect(
       decodes(TerminalOpenInput, {
         threadId: "thread-1",
+        terminalId: DEFAULT_TERMINAL_ID,
         cwd: "/tmp/project",
         cols: 10,
         rows: 2,
     ).toBe(false);
   });
-  it("defaults terminalId when missing", () => {
+  it("requires terminalId — the client must always pick an id", () => {
-    const parsed = decodeSync(TerminalOpenInput, {
+    expect(
-      threadId: "thread-1",
+      decodes(TerminalOpenInput, {
-      cwd: "/tmp/project",
+        threadId: "thread-1",
-      cols: 100,
+        cwd: "/tmp/project",
-      rows: 24,
+        cols: 100,
-    });
+        rows: 24,
-    expect(parsed.terminalId).toBe(DEFAULT_TERMINAL_ID);
+      }),
+    ).toBe(false);
   });
   it("accepts optional env overrides", () => {
     const parsed = decodeSync(TerminalOpenInput, {
       threadId: "thread-1",
+      terminalId: DEFAULT_TERMINAL_ID,
       cwd: "/tmp/project",
       worktreePath: "/tmp/project/.t3/worktrees/feature-a",
       cols: 100,
     expect(
       decodes(TerminalWriteInput, {
         threadId: "thread-1",
+        terminalId: DEFAULT_TERMINAL_ID,
         data: "echo hello\n",
       }),
     ).toBe(true);
     expect(
       decodes(TerminalWriteInput, {
         threadId: "thread-1",
+        terminalId: DEFAULT_TERMINAL_ID,
         data: "",
       }),
     ).toBe(false);
   });
+  it("rejects missing terminalId", () => {
+    expect(
+      decodes(TerminalWriteInput, {
+        threadId: "thread-1",
+        data: "echo hello\n",
+      }),
+    ).toBe(false);
+  });
 });
 describe("TerminalThreadInput", () => {
     expect(
       decodes(TerminalResizeInput, {
         threadId: "thread-1",
+        terminalId: DEFAULT_TERMINAL_ID,
         cols: 80,
         rows: 24,
       }),
     ).toBe(true);
   });
+  it("rejects missing terminalId", () => {
+    expect(
+      decodes(TerminalResizeInput, {
+        threadId: "thread-1",
+        cols: 80,
+        rows: 24,
+      }),
+    ).toBe(false);
+  });
 });
 describe("TerminalClearInput", () => {
-  it("defaults terminal id", () => {
+  it("requires terminalId", () => {
+    expect(decodes(TerminalClearInput, { threadId: "thread-1" })).toBe(false);
+  });
+  it("accepts an explicit terminalId", () => {
     const parsed = decodeSync(TerminalClearInput, {
       threadId: "thread-1",
+      terminalId: DEFAULT_TERMINAL_ID,
     });
     expect(parsed.terminalId).toBe(DEFAULT_TERMINAL_ID);
   });
         history: "hello\n",
         exitCode: null,
         exitSignal: null,
+        label: "Primary",
         updatedAt: new Date().toISOString(),
       }),
     ).toBe(true);
         threadId: "thread-1",
         terminalId: DEFAULT_TERMINAL_ID,
         hasRunningSubprocess: true,
+        label: "vim",
       }),
     ).toBe(true);
   });
           history: "",
           exitCode: null,
           exitSignal: null,
+          label: "Primary",
           updatedAt: new Date().toISOString(),
         },
       }),

packages/contracts/src/terminal.ts+14−7

-import { Effect, Schema } from "effect";
+import { Schema } from "effect";
 import { TrimmedNonEmptyString } from "./baseSchemas.ts";
-export const DEFAULT_TERMINAL_ID = "default";
+/**
+ * Client-side id for the first shell opened on a thread. Ids are uniformly
+ * `term-N`; there's no "default" intrinsic. Kept as a named constant so callers
+ * that want "the primary shell" don't hardcode `"term-1"`.
+ */
+export const DEFAULT_TERMINAL_ID = "term-1";
 const TrimmedNonEmptyStringSchema = TrimmedNonEmptyString;
 const TerminalColsSchema = Schema.Int.check(Schema.isGreaterThanOrEqualTo(20)).check(
   Schema.isMaxProperties(128),
 );
-const TerminalIdWithDefaultSchema = TerminalIdSchema.pipe(
-  Schema.withDecodingDefault(Effect.succeed(DEFAULT_TERMINAL_ID)),
-);
 export const TerminalThreadInput = Schema.Struct({
   threadId: TrimmedNonEmptyStringSchema,
 });
 export type TerminalThreadInput = typeof TerminalThreadInput.Type;
+/** Terminal ids are ALWAYS chosen by the client and sent explicitly — no server-side allocation. */
 const TerminalSessionInput = Schema.Struct({
   ...TerminalThreadInput.fields,
-  terminalId: TerminalIdWithDefaultSchema,
+  terminalId: TerminalIdSchema,
 });
 export type TerminalSessionInput = Schema.Codec.Encoded<typeof TerminalSessionInput>;
   history: Schema.String,
   exitCode: Schema.NullOr(Schema.Int),
   exitSignal: Schema.NullOr(Schema.Int),
+  /** Server-computed display title (idle shell vs subprocess command). */
+  label: Schema.String.check(Schema.isMaxLength(128)),
   updatedAt: Schema.String,
   sequence: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
 });
   exitCode: Schema.NullOr(Schema.Int),
   exitSignal: Schema.NullOr(Schema.Int),
   hasRunningSubprocess: Schema.Boolean,
+  /** Server-computed display title (idle shell vs subprocess command). */
+  label: Schema.String.check(Schema.isMaxLength(128)),
   updatedAt: Schema.String,
 });
 export type TerminalSummary = typeof TerminalSummary.Type;
   ...TerminalEventBaseSchema.fields,
   type: Schema.Literal("activity"),
   hasRunningSubprocess: Schema.Boolean,
+  label: Schema.String.check(Schema.isMaxLength(128)),
 });
 export const TerminalEvent = Schema.Union([

packages/shared/package.json+4−0

     "./composerTrigger": {
       "types": "./src/composerTrigger.ts",
       "import": "./src/composerTrigger.ts"
+    },
+    "./terminalLabels": {
+      "types": "./src/terminalLabels.ts",
+      "import": "./src/terminalLabels.ts"
     }
   },
   "scripts": {

packages/shared/src/terminalLabels.test.ts+54−0

@@ -0,0 +1,54 @@
	1	import { describe, expect, it } from "vitest";
	2
	3	import type { TerminalSummary } from "@t3tools/contracts";
	4	import { DEFAULT_TERMINAL_ID } from "@t3tools/contracts";
	5
	6	import { getTerminalLabel, nextTerminalId, resolveTerminalSessionLabel } from "./terminalLabels.ts";
	7
	8	describe("getTerminalLabel", () => {
	9	it("uses the numeric suffix for term-* ids", () => {
	10	expect(getTerminalLabel(DEFAULT_TERMINAL_ID)).toBe("Terminal 1");
	11	expect(getTerminalLabel("term-2")).toBe("Terminal 2");
	12	expect(getTerminalLabel("term-12")).toBe("Terminal 12");
	13	expect(getTerminalLabel("terminal-3")).toBe("Terminal 3");
	14	});
	15
	16	it("falls back to the raw id for unknown shapes", () => {
	17	expect(getTerminalLabel("custom-session")).toBe("custom-session");
	18	});
	19	});
	20
	21	describe("resolveTerminalSessionLabel", () => {
	22	it("prefers a non-empty summary label", () => {
	23	const summary = { label: " bun " } as Pick<TerminalSummary, "label">;
	24	expect(resolveTerminalSessionLabel("term-1", summary)).toBe("bun");
	25	});
	26
	27	it("falls back to getTerminalLabel when summary is missing or blank", () => {
	28	expect(resolveTerminalSessionLabel(DEFAULT_TERMINAL_ID, { label: " " })).toBe("Terminal 1");
	29	expect(resolveTerminalSessionLabel(DEFAULT_TERMINAL_ID, null)).toBe("Terminal 1");
	30	expect(resolveTerminalSessionLabel("term-2", undefined)).toBe("Terminal 2");
	31	});
	32	});
	33
	34	describe("nextTerminalId", () => {
	35	it("allocates term-1 when no terminals are listed yet", () => {
	36	expect(nextTerminalId([])).toBe(DEFAULT_TERMINAL_ID);
	37	expect(nextTerminalId([])).toBe("term-1");
	38	});
	39
	40	it("allocates term-2 when only term-1 exists", () => {
	41	expect(nextTerminalId([DEFAULT_TERMINAL_ID])).toBe("term-2");
	42	});
	43
	44	it("skips over taken term-N slots", () => {
	45	expect(nextTerminalId([DEFAULT_TERMINAL_ID, "term-2", "term-3"])).toBe("term-4");
	46	expect(nextTerminalId([DEFAULT_TERMINAL_ID, "term-3"])).toBe("term-2");
	47	expect(nextTerminalId(["term-2", "term-3"])).toBe("term-1");
	48	});
	49
	50	it("ignores blank/whitespace-only ids", () => {
	51	expect(nextTerminalId(["", " ", DEFAULT_TERMINAL_ID])).toBe("term-2");
	52	expect(nextTerminalId(["", " "])).toBe("term-1");
	53	});
	54	});

packages/shared/src/terminalLabels.ts+40−0

@@ -0,0 +1,40 @@
	1	import type { TerminalSummary } from "@t3tools/contracts";
	2
	3	/** Human-readable label for a terminal tab; matches mobile and web sidebars. */
	4	export function getTerminalLabel(terminalId: string): string {
	5	const numericSuffix = /^term(?:inal)?-(\d+)$/i.exec(terminalId)?.[1];
	6	if (numericSuffix) {
	7	return `Terminal ${numericSuffix}`;
	8	}
	9
	10	return terminalId;
	11	}
	12
	13	/** Prefer server summary label when present; otherwise fall back to `getTerminalLabel`. */
	14	export function resolveTerminalSessionLabel(
	15	terminalId: string,
	16	summary: Pick<TerminalSummary, "label"> \| null \| undefined,
	17	): string {
	18	const trimmed = summary?.label?.trim();
	19	if (trimmed && trimmed.length > 0) {
	20	return trimmed;
	21	}
	22	return getTerminalLabel(terminalId);
	23	}
	24
	25	/**
	26	* Client-side terminal id allocator. Ids are ALWAYS chosen by the client and sent explicitly
	27	* on every `terminal.open` / `terminal.attach` call — the server never allocates.
	28	*
	29	* Returns the lowest unused `term-N` id (starting at `term-1`), skipping any ids already in
	30	* `existingTerminalIds`.
	31	*/
	32	export function nextTerminalId(existingTerminalIds: ReadonlyArray<string>): string {
	33	const usedIds = new Set(existingTerminalIds.filter((id) => id.trim().length > 0));
	34	let nextIndex = 1;
	35	while (usedIds.has(`term-${nextIndex}`)) {
	36	nextIndex += 1;
	37	}
	38
	39	return `term-${nextIndex}`;
	40	}