@@ -41,6 +41,12 @@ names). The device id may be omitted when exactly one device is booted. It
 prints one JSON line; on failure it names the next command. Authorized mobile
 verification includes that step unless the user prohibits it.
 
+For a device you opened in an agent-device session elsewhere (a device pool,
+cloud, or remote host), run `vp run mobile:install <ios|android> --session <s>`
+from the directory you opened the session in. It installs the cached build into
+that session (`--abi arm64-v8a` for an ARM Android device; `--metro <url>` also
+opens it against Metro) and never builds.
+
 Start `vp run dev:client` from `apps/mobile`, or reuse a healthy Metro belonging
 to this checkout. Open its printed development-client URL with AgentDevice
 `open com.t3tools.t3code.dev <url>` and all returned target arguments.
 
@@ -32,6 +32,8 @@ const RUST = /^native\/(resource-monitor|kde-snap-shot|hyprland-snap-shot)\//;
 
 // These tests read other packages without declaring dependencies.
 const TEST_ONLY_DEPS = {
+  // Evals import the server's source to test its real model-facing text.
+  "@t3tools/evals": ["t3"],
   "@t3tools/provider-pi": ["@t3tools/client-runtime"],
   "@t3tools/scripts": [
     "@t3tools/desktop",
 
@@ -90,7 +90,7 @@ The most common defect in this repo is a change that works on the path you teste
 
 An empty database is a bad test. Seed your worktree's `.t3` with a copy of real data instead of pointing at live state:
 
-- The first `vp run dev` in a worktree does this for you when its database is missing. `--no-seed` or `T3CODE_DEV_SEED=0` skips it.
+- The first `vp run dev` in a worktree does this for you when its database is missing and the source is at most 500 MiB. Larger sources warn and dev starts with an empty database. `--no-seed` or `T3CODE_DEV_SEED=0` skips seeding. Manual migration still accepts larger sources and may use substantial disk space before pruning.
 - Run `vp run migrate-dev-db` with your dev server stopped to refresh. It rebuilds `<worktree>/.t3/userdata/statev2.sqlite` from a read-only snapshot of `~/.t3/userdata/statev2.sqlite`, the developer's real data. It keeps recent projects and their stopped threads, and drops scheduled tasks, pending work, and auth sessions, so your dev server never runs the developer's agents. Raise `--projects` and `--threads-per-project` for more data.
 - Refresh `statev2.sqlite`, not `state.sqlite`. The server copies the V1 `state.sqlite` only when `statev2.sqlite` is missing.
 - Bring `secrets` and `settings.json` only if the flow under test needs them.
@@ -136,10 +136,14 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
 
 For authorized mobile verification, a missing or outdated native client is an install step, not a blocker. Run `vp run mobile:install <ios|android> [device-id]` on the device host before starting Metro; it targets the only booted simulator or connected Android device when the id is omitted. It installs the dev client for this checkout's native fingerprint from the shared cache in seconds and builds only when no machine has built it yet, so prefer it over `expo run:*`, `xcodebuild`, or `gradlew`, which rebuild from scratch. Its stdout is one JSON line; build output goes to the log it names. See `test-t3-mobile` for the full workflow.
 
+## Evals
+
+`evals/` checks how real models behave with T3 Code's model-facing text: agent instructions, MCP tool descriptions and schemas, and generated titles. Before you change that text, read [evals/README.md](evals/README.md) and run the evals it names. When you fix a model behavior bug, add a case that fails before the fix.
+
 ## Pull requests
 
 - Never make a PR unless the developer explicitly asks you to do so.
-- If `origin` is git.cafe, follow [GitCafe mirror](docs/operations/development.md#gitcafe-mirror-optional): push to `origin`, open and track PRs with `cafe` and their git.cafe URLs, and keep `gh` for CI logs and merging.
+- If `origin` is git.cafe, follow [GitCafe mirror](docs/operations/development.md#gitcafe-mirror-optional): push to `origin`, open and track PRs with `cafe` and their git.cafe URLs, and keep `gh` for merging.
 - Conventional commit titles, plain language: `fix(web): new threads no longer spike CPU`.
 - Body: the problem in a sentence or two, then how you fixed it. End with the model and harness that did the work.
 - UI changes need before/after images. Motion or timing needs a short video.
@@ -194,7 +198,7 @@ Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/
   options, and pass combinators as additional function-builder arguments.
 - Inferred types over annotations. `any` is the enemy.
 - Default to no comment. Write one only for a constraint, an external quirk, or an invariant the code can't show, in one line where you can and four at most. Don't restate names or signatures, narrate steps, record history, or explain the fix you just made; the PR carries that. `t3code/no-low-value-comments` enforces the length cap and the mechanical cases.
-- React effects are a last resort: derive in render, act in handlers, reset with `key`, or use a ref callback or store. The `t3code/react-effect-budget` lint rule holds each file to its entry in `scripts/effect-budget.json`; raise an entry only in the PR that needs the effect, and lower it when you remove one.
+- React effects are for synchronizing with something outside React. Derive in render and act in handlers instead of syncing state, but don't hide real lifecycle work in refs or stores to dodge one. The `t3code/react-effect-budget` lint rule holds each file to its count in `scripts/effect-budget.json`; a new effect states its reason with `// oxlint-disable-next-line t3code/react-effect-budget -- <why>`.
 - Our users drive agents all day and notice a dropped frame, a lying spinner, and a stale label. No continuously repainting animations; they peg the GPU on high-refresh displays.
 - If a rule here fights the task in front of you, say so loudly and get a human sign-off before breaking it.
 
 
@@ -94,6 +94,7 @@ We are (mostly) not accepting contributions yet. Small fixes may be considered.
 
 Full docs live in [docs/](./docs). There's no docs site yet.
 
+- [FAQ](./docs/user/faq.md)
 - [Install and first run](./docs/user/install.md)
 - [Permission modes](./docs/user/permission-modes.md)
 - [Keyboard shortcuts](./docs/user/keybindings.md)
 
@@ -382,7 +382,10 @@ export const make = Effect.gen(function* () {
         webContents.send(DESKTOP_APP_ACTIVATION_REQUEST_CHANNEL, request);
       });
     }),
-    complete: (response) => Effect.sync(() => broker.complete(response)),
+    // The IPC handler owns the activation-completion span.
+    complete: Effect.fnUntraced(function* (response) {
+      return yield* Effect.sync(() => broker.complete(response));
+    }),
   });
 });
 
 
