Huge Cleanup

.gitignore

@@ -23,6 +23,7 @@ __pycache__/
 
 # Build outputs
 /apps/ade-cli/dist/
+/apps/ade-cli/dist-static/
 /apps/ade-code/dist/
 /apps/desktop/release/
 /apps/desktop/dist/

AGENTS.md

@@ -23,15 +23,15 @@
 
 - Desktop checks:
   - `npm --prefix apps/desktop run typecheck`
-  - `npm --prefix apps/desktop run test`
+  - `npm run test:desktop:sharded`
   - `npm --prefix apps/desktop run build`
   - `npm --prefix apps/desktop run lint`
 - ADE CLI checks:
   - `npm --prefix apps/ade-cli run typecheck`
   - `npm --prefix apps/ade-cli run test`
   - `npm --prefix apps/ade-cli run build`
 - Run the smallest relevant subset first when iterating, then finish with the broader checks that cover the touched surfaces.
-- If even running the full desktop test suit, u ahve to shard like ci
+- Run full desktop tests with the root `npm run test:desktop:sharded` command; use single-file or single-shard Vitest commands for iteration.
 
 ## Terminology
 
@@ -81,7 +81,7 @@ Desktop release:
 - **Node.js 22.x** is required (`node:sqlite` is used as the primary database engine).
 - Each app under `apps/` has its own independent `node_modules` and `package-lock.json` (no npm workspaces).
 - Validation commands are documented in the "Validation" section above.
-- The desktop test suite (265 test files) is large; CI shards it. For local iteration, run targeted tests (e.g. `npm --prefix apps/desktop run test:unit`) or a single file rather than the full suite.
+- The desktop test suite is large; CI shards it. For local iteration, run a single file or one CI-style shard rather than the full suite.
 
 ### Inspecting the local Electron desktop app with Codex Computer Use on macOS
 
@@ -111,7 +111,7 @@ Desktop release:
 - The `ADE_PROJECT_ROOT=/workspace` env var tells the main process to auto-open a project at startup. However, there is a timing race: the renderer's initial `getProject()` call may return null before the async project switch completes, causing the welcome screen to appear even though the backend loaded the project. A workaround is to open the project manually via the "Open a project" button in the top bar.
 - Computer-use features (screenshot, video capture, GUI automation) are macOS-only (`screencapture`, `osascript`). On Linux these gracefully degrade — the app returns `blocked_by_capability`.
 - `electron-builder` config only defines a `mac` target. Distributable Linux builds (deb/AppImage) are not configured, but dev mode works fine.
-- The `test:unit` script (`npm --prefix apps/desktop run test:unit`) uses `--project unit` which the pinned vitest 0.34.6 doesn't support. Use `npx vitest run <specific-test-file>` in `apps/desktop` for targeted tests, or `npm --prefix apps/desktop run test` for the full suite.
+- The pinned Vitest 0.34.6 does not support `--project`. Use `npx vitest run <specific-test-file>` in `apps/desktop` for targeted tests, `npx vitest run --shard=<n>/8` for a CI-style shard, or `npm run test:desktop:sharded` from the repo root for the full desktop unit workspace.
 - In the Cursor Cloud VM the active X display is `:1`, not `:99`. When launching Electron set `DISPLAY=:1`.
 - To launch the desktop dev app quickly when the CLI is already built: `npm run dev:desktop -- --skip-runtime-build`.
 - To launch the TUI against an already-running dev runtime: `npm run dev:code -- --skip-runtime-build --attach --project-root <path> --workspace-root <path>`.

README.md

@@ -154,7 +154,7 @@ Daily desktop dev:
 npm run dev
 ```
 
-That aliases to `npm run dev:desktop`: it rebuilds `apps/ade-cli`, launches the Electron desktop app, and points it at the dev runtime socket `/tmp/ade-runtime-dev.sock`. If no dev runtime is listening, desktop is allowed to create it. This is the normal desktop-dev flow.
+That aliases to `npm run dev:desktop`: it rebuilds `apps/ade-cli`, refreshes the shared dev runtime at `/tmp/ade-runtime-dev.sock` when needed, launches the Electron desktop app, and points desktop at that runtime. This is the normal desktop-dev flow.
 
 When these commands are run from an ADE lane worktree under `.ade/worktrees/`,
 they still run code from that lane checkout, but they open the primary checkout's
@@ -165,7 +165,7 @@ and uses the lane path as the workspace root for `dev:code`.
 Dev command matrix:
 
 ```bash
