feat(web,mobile): take over a device another thread still holds

apps/mobile/src/features/devices/DevicePreviewRouteScreen.tsx

@@ -1,13 +1,22 @@
 import { SheetCloseButton } from "../../components/ui/SheetHeader";
 import { Button } from "../../components/ui/Button";
 import * as Dialog from "../../components/ui/Dialog";
+import { scopeThreadRef } from "@t3tools/client-runtime/environment";
 import {
   deviceToolVersionLabels,
   deviceToolUpdateOwnership,
   deviceToolUpdatePolicy,
+  otherThreadDeviceSessions,
 } from "@t3tools/client-runtime/state/device";
-import { useIsFocused, useNavigation, type StaticScreenProps } from "@react-navigation/native";
-import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { threadRuntimeIsActive } from "@t3tools/client-runtime/state/shell";
+import { backgroundWorkHoldsCompletion } from "@t3tools/shared/orchestrationV2PendingBackgroundWork";
+import {
+  StackActions,
+  useIsFocused,
+  useNavigation,
+  type StaticScreenProps,
+} from "@react-navigation/native";
+import { EnvironmentId, ThreadId, type DeviceSession } from "@t3tools/contracts";
 import * as Cause from "effect/Cause";
 import { useEffect, useRef, useState, type RefObject } from "react";
 import * as Haptics from "expo-haptics";
@@ -34,6 +43,7 @@ import { deriveBottomControlInsets } from "../../lib/reserved-regions";
 import { useNativeColumnLayoutMetrics } from "../../native/native-layout-metrics";
 import { uuidv4 } from "../../lib/uuid";
 import { deviceEnvironment, useDeviceHubAccess } from "../../state/device";
+import { useThreadShell } from "../../state/entities";
 import { useEnvironmentQuery } from "../../state/query";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { useAppearancePreferences } from "../settings/appearance/AppearancePreferencesProvider";