@@ -28,8 +28,6 @@ vi.mock("@clerk/electron", () => ({
 vi.mock("@clerk/electron/storage", () => ({
   storage: storageMock,
 }));
-
-import * as Option from "effect/Option";
 import * as Exit from "effect/Exit";
 import * as FileSystem from "effect/FileSystem";
 import * as ElectronApp from "../electron/ElectronApp.ts";
@@ -297,7 +295,7 @@ it.effect(
         }),
     } as unknown as ElectronApp.ElectronApp["Service"];
     const electronWindow = {
-      currentMainOrFirst: Effect.succeed(Option.some(window)),
+      currentMainOrFirst: Effect.succeedSome(window),
       reveal: () => Effect.sync(() => revealed.resolve()),
     } as unknown as ElectronWindow.ElectronWindow["Service"];
     return Effect.gen(function* () {
 
@@ -100,9 +100,15 @@ it.layer(NodeServices.layer)("DesktopCliCommand", (it) => {
       const command = yield* commandIn({ home });
       const link = path.join(home, ".local", "bin", "t3");
 
-      expect(yield* command.state).toEqual({ supported: true, installedPath: null, onPath: false });
+      expect(yield* command.state).toEqual({
+        supported: true,
+        installedPath: null,
+        onPath: false,
+        launcherPath: null,
+      });
       const installed = yield* command.install;
       expect(installed.installedPath).toBe(link);
+      expect(installed.launcherPath).toBe(path.join(home, ".t3", "bin", "t3"));
       expect(yield* fs.readLink(link)).toBe(path.join(home, ".t3", "bin", "t3"));
       expect((yield* command.install).installedPath).toBe(link);
 
 
@@ -150,18 +150,26 @@ export const make = Effect.gen(function* () {
 
   const state: DesktopCliCommand["Service"]["state"] = Effect.gen(function* () {
     if (!environment.isPackaged) {
-      return { supported: false, installedPath: null, onPath: false } as const;
+      return { supported: false, installedPath: null, onPath: false, launcherPath: null } as const;
     }
+    const launcherPath = (yield* exists(launcher)) ? launcher : null;
     const installed = yield* installedAt;
     const shadowedBy = yield* foreignFirstOnPath;
     const shadow = Option.isSome(shadowedBy) ? { shadowedBy: shadowedBy.value } : {};
     if (Option.isNone(installed)) {
-      return { supported: true, installedPath: null, onPath: false, ...shadow };
+      return { supported: true, installedPath: null, onPath: false, launcherPath, ...shadow };
     }
     const first = yield* firstOnPath;
     const onPath = windows || (Option.isSome(first) && (yield* isOurLink(first.value)));
-    return { supported: true, installedPath: installed.value, onPath, ...shadow };
-  }).pipe(Effect.orElseSucceed(() => ({ supported: false, installedPath: null, onPath: false })));
+    return { supported: true, installedPath: installed.value, onPath, launcherPath, ...shadow };
+  }).pipe(
+    Effect.orElseSucceed(() => ({
+      supported: false,
+      installedPath: null,
+      onPath: false,
+      launcherPath: null,
+    })),
+  );
 
   const ensureLauncher = DesktopCliShim.install.pipe(
     Effect.provideService(DesktopEnvironment.DesktopEnvironment, environment),
 
@@ -459,90 +459,91 @@ const makeBackendOutputLogShape = (
 ): Effect.Effect<DesktopBackendOutputLogShape> =>
   Option.match(sink, {
     onNone: () => Effect.succeed(DesktopBackendOutputLogNoop),
-    onSome: (logFile) =>
-      Effect.gen(function* () {
-        const sessionRef = yield* Ref.make(Option.none<BackendOutputSession>());
-        const writeFailure = Effect.fn("desktop.observability.backendOutput.writeFailure")(
-          function* (session: BackendOutputSession, details: string) {
-            yield* writeBackendChildLogRecord(logFile, {
-              message: "backend child process failure output start",
-              level: "ERROR",
-              annotations: {
-                component: "desktop-backend-child",
-                runId: session.runId,
-                instanceId: id,
-                phase: "START",
-                details: session.startDetails,
-              },
-            });
-            for (const output of session.chunks) {
-              yield* writeBackendChildLogRecord(logFile, {
-                message: "backend child process output",
-                level: output.streamName === "stderr" ? "ERROR" : "INFO",
-                annotations: {
-                  component: "desktop-backend-child",
-                  runId: session.runId,
-                  instanceId: id,
-                  stream: output.streamName,
-                  text: textDecoder.decode(output.chunk.subarray(output.offset)),
-                },
-              });
-            }
-            yield* writeBackendChildLogRecord(logFile, {
-              message: "backend child process failure output end",
-              level: "ERROR",
-              annotations: {
-                component: "desktop-backend-child",
-                runId: session.runId,
-                instanceId: id,
-                phase: "END",
-                details: sanitizeLogValue(details),
-              },
-            });
+    // The enclosing operation owns the span for this inline handler.
+    onSome: Effect.fnUntraced(function* (logFile) {
+      const sessionRef = yield* Ref.make(Option.none<BackendOutputSession>());
+      const writeFailure = Effect.fn("desktop.observability.backendOutput.writeFailure")(function* (
+        session: BackendOutputSession,
+        details: string,
+      ) {
+        yield* writeBackendChildLogRecord(logFile, {
+          message: "backend child process failure output start",
+          level: "ERROR",
+          annotations: {
+            component: "desktop-backend-child",
+            runId: session.runId,
+            instanceId: id,
+            phase: "START",
+            details: session.startDetails,
           },
-        );
-        return {
-          beginSession: Effect.fn("desktop.observability.backendOutput.beginSession")(function* ({
-            details,
-          }) {
-            const runId = yield* currentDesktopRunId;
-            yield* Ref.set(
-              sessionRef,
-              Option.some({
-                runId,
-                startDetails: sanitizeLogValue(details),
-                chunks: [],
-                byteLength: 0,
-              }),
-            );
-          }),
-          writeOutputChunk: Effect.fnUntraced(function* (streamName, chunk) {
-            if (environment.isDevelopment) {
-              yield* writeDevelopmentConsoleOutput(streamName, chunk);
-            }
-            yield* Ref.update(
-              sessionRef,
-              Option.map((session) => appendBoundedOutputChunk(session, streamName, chunk)),
-            );
-          }),
-          persistFailureSnapshot: Effect.fn(
-            "desktop.observability.backendOutput.persistFailureSnapshot",
-          )(function* ({ details }) {
-            const session = yield* Ref.get(sessionRef);
-            if (Option.isSome(session)) {
-              yield* writeFailure(session.value, details);
-            }
-          }),
-          persistFailure: Effect.fn("desktop.observability.backendOutput.persistFailure")(
-            function* ({ details }) {
-              const session = yield* Ref.modify(sessionRef, (current) => [current, Option.none()]);
-              if (Option.isNone(session)) return;
-              yield* writeFailure(session.value, details);
+        });
+        for (const output of session.chunks) {
+          yield* writeBackendChildLogRecord(logFile, {
+            message: "backend child process output",
+            level: output.streamName === "stderr" ? "ERROR" : "INFO",
+            annotations: {
+              component: "desktop-backend-child",
+              runId: session.runId,
+              instanceId: id,
+              stream: output.streamName,
+              text: textDecoder.decode(output.chunk.subarray(output.offset)),
             },
-          ),
-          discardSession: Ref.set(sessionRef, Option.none()),
-        } satisfies DesktopBackendOutputLogShape;
-      }),
+          });
+        }
+        yield* writeBackendChildLogRecord(logFile, {
+          message: "backend child process failure output end",
+          level: "ERROR",
+          annotations: {
+            component: "desktop-backend-child",
+            runId: session.runId,
+            instanceId: id,
+            phase: "END",
+            details: sanitizeLogValue(details),
+          },
+        });
+      });
+      return {
+        beginSession: Effect.fn("desktop.observability.backendOutput.beginSession")(function* ({
+          details,
+        }) {
+          const runId = yield* currentDesktopRunId;
+          yield* Ref.set(
+            sessionRef,
+            Option.some({
+              runId,
+              startDetails: sanitizeLogValue(details),
+              chunks: [],
+              byteLength: 0,
+            }),
+          );
+        }),
+        writeOutputChunk: Effect.fnUntraced(function* (streamName, chunk) {
+          if (environment.isDevelopment) {
+            yield* writeDevelopmentConsoleOutput(streamName, chunk);
+          }
+          yield* Ref.update(
+            sessionRef,
+            Option.map((session) => appendBoundedOutputChunk(session, streamName, chunk)),
+          );
+        }),
+        persistFailureSnapshot: Effect.fn(
+          "desktop.observability.backendOutput.persistFailureSnapshot",
+        )(function* ({ details }) {
+          const session = yield* Ref.get(sessionRef);
+          if (Option.isSome(session)) {
+            yield* writeFailure(session.value, details);
+          }
+        }),
+        persistFailure: Effect.fn("desktop.observability.backendOutput.persistFailure")(function* ({
+          details,
+        }) {
+          const session = yield* Ref.modify(sessionRef, (current) => [current, Option.none()]);
+          if (Option.isNone(session)) return;
+          yield* writeFailure(session.value, details);
+        }),
+        discardSession: Ref.set(sessionRef, Option.none()),
+      } satisfies DesktopBackendOutputLogShape;
+    }),
   });
 
 const layerBackendOutputLogFactory = Layer.effect(
@@ -589,7 +590,9 @@ const layerBackendOutputLogFactory = Layer.effect(
       });
 
     return DesktopBackendOutputLogFactory.of({
-      forInstance: (id) => makeForId(id),
+      forInstance: Effect.fn("DesktopBackendOutputLogFactory.forInstance")(function (id) {
+        return makeForId(id);
+      }),
     });
   }),
 );
 
@@ -3,7 +3,6 @@ import { assert, describe, it } from "@effect/vitest";
 import * as NodeEvents from "node:events";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as Option from "effect/Option";
 
 import * as ElectronWindow from "../electron/ElectronWindow.ts";
 import { WEB_LINK_OPEN_CHANNEL } from "../ipc/channels.ts";
@@ -26,7 +25,7 @@ const makeWindow = () => {
       Layer.succeed(
         ElectronWindow.ElectronWindow,
         ElectronWindow.ElectronWindow.of({
-          currentMainOrFirst: Effect.succeed(Option.some(window)),
+          currentMainOrFirst: Effect.succeedSome(window),
           reveal: (target: Electron.BrowserWindow) => Effect.sync(() => void revealed.push(target)),
         } as unknown as ElectronWindow.ElectronWindow["Service"]),
       ),