-npm run dev:desktop          # desktop only; dev socket; desktop may auto-create runtime
+npm run dev:desktop          # refresh shared dev runtime, then launch desktop
 npm run dev:desktop:attach   # desktop only; fail if dev runtime is not already running
 npm run dev:desktop:clean    # desktop only; clear Vite cache before launch
 npm run dev:code:web          # `ade code` in the browser (PTY + inspector WebSocket)
@@ -192,11 +192,11 @@ ADE_DEV_RUNTIME_SOCKET_PATH=/tmp/my-ade-dev.sock npm run dev:runtime
 ADE_DESKTOP_BRIDGE_SOCKET_PATH=/tmp/my-bridge.sock npm run dev:desktop
 ```
 
-To test auto-runtime creation, use the `:auto`/default commands after stopping the dev runtime:
+To test auto-runtime creation, use the default dev commands after stopping the dev runtime:
 
 ```bash
 npm run dev:stop
-npm run dev:desktop          # tests desktop creating the dev runtime
+npm run dev:desktop          # tests the desktop wrapper creating the dev runtime
 npm run dev:stop
 npm run dev:code             # tests TUI wrapper creating the dev runtime
 ```
@@ -211,7 +211,7 @@ npm run package:beta         # origin/main -> ADE Beta.app, ade-beta, ~/.ade-bet
 These are unsigned local macOS app builds under `apps/desktop/release-alpha` and `apps/desktop/release-beta`. Beta fetches `origin/main`, fast-forwards the local `main` checkout when possible, and builds that checkout as `ADE Beta`. It does not create a packaging worktree. These builds do not replace the production `ADE.app`, production `ade`, or `~/.ade` runtime/state. Alpha and Beta also use separate Electron profile directories (`ade-desktop-alpha` / `ade-desktop-beta`) so their browser storage and window state do not collide with dev or stable.
 Local channel packages include the host runtime binary for this Mac. Release builds still require the full cross-platform runtime artifact set used by remote runtime bootstrap.
 
-Validate with `npm --prefix apps/desktop run typecheck` and `run test`. The desktop test suite is large — run the smallest relevant subset first.
+Validate with `npm --prefix apps/desktop run typecheck` and `npm run test:desktop:sharded` for the full desktop suite. The desktop test suite is large, so run the smallest relevant subset first.
 
 ## Links
 

apps/ade-cli/src/adeRpcServer.test.ts

@@ -1608,7 +1608,7 @@ describe("adeRpcServer", () => {
     });
     expect(fixture.runtime.computerUseArtifactBrokerService.ingest).toHaveBeenCalledWith(
       expect.objectContaining({
-        backend: { name: "macos-vm", toolName: "macos_vm_screenshot" },
+        backend: { name: "macos-vm", style: "local_fallback", toolName: "macos_vm_screenshot" },
         owners: expect.arrayContaining([
           expect.objectContaining({ kind: "lane", id: "lane-1" }),
           expect.objectContaining({ kind: "chat_session", id: "chat-session-1" }),
@@ -1631,7 +1631,7 @@ describe("adeRpcServer", () => {
     });
     expect(fixture.runtime.computerUseArtifactBrokerService.ingest).toHaveBeenCalledWith(
       expect.objectContaining({
-        backend: { name: "macos-vm", toolName: "macos_vm_select" },
+        backend: { name: "macos-vm", style: "local_fallback", toolName: "macos_vm_select" },
       }),
     );
 
@@ -1671,7 +1671,7 @@ describe("adeRpcServer", () => {
     });
     expect(fixture.runtime.computerUseArtifactBrokerService.ingest).toHaveBeenCalledWith(
       expect.objectContaining({
-        backend: { name: "macos-vm", toolName: "screenshot_environment" },
+        backend: { name: "macos-vm", style: "local_fallback", toolName: "screenshot_environment" },
       }),
     );
 
@@ -1967,6 +1967,10 @@ describe("adeRpcServer", () => {
 
     expect(runtime.computerUseArtifactBrokerService.ingest).toHaveBeenCalledWith(
       expect.objectContaining({
+        backend: expect.objectContaining({
+          name: "agent-browser",
+          style: "external_cli",
+        }),
         owners: expect.arrayContaining([
           expect.objectContaining({
             kind: "chat_session",

apps/ade-cli/src/adeRpcServer.ts

@@ -15,7 +15,6 @@ import {
 } from "../../desktop/src/main/services/computerUse/localComputerUse";
 import { loadAgentBrowserArtifactPayloadFromFile, parseAgentBrowserArtifactPayload } from "../../desktop/src/main/services/proof/agentBrowserArtifactAdapter";
 import {
-  ADE_ACTION_ALLOWLIST,
   ADE_ACTION_DOMAIN_NAMES,
   type AdeActionDomain,
   callerHasRoleAtLeast,
@@ -43,9 +42,8 @@ import {
 } from "../../desktop/src/shared/prIssueResolution";
 import {
   type LinearWorkflowConfig,
+  type ComputerUseBackendStyle,
   type ComputerUseArtifactOwner,
-  type DockLayout,
-  type GraphPersistedState,
   type LaneLinearIssue,
   type MergeMethod,
   type AppNavigationRequest,
@@ -69,6 +67,7 @@ import {
 import type { AgentChatPermissionMode, TerminalSessionSummary } from "../../desktop/src/shared/types";
 import type { AdeRuntime } from "./bootstrap";
 import { JsonRpcError, JsonRpcErrorCode, type JsonRpcHandler, type JsonRpcRequest } from "./jsonrpc";
+import { normalizeAdeRuntimeRole } from "./runtimeRoles";
 import { getSharedModelPickerStore } from "./services/modelPickerStore";
 
 // Cross-surface (desktop + TUI + iOS) model picker favorites & recents.
@@ -2101,12 +2100,6 @@ const MACOS_VM_TOOL_NAMES = new Set([
   "macos_vm_type",
 ]);
 
-const ALL_TOOL_SPECS: ToolSpec[] = [
-  ...TOOL_SPECS,
-  ...CTO_OPERATOR_TOOL_SPECS,
-  ...CTO_LINEAR_SYNC_TOOL_SPECS,
-  ...COORDINATOR_TOOL_SPECS,
-];
 const COORDINATOR_TOOL_NAMES = new Set(COORDINATOR_TOOL_SPECS.map((tool) => tool.name));
 const READ_ONLY_TOOLS = new Set([
   "check_conflicts",
@@ -2323,13 +2316,6 @@ function asOptionalTrimmedString(value: unknown): string | null {
   return text.length ? text : null;
 }
 
-function parseEnvBoolean(value: string | undefined): boolean | null {
-  const normalized = value?.trim().toLowerCase() ?? "";
-  if (normalized === "1" || normalized === "true" || normalized === "yes") return true;
-  if (normalized === "0" || normalized === "false" || normalized === "no") return false;
-  return null;
-}
-
 function asBoolean(value: unknown, fallback = false): boolean {
   return typeof value === "boolean" ? value : fallback;
 }
@@ -2455,6 +2441,14 @@ function assertNonEmptyString(value: unknown, field: string): string {
   return text;
 }
 
+function assertComputerUseBackendStyle(value: unknown, field: string): ComputerUseBackendStyle {
+  const style = assertNonEmptyString(value, field);
+  if (style === "external_cli" || style === "manual" || style === "local_fallback") {
+    return style;
+  }
+  throw new JsonRpcError(JsonRpcErrorCode.invalidParams, `${field} must be one of: external_cli, manual, local_fallback`);
+}
+
 function parseCliSessionProvider(value: unknown): LaunchProfile {
   const provider = asTrimmedString(value).toLowerCase();
   if (!isLaunchProfile(provider)) {
@@ -2924,52 +2918,6 @@ function resolveRunContextLaneId(runtime: AdeRuntime, callerCtx: CallerContext):
   return asOptionalTrimmedString(mission?.laneId) ?? asOptionalTrimmedString(mission?.lane_id);
 }
 
-function resolveAuthorizedWorkspaceRoot(
-  runtime: AdeRuntime,
-  session: SessionState,
-  toolArgs?: Record<string, unknown>,
-): string {
-  const requestedLaneId = toolArgs ? extractLaneId(toolArgs) : null;
-  if (requestedLaneId) {
-    const laneWorktreePath = resolveLaneWorktreePath(runtime, requestedLaneId);
-    if (!laneWorktreePath) {
-      throw new JsonRpcError(
-        JsonRpcErrorCode.invalidParams,
-        `Requested lane '${requestedLaneId}' does not have an available worktree.`,
-      );
-    }
-    return laneWorktreePath;
-  }
-
-  const sessionLaneId = resolveChatSessionLaneId(runtime, session);
-  if (sessionLaneId) {
-    const laneWorktreePath = resolveLaneWorktreePath(runtime, sessionLaneId);
-    if (!laneWorktreePath) {
-      throw new JsonRpcError(
-        JsonRpcErrorCode.invalidParams,
-        `Chat session lane '${sessionLaneId}' does not have an available worktree.`,
-      );
-    }
-    return laneWorktreePath;
-  }
-
-  const runContextLaneId = resolveRunContextLaneId(runtime, resolveCallerContext(session));
-  if (runContextLaneId) {
-    const laneWorktreePath = resolveLaneWorktreePath(runtime, runContextLaneId);
-    if (!laneWorktreePath) {
-      throw new JsonRpcError(
-        JsonRpcErrorCode.invalidParams,
-        `Run context lane '${runContextLaneId}' does not have an available worktree.`,
-      );
-    }
-    return laneWorktreePath;
-  }
-
-  const fallbackWorkspaceRoot = typeof runtime.workspaceRoot === "string" ? runtime.workspaceRoot.trim() : "";
-  if (fallbackWorkspaceRoot.length > 0) return fallbackWorkspaceRoot;
-  return runtime.projectRoot;
-}
-
 function resolveRequestedOrSessionLaneId(
   runtime: AdeRuntime,
   session: SessionState,
@@ -3364,15 +3312,7 @@ type CallerContext = {
 };
 
 function resolveEnvCallerContext(): CallerContext {
-  const envRoleRaw = process.env.ADE_DEFAULT_ROLE?.trim() ?? "";
-  const envRole: SessionIdentity["role"] | null =
-    envRoleRaw === "cto"
-    || envRoleRaw === "orchestrator"
-    || envRoleRaw === "agent"
-    || envRoleRaw === "external"
-    || envRoleRaw === "evaluator"
-      ? envRoleRaw
-      : null;
+  const envRole = normalizeAdeRuntimeRole(process.env.ADE_DEFAULT_ROLE);
   const envChatSessionId = process.env.ADE_CHAT_SESSION_ID?.trim() || null;
   const envMissionId = process.env.ADE_MISSION_ID?.trim() || null;
   const envRunId = process.env.ADE_RUN_ID?.trim() || null;
@@ -3498,11 +3438,6 @@ function parseInitializeIdentity(runtime: AdeRuntime, params: unknown): SessionI
   const data = safeObject(params);
   const identity = safeObject(data.identity);
   const envContext = resolveEnvCallerContext();
-  const identityRole = asOptionalTrimmedString(identity.role);
-  const parsedIdentityRole: SessionIdentity["role"] | null =
-    identityRole === "cto" || identityRole === "orchestrator" || identityRole === "agent" || identityRole === "external" || identityRole === "evaluator"
-      ? identityRole
-      : null;
   const validRole: SessionIdentity["role"] = envContext.role ?? "external";
   const requestedChatSessionId = asOptionalTrimmedString(identity.chatSessionId);
   const resolvedChatSessionId = envContext.chatSessionId ?? requestedChatSessionId;
@@ -4740,6 +4675,7 @@ async function runTool(args: {
     const result = runtime.computerUseArtifactBrokerService.ingest({
       backend: {
         name: "screencapture",
+        style: "local_fallback",
         toolName: args.toolName,
       },
       inputs: [
@@ -4809,6 +4745,7 @@ async function runTool(args: {
     const result = runtime.computerUseArtifactBrokerService.ingest({
       backend: {
         name: "macos-vm",
+        style: "local_fallback",
         toolName: args.toolName,
       },
       inputs: [
@@ -5968,7 +5905,7 @@ async function runTool(args: {
   }
 
   if (name === "ingest_computer_use_artifacts") {
-    const backendStyle = assertNonEmptyString(toolArgs.backendStyle, "backendStyle") as "external_cli" | "manual" | "local_fallback";
+    const backendStyle = assertComputerUseBackendStyle(toolArgs.backendStyle, "backendStyle");
     const backendName = assertNonEmptyString(toolArgs.backendName, "backendName");
     const manifestPath = asOptionalTrimmedString(toolArgs.manifestPath);
     let inputs = Array.isArray(toolArgs.inputs) ? toolArgs.inputs.map((entry) => safeObject(entry)) : [];
@@ -6007,6 +5944,7 @@ async function runTool(args: {
     const result = runtime.computerUseArtifactBrokerService.ingest({
       backend: {
         name: backendName,
+        style: backendStyle,
         toolName: asOptionalTrimmedString(toolArgs.toolName),
         command: asOptionalTrimmedString(toolArgs.command),
       },
@@ -7402,9 +7340,8 @@ const APP_NAVIGATE_SUPPORTED_KINDS = new Set([
 export function createAdeRpcRequestHandler(args: {
   runtime: AdeRuntime;
   serverVersion: string;
-  onActionsListChanged?: (() => void) | null;
 }): JsonRpcHandler & { dispose: () => void } {
-  const { runtime, serverVersion, onActionsListChanged } = args;
+  const { runtime, serverVersion } = args;
 
   const session: SessionState = {
     initialized: false,
@@ -7518,11 +7455,21 @@ export function createAdeRpcRequestHandler(args: {
         protocolVersion: session.protocolVersion,
         runtimeInfo: {
           name: "ade-rpc",
-          version: serverVersion
+          version: serverVersion,
+          buildHash:
+            typeof process.env.ADE_RUNTIME_BUILD_HASH === "string" &&
+            process.env.ADE_RUNTIME_BUILD_HASH.trim()
+              ? process.env.ADE_RUNTIME_BUILD_HASH.trim()
+              : null,
+          defaultRole:
+            normalizeAdeRuntimeRole(process.env.ADE_DEFAULT_ROLE),
+          projectRoot: runtime.projectRoot,
+          workspaceRoot: runtime.workspaceRoot ?? null,
+          pid: process.pid
         },
         capabilities: {
           actions: {
-            listChanged: true
+            listChanged: false
           },
           ...(resourcesEnabled
             ? {

apps/ade-cli/src/cli.test.ts

@@ -59,6 +59,18 @@ describe("ADE CLI", () => {
     ]);
   });
 
+  it("defaults ordinary CLI calls to the agent runtime role", () => {
+    const previousRole = process.env.ADE_DEFAULT_ROLE;
+    delete process.env.ADE_DEFAULT_ROLE;
+    try {
+      const parsed = parseCliArgs(["lanes", "list"]);
+      expect(parsed.options.role).toBe("agent");
+    } finally {
+      if (previousRole === undefined) delete process.env.ADE_DEFAULT_ROLE;
+      else process.env.ADE_DEFAULT_ROLE = previousRole;
+    }
+  });
+
   it("maps ade code to the terminal Work chat launcher", () => {
     const parsed = parseCliArgs([
       "--project-root",