@@ -88,6 +98,7 @@ export function DevicePreviewScreen({
   readonly initialDeviceKey?: string;
 }) {
   const embedded = onMaximize !== undefined;
+  const navigation = useNavigation();
   const insets = useSafeAreaInsets();
   // In a pane the stream sits below the pane's bar, which content otherwise slides under.
   const barOverlap = useBarOverlap();
@@ -103,10 +114,14 @@ export function DevicePreviewScreen({
   const [controlsVisible, setControlsVisible] = useState(true);
   const retryHost = useAtomCommand(deviceEnvironment.list);
   const shutdown = useAtomCommand(deviceEnvironment.shutdown, { reportFailure: false });
+  const close = useAtomCommand(deviceEnvironment.close, { reportFailure: false });
   const streamRef = useRef<DeviceStreamRef>(null);
   const state = useEnvironmentQuery(deviceEnvironment.state({ environmentId, input: {} }));
   const previews = threadDevicePreviews(state.data, threadId);
   const preview = selectedThreadDevicePreview(previews, selectedKey);
+  const holders = preview
+    ? otherThreadDeviceSessions(state.data?.sessions ?? [], preview.session)
+    : [];
   const onInputConnected = async (connected: boolean) => {
     setInputConnected(connected);
     if (!connected) setControlsVisible(true);
@@ -148,6 +163,29 @@ export function DevicePreviewScreen({
     }
   };
 
+  const takeOver = async (holder: DeviceSession) => {
+    const result = await close({
+      environmentId,
+      input: { threadId: holder.threadId, hostId: holder.hostId, deviceId: holder.deviceId },
+    });
+    if (result._tag === "Failure") {
+      Dialog.alert("Could not take over device", String(Cause.squash(result.cause)));
+    }
+  };
+  const holderBanners = holders.map((holder) => (
+    <DeviceHolderBanner
+      key={holder.threadId}
+      environmentId={environmentId}
+      holder={holder}
+      onOpenThread={() =>
+        navigation.dispatch(
+          StackActions.replace("Thread", { environmentId, threadId: holder.threadId }),
+        )
+      }
+      onTakeOver={() => takeOver(holder)}
+    />
+  ));
+
   const controls: AppBarMenuItem[] = [
     ...(state.data?.hosts
       .filter(
@@ -280,6 +318,9 @@ export function DevicePreviewScreen({
             ]}
           />
           <View style={{ height: barOverlap }} />
+          {holderBanners.length > 0 ? (
+            <View className="gap-2 px-3 pb-2">{holderBanners}</View>
+          ) : null}
         </>
       ) : null}
       {preview && focused && foreground ? (
@@ -347,6 +388,7 @@ export function DevicePreviewScreen({
               />
               <DeviceOptionsMenu items={menuItems} />
             </GlassSurface>
+            {holderBanners.length > 0 ? <View className="mt-2 gap-2">{holderBanners}</View> : null}
           </View>
         </Animated.View>
       ) : (
@@ -372,6 +414,46 @@ export function DevicePreviewScreen({
   );
 }
 
+function DeviceHolderBanner(props: {
+  readonly environmentId: EnvironmentId;
+  readonly holder: DeviceSession;
+  readonly onOpenThread: () => void;
+  readonly onTakeOver: () => Promise<void>;
+}) {
+  const shell = useThreadShell(scopeThreadRef(props.environmentId, props.holder.threadId));
+  const running =
+    threadRuntimeIsActive(shell?.runtime) ||
+    backgroundWorkHoldsCompletion(shell?.pendingBackgroundTasks ?? []);
+  const [takingOver, setTakingOver] = useState(false);
+  const title = shell?.title.trim() || "another thread";
+  return (
+    <GlassSurface className="flex-row items-center gap-3 px-3 py-2">
+      <Pressable
+        accessibilityRole="link"
+        accessibilityLabel={`Open thread ${title}`}
+        className="min-w-0 flex-1"
+        onPress={props.onOpenThread}
+      >
+        <AppText numberOfLines={2} className="text-sm text-foreground-muted">
+          Busy in <AppText className="font-t3-medium text-sm text-foreground">{title}</AppText>
+          {running ? ", which is running." : shell ? ", which isn't running." : "."}
+        </AppText>
+      </Pressable>
+      <Button
+        label="Take over"
+        accessibilityLabel={`Take over from ${title}`}
+        tone="primary"
+        size="compact"
+        loading={takingOver}
+        onPress={() => {
+          setTakingOver(true);
+          void props.onTakeOver().finally(() => setTakingOver(false));
+        }}
+      />
+    </GlassSurface>
+  );
+}
+
 function DeviceOptionsMenu({ items }: { readonly items: ReadonlyArray<AppBarMenuItem> }) {
   return (
     <Menu

apps/web/src/components/device/DevicePanel.browser.test.tsx

@@ -96,6 +96,14 @@ vi.mock("~/rightPanelStore", () => ({
   },
   selectThreadRightPanelState: () => ({ isOpen: false, activeSurfaceId: null, surfaces: [] }),
 }));
+vi.mock("~/state/entities", () => ({
+  useThreadShell: () => ({ title: "Holder", runtime: { status: "running" } }),
+}));
+vi.mock("~/components/ThreadContextChip", () => ({
+  ThreadContextChip: ({ record }: { record: { threadId: string } }) => (
+    <a href={`/${record.threadId}`}>{record.threadId}</a>
+  ),
+}));
 vi.mock("~/components/device/DeviceHostUpdates", () => ({ DeviceHostUpdates: () => null }));
 vi.mock("~/components/device/DeviceWorkspace", () => ({
   DeviceWorkspace: ({ onPowerOff }: { onPowerOff: () => void }) => (
@@ -199,6 +207,48 @@ describe("DevicePanel thread switches", () => {
   });
 });
 
+describe("DevicePanel takeover", () => {
+  const holder = ThreadId.make("thread-holder");
+  const session = {
+    hostId: "local",
+    deviceId: "phone",
+    platform: "ios",
+    openedAt: "2026-01-01T00:00:00.000Z",
+  } as const;
+  const shared: DeviceServiceState = {
+    ...deviceState,
+    sessions: [
+      ...deviceState.sessions,
+      { ...session, threadId: holder },
+      // The same serial on another host is a different device.
+      { ...session, threadId: ThreadId.make("thread-elsewhere"), hostId: "ssh" },
+    ],
+  };
+  const openPhone: Extract<RightPanelSurface, { kind: "device" }> = {
+    ...picker,
+    target: { ...phoneTarget, platform: "ios" },
+  };
+
+  it("closes the holder's session, even mid-run, so this thread's agent can claim the device", async () => {
+    setup();
+    currentState = shared;
+    mocks.close.mockResolvedValue(opened);
+    await using screen = await render(devicePanel(threadA, openPhone), { container });
+
+    await expect.element(screen.getByText("thread-elsewhere")).not.toBeInTheDocument();
+    await screen.getByRole("button", { name: "Take over from Holder" }).click();
+
+    expect(mocks.close.mock.calls).toEqual([
+      [
+        {
+          environmentId: threadA.environmentId,
+          input: { threadId: holder, hostId: "local", deviceId: "phone" },
+        },
+      ],
+    ]);
+  });
+});
+
 describe("DevicePanel host probe", () => {
   it("probes the hosts once while setup shows inside the panel", async () => {
     setup();

apps/web/src/components/device/DevicePanel.tsx

@@ -1,8 +1,14 @@
 import { DeviceHostUpdates } from "./DeviceHostUpdates";
+import { scopeThreadRef } from "@t3tools/client-runtime/environment";
+import { otherThreadDeviceSessions } from "@t3tools/client-runtime/state/device";
+import { threadRuntimeIsActive } from "@t3tools/client-runtime/state/shell";
+import { backgroundWorkHoldsCompletion } from "@t3tools/shared/orchestrationV2PendingBackgroundWork";
 import type {
   DevicePlatform,
   DeviceServiceState,
+  DeviceSession,
   DeviceSummary,
+  EnvironmentId,
   ScopedThreadRef,
 } from "@t3tools/contracts";
 import { ArrowUpRight, CircleAlert, Play, Smartphone, X } from "lucide-react";
@@ -29,8 +35,10 @@ import {
   NO_DEVICE_PROBE_ATOM,
   useDeviceState,
 } from "~/state/device";
+import { useThreadShell } from "~/state/entities";
 import { formatEnvironmentQueryError } from "~/state/query";
 import { useAtomCommand } from "~/state/use-atom-command";
+import { ThreadContextChip } from "../ThreadContextChip";
 import { DeviceLoadingView } from "./DeviceLoadingView";
 import {
   DeviceSetup,
@@ -95,6 +103,7 @@ export function DevicePanel(props: {
   const activeHost = activeDevice
     ? state.hosts.find((host) => host.id === activeDevice.hostId)
     : undefined;
+  const holders = activeSession ? otherThreadDeviceSessions(state.sessions, activeSession) : [];
 
   const grouped = groupDevices(state);
 
@@ -174,6 +183,16 @@ export function DevicePanel(props: {
     });
   };
 
+  const takeOver = (holder: DeviceSession) => {
+    const settleOperation = startOperation(null);
+    return close({
+      environmentId,
+      input: { threadId: holder.threadId, hostId: holder.hostId, deviceId: holder.deviceId },
+    }).then((result) =>
+      settleOperation(result._tag === "Failure" ? formatEnvironmentQueryError(result.cause) : null),
+    );
+  };
+
   const bootingDevices =
     state.bootingDevices?.filter((device) => device.threadId === threadId) ?? [];
   const { ready: hostReady, busy: hostBusy } = deviceHubReadiness(state);
@@ -242,6 +261,14 @@ export function DevicePanel(props: {
               minute.
             </div>
           ) : null}
+          {holders.map((holder) => (
+            <DeviceHolderNotice
+              key={holder.threadId}
+              environmentId={environmentId}
+              holder={holder}
+              onTakeOver={() => takeOver(holder)}
+            />
+          ))}
           {operationError ? (
             <DeviceNotice onDismiss={() => setOperation(null)}>{operationError}</DeviceNotice>
           ) : null}
@@ -386,6 +413,47 @@ export function DevicePanel(props: {
   );
 }
 
+function DeviceHolderNotice(props: {
+  readonly environmentId: EnvironmentId;
+  readonly holder: DeviceSession;
+  readonly onTakeOver: () => Promise<unknown>;
+}) {
+  const shell = useThreadShell(scopeThreadRef(props.environmentId, props.holder.threadId));
+  const running =
+    threadRuntimeIsActive(shell?.runtime) ||
+    backgroundWorkHoldsCompletion(shell?.pendingBackgroundTasks ?? []);
+  const [takingOver, setTakingOver] = useState(false);
+  return (
+    <div
+      role="status"
+      className="flex flex-wrap items-center gap-x-2 gap-y-1 border-b px-3 py-2 text-xs text-muted-foreground"
+    >
+      <span className="min-w-0 flex-1 basis-56">
+        Busy in{" "}
+        <ThreadContextChip
+          record={{
+            environmentId: props.environmentId,
+            threadId: props.holder.threadId,
+            title: "another thread",
+          }}
+        />
+        {running ? ", which is running." : shell ? ", which isn't running." : "."}
+      </span>
+      <Button
+        size="xs"
+        aria-label={`Take over from ${shell?.title.trim() || "another thread"}`}
+        disabled={takingOver}
+        onClick={() => {
+          setTakingOver(true);
+          void props.onTakeOver().finally(() => setTakingOver(false));
+        }}
+      >
+        {takingOver ? "Taking over…" : "Take over"}
+      </Button>
+    </div>
+  );
+}
+
 function DeviceNotice(props: { readonly onDismiss: () => void; readonly children: ReactNode }) {
   return (
     <div

docs/user/devices.md

@@ -79,6 +79,12 @@ If the thread has several devices open, choose one in the viewer. Closing the
 viewer stops streaming and leaves the device available to the agent. Device
 activity also appears in the thread timeline.
 
+Only one thread's agent can drive a device at a time. When another thread also
+has the device open, the Device panel and the mobile viewer name that thread
+and say whether it is still running; select the name to go there. Choose
+**Take over** to close the device there so this thread's agent can use it. An
+agent still working in that thread loses the device.
+
 Agents drive the device through the `agent-device` command line. T3
 Code installs and starts it only after **Agents can use devices** is on. iOS
 taps build a small test runner on first use, which takes a couple of minutes

packages/client-runtime/src/state/device.ts

@@ -1,4 +1,4 @@
-import { type DeviceToolVersions, WS_METHODS } from "@t3tools/contracts";
+import { type DeviceSession, type DeviceToolVersions, WS_METHODS } from "@t3tools/contracts";
 import { Atom } from "effect/reactivity";
 
 import type { EnvironmentRegistry } from "../connection/registry.ts";
@@ -116,5 +116,23 @@ export function deviceToolUpdatePolicy(tools: DeviceToolVersions | undefined) {
     ? "Update pending. Required tools will install automatically when next used. The host needs network access; an older install is not used as a fallback."
     : "Required tools are installed automatically when needed. Checking versions does not install or start anything.";
 }
+
+/**
+ * Other threads with the same device open. Any of them may hold the agent-device
+ * claim that refuses this thread's agent with DEVICE_IN_USE; closing their session
+ * releases it. Android serials repeat across hosts, so the host is part of the match.
+ */
+export function otherThreadDeviceSessions(
+  sessions: ReadonlyArray<DeviceSession>,
+  session: Pick<DeviceSession, "threadId" | "hostId" | "deviceId">,
+) {
+  return sessions.filter(
+    (other) =>
+      other.threadId !== session.threadId &&
+      other.hostId === session.hostId &&
+      other.deviceId === session.deviceId,
+  );
+}
+
 export const deviceToolUpdateOwnership =
   "This environment's T3 server chooses device tool versions for itself and its SSH hosts. Update that server to receive newer tool versions; updating only your browser or mobile app does not update a remote server.";