Commit cc41482df0232454af0cc5ac2f1afd984e342134 | the-knife

apps/mobile/modules/t3-terminal/android/src/main/java/expo/modules/t3terminal/T3TerminalModule.kt+4

 @@ -30,6 +30,10 @@ class T3TerminalModule : Module() {
         view.focusRequest = focusRequest
       }
+      Prop("readOnly") { view: T3TerminalView, readOnly: Boolean ->
+        view.readOnly = readOnly
+      }
       Prop("autoFocus") { view: T3TerminalView, autoFocus: Boolean ->
         view.autoFocus = autoFocus
       }

apps/mobile/modules/t3-terminal/android/src/main/java/expo/modules/t3terminal/T3TerminalView.kt+17-4

 @@ -100,6 +100,16 @@ class T3TerminalView(context: Context, appContext: AppContext) : ExpoView(contex
       }
     }
+  var readOnly: Boolean = false
+    set(value) {
+      field = value
+      inputView.isEnabled = !value
+      if (value) {
+        inputView.clearFocus()
+        hideKeyboard()
+      }
+    }
   var autoFocus: Boolean = true
     set(value) {
       field = value
 @@ -238,6 +248,7 @@ class T3TerminalView(context: Context, appContext: AppContext) : ExpoView(contex
       InputType.TYPE_TEXT_FLAG_NO_SUGGESTIONS
     inputView.setPadding(0, 0, 0, 0)
     inputView.setOnEditorActionListener { _, actionId, event ->
+      if (readOnly) return@setOnEditorActionListener true
       val isKeyUp = event?.action == KeyEvent.ACTION_UP
       val isImeSend = actionId == EditorInfo.IME_ACTION_SEND && !isKeyUp
       val isHardwareEnter = event?.keyCode == KeyEvent.KEYCODE_ENTER &&
 @@ -252,6 +263,7 @@ class T3TerminalView(context: Context, appContext: AppContext) : ExpoView(contex
       }
     }
     inputView.setOnKeyListener { _, keyCode, event ->
+      if (readOnly) return@setOnKeyListener true
       if (event.action != KeyEvent.ACTION_DOWN) return@setOnKeyListener false
       when {
         keyCode == KeyEvent.KEYCODE_DEL -> {
 @@ -273,11 +285,11 @@ class T3TerminalView(context: Context, appContext: AppContext) : ExpoView(contex
         override fun beforeTextChanged(s: CharSequence?, start: Int, count: Int, after: Int) = Unit
         override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {
+          if (readOnly) return
           if (clearingInput || s == null || count <= 0) return
           val end = (start + count).coerceAtMost(s.length)
-          if (start >= end) return
+          if (start < end) {
-          val insertedText = s.subSequence(start, end).toString()
+            val insertedText = s.subSequence(start, end).toString()
-          if (insertedText.isNotEmpty()) {
             onInput(mapOf("data" to insertedText))
           }
         }
 @@ -390,12 +402,13 @@ class T3TerminalView(context: Context, appContext: AppContext) : ExpoView(contex
   }
   private fun emitResponse(response: ByteArray) {
-    if (response.isNotEmpty()) {
+    if (!readOnly && response.isNotEmpty()) {
       onInput(mapOf("data" to String(response, Charsets.UTF_8)))
     }
   }
   private fun requestKeyboardFocus() {
+    if (readOnly) return
     inputView.requestFocus()
     val inputMethodManager = context.getSystemService(
       Context.INPUT_METHOD_SERVICE

apps/mobile/modules/t3-terminal/ios/T3TerminalModule.swift+4

 @@ -27,6 +27,10 @@ public class T3TerminalModule: Module {
         view.focusRequest = focusRequest
       }
+      Prop("readOnly") { (view: T3TerminalView, readOnly: Bool) in
+        view.readOnly = readOnly
+      }
       Prop("autoFocus") { (view: T3TerminalView, autoFocus: Bool) in
         view.autoFocus = autoFocus
       }

apps/mobile/modules/t3-terminal/ios/T3TerminalView.swift+11-3

 @@ -274,6 +274,14 @@ public final class T3TerminalView: ExpoView, UITextFieldDelegate {
     }
   }
+  var readOnly = false {
+    didSet {
+      if readOnly {
+        inputField.resignFirstResponder()
+      }
+    }
+  }
   var autoFocus = true {
     didSet {
       guard oldValue != autoFocus else { return }
 @@ -610,7 +618,7 @@ public final class T3TerminalView: ExpoView, UITextFieldDelegate {
       guard let input = String(data: bytes, encoding: .utf8), !input.isEmpty else { return }
       DispatchQueue.main.async {
-        view.onInput(["data": input])
+        view.emitInput(input)
       }
     }, userdata)
   }
 @@ -687,13 +695,13 @@ public final class T3TerminalView: ExpoView, UITextFieldDelegate {
   }
   private func requestKeyboardFocus() {
-    guard window != nil else { return }
+    guard window != nil, !readOnly else { return }
     inputField.becomeFirstResponder()
     textInputModeDidChange()
   }
   private func emitInput(_ data: String) {
-    guard !data.isEmpty else { return }
+    guard !readOnly, !data.isEmpty else { return }
     onInput(["data": data])
   }

apps/mobile/src/features/terminal/NativeTerminalSurface.tsx+30-14

 @@ -23,6 +23,7 @@ import {
   type TerminalTheme,
 } from "./terminalTheme";
 import { terminalDebugLog } from "./terminalDebugLog";
+import { useTerminalSurfaceBuffer } from "./useTerminalSurfaceBuffer";
 interface TerminalInputEvent {
   readonly data: string;
 @@ -35,9 +36,10 @@ interface TerminalResizeEvent {
 interface TerminalSurfaceProps extends ViewProps {
   readonly terminalKey: string;
-  readonly buffer: string;
+  readonly buffer: string | null;
   readonly fontSize?: number;
   readonly isRunning: boolean;
+  readonly readOnly?: boolean;
   readonly autoFocus?: boolean;
   readonly keyboardFocusRequest?: number;
   readonly captureRequest?: number;
 @@ -47,6 +49,10 @@ interface TerminalSurfaceProps extends ViewProps {
   readonly onResize: (size: { readonly cols: number; readonly rows: number }) => void;
 }
+type ReadyTerminalSurfaceProps = Omit<TerminalSurfaceProps, "buffer"> & {
+  readonly buffer: string;
+};
 function estimateGridSize(input: {
   readonly width: number;
   readonly height: number;
 @@ -60,14 +66,18 @@ function estimateGridSize(input: {
   };
 }
-const FallbackTerminalSurface = memo(function FallbackTerminalSurface(props: TerminalSurfaceProps) {
+const FallbackTerminalSurface = memo(function FallbackTerminalSurface(
+  props: ReadyTerminalSurfaceProps,
+) {
   const fontSize = props.fontSize ?? MOBILE_TYPOGRAPHY.label.fontSize;
   const inputRef = useRef<TextInputInstance>(null);
   const { themeAppearance, themeId } = useAppearancePreferences();
   const theme = props.theme ?? getMobileTerminalTheme(themeId, themeAppearance);
-  const statusLabel = props.isRunning
+  const statusLabel = props.readOnly
-    ? "Native terminal unavailable. Using text fallback."
+    ? "Viewing terminal output."
-    : "Open terminal to start a shell.";
+    : props.isRunning
+      ? "Native terminal unavailable. Using text fallback."
+      : "Open terminal to start a shell.";
   const handleLayout = (event: LayoutChangeEvent) => {
     const { width, height } = event.nativeEvent.layout;
 @@ -75,14 +85,14 @@ const FallbackTerminalSurface = memo(function FallbackTerminalSurface(props: Ter
   };
   useEffect(() => {
-    if ((props.keyboardFocusRequest ?? 0) > 0) {
+    if (!props.readOnly && (props.keyboardFocusRequest ?? 0) > 0) {
       inputRef.current?.blur();
       const focusFrame = requestAnimationFrame(() => inputRef.current?.focus());
       return () => cancelAnimationFrame(focusFrame);
     }
     return undefined;
-  }, [props.keyboardFocusRequest]);
+  }, [props.keyboardFocusRequest, props.readOnly]);
   return (
     <View
 @@ -135,7 +145,7 @@ const FallbackTerminalSurface = memo(function FallbackTerminalSurface(props: Ter
           autoCapitalize="none"
           autoCorrect={false}
           blurOnSubmit={false}
-          editable={props.isRunning}
+          editable={props.isRunning && !props.readOnly}
           placeholder="type and press return"
           placeholderTextColor={theme.mutedForeground}
           returnKeyType="send"
 @@ -155,9 +165,9 @@ const FallbackTerminalSurface = memo(function FallbackTerminalSurface(props: Ter
           }}
         />
         <Pressable
-          disabled={!props.isRunning}
+          disabled={!props.isRunning || props.readOnly}
           style={({ pressed }) => ({
-            opacity: !props.isRunning ? 0.35 : pressed ? 0.65 : 1,
+            opacity: !props.isRunning || props.readOnly ? 0.35 : pressed ? 0.65 : 1,
             paddingHorizontal: 10,
             paddingVertical: 6,
             borderRadius: 8,
 @@ -175,6 +185,11 @@ const FallbackTerminalSurface = memo(function FallbackTerminalSurface(props: Ter
 });
 export const TerminalSurface = memo(function TerminalSurface(props: TerminalSurfaceProps) {
+  const buffer = useTerminalSurfaceBuffer(props);
+  return <ReadyTerminalSurface {...props} buffer={buffer} />;
+});
+const ReadyTerminalSurface = memo(function ReadyTerminalSurface(props: ReadyTerminalSurfaceProps) {
   const fontSize = props.fontSize ?? MOBILE_TYPOGRAPHY.label.fontSize;
   const { themeAppearance, themeId } = useAppearancePreferences();
   const theme = props.theme ?? getMobileTerminalTheme(themeId, themeAppearance);
 @@ -194,7 +209,7 @@ export const TerminalSurface = memo(function TerminalSurface(props: TerminalSurf
   }, [hasNativeSurface, props.buffer.length, props.isRunning, props.terminalKey]);
   const handleNativeInput = useCallback(
     (event: NativeSyntheticEvent<TerminalInputEvent>) => {
-      if (!props.isRunning) {
+      if (!props.isRunning || props.readOnly) {
         return;
       }
       terminalDebugLog("native:onInput", {
 @@ -202,7 +217,7 @@ export const TerminalSurface = memo(function TerminalSurface(props: TerminalSurf
       });
       onInput(event.nativeEvent.data);
     },
-    [onInput, props.isRunning],
+    [onInput, props.isRunning, props.readOnly],
   );
   const handleNativeResize = useCallback(
     (event: NativeSyntheticEvent<TerminalResizeEvent>) => {
 @@ -219,9 +234,10 @@ export const TerminalSurface = memo(function TerminalSurface(props: TerminalSurf
       <View style={props.style}>
         <NativeTerminalSurfaceView
           appearanceScheme={themeAppearance}
-          autoFocus={props.autoFocus ?? true}
+          autoFocus={!props.readOnly && (props.autoFocus ?? true)}
+          readOnly={props.readOnly ?? false}
           backgroundColor={theme.background}
-          focusRequest={props.isRunning ? (props.keyboardFocusRequest ?? 0) : 0}
+          focusRequest={props.isRunning && !props.readOnly ? (props.keyboardFocusRequest ?? 0) : 0}
           foregroundColor={theme.foreground}
           mutedForegroundColor={theme.mutedForeground}
           terminalKey={props.terminalKey}

apps/mobile/src/features/terminal/ThreadTerminalRouteScreen.tsx+153-137

 @@ -1,4 +1,10 @@
-import { DEFAULT_TERMINAL_ID, EnvironmentId, ThreadId } from "@t3tools/contracts";
+import {
+  AuthTerminalReadScope,
+  AuthTerminalOperateScope,
+  DEFAULT_TERMINAL_ID,
+  EnvironmentId,
+  ThreadId,
+} from "@t3tools/contracts";
 import { type KnownTerminalSession } from "@t3tools/client-runtime/state/terminal";
 import { SymbolView } from "../../components/AppSymbol";
 import { ScreenHeader } from "../../components/ScreenHeader";
 @@ -32,7 +38,10 @@ import { MaterialIconButton } from "../../components/MaterialIconButton";
 import { environmentCatalog } from "../../connection/catalog";
 import { useEnvironmentPresentation } from "../../state/presentation";
 import { terminalEnvironment } from "../../state/terminal";
+import { environmentSession, readEnvironmentScope } from "../../state/session";
+import { useEnvironmentQuery } from "../../state/query";
 import { useAtomCommand } from "../../state/use-atom-command";
+import { uuidv4 } from "../../lib/uuid";
 import { useServerConfigs } from "../../state/entities";
 import { useConnectionsReady } from "../../state/workspace";
 import {
 @@ -79,10 +88,13 @@ import {
 } from "./terminalInput";
 import { createTerminalPasteSession } from "./terminalPaste";
 import { cacheTerminalGridSize, getCachedTerminalGridSize } from "./terminalUiState";
+import { useTerminalGridSync } from "./useTerminalGridSync";
+import { useTerminalLifecycle } from "./useTerminalLifecycle";
 function TerminalHeader(props: {
   readonly subtitle: string;
   readonly isEnvironmentReady: boolean;
+  readonly canOperateTerminal: boolean;
   readonly fontSize: number;
   readonly terminalId: string;
   readonly sessions: ReadonlyArray<TerminalMenuSession>;
 @@ -149,6 +161,7 @@ function TerminalHeader(props: {
                   })),
                   {
                     id: "terminal-new",
+                    disabled: !props.canOperateTerminal,
                     title: "Open new terminal",
                     icon: "plus",
                     subtitle: `Start another shell in ${basename(props.workspaceRoot) ?? "this workspace"}`,
 @@ -260,6 +273,15 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
     ? EnvironmentId.make(routeEnvironmentIdRaw)
     : null;
   const routeThreadId = routeThreadIdRaw ? ThreadId.make(routeThreadIdRaw) : null;
+  const terminalSession = useEnvironmentQuery(
+    routeEnvironmentId === null ? null : environmentSession.sessionStateAtom(routeEnvironmentId),
+  );
+  const isAuthenticated =
+    terminalSession.error === null && terminalSession.data?.authenticated === true;
+  const canOperateTerminal =
+    isAuthenticated && terminalSession.data?.scopes?.includes(AuthTerminalOperateScope) === true;
+  const canReadTerminal =
+    isAuthenticated && terminalSession.data?.scopes?.includes(AuthTerminalReadScope) === true;
   const environment = useEnvironmentPresentation(routeEnvironmentId);
   const isEnvironmentReady = environment.presentation?.connection.phase === "connected";
   const requestedTerminalId = firstRouteParam(params.terminalId);
 @@ -283,18 +305,25 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
           terminalId,
         })
       : null;
-  const knownSessions = useKnownTerminalSessions({
+  const {
+    sessions: knownSessions,
+    isPending: sessionsPending,
+    error: sessionsError,
+  } = useKnownTerminalSessions({
     environmentId: selectedThread?.environmentId ?? null,
     threadId: selectedThread?.id ?? null,
   });
   const runningSession = useMemo(
-    () => pickRunningTerminalSessionForBootstrap(knownSessions),
+    () =>
-    [knownSessions],
+      pickRunningTerminalSessionForBootstrap(knownSessions ?? []) ??
+      (canOperateTerminal ? null : (knownSessions?.[0] ?? null)),
+    [canOperateTerminal, knownSessions],
   );
   const activeKnownSession = useMemo(
-    () => knownSessions.find((session) => session.target.terminalId === terminalId) ?? null,
+    () => knownSessions?.find((session) => session.target.terminalId === terminalId) ?? null,
     [knownSessions, terminalId],
   );
+  const hasTerminalTarget = requestedTerminalId !== null || activeKnownSession !== null;
   const launchTarget = useMemo(
     () =>
       selectedThread
 @@ -418,13 +447,28 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
       terminalId,
     ],
   );
+  const observingTerminal =
+    !canOperateTerminal && canReadTerminal && selectedThread !== null && hasTerminalTarget;
   const terminal = useAttachedTerminalSession({
     environmentId: selectedThread?.environmentId ?? null,
-    terminal: terminalAttachInput,
+    terminal: canOperateTerminal
+      ? terminalAttachInput
+      : observingTerminal
+        ? { threadId: selectedThread.id, terminalId }
+        : null,
   });
   const terminalKey = selectedThread
     ? `${selectedThread.environmentId}:${selectedThread.id}:${terminalId}`
     : terminalId;
+  useTerminalGridSync({
+    environmentId: selectedThread?.environmentId ?? null,
+    threadId: selectedThread?.id ?? null,
+    terminalId,
+    canOperate: canOperateTerminal,
+    terminal,
+    size: lastGridSize,
+    resize: resizeTerminal,
+  });
   const bufferReplayKey = useMemo(
     () => getTerminalBufferReplayKey({ terminalKey, fontSize }),
     [fontSize, terminalKey],
 @@ -439,64 +483,8 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
   });
   const isRunning = terminal.status === "running" || terminal.status === "starting";
-  // When the process ends while this screen is attached (e.g. typing `exit`),
-  // close the session and leave the screen, mirroring the web drawer's
-  // onSessionExited flow. Only react to a running -> exited transition
-  // observed on this screen so already-exited sessions can still be opened
-  // (they restart on attach).
-  const runningTerminalKeyRef = useRef<string | null>(null);
-  const reopenedStaleTerminalKeyRef = useRef<string | null>(null);
   const pendingExitNavigationRef = useRef<string | null>(null);
-  // Attach subscriptions are cached with an idle TTL, so revisiting a
-  // terminal whose session ended while unobserved reuses the stale stream
-  // without a new attach RPC — the server never respawns anything. Detect
-  // that (dead status with processed events, never seen running here) and
-  // issue an explicit open; its snapshot flows into the live subscription.
-  useEffect(() => {
-    if (isRunning) {
-      reopenedStaleTerminalKeyRef.current = null;
-      return;
-    }
-    if (
-      terminalAttachInput === null ||
-      !selectedThread ||
-      (terminal.status !== "closed" && terminal.status !== "exited") ||
-      terminal.version === 0 ||
-      runningTerminalKeyRef.current === terminalKey ||
-      reopenedStaleTerminalKeyRef.current === terminalKey
-    ) {
-      return;
-    }
-    reopenedStaleTerminalKeyRef.current = terminalKey;
-    void openTerminal({
-      environmentId: selectedThread.environmentId,
-      input: {
-        threadId: selectedThread.id,
-        terminalId,
-        cwd: terminalAttachInput.cwd,
-        worktreePath: terminalAttachInput.worktreePath,
-        cols: terminalAttachInput.cols,
-        rows: terminalAttachInput.rows,
-        ...(terminalAttachInput.env ? { env: terminalAttachInput.env } : {}),
-      },
-    }).then((result) => {
-      // Release the guard on failure so a later render can retry the respawn.
-      if (result._tag === "Failure" && reopenedStaleTerminalKeyRef.current === terminalKey) {
-        reopenedStaleTerminalKeyRef.current = null;
-      }
-    });
-  }, [
-    isRunning,
-    openTerminal,
-    selectedThread,
-    terminal.status,
-    terminal.version,
-    terminalAttachInput,
-    terminalId,
-    terminalKey,
-  ]);
   useEffect(() => {
     terminalDebugLog("surface:props", {
       terminalKey,
 @@ -596,7 +584,7 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
     height: state.height,
     isVisible: state.isVisible,
   }));
-  const isAccessoryVisible = keyboardState.isVisible && !isAccessoryDismissed;
+  const isAccessoryVisible = canOperateTerminal && keyboardState.isVisible && !isAccessoryDismissed;
   // Android's terminal owns an EditText; turning off autoFocus also clears its native focus.
   const terminalAutoFocus =
     Platform.OS === "android"
 @@ -624,7 +612,7 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
   const terminalMenuSessions = useMemo<ReadonlyArray<TerminalMenuSession>>(
     () =>
       buildTerminalMenuSessions({
-        knownSessions,
+        knownSessions: knownSessions ?? [],
         workspaceRoot: selectedThreadProject?.workspaceRoot ?? null,
         currentSession: {
           terminalId,
 @@ -707,8 +695,10 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
   useEffect(() => {
     const initialInput = pendingLaunch?.initialInput;
     if (
+      !canOperateTerminal ||
       !initialInput ||
       !selectedThread ||
+      !readEnvironmentScope(selectedThread.environmentId, AuthTerminalOperateScope) ||
       terminal.version === 0 ||
       sentInitialInputKeyRef.current === launchTargetKey
     ) {
 @@ -730,6 +720,7 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
     terminal.version,
     terminalId,
     writeTerminal,
+    canOperateTerminal,
   ]);
   useEffect(() => {
 @@ -795,7 +786,11 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
   /** Resolves true once the pty accepted the write, false if it was skipped or rejected. */
   const writeInput = useCallback(
     async (data: string): Promise<boolean> => {
-      if (!selectedThread || !isRunning) {
+      if (
+        !selectedThread ||
+        !isRunning ||
+        !readEnvironmentScope(selectedThread.environmentId, AuthTerminalOperateScope)
+      ) {
         return false;
       }
 @@ -820,11 +815,11 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
   // Drop delayed clipboard reads whenever the route or attached pty changes.
   useEffect(() => {
-    pasteSession.reset(isRunning);
+    pasteSession.reset(canOperateTerminal && isRunning);
     return () => {
       pasteSession.reset(false);
     };
-  }, [isRunning, pasteSession, terminal.lifecycleVersion, terminalKey]);
+  }, [canOperateTerminal, isRunning, pasteSession, terminal.lifecycleVersion, terminalKey]);
   const pasteFromClipboard = useCallback(async () => {
     await pasteSession.paste({
 @@ -896,31 +891,15 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
       }
       setLastGridSize(size);
-      if (!selectedThread || !isRunning) {
-        return;
-      }
-      void resizeTerminal({
-        environmentId: selectedThread.environmentId,
-        input: {
-          threadId: selectedThread.id,
-          terminalId,
-          cols: size.cols,
-          rows: size.rows,
-        },
-      });
     },
     [
-      isRunning,
       lastGridSize.cols,
       lastGridSize.rows,
       bufferReplayKey,
       readyBufferReplayKey,
       routeEnvironmentId,
       routeThreadId,
-      resizeTerminal,
       scheduleBufferReplayReady,
-      selectedThread,
       terminalId,
       terminalKey,
     ],
 @@ -989,59 +968,54 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
     }
   }, [navigation, selectedThread, terminalId, terminalMenuSessions]);
-  useEffect(() => {
+  useTerminalLifecycle({
-    // Detached (hidden surface or environment drop): forget the running
+    terminalKey,
-    // marker so a reattach takes the stale-reopen path instead of misreading
+    canOperate: canOperateTerminal,
-    // the dead snapshot as an exit observed on this screen. A pending exit
+    observing: observingTerminal,
-    // navigation stays armed — it only clears once the session runs again —
+    attached: terminalAttachInput !== null && selectedThread !== null,
-    // so refocusing a dead screen still leaves it.
+    terminal,
-    if (terminalAttachInput === null) {
+    reopen: async () => {
-      runningTerminalKeyRef.current = null;
+      if (
-      return;
+        terminalAttachInput === null ||
-    }
+        selectedThread === null ||
-    if (isRunning) {
+        !readEnvironmentScope(selectedThread.environmentId, AuthTerminalOperateScope)
-      runningTerminalKeyRef.current = terminalKey;
+      )
-      // The session came back (e.g. respawned elsewhere) before the user
+        return false;
-      // returned; a stale pending exit must not eject a live terminal.
+      const result = await openTerminal({
-      pendingExitNavigationRef.current = null;
-      return;
-    }
-    // The web drawer treats both exited and closed as session end.
-    const sessionEnded = terminal.status === "exited" || terminal.status === "closed";
-    if (!sessionEnded || runningTerminalKeyRef.current !== terminalKey) {
-      return;
-    }
-    runningTerminalKeyRef.current = null;
-    // Mark this key handled so the stale-attach effect doesn't respawn the
-    // session the user just ended.
-    reopenedStaleTerminalKeyRef.current = terminalKey;
-    if (selectedThread) {
-      void closeTerminal({
         environmentId: selectedThread.environmentId,
         input: {
           threadId: selectedThread.id,
           terminalId,
+          cwd: terminalAttachInput.cwd,
+          worktreePath: terminalAttachInput.worktreePath,
+          cols: terminalAttachInput.cols,
+          rows: terminalAttachInput.rows,
+          ...(terminalAttachInput.env ? { env: terminalAttachInput.env } : {}),
         },
       });
-    }
+      return result._tag === "Success";
-    if (navigation.isFocused()) {
+    },
-      navigateAwayAfterExit();
+    onRunning: () => {
-      return;
+      pendingExitNavigationRef.current = null;
-    }
+    },
-    // An unfocused screen can't navigate; leave when the user returns so
+    onExit: () => {
-    // they never land on the dead session.
+      if (
-    pendingExitNavigationRef.current = terminalKey;
+        selectedThread === null ||
-  }, [
+        !readEnvironmentScope(selectedThread.environmentId, AuthTerminalOperateScope)
-    closeTerminal,
+      )
-    isRunning,
+        return;
-    navigateAwayAfterExit,
+      void closeTerminal({
-    navigation,
+        environmentId: selectedThread.environmentId,
-    selectedThread,
+        input: { threadId: selectedThread.id, terminalId },
-    terminal.status,
+      });
-    terminalAttachInput,
+      if (navigation.isFocused()) {
-    terminalId,
+        navigateAwayAfterExit();
-    terminalKey,
+        return;
-  ]);
+      }
+      // Leave a background terminal screen when it is focused again.
+      pendingExitNavigationRef.current = terminalKey;
+    },
+  });
   useEffect(
     () =>
 @@ -1056,7 +1030,10 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
   );
   const handleOpenNewTerminal = useCallback(() => {
-    if (!selectedThread) {
+    if (
+      !selectedThread ||
+      !readEnvironmentScope(selectedThread.environmentId, AuthTerminalOperateScope)
+    ) {
       return;
     }
 @@ -1067,10 +1044,14 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
         terminalId: nextOpenTerminalId({
           listedTerminalIds: terminalMenuSessions.map((session) => session.terminalId),
           activeRouteTerminalId: terminalId,
+          ...(knownSessions === null ||
+          !readEnvironmentScope(selectedThread.environmentId, AuthTerminalReadScope)
+            ? { uniqueSuffix: uuidv4() }
+            : {}),
         }),
       }),
     );
-  }, [navigation, selectedThread, terminalId, terminalMenuSessions]);
+  }, [knownSessions, navigation, selectedThread, terminalId, terminalMenuSessions]);
   const handleDecreaseFontSize = useCallback(() => {
     setTerminalFontSize(stepTerminalFontSize(fontSize, -1));
 @@ -1081,7 +1062,10 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
   }, [fontSize, setTerminalFontSize]);
   const handleClearTerminal = useCallback(() => {
-    if (!selectedThread) {
+    if (
+      !selectedThread ||
+      !readEnvironmentScope(selectedThread.environmentId, AuthTerminalOperateScope)
+    ) {
       return;
     }
 @@ -1130,9 +1114,10 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
   }, []);
   const handleShowKeyboard = useCallback(() => {
+    if (!canOperateTerminal) return;
     setIsAccessoryDismissed(false);
     setKeyboardFocusRequest((current) => current + 1);
-  }, []);
+  }, [canOperateTerminal]);
   const handleRetryEnvironment = useCallback(() => {
     if (routeEnvironmentId !== null) {
       void retryEnvironment(routeEnvironmentId);
 @@ -1186,6 +1171,7 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
         />
       ) : null}
       <TerminalHeader
+        canOperateTerminal={canOperateTerminal}
         subtitle={headerSubtitle}
         isEnvironmentReady={isEnvironmentReady}
         fontSize={fontSize}
 @@ -1232,6 +1218,34 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
               resourceName="terminal"
               onRetry={handleRetryEnvironment}
             />
+          ) : terminalSession.data === null && terminalSession.error === null ? (
+            <EmptyState
+              title="Checking terminal access"
+              detail="Waiting for this connection's permissions."
+            />
+          ) : !canReadTerminal && !canOperateTerminal ? (
+            <EmptyState
+              title={
+                terminalSession.error
+                  ? "Could not check terminal access"
+                  : "Terminal access unavailable"
+              }
+              detail={
+                terminalSession.error ??
+                "This connection does not have permission to view terminals."
+              }
+            />
+          ) : !canOperateTerminal && !hasTerminalTarget && sessionsPending ? (
+            <EmptyState title="Loading terminals" detail="Reading existing terminal sessions." />
+          ) : !canOperateTerminal && !hasTerminalTarget && sessionsError !== null ? (
+            <EmptyState title="Could not load terminals" detail={sessionsError} />
+          ) : !canOperateTerminal && !hasTerminalTarget ? (
+            <EmptyState
+              title="No terminal sessions"
+              detail="Existing terminals will appear here when another client opens one."
+            />
+          ) : !canOperateTerminal && terminal.error !== null ? (
+            <EmptyState title="Terminal unavailable" detail={terminal.error} />
           ) : (
             <>
               <View
 @@ -1249,8 +1263,9 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
                   }}
                 />
                 <TerminalSurface
-                  autoFocus={terminalAutoFocus}
+                  autoFocus={canOperateTerminal && terminalAutoFocus}
-                  buffer={terminalSurfaceBuffer}
+                  readOnly={!canOperateTerminal}
+                  buffer={terminal.version === 0 ? null : terminalSurfaceBuffer}
                   fontSize={fontSize}
                   isRunning={isRunning}
                   keyboardFocusRequest={keyboardFocusRequest}
 @@ -1279,6 +1294,7 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
                   <View className="flex-1" />
                   <MaterialIconButton
                     accessibilityLabel="Show keyboard"
+                    disabled={!canOperateTerminal}
                     icon="keyboard"
                     onPress={handleShowKeyboard}
                   />
 @@ -1345,7 +1361,7 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
                     </ComposerToolbarRow>
                   </View>
                 </KeyboardStickyView>
-              ) : !keyboardState.isVisible && Platform.OS !== "android" ? (
+              ) : canOperateTerminal && !keyboardState.isVisible && Platform.OS !== "android" ? (
                 <Pressable
                   accessibilityLabel="Show keyboard"
                   accessibilityRole="button"

apps/mobile/src/features/terminal/nativeTerminalModule.ts+1

...	@@ -24,6 +24,7 @@ interface TerminalResizeEvent {	...	@@ -24,6 +24,7 @@ interface TerminalResizeEvent {
24	export interface NativeTerminalSurfaceProps extends ViewProps {	24	export interface NativeTerminalSurfaceProps extends ViewProps {
25	readonly appearanceScheme?: "light" \| "dark";	25	readonly appearanceScheme?: "light" \| "dark";
26	readonly autoFocus?: boolean;	26	readonly autoFocus?: boolean;
		27	readonly readOnly?: boolean;
27	readonly focusRequest?: number;	28	readonly focusRequest?: number;
28	readonly captureRequest?: number;	29	readonly captureRequest?: number;
29	readonly onCapture?: (event: NativeSyntheticEvent<{ readonly text: string }>) => void;	30	readonly onCapture?: (event: NativeSyntheticEvent<{ readonly text: string }>) => void;

apps/mobile/src/features/terminal/terminalMenu.test.ts+23

...	@@ -129,6 +129,19 @@ describe("buildTerminalMenuSessions", () => {	...	@@ -129,6 +129,19 @@ describe("buildTerminalMenuSessions", () => {
129	});	129	});
130		130
131	describe("nextOpenTerminalId", () => {	131	describe("nextOpenTerminalId", () => {
		132	it("allocates separate terminals on repeated visits without readable metadata", () => {
		133	const first = nextOpenTerminalId({
		134	listedTerminalIds: [],
		135	uniqueSuffix: "783c91cc-a413-47c7-8312-c2a5a1f05e40",
		136	});
		137	const nextVisit = nextOpenTerminalId({
		138	listedTerminalIds: [],
		139	uniqueSuffix: "102315fc-ceef-45c4-b978-c4d4947d3c26",
		140	});
		141	expect(first).not.toBe(DEFAULT_TERMINAL_ID);
		142	expect(nextVisit).not.toBe(first);
		143	});
		144
132	it("matches nextTerminalId when not on a terminal route", () => {	145	it("matches nextTerminalId when not on a terminal route", () => {
133	expect(nextOpenTerminalId({ listedTerminalIds: [] })).toBe(DEFAULT_TERMINAL_ID);	146	expect(nextOpenTerminalId({ listedTerminalIds: [] })).toBe(DEFAULT_TERMINAL_ID);
134	expect(nextOpenTerminalId({ listedTerminalIds: [DEFAULT_TERMINAL_ID] })).toBe("term-2");	147	expect(nextOpenTerminalId({ listedTerminalIds: [DEFAULT_TERMINAL_ID] })).toBe("term-2");
...	@@ -208,6 +221,16 @@ describe("previousLiveTerminalId", () => {	...	@@ -208,6 +221,16 @@ describe("previousLiveTerminalId", () => {
208	});	221	});
209		222
210	describe("resolveProjectScriptTerminalId", () => {	223	describe("resolveProjectScriptTerminalId", () => {
		224	it("never targets an unseen default terminal when metadata is unavailable", () => {
		225	const terminalId = resolveProjectScriptTerminalId({
		226	existingTerminalIds: [],
		227	hasRunningTerminal: false,
		228	uniqueSuffix: "783c91cc-a413-47c7-8312-c2a5a1f05e40",
		229	});
		230	expect(terminalId).not.toBe(DEFAULT_TERMINAL_ID);
		231	expect(getTerminalLabel(terminalId)).toBe("Terminal 1");
		232	});
		233
211	it("reuses the default shell when no terminal is running", () => {	234	it("reuses the default shell when no terminal is running", () => {
212	expect(	235	expect(
213	resolveProjectScriptTerminalId({	236	resolveProjectScriptTerminalId({

apps/mobile/src/features/terminal/terminalMenu.ts+6-4

 @@ -70,15 +70,16 @@ export function getTerminalStatusLabel(input: {
 export function nextOpenTerminalId(input: {
   readonly listedTerminalIds: ReadonlyArray<string>;
   readonly activeRouteTerminalId?: string | null;
+  readonly uniqueSuffix?: string;
 }): 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 nextTerminalId(listed, input.uniqueSuffix);
   }
-  return nextTerminalId([...listed, routeId]);
+  return nextTerminalId([...listed, routeId], input.uniqueSuffix);
 }
 export function buildTerminalMenuSessions(input: {
 @@ -146,12 +147,13 @@ export function previousLiveTerminalId(input: {
 export function resolveProjectScriptTerminalId(input: {
   readonly existingTerminalIds: ReadonlyArray<string>;
   readonly hasRunningTerminal: boolean;
+  readonly uniqueSuffix?: string;
 }): string {
-  if (!input.hasRunningTerminal) {
+  if (!input.hasRunningTerminal && input.uniqueSuffix === undefined) {
     return DEFAULT_TERMINAL_ID;
   }
-  return nextTerminalId(input.existingTerminalIds);
+  return nextTerminalId(input.existingTerminalIds, input.uniqueSuffix);
 }
 export function projectScriptMenuLabel(script: ProjectScript): string {

apps/mobile/src/features/terminal/useTerminalGridSync.test.ts created+183

...	@@ -0,0 +1,183 @@
1	import * as NodeModule from "node:module";
2	import { EMPTY_TERMINAL_BUFFER_STATE } from "@t3tools/client-runtime/state/terminal";
3	import { EnvironmentId, ThreadId } from "@t3tools/contracts";
4	import { act, createElement, type ReactNode } from "react";
5	import { afterEach, beforeEach, expect, it, vi } from "vite-plus/test";
6
7	import { useTerminalGridSync } from "./useTerminalGridSync";
8
9	const access = vi.hoisted(() => ({ environments: new Set<string>() }));
10	vi.mock("../../state/session", () => ({
11	readEnvironmentScope: (environmentId: string, scope: string) =>
12	scope === "terminal:operate" && access.environments.has(environmentId),
13	}));
14
15	// Mobile already depends on ReactDOM but does not install its browser type declarations.
16	const { createRoot } = NodeModule.createRequire(import.meta.url)("react-dom/client") as {
17	createRoot(container: Element): {
18	render(children: ReactNode): void;
19	unmount(): void;
20	};
21	};
22
23	type Input = Parameters<typeof useTerminalGridSync>[0];
24	let root: ReturnType<typeof createRoot>;
25	const resize = vi.fn<Input["resize"]>();
26
27	function GridProbe(input: Input) {
28	useTerminalGridSync(input);
29	return null;
30	}
31
32	function session({
33	generation = 1,
34	version = 1,
35	status = "running",
36	}: {
37	readonly generation?: number;
38	readonly version?: number;
39	readonly status?: Input["terminal"]["status"];
40	} = {}): Input["terminal"] {
41	return { output: { ...EMPTY_TERMINAL_BUFFER_STATE.output, generation }, version, status };
42	}
43
44	function input(): Input {
45	return {
46	environmentId: EnvironmentId.make("environment"),
47	threadId: ThreadId.make("thread"),
48	terminalId: "term-1",
49	canOperate: true,
50	terminal: session(),
51	size: { cols: 80, rows: 24 },
52	resize,
53	};
54	}
55
56	function render(value: Input) {
57	return act(() => root.render(createElement(GridProbe, value)));
58	}
59
60	beforeEach(() => {
61	resize.mockClear();
62	access.environments.clear();
63	access.environments.add("environment");
64	// The probe renders no DOM, but ReactDOM needs an event target to run real effects.
65	const document = {
66	nodeType: 9,
67	addEventListener() {},
68	removeEventListener() {},
69	};
70	const container = {
71	nodeType: 1,
72	tagName: "DIV",
73	namespaceURI: "http://www.w3.org/1999/xhtml",
74	ownerDocument: document,
75	addEventListener() {},
76	removeEventListener() {},
77	};
78	vi.stubGlobal("document", document);
79	vi.stubGlobal("window", { document, HTMLIFrameElement: EventTarget });
80	vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
81	root = createRoot(container as unknown as HTMLElement);
82	});
83
84	it("checks the current target grant before dispatching a delayed resize", async () => {
85	const current = input();
86	await render(current);
87	expect(resize).toHaveBeenCalledOnce();
88
89	access.environments.clear();
90	await render({ ...current, size: { cols: 120, rows: 40 } });
91	expect(resize).toHaveBeenCalledOnce();
92
93	access.environments.add("secondary");
94	await render({ ...current, size: { cols: 120, rows: 41 } });
95	expect(resize).toHaveBeenCalledOnce();
96
97	await render({ ...current, environmentId: EnvironmentId.make("secondary") });
98	expect(resize).toHaveBeenCalledTimes(2);
99	expect(resize).toHaveBeenLastCalledWith({
100	environmentId: "secondary",
101	input: { threadId: "thread", terminalId: "term-1", cols: 80, rows: 24 },
102	});
103	});
104
105	afterEach(async () => {
106	await act(() => root.unmount());
107	vi.unstubAllGlobals();
108	});
109
110	it("replays an observer's measured grid once its writable attachment snapshot arrives", async () => {
111	let current = { ...input(), canOperate: false };
112	await render(current);
113	current = { ...current, size: { cols: 120, rows: 40 } };
114	await render(current);
115	expect(resize).not.toHaveBeenCalled();
116
117	current = {
118	...current,
119	canOperate: true,
120	terminal: session({ generation: 2, version: 0 }),
121	};
122	await render(current);
123	expect(resize).not.toHaveBeenCalled();
124
125	current = { ...current, terminal: session({ generation: 2 }) };
126	await render(current);
127	expect(resize).toHaveBeenCalledExactlyOnceWith({
128	environmentId: "environment",
129	input: { threadId: "thread", terminalId: "term-1", cols: 120, rows: 40 },
130	});
131
132	await render({ ...current, terminal: session({ generation: 2, version: 3 }) });
133	await render({ ...current, size: { ...current.size } });
134	expect(resize).toHaveBeenCalledOnce();
135
136	await render({ ...current, size: { cols: 120, rows: 41 } });
137	expect(resize).toHaveBeenCalledTimes(2);
138	expect(resize).toHaveBeenLastCalledWith({
139	environmentId: "environment",
140	input: { threadId: "thread", terminalId: "term-1", cols: 120, rows: 41 },
141	});
142	});
143
144	it("replays an unchanged grid after reconnecting with a new attachment generation", async () => {
145	const current = { ...input(), size: { cols: 120, rows: 40 } };
146	await render(current);
147	expect(resize).toHaveBeenCalledOnce();
148
149	await render({ ...current, terminal: session({ generation: 2, version: 0 }) });
150	expect(resize).toHaveBeenCalledOnce();
151
152	await render({ ...current, terminal: session({ generation: 2 }) });
153	expect(resize).toHaveBeenCalledTimes(2);
154	expect(resize).toHaveBeenLastCalledWith({
155	environmentId: "environment",
156	input: { threadId: "thread", terminalId: "term-1", cols: 120, rows: 40 },
157	});
158
159	// React may observe the next snapshot without rendering the empty seed first.
160	await render({ ...current, terminal: session({ generation: 3 }) });
161	expect(resize).toHaveBeenCalledTimes(3);
162	});
163
164	it.each([
165	{ name: "permission is revoked", change: { canOperate: false } },
166	{ name: "the attachment is pending", change: { terminal: session({ version: 0 }) } },
167	{ name: "the process has exited", change: { terminal: session({ status: "exited" }) } },
168	])("retains measurements without resizing while $name", async ({ change }) => {
169	const current = input();
170	await render(current);
171	expect(resize).toHaveBeenCalledOnce();
172
173	await render({ ...current, ...change, size: { cols: 120, rows: 40 } });
174	await render({ ...current, ...change, size: { cols: 120, rows: 41 } });
175	expect(resize).toHaveBeenCalledOnce();
176
177	await render({ ...current, size: { cols: 120, rows: 41 } });
178	expect(resize).toHaveBeenCalledTimes(2);
179	expect(resize).toHaveBeenLastCalledWith({
180	environmentId: "environment",
181	input: { threadId: "thread", terminalId: "term-1", cols: 120, rows: 41 },
182	});
183	});

apps/mobile/src/features/terminal/useTerminalGridSync.ts created+52

...	@@ -0,0 +1,52 @@
1	import type { TerminalSessionState } from "@t3tools/client-runtime/state/terminal";
2	import {
3	AuthTerminalOperateScope,
4	type EnvironmentId,
5	type TerminalResizeInput,
6	type ThreadId,
7	} from "@t3tools/contracts";
8	import { useEffect } from "react";
9
10	import type { TerminalGridSize } from "./terminalUiState";
11	import { readEnvironmentScope } from "../../state/session";
12
13	/** Replay the measured grid when a writable attachment becomes ready or reconnects. */
14	export function useTerminalGridSync({
15	environmentId,
16	threadId,
17	terminalId,
18	canOperate,
19	terminal,
20	size,
21	resize,
22	}: {
23	readonly environmentId: EnvironmentId \| null;
24	readonly threadId: ThreadId \| null;
25	readonly terminalId: string;
26	readonly canOperate: boolean;
27	readonly terminal: Pick<TerminalSessionState, "output" \| "status" \| "version">;
28	readonly size: TerminalGridSize;
29	readonly resize: (target: {
30	readonly environmentId: EnvironmentId;
31	readonly input: TerminalResizeInput;
32	}) => void;
33	}): void {
34	const generation =
35	canOperate && terminal.version > 0 && terminal.status === "running"
36	? terminal.output.generation
37	: null;
38
39	useEffect(() => {
40	if (
41	generation === null \|\|
42	environmentId === null \|\|
43	threadId === null \|\|
44	!readEnvironmentScope(environmentId, AuthTerminalOperateScope)
45	)
46	return;
47	resize({
48	environmentId,
49	input: { threadId, terminalId, cols: size.cols, rows: size.rows },
50	});
51	}, [environmentId, generation, resize, size.cols, size.rows, terminalId, threadId]);
52	}

apps/mobile/src/features/terminal/useTerminalLifecycle.test.ts created+177

...	@@ -0,0 +1,177 @@
1	import * as NodeModule from "node:module";
2	import { act, createElement, type ReactNode } from "react";
3	import { afterEach, beforeEach, expect, it, vi } from "vite-plus/test";
4
5	import { useTerminalLifecycle } from "./useTerminalLifecycle";
6
7	const { createRoot } = NodeModule.createRequire(import.meta.url)("react-dom/client") as {
8	createRoot(container: Element): {
9	render(children: ReactNode): void;
10	unmount(): void;
11	};
12	};
13
14	type Input = Parameters<typeof useTerminalLifecycle>[0];
15	let root: ReturnType<typeof createRoot>;
16	const reopen = vi.fn<Input["reopen"]>();
17	const onRunning = vi.fn<Input["onRunning"]>();
18	const onExit = vi.fn<Input["onExit"]>();
19
20	function LifecycleProbe(input: Input) {
21	useTerminalLifecycle(input);
22	return null;
23	}
24
25	function input(changes: Partial<Input> = {}): Input {
26	return {
27	terminalKey: "environment:thread:term-1",
28	canOperate: true,
29	observing: false,
30	attached: true,
31	terminal: { status: "running", version: 1 },
32	reopen,
33	onRunning,
34	onExit,
35	...changes,
36	};
37	}
38
39	function render(value: Input) {
40	return act(() => root.render(createElement(LifecycleProbe, value)));
41	}
42
43	beforeEach(() => {
44	reopen.mockReset().mockResolvedValue(true);
45	onRunning.mockClear();
46	onExit.mockClear();
47	const document = {
48	nodeType: 9,
49	addEventListener() {},
50	removeEventListener() {},
51	};
52	const container = {
53	nodeType: 1,
54	tagName: "DIV",
55	namespaceURI: "http://www.w3.org/1999/xhtml",
56	ownerDocument: document,
57	addEventListener() {},
58	removeEventListener() {},
59	};
60	vi.stubGlobal("document", document);
61	vi.stubGlobal("window", { document, HTMLIFrameElement: EventTarget });
62	vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
63	root = createRoot(container as unknown as HTMLElement);
64	});
65
66	afterEach(async () => {
67	await act(() => root.unmount());
68	vi.unstubAllGlobals();
69	});
70
71	it.each(["running", "closed", "exited"] as const)(
72	"waits for the replacement attachment snapshot before handling %s",
73	async (status) => {
74	await render(input());
75	await render(input({ terminal: { status: "closed", version: 0 } }));
76	expect(onExit).not.toHaveBeenCalled();
77	expect(reopen).not.toHaveBeenCalled();
78
79	await render(input({ terminal: { status, version: 1 } }));
80	expect(onExit).toHaveBeenCalledTimes(status === "running" ? 0 : 1);
81	expect(reopen).not.toHaveBeenCalled();
82	},
83	);
84
85	it("retains an exited observer's history after gaining operate", async () => {
86	await render(input({ canOperate: false, terminal: { status: "exited", version: 1 } }));
87	await render(input({ terminal: { status: "closed", version: 0 } }));
88	await render(input({ terminal: { status: "exited", version: 1 } }));
89	expect(reopen).not.toHaveBeenCalled();
90	expect(onExit).not.toHaveBeenCalled();
91	});
92
93	it.each(["closed", "exited"] as const)(
94	"keeps a pending observer passive when its first writable snapshot is %s",
95	async (status) => {
96	await render(
97	input({
98	canOperate: false,
99	observing: true,
100	terminal: { status, version: 0 },
101	}),
102	);
103	await render(input({ terminal: { status: "closed", version: 0 } }));
104	await render(input({ terminal: { status, version: 1 } }));
105	expect(reopen).not.toHaveBeenCalled();
106	expect(onExit).not.toHaveBeenCalled();
107	expect(onRunning).not.toHaveBeenCalled();
108	},
109	);
110
111	it("reopens an explicit operator visit after permissions finish loading", async () => {
112	await render(
113	input({
114	canOperate: false,
115	observing: false,
116	terminal: { status: "closed", version: 0 },
117	}),
118	);
119	await render(input({ terminal: { status: "closed", version: 0 } }));
120	await render(input({ terminal: { status: "exited", version: 1 } }));
121	expect(reopen).toHaveBeenCalledOnce();
122	expect(onExit).not.toHaveBeenCalled();
123	});
124
125	it("does not respawn a terminal that exited after operate was revoked", async () => {
126	await render(input());
127	await render(input({ canOperate: false }));
128	await render(input({ canOperate: false, terminal: { status: "exited", version: 2 } }));
129	await render(input({ terminal: { status: "exited", version: 1 } }));
130	expect(reopen).not.toHaveBeenCalled();
131	expect(onExit).not.toHaveBeenCalled();
132	});
133
134	it("remembers revocation before the observer has received a snapshot", async () => {
135	await render(input());
136	await render(input({ canOperate: false, terminal: { status: "closed", version: 0 } }));
137	await render(input({ terminal: { status: "exited", version: 1 } }));
138	expect(reopen).not.toHaveBeenCalled();
139	expect(onExit).not.toHaveBeenCalled();
140	});
141
142	it("cleans up an actual exit after an observed running terminal becomes writable", async () => {
143	await render(input({ canOperate: false }));
144	await render(input());
145	await render(input({ terminal: { status: "exited", version: 2 } }));
146	await render(input({ terminal: { status: "closed", version: 3 } }));
147	expect(onExit).toHaveBeenCalledOnce();
148	expect(reopen).not.toHaveBeenCalled();
149	});
150
151	it("reopens an ended terminal on an explicit new route visit", async () => {
152	await render(input({ canOperate: false, terminal: { status: "exited", version: 1 } }));
153	await render(input({ terminalKey: "environment:thread:term-2" }));
154	await render(input({ terminal: { status: "exited", version: 1 } }));
155	expect(reopen).toHaveBeenCalledOnce();
156
157	await render(input({ terminal: { status: "exited", version: 2 } }));
158	expect(reopen).toHaveBeenCalledOnce();
159	await render(input({ terminal: { status: "running", version: 3 } }));
160	await render(input({ terminal: { status: "exited", version: 4 } }));
161	expect(onExit).toHaveBeenCalledOnce();
162	});
163
164	it("keeps a detached terminal from being mistaken for a live exit", async () => {
165	await render(input());
166	await render(input({ attached: false, terminal: { status: "closed", version: 0 } }));
167	await render(input({ terminal: { status: "exited", version: 1 } }));
168	expect(onExit).not.toHaveBeenCalled();
169	expect(reopen).toHaveBeenCalledOnce();
170	});
171
172	it("allows a later snapshot to retry an unsuccessful explicit reopen", async () => {
173	reopen.mockResolvedValueOnce(false);
174	await render(input({ terminal: { status: "exited", version: 1 } }));
175	await render(input({ terminal: { status: "exited", version: 2 } }));
176	expect(reopen).toHaveBeenCalledTimes(2);
177	});

apps/mobile/src/features/terminal/useTerminalLifecycle.ts created+79

...	@@ -0,0 +1,79 @@
1	import type { TerminalSessionState } from "@t3tools/client-runtime/state/terminal";
2	import { useEffect, useEffectEvent, useRef } from "react";
3
4	/** Keep observed history passive while preserving explicit terminal visits and live exits. */
5	export function useTerminalLifecycle({
6	terminalKey,
7	canOperate,
8	observing,
9	attached,
10	terminal,
11	reopen,
12	onRunning,
13	onExit,
14	}: {
15	readonly terminalKey: string;
16	readonly canOperate: boolean;
17	readonly observing: boolean;
18	readonly attached: boolean;
19	readonly terminal: Pick<TerminalSessionState, "status" \| "version">;
20	readonly reopen: () => Promise<boolean>;
21	readonly onRunning: () => void;
22	readonly onExit: () => void;
23	}) {
24	const lifecycle = useRef({
25	key: terminalKey,
26	wasRunning: false,
27	observed: false,
28	reopened: false,
29	});
30	const reopenTerminal = useEffectEvent(reopen);
31	const handleRunning = useEffectEvent(onRunning);
32	const handleExit = useEffectEvent(onExit);
33
34	useEffect(() => {
35	if (lifecycle.current.key !== terminalKey) {
36	lifecycle.current = {
37	key: terminalKey,
38	wasRunning: false,
39	observed: false,
40	reopened: false,
41	};
42	}
43	const current = lifecycle.current;
44	if (!canOperate) {
45	// An observe request stays passive before its first snapshot arrives.
46	if (observing \|\| terminal.version > 0 \|\| current.wasRunning) current.observed = true;
47	current.wasRunning = false;
48	return;
49	}
50	if (!attached) {
51	current.wasRunning = false;
52	return;
53	}
54	// An attachment without its first snapshot has no known process status yet.
55	if (terminal.version === 0) return;
56
57	if (terminal.status === "running" \|\| terminal.status === "starting") {
58	current.wasRunning = true;
59	current.reopened = false;
60	handleRunning();
61	return;
62	}
63	if (terminal.status !== "closed" && terminal.status !== "exited") return;
64
65	if (current.wasRunning) {
66	current.wasRunning = false;
67	current.reopened = true;
68	handleExit();
69	return;
70	}
71	// An explicit visit can reopen a cached ended session. Granting a viewer
72	// operate permission must leave the history they were reading intact.
73	if (current.observed \|\| current.reopened) return;
74	current.reopened = true;
75	void reopenTerminal().then((succeeded) => {
76	if (!succeeded && lifecycle.current === current) current.reopened = false;
77	});
78	}, [attached, canOperate, observing, terminal.status, terminal.version, terminalKey]);
79	}

apps/mobile/src/features/terminal/useTerminalSurfaceBuffer.test.ts created+100

...	@@ -0,0 +1,100 @@
1	import * as NodeModule from "node:module";
2	import { act, createElement, useEffect, type ReactNode } from "react";
3	import { afterEach, beforeEach, expect, it, vi } from "vite-plus/test";
4
5	import { useTerminalSurfaceBuffer } from "./useTerminalSurfaceBuffer";
6
7	const { createRoot } = NodeModule.createRequire(import.meta.url)("react-dom/client") as {
8	createRoot(container: Element): {
9	render(children: ReactNode): void;
10	unmount(): void;
11	};
12	};
13
14	type Input = Parameters<typeof useTerminalSurfaceBuffer>[0] & { readonly readOnly: boolean };
15	let root: ReturnType<typeof createRoot>;
16	const displayed = vi.fn<(value: { buffer: string; readOnly: boolean }) => void>();
17
18	function BufferProbe(input: Input) {
19	const buffer = useTerminalSurfaceBuffer(input);
20	useEffect(() => {
21	displayed({ buffer, readOnly: input.readOnly });
22	}, [buffer, input.readOnly]);
23	return null;
24	}
25
26	function render(changes: Partial<Input> = {}) {
27	return act(() =>
28	root.render(
29	createElement(BufferProbe, {
30	terminalKey: "environment:thread:term-1",
31	buffer: "host output",
32	readOnly: false,
33	...changes,
34	}),
35	),
36	);
37	}
38
39	beforeEach(() => {
40	displayed.mockClear();
41	const document = { nodeType: 9, addEventListener() {}, removeEventListener() {} };
42	const container = {
43	nodeType: 1,
44	tagName: "DIV",
45	namespaceURI: "http://www.w3.org/1999/xhtml",
46	ownerDocument: document,
47	addEventListener() {},
48	removeEventListener() {},
49	};
50	vi.stubGlobal("document", document);
51	vi.stubGlobal("window", { document, HTMLIFrameElement: EventTarget });
52	vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
53	root = createRoot(container as unknown as HTMLElement);
54	});
55
56	afterEach(async () => {
57	await act(() => root.unmount());
58	vi.unstubAllGlobals();
59	});
60
61	it("preserves displayed history while permissions change before the next snapshot", async () => {
62	await render();
63	await render({ buffer: null, readOnly: true });
64	expect(displayed).toHaveBeenLastCalledWith({ buffer: "host output", readOnly: true });
65
66	await render({ buffer: "host output\nobserved output", readOnly: true });
67	await render({ buffer: null });
68	expect(displayed).toHaveBeenLastCalledWith({
69	buffer: "host output\nobserved output",
70	readOnly: false,
71	});
72	expect(displayed.mock.calls.every(([value]) => value.buffer.length > 0)).toBe(true);
73	});
74
75	it("still applies an intentional empty buffer", async () => {
76	await render();
77	await render({ buffer: null });
78	expect(displayed).toHaveBeenCalledTimes(1);
79	await render({ buffer: "" });
80	expect(displayed).toHaveBeenLastCalledWith({ buffer: "", readOnly: false });
81	});
82
83	it.each([
84	"secondary:thread:term-1",
85	"environment:another-thread:term-1",
86	"environment:thread:term-2",
87	])("does not carry history into another terminal target (%s)", async (terminalKey) => {
88	await render();
89	await render({ terminalKey, buffer: null });
90	expect(displayed).toHaveBeenLastCalledWith({ buffer: "", readOnly: false });
91	await render({ terminalKey, buffer: "new target" });
92	expect(displayed).toHaveBeenLastCalledWith({ buffer: "new target", readOnly: false });
93	});
94
95	it("starts empty until its first snapshot arrives", async () => {
96	await render({ buffer: null });
97	expect(displayed).toHaveBeenLastCalledWith({ buffer: "", readOnly: false });
98	await render();
99	expect(displayed).toHaveBeenLastCalledWith({ buffer: "host output", readOnly: false });
100	});

apps/mobile/src/features/terminal/useTerminalSurfaceBuffer.ts created+17

...	@@ -0,0 +1,17 @@
1	import { useState } from "react";
2
3	/** A null buffer means the attachment is waiting for its first snapshot. */
4	export function useTerminalSurfaceBuffer({
5	terminalKey,
6	buffer,
7	}: {
8	readonly terminalKey: string;
9	readonly buffer: string \| null;
10	}): string {
11	const [snapshot, setSnapshot] = useState({ terminalKey, buffer: buffer ?? "" });
12	const currentBuffer = buffer ?? (snapshot.terminalKey === terminalKey ? snapshot.buffer : "");
13	if (snapshot.terminalKey !== terminalKey \|\| snapshot.buffer !== currentBuffer) {
14	setSnapshot({ terminalKey, buffer: currentBuffer });
15	}
16	return currentBuffer;
17	}

apps/mobile/src/features/threads/ThreadGitControls.tsx+6

...	@@ -102,6 +102,7 @@ type ThreadGitControlsProps = ThreadGitMenuProps & {	...	@@ -102,6 +102,7 @@ type ThreadGitControlsProps = ThreadGitMenuProps & {
102	readonly onPress: () => void;	102	readonly onPress: () => void;
103	};	103	};
104	readonly canOpenTerminal: boolean;	104	readonly canOpenTerminal: boolean;
		105	readonly canOperateTerminal: boolean;
105	readonly canOpenFiles: boolean;	106	readonly canOpenFiles: boolean;
106	readonly projectScripts: ReadonlyArray<ProjectScript>;	107	readonly projectScripts: ReadonlyArray<ProjectScript>;
107	readonly terminalSessions: ReadonlyArray<TerminalMenuSession>;	108	readonly terminalSessions: ReadonlyArray<TerminalMenuSession>;
...	@@ -287,6 +288,7 @@ function useThreadGitHeaderActionItems(props: ThreadGitControlsProps): ThreadGit	...	@@ -287,6 +288,7 @@ function useThreadGitHeaderActionItems(props: ThreadGitControlsProps): ThreadGit
287	items: [	288	items: [
288	...props.projectScripts.map((script) => ({	289	...props.projectScripts.map((script) => ({
289	description: script.command,	290	description: script.command,
		291	disabled: !props.canOperateTerminal,
290	icon: { name: projectScriptMenuIcon(script.icon), type: "sfSymbol" as const },	292	icon: { name: projectScriptMenuIcon(script.icon), type: "sfSymbol" as const },
291	label: projectScriptMenuLabel(script),	293	label: projectScriptMenuLabel(script),
292	onPress: () => void props.onRunProjectScript(script),	294	onPress: () => void props.onRunProjectScript(script),
...	@@ -321,6 +323,7 @@ function useThreadGitHeaderActionItems(props: ThreadGitControlsProps): ThreadGit	...	@@ -321,6 +323,7 @@ function useThreadGitHeaderActionItems(props: ThreadGitControlsProps): ThreadGit
321	})),	323	})),
322	{	324	{
323	description: "Start another shell for this thread",	325	description: "Start another shell for this thread",
		326	disabled: !props.canOperateTerminal,
324	icon: { name: "plus", type: "sfSymbol" },	327	icon: { name: "plus", type: "sfSymbol" },
325	label: "Open new terminal",	328	label: "Open new terminal",
326	onPress: props.onOpenNewTerminal,	329	onPress: props.onOpenNewTerminal,
...	@@ -417,6 +420,7 @@ function useThreadGitHeaderActionItems(props: ThreadGitControlsProps): ThreadGit	...	@@ -417,6 +420,7 @@ function useThreadGitHeaderActionItems(props: ThreadGitControlsProps): ThreadGit
417	model.runQuickAction,	420	model.runQuickAction,
418	props.canOpenFiles,	421	props.canOpenFiles,
419	props.canOpenTerminal,	422	props.canOpenTerminal,
		423	props.canOperateTerminal,
420	props.gitStatus,	424	props.gitStatus,
421	props.onMergeBack,	425	props.onMergeBack,
422	props.onOpenNewTerminal,	426	props.onOpenNewTerminal,
...	@@ -474,6 +478,7 @@ export function ThreadGitControls(props: ThreadGitControlsProps) {	...	@@ -474,6 +478,7 @@ export function ThreadGitControls(props: ThreadGitControlsProps) {
474	<NativeHeaderToolbar.MenuAction	478	<NativeHeaderToolbar.MenuAction
475	key={script.id}	479	key={script.id}
476	icon={projectScriptMenuIcon(script.icon)}	480	icon={projectScriptMenuIcon(script.icon)}
		481	disabled={!props.canOperateTerminal}
477	onPress={() => void props.onRunProjectScript(script)}	482	onPress={() => void props.onRunProjectScript(script)}
478	subtitle={script.command}	483	subtitle={script.command}
479	>	484	>
...	@@ -512,6 +517,7 @@ export function ThreadGitControls(props: ThreadGitControlsProps) {	...	@@ -512,6 +517,7 @@ export function ThreadGitControls(props: ThreadGitControlsProps) {
512	))}	517	))}
513	<NativeHeaderToolbar.MenuAction	518	<NativeHeaderToolbar.MenuAction
514	icon="plus"	519	icon="plus"
		520	disabled={!props.canOperateTerminal}
515	onPress={props.onOpenNewTerminal}	521	onPress={props.onOpenNewTerminal}
516	subtitle="Start another shell for this thread"	522	subtitle="Start another shell for this thread"
517	>	523	>

apps/mobile/src/features/threads/ThreadRouteScreen.tsx+52-10

 @@ -16,12 +16,13 @@ import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } fro
 import * as Option from "effect/Option";
 import {
   AuthOrchestrationOperateScope,
+  AuthTerminalOperateScope,
+  AuthTerminalReadScope,
   DEFAULT_SERVER_SETTINGS,
   EnvironmentId,
   ThreadId,
   type ProjectScript,
 } from "@t3tools/contracts";
-import { readEnvironmentScope, useEnvironmentScope } from "../../state/session";
 import {
   projectScriptCwd,
   projectScriptRuntimeEnv,
 @@ -48,6 +49,8 @@ import {
   useRemoteEnvironmentRuntime,
 } from "../../state/use-remote-environment-registry";
 import { useKnownTerminalSessions } from "../../state/use-terminal-session";
+import { uuidv4 } from "../../lib/uuid";
+import { readEnvironmentScope, useEnvironmentScope } from "../../state/session";
 import { useSelectedThreadDetailState } from "../../state/use-thread-detail";
 import { useThreadSelection } from "../../state/use-thread-selection";
 import { GitActionProgressOverlay } from "./GitActionProgressOverlay";
 @@ -119,7 +122,7 @@ function ThreadHeader(
         onPress: filesVisible ? toggleAuxiliaryPane : props.onOpenFilesInspector,
       });
     }
-    if (props.hasWorkspaceRoot) {
+    if (props.hasWorkspaceRoot && props.gitControls.canOpenTerminal) {
       actions.push({
         accessibilityLabel: "Open terminal",
         icon: "terminal",
 @@ -150,6 +153,7 @@ function ThreadHeader(
     props.onReturnToThread,
     props.hasThreadCwd,
     props.hasWorkspaceRoot,
+    props.gitControls.canOpenTerminal,
   ]);
   return (
 @@ -339,6 +343,14 @@ function ThreadRouteContent(
     selectedThread?.environmentId ?? null,
     AuthOrchestrationOperateScope,
   );
+  const canReadTerminal = useEnvironmentScope(
+    selectedThread?.environmentId ?? null,
+    AuthTerminalReadScope,
+  );
+  const canOperateTerminal = useEnvironmentScope(
+    selectedThread?.environmentId ?? null,
+    AuthTerminalOperateScope,
+  );
   const selectedThreadDetailState = props.selectedThreadDetailState;
   const selectedThreadDetail = Option.getOrNull(selectedThreadDetailState.data);
   const { selectedThreadCwd } = useSelectedThreadWorktree();
 @@ -504,14 +516,14 @@ function ThreadRouteContent(
         })
       : null,
   );
-  const knownTerminalSessions = useKnownTerminalSessions({
+  const { sessions: knownTerminalSessions } = useKnownTerminalSessions({
     environmentId: selectedThread?.environmentId ?? null,
     threadId: selectedThread?.id ?? null,
   });
   const terminalMenuSessions = useMemo(
     () =>
       buildTerminalMenuSessions({
-        knownSessions: knownTerminalSessions,
+        knownSessions: knownTerminalSessions ?? [],
         workspaceRoot: selectedThreadProject?.workspaceRoot ?? null,
       }),
     [knownTerminalSessions, selectedThreadProject?.workspaceRoot],
 @@ -703,7 +715,12 @@ function ThreadRouteContent(
         hasWorkspaceRoot: Boolean(selectedThreadProject?.workspaceRoot),
       });
-      if (!selectedThread || !selectedThreadProject?.workspaceRoot) {
+      if (
+        !selectedThread ||
+        !selectedThreadProject?.workspaceRoot ||
+        (!readEnvironmentScope(selectedThread.environmentId, AuthTerminalReadScope) &&
+          !readEnvironmentScope(selectedThread.environmentId, AuthTerminalOperateScope))
+      ) {
         return;
       }
 @@ -723,19 +740,33 @@ function ThreadRouteContent(
       listedTerminalIds: terminalMenuSessions.map((session) => session.terminalId),
     });
-    if (!selectedThread || !selectedThreadProject?.workspaceRoot) {
+    if (
+      !selectedThread ||
+      !selectedThreadProject?.workspaceRoot ||
+      !readEnvironmentScope(selectedThread.environmentId, AuthTerminalOperateScope)
+    ) {
       return;
     }
     const nextId = nextOpenTerminalId({
       listedTerminalIds: terminalMenuSessions.map((session) => session.terminalId),
+      ...(knownTerminalSessions === null ||
+      !readEnvironmentScope(selectedThread.environmentId, AuthTerminalReadScope)
+        ? { uniqueSuffix: uuidv4() }
+        : {}),
     });
     void navigation.navigate("ThreadTerminal", {
       environmentId: String(selectedThread.environmentId),
       threadId: String(selectedThread.id),
       terminalId: nextId,
     });
-  }, [navigation, selectedThread, selectedThreadProject?.workspaceRoot, terminalMenuSessions]);
+  }, [
+    knownTerminalSessions,
+    navigation,
+    selectedThread,
+    selectedThreadProject?.workspaceRoot,
+    terminalMenuSessions,
+  ]);
   const handleRunProjectScript = useCallback(
     async (script: ProjectScript) => {
 @@ -746,16 +777,24 @@ function ThreadRouteContent(
         hasWorkspaceRoot: Boolean(selectedThreadProject?.workspaceRoot),
       });
-      if (!selectedThread || !selectedThreadProject?.workspaceRoot) {
+      if (
+        !selectedThread ||
+        !selectedThreadProject?.workspaceRoot ||
+        !readEnvironmentScope(selectedThread.environmentId, AuthTerminalOperateScope)
+      ) {
         terminalDebugLog("project-script:abort", {
           scriptId: script.id,
-          reason: "no-thread-or-workspace",
+          reason: "no-thread-workspace-or-terminal-access",
         });
         return;
       }
       const targetTerminalId = resolveProjectScriptTerminalId({
         existingTerminalIds: terminalMenuSessions.map((session) => session.terminalId),
+        ...(knownTerminalSessions === null ||
+        !readEnvironmentScope(selectedThread.environmentId, AuthTerminalReadScope)
+          ? { uniqueSuffix: uuidv4() }
+          : {}),
         hasRunningTerminal: terminalMenuSessions.some(
           (session) => session.status === "running" || session.status === "starting",
         ),
 @@ -804,6 +843,7 @@ function ThreadRouteContent(
       selectedThreadDetailWorktreePath,
       selectedThreadProject,
       terminalMenuSessions,
+      knownTerminalSessions,
     ],
   );
   const threadGitControlProps = {
 @@ -826,7 +866,9 @@ function ThreadRouteContent(
     currentBranch: selectedThread?.branch ?? null,
     gitStatus: gitStatus.data,
     gitOperationLabel: gitState.gitOperationLabel,
-    canOpenTerminal: Boolean(selectedThreadProject?.workspaceRoot),
+    canOpenTerminal:
+      Boolean(selectedThreadProject?.workspaceRoot) && (canReadTerminal || canOperateTerminal),
+    canOperateTerminal,
     canOpenFiles: Boolean(selectedThreadProject?.workspaceRoot),
     projectScripts: selectedThreadProject
       ? resolveProjectScripts(

apps/mobile/src/state/use-terminal-session.ts+31-13

 @@ -6,11 +6,18 @@ import {
   type KnownTerminalSession,
   type TerminalSessionState,
 } from "@t3tools/client-runtime/state/terminal";
-import { ThreadId, type EnvironmentId, type TerminalAttachInput } from "@t3tools/contracts";
+import {
+  AuthTerminalReadScope,
+  AuthTerminalOperateScope,
+  ThreadId,
+  type EnvironmentId,
+  type TerminalAttachInput,
+} from "@t3tools/contracts";
 import { useMemo } from "react";
 import { useEnvironmentQuery } from "./query";
 import { terminalEnvironment } from "./terminal";
+import { useEnvironmentScope } from "./session";
 type LegacyTerminalSessionState = TerminalSessionState & { readonly buffer: string };
 const EMPTY_LEGACY_TERMINAL_SESSION_STATE: LegacyTerminalSessionState = {
 @@ -22,16 +29,25 @@ export function useAttachedTerminalSession(input: {
   readonly environmentId: EnvironmentId | null;
   readonly terminal: TerminalAttachInput | null;
 }): LegacyTerminalSessionState {
+  const canRead = useEnvironmentScope(input.environmentId, AuthTerminalReadScope);
+  const canOperate = useEnvironmentScope(input.environmentId, AuthTerminalOperateScope);
   const attach = useEnvironmentQuery(
     input.environmentId !== null && input.terminal !== null
-      ? terminalEnvironment.attach({
+      ? canOperate
-          environmentId: input.environmentId,
+        ? terminalEnvironment.attach({
-          input: input.terminal,
+            environmentId: input.environmentId,
-        })
+            input: input.terminal,
+          })
+        : canRead
+          ? terminalEnvironment.observe({
+              environmentId: input.environmentId,
+              input: { threadId: input.terminal.threadId, terminalId: input.terminal.terminalId },
+            })
+          : null
       : null,
   );
   const metadata = useEnvironmentQuery(
-    input.environmentId === null
+    input.environmentId === null || !canRead
       ? null
       : terminalEnvironment.metadata({
           environmentId: input.environmentId,
 @@ -64,20 +80,21 @@ export function useAttachedTerminalSession(input: {
 export function useKnownTerminalSessions(input: {
   readonly environmentId: EnvironmentId | null;
   readonly threadId: ThreadId | null;
-}): ReadonlyArray<KnownTerminalSession> {
+}) {
+  const canRead = useEnvironmentScope(input.environmentId, AuthTerminalReadScope);
   const metadata = useEnvironmentQuery(
-    input.environmentId === null
+    input.environmentId === null || !canRead
       ? null
       : terminalEnvironment.metadata({
           environmentId: input.environmentId,
           input: null,
         }),
   );
-  return useMemo(() => {
+  const sessions = useMemo((): ReadonlyArray<KnownTerminalSession> | null => {
-    if (input.environmentId === null) {
+    if (input.environmentId === null || metadata.data === null || metadata.error !== null) {
-      return [];
+      return null;
     }
-    return (metadata.data ?? [])
+    return metadata.data
       .filter((summary) => input.threadId === null || summary.threadId === input.threadId)
       .map((summary) => ({
         target: {
 @@ -92,5 +109,6 @@ export function useKnownTerminalSessions(input: {
           numeric: true,
         }),
       );
-  }, [input.environmentId, input.threadId, metadata.data]);
+  }, [input.environmentId, input.threadId, metadata.data, metadata.error]);
+  return { sessions, isPending: metadata.isPending, error: metadata.error };
 }

apps/server/src/auth/RpcAuthorization.test.ts+23

...	@@ -13,6 +13,8 @@ import {	...	@@ -13,6 +13,8 @@ import {
13	AuthPreviewOperateScope,	13	AuthPreviewOperateScope,
14	AuthRelayReadScope,	14	AuthRelayReadScope,
15	AuthRelayWriteScope,	15	AuthRelayWriteScope,
		16	AuthTerminalReadScope,
		17	AuthTerminalOperateScope,
16	WS_METHODS,	18	WS_METHODS,
17	WsRpcGroup,	19	WsRpcGroup,
18	} from "@t3tools/contracts";	20	} from "@t3tools/contracts";
...	@@ -162,6 +164,27 @@ describe("RPC authorization scopes", () => {	...	@@ -162,6 +164,27 @@ describe("RPC authorization scopes", () => {
162	}	164	}
163	});	165	});
164		166
		167	it("separates passive terminal observation from operations that can change a shell", () => {
		168	for (const method of [
		169	WS_METHODS.terminalObserve,
		170	WS_METHODS.subscribeTerminalEvents,
		171	WS_METHODS.subscribeTerminalMetadata,
		172	]) {
		173	expect(requiredScopeForRpcMethod(method)).toBe(AuthTerminalReadScope);
		174	}
		175	for (const method of [
		176	WS_METHODS.terminalAttach,
		177	WS_METHODS.terminalOpen,
		178	WS_METHODS.terminalWrite,
		179	WS_METHODS.terminalResize,
		180	WS_METHODS.terminalClear,
		181	WS_METHODS.terminalRestart,
		182	WS_METHODS.terminalClose,
		183	]) {
		184	expect(requiredScopeForRpcMethod(method)).toBe(AuthTerminalOperateScope);
		185	}
		186	});
		187
165	it("rejects unknown RPC method names", () => {	188	it("rejects unknown RPC method names", () => {
166	for (const method of ["server.notRegistered", "toString", "constructor"]) {	189	for (const method of ["server.notRegistered", "toString", "constructor"]) {
167	expect(() => requiredScopeForRpcMethod(method)).toThrow(	190	expect(() => requiredScopeForRpcMethod(method)).toThrow(

apps/server/src/auth/RpcAuthorization.ts+4-2

 @@ -20,6 +20,7 @@ import {
   AuthRelayWriteScope,
   AuthTerminalOperateScope,
   ORCHESTRATION_V2_WS_METHODS,
+  AuthTerminalReadScope,
   type AuthEnvironmentScope,
   EnvironmentAuthorizationError,
   RpcScopeAuthorization,
 @@ -164,13 +165,14 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.reviewGetDiffFileContents]: AuthFilesystemReadScope,
   [WS_METHODS.terminalOpen]: AuthTerminalOperateScope,
   [WS_METHODS.terminalAttach]: AuthTerminalOperateScope,
+  [WS_METHODS.terminalObserve]: AuthTerminalReadScope,
   [WS_METHODS.terminalWrite]: AuthTerminalOperateScope,
   [WS_METHODS.terminalResize]: AuthTerminalOperateScope,
   [WS_METHODS.terminalClear]: AuthTerminalOperateScope,
   [WS_METHODS.terminalRestart]: AuthTerminalOperateScope,
   [WS_METHODS.terminalClose]: AuthTerminalOperateScope,
-  [WS_METHODS.subscribeTerminalEvents]: AuthTerminalOperateScope,
+  [WS_METHODS.subscribeTerminalEvents]: AuthTerminalReadScope,
-  [WS_METHODS.subscribeTerminalMetadata]: AuthTerminalOperateScope,
+  [WS_METHODS.subscribeTerminalMetadata]: AuthTerminalReadScope,
   [WS_METHODS.previewOpen]: AuthPreviewOperateScope,
   [WS_METHODS.previewNavigate]: AuthPreviewOperateScope,
   [WS_METHODS.previewResize]: AuthPreviewOperateScope,

apps/server/src/observability/RpcInstrumentation.ts+1

...	@@ -161,6 +161,7 @@ const RPC_AGGREGATES = {	...	@@ -161,6 +161,7 @@ const RPC_AGGREGATES = {
161	[WS_METHODS.reviewGetDiffFileContents]: "review",	161	[WS_METHODS.reviewGetDiffFileContents]: "review",
162	[WS_METHODS.terminalOpen]: "terminal",	162	[WS_METHODS.terminalOpen]: "terminal",
163	[WS_METHODS.terminalAttach]: "terminal",	163	[WS_METHODS.terminalAttach]: "terminal",
		164	[WS_METHODS.terminalObserve]: "terminal",
164	[WS_METHODS.terminalWrite]: "terminal",	165	[WS_METHODS.terminalWrite]: "terminal",
165	[WS_METHODS.terminalResize]: "terminal",	166	[WS_METHODS.terminalResize]: "terminal",
166	[WS_METHODS.terminalClear]: "terminal",	167	[WS_METHODS.terminalClear]: "terminal",

apps/server/src/terminal/Manager.test.ts+98

...	@@ -2693,6 +2693,104 @@ it.layer(	...	@@ -2693,6 +2693,104 @@ it.layer(
2693	}),	2693	}),
2694	);	2694	);
2695		2695
		2696	it.effect("observes terminal history and live output without changing the process", () =>
		2697	Effect.gen(function* () {
		2698	const { manager, ptyAdapter } = yield* createManager();
		2699	const opened = yield* manager.open(openInput({ env: { OBSERVER_TEST: "original" } }));
		2700	const process = ptyAdapter.processes[0]!;
		2701	const historyReceived = yield* Deferred.make<void>();
		2702	const unsubscribeHistory = yield* manager.subscribe((event) =>
		2703	event.type === "output"
		2704	? Deferred.succeed(historyReceived, undefined).pipe(Effect.asVoid)
		2705	: Effect.void,
		2706	);
		2707	process.emitData("existing history\n");
		2708	yield* Deferred.await(historyReceived);
		2709	unsubscribeHistory();
		2710
		2711	const observed = yield* Ref.make<ReadonlyArray<TerminalAttachStreamEvent>>([]);
		2712	const liveReceived = yield* Deferred.make<void>();
		2713	const unsubscribe = yield* manager.observeStream(
		2714	{ threadId: opened.threadId, terminalId: opened.terminalId },
		2715	(event) =>
		2716	Ref.update(observed, (events) => [...events, event]).pipe(
		2717	Effect.andThen(
		2718	event.type === "output"
		2719	? Deferred.succeed(liveReceived, undefined).pipe(Effect.asVoid)
		2720	: Effect.void,
		2721	),
		2722	),
		2723	);
		2724	yield* Effect.addFinalizer(() => Effect.sync(unsubscribe));
		2725	process.emitData("live output\n");
		2726	yield* Deferred.await(liveReceived);
		2727
		2728	expect(yield* Ref.get(observed)).toMatchObject([
		2729	{
		2730	type: "snapshot",
		2731	snapshot: {
		2732	cwd: opened.cwd,
		2733	worktreePath: opened.worktreePath,
		2734	pid: opened.pid,
		2735	history: "existing history\n",
		2736	},
		2737	},
		2738	{ type: "output", data: "live output\n" },
		2739	]);
		2740	expect(ptyAdapter.spawnInputs).toHaveLength(1);
		2741	expect(ptyAdapter.spawnInputs[0]?.env.OBSERVER_TEST).toBe("original");
		2742	expect(process.resizeCalls).toEqual([]);
		2743	expect(process.writes).toEqual([]);
		2744	expect(process.killSignals).toEqual([]);
		2745	}),
		2746	);
		2747
		2748	it.effect("observes exited terminals without restarting and rejects missing sessions", () =>
		2749	Effect.gen(function* () {
		2750	const { manager, ptyAdapter } = yield* createManager();
		2751	const missingEvents: TerminalAttachStreamEvent[] = [];
		2752	const missing = yield* manager
		2753	.observeStream({ threadId: "thread-1", terminalId: DEFAULT_TERMINAL_ID }, (event) =>
		2754	Effect.sync(() => {
		2755	missingEvents.push(event);
		2756	}),
		2757	)
		2758	.pipe(Effect.flip);
		2759	expect(missing._tag).toBe("TerminalSessionLookupError");
		2760	expect(ptyAdapter.spawnInputs).toEqual([]);
		2761
		2762	yield* manager.open(openInput());
		2763	const process = ptyAdapter.processes[0]!;
		2764	const exited = yield* Deferred.make<void>();
		2765	const unsubscribeExit = yield* manager.subscribe((event) =>
		2766	event.type === "exited"
		2767	? Deferred.succeed(exited, undefined).pipe(Effect.asVoid)
		2768	: Effect.void,
		2769	);
		2770	process.emitExit({ exitCode: 7, signal: 0 });
		2771	yield* Deferred.await(exited);
		2772	unsubscribeExit();
		2773
		2774	const events: TerminalAttachStreamEvent[] = [];
		2775	const unsubscribe = yield* manager.observeStream(
		2776	{ threadId: "thread-1", terminalId: DEFAULT_TERMINAL_ID },
		2777	(event) =>
		2778	Effect.sync(() => {
		2779	events.push(event);
		2780	}),
		2781	);
		2782	unsubscribe();
		2783	expect(events).toMatchObject([
		2784	{ type: "snapshot", snapshot: { status: "exited", exitCode: 7, pid: null } },
		2785	]);
		2786	expect(ptyAdapter.spawnInputs).toHaveLength(1);
		2787	expect(process.resizeCalls).toEqual([]);
		2788	expect(process.writes).toEqual([]);
		2789	expect(process.killSignals).toEqual([]);
		2790	expect(missingEvents).toEqual([]);
		2791	}),
		2792	);
		2793
2696	it.effect("buffers attach output delivered during the initial snapshot callback", () =>	2794	it.effect("buffers attach output delivered during the initial snapshot callback", () =>
2697	Effect.gen(function* () {	2795	Effect.gen(function* () {
2698	const { manager, ptyAdapter } = yield* createManager(5, {	2796	const { manager, ptyAdapter } = yield* createManager(5, {

apps/server/src/terminal/Manager.ts+27-2

 @@ -28,6 +28,7 @@ import {
   type TerminalEvent,
   type TerminalMetadataStreamEvent,
   type TerminalOpenInput,
+  type TerminalObserveInput,
   type TerminalResizeInput,
   type ResourceMonitorProcessTableEntry,
   type TerminalRestartInput,
 @@ -170,6 +171,12 @@ export class TerminalManager extends Context.Service<
       listener: (event: TerminalAttachStreamEvent) => Effect.Effect<void>,
     ) => Effect.Effect<() => void, TerminalError>;
+    /** Observe an existing session without starting or changing its process. */
+    readonly observeStream: (
+      input: TerminalObserveInput,
+      listener: (event: TerminalAttachStreamEvent) => Effect.Effect<void>,
+    ) => Effect.Effect<() => void, TerminalError>;
     /**
      * Write input bytes to a terminal session.
      */
 @@ -2787,7 +2794,11 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
       };
     });
-  const attachStream: TerminalManager["Service"]["attachStream"] = (input, listener) => {
+  const streamSession = (
+    input: TerminalObserveInput,
+    initial: Effect.Effect<TerminalSessionSnapshot, TerminalError>,
+    listener: (event: TerminalAttachStreamEvent) => Effect.Effect<void>,
+  ) => {
     let unsubscribe: (() => void) | null = null;
     return Effect.gen(function* () {
 @@ -2808,7 +2819,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
         return attachEvent ? listener(attachEvent) : Effect.void;
       });
-      const initialSnapshot = yield* openOrAttachForStream(input);
+      const initialSnapshot = yield* initial;
       yield* listener({
         type: "snapshot",
 @@ -2844,6 +2855,19 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
     );
   };
+  const attachStream: TerminalManager["Service"]["attachStream"] = (input, listener) =>
+    streamSession(input, openOrAttachForStream(input), listener);
+  const observeStream: TerminalManager["Service"]["observeStream"] = (input, listener) =>
+    streamSession(
+      input,
+      withThreadLock(
+        input.threadId,
+        requireSession(input.threadId, input.terminalId).pipe(Effect.map(snapshot)),
+      ),
+      listener,
+    );
   const metadataEventFromTerminalEvent = (
     event: TerminalEvent,
   ): Effect.Effect<TerminalMetadataStreamEvent | null> => {
 @@ -3153,6 +3177,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
   return TerminalManager.of({
     open,
     attachStream,
+    observeStream,
     write,
     resize,
     clear,

apps/server/src/ws.ts+8-1

 @@ -2840,13 +2840,20 @@ const layerWsRpc = (
             Effect.acquireRelease(
               terminalManager.attachStream(input, (event) => Queue.offer(queue, event)),
               (unsubscribe) => Effect.sync(unsubscribe),
-            ),
+            ).pipe(Effect.catchCause((cause) => Queue.failCause(queue, cause))),
           ),
         [WS_METHODS.terminalWrite]: (input) => terminalManager.write(input),
         [WS_METHODS.terminalResize]: (input) => terminalManager.resize(input),
         [WS_METHODS.terminalClear]: (input) => terminalManager.clear(input),
         [WS_METHODS.terminalRestart]: (input) => terminalManager.restart(input),
         [WS_METHODS.terminalClose]: (input) => terminalManager.close(input),
+        [WS_METHODS.terminalObserve]: (input) =>
+          Stream.callback<TerminalAttachStreamEvent, TerminalError>((queue) =>
+            Effect.acquireRelease(
+              terminalManager.observeStream(input, (event) => Queue.offer(queue, event)),
+              (unsubscribe) => Effect.sync(unsubscribe),
+            ).pipe(Effect.catchCause((cause) => Queue.failCause(queue, cause))),
+          ),
         [WS_METHODS.subscribeTerminalEvents]: (_input) =>
           Stream.callback<TerminalEvent>((queue) =>
             Effect.acquireRelease(

apps/web/src/components/ChatView.tsx+163-50

 @@ -52,6 +52,8 @@ import {
   AuthSettingsWriteScope,
   AuthSourceControlWriteScope,
   AuthPreviewOperateScope,
+  AuthTerminalReadScope,
+  AuthTerminalOperateScope,
   type AssistantCitation,
   type ChatFileAttachment,
   CommandId,
 @@ -980,6 +982,11 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
   keybindings,
   onAddTerminalContext,
 }: PersistentThreadTerminalDrawerProps) {
+  const canOperateTerminal = useEnvironmentScope(threadRef.environmentId, AuthTerminalOperateScope);
+  const hasTerminalWriteAccess = useCallback(
+    () => readEnvironmentScope(threadRef.environmentId, AuthTerminalOperateScope),
+    [threadRef.environmentId],
+  );
   const openTerminal = useAtomCommand(terminalEnvironment.open, "terminal open");
   const writeTerminal = useAtomCommand(terminalEnvironment.write, "terminal write");
   const closeTerminalMutation = useAtomCommand(terminalEnvironment.close, "terminal close");
 @@ -1013,7 +1020,9 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
   );
   const drawerTerminalSessions = useMemo(
     () =>
-      knownTerminalSessions.filter((session) => !panelTerminalIds.has(session.target.terminalId)),
+      knownTerminalSessions?.filter(
+        (session) => !panelTerminalIds.has(session.target.terminalId),
+      ) ?? [],
     [knownTerminalSessions, panelTerminalIds],
   );
   const terminalLabelsById = useMemo(() => {
 @@ -1075,6 +1084,17 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
     ],
     [panelTerminalIds, serverOrderedTerminalIds, terminalUiState.terminalIds],
   );
+  const allocateTerminalId = useCallback(
+    () =>
+      nextTerminalId(
+        allocatableTerminalIds,
+        knownTerminalSessions === null ||
+          !readEnvironmentScope(threadRef.environmentId, AuthTerminalReadScope)
+          ? randomUUID()
+          : undefined,
+      ),
+    [allocatableTerminalIds, knownTerminalSessions, threadRef.environmentId],
+  );
   const storeSetTerminalHeight = useTerminalUiStateStore((state) => state.setTerminalHeight);
   const storeSplitTerminal = useTerminalUiStateStore((state) => state.splitTerminal);
   const storeSplitTerminalVertical = useTerminalUiStateStore(
 @@ -1141,10 +1161,10 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
   );
   const splitTerminal = useCallback(() => {
-    if (!cwd) {
+    if (!hasTerminalWriteAccess() || !cwd) {
       return;
     }
-    const terminalId = nextTerminalId(allocatableTerminalIds);
+    const terminalId = allocateTerminalId();
     storeSplitTerminal(threadRef, terminalId);
     bumpFocusRequestId();
     void openTerminal({
 @@ -1158,7 +1178,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
       },
     });
   }, [
-    allocatableTerminalIds,
+    allocateTerminalId,
     bumpFocusRequestId,
     cwd,
     effectiveWorktreePath,
 @@ -1167,12 +1187,13 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
     threadId,
     threadRef,
     openTerminal,
+    hasTerminalWriteAccess,
   ]);
   const splitTerminalVertical = useCallback(() => {
-    if (!cwd) {
+    if (!hasTerminalWriteAccess() || !cwd) {
       return;
     }
-    const terminalId = nextTerminalId(allocatableTerminalIds);
+    const terminalId = allocateTerminalId();
     storeSplitTerminalVertical(threadRef, terminalId);
     bumpFocusRequestId();
     void openTerminal({
 @@ -1186,11 +1207,12 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
       },
     });
   }, [
-    allocatableTerminalIds,
+    allocateTerminalId,
     bumpFocusRequestId,
     cwd,
     effectiveWorktreePath,
     openTerminal,
+    hasTerminalWriteAccess,
     runtimeEnv,
     storeSplitTerminalVertical,
     threadId,
 @@ -1198,10 +1220,10 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
   ]);
   const createNewTerminal = useCallback(() => {
-    if (!cwd) {
+    if (!hasTerminalWriteAccess() || !cwd) {
       return;
     }
-    const terminalId = nextTerminalId(allocatableTerminalIds);
+    const terminalId = allocateTerminalId();
     storeNewTerminal(threadRef, terminalId);
     bumpFocusRequestId();
     void openTerminal({
 @@ -1218,12 +1240,13 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
     bumpFocusRequestId,
     cwd,
     effectiveWorktreePath,
-    allocatableTerminalIds,
+    allocateTerminalId,
     runtimeEnv,
     storeNewTerminal,
     threadId,
     threadRef,
     openTerminal,
+    hasTerminalWriteAccess,
   ]);
   const activateTerminal = useCallback(
 @@ -1236,6 +1259,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
   const closeTerminal = useCallback(
     (terminalId: string) => {
+      if (!hasTerminalWriteAccess()) return;
       const fallbackExitWrite = () =>
         writeTerminal({
           environmentId: threadRef.environmentId,
 @@ -1251,7 +1275,11 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
             deleteHistory: true,
           },
         });
-        if (closeResult._tag === "Failure" && !isAtomCommandInterrupted(closeResult)) {
+        if (
+          closeResult._tag === "Failure" &&
+          !isAtomCommandInterrupted(closeResult) &&
+          hasTerminalWriteAccess()
+        ) {
           await fallbackExitWrite();
         }
       })();
 @@ -1265,6 +1293,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
       threadId,
       threadRef,
       closeTerminalMutation,
+      hasTerminalWriteAccess,
       writeTerminal,
     ],
   );
 @@ -1303,7 +1332,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
           visible={visible}
           height={terminalUiState.terminalHeight}
           // Known-session order is MRU and changes on focus; persisted store order keeps sidebar labels stable.
-          terminalIds={terminalUiState.terminalIds}
+          terminalIds={canOperateTerminal ? terminalUiState.terminalIds : serverOrderedTerminalIds}
           activeTerminalId={terminalUiState.activeTerminalId}
           terminalGroups={terminalUiState.terminalGroups}
           activeTerminalGroupId={terminalUiState.activeTerminalGroupId}
 @@ -1379,7 +1408,7 @@ const PersistentThreadTerminalPanel = memo(function PersistentThreadTerminalPane
   });
   const threadWorktreePath = serverThread?.worktreePath ?? draftThread?.worktreePath ?? null;
   const activeSummary =
-    knownTerminalSessions.find((session) => session.target.terminalId === surface.activeTerminalId)
+    knownTerminalSessions?.find((session) => session.target.terminalId === surface.activeTerminalId)
       ?.state.summary ?? null;
   const worktreePath =
     launchContext?.worktreePath ?? activeSummary?.worktreePath ?? threadWorktreePath;
 @@ -1409,7 +1438,7 @@ const PersistentThreadTerminalPanel = memo(function PersistentThreadTerminalPane
     const labels = new Map<string, string>();
     for (const terminalId of surface.terminalIds) {
       const summary =
-        knownTerminalSessions.find((session) => session.target.terminalId === terminalId)?.state
+        knownTerminalSessions?.find((session) => session.target.terminalId === terminalId)?.state
           .summary ?? null;
       labels.set(terminalId, resolveTerminalSessionLabel(terminalId, summary));
     }
 @@ -1426,7 +1455,7 @@ const PersistentThreadTerminalPanel = memo(function PersistentThreadTerminalPane
     >();
     for (const terminalId of surface.terminalIds) {
       const summary =
-        knownTerminalSessions.find((session) => session.target.terminalId === terminalId)?.state
+        knownTerminalSessions?.find((session) => session.target.terminalId === terminalId)?.state
           .summary ?? null;
       const terminalWorktreePath =
         launchContext?.worktreePath ?? summary?.worktreePath ?? threadWorktreePath;
 @@ -1544,6 +1573,12 @@ export default function ChatView(props: ChatViewProps) {
     forceExpandedMobileComposer = false,
   } = props;
   const canOperateThread = useEnvironmentScope(environmentId, AuthOrchestrationOperateScope);
+  const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
+  const hasTerminalWriteAccess = useCallback(
+    () => readEnvironmentScope(environmentId, AuthTerminalOperateScope),
+    [environmentId],
+  );
+  const canReadTerminal = useEnvironmentScope(environmentId, AuthTerminalReadScope);
   const draftId = routeKind === "draft" ? props.draftId : null;
   const handleNewThread = useNewThreadHandler();
   const { settleThread, pinThread, confirmAndUnpinThread } = useThreadActions();
 @@ -2180,7 +2215,7 @@ export default function ChatView(props: ChatViewProps) {
     threadId: activeThreadId,
   });
   const activeThreadKnownSessions = useMemo(() => {
-    if (activeThreadId === null) {
+    if (activeThreadId === null || activeThreadKnownSessionsRaw === null) {
       return [];
     }
     return activeThreadKnownSessionsRaw.filter(
 @@ -2301,6 +2336,17 @@ export default function ChatView(props: ChatViewProps) {
     () => [...new Set([...activeKnownTerminalIds, ...panelTerminalIds])],
     [activeKnownTerminalIds, panelTerminalIds],
   );
+  const canReuseTerminal = activeThreadKnownSessionsRaw !== null;
+  const allocateTerminalId = useCallback(
+    () =>
+      nextTerminalId(
+        allocatableActiveTerminalIds,
+        canReuseTerminal && readEnvironmentScope(environmentId, AuthTerminalReadScope)
+          ? undefined
+          : randomUUID(),
+      ),
+    [allocatableActiveTerminalIds, canReuseTerminal, environmentId],
+  );
   const previewPanelOpen = activeRightPanelKind === "preview" && browserAvailable;
   const rightPanelOpen = rightPanelState.isOpen;
   const { active: panelAnimationsActive, durationMs: panelAnimationDurationMs } =
 @@ -4696,7 +4742,13 @@ export default function ChatView(props: ChatViewProps) {
   const toggleTerminalVisibility = useCallback(() => {
     if (!activeThreadRef) return;
     const nextOpen = !terminalUiState.terminalOpen;
-    if (nextOpen && terminalUiState.terminalIds.length === 0) {
+    if (
+      nextOpen &&
+      !readEnvironmentScope(environmentId, AuthTerminalReadScope) &&
+      !hasTerminalWriteAccess()
+    )
+      return;
+    if (nextOpen && hasTerminalWriteAccess() && terminalUiState.terminalIds.length === 0) {
       if (!activeThreadId || !activeProject) {
         return;
       }
 @@ -4704,7 +4756,7 @@ export default function ChatView(props: ChatViewProps) {
       if (!cwdForOpen) {
         return;
       }
-      const terminalId = nextTerminalId(allocatableActiveTerminalIds);
+      const terminalId = allocateTerminalId();
       storeEnsureTerminal(activeThreadRef, terminalId, { open: true });
       void openTerminal({
         environmentId,
 @@ -4727,10 +4779,11 @@ export default function ChatView(props: ChatViewProps) {
     activeThreadId,
     activeThreadRef,
     activeThreadWorktreePath,
-    allocatableActiveTerminalIds,
+    allocateTerminalId,
     environmentId,
     gitCwd,
     openTerminal,
+    hasTerminalWriteAccess,
     setTerminalOpen,
     storeEnsureTerminal,
     terminalUiState.terminalIds.length,
 @@ -4738,14 +4791,20 @@ export default function ChatView(props: ChatViewProps) {
   ]);
   const splitTerminal = useCallback(
     (direction: "horizontal" | "vertical" = "horizontal") => {
-      if (!activeThreadRef || hasReachedSplitLimit || !activeThreadId || !activeProject) {
+      if (
+        !hasTerminalWriteAccess() ||
+        !activeThreadRef ||
+        hasReachedSplitLimit ||
+        !activeThreadId ||
+        !activeProject
+      ) {
         return;
       }
       const cwdForOpen = gitCwd ?? activeProject.workspaceRoot;
       if (!cwdForOpen) {
         return;
       }
-      const terminalId = nextTerminalId(allocatableActiveTerminalIds);
+      const terminalId = allocateTerminalId();
       if (direction === "vertical") {
         storeSplitTerminalVertical(activeThreadRef, terminalId);
       } else {
 @@ -4769,9 +4828,10 @@ export default function ChatView(props: ChatViewProps) {
     [
       activeProject,
       activeThreadId,
-      allocatableActiveTerminalIds,
+      allocateTerminalId,
       activeThreadRef,
       openTerminal,
+      hasTerminalWriteAccess,
       activeThreadWorktreePath,
       environmentId,
       gitCwd,
 @@ -4781,14 +4841,14 @@ export default function ChatView(props: ChatViewProps) {
     ],
   );
   const createNewTerminal = useCallback(() => {
-    if (!activeThreadRef || !activeThreadId || !activeProject) {
+    if (!hasTerminalWriteAccess() || !activeThreadRef || !activeThreadId || !activeProject) {
       return;
     }
     const cwdForOpen = gitCwd ?? activeProject.workspaceRoot;
     if (!cwdForOpen) {
       return;
     }
-    const terminalId = nextTerminalId(allocatableActiveTerminalIds);
+    const terminalId = allocateTerminalId();
     storeNewTerminal(activeThreadRef, terminalId);
     setTerminalFocusRequestId((value) => value + 1);
     void openTerminal({
 @@ -4807,9 +4867,10 @@ export default function ChatView(props: ChatViewProps) {
   }, [
     activeProject,
     activeThreadId,
-    allocatableActiveTerminalIds,
+    allocateTerminalId,
     activeThreadRef,
     openTerminal,
+    hasTerminalWriteAccess,
     activeThreadWorktreePath,
     environmentId,
     gitCwd,
 @@ -4817,7 +4878,7 @@ export default function ChatView(props: ChatViewProps) {
   ]);
   const closeTerminal = useCallback(
     (terminalId: string) => {
-      if (!activeThreadId || !activeThreadRef) return;
+      if (!hasTerminalWriteAccess() || !activeThreadId || !activeThreadRef) return;
       const fallbackExitWrite = () =>
         writeTerminal({
           environmentId,
 @@ -4832,7 +4893,11 @@ export default function ChatView(props: ChatViewProps) {
             deleteHistory: true,
           },
         });
-        if (closeResult._tag === "Failure" && !isAtomCommandInterrupted(closeResult)) {
+        if (
+          closeResult._tag === "Failure" &&
+          !isAtomCommandInterrupted(closeResult) &&
+          hasTerminalWriteAccess()
+        ) {
           await fallbackExitWrite();
         }
       })();
 @@ -4843,6 +4908,7 @@ export default function ChatView(props: ChatViewProps) {
       activeThreadId,
       activeThreadRef,
       closeTerminalMutation,
+      hasTerminalWriteAccess,
       environmentId,
       storeCloseTerminal,
       writeTerminal,
 @@ -4859,7 +4925,7 @@ export default function ChatView(props: ChatViewProps) {
         rememberAsLastInvoked?: boolean;
       },
     ) => {
-      if (!activeThreadId || !activeProject || !activeThread) return;
+      if (!hasTerminalWriteAccess() || !activeThreadId || !activeProject || !activeThread) return;
       if (options?.rememberAsLastInvoked !== false) {
         setLastInvokedScriptByProjectId((current) => {
           if (current[activeProject.id] === script.id) return current;
 @@ -4871,7 +4937,10 @@ export default function ChatView(props: ChatViewProps) {
         terminalUiState.activeTerminalId || activeKnownTerminalIds[0] || DEFAULT_THREAD_TERMINAL_ID;
       const isBaseTerminalBusy = runningTerminalIds.includes(baseTerminalId);
       const wantsNewTerminal = Boolean(options?.preferNewTerminal) || isBaseTerminalBusy;
-      const shouldCreateNewTerminal = wantsNewTerminal;
+      const shouldCreateNewTerminal =
+        wantsNewTerminal ||
+        !canReuseTerminal ||
+        !readEnvironmentScope(environmentId, AuthTerminalReadScope);
       const targetWorktreePath = options?.worktreePath ?? activeThread.worktreePath ?? null;
       setTerminalUiLaunchContext({
 @@ -4892,9 +4961,7 @@ export default function ChatView(props: ChatViewProps) {
         worktreePath: targetWorktreePath,
         ...(options?.env ? { extraEnv: options.env } : {}),
       });
-      const targetTerminalId = shouldCreateNewTerminal
+      const targetTerminalId = shouldCreateNewTerminal ? allocateTerminalId() : baseTerminalId;
-        ? nextTerminalId(allocatableActiveTerminalIds)
-        : baseTerminalId;
       const openTerminalInput: TerminalOpenInput = shouldCreateNewTerminal
         ? {
             threadId: activeThreadId,
 @@ -4931,6 +4998,7 @@ export default function ChatView(props: ChatViewProps) {
         return;
       }
+      if (!hasTerminalWriteAccess()) return;
       const writeResult = await writeTerminal({
         environmentId,
         input: {
 @@ -4981,8 +5049,10 @@ export default function ChatView(props: ChatViewProps) {
       environmentId,
       openTerminal,
       openPreview,
+      hasTerminalWriteAccess,
       activeKnownTerminalIds,
-      allocatableActiveTerminalIds,
+      canReuseTerminal,
+      allocateTerminalId,
       runningTerminalIds,
       terminalUiState.activeTerminalId,
       writeTerminal,
 @@ -5792,9 +5862,9 @@ export default function ChatView(props: ChatViewProps) {
     previewPanelOpen,
   ]);
   const addTerminalSurface = useCallback(() => {
-    if (!activeThreadRef || !activeThreadId || !activeProject) return;
+    if (!hasTerminalWriteAccess() || !activeThreadRef || !activeThreadId || !activeProject) return;
     const cwd = gitCwd ?? activeProject.workspaceRoot;
-    const terminalId = nextTerminalId(allocatableActiveTerminalIds);
+    const terminalId = allocateTerminalId();
     useRightPanelStore.getState().openTerminal(activeThreadRef, terminalId);
     setTerminalFocusRequestId((value) => value + 1);
     void openTerminal({
 @@ -5815,13 +5885,15 @@ export default function ChatView(props: ChatViewProps) {
     activeThreadId,
     activeThreadRef,
     activeThreadWorktreePath,
-    allocatableActiveTerminalIds,
+    allocateTerminalId,
     gitCwd,
     openTerminal,
+    hasTerminalWriteAccess,
   ]);
   const splitPanelTerminal = useCallback(
     (direction: "horizontal" | "vertical" = "horizontal") => {
       if (
+        !hasTerminalWriteAccess() ||
         !activeThreadRef ||
         !activeThreadId ||
         !activeProject ||
 @@ -5830,7 +5902,7 @@ export default function ChatView(props: ChatViewProps) {
       ) {
         return;
       }
-      const terminalId = nextTerminalId(allocatableActiveTerminalIds);
+      const terminalId = allocateTerminalId();
       const cwd = gitCwd ?? activeProject.workspaceRoot;
       useRightPanelStore
         .getState()
 @@ -5856,9 +5928,10 @@ export default function ChatView(props: ChatViewProps) {
       activeThreadId,
       activeThreadRef,
       activeThreadWorktreePath,
-      allocatableActiveTerminalIds,
+      allocateTerminalId,
       gitCwd,
       openTerminal,
+      hasTerminalWriteAccess,
     ],
   );
   const splitPanelTerminalVertical = useCallback(() => {
 @@ -5876,7 +5949,12 @@ export default function ChatView(props: ChatViewProps) {
   );
   const closePanelTerminal = useCallback(
     (terminalId: string) => {
-      if (!activeThreadRef || activeRightPanelSurface?.kind !== "terminal") return;
+      if (
+        !hasTerminalWriteAccess() ||
+        !activeThreadRef ||
+        activeRightPanelSurface?.kind !== "terminal"
+      )
+        return;
       void closeTerminalMutation({
         environmentId: activeThreadRef.environmentId,
         input: { threadId: activeThreadRef.threadId, terminalId, deleteHistory: true },
 @@ -5887,25 +5965,37 @@ export default function ChatView(props: ChatViewProps) {
         .closeTerminal(activeThreadRef, activeRightPanelSurface.id, terminalId);
       setTerminalFocusRequestId((value) => value + 1);
     },
-    [activeRightPanelSurface, activeThreadRef, closeTerminalMutation, storeCloseTerminal],
+    [
+      hasTerminalWriteAccess,
+      activeRightPanelSurface,
+      activeThreadRef,
+      closeTerminalMutation,
+      storeCloseTerminal,
+    ],
   );
   const requestCloseTerminal = useCallback(
     (terminalId: string) => {
+      if (!hasTerminalWriteAccess()) return;
       const label = activeTerminalLabelsById.get(terminalId) ?? getTerminalLabel(terminalId);
       void confirmTerminalClose([label]).then((confirmed) => {
-        if (confirmed) closeTerminal(terminalId);
+        if (confirmed && readEnvironmentScope(environmentId, AuthTerminalOperateScope)) {
+          closeTerminal(terminalId);
+        }
       });
     },
-    [activeTerminalLabelsById, closeTerminal],
+    [hasTerminalWriteAccess, activeTerminalLabelsById, closeTerminal, environmentId],
   );
   const requestClosePanelTerminal = useCallback(
     (terminalId: string) => {
+      if (!hasTerminalWriteAccess()) return;
       const label = activeTerminalLabelsById.get(terminalId) ?? getTerminalLabel(terminalId);
       void confirmTerminalClose([label]).then((confirmed) => {
-        if (confirmed) closePanelTerminal(terminalId);
+        if (confirmed && readEnvironmentScope(environmentId, AuthTerminalOperateScope)) {
+          closePanelTerminal(terminalId);
+        }
       });
     },
-    [activeTerminalLabelsById, closePanelTerminal],
+    [hasTerminalWriteAccess, activeTerminalLabelsById, closePanelTerminal, environmentId],
   );
   const activateRightPanelSurface = useCallback(
     (surface: RightPanelSurface) => {
 @@ -5956,7 +6046,10 @@ export default function ChatView(props: ChatViewProps) {
             threadRef: activeThreadRef,
           });
         }
-        if (surface.kind === "terminal") {
+        if (
+          surface.kind === "terminal" &&
+          readEnvironmentScope(activeThreadRef.environmentId, AuthTerminalOperateScope)
+        ) {
           for (const terminalId of surface.terminalIds) {
             storeCloseTerminal(activeThreadRef, terminalId);
             void closeTerminalMutation({
 @@ -6034,7 +6127,10 @@ export default function ChatView(props: ChatViewProps) {
         closeAfterAgentBrowserConfirmation([surface], finishClose);
         return;
       }
-      if (surface.kind !== "terminal") {
+      if (
+        surface.kind !== "terminal" ||
+        !readEnvironmentScope(activeThreadRef.environmentId, AuthTerminalOperateScope)
+      ) {
         finishClose();
         return;
       }
 @@ -6047,7 +6143,9 @@ export default function ChatView(props: ChatViewProps) {
           (terminalId) => activeTerminalLabelsById.get(terminalId) ?? getTerminalLabel(terminalId),
         );
       void confirmTerminalClose([activeLabel, ...otherLabels]).then((confirmed) => {
-        if (confirmed) finishClose();
+        if (confirmed) {
+          finishClose();
+        }
       });
     },
     [
 @@ -7963,6 +8061,7 @@ export default function ChatView(props: ChatViewProps) {
       }
       if (command === "terminal.toggle") {
+        if (!terminalUiState.terminalOpen && !canReadTerminal && !canOperateTerminal) return;
         event.preventDefault();
         event.stopPropagation();
         toggleTerminalVisibility();
 @@ -7994,6 +8093,9 @@ export default function ChatView(props: ChatViewProps) {
       }
       if (command === "terminal.split") {
+        // Without operate access the key keeps its native meaning, as it
+        // does when nothing is open.
+        if (!canOperateTerminal) return;
         event.preventDefault();
         event.stopPropagation();
         if (terminalFocusOwner === "right-panel") {
 @@ -8008,6 +8110,9 @@ export default function ChatView(props: ChatViewProps) {
       }
       if (command === "terminal.splitVertical") {
+        // Without operate access the key keeps its native meaning, as it
+        // does when nothing is open.
+        if (!canOperateTerminal) return;
         event.preventDefault();
         event.stopPropagation();
         if (terminalFocusOwner === "right-panel") {
 @@ -8022,6 +8127,9 @@ export default function ChatView(props: ChatViewProps) {
       }
       if (command === "terminal.close") {
+        // Without operate access the key keeps its native meaning, as it
+        // does when nothing is open.
+        if (!canOperateTerminal) return;
         event.preventDefault();
         event.stopPropagation();
         if (terminalFocusOwner === "right-panel" && activeRightPanelSurface?.kind === "terminal") {
 @@ -8034,6 +8142,9 @@ export default function ChatView(props: ChatViewProps) {
       }
       if (command === "terminal.new") {
+        // Without operate access the key keeps its native meaning, as it
+        // does when nothing is open.
+        if (!canOperateTerminal) return;
         event.preventDefault();
         event.stopPropagation();
         if (terminalFocusOwner === "right-panel") {
 @@ -8132,7 +8243,7 @@ export default function ChatView(props: ChatViewProps) {
       }
       const scriptId = projectScriptIdFromCommand(command);
-      if (!scriptId || !activeProject) return;
+      if (!scriptId || !activeProject || !canOperateTerminal) return;
       const script = activeProjectScripts.find((entry) => entry.id === scriptId);
       if (!script) return;
       event.preventDefault();
 @@ -8145,6 +8256,8 @@ export default function ChatView(props: ChatViewProps) {
     activeProject,
     activeRightPanelSurface,
     activeProjectScripts,
+    canReadTerminal,
+    canOperateTerminal,
     addTerminalSurface,
     activeThreadRef,
     activeThreadPinned,
 @@ -11769,7 +11882,7 @@ export default function ChatView(props: ChatViewProps) {
           onAddPullRequests={addPullRequestsSurface}
           onAddDevice={addDeviceSurface}
           browserAvailable={canOperatePreview && browserAvailable}
-          terminalAvailable={activeProject !== null}
+          terminalAvailable={activeProject !== null && canOperateTerminal}
           diffAvailable={isServerThread && isGitRepo}
           filesAvailable={activeProject !== null}
           pullRequestAvailable={pullRequestSurfaceAvailable}
 @@ -11827,7 +11940,7 @@ export default function ChatView(props: ChatViewProps) {
             onAddPullRequests={addPullRequestsSurface}
             onAddDevice={addDeviceSurface}
             browserAvailable={canOperatePreview && browserAvailable}
-            terminalAvailable={activeProject !== null}
+            terminalAvailable={activeProject !== null && canOperateTerminal}
             diffAvailable={isServerThread && isGitRepo}
             filesAvailable={activeProject !== null}
             pullRequestAvailable={pullRequestSurfaceAvailable}

apps/web/src/components/ProjectScriptsControl.tsx+12-5

...	@@ -66,7 +66,7 @@ interface ProjectScriptsControlProps {	...	@@ -66,7 +66,7 @@ interface ProjectScriptsControlProps {
66	/** Scripts declared in the project's checked-in t3.json, offered for import. */	66	/** Scripts declared in the project's checked-in t3.json, offered for import. */
67	fileScripts?: ReadonlyArray<T3ProjectFileScript>;	67	fileScripts?: ReadonlyArray<T3ProjectFileScript>;
68	preferredScriptId?: string \| null;	68	preferredScriptId?: string \| null;
69	onRunScript: (script: ProjectScript) => void;	69	onRunScript?: ((script: ProjectScript) => void) \| undefined;
70	onAddScript: (input: NewProjectScriptInput) => Promise<ProjectScriptActionResult>;	70	onAddScript: (input: NewProjectScriptInput) => Promise<ProjectScriptActionResult>;
71	onUpdateScript: (	71	onUpdateScript: (
72	scriptId: string,	72	scriptId: string,
...	@@ -198,7 +198,8 @@ export default function ProjectScriptsControl({	...	@@ -198,7 +198,8 @@ export default function ProjectScriptsControl({
198	density={presentation === "menu" ? "touch" : "default"}	198	density={presentation === "menu" ? "touch" : "default"}
199	key={script.id}	199	key={script.id}
200	className="group"	200	className="group"
201	onClick={() => onRunScript(script)}	201	disabled={!onRunScript}
		202	onClick={() => onRunScript?.(script)}
202	>	203	>
203	<ScriptIcon icon={script.icon} className="size-4" />	204	<ScriptIcon icon={script.icon} className="size-4" />
204	<MenuItemLabel>	205	<MenuItemLabel>
...	@@ -255,7 +256,8 @@ export default function ProjectScriptsControl({	...	@@ -255,7 +256,8 @@ export default function ProjectScriptsControl({
255	{primaryScript && (	256	{primaryScript && (
256	<MenuItem	257	<MenuItem
257	density={presentation === "menu" ? "touch" : "default"}	258	density={presentation === "menu" ? "touch" : "default"}
258	onClick={() => onRunScript(primaryScript)}	259	disabled={!onRunScript}
		260	onClick={() => onRunScript?.(primaryScript)}
259	>	261	>
260	<ScriptIcon icon={primaryScript.icon} className="size-4" />	262	<ScriptIcon icon={primaryScript.icon} className="size-4" />
261	<MenuItemLabel>Run {primaryScript.name}</MenuItemLabel>	263	<MenuItemLabel>Run {primaryScript.name}</MenuItemLabel>
...	@@ -308,7 +310,8 @@ export default function ProjectScriptsControl({	...	@@ -308,7 +310,8 @@ export default function ProjectScriptsControl({
308	// The tooltip wrapper replaces data-slot="button", so themed	310	// The tooltip wrapper replaces data-slot="button", so themed
309	// toolbar styling needs its own hook.	311	// toolbar styling needs its own hook.
310	data-toolbar-control=""	312	data-toolbar-control=""
311	onClick={() => onRunScript(primaryScript)}	313	aria-disabled={!onRunScript \|\| undefined}
		314	onClick={() => onRunScript?.(primaryScript)}
312	/>	315	/>
313	}	316	}
314	>	317	>
...	@@ -325,7 +328,11 @@ export default function ProjectScriptsControl({	...	@@ -325,7 +328,11 @@ export default function ProjectScriptsControl({
325	{primaryScript.name}	328	{primaryScript.name}
326	</span>	329	</span>
327	</TooltipTrigger>	330	</TooltipTrigger>
328	<TooltipPopup side="top">Run {primaryScript.name}</TooltipPopup>	331	<TooltipPopup side="top">
		332	{onRunScript
		333	? `Run ${primaryScript.name}`
		334	: "Pair this client again with permission to run terminal commands."}
		335	</TooltipPopup>
329	</Tooltip>	336	</Tooltip>
330	{isPanel ? (	337	{isPanel ? (
331	<span aria-hidden="true" className={THREAD_DETAILS_PANEL_SPLIT_SEPARATOR_CLASS} />	338	<span aria-hidden="true" className={THREAD_DETAILS_PANEL_SPLIT_SEPARATOR_CLASS} />

apps/web/src/components/ThreadTerminalDrawer.permissions.test.tsx created+153

...	@@ -0,0 +1,153 @@
1	import {
2	AuthTerminalOperateScope,
3	EnvironmentId,
4	ThreadId,
5	type AuthEnvironmentScope,
6	} from "@t3tools/contracts";
7	import { DEFAULT_CLIENT_SETTINGS } from "@t3tools/contracts/settings";
8	import { nextTerminalAttachSeedState } from "@t3tools/client-runtime/state/terminal";
9	import { AsyncResult } from "effect/reactivity";
10	import { act, create, type ReactTestRenderer } from "react-test-renderer";
11	import { afterEach, beforeEach, expect, it, vi } from "vite-plus/test";
12	import type {
13	GhosttyTerminalSurface,
14	GhosttyTerminalSurfaceOptions,
15	} from "~/terminal/ghostty/surface";
16
17	const state = vi.hoisted(() => ({
18	allowed: true,
19	listeners: new Set<() => void>(),
20	resize: vi.fn(),
21	otherCommand: vi.fn(),
22	createSurface:
23	vi.fn<
24	(
25	mount: HTMLElement,
26	options: GhosttyTerminalSurfaceOptions,
27	) => Promise<GhosttyTerminalSurface>
28	>(),
29	}));
30
31	vi.mock("@effect/atom-react", () => ({ useAtomValue: () => null }));
32	vi.mock("../hooks/useSettings", () => ({
33	getClientSettings: () => DEFAULT_CLIENT_SETTINGS,
34	useClientSettings: (select: (settings: typeof DEFAULT_CLIENT_SETTINGS) => unknown) =>
35	select(DEFAULT_CLIENT_SETTINGS),
36	}));
37	vi.mock("../editorPreferences", () => ({ useOpenInPreferredEditor: () => state.otherCommand }));
38	vi.mock("../localApi", () => ({ readLocalApi: () => null }));
39	vi.mock("../state/server", () => ({
40	serverEnvironment: { configValueAtom: () => "config" },
41	}));
42	vi.mock("../state/preview", () => ({ previewEnvironment: { open: "open" } }));
43	vi.mock("../state/terminal", () => ({ terminalEnvironment: { resize: "resize", write: "write" } }));
44	vi.mock("../state/use-atom-command", () => ({
45	useAtomCommand: (command: string) => (command === "resize" ? state.resize : state.otherCommand),
46	}));
47	vi.mock("../state/terminalSessions", () => ({
48	useAttachedTerminalSession: () => session,
49	}));
50	vi.mock("~/terminal/ghostty/surface", () => ({
51	GhosttyTerminalSurface: { create: state.createSurface },
52	}));
53	vi.mock("../state/session", async () => {
54	const { useSyncExternalStore } = await import("react");
55	const readEnvironmentScope = (id: EnvironmentId \| null, scope: AuthEnvironmentScope) =>
56	id !== null &&
57	(scope !== AuthTerminalOperateScope \|\| id !== threadRef.environmentId \|\| state.allowed);
58	return {
59	readEnvironmentScope,
60	useEnvironmentScope: (id: EnvironmentId \| null, scope: AuthEnvironmentScope) =>
61	useSyncExternalStore(
62	(listener) => {
63	state.listeners.add(listener);
64	return () => state.listeners.delete(listener);
65	},
66	() => readEnvironmentScope(id, scope),
67	),
68	};
69	});
70
71	import { TerminalViewport } from "./ThreadTerminalDrawer";
72
73	const threadRef = {
74	environmentId: EnvironmentId.make("secondary-terminal"),
75	threadId: ThreadId.make("thread"),
76	};
77	const session = { ...nextTerminalAttachSeedState(), status: "running" as const, version: 1 };
78	let renderer: ReactTestRenderer \| undefined;
79
80	beforeEach(() => {
81	state.allowed = true;
82	state.listeners.clear();
83	state.resize.mockReset().mockResolvedValue(AsyncResult.success(undefined));
84	state.otherCommand.mockReset().mockResolvedValue(AsyncResult.success(undefined));
85	// A surface can report its initial grid while asynchronous WASM setup is
86	// pending. Keep that unrelated setup pending while exercising its callback.
87	state.createSurface.mockReset().mockReturnValue(new Promise(() => undefined));
88	vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
89	vi.stubGlobal("document", {
90	body: {},
91	documentElement: { classList: { contains: () => false } },
92	querySelector: () => null,
93	createElement: () => ({ getContext: () => null }),
94	});
95	vi.stubGlobal("getComputedStyle", () => ({
96	colorScheme: "light",
97	backgroundColor: "",
98	color: "",
99	getPropertyValue: () => "",
100	}));
101	});
102
103	afterEach(async () => {
104	await act(async () => renderer?.unmount());
105	renderer = undefined;
106	vi.unstubAllGlobals();
107	});
108
109	it("rechecks the target terminal grant when a retained surface callback reports a resize", async () => {
110	await act(async () => {
111	renderer = create(
112	<TerminalViewport
113	advancedTypography={false}
114	threadRef={threadRef}
115	threadId={threadRef.threadId}
116	terminalId="terminal-1"
117	terminalLabel="Terminal 1"
118	cwd="/repo"
119	onSessionExited={state.otherCommand}
120	focusRequestId={0}
121	autoFocus={false}
122	visible={true}
123	resizeEpoch={0}
124	drawerHeight={200}
125	keybindings={[]}
126	/>,
127	{ createNodeMock: () => ({ closest: () => null, contains: () => false }) },
128	);
129	});
130	expect(state.createSurface).toHaveBeenCalledOnce();
131	const onResize = state.createSurface.mock.calls[0]![1].onResize;
132	if (!onResize) throw new Error("The terminal did not register its resize callback.");
133
134	onResize(80, 24);
135	expect(state.resize).toHaveBeenCalledExactlyOnceWith({
136	environmentId: threadRef.environmentId,
137	input: { threadId: threadRef.threadId, terminalId: "terminal-1", cols: 80, rows: 24 },
138	});
139
140	// The connection updates before React commits its external-store update.
141	// Other environments retain access; only this terminal's target is revoked.
142	state.allowed = false;
143	onResize(120, 40);
144	expect(state.resize).toHaveBeenCalledTimes(1);
145
146	state.allowed = true;
147	onResize(100, 30);
148	expect(state.resize).toHaveBeenCalledTimes(2);
149	expect(state.resize).toHaveBeenLastCalledWith({
150	environmentId: threadRef.environmentId,
151	input: { threadId: threadRef.threadId, terminalId: "terminal-1", cols: 100, rows: 30 },
152	});
153	});

apps/web/src/components/ThreadTerminalDrawer.test.ts+66-3

...	@@ -1,9 +1,17 @@	...	@@ -1,9 +1,17 @@
1	import { afterEach, describe, expect, it, vi } from "vite-plus/test";	1	import { afterEach, describe, expect, it, vi } from "vite-plus/test";
		2	import {
		3	applyTerminalAttachStreamEvent,
		4	combineTerminalSessionState,
		5	EMPTY_TERMINAL_BUFFER_STATE,
		6	INITIAL_TERMINAL_OUTPUT_CURSOR,
		7	nextTerminalAttachSeedState,
		8	} from "@t3tools/client-runtime/state/terminal";
2		9
3	import {	10	import {
4	shouldClearTerminalSelectionAction,	11	shouldClearTerminalSelectionAction,
5	shouldHandleTerminalExit,	12	shouldHandleTerminalExit,
6	terminalContextMenuItems,	13	terminalContextMenuItems,
		14	synchronizeTerminalOutput,
7	terminalSelectionLineRange,	15	terminalSelectionLineRange,
8	terminalSelectionMenuItems,	16	terminalSelectionMenuItems,
9	terminalThemeFromApp,	17	terminalThemeFromApp,
...	@@ -138,8 +146,63 @@ describe("terminal selection actions", () => {	...	@@ -138,8 +146,63 @@ describe("terminal selection actions", () => {
138	});	146	});
139		147
140	it("handles an exit that lands while the terminal surface is still loading", () => {	148	it("handles an exit that lands while the terminal surface is still loading", () => {
141	expect(shouldHandleTerminalExit("exited", "running", false)).toBe(true);	149	expect(shouldHandleTerminalExit("exited", "running", false, 1)).toBe(true);
142	expect(shouldHandleTerminalExit("exited", "exited", false)).toBe(false);	150	expect(shouldHandleTerminalExit("exited", "exited", false, 1)).toBe(false);
143	expect(shouldHandleTerminalExit("closed", "running", true)).toBe(false);	151	expect(shouldHandleTerminalExit("closed", "running", true, 1)).toBe(false);
		152	});
		153
		154	it.each(["closed", "exited"] as const)("ignores an unsynchronized %s seed", (status) => {
		155	expect(shouldHandleTerminalExit(status, "running", false, 0)).toBe(false);
		156	expect(shouldHandleTerminalExit(status, "running", false, 1)).toBe(true);
		157	});
		158	});
		159
		160	it("retains visible output and selection until a replacement subscription receives its snapshot", () => {
		161	const terminal = { resetAndWrite: vi.fn(), write: vi.fn(), clearSelection: vi.fn() };
		162	const snapshot = {
		163	threadId: "thread",
		164	terminalId: "term-1",
		165	cwd: "/repo",
		166	worktreePath: null,
		167	status: "running" as const,
		168	pid: 123,
		169	history: "host output",
		170	exitCode: null,
		171	exitSignal: null,
		172	label: "Terminal 1",
		173	updatedAt: "2026-09-05T00:00:00.000Z",
		174	};
		175	const attached = applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), {
		176	type: "snapshot",
		177	snapshot,
		178	});
		179	const cursor = synchronizeTerminalOutput(terminal, attached, INITIAL_TERMINAL_OUTPUT_CURSOR);
		180	expect(terminal.resetAndWrite).toHaveBeenLastCalledWith("host output");
		181	terminal.resetAndWrite.mockClear();
		182	terminal.clearSelection.mockClear();
		183
		184	const pending = combineTerminalSessionState(
		185	{ ...snapshot, hasRunningSubprocess: false },
		186	EMPTY_TERMINAL_BUFFER_STATE,
		187	);
		188	expect(pending.status).toBe("running");
		189	expect(synchronizeTerminalOutput(terminal, pending, cursor)).toBe(cursor);
		190	expect(terminal.resetAndWrite).not.toHaveBeenCalled();
		191	expect(terminal.write).not.toHaveBeenCalled();
		192	expect(terminal.clearSelection).not.toHaveBeenCalled();
		193
		194	const observed = applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), {
		195	type: "snapshot",
		196	snapshot: { ...snapshot, history: "host output\nobserved output" },
		197	});
		198	const observedCursor = synchronizeTerminalOutput(terminal, observed, cursor);
		199	expect(terminal.resetAndWrite).toHaveBeenLastCalledWith("host output\nobserved output");
		200
		201	const cleared = applyTerminalAttachStreamEvent(observed, {
		202	type: "cleared",
		203	threadId: "thread",
		204	terminalId: "term-1",
144	});	205	});
		206	synchronizeTerminalOutput(terminal, cleared, observedCursor);
		207	expect(terminal.resetAndWrite).toHaveBeenLastCalledWith("");
145	});	208	});

apps/web/src/components/ThreadTerminalDrawer.tsx+135-37

 @@ -20,6 +20,8 @@ import {
 } from "lucide-react";
 import {
   AuthPreviewOperateScope,
+  AuthOrchestrationOperateScope,
+  AuthTerminalOperateScope,
   type ContextMenuItem,
   type ProviderInstanceId,
   type ResolvedKeybindingsConfig,
 @@ -83,6 +85,7 @@ import { serverEnvironment } from "../state/server";
 import { previewEnvironment } from "../state/preview";
 import { readEnvironmentScope } from "../state/session";
 import { terminalEnvironment } from "../state/terminal";
+import { useEnvironmentScope } from "../state/session";
 import { openTerminalLinkInPreview } from "./preview/openTerminalLinkInPreview";
 import { useAtomCommand } from "../state/use-atom-command";
 import { preventTerminalCloseShortcut } from "../lib/terminalCloseShortcut";
 @@ -121,6 +124,18 @@ export function writeTerminalOutputUpdate(
   }
 }
+export function synchronizeTerminalOutput(
+  terminal: Pick<GhosttyTerminalSurface, "resetAndWrite" | "write" | "clearSelection">,
+  session: Pick<TerminalSessionState, "output" | "version">,
+  cursor: TerminalOutputCursor,
+): TerminalOutputCursor {
+  if (session.version === 0) return cursor;
+  const update = readTerminalOutputUpdate(session.output, cursor);
+  writeTerminalOutputUpdate(terminal, update);
+  terminal.clearSelection();
+  return update.cursor;
+}
 function parseTerminalColor(value: string, fallback: GhosttyColor): GhosttyColor {
   if (typeof document === "undefined") return fallback;
 @@ -272,6 +287,7 @@ export function terminalSelectionMenuItems(options?: {
 export function terminalContextMenuItems(options: {
   hasSelection: boolean;
   canAddToChat?: boolean;
+  readOnly?: boolean;
 }): ContextMenuItem<TerminalContextMenuAction>[] {
   const { hasSelection, canAddToChat = true } = options;
   return [
 @@ -279,7 +295,7 @@ export function terminalContextMenuItems(options: {
       ...item,
       disabled: !hasSelection,
     })),
-    { id: "paste", label: "Paste" },
+    { id: "paste", label: "Paste", ...(options.readOnly ? { disabled: true } : {}) },
   ];
 }
 @@ -302,9 +318,13 @@ export function shouldHandleTerminalExit(
   current: TerminalSessionState["status"],
   synchronized: TerminalSessionState["status"],
   alreadyHandled: boolean,
+  version: number,
 ): boolean {
   return (
-    (current === "closed" || current === "exited") && current !== synchronized && !alreadyHandled
+    version > 0 &&
+    (current === "closed" || current === "exited") &&
+    current !== synchronized &&
+    !alreadyHandled
   );
 }
 @@ -357,6 +377,15 @@ export function TerminalViewport({
   const terminalRef = useRef<GhosttyTerminalSurface | null>(null);
   const visibleRef = useRef(visible);
   const environmentId = threadRef.environmentId;
+  const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
+  const hasTerminalWriteAccess = useEffectEvent(() =>
+    readEnvironmentScope(environmentId, AuthTerminalOperateScope),
+  );
+  const canOpenHostEditor = useEnvironmentScope(environmentId, AuthOrchestrationOperateScope);
+  const canActivateTerminalLink = useEffectEvent(
+    (text: string) =>
+      isTerminalUrl(text) || readEnvironmentScope(environmentId, AuthOrchestrationOperateScope),
+  );
   const serverConfig = useAtomValue(serverEnvironment.configValueAtom(environmentId));
   const openInPreferredEditor = useOpenInPreferredEditor(
     environmentId,
 @@ -381,7 +410,7 @@ export function TerminalViewport({
   const keybindingsRef = useRef(keybindings);
   const runtimeEnvKey = useMemo(() => runtimeEnvSignature(runtimeEnv), [runtimeEnv]);
   const handleSessionExited = useEffectEvent(() => {
-    onSessionExited();
+    if (hasTerminalWriteAccess()) onSessionExited();
   });
   const handleAddTerminalContext = useEffectEvent((selection: TerminalContextSelection) => {
     onAddTerminalContext?.(selection);
 @@ -414,29 +443,35 @@ export function TerminalViewport({
       ...(providerInstanceId ? { providerInstanceId } : {}),
     },
   });
+  const canResizeTerminal =
+    canOperateTerminal && terminalSession.version > 0 && terminalSession.status === "running";
+  const resizeSessionGeneration = canResizeTerminal ? terminalSession.output.generation : null;
   const writeTerminal = useEffectEvent((data: string) =>
     runTerminalWrite({
       environmentId,
       input: { threadId, terminalId, data },
     }),
   );
-  const resizeTerminal = useEffectEvent((cols: number, rows: number) =>
+  const resizeTerminal = useEffectEvent((cols: number, rows: number) => {
-    runTerminalResize({
+    if (!canResizeTerminal || !hasTerminalWriteAccess()) return;
+    return runTerminalResize({
       environmentId,
       input: { threadId, terminalId, cols, rows },
-    }),
+    });
-  );
+  });
   const terminalOutput = terminalSession.output;
   const terminalError = terminalSession.error;
   const terminalStatus = terminalSession.status;
   const outputCursorRef = useRef<TerminalOutputCursor>(INITIAL_TERMINAL_OUTPUT_CURSOR);
   const synchronizedStatusRef = useRef<TerminalSessionState["status"]>("closed");
   const synchronizeTerminalStatus = useEffectEvent(
-    (terminal: GhosttyTerminalSurface, status: TerminalSessionState["status"]) => {
+    (terminal: GhosttyTerminalSurface, status: TerminalSessionState["status"], version: number) => {
       const synchronized = synchronizedStatusRef.current;
-      if (status === "running") {
+      if (version > 0 && status === "running") {
         hasHandledExitRef.current = false;
-      } else if (shouldHandleTerminalExit(status, synchronized, hasHandledExitRef.current)) {
+      } else if (
+        shouldHandleTerminalExit(status, synchronized, hasHandledExitRef.current, version)
+      ) {
         hasHandledExitRef.current = true;
         writeSystemMessage(terminal, status === "closed" ? "Terminal closed" : "Process exited");
         window.setTimeout(() => {
 @@ -445,7 +480,7 @@ export function TerminalViewport({
           }
         }, 0);
       }
-      synchronizedStatusRef.current = status;
+      if (version > 0) synchronizedStatusRef.current = status;
     },
   );
   const terminalVersion = terminalSession.version;
 @@ -467,6 +502,22 @@ export function TerminalViewport({
     keybindingsRef.current = keybindings;
   }, [keybindings]);
+  useLayoutEffect(() => {
+    if (terminalRef.current) terminalRef.current.input.readOnly = !canOperateTerminal;
+  }, [canOperateTerminal]);
+  // A grant can change while the pointer remains over a link.
+  useEffect(() => {
+    terminalRef.current?.refreshLinkActivation();
+  }, [canOpenHostEditor]);
+  useEffect(() => {
+    if (resizeSessionGeneration === null) return;
+    // The first fit can finish before authorization or the attach snapshot.
+    // Replay its grid once this writable session exists, including reconnects.
+    terminalRef.current?.resendSize();
+  }, [resizeSessionGeneration]);
   useLayoutEffect(() => {
     visibleRef.current = visible;
     terminalRef.current?.setVisible(visible);
 @@ -503,6 +554,7 @@ export function TerminalViewport({
         onSelectionChange: () => handleSelectionChange(),
         beforeKey: (event) => handleBeforeKey(event),
         onLinkActivate: (text, event) => handleLinkActivate(text, event),
+        canActivateLink: (text) => canActivateTerminalLink(text),
         // The surface listens from construction, so a right-click can land
         // while `create` is still awaiting WASM — before the handler below it
         // exists. The ref is only assigned once that setup has run.
 @@ -521,6 +573,7 @@ export function TerminalViewport({
       terminal.setTheme(terminalThemeFromApp(mount));
       setupTerminal = terminal;
       terminalRef.current = terminal;
+      terminal.input.readOnly = !hasTerminalWriteAccess();
       // Client settings hydrate asynchronously; a font preference that landed
       // while the surface was loading found terminalRef null, so its setFont
       // was dropped. Re-apply whatever is current once the terminal exists.
 @@ -544,9 +597,13 @@ export function TerminalViewport({
       // (A session that is "closed" at mount is indistinguishable from one that
       // never started, so only "exited" triggers the message — as with xterm.)
       synchronizedStatusRef.current = "closed";
-      synchronizeTerminalStatus(terminal, latestSession.status);
+      synchronizeTerminalStatus(terminal, latestSession.status, latestSession.version);
       // Startup may finish after the user has returned to the composer.
-      if (visibleRef.current && mount.contains(document.activeElement)) {
+      if (
+        hasTerminalWriteAccess() &&
+        visibleRef.current &&
+        mount.contains(document.activeElement)
+      ) {
         terminal.focus();
       }
 @@ -634,6 +691,7 @@ export function TerminalViewport({
       };
       const pasteFromClipboard = async (requestId: number) => {
+        if (!hasTerminalWriteAccess()) return;
         const activeTerminal = terminalRef.current;
         if (!activeTerminal) return;
         try {
 @@ -667,6 +725,7 @@ export function TerminalViewport({
             terminalContextMenuItems({
               hasSelection: selectionAction !== null,
               canAddToChat: canAddSelectionToChat(),
+              readOnly: !hasTerminalWriteAccess(),
             }),
             { x: event.clientX, y: event.clientY },
           );
 @@ -732,6 +791,7 @@ export function TerminalViewport({
       };
       const sendTerminalInput = async (data: string, fallbackError: string) => {
+        if (!hasTerminalWriteAccess()) return;
         const activeTerminal = terminalRef.current;
         if (!activeTerminal) return;
         const result = await writeTerminal(data);
 @@ -784,6 +844,7 @@ export function TerminalViewport({
       }
       function handleLinkActivate(text: string, event: MouseEvent): void {
+        if (!canActivateTerminalLink(text)) return;
         const latestTerminal = terminalRef.current;
         if (!latestTerminal) return;
         if (isTerminalUrl(text)) {
 @@ -835,6 +896,7 @@ export function TerminalViewport({
       }
       function handleData(data: string): void {
+        if (!hasTerminalWriteAccess()) return;
         void (async () => {
           const result = await writeTerminal(data);
           if (result._tag === "Success" || isAtomCommandInterrupted(result)) return;
 @@ -924,7 +986,9 @@ export function TerminalViewport({
       cancelled = true;
       const hadFocus = mount.contains(document.activeElement);
       teardown?.();
-      if (hadFocus && mount.isConnected) mount.focus({ preventScroll: true });
+      if (hasTerminalWriteAccess() && hadFocus && mount.isConnected) {
+        mount.focus({ preventScroll: true });
+      }
     };
   }, [cwd, environmentId, runtimeEnvKey, terminalId, threadId, worktreePath]);
 @@ -942,15 +1006,12 @@ export function TerminalViewport({
     }
     const previous = previousSessionRef.current;
-    synchronizeTerminalStatus(terminal, current.status);
+    synchronizeTerminalStatus(terminal, current.status, current.version);
     if (current.version === previous.version && current.output === previous.output) {
       return;
     }
-    const outputUpdate = readTerminalOutputUpdate(current.output, outputCursorRef.current);
+    outputCursorRef.current = synchronizeTerminalOutput(terminal, current, outputCursorRef.current);
-    writeTerminalOutputUpdate(terminal, outputUpdate);
-    outputCursorRef.current = outputUpdate.cursor;
-    terminal.clearSelection();
     if (current.error !== null && current.error !== previous.error) {
       writeSystemMessage(terminal, current.error);
 @@ -960,11 +1021,11 @@ export function TerminalViewport({
   }, [terminalOutput, terminalError, terminalStatus, terminalVersion]);
   useEffect(() => {
-    if (!autoFocus || !visible) return;
+    if (!autoFocus || !canOperateTerminal || !visible) return;
     // Claim focus when requested, then hand it to the terminal once ready only
     // if the user has not focused something else in the meantime.
     (terminalRef.current ?? containerRef.current)?.focus();
-  }, [autoFocus, focusRequestId, visible]);
+  }, [autoFocus, canOperateTerminal, focusRequestId, visible]);
   useEffect(() => {
     const terminal = terminalRef.current;
 @@ -1029,14 +1090,29 @@ interface TerminalActionButtonProps {
   className: string;
   onClick: () => void;
   children: ReactNode;
+  disabled?: boolean;
 }
-function TerminalActionButton({ label, className, onClick, children }: TerminalActionButtonProps) {
+function TerminalActionButton({
+  label,
+  className,
+  onClick,
+  children,
+  disabled,
+}: TerminalActionButtonProps) {
   return (
     <Popover>
       <PopoverTrigger
         openOnHover
-        render={<button type="button" className={className} onClick={onClick} aria-label={label} />}
+        render={
+          <button
+            type="button"
+            className={cn(className, disabled && "opacity-45 cursor-not-allowed")}
+            onClick={disabled ? undefined : onClick}
+            aria-label={label}
+            aria-disabled={disabled}
+          />
+        }
       >
         {children}
       </PopoverTrigger>
 @@ -1082,6 +1158,7 @@ export default function ThreadTerminalDrawer({
   terminalLabelsById,
   terminalLaunchLocationsById,
 }: ThreadTerminalDrawerProps) {
+  const canOperateTerminal = useEnvironmentScope(threadRef.environmentId, AuthTerminalOperateScope);
   const isPanel = mode === "panel";
   const [advancedTypography] = useLocalStorage(
     TYPOGRAPHY_ADVANCED_STORAGE_KEY,
 @@ -1273,24 +1350,28 @@ export default function ThreadTerminalDrawer({
     ? `Close Terminal (${closeShortcutLabel})`
     : "Close Terminal";
   const onSplitTerminalAction = useCallback(() => {
-    if (hasReachedSplitLimit) return;
+    if (!canOperateTerminal || hasReachedSplitLimit) return;
     onSplitTerminal();
-  }, [hasReachedSplitLimit, onSplitTerminal]);
+  }, [canOperateTerminal, hasReachedSplitLimit, onSplitTerminal]);
   const onSplitTerminalVerticalAction = useCallback(() => {
-    if (hasReachedSplitLimit) return;
+    if (!canOperateTerminal || hasReachedSplitLimit) return;
     onSplitTerminalVertical();
-  }, [hasReachedSplitLimit, onSplitTerminalVertical]);
+  }, [canOperateTerminal, hasReachedSplitLimit, onSplitTerminalVertical]);
   const onNewTerminalAction = useCallback(() => {
+    if (!canOperateTerminal) return;
     onNewTerminal();
-  }, [onNewTerminal]);
+  }, [canOperateTerminal, onNewTerminal]);
   const confirmCloseTerminal = useCallback(
     (terminalId: string) => {
+      if (!canOperateTerminal) return;
       const label = terminalLabelById.get(terminalId) ?? getTerminalLabel(terminalId);
       void confirmTerminalClose([label]).then((confirmed) => {
-        if (confirmed) onCloseTerminal(terminalId);
+        if (confirmed && readEnvironmentScope(threadRef.environmentId, AuthTerminalOperateScope)) {
+          onCloseTerminal(terminalId);
+        }
       });
     },
-    [onCloseTerminal, terminalLabelById],
+    [canOperateTerminal, onCloseTerminal, terminalLabelById, threadRef.environmentId],
   );
   useEffect(() => {
 @@ -1417,7 +1498,12 @@ export default function ThreadTerminalDrawer({
         ) : null}
         <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 size="xs" variant="outline" onClick={onNewTerminalAction}>
+          <Button
+            size="xs"
+            variant="outline"
+            onClick={onNewTerminalAction}
+            disabled={!canOperateTerminal}
+          >
             {newTerminalActionLabel}
           </Button>
         </div>
 @@ -1451,6 +1537,7 @@ export default function ThreadTerminalDrawer({
         <div className="pointer-events-none absolute right-2 top-2 z-20">
           <div className="pointer-events-auto inline-flex items-center overflow-hidden rounded-md border border-border/80 bg-background shadow-xs">
             <TerminalActionButton
+              disabled={!canOperateTerminal}
               className={`p-1 text-foreground/90 transition-colors ${
                 hasReachedSplitLimit
                   ? "cursor-not-allowed opacity-64 hover:bg-transparent"
 @@ -1463,6 +1550,7 @@ export default function ThreadTerminalDrawer({
             </TerminalActionButton>
             <div className="h-4 w-px bg-border/80" />
             <TerminalActionButton
+              disabled={!canOperateTerminal}
               className={`p-1 text-foreground/90 transition-colors ${
                 hasReachedSplitLimit
                   ? "cursor-not-allowed opacity-64 hover:bg-transparent"
 @@ -1475,6 +1563,7 @@ export default function ThreadTerminalDrawer({
             </TerminalActionButton>
             <div className="h-4 w-px bg-border/80" />
             <TerminalActionButton
+              disabled={!canOperateTerminal}
               className="p-1 text-foreground/90 transition-colors hover:bg-accent"
               onClick={onNewTerminalAction}
               label={newTerminalActionLabel}
 @@ -1483,6 +1572,7 @@ export default function ThreadTerminalDrawer({
             </TerminalActionButton>
             <div className="h-4 w-px bg-border/80" />
             <TerminalActionButton
+              disabled={!canOperateTerminal}
               className="p-1 text-foreground/90 transition-colors hover:bg-accent"
               onClick={() => confirmCloseTerminal(resolvedActiveTerminalId)}
               label={closeTerminalActionLabel}
 @@ -1596,6 +1686,7 @@ export default function ThreadTerminalDrawer({
               <div className="flex h-[22px] items-stretch justify-end border-b border-border/70">
                 <div className="inline-flex h-full items-stretch">
                   <TerminalActionButton
+                    disabled={!canOperateTerminal}
                     className={`inline-flex h-full items-center px-1 text-foreground/90 transition-colors ${
                       hasReachedSplitLimit
                         ? "cursor-not-allowed opacity-64 hover:bg-transparent"
 @@ -1607,6 +1698,7 @@ export default function ThreadTerminalDrawer({
                     <SquareSplitHorizontal className="size-3.25" />
                   </TerminalActionButton>
                   <TerminalActionButton
+                    disabled={!canOperateTerminal}
                     className={`inline-flex h-full items-center border-l border-border/70 px-1 text-foreground/90 transition-colors ${
                       hasReachedSplitLimit
                         ? "cursor-not-allowed opacity-64 hover:bg-transparent"
 @@ -1618,6 +1710,7 @@ export default function ThreadTerminalDrawer({
                     <SquareSplitVertical className="size-3.25" />
                   </TerminalActionButton>
                   <TerminalActionButton
+                    disabled={!canOperateTerminal}
                     className="inline-flex h-full items-center border-l border-border/70 px-1 text-foreground/90 transition-colors hover:bg-accent/70"
                     onClick={onNewTerminalAction}
                     label={newTerminalActionLabel}
 @@ -1625,6 +1718,7 @@ export default function ThreadTerminalDrawer({
                     <Plus className="size-3.25" />
                   </TerminalActionButton>
                   <TerminalActionButton
+                    disabled={!canOperateTerminal}
                     className="inline-flex h-full items-center border-l border-border/70 px-1 text-foreground/90 transition-colors hover:bg-accent/70"
                     onClick={() => confirmCloseTerminal(resolvedActiveTerminalId)}
                     label={closeTerminalActionLabel}
 @@ -1691,13 +1785,17 @@ export default function ThreadTerminalDrawer({
                                   : "text-muted-foreground hover:bg-accent/60 hover:text-foreground",
                               )}
                             >
-                              <PanelTabCloseButton
+                              {canOperateTerminal ? (
-                                label={closeTerminalLabel}
+                                <PanelTabCloseButton
-                                onClick={() => confirmCloseTerminal(terminalId)}
+                                  label={closeTerminalLabel}
-                                tooltip={closeTerminalLabel}
+                                  onClick={() => confirmCloseTerminal(terminalId)}
-                              >
+                                  tooltip={closeTerminalLabel}
+                                >
+                                  <TerminalSquare className="size-3 shrink-0" />
+                                </PanelTabCloseButton>
+                              ) : (
                                 <TerminalSquare className="size-3 shrink-0" />
-                              </PanelTabCloseButton>
+                              )}
                               <button
                                 type="button"
                                 className="flex min-w-0 flex-1 cursor-pointer items-center gap-1 text-left"

apps/web/src/components/onboarding/WelcomeWizard.terminal.test.tsx created+470

...	@@ -0,0 +1,470 @@
1	import { RegistryContext } from "@effect/atom-react";
2	import {
3	BearerConnectionTarget,
4	PrimaryConnectionTarget,
5	} from "@t3tools/client-runtime/connection";
6	import {
7	AuthTerminalOperateScope,
8	DEFAULT_SERVER_SETTINGS,
9	EnvironmentId,
10	ProviderDriverKind,
11	ProviderInstanceId,
12	type AuthEnvironmentScope,
13	type AuthSessionState,
14	type ResolvedKeybindingsConfig,
15	type ServerProvider,
16	type ServerSettings,
17	type TerminalCloseInput,
18	type TerminalOpenInput,
19	type TerminalWriteInput,
20	} from "@t3tools/contracts";
21	import { DEFAULT_RESOLVED_KEYBINDINGS } from "@t3tools/shared/keybindings";
22	import * as Cause from "effect/Cause";
23	import { AsyncResult, Atom, AtomRegistry } from "effect/reactivity";
24	import { act, create, type ReactTestInstance, type ReactTestRenderer } from "react-test-renderer";
25	import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
26
27	type SessionResult = AsyncResult.AsyncResult<AuthSessionState, Error>;
28	type CommandResult = AsyncResult.AsyncResult<void, Error>;
29	type Request<Input> = { environmentId: EnvironmentId; input: Input };
30	type SetupConfig = {
31	cwd: string;
32	settings: ServerSettings;
33	environment: { platform: { os: "darwin" } };
34	keybindings: ResolvedKeybindingsConfig;
35	};
36	const state = vi.hoisted(() => ({
37	registry: null as AtomRegistry.AtomRegistry \| null,
38	sessions: new Map<EnvironmentId, Atom.Writable<SessionResult>>(),
39	providers: new Map<EnvironmentId, Atom.Writable<ReadonlyArray<ServerProvider>>>(),
40	configs: new Map<EnvironmentId, Atom.Atom<SetupConfig>>(),
41	open: vi.fn<(request: Request<TerminalOpenInput>) => Promise<CommandResult>>(),
42	write: vi.fn<(request: Request<TerminalWriteInput>) => Promise<CommandResult>>(),
43	close: vi.fn<(request: Request<TerminalCloseInput>) => Promise<CommandResult>>(),
44	refresh: vi.fn(),
45	pair: vi.fn(),
46	createProject: vi.fn(),
47	importThreads: vi.fn(),
48	complete: vi.fn<() => Promise<void>>(),
49	done: vi.fn(),
50	}));
51
52	vi.mock("../../connection/runtime", () => ({ connectionAtomRuntime: undefined }));
53	vi.mock("@t3tools/client-runtime/state/session", () => ({
54	createEnvironmentSessionAtoms: () => ({
55	sessionStateAtom: (id: EnvironmentId) => state.sessions.get(id)!,
56	}),
57	}));
58	vi.mock("../../rpc/atomRegistry", () => ({
59	get appAtomRegistry() {
60	return state.registry;
61	},
62	}));
63	vi.mock("../../state/environments", () => ({
64	useEnvironments: () => ({ environments: [remoteEnvironment] }),
65	usePrimaryEnvironment: () => primaryEnvironment,
66	}));
67	vi.mock("../../state/server", () => ({
68	serverEnvironment: {
69	providersValueAtom: (id: EnvironmentId) => state.providers.get(id)!,
70	configValueAtom: (id: EnvironmentId) => state.configs.get(id)!,
71	refreshProviders: "refresh",
72	},
73	}));
74	vi.mock("../../state/terminal", () => ({
75	terminalEnvironment: { open: "open", write: "write", close: "close" },
76	}));
77	vi.mock("../../state/use-atom-command", () => ({
78	useAtomCommand: (
79	command: "open" \| "write" \| "close" \| "refresh" \| "pair" \| "createProject" \| "importThreads",
80	) => state[command],
81	}));
82	vi.mock("../../connection/onboarding", () => ({ connectPairing: "pair" }));
83	vi.mock("../../state/agentSessions", () => ({
84	agentSessionImport: "importThreads",
85	agentSessionScan: vi.fn(),
86	}));
87	vi.mock("../../state/projects", () => ({ projectEnvironment: { create: "createProject" } }));
88	vi.mock("../../state/entities", () => ({ readProjects: () => [], useProjects: () => [] }));
89	vi.mock("../../onboarding/useProjectScans", () => ({ useProjectScans: () => [] }));
90	vi.mock("../ui/dialog", () => ({
91	Dialog: "div",
92	DialogPopup: "div",
93	DialogTitle: "div",
94	DialogHeader: "div",
95	}));
96	vi.mock("../ui/wizard", () => ({
97	WizardPanel: "div",
98	WizardPopup: "div",
99	WizardHeader: "div",
100	WizardSteps: ({ onStepChange }: { onStepChange: (step: number) => void }) => (
101	<button onClick={() => onStepChange(0)}>Back</button>
102	),
103	}));
104	vi.mock("../ui/scroll-area", () => ({ ScrollArea: "div" }));
105	vi.mock("../../onboarding/firstRun", () => ({ useCompleteOnboarding: () => state.complete }));
106	vi.mock("../../hooks/useTheme", () => ({ mountOnboardingTheme: () => undefined }));
107	vi.mock("../../hooks/useLocalStorage", () => ({ useLocalStorage: () => [false, vi.fn()] }));
108	vi.mock("../../hooks/useCopyToClipboard", () => ({
109	useCopyToClipboard: () => ({ copyToClipboard: vi.fn(), isCopied: false }),
110	}));
111	vi.mock("../../cloud/publicConfig", () => ({ hasCloudPublicConfig: () => false }));
112	vi.mock("../clerk/useT3ConnectAuthPrompt", () => ({ useT3ConnectAuthPrompt: vi.fn() }));
113	vi.mock("@clerk/react", () => ({ useAuth: vi.fn() }));
114	vi.mock("../../env", () => ({ isElectron: false }));
115	vi.mock("../../providerInstances", () => ({ resolveDefaultProviderModelSelection: vi.fn() }));
116	vi.mock("../settings/ChatGptWelcomeCoordinator", () => ({ ChatGptWelcomeCoordinator: () => null }));
117	vi.mock("../settings/CodexSetupSection", () => ({
118	CodexSetupSection: () => null,
119	AddManagedCodexAccountDialog: () => null,
120	}));
121	vi.mock("../settings/providerDriverMeta", () => ({
122	getDriverOption: (driver: string) => ({ label: driver }),
123	}));
124	vi.mock("../settings/providerStatus", () => ({
125	getProviderSummary: () => ({ headline: "Setup required" }),
126	}));
127	vi.mock("../cloud/CloudEnvironmentConnectList", () => ({
128	CloudEnvironmentConnectRows: () => null,
129	}));
130	vi.mock("../ThreadTerminalDrawer", () => ({
131	TerminalViewport: () => <div data-terminal-viewport />,
132	}));
133	vi.mock("../ui/button", () => ({ Button: "button" }));
134	vi.mock("../ui/input", () => ({ Input: "input" }));
135	vi.mock("../ui/checkbox", () => ({ Checkbox: "input" }));
136	vi.mock("../ui/collapsible", () => ({
137	Collapsible: "div",
138	CollapsiblePanel: "div",
139	CollapsibleTrigger: "button",
140	}));
141	vi.mock("../ui/toast", () => ({
142	toastManager: { add: vi.fn(), update: vi.fn(), close: vi.fn() },
143	}));
144
145	import { WelcomeWizard } from "./WelcomeWizard";
146
147	const primaryId = EnvironmentId.make("primary");
148	const remoteId = EnvironmentId.make("paired-remote");
149	const primaryEnvironment = {
150	environmentId: primaryId,
151	label: "This computer",
152	connection: { phase: "connected" },
153	entry: {
154	target: new PrimaryConnectionTarget({
155	environmentId: primaryId,
156	label: "This computer",
157	httpBaseUrl: "http://127.0.0.1:3773",
158	wsBaseUrl: "ws://127.0.0.1:3773",
159	}),
160	},
161	} as const;
162	const remoteEnvironment = {
163	environmentId: remoteId,
164	label: "Paired computer",
165	connection: { phase: "connected" },
166	entry: {
167	target: new BearerConnectionTarget({
168	environmentId: remoteId,
169	label: "Paired computer",
170	connectionId: "paired-remote",
171	}),
172	},
173	} as const;
174	const missingClaude: ServerProvider = {
175	instanceId: ProviderInstanceId.make("claude-work"),
176	driver: ProviderDriverKind.make("claudeAgent"),
177	enabled: true,
178	installed: false,
179	version: null,
180	status: "error",
181	auth: { status: "unknown" },
182	checkedAt: "2026-09-05T00:00:00.000Z",
183	models: [],
184	slashCommands: [],
185	skills: [],
186	};
187	const signedOutCodex: ServerProvider = {
188	...missingClaude,
189	instanceId: ProviderInstanceId.make("codex-work"),
190	driver: ProviderDriverKind.make("codex"),
191	installed: true,
192	auth: { status: "unauthenticated" },
193	};
194	const session = (scopes: readonly AuthEnvironmentScope[]): AuthSessionState => ({
195	authenticated: true,
196	scopes,
197	auth: {
198	policy: "remote-reachable",
199	bootstrapMethods: ["one-time-token"],
200	sessionMethods: ["bearer-access-token"],
201	sessionCookieName: "t3_session",
202	},
203	});
204	function setAccess(environmentId: EnvironmentId, allowed: boolean) {
205	state.registry!.set(
206	state.sessions.get(environmentId)!,
207	AsyncResult.success(session(allowed ? [AuthTerminalOperateScope] : [])),
208	);
209	}
210	function deferred<T>() {
211	let resolve!: (value: T) => void;
212	const promise = new Promise<T>((complete) => {
213	resolve = complete;
214	});
215	return { promise, resolve };
216	}
217	function text(node: ReactTestInstance \| string): string {
218	return typeof node === "string" ? node : node.children.map(text).join("");
219	}
220	let renderer: ReactTestRenderer \| undefined;
221	function button(label: string) {
222	return renderer!.root.findAllByType("button").find((node) => text(node) === label)!;
223	}
224	async function click(label: string) {
225	const node = button(label);
226	expect(node).toBeDefined();
227	expect(node.props.disabled).not.toBe(true);
228	await act(async () => node.props.onClick());
229	}
230	function hasViewport() {
231	return renderer!.root.findAllByProps({ "data-terminal-viewport": true }).length > 0;
232	}
233	async function enterRemoteAgents() {
234	await act(async () => {
235	renderer = create(
236	<RegistryContext.Provider value={state.registry!}>
237	<WelcomeWizard localAvailable onDone={state.done} />
238	</RegistryContext.Provider>,
239	);
240	});
241	await click("Continue");
242	expect(text(renderer!.root)).toContain("Paired computer");
243	}
244
245	beforeEach(() => {
246	vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
247	vi.stubGlobal("document", { activeElement: null, body: {}, getElementById: () => null });
248	state.registry = AtomRegistry.make();
249	for (const id of [primaryId, remoteId]) {
250	state.sessions.set(
251	id,
252	Atom.make<SessionResult>(AsyncResult.success(session([AuthTerminalOperateScope]))).pipe(
253	Atom.keepAlive,
254	),
255	);
256	state.providers.set(
257	id,
258	Atom.make<ReadonlyArray<ServerProvider>>([missingClaude, signedOutCodex]).pipe(
259	Atom.keepAlive,
260	),
261	);
262	state.configs.set(
263	id,
264	Atom.make<SetupConfig>({
265	cwd: `/fixtures/${id}`,
266	settings: {
267	...DEFAULT_SERVER_SETTINGS,
268	providerInstances: {
269	[signedOutCodex.instanceId]: {
270	driver: signedOutCodex.driver,
271	config: { binaryPath: "/opt/codex-work", setupMode: "existing" },
272	},
273	},
274	},
275	environment: { platform: { os: "darwin" } },
276	keybindings: DEFAULT_RESOLVED_KEYBINDINGS,
277	}),
278	);
279	}
280	state.open.mockReset().mockResolvedValue(AsyncResult.success(undefined));
281	state.write.mockReset().mockResolvedValue(AsyncResult.success(undefined));
282	state.close.mockReset().mockResolvedValue(AsyncResult.success(undefined));
283	state.refresh.mockReset().mockResolvedValue(AsyncResult.success(undefined));
284	state.pair.mockReset().mockResolvedValue(AsyncResult.success(remoteId));
285	state.complete.mockReset().mockResolvedValue(undefined);
286	state.done.mockReset();
287	});
288
289	afterEach(async () => {
290	await act(async () => renderer?.unmount());
291	renderer = undefined;
292	state.registry?.dispose();
293	state.sessions.clear();
294	state.providers.clear();
295	state.configs.clear();
296	vi.unstubAllGlobals();
297	});
298
299	describe("welcome agent terminal setup", () => {
300	it("disables both setup actions for the paired read-only connection and preserves local completion", async () => {
301	setAccess(remoteId, false);
302	await enterRemoteAgents();
303	expect(button("Install").props.disabled).toBe(true);
304	expect(button("Sign in").props.disabled).toBe(true);
305	expect(text(renderer!.root)).toContain("This connection cannot control terminals.");
306	await act(async () => {
307	button("Install").props.onClick();
308	button("Sign in").props.onClick();
309	});
310	expect(state.open).not.toHaveBeenCalled();
311	expect(state.write).not.toHaveBeenCalled();
312	expect(state.close).not.toHaveBeenCalled();
313	await click("Continue");
314	await click("Do not import projects");
315	expect(state.complete).toHaveBeenCalledOnce();
316	expect(state.done).toHaveBeenCalledExactlyOnceWith(undefined);
317	});
318
319	it("rejects a retained install action after revocation and allows a terminal-only regrant", async () => {
320	setAccess(primaryId, false);
321	await enterRemoteAgents();
322	const install = button("Install").props.onClick;
323	await act(async () => {
324	setAccess(remoteId, false);
325	install();
326	});
327	expect(state.open).not.toHaveBeenCalled();
328	expect(button("Install").props.disabled).toBe(true);
329	await act(async () => setAccess(remoteId, true));
330	expect(button("Install").props.disabled).toBe(false);
331	await act(async () => install());
332	expect(state.open).toHaveBeenCalledExactlyOnceWith({
333	environmentId: remoteId,
334	input: {
335	threadId: "onboarding-agent-setup",
336	terminalId: expect.any(String),
337	cwd: "/fixtures/paired-remote",
338	providerInstanceId: missingClaude.instanceId,
339	},
340	});
341	expect(state.write).toHaveBeenCalledExactlyOnceWith({
342	environmentId: remoteId,
343	input: {
344	threadId: "onboarding-agent-setup",
345	terminalId: state.open.mock.calls[0]![0].input.terminalId,
346	data: "curl -fsSL https://claude.ai/install.sh \| bash",
347	},
348	});
349	expect(hasViewport()).toBe(true);
350	await click("Close");
351	expect(state.close).toHaveBeenCalledExactlyOnceWith({
352	environmentId: remoteId,
353	input: {
354	threadId: "onboarding-agent-setup",
355	terminalId: state.open.mock.calls[0]![0].input.terminalId,
356	deleteHistory: true,
357	},
358	});
359	});
360
361	it("pretypes the selected provider's sign-in command without executing it", async () => {
362	setAccess(primaryId, false);
363	await enterRemoteAgents();
364	await click("Sign in");
365	expect(state.open).toHaveBeenCalledExactlyOnceWith({
366	environmentId: remoteId,
367	input: {
368	threadId: "onboarding-agent-setup",
369	terminalId: expect.any(String),
370	cwd: "/fixtures/paired-remote",
371	providerInstanceId: signedOutCodex.instanceId,
372	},
373	});
374	expect(state.write).toHaveBeenCalledExactlyOnceWith({
375	environmentId: remoteId,
376	input: {
377	threadId: "onboarding-agent-setup",
378	terminalId: state.open.mock.calls[0]![0].input.terminalId,
379	data: "/opt/codex-work login",
380	},
381	});
382	expect(text(renderer!.root)).toContain("Review the command, then press Enter to run it.");
383	});
384
385	it("checks access when a queued retry starts and recovers after regrant", async () => {
386	state.open.mockResolvedValueOnce(AsyncResult.failure(Cause.fail(new Error("Could not open"))));
387	await enterRemoteAgents();
388	await click("Install");
389	const closing = deferred<CommandResult>();
390	state.close.mockReturnValueOnce(closing.promise);
391	await click("Retry");
392	expect(state.close).toHaveBeenCalledOnce();
393	expect(state.open).toHaveBeenCalledOnce();
394	await act(async () => {
395	setAccess(remoteId, false);
396	closing.resolve(AsyncResult.success(undefined));
397	});
398	expect(state.open).toHaveBeenCalledOnce();
399	expect(button("Retry").props.disabled).toBe(true);
400	expect(state.write).not.toHaveBeenCalled();
401	await act(async () => setAccess(remoteId, true));
402	await click("Retry");
403	expect(state.open).toHaveBeenCalledTimes(2);
404	expect(state.write).toHaveBeenCalledOnce();
405	expect(hasViewport()).toBe(true);
406	});
407
408	it("keeps an accepted terminal visible without pretyping when access is revoked during open", async () => {
409	const opening = deferred<CommandResult>();
410	state.open.mockReturnValueOnce(opening.promise);
411	await enterRemoteAgents();
412	await click("Install");
413	await act(async () => {
414	setAccess(remoteId, false);
415	opening.resolve(AsyncResult.success(undefined));
416	});
417	expect(state.write).not.toHaveBeenCalled();
418	expect(state.close).not.toHaveBeenCalled();
419	expect(hasViewport()).toBe(true);
420	expect(text(renderer!.root)).toContain("This connection cannot control terminals.");
421	await act(async () => setAccess(remoteId, true));
422	expect(state.open).toHaveBeenCalledOnce();
423	expect(state.write).not.toHaveBeenCalled();
424	expect(text(renderer!.root)).toContain(
425	"Run curl -fsSL https://claude.ai/install.sh \| bash in this",
426	);
427	await act(async () => setAccess(remoteId, false));
428	await click("Close");
429	expect(hasViewport()).toBe(false);
430	expect(state.close).not.toHaveBeenCalled();
431	await click("Continue");
432	expect(text(renderer!.root)).toContain("Choose your projects");
433	});
434
435	it("settles accepted pretyping locally after revocation without closing the PTY", async () => {
436	const writing = deferred<CommandResult>();
437	state.write.mockReturnValueOnce(writing.promise);
438	await enterRemoteAgents();
439	await click("Sign in");
440	await act(async () => {
441	setAccess(remoteId, false);
442	writing.resolve(AsyncResult.success(undefined));
443	});
444	expect(state.open).toHaveBeenCalledOnce();
445	expect(state.write).toHaveBeenCalledOnce();
446	expect(hasViewport()).toBe(true);
447	await act(async () => setAccess(remoteId, true));
448	expect(text(renderer!.root)).toContain("Review the command, then press Enter to run it.");
449	expect(state.open).toHaveBeenCalledOnce();
450	expect(state.write).toHaveBeenCalledOnce();
451	await act(async () => setAccess(remoteId, false));
452	await click("Close");
453	expect(state.close).not.toHaveBeenCalled();
454	});
455
456	it("rechecks the original environment when cleanup runs after pending pretyping", async () => {
457	const writing = deferred<CommandResult>();
458	state.write.mockReturnValueOnce(writing.promise);
459	await enterRemoteAgents();
460	await click("Install");
461	await click("Back");
462	expect(state.close).not.toHaveBeenCalled();
463	await act(async () => {
464	setAccess(remoteId, false);
465	writing.resolve(AsyncResult.success(undefined));
466	});
467	expect(state.close).not.toHaveBeenCalled();
468	expect(text(renderer!.root)).toContain("Connect your computers");
469	});
470	});

apps/web/src/components/onboarding/WelcomeWizard.tsx+51-11

 @@ -15,6 +15,7 @@ import {
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
 import {
+  AuthTerminalOperateScope,
   CommandId,
   defaultInstanceIdForDriver,
   AuthOrchestrationOperateScope,
 @@ -61,7 +62,11 @@ import { isOnboardingRelayEnvironment } from "../../onboarding/targetEnvironment
 import { useProjectScans } from "../../onboarding/useProjectScans";
 import { projectEnvironment } from "../../state/projects";
 import { serverEnvironment } from "../../state/server";
-import { readEnvironmentScope, useEnvironmentsWithScope } from "../../state/session";
+import {
+  readEnvironmentScope,
+  useEnvironmentScope,
+  useEnvironmentsWithScope,
+} from "../../state/session";
 import { terminalEnvironment } from "../../state/terminal";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { connectPairing } from "../../connection/onboarding";
 @@ -712,6 +717,7 @@ function ConnectedAgentsStep({
     displayName: string;
     autoStart: boolean;
   } | null>(null);
+  const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
   // Re-probe on entry so freshly installed CLIs show up without a manual
   // refresh; harmless when nothing changed (single-flighted per environment).
 @@ -745,6 +751,11 @@ function ConnectedAgentsStep({
   return (
     <section>
       <h2 className="mb-2 text-sm font-medium">{machineLabel}</h2>
+      {!canOperateTerminal ? (
+        <p className="mb-2 text-sm text-muted-foreground">
+          This connection cannot control terminals.
+        </p>
+      ) : null}
       <div className="space-y-1.5">
         {primaryAgents.map(({ driver, provider, instanceId }) =>
           driver === "codex" && serverConfig !== null ? (
 @@ -759,7 +770,11 @@ function ConnectedAgentsStep({
               }
               terminalOpen={terminalSession?.driver === driver}
               onOpenTerminal={() => {
-                if (provider === undefined) return;
+                if (
+                  provider === undefined ||
+                  !readEnvironmentScope(environmentId, AuthTerminalOperateScope)
+                )
+                  return;
                 setTerminalSession({
                   environmentId,
                   driver,
 @@ -785,9 +800,14 @@ function ConnectedAgentsStep({
               driver={driver}
               provider={provider}
               terminalOpen={terminalSession?.driver === driver}
-              terminalAvailable={serverConfig !== null}
+              terminalAvailable={serverConfig !== null && canOperateTerminal}
               onOpenTerminal={() => {
-                if (provider === undefined || serverConfig === null) return;
+                if (
+                  provider === undefined ||
+                  serverConfig === null ||
+                  !readEnvironmentScope(environmentId, AuthTerminalOperateScope)
+                )
+                  return;
                 setTerminalSession({
                   environmentId,
                   driver,
 @@ -864,6 +884,7 @@ function OnboardingCodexSetup({
   } | null;
   readonly onAutoStartConsumed: () => void;
 }) {
+  const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
   const update = useAtomCommand(serverEnvironment.updateSettings, "Codex setup settings");
   const instanceId =
     createdAccount?.instanceId ??
 @@ -911,7 +932,7 @@ function OnboardingCodexSetup({
       driver="codex"
       provider={provider}
       terminalOpen={terminalOpen}
-      terminalAvailable
+      terminalAvailable={canOperateTerminal}
       onOpenTerminal={onOpenTerminal}
     />
   ) : (
 @@ -1005,6 +1026,7 @@ function AgentInstallTerminal({
   readonly onClose: () => void;
 }) {
   const { command, cwd, driver, environmentId, keybindings, providerInstanceId } = session;
+  const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
   // Same terminal typography preference the thread drawer honors.
   const [advancedTypography] = useLocalStorage(
     TYPOGRAPHY_ADVANCED_STORAGE_KEY,
 @@ -1039,6 +1061,10 @@ function AgentInstallTerminal({
     setupQueueRef.current = setupQueueRef.current.then(async () => {
       if (activeSetupGenerationRef.current !== generation) return;
+      if (!readEnvironmentScope(environmentId, AuthTerminalOperateScope)) {
+        setSetupState("openFailed");
+        return;
+      }
       const opened = await openTerminal({
         environmentId,
         input: {
 @@ -1054,6 +1080,10 @@ function AgentInstallTerminal({
       }
       if (activeSetupGenerationRef.current !== generation) return;
+      if (!readEnvironmentScope(environmentId, AuthTerminalOperateScope)) {
+        setSetupState("writeFailed");
+        return;
+      }
       const wrote = await writeTerminal({
         environmentId,
 @@ -1063,15 +1093,14 @@ function AgentInstallTerminal({
       setSetupState(wrote._tag === "Success" ? "ready" : "writeFailed");
     });
-    // Every exit path unmounts the drawer (Done, Continue/Skip, card switch,
+    // Every exit path unmounts the drawer. Close the PTY only while this
-    // session exit), so this cleanup is the single place the PTY dies —
+    // connection still has terminal access; revocation leaves it running.
-    // nothing is left running behind the wizard. An interrupted install is
-    // re-runnable from the card.
     return () => {
       if (activeSetupGenerationRef.current === generation) {
         activeSetupGenerationRef.current = null;
       }
       setupQueueRef.current = setupQueueRef.current.then(async () => {
+        if (!readEnvironmentScope(environmentId, AuthTerminalOperateScope)) return;
         await closeTerminal({
           environmentId,
           input: { threadId: AGENT_ONBOARDING_THREAD_ID, terminalId, deleteHistory: true },
 @@ -1097,7 +1126,9 @@ function AgentInstallTerminal({
     >
       <div className="flex items-center justify-between border-b border-border/60 bg-background/60 px-3 py-1.5">
         <span className="text-2xs font-medium text-muted-foreground">
-          {setupState === "writeFailed" ? (
+          {!canOperateTerminal ? (
+            "This connection cannot control terminals."
+          ) : setupState === "writeFailed" ? (
             <>
               Run <code className="rounded bg-muted px-1 font-mono">{command}</code> in this
               terminal.
 @@ -1112,7 +1143,16 @@ function AgentInstallTerminal({
         </span>
         <div className="flex items-center gap-1">
           {setupState === "openFailed" ? (
-            <Button size="xs" variant="ghost" onClick={() => setSetupAttempt((value) => value + 1)}>
+            <Button
+              size="xs"
+              variant="ghost"
+              disabled={!canOperateTerminal}
+              onClick={() => {
+                if (readEnvironmentScope(environmentId, AuthTerminalOperateScope)) {
+                  setSetupAttempt((value) => value + 1);
+                }
+              }}
+            >
               Retry
             </Button>
           ) : null}

apps/web/src/components/settings/ConnectionsSettings.logic.test.ts+36

...	@@ -6,8 +6,44 @@ import {	...	@@ -6,8 +6,44 @@ import {
6	isQrShareableEndpoint,	6	isQrShareableEndpoint,
7	isWslSettingsRowVisible,	7	isWslSettingsRowVisible,
8	selectQrEndpointOption,	8	selectQrEndpointOption,
		9	togglePairingScopeSelection,
9	} from "./ConnectionsSettings.logic";	10	} from "./ConnectionsSettings.logic";
10		11
		12	describe("togglePairingScopeSelection", () => {
		13	it.each([
		14	{
		15	label: "adds terminal:read when terminal:operate is selected",
		16	current: ["orchestration:read"],
		17	scope: "terminal:operate",
		18	checked: true,
		19	expected: ["orchestration:read", "terminal:operate", "terminal:read"],
		20	},
		21	{
		22	label: "drops terminal:operate when terminal:read is cleared",
		23	current: ["terminal:read", "terminal:operate", "relay:read"],
		24	scope: "terminal:read",
		25	checked: false,
		26	expected: ["relay:read"],
		27	},
		28	{
		29	label: "keeps terminal:read when terminal:operate is cleared",
		30	current: ["terminal:read", "terminal:operate"],
		31	scope: "terminal:operate",
		32	checked: false,
		33	expected: ["terminal:read"],
		34	},
		35	{
		36	label: "toggles unrelated scopes on their own",
		37	current: ["terminal:read"],
		38	scope: "filesystem:read",
		39	checked: true,
		40	expected: ["terminal:read", "filesystem:read"],
		41	},
		42	] as const)("$label", ({ current, scope, checked, expected }) => {
		43	expect(togglePairingScopeSelection(current, scope, checked)).toEqual(expected);
		44	});
		45	});
		46
11	const baseWslState: DesktopWslState = {	47	const baseWslState: DesktopWslState = {
12	enabled: false,	48	enabled: false,
13	distro: null,	49	distro: null,

apps/web/src/components/settings/ConnectionsSettings.logic.ts+31-1

...	@@ -1,4 +1,34 @@	...	@@ -1,4 +1,34 @@
1	import type { AdvertisedEndpoint, DesktopBridge, DesktopWslState } from "@t3tools/contracts";	1	import {
		2	type AdvertisedEndpoint,
		3	type AuthGrantScope,
		4	AuthTerminalOperateScope,
		5	AuthTerminalReadScope,
		6	type DesktopBridge,
		7	type DesktopWslState,
		8	} from "@t3tools/contracts";
		9
		10	/**
		11	* Operating terminals without being able to list them leaves a client
		12	* allocating a fresh shell for every script run it cannot see, so the pairing
		13	* form keeps `terminal:read` alongside `terminal:operate`.
		14	*/
		15	export function togglePairingScopeSelection(
		16	current: ReadonlyArray<AuthGrantScope>,
		17	scope: AuthGrantScope,
		18	checked: boolean,
		19	): ReadonlyArray<AuthGrantScope> {
		20	const without = (scopes: ReadonlyArray<AuthGrantScope>) =>
		21	scopes.filter((currentScope) => currentScope !== scope);
		22	if (!checked) {
		23	return scope === AuthTerminalReadScope
		24	? without(current).filter((currentScope) => currentScope !== AuthTerminalOperateScope)
		25	: without(current);
		26	}
		27	const next = [...without(current), scope];
		28	return scope === AuthTerminalOperateScope && !next.includes(AuthTerminalReadScope)
		29	? [...next, AuthTerminalReadScope]
		30	: next;
		31	}
2		32
3	/** A missing access list says nothing about whether other clients exist. */	33	/** A missing access list says nothing about whether other clients exist. */
4	export function canRevokeOtherClients(	34	export function canRevokeOtherClients(

apps/web/src/components/settings/ConnectionsSettings.tsx+9-3

...	@@ -37,6 +37,7 @@ import {	...	@@ -37,6 +37,7 @@ import {
37	AuthFilesystemWriteScope,	37	AuthFilesystemWriteScope,
38	AuthStandardClientScopes,	38	AuthStandardClientScopes,
39	AuthTerminalOperateScope,	39	AuthTerminalOperateScope,
		40	AuthTerminalReadScope,
40	type AuthClientSession,	41	type AuthClientSession,
41	type AuthEnvironmentScope,	42	type AuthEnvironmentScope,
42	type AuthGrantScope,	43	type AuthGrantScope,
...	@@ -75,6 +76,7 @@ import {	...	@@ -75,6 +76,7 @@ import {
75	isQrShareableEndpoint,	76	isQrShareableEndpoint,
76	isWslSettingsRowVisible,	77	isWslSettingsRowVisible,
77	selectQrEndpointOption,	78	selectQrEndpointOption,
		79	togglePairingScopeSelection,
78	} from "./ConnectionsSettings.logic";	80	} from "./ConnectionsSettings.logic";
79	import {	81	import {
80	SettingsPageContainer,	82	SettingsPageContainer,
...	@@ -269,6 +271,11 @@ const PAIRING_SCOPE_OPTIONS: ReadonlyArray<{	...	@@ -269,6 +271,11 @@ const PAIRING_SCOPE_OPTIONS: ReadonlyArray<{
269	title: "View diagnostics and usage",	271	title: "View diagnostics and usage",
270	description: "Read process diagnostics, resource history, and usage totals.",	272	description: "Read process diagnostics, resource history, and usage totals.",
271	},	273	},
		274	{
		275	scope: AuthTerminalReadScope,
		276	title: "View terminals",
		277	description: "Read existing terminal output and status.",
		278	},
272	{	279	{
273	scope: AuthTerminalOperateScope,	280	scope: AuthTerminalOperateScope,
274	title: "Use terminals",	281	title: "Use terminals",
...	@@ -1165,9 +1172,7 @@ const AuthorizedClientsHeaderAction = memo(function AuthorizedClientsHeaderActio	...	@@ -1165,9 +1172,7 @@ const AuthorizedClientsHeaderAction = memo(function AuthorizedClientsHeaderActio
1165	}, [delegatableScopes, onPairingLinkCreated, pairingLabel, primaryEnvironmentId, selectedScopes]);	1172	}, [delegatableScopes, onPairingLinkCreated, pairingLabel, primaryEnvironmentId, selectedScopes]);
1166		1173
1167	const togglePairingScope = useCallback((scope: AuthGrantScope, checked: boolean) => {	1174	const togglePairingScope = useCallback((scope: AuthGrantScope, checked: boolean) => {
1168	setPairingScopes((current) =>	1175	setPairingScopes((current) => togglePairingScopeSelection(current, scope, checked));
1169	checked ? [...current, scope] : current.filter((currentScope) => currentScope !== scope),
1170	);
1171	}, []);	1176	}, []);
1172		1177
1173	return (	1178	return (
...	@@ -1240,6 +1245,7 @@ const AuthorizedClientsHeaderAction = memo(function AuthorizedClientsHeaderActio	...	@@ -1240,6 +1245,7 @@ const AuthorizedClientsHeaderAction = memo(function AuthorizedClientsHeaderActio
1240	AuthOrchestrationReadScope,	1245	AuthOrchestrationReadScope,
1241	AuthFilesystemReadScope,	1246	AuthFilesystemReadScope,
1242	AuthDiagnosticsReadScope,	1247	AuthDiagnosticsReadScope,
		1248	AuthTerminalReadScope,
1243	].filter((scope) => delegatableScopes.includes(scope)),	1249	].filter((scope) => delegatableScopes.includes(scope)),
1244	)	1250	)
1245	}	1251	}

apps/web/src/state/terminalSessionAvailability.test.ts created+104

...	@@ -0,0 +1,104 @@
1	import { EnvironmentId, ThreadId, type TerminalSummary } from "@t3tools/contracts";
2	import { act, createElement, useEffect } from "react";
3	import { createRoot, type Root } from "react-dom/client";
4	import { afterEach, beforeEach, expect, it, vi } from "vite-plus/test";
5
6	import { useKnownTerminalSessions } from "./terminalSessions";
7
8	const state = vi.hoisted(() => ({
9	canRead: true,
10	data: null as ReadonlyArray<TerminalSummary> \| null,
11	error: null as string \| null,
12	}));
13
14	vi.mock("./session", () => ({ useEnvironmentScope: () => state.canRead }));
15	vi.mock("./terminal", () => ({ terminalEnvironment: { metadata: () => ({}) } }));
16	vi.mock("./query", () => ({
17	useEnvironmentQuery: (atom: unknown) =>
18	atom === null ? { data: null, error: null } : { data: state.data, error: state.error },
19	}));
20
21	let root: Root;
22	let current: ReturnType<typeof useKnownTerminalSessions>;
23	const target = {
24	environmentId: EnvironmentId.make("secondary"),
25	threadId: ThreadId.make("thread"),
26	};
27	const terminal: TerminalSummary = {
28	threadId: "thread",
29	terminalId: "term-1",
30	cwd: "/repo",
31	worktreePath: null,
32	status: "running",
33	pid: 123,
34	exitCode: null,
35	exitSignal: null,
36	hasRunningSubprocess: true,
37	label: "Busy process",
38	updatedAt: "2026-09-05T00:00:00.000Z",
39	};
40
41	function Probe() {
42	const sessions = useKnownTerminalSessions(target);
43	useEffect(() => {
44	current = sessions;
45	}, [sessions]);
46	return null;
47	}
48
49	function render() {
50	return act(() => root.render(createElement(Probe)));
51	}
52
53	beforeEach(() => {
54	state.canRead = true;
55	state.data = null;
56	state.error = null;
57	const document = { nodeType: 9, addEventListener() {}, removeEventListener() {} };
58	const container = {
59	nodeType: 1,
60	tagName: "DIV",
61	namespaceURI: "http://www.w3.org/1999/xhtml",
62	ownerDocument: document,
63	addEventListener() {},
64	removeEventListener() {},
65	};
66	vi.stubGlobal("document", document);
67	vi.stubGlobal("window", { document, HTMLIFrameElement: EventTarget });
68	vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
69	root = createRoot(container as unknown as HTMLElement);
70	});
71
72	afterEach(async () => {
73	await act(() => root.unmount());
74	vi.unstubAllGlobals();
75	});
76
77	it("distinguishes missing metadata from an authoritative empty list across scope changes", async () => {
78	await render();
79	expect(current).toBeNull();
80
81	state.data = [terminal];
82	await render();
83	expect(current?.[0]).toMatchObject({
84	target: { environmentId: "secondary", terminalId: "term-1" },
85	state: { hasRunningSubprocess: true },
86	});
87
88	state.canRead = false;
89	await render();
90	expect(current).toBeNull();
91
92	state.canRead = true;
93	state.data = [];
94	await render();
95	expect(current).toEqual([]);
96	});
97
98	it("does not reuse cached terminal metadata after a subscription failure", async () => {
99	state.data = [terminal];
100	await render();
101	state.error = "Access denied";
102	await render();
103	expect(current).toBeNull();
104	});

apps/web/src/state/terminalSessions.ts+26-10

 @@ -8,6 +8,8 @@ import {
 } from "@t3tools/client-runtime/state/terminal";
 import {
   ThreadId,
+  AuthTerminalReadScope,
+  AuthTerminalOperateScope,
   type EnvironmentId,
   type TerminalAttachInput,
   type TerminalSummary,
 @@ -16,6 +18,7 @@ import { useMemo } from "react";
 import { useEnvironmentQuery } from "./query";
 import { terminalEnvironment } from "./terminal";
+import { useEnvironmentScope } from "./session";
 const EMPTY_KNOWN_TERMINAL_SESSIONS = Object.freeze<ReadonlyArray<KnownTerminalSession>>([]);
 @@ -125,16 +128,25 @@ export function useAttachedTerminalSession(input: {
   readonly environmentId: EnvironmentId | null;
   readonly terminal: TerminalAttachInput | null;
 }): TerminalSessionState {
+  const canRead = useEnvironmentScope(input.environmentId, AuthTerminalReadScope);
+  const canOperate = useEnvironmentScope(input.environmentId, AuthTerminalOperateScope);
   const attach = useEnvironmentQuery(
     input.environmentId !== null && input.terminal !== null
-      ? terminalEnvironment.attach({
+      ? canOperate
-          environmentId: input.environmentId,
+        ? terminalEnvironment.attach({
-          input: input.terminal,
+            environmentId: input.environmentId,
-        })
+            input: input.terminal,
+          })
+        : canRead
+          ? terminalEnvironment.observe({
+              environmentId: input.environmentId,
+              input: { threadId: input.terminal.threadId, terminalId: input.terminal.terminalId },
+            })
+          : null
       : null,
   );
   const metadata = useEnvironmentQuery(
-    input.environmentId === null
+    input.environmentId === null || !canRead
       ? null
       : terminalEnvironment.metadata({
           environmentId: input.environmentId,
 @@ -160,9 +172,10 @@ export function useAttachedTerminalSession(input: {
 export function useKnownTerminalSessions(input: {
   readonly environmentId: EnvironmentId | null;
   readonly threadId: ThreadId | null;
-}): ReadonlyArray<KnownTerminalSession> {
+}): ReadonlyArray<KnownTerminalSession> | null {
+  const canRead = useEnvironmentScope(input.environmentId, AuthTerminalReadScope);
   const metadata = useEnvironmentQuery(
-    input.environmentId === null
+    input.environmentId === null || !canRead
       ? null
       : terminalEnvironment.metadata({
           environmentId: input.environmentId,
 @@ -170,8 +183,11 @@ export function useKnownTerminalSessions(input: {
         }),
   );
   return useMemo(
-    () => selectKnownTerminalSessions(metadata.data, input.environmentId, input.threadId),
+    () =>
-    [input.environmentId, input.threadId, metadata.data],
+      metadata.data === null || metadata.error !== null
+        ? null
+        : selectKnownTerminalSessions(metadata.data, input.environmentId, input.threadId),
+    [input.environmentId, input.threadId, metadata.data, metadata.error],
   );
 }
 @@ -180,5 +196,5 @@ export function useThreadRunningTerminalIds(input: {
   readonly threadId: ThreadId | null;
 }): ReadonlyArray<string> {
   const sessions = useKnownTerminalSessions(input);
-  return useMemo(() => selectRunningSubprocessTerminalIds(sessions), [sessions]);
+  return useMemo(() => selectRunningSubprocessTerminalIds(sessions ?? []), [sessions]);
 }

apps/web/src/terminal/ghostty/surface.test.ts+115-2

...	@@ -167,7 +167,13 @@ describe("GhosttyTerminalSurface visibility", () => {	...	@@ -167,7 +167,13 @@ describe("GhosttyTerminalSurface visibility", () => {
167	resize() {	167	resize() {
168	for (const callback of resizeCallbacks) callback();	168	for (const callback of resizeCallbacks) callback();
169	},	169	},
170	pointer(type: string, clientX: number, buttons: number, shiftKey = false, button = 0) {	170	pointer(
		171	type: string,
		172	clientX: number,
		173	buttons: number,
		174	modifiers: boolean \| Partial<Pick<MouseEvent, "ctrlKey" \| "metaKey" \| "shiftKey">> = {},
		175	button = 0,
		176	) {
171	canvas.dispatchEvent(	177	canvas.dispatchEvent(
172	Object.assign(new Event(type, { cancelable: true }), {	178	Object.assign(new Event(type, { cancelable: true }), {
173	clientX,	179	clientX,
...	@@ -175,7 +181,7 @@ describe("GhosttyTerminalSurface visibility", () => {	...	@@ -175,7 +181,7 @@ describe("GhosttyTerminalSurface visibility", () => {
175	pointerId: 1,	181	pointerId: 1,
176	button,	182	button,
177	buttons,	183	buttons,
178	shiftKey,	184	...(typeof modifiers === "boolean" ? { shiftKey: modifiers } : modifiers),
179	}),	185	}),
180	);	186	);
181	},	187	},
...	@@ -210,6 +216,113 @@ describe("GhosttyTerminalSurface visibility", () => {	...	@@ -210,6 +216,113 @@ describe("GhosttyTerminalSurface visibility", () => {
210	vi.restoreAllMocks();	216	vi.restoreAllMocks();
211	});	217	});
212		218
		219	it.each([
		220	{ platform: "Linux x86_64", modifiers: { ctrlKey: true, metaKey: false } },
		221	{ platform: "MacIntel", modifiers: { ctrlKey: false, metaKey: true } },
		222	])(
		223	"gates path links and preserves selection and URLs ($platform)",
		224	async ({ platform, modifiers }) => {
		225	vi.stubGlobal("navigator", { platform });
		226	const harness = createHarness();
		227	vi.spyOn(Event.prototype, "timeStamp", "get").mockImplementation(() => Date.now());
		228	let canOpenPaths = false;
		229	const openLink = vi.fn();
		230	const surface = await harness.create({
		231	canActivateLink: (text) => text.startsWith("https://") \|\| canOpenPaths,
		232	onLinkActivate: openLink,
		233	});
		234	surface.write("/repo/file.ts");
		235	harness.flushFrame();
		236	harness.pointer("pointermove", 5, 0, modifiers);
		237	expect(surface.canvas.style.cursor).toBe("");
		238	harness.pointer("pointerdown", 5, 1, modifiers);
		239	harness.pointer("pointerup", 5, 0, modifiers);
		240	expect(openLink).not.toHaveBeenCalled();
		241
		242	vi.advanceTimersByTime(501);
		243	harness.pointer("pointerdown", 5, 1);
		244	harness.pointer("pointermove", 37, 1);
		245	harness.pointer("pointerup", 37, 0);
		246	expect(surface.getSelection()).toBe("/repo");
		247
		248	vi.advanceTimersByTime(501);
		249	harness.pointer("pointermove", 5, 0, modifiers);
		250	canOpenPaths = true;
		251	surface.refreshLinkActivation();
		252	expect(surface.canvas.style.cursor).toBe("pointer");
		253	harness.pointer("pointerdown", 5, 1, modifiers);
		254	harness.pointer("pointerup", 5, 0, modifiers);
		255	expect(openLink).toHaveBeenCalledExactlyOnceWith("/repo/file.ts", expect.any(Event));
		256
		257	vi.advanceTimersByTime(501);
		258	harness.pointer("pointerdown", 5, 1, modifiers);
		259	canOpenPaths = false;
		260	surface.refreshLinkActivation();
		261	expect(surface.canvas.style.cursor).toBe("");
		262	harness.pointer("pointerup", 5, 0, modifiers);
		263	expect(openLink).toHaveBeenCalledOnce();
		264
		265	vi.advanceTimersByTime(501);
		266	surface.resetAndWrite("https://t3.codes");
		267	harness.flushFrame();
		268	harness.pointer("pointermove", 5, 0, modifiers);
		269	expect(surface.canvas.style.cursor).toBe("pointer");
		270	harness.pointer("pointerdown", 5, 1, modifiers);
		271	harness.pointer("pointerup", 5, 0, modifiers);
		272	expect(openLink).toHaveBeenLastCalledWith("https://t3.codes", expect.any(Event));
		273	},
		274	);
		275
		276	it("resends an unchanged grid when authorization and attachment become ready", async () => {
		277	const harness = createHarness();
		278	let canOperate = false;
		279	let attached = false;
		280	const resizePty = vi.fn<(cols: number, rows: number) => void>();
		281	const surface = await harness.create({
		282	onResize: (cols, rows) => {
		283	if (canOperate && attached) resizePty(cols, rows);
		284	},
		285	});
		286	vi.advanceTimersByTime(150);
		287	expect(resizePty).not.toHaveBeenCalled();
		288
		289	canOperate = true;
		290	surface.resendSize();
		291	vi.advanceTimersByTime(150);
		292	expect(resizePty).not.toHaveBeenCalled();
		293
		294	attached = true;
		295	surface.resendSize();
		296	vi.advanceTimersByTime(150);
		297	expect(resizePty).toHaveBeenCalledExactlyOnceWith(20, 6);
		298	surface.fit();
		299	vi.advanceTimersByTime(150);
		300	expect(resizePty).toHaveBeenCalledOnce();
		301
		302	canOperate = false;
		303	harness.mount.clientWidth = 248;
		304	surface.fit();
		305	vi.advanceTimersByTime(150);
		306	expect(resizePty).toHaveBeenCalledOnce();
		307	});
		308
		309	it("replays the current grid on reveal when a hidden host becomes ready", async () => {
		310	const harness = createHarness();
		311	const onResize = vi.fn<(cols: number, rows: number) => void>();
		312	const surface = await harness.create({ onResize });
		313	vi.advanceTimersByTime(150);
		314	onResize.mockClear();
		315
		316	surface.setVisible(false);
		317	surface.resendSize();
		318	vi.advanceTimersByTime(150);
		319	expect(onResize).not.toHaveBeenCalled();
		320
		321	surface.setVisible(true);
		322	vi.advanceTimersByTime(150);
		323	expect(onResize).toHaveBeenCalledExactlyOnceWith(20, 6);
		324	});
		325
213	it("stops hidden snapshots and paint while preserving live VT replies and the next cursor", async () => {	326	it("stops hidden snapshots and paint while preserving live VT replies and the next cursor", async () => {
214	const harness = createHarness();	327	const harness = createHarness();
215	const surface = await harness.create();	328	const surface = await harness.create();

apps/web/src/terminal/ghostty/surface.ts+18

 @@ -547,6 +547,7 @@ export interface GhosttyTerminalSurfaceOptions {
   readonly onSelectionChange: () => void;
   readonly beforeKey: (event: KeyboardEvent) => boolean;
   readonly onLinkActivate: (text: string, event: MouseEvent) => void;
+  readonly canActivateLink?: (text: string) => boolean;
   /**
    * A right-click the running application did not claim through mouse
    * reporting. The host owns the menu, so it also owns preventing the browser
 @@ -793,6 +794,12 @@ export class GhosttyTerminalSurface {
     this.requestRender();
   }
+  /** Re-evaluate link feedback after the host's available actions change. */
+  refreshLinkActivation(): void {
+    if (this.disposed) return;
+    this.refreshHoveredLink();
+  }
   async setFont(font: GhosttyTerminalFont): Promise<void> {
     if (this.disposed) return;
     const fontSize = terminalFontSize(font.size);
 @@ -855,6 +862,12 @@ export class GhosttyTerminalSurface {
     this.applyFontMetrics();
   };
+  /** Replay the measured grid after the host becomes ready to resize its PTY. */
+  resendSize(): void {
+    this.resizeNotified = false;
+    this.fit();
+  }
   fit(): boolean {
     if (this.disposed || !this.visible) return false;
     const width = this.mount.clientWidth;
 @@ -1926,6 +1939,11 @@ export class GhosttyTerminalSurface {
   }
   private linkAt(clientX: number, clientY: number): TerminalLinkWithRange | null {
+    const link = this.findLinkAt(clientX, clientY);
+    return link && this.options.canActivateLink?.(link.text) !== false ? link : null;
+  }
+  private findLinkAt(clientX: number, clientY: number): TerminalLinkWithRange | null {
     if (!this.snapshot) return null;
     const cell = terminalGridCellAt({
       bounds: this.canvas.getBoundingClientRect(),

packages/client-runtime/src/rpc/client.ts+2-1

...	@@ -66,7 +66,8 @@ export type EnvironmentSubscriptionRpcTag =	...	@@ -66,7 +66,8 @@ export type EnvironmentSubscriptionRpcTag =
66	\| typeof WS_METHODS.subscribeVcsStatus	66	\| typeof WS_METHODS.subscribeVcsStatus
67	\| typeof WS_METHODS.subscribeWorktreeSetup	67	\| typeof WS_METHODS.subscribeWorktreeSetup
68	\| typeof WS_METHODS.subscribeProjectClones	68	\| typeof WS_METHODS.subscribeProjectClones
69	\| typeof WS_METHODS.terminalAttach;	69	\| typeof WS_METHODS.terminalAttach
		70	\| typeof WS_METHODS.terminalObserve;
70		71
71	export type EnvironmentStreamCommandRpcTag =	72	export type EnvironmentStreamCommandRpcTag =
72	\| typeof WS_METHODS.chatGptHandoffSubscribe	73	\| typeof WS_METHODS.chatGptHandoffSubscribe

packages/client-runtime/src/state/terminal.ts+9

...	@@ -37,6 +37,15 @@ export function createTerminalEnvironmentAtoms<R, E>(	...	@@ -37,6 +37,15 @@ export function createTerminalEnvironmentAtoms<R, E>(
37	}) => JSON.stringify([environmentId, input.threadId, input.terminalId ?? null]);	37	}) => JSON.stringify([environmentId, input.threadId, input.terminalId ?? null]);
38	const lifecycleConcurrency = { mode: "serial" as const, key: terminalThreadKey };	38	const lifecycleConcurrency = { mode: "serial" as const, key: terminalThreadKey };
39	return {	39	return {
		40	observe: createEnvironmentSubscriptionAtomFamily(runtime, {
		41	label: "environment-data:terminal:observe",
		42	subscribe: (input: EnvironmentRpcInput<typeof WS_METHODS.terminalObserve>) =>
		43	Stream.suspend(() =>
		44	subscribe(WS_METHODS.terminalObserve, input).pipe(
		45	Stream.scan(nextTerminalAttachSeedState, applyTerminalAttachStreamEvent),
		46	),
		47	),
		48	}),
40	attach: createEnvironmentSubscriptionAtomFamily(runtime, {	49	attach: createEnvironmentSubscriptionAtomFamily(runtime, {
41	label: "environment-data:terminal:attach",	50	label: "environment-data:terminal:attach",
42	subscribe: (input: EnvironmentRpcInput<typeof WS_METHODS.terminalAttach>) =>	51	subscribe: (input: EnvironmentRpcInput<typeof WS_METHODS.terminalAttach>) =>

packages/contracts/src/auth.ts+3

...	@@ -85,6 +85,7 @@ export const AuthProvidersManageScope = "providers:manage" as const;	...	@@ -85,6 +85,7 @@ export const AuthProvidersManageScope = "providers:manage" as const;
85	export const AuthEnvironmentMaintainScope = "environment:maintain" as const;	85	export const AuthEnvironmentMaintainScope = "environment:maintain" as const;
86	export const AuthPreviewOperateScope = "preview:operate" as const;	86	export const AuthPreviewOperateScope = "preview:operate" as const;
87	export const AuthDiagnosticsReadScope = "diagnostics:read" as const;	87	export const AuthDiagnosticsReadScope = "diagnostics:read" as const;
		88	export const AuthTerminalReadScope = "terminal:read" as const;
88	export const AuthTerminalOperateScope = "terminal:operate" as const;	89	export const AuthTerminalOperateScope = "terminal:operate" as const;
89	export const AuthSourceControlWriteScope = "source-control:write" as const;	90	export const AuthSourceControlWriteScope = "source-control:write" as const;
90	export const AuthFilesystemReadScope = "filesystem:read" as const;	91	export const AuthFilesystemReadScope = "filesystem:read" as const;
...	@@ -103,6 +104,7 @@ export const AuthEnvironmentScope = Schema.Literals([	...	@@ -103,6 +104,7 @@ export const AuthEnvironmentScope = Schema.Literals([
103	AuthEnvironmentMaintainScope,	104	AuthEnvironmentMaintainScope,
104	AuthPreviewOperateScope,	105	AuthPreviewOperateScope,
105	AuthDiagnosticsReadScope,	106	AuthDiagnosticsReadScope,
		107	AuthTerminalReadScope,
106	AuthTerminalOperateScope,	108	AuthTerminalOperateScope,
107	AuthFilesystemReadScope,	109	AuthFilesystemReadScope,
108	AuthFilesystemWriteScope,	110	AuthFilesystemWriteScope,
...	@@ -132,6 +134,7 @@ export const AuthStandardClientScopes = [	...	@@ -132,6 +134,7 @@ export const AuthStandardClientScopes = [
132	AuthEnvironmentMaintainScope,	134	AuthEnvironmentMaintainScope,
133	AuthPreviewOperateScope,	135	AuthPreviewOperateScope,
134	AuthDiagnosticsReadScope,	136	AuthDiagnosticsReadScope,
		137	AuthTerminalReadScope,
135	AuthTerminalOperateScope,	138	AuthTerminalOperateScope,
136	AuthSourceControlWriteScope,	139	AuthSourceControlWriteScope,
137	AuthFilesystemReadScope,	140	AuthFilesystemReadScope,

packages/contracts/src/rpc.ts+10

...	@@ -218,6 +218,7 @@ import {	...	@@ -218,6 +218,7 @@ import {
218	} from "./project.ts";	218	} from "./project.ts";
219	import {	219	import {
220	TerminalAttachInput,	220	TerminalAttachInput,
		221	TerminalObserveInput,
221	TerminalAttachStreamEvent,	222	TerminalAttachStreamEvent,
222	TerminalClearInput,	223	TerminalClearInput,
223	TerminalCloseInput,	224	TerminalCloseInput,
...	@@ -406,6 +407,7 @@ export const WS_METHODS = {	...	@@ -406,6 +407,7 @@ export const WS_METHODS = {
406	// Terminal methods	407	// Terminal methods
407	terminalOpen: "terminal.open",	408	terminalOpen: "terminal.open",
408	terminalAttach: "terminal.attach",	409	terminalAttach: "terminal.attach",
		410	terminalObserve: "terminal.observe",
409	terminalWrite: "terminal.write",	411	terminalWrite: "terminal.write",
410	terminalResize: "terminal.resize",	412	terminalResize: "terminal.resize",
411	terminalClear: "terminal.clear",	413	terminalClear: "terminal.clear",
...	@@ -1351,6 +1353,13 @@ const WsTerminalAttachRpc = Rpc.make(WS_METHODS.terminalAttach, {	...	@@ -1351,6 +1353,13 @@ const WsTerminalAttachRpc = Rpc.make(WS_METHODS.terminalAttach, {
1351	stream: true,	1353	stream: true,
1352	});	1354	});
1353		1355
		1356	const WsTerminalObserveRpc = Rpc.make(WS_METHODS.terminalObserve, {
		1357	payload: TerminalObserveInput,
		1358	success: TerminalAttachStreamEvent,
		1359	error: Schema.Union([TerminalError, EnvironmentAuthorizationError]),
		1360	stream: true,
		1361	});
		1362
1354	const WsTerminalWriteRpc = Rpc.make(WS_METHODS.terminalWrite, {	1363	const WsTerminalWriteRpc = Rpc.make(WS_METHODS.terminalWrite, {
1355	payload: TerminalWriteInput,	1364	payload: TerminalWriteInput,
1356	error: Schema.Union([TerminalError, EnvironmentAuthorizationError]),	1365	error: Schema.Union([TerminalError, EnvironmentAuthorizationError]),
...	@@ -1866,6 +1875,7 @@ export const WsRpcGroup = RpcGroup.make(	...	@@ -1866,6 +1875,7 @@ export const WsRpcGroup = RpcGroup.make(
1866	WsReviewGetDiffFileContentsRpc,	1875	WsReviewGetDiffFileContentsRpc,
1867	WsTerminalOpenRpc,	1876	WsTerminalOpenRpc,
1868	WsTerminalAttachRpc,	1877	WsTerminalAttachRpc,
		1878	WsTerminalObserveRpc,
1869	WsTerminalWriteRpc,	1879	WsTerminalWriteRpc,
1870	WsTerminalResizeRpc,	1880	WsTerminalResizeRpc,
1871	WsTerminalClearRpc,	1881	WsTerminalClearRpc,

packages/contracts/src/terminal.ts+3

 @@ -60,6 +60,9 @@ export const TerminalAttachInput = Schema.Struct({
 });
 export type TerminalAttachInput = typeof TerminalAttachInput.Type;
+export const TerminalObserveInput = TerminalSessionInput;
+export type TerminalObserveInput = Schema.Codec.Encoded<typeof TerminalObserveInput>;
 export const TerminalWriteInput = Schema.Struct({
   ...TerminalSessionInput.fields,
   data: Schema.String.check(Schema.isNonEmpty()).check(Schema.isMaxLength(65_536)),

packages/shared/src/terminalLabels.test.ts+24-1

...	@@ -1,10 +1,13 @@	...	@@ -1,10 +1,13 @@
1	import { describe, expect, it } from "vite-plus/test";	1	import { describe, expect, it } from "vite-plus/test";
2		2
3	import type { TerminalSummary } from "@t3tools/contracts";	3	import type { TerminalSummary } from "@t3tools/contracts";
4	import { DEFAULT_TERMINAL_ID } from "@t3tools/contracts";	4	import { DEFAULT_TERMINAL_ID, TerminalOpenInput } from "@t3tools/contracts";
		5	import * as Schema from "effect/Schema";
5		6
6	import { getTerminalLabel, nextTerminalId, resolveTerminalSessionLabel } from "./terminalLabels.ts";	7	import { getTerminalLabel, nextTerminalId, resolveTerminalSessionLabel } from "./terminalLabels.ts";
7		8
		9	const decodeTerminalOpen = Schema.decodeUnknownSync(TerminalOpenInput);
		10
8	describe("getTerminalLabel", () => {	11	describe("getTerminalLabel", () => {
9	it("uses the numeric suffix for term-* ids", () => {	12	it("uses the numeric suffix for term-* ids", () => {
10	expect(getTerminalLabel(DEFAULT_TERMINAL_ID)).toBe("Terminal 1");	13	expect(getTerminalLabel(DEFAULT_TERMINAL_ID)).toBe("Terminal 1");
...	@@ -16,6 +19,10 @@ describe("getTerminalLabel", () => {	...	@@ -16,6 +19,10 @@ describe("getTerminalLabel", () => {
16	it("falls back to the raw id for unknown shapes", () => {	19	it("falls back to the raw id for unknown shapes", () => {
17	expect(getTerminalLabel("custom-session")).toBe("custom-session");	20	expect(getTerminalLabel("custom-session")).toBe("custom-session");
18	});	21	});
		22
		23	it("keeps a numbered label for terminals allocated without host metadata", () => {
		24	expect(getTerminalLabel("term-2-783c91cc-a413-47c7-8312-c2a5a1f05e40")).toBe("Terminal 2");
		25	});
19	});	26	});
20		27
21	describe("resolveTerminalSessionLabel", () => {	28	describe("resolveTerminalSessionLabel", () => {
...	@@ -50,4 +57,20 @@ describe("nextTerminalId", () => {	...	@@ -50,4 +57,20 @@ describe("nextTerminalId", () => {
50	expect(nextTerminalId(["", " ", DEFAULT_TERMINAL_ID])).toBe("term-2");	57	expect(nextTerminalId(["", " ", DEFAULT_TERMINAL_ID])).toBe("term-2");
51	expect(nextTerminalId(["", " "])).toBe("term-1");	58	expect(nextTerminalId(["", " "])).toBe("term-1");
52	});	59	});
		60
		61	it("avoids unseen sessions when metadata is unavailable and resumes normal numbering", () => {
		62	const first = nextTerminalId([], "783c91cc-a413-47c7-8312-c2a5a1f05e40");
		63	const second = nextTerminalId([first], "102315fc-ceef-45c4-b978-c4d4947d3c26");
		64	expect(first).not.toBe(DEFAULT_TERMINAL_ID);
		65	expect(second).not.toBe(first);
		66	expect(getTerminalLabel(second)).toBe("Terminal 2");
		67	expect(nextTerminalId([first, second])).toBe("term-3");
		68	expect(
		69	decodeTerminalOpen({
		70	threadId: "thread",
		71	terminalId: second,
		72	cwd: "/workspace",
		73	}),
		74	).toMatchObject({ terminalId: second });
		75	});
53	});	76	});

packages/shared/src/terminalLabels.ts+16-7

 @@ -1,8 +1,14 @@
 import type { TerminalSummary } from "@t3tools/contracts";
+function terminalNumber(terminalId: string): string | undefined {
+  return /^term(?:inal)?-(\d+)(?:-[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12})?$/i.exec(
+    terminalId,
+  )?.[1];
+}
 /** Human-readable label for a terminal tab; matches mobile and web sidebars. */
 export function getTerminalLabel(terminalId: string): string {
-  const numericSuffix = /^term(?:inal)?-(\d+)$/i.exec(terminalId)?.[1];
+  const numericSuffix = terminalNumber(terminalId);
   if (numericSuffix) {
     return `Terminal ${numericSuffix}`;
   }
 @@ -26,15 +32,18 @@ export function resolveTerminalSessionLabel(
  * Client-side terminal id allocator. Ids are ALWAYS chosen by the client and sent explicitly
  * on every `terminal.open` / `terminal.attach` call — the server never allocates.
  *
- * Returns the lowest unused `term-N` id (starting at `term-1`), skipping any ids already in
+ * Returns the lowest unused `term-N` number. When metadata is unavailable,
- * `existingTerminalIds`.
+ * callers append a UUID so an unseen host session cannot be reused accidentally.
  */
-export function nextTerminalId(existingTerminalIds: ReadonlyArray<string>): string {
+export function nextTerminalId(
-  const usedIds = new Set(existingTerminalIds.filter((id) => id.trim().length > 0));
+  existingTerminalIds: ReadonlyArray<string>,
+  uniqueSuffix?: string,
+): string {
+  const usedNumbers = new Set(existingTerminalIds.map(terminalNumber));
   let nextIndex = 1;
-  while (usedIds.has(`term-${nextIndex}`)) {
+  while (usedNumbers.has(String(nextIndex))) {
     nextIndex += 1;
   }
-  return `term-${nextIndex}`;
+  return `term-${nextIndex}${uniqueSuffix === undefined ? "" : `-${uniqueSuffix}`}`;
 }

author	Julius Marminge <julius0216@outlook.com> 2026-10-06 20:30:13-07:00
committer	GitHub <noreply@github.com> 2026-10-06 20:30:13-07:00
log	cc41482df0232454af0cc5ac2f1afd984e342134
tree	e074e63429b4a58ae42e3fa83a794a054a7b43ec
parent	57b2418d4fbab56290ff4cb861dcd0a7d0f5ef63
signature	Signed by PGP key B5690EEEBB952194

feat(auth): allow passive terminal observation (#9791)