feat(server): Agent Relay provider — attach, workspace discovery, spawn, and external-session visibility

.gitignore

@@ -38,3 +38,4 @@ node_modules/
 *.log
 .env*
 !.env.example
+.claude/worktrees/

apps/mobile/src/components/ProviderIcon.tsx

@@ -1,5 +1,5 @@
 import { Image } from "expo-image";
-import { Path, Svg } from "react-native-svg";
+import { Circle, Path, Svg } from "react-native-svg";
 import { useAppearancePreferences } from "../features/settings/appearance/AppearancePreferencesProvider";
 
 type ProviderIconProps = {
@@ -61,6 +61,22 @@ export function ProviderIcon(props: ProviderIconProps) {
     );
   }
 
+  if (props.provider === "agentrelay") {
+    return (
+      <Svg width={size} height={size} viewBox="0 0 24 24" fill="none">
+        <Circle cx="5" cy="12" r="2.5" stroke={mono} strokeWidth="1.5" />
+        <Circle cx="19" cy="5" r="2.5" stroke={mono} strokeWidth="1.5" />
+        <Circle cx="19" cy="19" r="2.5" stroke={mono} strokeWidth="1.5" />
+        <Path
+          d="M7.3 10.8 16.7 6.2M7.3 13.2l9.4 4.6"
+          stroke={mono}
+          strokeWidth="1.5"
+          strokeLinecap="round"
+        />
+      </Svg>
+    );
+  }
+
   if (props.provider === "opencode") {
     return (
       <Svg width={size} height={size} viewBox="0 0 32 40" fill="none">

apps/server/integration/orphanedProviderSessionStartup.integration.test.ts

@@ -38,6 +38,7 @@ import { ProviderSessionDirectoryLive } from "../src/provider/Layers/ProviderSes
 import * as ProviderService from "../src/provider/Services/ProviderService.ts";
 import * as ProviderSessionDirectory from "../src/provider/Services/ProviderSessionDirectory.ts";
 import * as ProviderSessionReaper from "../src/provider/Services/ProviderSessionReaper.ts";
+import * as AgentRelayThreadDiscoveryReactor from "../src/provider/Services/AgentRelayThreadDiscoveryReactor.ts";
 import * as RepositoryIdentityResolver from "../src/project/RepositoryIdentityResolver.ts";
 import * as ServerLifecycleEvents from "../src/serverLifecycleEvents.ts";
 import * as ServerRuntimeStartup from "../src/serverRuntimeStartup.ts";
@@ -79,6 +80,9 @@ const startupDependencies = Layer.mergeAll(
   Layer.succeed(ProviderSessionReaper.ProviderSessionReaper, {
     start: () => Effect.void,
   }),
+  Layer.succeed(AgentRelayThreadDiscoveryReactor.AgentRelayThreadDiscoveryReactor, {
+    start: () => Effect.void,
+  }),
   ServerLifecycleEvents.layer,
   Layer.succeed(ServerEnvironment.ServerEnvironment, {
     getEnvironmentId: Effect.succeed(EnvironmentId.make("environment-startup-orphan")),

apps/server/package.json

@@ -22,6 +22,7 @@
     "test": "vp test run"
   },
   "dependencies": {
+    "@agent-relay/sdk": "^11.10.3",
     "@anthropic-ai/claude-agent-sdk": "^0.3.260",
     "@effect/platform-bun": "catalog:",
     "@effect/platform-node": "catalog:",
@@ -33,6 +34,7 @@
     "node-pty": "^1.1.0",
     "stream-chain": "^4.2.5",
     "stream-json": "3.6.0",
+    "ws": "^8.18.0",
     "yaml": "catalog:",
     "yauzl": "^3.4.0"
   },
@@ -44,6 +46,7 @@
     "@t3tools/web": "workspace:*",
     "@types/bun": "1.3.14",
     "@types/node": "catalog:",
+    "@types/ws": "^8.5.13",
     "@types/yauzl": "^3.4.0",
     "effect-acp": "workspace:*",
     "effect-codex-app-server": "workspace:*",

apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts

@@ -1258,6 +1258,76 @@ describe("ProviderCommandReactor", () => {
     }),
   );
 
+  effectIt.effect("refuses to start a provider session on an external-session marker thread", () =>
+    Effect.gen(function* () {
+      const harness = yield* Effect.promise(() => createHarness());
+      const now = "2026-01-01T00:00:00.000Z";
+      // Same id shape ExternalSessionHooks.ts mints for a Claude Code /
+      // Codex session started outside T3 Code (see
+      // `externalSessionThreadId`/`isExternalSessionMarkerThreadId`).
+      const markerThreadId = ThreadId.make("external:claude:session-outside-t3");
+
+      yield* harness.engine.dispatch({
+        type: "thread.create",
+        commandId: CommandId.make("cmd-marker-thread-create"),
+        threadId: markerThreadId,
+        projectId: asProjectId("project-1"),
+        title: "External Claude Code session",
+        modelSelection: {
+          instanceId: ProviderInstanceId.make("codex"),
+          model: "gpt-5-codex",
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        branch: null,
+        worktreePath: null,
+        createdAt: now,
+        historyImport: true,
+      });
+
+      yield* harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-on-marker-thread"),
+        threadId: markerThreadId,
+        message: {
+          messageId: asMessageId("user-message-on-marker-thread"),
+          role: "user",
+          text: "hello",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      });
+
+      yield* Effect.promise(() =>
+        waitFor(async () => {
+          const thread = (await harness.readModel()).threads.find(
+            (entry) => entry.id === markerThreadId,
+          );
+          return (
+            thread?.activities.some(
+              (activity) => activity.kind === "provider.turn.start.failed",
+            ) === true
+          );
+        }),
+      );
+
+      const thread = (yield* Effect.promise(() => harness.readModel())).threads.find(
+        (entry) => entry.id === markerThreadId,
+      );
+      expect(
+        thread?.activities.find((activity) => activity.kind === "provider.turn.start.failed"),
+      ).toMatchObject({
+        summary: "Provider turn start failed",
+        payload: { detail: expect.stringContaining("read-only marker") },
+      });
+      expect(thread?.session).toBeNull();
+      expect(harness.startSession).not.toHaveBeenCalled();
+      expect(harness.sendTurn).not.toHaveBeenCalled();
+    }),
+  );
+
   effectIt.effect("shows the missing workspace message without a provider stack trace", () =>
     Effect.gen(function* () {
       const attempted = yield* Deferred.make<void>();

apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

@@ -31,6 +31,7 @@ import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker";
 
 import { resolveThreadWorkspaceCwd } from "../../checkpointing/Utils.ts";
 import { increment, orchestrationEventsProcessedTotal } from "../../observability/Metrics.ts";
+import { isExternalSessionMarkerThreadId } from "../../project/ExternalSessionHooks.ts";
 import {
   ProviderAdapterRequestError,
   ProviderAdapterValidationError,
@@ -1192,6 +1193,26 @@ const make = Effect.gen(function* () {
     if (!thread) {
       return;
     }
+    // A thread minted by the external-session lifecycle hooks is a read-only
+    // historical marker for a session T3 Code never ran — there is no PTY or
+    // provider session to attach to. Nothing server-side stops a client from
+    // sending it a message (see ExternalSessionHooks.ts), so refuse to start
+    // a real provider session here instead of silently spawning one inside
+    // what the user sees as a read-only marker thread.
+    if (isExternalSessionMarkerThreadId(event.payload.threadId)) {
+      yield* appendProviderFailureActivity({
+        threadId: event.payload.threadId,
+        kind: "provider.turn.start.failed",
+        summary: "Provider turn start failed",
+        detail:
+          "This thread is a read-only marker for a session started outside T3 Code. It has no " +
+          "live provider session to attach to and cannot start a new one.",
+        turnId: null,
+        createdAt: event.payload.createdAt,
+        requestId: event.payload.messageId,
+      });
+      return;
+    }
     const turnStart = yield* projectionSnapshotQuery.getTurnStartMessage({
       threadId: thread.id,
       messageId: event.payload.messageId,