From 8e31d98b5c6419d7d3ace54e814cbb37b1b7c973 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:02:35 -0400
Subject: [PATCH 01/24] perf(boot): defer Linear quick view visibility check

boot open-project score 694.26 -> 204.38; removed ade.cto.getLinearConnectionStatus 2039ms from startup summary
---
 .../components/app/LinearQuickViewButton.tsx         |  7 ++++++-
 .../src/renderer/components/app/TopBar.test.tsx      | 12 ++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/renderer/components/app/LinearQuickViewButton.tsx b/apps/desktop/src/renderer/components/app/LinearQuickViewButton.tsx
index 31ee35ab0..a80142f68 100644
--- a/apps/desktop/src/renderer/components/app/LinearQuickViewButton.tsx
+++ b/apps/desktop/src/renderer/components/app/LinearQuickViewButton.tsx
@@ -15,6 +15,8 @@ import { LinearIssueBrowser, linearBrowserIssueToLaneIssue } from "./LinearIssue
 
 type PopoverPosition = { top: number; right: number } | null;
 
+const INITIAL_VISIBILITY_CHECK_DELAY_MS = 8_000;
+
 export function LinearQuickViewButton() {
   const project = useAppStore((s) => s.project);
   const refreshLanes = useAppStore((s) => s.refreshLanes);
@@ -42,15 +44,18 @@ export function LinearQuickViewButton() {
     setVisible(false);
     setOpen(false);
     setQuickView(null);
-    void loadVisibility()
+    const timer = window.setTimeout(() => {
+      void loadVisibility()
       .then((nextVisible) => {
         if (!cancelled) setVisible(nextVisible);
       })
       .catch(() => {
         if (!cancelled) setVisible(false);
       });
+    }, INITIAL_VISIBILITY_CHECK_DELAY_MS);
     return () => {
       cancelled = true;
+      window.clearTimeout(timer);
     };
   }, [loadVisibility, project?.rootPath]);
 
diff --git a/apps/desktop/src/renderer/components/app/TopBar.test.tsx b/apps/desktop/src/renderer/components/app/TopBar.test.tsx
index faf078181..aa97101c6 100644
--- a/apps/desktop/src/renderer/components/app/TopBar.test.tsx
+++ b/apps/desktop/src/renderer/components/app/TopBar.test.tsx
@@ -566,6 +566,11 @@ describe("TopBar", () => {
 
     render(<TopBar />);
 
+    await act(async () => {
+      window.dispatchEvent(new Event("focus"));
+      await Promise.resolve();
+    });
+
     fireEvent.click(await screen.findByRole("button", { name: /linear quick view/i }));
 
     await waitFor(() => {
@@ -617,6 +622,13 @@ describe("TopBar", () => {
 
     render(<TopBar />);
 
+    expect(getLinearConnectionStatus).not.toHaveBeenCalled();
+    expect(screen.queryByRole("button", { name: /linear quick view/i })).toBeNull();
+
+    await act(async () => {
+      window.dispatchEvent(new Event("focus"));
+      await Promise.resolve();
+    });
     await waitFor(() => {
       expect(getLinearConnectionStatus).toHaveBeenCalledTimes(1);
     });

From a35ae3cfa997420407578335fd92c3e80750e444 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:05:40 -0400
Subject: [PATCH 02/24] fix(tui): stream daemon chat events to ade code

Adapt multi-project runtime chat envelopes from runtime/event into the TUI onChatEvent stream; verified attached print-state and focused connection tests.
---
 .../tuiClient/__tests__/connection.test.ts    | 87 +++++++++++++++++++
 apps/ade-cli/src/tuiClient/connection.ts      | 66 +++++++++++++-
 2 files changed, 149 insertions(+), 4 deletions(-)

diff --git a/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts b/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts
index bcdbfb181..178d68d06 100644
--- a/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts
+++ b/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts
@@ -221,6 +221,93 @@ describe("connectToAde embedded mode", () => {
     expect(requests.at(-1)?.params).toMatchObject({ projectId: "project-daemon" });
   });
 
+  it("adapts multi-project runtime chat events into the TUI chat stream", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "ade-code-connection-"));
+    const socketPath = path.join(tmpDir, "ade.sock");
+    const serverSocketRef: { current: net.Socket | null } = { current: null };
+    const requests: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const server = net.createServer((socket) => {
+      serverSocketRef.current = socket;
+      let buffer = "";
+      socket.on("data", (chunk) => {
+        buffer += chunk.toString("utf8");
+        while (true) {
+          const newline = buffer.indexOf("\n");
+          if (newline < 0) return;
+          const line = buffer.slice(0, newline).trim();
+          buffer = buffer.slice(newline + 1);
+          if (!line) continue;
+          const request = JSON.parse(line) as { id: number; method: string; params?: Record<string, unknown> };
+          requests.push({ method: request.method, params: request.params });
+          const result = (() => {
+            if (request.method === "ade/initialize") {
+              return {
+                runtimeInfo: { multiProject: true },
+                capabilities: { projects: true },
+              };
+            }
+            if (request.method === "projects.add") {
+              return { projectId: "project-daemon", rootPath: project.projectRoot };
+            }
+            if (request.method === "runtimeEvents.subscribe") {
+              return { subscriptionId: "runtime-sub-1" };
+            }
+            if (request.method === "runtimeEvents.unsubscribe") {
+              return { removed: true };
+            }
+            return null;
+          })();
+          socket.write(`${JSON.stringify({ jsonrpc: "2.0", id: request.id, result })}\n`);
+        }
+      });
+    });
+    await new Promise<void>((resolve) => server.listen(socketPath, resolve));
+
+    const connection = await connectToAde({
+      project,
+      socketPath,
+    });
+    try {
+      const delivered = new Promise<AgentChatEventEnvelope>((resolve) => {
+        connection.onChatEvent(resolve);
+      });
+      await vi.waitUntil(
+        () => requests.some((request) => request.method === "runtimeEvents.subscribe"),
+        { timeout: 1000 },
+      );
+      expect(requests.find((request) => request.method === "runtimeEvents.subscribe")?.params)
+        .toMatchObject({ projectId: "project-daemon", category: "runtime" });
+
+      const envelope = {
+        sessionId: "chat-1",
+        timestamp: "2026-05-14T00:00:00.000Z",
+        event: { type: "text", text: "hello from daemon" },
+        sequence: 1,
+      } as AgentChatEventEnvelope;
+      serverSocketRef.current?.write(`${JSON.stringify({
+        jsonrpc: "2.0",
+        method: "runtime/event",
+        params: {
+          subscriptionId: "runtime-sub-1",
+          projectId: "project-daemon",
+          event: {
+            id: 1,
+            timestamp: "2026-05-14T00:00:00.000Z",
+            category: "runtime",
+            payload: envelope,
+          },
+        },
+      })}\n`);
+
+      await expect(delivered).resolves.toEqual(envelope);
+    } finally {
+      await connection.close();
+      serverSocketRef.current?.destroy();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
   it("spawns the standalone binary directly when no CLI script entrypoint exists", async () => {
     const socketPath = useMissingMachineSocket();
     const missingEntrypointDir = fs.mkdtempSync(
diff --git a/apps/ade-cli/src/tuiClient/connection.ts b/apps/ade-cli/src/tuiClient/connection.ts
index 864c5dc17..9a0ce122e 100644
--- a/apps/ade-cli/src/tuiClient/connection.ts
+++ b/apps/ade-cli/src/tuiClient/connection.ts
@@ -279,6 +279,20 @@ function isMultiProjectRuntime(result: InitializeResult): boolean {
   );
 }
 
+function isAgentChatEventEnvelope(value: unknown): value is AgentChatEventEnvelope {
+  if (!isRecord(value)) return false;
+  if (typeof value.sessionId !== "string" || typeof value.timestamp !== "string") {
+    return false;
+  }
+  const event = value.event;
+  return isRecord(event) && typeof event.type === "string";
+}
+
+function runtimeChatEnvelope(event: BufferedEvent): AgentChatEventEnvelope | null {
+  if (event.category !== "runtime") return null;
+  return isAgentChatEventEnvelope(event.payload) ? event.payload : null;
+}
+
 function withProjectId(
   method: string,
   params: unknown,
@@ -356,7 +370,8 @@ async function connectAttachedSocket(args: {
       "ADE RPC socket did not finish initialization.",
     );
     let request = rawRequest;
-    if (isMultiProjectRuntime(initializeResult)) {
+    const multiProjectRuntime = isMultiProjectRuntime(initializeResult);
+    if (multiProjectRuntime) {
       const project = await rawRequest<ProjectRecord>("projects.add", {
         rootPath: args.project.projectRoot,
       });
@@ -382,10 +397,53 @@ async function connectAttachedSocket(args: {
       socketPath: args.socketPath,
       request,
       ...createAdeActionHelpers(request),
-      onChatEvent: (callback: (event: AgentChatEventEnvelope) => void) =>
-        attachedClient.onNotification("chat/event", (params) =>
+      onChatEvent: (callback: (event: AgentChatEventEnvelope) => void) => {
+        const stopChatNotification = attachedClient.onNotification("chat/event", (params) =>
           callback(params as AgentChatEventEnvelope),
-        ),
+        );
+        if (!multiProjectRuntime) return stopChatNotification;
+
+        let disposed = false;
+        let subscriptionId: string | null = null;
+        const pending: RuntimeEventNotification[] = [];
+        const stopRuntimeNotification = attachedClient.onNotification("runtime/event", (params) => {
+          const payload = params as RuntimeEventNotification;
+          if (!isBufferedEvent(payload.event)) return;
+          if (!subscriptionId) {
+            pending.push(payload);
+            return;
+          }
+          if (payload.subscriptionId !== subscriptionId) return;
+          const envelope = runtimeChatEnvelope(payload.event);
+          if (envelope) callback(envelope);
+        });
+        request<{ subscriptionId: string }>("runtimeEvents.subscribe", {
+          category: "runtime",
+          cursor: 0,
+          limit: 100,
+        }).then((response) => {
+          if (disposed) {
+            request("runtimeEvents.unsubscribe", { subscriptionId: response.subscriptionId }).catch(() => {});
+            return;
+          }
+          subscriptionId = response.subscriptionId;
+          for (const payload of pending.splice(0)) {
+            if (payload.subscriptionId !== subscriptionId || !isBufferedEvent(payload.event)) continue;
+            const envelope = runtimeChatEnvelope(payload.event);
+            if (envelope) callback(envelope);
+          }
+        }).catch(() => {
+          stopRuntimeNotification();
+        });
+        return () => {
+          disposed = true;
+          stopChatNotification();
+          stopRuntimeNotification();
+          if (subscriptionId) {
+            request("runtimeEvents.unsubscribe", { subscriptionId }).catch(() => {});
+          }
+        };
+      },
       subscribeRuntimeEvents: async (subscriptionArgs, callback) => {
         let subscriptionId: string | null = null;
         const pending: PendingRuntimeEvent[] = [];

From 0b67b157caa086a58a27f6cd1b445906b69208dd Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:08:38 -0400
Subject: [PATCH 03/24] perf(lanes): avoid snapshot refresh for local git state

---
 .../src/renderer/components/lanes/LaneGitActionsPane.test.tsx   | 2 +-
 .../src/renderer/components/lanes/LaneGitActionsPane.tsx        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/src/renderer/components/lanes/LaneGitActionsPane.test.tsx b/apps/desktop/src/renderer/components/lanes/LaneGitActionsPane.test.tsx
index f62bf5e59..c536eee50 100644
--- a/apps/desktop/src/renderer/components/lanes/LaneGitActionsPane.test.tsx
+++ b/apps/desktop/src/renderer/components/lanes/LaneGitActionsPane.test.tsx
@@ -324,7 +324,7 @@ describe("LaneGitActionsPane rescue action", () => {
     await waitFor(() => {
       expect(mockStoreState.refreshLanes).toHaveBeenCalledWith({
         includeStatus: true,
-        includeSnapshots: true,
+        includeSnapshots: false,
       });
     });
     await waitFor(() => {
diff --git a/apps/desktop/src/renderer/components/lanes/LaneGitActionsPane.tsx b/apps/desktop/src/renderer/components/lanes/LaneGitActionsPane.tsx
index 1f7844d7f..eb39d6090 100644
--- a/apps/desktop/src/renderer/components/lanes/LaneGitActionsPane.tsx
+++ b/apps/desktop/src/renderer/components/lanes/LaneGitActionsPane.tsx
@@ -721,7 +721,7 @@ export function LaneGitActionsPane({
   const refreshLaneGitState = useCallback(async (targetLaneId: string | null) => {
     await Promise.all([
       refreshChanges(targetLaneId),
-      refreshLanes({ includeStatus: true, includeSnapshots: true }),
+      refreshLanes({ includeStatus: true, includeSnapshots: false }),
       refreshGitMeta(targetLaneId),
     ]);
   }, [refreshChanges, refreshGitMeta, refreshLanes]);

From 8af850dacad9818c0c3fdcbe5f58160898810d37 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:19:54 -0400
Subject: [PATCH 04/24] feat(agents): bundle ADE operating skills

---
 apps/desktop/package.json                     |  7 ++
 .../agent-skills/ade-app-control/SKILL.md     | 51 +++++++++++++
 .../agent-skills/ade-browser/SKILL.md         | 37 ++++++++++
 .../ade-cli-control-plane/SKILL.md            | 32 ++++++++
 .../agent-skills/ade-cto-missions/SKILL.md    | 45 ++++++++++++
 .../agent-skills/ade-ios-simulator/SKILL.md   | 73 +++++++++++++++++++
 .../agent-skills/ade-lanes-git/SKILL.md       | 49 +++++++++++++
 .../agent-skills/ade-macos-vm/SKILL.md        | 35 +++++++++
 .../agent-skills/ade-pr-workflows/SKILL.md    | 37 ++++++++++
 .../agent-skills/ade-proof-artifacts/SKILL.md | 33 +++++++++
 .../scripts/validate-mac-artifacts.mjs        |  2 +
 .../scripts/validate-win-artifacts.mjs        |  2 +
 .../services/ai/tools/systemPrompt.test.ts    |  6 +-
 .../chat/claudeSlashCommandDiscovery.test.ts  | 51 ++++++++++++-
 .../chat/claudeSlashCommandDiscovery.ts       | 72 +++++++++++++++---
 .../services/memory/skillRegistryService.ts   | 16 +++-
 apps/desktop/src/shared/adeCliGuidance.ts     | 41 +++--------
 17 files changed, 538 insertions(+), 51 deletions(-)
 create mode 100644 apps/desktop/resources/agent-skills/ade-app-control/SKILL.md
 create mode 100644 apps/desktop/resources/agent-skills/ade-browser/SKILL.md
 create mode 100644 apps/desktop/resources/agent-skills/ade-cli-control-plane/SKILL.md
 create mode 100644 apps/desktop/resources/agent-skills/ade-cto-missions/SKILL.md
 create mode 100644 apps/desktop/resources/agent-skills/ade-ios-simulator/SKILL.md
 create mode 100644 apps/desktop/resources/agent-skills/ade-lanes-git/SKILL.md
 create mode 100644 apps/desktop/resources/agent-skills/ade-macos-vm/SKILL.md
 create mode 100644 apps/desktop/resources/agent-skills/ade-pr-workflows/SKILL.md
 create mode 100644 apps/desktop/resources/agent-skills/ade-proof-artifacts/SKILL.md

diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index a2ad7c074..dddf4e406 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -228,6 +228,13 @@
         "filter": [
           "**/*"
         ]
+      },
+      {
+        "from": "resources/agent-skills",
+        "to": "agent-skills",
+        "filter": [
+          "**/*"
+        ]
       }
     ],
     "afterPack": "./scripts/after-pack-runtime-fixes.cjs",
diff --git a/apps/desktop/resources/agent-skills/ade-app-control/SKILL.md b/apps/desktop/resources/agent-skills/ade-app-control/SKILL.md
new file mode 100644
index 000000000..6267ae912
--- /dev/null
+++ b/apps/desktop/resources/agent-skills/ade-app-control/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: ade-app-control
+description: Use this skill when inspecting, launching, logging, clicking, typing, or selecting context from Electron apps through ADE App Control and the `ade app-control` CLI.
+---
+
+# ADE App Control
+
+## Use socket mode
+
+App Control is a live desktop drawer service. Prefer socket-backed commands:
+
+```bash
+ade help app-control
+ade --socket app-control status --text
+ade --socket app-control launch --command "npm run dev" --text
+ade --socket app-control connect --cdp-port <port> --text
+```
+
+ADE sets `ADE_APP_CONTROL_CDP_PORT` and `ADE_APP_CONTROL_DEBUG_FLAGS` for launches. Custom Electron launchers should forward one of those values to `--remote-debugging-port`.
+
+## Inspect
+
+```bash
+ade --socket app-control snapshot --text
+ade --socket app-control elements --text
+ade --socket app-control select --x <x> --y <y> --text
+```
+
+Use Inspect mode or `select` to return screenshot-backed DOM, selector, and source context. When the session is chat-owned, ADE can attach the selection to the drawer chat.
+
+## Act
+
+```bash
+ade --socket app-control click --x <x> --y <y> --text
+ade --socket app-control type --value "text" --text
+```
+
+Use Control mode for input. Re-snapshot after meaningful UI changes.
+
+## Logs and terminal
+
+Start with App Control status, then prefer App Control terminal/log commands:
+
+```bash
+ade --socket app-control logs --text --max-bytes 8388608
+ade --socket app-control terminal write --data "y\n"
+ade --socket app-control terminal signal --signal SIGINT
+```
+
+Only fall back to `ade --socket terminal list --text` and `ade --socket terminal read ...` when no App Control terminal is active.
+
diff --git a/apps/desktop/resources/agent-skills/ade-browser/SKILL.md b/apps/desktop/resources/agent-skills/ade-browser/SKILL.md
new file mode 100644
index 000000000..fb72ef03d
--- /dev/null
+++ b/apps/desktop/resources/agent-skills/ade-browser/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: ade-browser
+description: Use this skill when using ADE's built-in browser pane, shared browser tabs, screenshots, page inspection, or browser context selection through `ade browser`.
+---
+
+# ADE browser
+
+## Scope
+
+The ADE browser is global, not lane-scoped. Use socket mode so CLI calls and the Work sidebar share the same tabs.
+
+## Common commands
+
+```bash
+ade help browser
+ade --socket browser panel --text
+ade --socket browser status --text
+ade --socket browser open <url> --new-tab --text
+ade --socket browser tabs --text
+ade --socket browser switch --tab <id> --text
+ade --socket browser screenshot --text
+```
+
+For inspection and chat context:
+
+```bash
+ade --socket browser inspect-start --text
+ade --socket browser select-current --text
+ade --socket browser clear-selection --text
+```
+
+## Gotchas
+
+- Open localhost URLs and chat-output links in the ADE browser when the user expects them to show in the Work sidebar.
+- Because tabs are global, confirm the active tab before taking a screenshot or selecting context.
+- If there is no active browser panel/session, report the blocker rather than pretending to inspect the page.
+
diff --git a/apps/desktop/resources/agent-skills/ade-cli-control-plane/SKILL.md b/apps/desktop/resources/agent-skills/ade-cli-control-plane/SKILL.md
new file mode 100644
index 000000000..43c0feff4
--- /dev/null
+++ b/apps/desktop/resources/agent-skills/ade-cli-control-plane/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: ade-cli-control-plane
+description: Use this skill when an agent needs to inspect or operate ADE itself through the `ade` CLI, including lanes, chats, actions, memory, proof, runtime/socket state, or help/flag discovery.
+---
+
+# ADE CLI control plane
+
+## Core rule
+
+Use normal shell commands for local repo edits, tests, and Git inspection. Use `ade` when you need ADE state or ADE-owned services: lanes, chats, missions, PR metadata, memory, proof/artifacts, managed terminals, App Control, iOS Simulator, browser, macOS VM, settings, usage, updates, or service actions.
+
+## First checks
+
+1. Run `ade doctor --text` when the ADE environment is unclear.
+2. Run `ade help <command>` or `ade help <command> <subcommand>` before guessing flags.
+3. Prefer `--text` for human-readable output and JSON output when scripting.
+4. Use `ade actions list --text` or `ade actions list --domain <domain> --text` as the escape hatch for service methods without a typed command.
+
+## Socket mode
+
+Use `--socket` when the CLI and ADE desktop drawer must share live state. This matters for App Control, iOS Simulator, Preview Lab, browser tabs, terminal logs, context selection, and proof drawer updates.
+
+## Fallback path
+
+If `command -v ade` fails:
+
+1. Try `${ADE_CLI_PATH:-}` if set.
+2. Try `${ADE_CLI_BIN_DIR:-}/ade` if set.
+3. In an ADE source checkout, after confirming it exists, use `node apps/ade-cli/dist/cli.cjs ...`.
+
+The normal reason to skip ADE CLI is that it is truly unreachable after these fallbacks.
+
diff --git a/apps/desktop/resources/agent-skills/ade-cto-missions/SKILL.md b/apps/desktop/resources/agent-skills/ade-cto-missions/SKILL.md
new file mode 100644
index 000000000..acb58b78b
--- /dev/null
+++ b/apps/desktop/resources/agent-skills/ade-cto-missions/SKILL.md
@@ -0,0 +1,45 @@
+---
+name: ade-cto-missions
+description: Use this skill when operating ADE CTO, missions, coordinator tools, worker agents, Linear routing, multi-agent orchestration, or mission run inspection.
+---
+
+# ADE CTO and missions
+
+## CTO
+
+Use CTO commands for team-lead state and Work chats:
+
+```bash
+ade cto state --text
+ade cto chats --text
+ade help cto
+```
+
+## Missions
+
+Use missions for orchestrated multi-step work:
+
+```bash
+ade missions list --text
+ade missions launch --prompt "..." --manual --text
+ade missions watch <mission-id> --text
+ade missions graph <mission-id> --text
+ade missions runs <mission-id> --text
+```
+
+## Coordinator and Linear
+
+```bash
+ade coordinator <tool> --help
+ade linear workflows --text
+ade linear run <workflow> --text
+ade linear sync --text
+```
+
+## Operating rules
+
+- Keep worker briefs small and specific.
+- Use project memory for non-obvious conventions and past pitfalls, not for information derivable from code or git.
+- When polling long-running mission/worker state, return compact summaries instead of pasting full logs.
+- If a worker result conflicts with repo evidence, inspect the files yourself before merging its conclusion.
+
diff --git a/apps/desktop/resources/agent-skills/ade-ios-simulator/SKILL.md b/apps/desktop/resources/agent-skills/ade-ios-simulator/SKILL.md
new file mode 100644
index 000000000..dbd16fac7
--- /dev/null
+++ b/apps/desktop/resources/agent-skills/ade-ios-simulator/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: ade-ios-simulator
+description: Use this skill when working with ADE iOS Simulator, Preview Lab, SwiftUI preview rendering, simulator screenshots, taps, streams, or iOS drawer context via `ade ios-sim`.
+---
+
+# ADE iOS Simulator and Preview Lab
+
+## Start here
+
+Use socket mode so CLI actions and the desktop drawer share one simulator session:
+
+```bash
+ade --socket ios-sim status --text
+ade --socket ios-sim devices --text
+ade --socket ios-sim apps --text
+ade help ios-sim launch
+```
+
+Launch with a target from `apps`:
+
+```bash
+ade --socket ios-sim launch --target <id> --text
+```
+
+## Inspect and interact
+
+Capture current screen/context before acting:
+
+```bash
+ade --socket ios-sim snapshot --text
+ade --socket ios-sim elements --text
+ade --socket ios-sim select --x <x> --y <y> --text
+```
+
+Interact with the running app:
+
+```bash
+ade --socket ios-sim tap --x <x> --y <y> --text
+ade --socket ios-sim drag --start-x <x> --start-y <y> --end-x <x> --end-y <y> --text
+ade --socket ios-sim type --value "text" --text
+```
+
+## Streams
+
+Use `stream-status` to explain the active backend, latency, fallback reason, and blockers:
+
+```bash
+ade --socket ios-sim window-start --fps 60 --text
+ade --socket ios-sim live-start --fps 30 --text
+ade --socket ios-sim stream-status --text
+ade --socket ios-sim stream-stop --text
+```
+
+Low idle fps is normal on `iosurface-indigo` because frames are event-driven when the simulator is still.
+
+## Preview Lab
+
+For SwiftUI preview work:
+
+```bash
+ade --socket ios-sim preview-status --text
+ade --socket ios-sim previews --source <swift-file> --text
+ade --socket ios-sim preview-render --source <swift-file> --index <n> --text
+```
+
+Add a preview only when no useful nearby preview already exists. Preview fixtures must not require live sync, keychain, network, push, sockets, or production databases.
+
+## Gotchas
+
+- Do not create symlink projects, fake schemes, or repo-layout shims as the first fix for app detection. Re-run `ade --socket ios-sim apps --text` and report the selected project, scheme, and build output.
+- If no simulator/session/snapshot exists, report the exact blocker instead of guessing the screen.
+- When you own the simulator session and the task no longer needs it, run `ade --socket ios-sim shutdown --text`.
+
diff --git a/apps/desktop/resources/agent-skills/ade-lanes-git/SKILL.md b/apps/desktop/resources/agent-skills/ade-lanes-git/SKILL.md
new file mode 100644
index 000000000..49e2f8453
--- /dev/null
+++ b/apps/desktop/resources/agent-skills/ade-lanes-git/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: ade-lanes-git
+description: Use this skill when creating, inspecting, syncing, committing, pushing, archiving, or rebasing ADE lanes and lane worktrees through `ade lanes` and `ade git`.
+---
+
+# ADE lanes and git
+
+## Lanes
+
+Lanes are ADE-managed git worktrees and branches.
+
+```bash
+ade lanes list --text
+ade lanes show <lane> --text
+ade lanes create --name <name> --description "..." --text
+ade lanes child --lane <parent> --name <name> --text
+ade lanes archive <lane> --text
+```
+
+## ADE-aware Git
+
+Use ADE git commands when the operation should update ADE operation state and refresh lane status:
+
+```bash
+ade git status --lane <lane> --text
+ade git status --full --lane <lane> --text
+ade git sync --lane <lane> --rebase --base main --text
+ade git stage --lane <lane> <path>
+ade git stage-all --lane <lane>
+ade git commit --lane <lane> -m "message"
+ade git push --lane <lane> --set-upstream --text
+```
+
+## Rebase and conflicts
+
+```bash
+ade git rebase --lane <lane> --ai --text
+ade git conflict show --lane <lane> --text
+ade git rebase continue --lane <lane> --text
+```
+
+For conflicts, inspect both sides and preserve intent from both branches. Do not blindly accept ours/theirs.
+
+## Gotchas
+
+- Use `--lane` for anything other than the active workspace.
+- Use `ade diff changes --lane <lane> --text` when you need ADE's view of file changes.
+- Do not archive or delete lanes unless the user asked for cleanup or the release workflow explicitly requires it.
+
diff --git a/apps/desktop/resources/agent-skills/ade-macos-vm/SKILL.md b/apps/desktop/resources/agent-skills/ade-macos-vm/SKILL.md
new file mode 100644
index 000000000..1ad8a0f01
--- /dev/null
+++ b/apps/desktop/resources/agent-skills/ade-macos-vm/SKILL.md
@@ -0,0 +1,35 @@
+---
+name: ade-macos-vm
+description: Use this skill when starting, inspecting, guiding, screenshotting, selecting, clicking, typing, or troubleshooting ADE lane-tied macOS VMs through `ade macos-vm`.
+---
+
+# ADE macOS VM
+
+## Start
+
+macOS VMs are lane-tied agent workspaces.
+
+```bash
+ade help macos-vm
+ade --socket macos-vm status --lane <lane> --text
+ade --socket macos-vm start --lane <lane> --create --text
+ade --socket macos-vm guide --lane <lane> --text
+```
+
+## Interact
+
+```bash
+ade --socket macos-vm screenshot --lane <lane> --text
+ade --socket macos-vm select --lane <lane> --x <x> --y <y> --text
+ade --socket macos-vm click --lane <lane> <x> <y>
+ade --socket macos-vm type --lane <lane> --value "text"
+```
+
+Click/select coordinates are window-relative by default.
+
+## Gotchas
+
+- Keep code edits under the guest shared path described by `guide`.
+- Confirm provider readiness from `status` before promising VM interaction.
+- If the VM is missing or blocked, report the exact status and next action.
+
diff --git a/apps/desktop/resources/agent-skills/ade-pr-workflows/SKILL.md b/apps/desktop/resources/agent-skills/ade-pr-workflows/SKILL.md
new file mode 100644
index 000000000..b362f4f78
--- /dev/null
+++ b/apps/desktop/resources/agent-skills/ade-pr-workflows/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: ade-pr-workflows
+description: Use this skill when working with ADE PR workflows including PR tab data, PR checks/comments, queues, Path to Merge, rebase resolver, issue resolver agents, CI fixes, or merge readiness.
+---
+
+# ADE PR workflows
+
+## Start with typed PR commands
+
+```bash
+ade prs list --text
+ade prs show <pr-id-or-number-or-url> --text
+ade prs checks <pr-id-or-number-or-url> --text
+ade prs comments <pr-id-or-number-or-url> --text
+ade prs path-to-merge <pr-id-or-number-or-url> --model <model> --max-rounds 3 --no-auto-merge --text
+```
+
+Use `ade help prs` and `ade help git rebase` before guessing PR or rebase flags.
+
+## Use actions for niche surfaces
+
+```bash
+ade actions list --domain pr --text
+ade actions list --domain issue_inventory --text
+ade actions run <domain.action> --input-json '{"key":"value"}'
+```
+
+## Resolver rules
+
+- Preserve both the lane's intent and main's intent during conflicts.
+- Read conflict files and surrounding call sites before choosing a side.
+- For review-thread or CI work, fetch current checks/comments first; do not rely on stale PR tab state.
+- Prefer focused fixes and rerun the smallest relevant check before escalating to broader validation.
+
+## Release readiness
+
+Before treating a PR as merge-ready, verify working tree cleanliness, pushed branch status, required checks, unresolved review threads, and whether rebasing/merging main introduced conflicts or semantic drift.
diff --git a/apps/desktop/resources/agent-skills/ade-proof-artifacts/SKILL.md b/apps/desktop/resources/agent-skills/ade-proof-artifacts/SKILL.md
new file mode 100644
index 000000000..79e9a1341
--- /dev/null
+++ b/apps/desktop/resources/agent-skills/ade-proof-artifacts/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: ade-proof-artifacts
+description: Use this skill when the user asks for proof, screenshots, video, artifacts, test evidence, computer-use capture, or when work should appear in ADE's proof drawer.
+---
+
+# ADE proof and artifacts
+
+## Rule
+
+When the user asks to capture, send, attach, or provide proof, create evidence with the relevant tool, then register it through ADE so it appears in the proof drawer for the active chat, mission, or lane.
+
+## Commands
+
+```bash
+ade proof status --text
+ade proof list --text
+ade proof screenshot --text
+ade proof record --seconds 20 --text
+ade help proof
+```
+
+## What counts as proof
+
+- Screenshot or video of the UI state.
+- App Control, iOS Simulator, ADE browser, or macOS VM capture.
+- Test output or log bundle when visual proof is not the right artifact.
+
+## Gotchas
+
+- Do not leave proof as an unregistered local file when the user expects ADE to show it.
+- Include enough context in the artifact name/description to understand what was verified.
+- Clean up stale processes you started before declaring proof complete.
+
diff --git a/apps/desktop/scripts/validate-mac-artifacts.mjs b/apps/desktop/scripts/validate-mac-artifacts.mjs
index c5361b6df..9561dbab3 100644
--- a/apps/desktop/scripts/validate-mac-artifacts.mjs
+++ b/apps/desktop/scripts/validate-mac-artifacts.mjs
@@ -322,6 +322,7 @@ async function validatePackagedRuntime(appPath, description) {
   const adeCliTuiPath = path.join(resourcesPath, "ade-cli", "tuiClient", "cli.mjs");
   const adeCliBinPath = path.join(resourcesPath, "ade-cli", "bin", "ade");
   const adeCliInstallerPath = path.join(resourcesPath, "ade-cli", "install-path.sh");
+  const bundledAgentSkillsPath = path.join(resourcesPath, "agent-skills", "ade-cli-control-plane", "SKILL.md");
   const iosSimHelperRoot = path.join(resourcesPath, "native", "ios-sim-helpers");
   const iosSimHelperBuildScript = path.join(iosSimHelperRoot, "build.sh");
   const nodeModulesPath = path.join(unpackedPath, "node_modules");
@@ -338,6 +339,7 @@ async function validatePackagedRuntime(appPath, description) {
   await assertPathExists(adeCliTuiPath, "bundled ADE CLI TUI entry");
   await assertPathExists(adeCliBinPath, "bundled ADE CLI wrapper");
   await assertPathExists(adeCliInstallerPath, "bundled ADE CLI PATH installer");
+  await assertPathExists(bundledAgentSkillsPath, "bundled ADE agent skills");
   await assertPathExists(iosSimHelperBuildScript, "bundled iOS simulator helper build script");
   await assertPathExists(path.join(iosSimHelperRoot, "sim-capture.swift"), "bundled iOS simulator capture helper source");
   await assertPathExists(path.join(iosSimHelperRoot, "sim-input.m"), "bundled iOS simulator input helper source");
diff --git a/apps/desktop/scripts/validate-win-artifacts.mjs b/apps/desktop/scripts/validate-win-artifacts.mjs
index 96450589d..8d0d1acc0 100644
--- a/apps/desktop/scripts/validate-win-artifacts.mjs
+++ b/apps/desktop/scripts/validate-win-artifacts.mjs
@@ -456,6 +456,7 @@ async function validatePackagedRuntime(appDir) {
   const adeCliTuiPath = path.join(resourcesPath, "ade-cli", "tuiClient", "cli.mjs");
   const adeCliBinPath = path.join(resourcesPath, "ade-cli", "bin", "ade.cmd");
   const adeCliInstallerPath = path.join(resourcesPath, "ade-cli", "install-path.cmd");
+  const bundledAgentSkillsPath = path.join(resourcesPath, "agent-skills", "ade-cli-control-plane", "SKILL.md");
   const nodeModulesPath = path.join(unpackedPath, "node_modules");
   const nodePtyModulePath = path.join(nodeModulesPath, "node-pty");
   const sqlJsModulePath = path.join(nodeModulesPath, "sql.js");
@@ -482,6 +483,7 @@ async function validatePackagedRuntime(appDir) {
   await assertPathExists(adeCliTuiPath, "bundled ADE CLI TUI entry");
   await assertPathExists(adeCliBinPath, "bundled ADE CLI wrapper");
   await assertPathExists(adeCliInstallerPath, "bundled ADE CLI PATH installer");
+  await assertPathExists(bundledAgentSkillsPath, "bundled ADE agent skills");
   await assertPathExists(nodePtyModulePath, "unpacked node-pty module");
   await assertPathExists(sqlJsModulePath, "unpacked sql.js module");
   await assertPathExists(path.join(onnxRuntimeWinPath, "onnxruntime_binding.node"), "Windows ONNX Runtime native addon");
diff --git a/apps/desktop/src/main/services/ai/tools/systemPrompt.test.ts b/apps/desktop/src/main/services/ai/tools/systemPrompt.test.ts
index 8d6008179..a095fe47e 100644
--- a/apps/desktop/src/main/services/ai/tools/systemPrompt.test.ts
+++ b/apps/desktop/src/main/services/ai/tools/systemPrompt.test.ts
@@ -302,9 +302,9 @@ describe("buildCodingAgentSystemPrompt", () => {
     expect(result).toContain("## Operating Loop");
     expect(result).toContain("## ADE CLI");
     expect(result).toContain("only normal reason to skip ADE CLI");
-    expect(result).toContain("can be driven from ADE CLI sessions");
-    expect(result).toContain("ade help ios-sim");
-    expect(result).toContain("preview-render --source <swift-file>");
+    expect(result).toContain("ADE ships Agent Skills for deeper operating details");
+    expect(result).toContain("ade-ios-simulator");
+    expect(result).toContain("ade-cli-control-plane");
     expect(result).toContain("## Editing Rules");
     expect(result).toContain("## Verification Rules");
     expect(result).toContain("## User-Facing Progress");
diff --git a/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.test.ts b/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.test.ts
index 161e4c5de..d8dd4975d 100644
--- a/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.test.ts
+++ b/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.test.ts
@@ -147,12 +147,55 @@ describe("discoverClaudeSlashCommands", () => {
       "",
     ].join("\n"));
 
-    expect(discoverClaudeSlashCommands(tmpRoot)).toMatchObject([
-      {
+    const commands = discoverClaudeSlashCommands(tmpRoot);
+    expect(commands).toEqual(expect.arrayContaining([
+      expect.objectContaining({
         name: "/fix-issue",
         description: "Fix a GitHub issue",
-      },
-    ]);
+      }),
+    ]));
+    expect(commands).not.toEqual(expect.arrayContaining([
+      expect.objectContaining({ name: "/background-context" }),
+    ]));
+  });
+
+  it("discovers cross-client .agents skills and ADE project skills", () => {
+    const agentsSkill = path.join(tmpRoot, ".agents", "skills", "ios-lab");
+    const adeSkill = path.join(tmpRoot, ".ade", "skills", "pr-resolver");
+    fs.mkdirSync(agentsSkill, { recursive: true });
+    fs.mkdirSync(adeSkill, { recursive: true });
+    fs.writeFileSync(path.join(agentsSkill, "SKILL.md"), [
+      "---",
+      "name: ios-lab",
+      "description: Use this skill for simulator work",
+      "---",
+      "",
+      "Inspect the simulator.",
+      "",
+    ].join("\n"));
+    fs.writeFileSync(path.join(adeSkill, "SKILL.md"), [
+      "---",
+      "name: pr-resolver",
+      "description: Use this skill for PR resolver work",
+      "---",
+      "",
+      "Resolve the PR.",
+      "",
+    ].join("\n"));
+
+    const commands = discoverClaudeSlashCommands(tmpRoot);
+    expect(commands).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        name: "/ios-lab",
+        description: "Use this skill for simulator work",
+        source: "skill",
+      }),
+      expect.objectContaining({
+        name: "/pr-resolver",
+        description: "Use this skill for PR resolver work",
+        source: "skill",
+      }),
+    ]));
   });
 
   it("walks up parent directories to discover .claude/commands at workspace root from a lane subdir", () => {
diff --git a/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.ts b/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.ts
index eb7f1cece..764998058 100644
--- a/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.ts
+++ b/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.ts
@@ -251,15 +251,67 @@ function claudeRootsByPrecedence(cwd: string): string[] {
   return roots;
 }
 
+function ancestorSkillRoots(cwd: string, dirName: ".agents" | ".ade"): string[] {
+  const roots: string[] = [];
+  const seen = new Set<string>();
+  const home = path.resolve(os.homedir());
+  let current = path.resolve(cwd);
+  let depth = 0;
+  while (depth < 25) {
+    const candidate = path.join(current, dirName, "skills");
+    if (!seen.has(candidate)) {
+      seen.add(candidate);
+      roots.push(candidate);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    if (current === home) break;
+    current = parent;
+    depth += 1;
+  }
+  return roots;
+}
+
+function bundledSkillRoots(): string[] {
+  const candidates: string[] = [];
+  if (process.resourcesPath) {
+    candidates.push(path.join(process.resourcesPath, "agent-skills"));
+  }
+  return candidates;
+}
+
+function skillRootsByPrecedence(cwd: string): string[] {
+  const roots: string[] = [];
+  const seen = new Set<string>();
+  const addRoot = (root: string): void => {
+    const resolved = path.resolve(root);
+    if (seen.has(resolved)) return;
+    seen.add(resolved);
+    roots.push(resolved);
+  };
+
+  for (const root of claudeRootsByPrecedence(cwd)) addRoot(path.join(root, "skills"));
+  for (const root of ancestorSkillRoots(cwd, ".agents")) addRoot(root);
+  for (const root of ancestorSkillRoots(cwd, ".ade")) addRoot(root);
+  addRoot(path.join(os.homedir(), ".agents", "skills"));
+  addRoot(path.join(os.homedir(), ".ade", "skills"));
+  for (const root of bundledSkillRoots()) addRoot(root);
+  return roots;
+}
+
 export function discoverClaudeSlashCommands(cwd: string): DiscoveredClaudeSlashCommand[] {
-  const roots = claudeRootsByPrecedence(cwd);
+  const claudeRoots = claudeRootsByPrecedence(cwd);
   const byName = new Map<string, DiscoveredClaudeSlashCommand>();
 
-  for (const root of roots) {
-    const discovered = [
-      ...discoverLegacyCommands(path.join(root, "commands")),
-      ...discoverSkills(path.join(root, "skills")),
-    ];
+  for (const root of claudeRoots) {
+    const discovered = discoverLegacyCommands(path.join(root, "commands"));
+    for (const command of discovered) {
+      const key = slashCommandKey(command.name);
+      if (!byName.has(key)) byName.set(key, command);
+    }
+  }
+  for (const root of skillRootsByPrecedence(cwd)) {
+    const discovered = discoverSkills(root);
     for (const command of discovered) {
       const key = slashCommandKey(command.name);
       if (!byName.has(key)) byName.set(key, command);
@@ -317,17 +369,17 @@ export function resolveClaudeSlashCommandInvocation(
   const name = match[1];
   if (!name) return null;
   const argumentsText = match[2]?.trim() ?? "";
-  const roots = claudeRootsByPrecedence(cwd);
+  const claudeRoots = claudeRootsByPrecedence(cwd);
 
   // Prefer command files; fall back to user-invocable skills (SKILL.md).
   let resolvedFile: string | null = null;
-  for (const root of roots) {
+  for (const root of claudeRoots) {
     resolvedFile = resolveLegacyCommandFile(path.join(root, "commands"), name);
     if (resolvedFile) break;
   }
   if (!resolvedFile) {
-    for (const root of roots) {
-      resolvedFile = resolveSkillFile(path.join(root, "skills"), name);
+    for (const root of skillRootsByPrecedence(cwd)) {
+      resolvedFile = resolveSkillFile(root, name);
       if (resolvedFile) break;
     }
   }
diff --git a/apps/desktop/src/main/services/memory/skillRegistryService.ts b/apps/desktop/src/main/services/memory/skillRegistryService.ts
index 0c2b542e9..767066415 100644
--- a/apps/desktop/src/main/services/memory/skillRegistryService.ts
+++ b/apps/desktop/src/main/services/memory/skillRegistryService.ts
@@ -24,9 +24,11 @@ type SkillIndexRow = {
 
 const WATCH_PATTERNS = [
   ".ade/skills/**/*.md",
+  ".agents/skills/**/*.md",
   ".claude/skills/**/*.md",
   ".claude/commands/**/*.md",
   "CLAUDE.md",
+  "AGENTS.md",
   "agents.md",
 ];
 
@@ -139,6 +141,11 @@ function buildSkillMarkdown(input: {
   ];
 
   const lines = [
+    "---",
+    `name: ${slugify(input.title)}`,
+    `description: Use this skill when ${input.trigger.trim() || "the workflow applies"}.`,
+    "---",
+    "",
     `# ${input.title}`,
     "",
     "## When to use",
@@ -295,7 +302,7 @@ export function createSkillRegistryService(args: {
 
     // Root docs (CLAUDE.md, agents.md) should be read directly from disk --
     // do NOT import them as procedure memories.
-    if (kind !== "root_doc") {
+    if (kind !== "root_doc" && source !== "exported") {
       const existingMemory = existing?.memory_id ? memoryService.getMemory(existing.memory_id) : null;
       const importedProcedureContent = buildProcedureBody(title, content, absolutePath);
 
@@ -349,7 +356,7 @@ export function createSkillRegistryService(args: {
           supersededByMemoryId: memoryId,
         });
       }
-    } else {
+    } else if (kind === "root_doc") {
       // Root doc -- clear any previously-imported memory reference.
       memoryId = null;
     }
@@ -384,9 +391,10 @@ export function createSkillRegistryService(args: {
       }
     };
     crawl(path.join(projectRoot, ".ade", "skills"));
+    crawl(path.join(projectRoot, ".agents", "skills"));
     crawl(path.join(projectRoot, ".claude", "skills"));
     crawl(path.join(projectRoot, ".claude", "commands"));
-    for (const fileName of ["CLAUDE.md", "agents.md"]) {
+    for (const fileName of ["CLAUDE.md", "AGENTS.md", "agents.md"]) {
       const absolute = path.join(projectRoot, fileName);
       if (fs.existsSync(absolute)) discovered.add(path.resolve(absolute));
     }
@@ -415,7 +423,7 @@ export function createSkillRegistryService(args: {
     while (fs.existsSync(destinationPath)) {
       slug = `${slugBase}-${counter}`;
       counter += 1;
-      destinationDir = path.join(projectRoot, ".claude", "skills", slug);
+      destinationDir = path.join(projectRoot, ".ade", "skills", slug);
       destinationPath = path.join(destinationDir, "SKILL.md");
     }
     fs.mkdirSync(destinationDir, { recursive: true });
diff --git a/apps/desktop/src/shared/adeCliGuidance.ts b/apps/desktop/src/shared/adeCliGuidance.ts
index e87bdaaf4..8a32c6a8e 100644
--- a/apps/desktop/src/shared/adeCliGuidance.ts
+++ b/apps/desktop/src/shared/adeCliGuidance.ts
@@ -1,41 +1,22 @@
 export const ADE_CLI_AGENT_GUIDANCE = [
   "## ADE CLI",
-  "ADE is a local-first desktop development environment. It manages lanes (git worktrees), native ADE chats, terminal sessions, missions, PR workflows, memory, proof/artifacts, App Control, iOS Simulator/Preview Lab state, lane-tied macOS VMs, config, and managed processes.",
-  "`ade` is the default control plane for ADE-managed sessions. Use normal shell commands for the immediate repo inspection/edit/test in front of you; use ADE CLI when you need ADE state, drawer/session state, proof registration, missions, PR metadata, memory, or managed app/simulator control.",
+  "ADE is a local-first desktop development environment for lanes, chats, terminal sessions, missions, PR workflows, memory, proof/artifacts, App Control, iOS Simulator/Preview Lab state, lane-tied macOS VMs, config, and managed processes.",
+  "`ade` is the default control plane for ADE-managed sessions. Use normal shell commands for immediate repo inspection/edit/test work; use ADE CLI when you need ADE state, drawer/session state, proof registration, missions, PR metadata, memory, or managed app/simulator/browser/VM control.",
   "",
-  "### First orientation",
-  "- For ADE work beyond the immediate local edit, shell command, or repository inspection in front of you, check ADE CLI first.",
+  "### Discovery",
   "- Start with `ade doctor --text` when the environment is unclear.",
-  "- Use typed commands with `--text` for readable output: `ade lanes list --text`, `ade missions list --text`, `ade chats list --text`, `ade prs checks <pr> --text`, `ade proof status --text`, and `ade actions list --text`.",
-  "- Use `ade help <command>` and `ade help <command> <subcommand>` to discover exact flags instead of guessing. `ade actions list --text` / `ade actions run ...` is the escape hatch for service actions that do not yet have a friendly command.",
+  "- Use typed commands with `--text` for readable output: `ade lanes list --text`, `ade missions list --text`, `ade chat list --text`, `ade prs checks <pr> --text`, `ade proof status --text`, and `ade actions list --text`.",
+  "- Use `ade help <command>` and `ade help <command> <subcommand>` for exact flags. `ade actions list --text` / `ade actions run ...` is the escape hatch for service actions that do not yet have a friendly command.",
   "- If `command -v ade` fails, try `${ADE_CLI_PATH:-}` when set, then `${ADE_CLI_BIN_DIR:-}/ade`, and in an ADE source checkout fall back to `node apps/ade-cli/dist/cli.cjs ...` after confirming the file exists.",
   "- The only normal reason to skip ADE CLI for an ADE action is that the user truly does not have it installed or reachable after those fallbacks.",
   "",
-  "### Desktop socket surfaces",
-  "- Use `--socket` when the ADE desktop drawer and the CLI must share one live session. This matters for App Control, iOS Simulator, Preview Lab, terminal logs, selection/context capture, and proof drawer updates.",
-  "- iOS Simulator and Preview Lab can be driven from ADE CLI sessions when the desktop/runtime socket is available. In a standalone CLI session without `ADE_CHAT_SESSION_ID`, selections return inspect data and update the shared drawer service but do not automatically inject into a chat composer.",
-  "- For App Control on Electron apps, prefer socket mode: `ade help app-control`, `ade --socket app-control status --text`, `ade --socket app-control launch --command \"npm run dev\" --text`, or `ade --socket app-control connect --cdp-port <port> --text`.",
-  "- For App Control terminal/log questions, check `ade --socket app-control status --text`, then prefer `ade --socket app-control logs --text --max-bytes 8388608`, `ade --socket app-control terminal write --data \"y\\n\"`, or `ade --socket app-control terminal signal --signal SIGINT`. Only fall back to `ade --socket terminal list --text` / `terminal read` when no App Control terminal is active.",
-  "- ADE sets `ADE_APP_CONTROL_CDP_PORT` and `ADE_APP_CONTROL_DEBUG_FLAGS` for App Control launches. Custom Electron launchers should forward one of those values to `--remote-debugging-port`.",
-  "- After App Control launch/connect, use `ade --socket app-control snapshot --text` or `elements --text`; use Control mode or `click`/`type` for input; use Inspect mode or `select --x <x> --y <y>` to return screenshot-backed DOM/selector/source context and, when the session is chat-owned, attach it to the drawer chat.",
-  "- For ADE browser work, prefer socket mode so CLI calls and the Work sidebar share the same global browser tabs: `ade help browser`, `ade --socket browser panel --text`, `ade --socket browser status --text`, `ade --socket browser open <url> --new-tab --text`, `ade --socket browser switch --tab <id> --text`, `ade --socket browser screenshot --text`, and `ade --socket browser inspect-start --text` / `ade --socket browser select-current --text` / `ade --socket browser clear-selection --text`. The ADE browser is global rather than lane-scoped; links from chat output and localhost URLs in chat terminals should open there by default.",
-  "- For lane-tied macOS VM work, use `ade help macos-vm`, `ade --socket macos-vm status --lane <lane> --text`, `ade --socket macos-vm start --lane <lane> --create --text`, and `ade --socket macos-vm guide --lane <lane> --text`. To interact through ADE, use `ade --socket macos-vm screenshot --lane <lane> --text`, `ade --socket macos-vm select --lane <lane> --x <x> --y <y> --text`, `ade --socket macos-vm click --lane <lane> <x> <y>`, and `ade --socket macos-vm type --lane <lane> --value <text>`; click/select coordinates are window-relative by default.",
-  "",
-  "### iOS Simulator and Preview Lab",
-  "- For iOS work inside an ADE chat, start with `ade help ios-sim`, `ade --socket ios-sim status --text`, `ade --socket ios-sim devices --text`, and `ade --socket ios-sim apps --device <udid> --text`, then launch with `ade --socket ios-sim launch --target <id> --text`.",
-  "- For iOS launch target problems, do not create symlink projects, fake schemes, or repo-layout shims as the first fix. Re-list `ade --socket ios-sim apps --text`; ADE should discover root-level `.xcodeproj` bundles and `apps/*/*.xcodeproj` projects. If no app appears or the build fails, report the selected project, scheme, and exact build output instead of guessing.",
-  "- After launch, use `ade --socket ios-sim snapshot --text` or `ade --socket ios-sim elements --text` for screenshot + accessibility/ADEInspector grounding. Use `ade --socket ios-sim select --x <x> --y <y>` to return simulator context and, when the session is chat-owned, attach it to the drawer chat. Use `ade --socket ios-sim tap`, `ade --socket ios-sim drag` / `ade --socket ios-sim swipe`, or `ade --socket ios-sim type` against the active app.",
-  "- Stream commands are `ade --socket ios-sim window-start`, `ade --socket ios-sim live-start`, `ade --socket ios-sim preview-start`, `ade --socket ios-sim stream-status`, and `ade --socket ios-sim stream-stop`. Use `ade --socket ios-sim stream-status --text` to explain the active backend/input path, fallback reason, helper pid, latency, and any blocker. Low idle fps is normal on `iosurface-indigo` because frames are event-driven while the simulator is still.",
-  "- For ADE Preview Lab, check `ade --socket ios-sim preview-status --text`, discover existing previews with `ade --socket ios-sim previews --source <swift-file> --text`, and finish with `ade --socket ios-sim preview-render --source <swift-file> --index <n> --text`. Add a preview only when no matching preview already exists.",
-  "- If the simulator is not running or no active session/snapshot is available, warn the user with the exact blocker instead of guessing the screen.",
-  "- When you finish iOS Simulator work, run `ade --socket ios-sim shutdown` when you own the session and the task no longer needs the running simulator.",
+  "### Skills",
+  "- ADE ships Agent Skills for deeper operating details. Use the relevant skill instead of relying on trial and error: `ade-cli-control-plane`, `ade-ios-simulator`, `ade-app-control`, `ade-browser`, `ade-pr-workflows`, `ade-lanes-git`, `ade-cto-missions`, `ade-proof-artifacts`, and `ade-macos-vm`.",
+  "- If skills are not auto-listed by your runtime, look for them in project/user `.agents/skills`, `.ade/skills`, `.claude/skills`, or ADE's bundled `agent-skills` resources, then read that skill's `SKILL.md` on demand.",
   "",
-  "### SwiftUI previewability",
-  "- When changing SwiftUI from simulator or preview context, keep the affected UI previewable: add or repair nearby `#Preview` definitions and deterministic mock fixtures when needed.",
-  "- Preview fixtures should use representative visible UI context when useful, but must not depend on live sync, keychain, network, push, sockets, or a production database.",
-  "- For appearance-sensitive work, add named light/dark preview variants with `.preferredColorScheme(.light)` / `.preferredColorScheme(.dark)` and prefer adaptive system colors.",
-  "- When asked to make a preview reachable in the live simulator, add a DEBUG-only route, deep link, launch-argument handler, or small preview host. ADE may pass optional `ADE_PREVIEW_*` environment values.",
-  "- When an iOS visual inspect packet is attached to chat, ensure the affected source file or a nearby related Swift file contains a renderable `#Preview`/`PreviewProvider`, and add mock data or a preview harness if the screen would otherwise be blank.",
+  "### Socket-backed live surfaces",
+  "- Use `--socket` when the ADE desktop drawer and the CLI must share one live session. This matters for App Control, iOS Simulator, Preview Lab, terminal logs, selection/context capture, and proof drawer updates.",
+  "- Common starts: `ade --socket ios-sim status --text`, `ade --socket app-control status --text`, `ade --socket browser status --text`, and `ade --socket macos-vm status --lane <lane> --text`.",
   "",
   "### Proof and cleanup",
   "- When the user asks you to capture, send, attach, or provide proof, use the appropriate computer-use/browser/app-control tool to produce evidence, then register it with ADE via `ade proof ...` so it appears in the ADE proof drawer for the active chat, mission, or lane.",

From b33388d4cd9ceaa755c3f7c80ee05516e3aba97e Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:21:08 -0400
Subject: [PATCH 05/24] fix(remote): retry sync reads after reconnect

---
 .../remoteConnectionPool.test.ts              | 44 +++++++++++++++++++
 .../remoteRuntime/remoteConnectionPool.ts     | 13 +++---
 2 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.test.ts b/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.test.ts
index 672a59338..80ae3dab9 100644
--- a/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.test.ts
+++ b/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.test.ts
@@ -449,6 +449,50 @@ describe("RemoteConnectionPool", () => {
     });
   });
 
+  it("retries project-scoped sync reads once when the connection closes during the request", async () => {
+    const firstClient = createClient();
+    const firstSsh = createSsh();
+    firstClient.call.mockRejectedValueOnce(
+      new Error("Remote ADE service connection closed."),
+    );
+    bootstrapRemoteRuntimeMock.mockResolvedValueOnce({
+      client: firstClient,
+      ssh: firstSsh,
+      result: connectResult("1.0.0"),
+    });
+    const secondClient = createClient();
+    secondClient.call.mockResolvedValueOnce({
+      pairingPin: "654321",
+      connectedPeers: [{ id: "phone-1" }],
+    });
+    bootstrapRemoteRuntimeMock.mockResolvedValueOnce({
+      client: secondClient,
+      ssh: createSsh(),
+      result: connectResult("1.0.1"),
+    });
+    const pool = new RemoteConnectionPool({} as RemoteTargetRegistry, "1.0.0");
+
+    await expect(
+      pool.callSyncForTarget(target, "project-1", "sync.getStatus", {
+        includeTransferReadiness: true,
+      }),
+    ).resolves.toEqual({
+      pairingPin: "654321",
+      connectedPeers: [{ id: "phone-1" }],
+    });
+
+    expect(firstSsh.end).toHaveBeenCalledTimes(1);
+    expect(bootstrapRemoteRuntimeMock).toHaveBeenCalledTimes(2);
+    expect(firstClient.call).toHaveBeenCalledWith("sync.getStatus", {
+      projectId: "project-1",
+      includeTransferReadiness: true,
+    });
+    expect(secondClient.call).toHaveBeenCalledWith("sync.getStatus", {
+      projectId: "project-1",
+      includeTransferReadiness: true,
+    });
+  });
+
   it("subscribes to runtime event notifications and unsubscribes on cleanup", async () => {
     const client = createClient();
     client.call.mockImplementation(async (method: string) => {
diff --git a/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.ts b/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.ts
index 76718bcac..c93faa4ec 100644
--- a/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.ts
+++ b/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.ts
@@ -142,11 +142,14 @@ export class RemoteConnectionPool {
     method: string,
     params: Record<string, unknown> = {},
   ): Promise<unknown> {
-    const entry = await this.connectEntry(target);
-    return await entry.client.call(method, {
-      ...params,
-      projectId,
-    });
+    return await this.withEntryForTarget(
+      target,
+      (entry) => entry.client.call(method, {
+        ...params,
+        projectId,
+      }),
+      { retryOnConnectionError: true },
+    );
   }
 
   private async addProjectWithEntry(

From 557e6d67ce5860b595d35f371c65af6f5d97f265 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:22:03 -0400
Subject: [PATCH 06/24] perf(prs): avoid snapshot refresh from header reload

---
 apps/desktop/src/renderer/components/prs/PRsPage.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/desktop/src/renderer/components/prs/PRsPage.tsx b/apps/desktop/src/renderer/components/prs/PRsPage.tsx
index 62af7acbc..73d82547a 100644
--- a/apps/desktop/src/renderer/components/prs/PRsPage.tsx
+++ b/apps/desktop/src/renderer/components/prs/PRsPage.tsx
@@ -102,7 +102,7 @@ function PRsPageInner() {
   const handleRefresh = React.useCallback(async () => {
     await Promise.all([
       refresh(),
-      refreshLanes().catch(() => {}),
+      refreshLanes({ includeStatus: false, includeSnapshots: false }).catch(() => {}),
     ]);
     setIntegrationRefreshNonce((prev) => prev + 1);
   }, [refresh, refreshLanes]);

From 228fadbc629411d75daa4dc249e1dfec0f6ee94e Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:23:04 -0400
Subject: [PATCH 07/24] chore(release): gate packaging on ci-pass

---
 .github/workflows/prepare-release.yml   |   2 +
 .github/workflows/release-core.yml      |  32 ++++
 .github/workflows/release.yml           |   2 +
 apps/desktop/resources/ade-cli-help.txt | 186 +++++++++++++++++-------
 4 files changed, 172 insertions(+), 50 deletions(-)

diff --git a/.github/workflows/prepare-release.yml b/.github/workflows/prepare-release.yml
index 10284f389..afbbbb48f 100644
--- a/.github/workflows/prepare-release.yml
+++ b/.github/workflows/prepare-release.yml
@@ -9,6 +9,8 @@ on:
         type: string
 
 permissions:
+  actions: read
+  checks: read
   contents: read
 
 jobs:
diff --git a/.github/workflows/release-core.yml b/.github/workflows/release-core.yml
index eb2b89c46..b503117cd 100644
--- a/.github/workflows/release-core.yml
+++ b/.github/workflows/release-core.yml
@@ -18,6 +18,8 @@ on:
         type: boolean
 
 permissions:
+  actions: read
+  checks: read
   contents: write
 
 jobs:
@@ -34,6 +36,36 @@ jobs:
           git fetch origin main:refs/remotes/origin/main
           git merge-base --is-ancestor HEAD refs/remotes/origin/main
 
+      - name: Ensure CI passed for release commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TARGET_REF: ${{ inputs.target_ref }}
+        run: |
+          set -euo pipefail
+
+          ci_pass_json="$(
+            gh api "repos/$GH_REPO/commits/$TARGET_REF/check-runs" \
+              -f per_page=100 \
+              --paginate \
+              --jq '[.check_runs[] | select(.name == "ci-pass")] | sort_by(.completed_at // "") | last // empty'
+          )"
+
+          if [ -z "$ci_pass_json" ] || [ "$ci_pass_json" = "null" ]; then
+            echo "::error::No ci-pass check run was found for $TARGET_REF. Run CI before releasing."
+            exit 1
+          fi
+
+          status="$(printf '%s' "$ci_pass_json" | jq -r '.status // ""')"
+          conclusion="$(printf '%s' "$ci_pass_json" | jq -r '.conclusion // ""')"
+          url="$(printf '%s' "$ci_pass_json" | jq -r '.html_url // ""')"
+          if [ "$status" != "completed" ] || [ "$conclusion" != "success" ]; then
+            echo "::error::ci-pass for $TARGET_REF is $status/$conclusion. Release packaging requires green CI. $url"
+            exit 1
+          fi
+
+          echo "ci-pass succeeded for $TARGET_REF: $url"
+
   build-mac-release:
     needs:
       - verify
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 2e0c98683..c34da7510 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -16,6 +16,8 @@ on:
         type: string
 
 permissions:
+  actions: read
+  checks: read
   contents: write
 
 jobs:
diff --git a/apps/desktop/resources/ade-cli-help.txt b/apps/desktop/resources/ade-cli-help.txt
index 310a97705..87be9fcf6 100644
--- a/apps/desktop/resources/ade-cli-help.txt
+++ b/apps/desktop/resources/ade-cli-help.txt
@@ -10,17 +10,27 @@ _    ____  _____
 
   Agent-focused command-line interface for ADE.
 
-  ADE CLI commands operate on the same project database and live desktop socket
-  used by the ADE app. By default the CLI connects to the app socket when it is
-  running; otherwise it falls back to a headless runtime for local-safe actions.
+  ADE CLI commands operate through the machine ADE runtime daemon by default.
+  If the daemon is not running, the CLI starts it, registers the selected
+  project, and routes project actions through that runtime.
 
     $ ade help <command...>                         Display help for a command
     $ ade auth status                               Check local ADE CLI readiness
+    $ ade code                                      Open ADE Work chat in the terminal
+    $ ade desktop                                   Launch the installed desktop app
+    $ ade runtime start | stop | status             Manage the machine runtime daemon
+    $ ade serve                                     Run the ADE runtime daemon in foreground
+    $ ade rpc --stdio                               Speak ADE JSON-RPC over stdin/stdout
+    $ ade init [path]                               Register a project with this machine runtime
+    $ ade projects list                             List projects registered on this machine
+    $ ade sync status | pin generate                Manage machine sync and phone pairing
     $ ade doctor                                    Inspect project, socket, runtime, and tool availability
     $ ade lanes list | show | create | child        Work with lanes and lane stacks
     $ ade git status | commit | push | stash        Run ADE-aware git operations
-    $ ade diff changes | file                       Inspect lane diffs
+    $ ade operations status | wait                  Poll operation/test/chat/run/mission status
+    $ ade diff changes | file | patch               Inspect lane diffs (including raw git patch text)
     $ ade files tree | read | write | search        Read and edit lane workspaces
+    $ ade missions launch | watch | graph           Create, start, and inspect mission runs
     $ ade prs list | create | path-to-merge         Manage PRs, queues, and Path to Merge repair rounds
     $ ade run defs | ps | start | logs              Manage Run tab process definitions and runtime
     $ ade shell start | write | resize | close      Launch and control tracked shell sessions
@@ -33,21 +43,23 @@ _    ____  _____
     $ ade coordinator <tool>                        Call coordinator runtime tools
     $ ade tests list | run | stop | runs | logs     Run configured test suites
     $ ade proof status | list | screenshot | record Manage proof and computer-use artifacts
-    $ ade ios-sim devices | apps | launch | tap   Control iOS Simulator apps, capture, and input
-    $ ade app-control launch | snapshot | click   Inspect and drive Electron apps
+    $ ade ios-sim devices | apps | launch | tap    Control iOS Simulator apps, capture, and input
+    $ ade app-control launch | snapshot | click    Inspect and drive Electron apps
+    $ ade macos-vm status | start | guide          Run lane-tied macOS VMs for agent work
     $ ade browser open | tabs | screenshot         Use ADE's built-in browser pane
     $ ade memory add | search | pin                 Use ADE memory
+    $ ade usage snapshot | refresh | budget         Read provider quota usage and edit automation guardrails
     $ ade settings action <method>                  Call project config actions
     $ ade update status | check | install | dismiss Read auto-update state and drive install
-    $ ade actions list | run | status               Escape hatch for every ADE service action
+    $ ade actions list | run | status | wait        Escape hatch for every ADE service action
     $ ade cursor cloud agents | runs | artifacts | repos | models | me
                                                     Drive Cursor Cloud agents via @cursor/sdk
 
   Global options:
     --project-root <path>   ADE project root. Inside .ade/worktrees/<lane>, this resolves to the parent project.
     --workspace-root <path> Lane/worktree to treat as the active workspace.
-    --headless              Skip the desktop socket and run an in-process ADE runtime.
-    --socket                Require the desktop socket; fail instead of falling back to headless.
+    --headless              Skip the runtime daemon and run an in-process ADE runtime.
+    --socket                Require a live ADE socket; fail instead of falling back to headless.
     --json                  Print machine-readable JSON. This is the default output mode.
     --text                  Print a compact human-readable summary when a formatter exists.
     --timeout-ms <ms>       Per-request timeout. Long agent/PR workflows may need several minutes.
@@ -57,14 +69,19 @@ _    ____  _____
     $ ade lanes list --text
     $ ade lanes create --name fix-login --description "Repair login redirect"
     $ ade git status --lane <lane> --text
+    $ ade git status --full --lane <lane> --text
+    $ ade git sync --lane <lane> --rebase --base main
     $ ade git stage --lane <lane> src/index.ts
     $ ade git commit --lane <lane> -m "Fix login redirect"
+    $ ade missions launch --prompt "Fix onboarding" --manual --text
     $ ade prs create --lane <lane> --base main --draft
     $ ade prs path-to-merge <pr-id-or-number-or-url> --model <model> --max-rounds 3 --no-auto-merge
     $ ade proof record --seconds 20
     $ ade ios-sim apps --text
     $ ade ios-sim launch --target <id> --text
     $ ade app-control launch --command "pnpm dev" --text
+    $ ade macos-vm start --lane <lane> --create --text
+    $ ade macos-vm guide --lane <lane> --text
     $ ade --socket browser open http://localhost:5173 --new-tab --text
     $ ade terminal read --chat-session <id> --text
 
@@ -94,17 +111,27 @@ _    ____  _____
 
   Agent-focused command-line interface for ADE.
 
-  ADE CLI commands operate on the same project database and live desktop socket
-  used by the ADE app. By default the CLI connects to the app socket when it is
-  running; otherwise it falls back to a headless runtime for local-safe actions.
+  ADE CLI commands operate through the machine ADE runtime daemon by default.
+  If the daemon is not running, the CLI starts it, registers the selected
+  project, and routes project actions through that runtime.
 
     $ ade help <command...>                         Display help for a command
     $ ade auth status                               Check local ADE CLI readiness
+    $ ade code                                      Open ADE Work chat in the terminal
+    $ ade desktop                                   Launch the installed desktop app
+    $ ade runtime start | stop | status             Manage the machine runtime daemon
+    $ ade serve                                     Run the ADE runtime daemon in foreground
+    $ ade rpc --stdio                               Speak ADE JSON-RPC over stdin/stdout
+    $ ade init [path]                               Register a project with this machine runtime
+    $ ade projects list                             List projects registered on this machine
+    $ ade sync status | pin generate                Manage machine sync and phone pairing
     $ ade doctor                                    Inspect project, socket, runtime, and tool availability
     $ ade lanes list | show | create | child        Work with lanes and lane stacks
     $ ade git status | commit | push | stash        Run ADE-aware git operations
-    $ ade diff changes | file                       Inspect lane diffs
+    $ ade operations status | wait                  Poll operation/test/chat/run/mission status
+    $ ade diff changes | file | patch               Inspect lane diffs (including raw git patch text)
     $ ade files tree | read | write | search        Read and edit lane workspaces
+    $ ade missions launch | watch | graph           Create, start, and inspect mission runs
     $ ade prs list | create | path-to-merge         Manage PRs, queues, and Path to Merge repair rounds
     $ ade run defs | ps | start | logs              Manage Run tab process definitions and runtime
     $ ade shell start | write | resize | close      Launch and control tracked shell sessions
@@ -117,21 +144,23 @@ _    ____  _____
     $ ade coordinator <tool>                        Call coordinator runtime tools
     $ ade tests list | run | stop | runs | logs     Run configured test suites
     $ ade proof status | list | screenshot | record Manage proof and computer-use artifacts
-    $ ade ios-sim devices | apps | launch | tap   Control iOS Simulator apps, capture, and input
-    $ ade app-control launch | snapshot | click   Inspect and drive Electron apps
+    $ ade ios-sim devices | apps | launch | tap    Control iOS Simulator apps, capture, and input
+    $ ade app-control launch | snapshot | click    Inspect and drive Electron apps
+    $ ade macos-vm status | start | guide          Run lane-tied macOS VMs for agent work
     $ ade browser open | tabs | screenshot         Use ADE's built-in browser pane
     $ ade memory add | search | pin                 Use ADE memory
+    $ ade usage snapshot | refresh | budget         Read provider quota usage and edit automation guardrails
     $ ade settings action <method>                  Call project config actions
     $ ade update status | check | install | dismiss Read auto-update state and drive install
-    $ ade actions list | run | status               Escape hatch for every ADE service action
+    $ ade actions list | run | status | wait        Escape hatch for every ADE service action
     $ ade cursor cloud agents | runs | artifacts | repos | models | me
                                                     Drive Cursor Cloud agents via @cursor/sdk
 
   Global options:
     --project-root <path>   ADE project root. Inside .ade/worktrees/<lane>, this resolves to the parent project.
     --workspace-root <path> Lane/worktree to treat as the active workspace.
-    --headless              Skip the desktop socket and run an in-process ADE runtime.
-    --socket                Require the desktop socket; fail instead of falling back to headless.
+    --headless              Skip the runtime daemon and run an in-process ADE runtime.
+    --socket                Require a live ADE socket; fail instead of falling back to headless.
     --json                  Print machine-readable JSON. This is the default output mode.
     --text                  Print a compact human-readable summary when a formatter exists.
     --timeout-ms <ms>       Per-request timeout. Long agent/PR workflows may need several minutes.
@@ -141,14 +170,19 @@ _    ____  _____
     $ ade lanes list --text
     $ ade lanes create --name fix-login --description "Repair login redirect"
     $ ade git status --lane <lane> --text
+    $ ade git status --full --lane <lane> --text
+    $ ade git sync --lane <lane> --rebase --base main
     $ ade git stage --lane <lane> src/index.ts
     $ ade git commit --lane <lane> -m "Fix login redirect"
+    $ ade missions launch --prompt "Fix onboarding" --manual --text
     $ ade prs create --lane <lane> --base main --draft
     $ ade prs path-to-merge <pr-id-or-number-or-url> --model <model> --max-rounds 3 --no-auto-merge
     $ ade proof record --seconds 20
     $ ade ios-sim apps --text
     $ ade ios-sim launch --target <id> --text
     $ ade app-control launch --command "pnpm dev" --text
+    $ ade macos-vm start --lane <lane> --create --text
+    $ ade macos-vm guide --lane <lane> --text
     $ ade --socket browser open http://localhost:5173 --new-tab --text
     $ ade terminal read --chat-session <id> --text
 
@@ -178,17 +212,27 @@ _    ____  _____
 
   Agent-focused command-line interface for ADE.
 
-  ADE CLI commands operate on the same project database and live desktop socket
-  used by the ADE app. By default the CLI connects to the app socket when it is
-  running; otherwise it falls back to a headless runtime for local-safe actions.
+  ADE CLI commands operate through the machine ADE runtime daemon by default.
+  If the daemon is not running, the CLI starts it, registers the selected
+  project, and routes project actions through that runtime.
 
     $ ade help <command...>                         Display help for a command
     $ ade auth status                               Check local ADE CLI readiness
+    $ ade code                                      Open ADE Work chat in the terminal
+    $ ade desktop                                   Launch the installed desktop app
+    $ ade runtime start | stop | status             Manage the machine runtime daemon
+    $ ade serve                                     Run the ADE runtime daemon in foreground
+    $ ade rpc --stdio                               Speak ADE JSON-RPC over stdin/stdout
+    $ ade init [path]                               Register a project with this machine runtime
+    $ ade projects list                             List projects registered on this machine
+    $ ade sync status | pin generate                Manage machine sync and phone pairing
     $ ade doctor                                    Inspect project, socket, runtime, and tool availability
     $ ade lanes list | show | create | child        Work with lanes and lane stacks
     $ ade git status | commit | push | stash        Run ADE-aware git operations
-    $ ade diff changes | file                       Inspect lane diffs
+    $ ade operations status | wait                  Poll operation/test/chat/run/mission status
+    $ ade diff changes | file | patch               Inspect lane diffs (including raw git patch text)
     $ ade files tree | read | write | search        Read and edit lane workspaces
+    $ ade missions launch | watch | graph           Create, start, and inspect mission runs
     $ ade prs list | create | path-to-merge         Manage PRs, queues, and Path to Merge repair rounds
     $ ade run defs | ps | start | logs              Manage Run tab process definitions and runtime
     $ ade shell start | write | resize | close      Launch and control tracked shell sessions
@@ -201,21 +245,23 @@ _    ____  _____
     $ ade coordinator <tool>                        Call coordinator runtime tools
     $ ade tests list | run | stop | runs | logs     Run configured test suites
     $ ade proof status | list | screenshot | record Manage proof and computer-use artifacts
-    $ ade ios-sim devices | apps | launch | tap   Control iOS Simulator apps, capture, and input
-    $ ade app-control launch | snapshot | click   Inspect and drive Electron apps
+    $ ade ios-sim devices | apps | launch | tap    Control iOS Simulator apps, capture, and input
+    $ ade app-control launch | snapshot | click    Inspect and drive Electron apps
+    $ ade macos-vm status | start | guide          Run lane-tied macOS VMs for agent work
     $ ade browser open | tabs | screenshot         Use ADE's built-in browser pane
     $ ade memory add | search | pin                 Use ADE memory
+    $ ade usage snapshot | refresh | budget         Read provider quota usage and edit automation guardrails
     $ ade settings action <method>                  Call project config actions
     $ ade update status | check | install | dismiss Read auto-update state and drive install
-    $ ade actions list | run | status               Escape hatch for every ADE service action
+    $ ade actions list | run | status | wait        Escape hatch for every ADE service action
     $ ade cursor cloud agents | runs | artifacts | repos | models | me
                                                     Drive Cursor Cloud agents via @cursor/sdk
 
   Global options:
     --project-root <path>   ADE project root. Inside .ade/worktrees/<lane>, this resolves to the parent project.
     --workspace-root <path> Lane/worktree to treat as the active workspace.
-    --headless              Skip the desktop socket and run an in-process ADE runtime.
-    --socket                Require the desktop socket; fail instead of falling back to headless.
+    --headless              Skip the runtime daemon and run an in-process ADE runtime.
+    --socket                Require a live ADE socket; fail instead of falling back to headless.
     --json                  Print machine-readable JSON. This is the default output mode.
     --text                  Print a compact human-readable summary when a formatter exists.
     --timeout-ms <ms>       Per-request timeout. Long agent/PR workflows may need several minutes.
@@ -225,14 +271,19 @@ _    ____  _____
     $ ade lanes list --text
     $ ade lanes create --name fix-login --description "Repair login redirect"
     $ ade git status --lane <lane> --text
+    $ ade git status --full --lane <lane> --text
+    $ ade git sync --lane <lane> --rebase --base main
     $ ade git stage --lane <lane> src/index.ts
     $ ade git commit --lane <lane> -m "Fix login redirect"
+    $ ade missions launch --prompt "Fix onboarding" --manual --text
     $ ade prs create --lane <lane> --base main --draft
     $ ade prs path-to-merge <pr-id-or-number-or-url> --model <model> --max-rounds 3 --no-auto-merge
     $ ade proof record --seconds 20
     $ ade ios-sim apps --text
     $ ade ios-sim launch --target <id> --text
     $ ade app-control launch --command "pnpm dev" --text
+    $ ade macos-vm start --lane <lane> --create --text
+    $ ade macos-vm guide --lane <lane> --text
     $ ade --socket browser open http://localhost:5173 --new-tab --text
     $ ade terminal read --chat-session <id> --text
 
@@ -269,6 +320,7 @@ _    ____  _____
     $ ade lanes show <lane> --text                  Inspect one lane status
     $ ade lanes create --name <name>                Create a lane from the current project context
     $ ade lanes create --linear-issue-json '{...}'  Create a lane linked to a Linear issue
+    $ ade lanes create --branch-name <branch>       Override the auto-generated branch name
     $ ade lanes child --lane <parent> --name <name> Create a child lane under a parent
     $ ade lanes import --branch <branch>            Register an existing branch/worktree
     $ ade lanes archive <lane>                      Archive a lane in ADE
@@ -289,15 +341,24 @@ _    ____  _____
   refresh lane state. Use --lane for anything other than the active workspace.
 
     $ ade git status --lane <lane> --text           Show ADE-aware sync status
+    $ ade git status --full --lane <lane> --text    Show full lane status, diff, and conflict state
+    $ ade git fetch --lane <lane>                   Fetch remote refs
+    $ ade git pull --lane <lane>                    Pull with ADE's ff-only lane operation
+    $ ade git sync --lane <lane> --rebase --base main
+                                                    Sync the lane with its base branch
     $ ade git stage --lane <lane> src/file.ts       Stage one file
     $ ade git stage-all --lane <lane>               Stage all current changes
     $ ade git unstage --lane <lane> src/file.ts     Unstage one file
     $ ade git commit --lane <lane> [-m <message>]   Commit, adding Refs <issue-id> on linked Linear lanes
     $ ade git push --lane <lane> --set-upstream     Push through ADE
+    $ ade git push --lane <lane> --force-with-lease Force-push through ADE with lease
     $ ade git branches --lane <lane> --text         List branches with last-commit metadata
     $ ade git user-identity --lane <lane> --text    Read lane checkout's git user.name/email
     $ ade git stash push|list|apply|pop             Use ADE lane stash actions
     $ ade git rebase --lane <lane> --ai             Rebase with ADE conflict support
+    $ ade git rebase continue --lane <lane>         Continue an in-progress rebase
+    $ ade git conflict show --lane <lane> --text    Inspect merge/rebase conflict state
+    $ ade git conflict resolve --kind rebase        Continue after manual conflict resolution
     $ ade diff changes --lane <lane> --text         Inspect changed files
 
 ## ade diff --help
@@ -310,7 +371,8 @@ _    ____  _____
   Diffs
 
     $ ade diff changes --lane <lane> --text         Summarize staged/unstaged file changes
-    $ ade diff file --lane <lane> <path> --text     Show one file diff
+    $ ade diff file --lane <lane> <path> --text     Show one file diff (side-by-side text)
+    $ ade diff patch --lane <lane> <path> --text    Raw unified diff / patch for one file
     $ ade diff file --mode staged <path>            Inspect staged diff for one file
     $ ade diff actions --text                       List diff service actions
 
@@ -372,8 +434,8 @@ _    ____  _____
 
   Run tab
 
-  Run tab commands mirror ADE desktop process definitions and runtime state.
-  They require the desktop socket when live process state is needed.
+  Run tab commands mirror ADE process definitions and runtime state. They use
+  the machine runtime daemon when live process state is needed.
 
     $ ade run defs --text                           List configured run commands
     $ ade run ps --lane <lane> --text               List process runtime state
@@ -397,6 +459,8 @@ _    ____  _____
 
     $ ade shell start --lane <lane> -- npm test     Start a tracked shell session
     $ ade shell start --lane <lane> -c "npm test"   Start with a command string
+    $ ade shell start-cli codex --lane <lane> --permission-mode edit
+    $ ade shell start --provider claude --lane <lane> --message "fix tests"
     $ ade shell start --lane <lane> --chat-session <id> -c "npm test"
     $ ade shell write <pty-id> --data "q"           Write data to a PTY
     $ ade shell resize <pty-id> --cols 120 --rows 36
@@ -412,7 +476,7 @@ _    ____  _____
   Chat terminal
 
   Terminal commands control the active in-chat terminal for an ADE chat. Use
-  desktop socket mode when you want the same terminal the user sees in the app.
+  attached runtime mode when you want the same terminal the app is viewing.
 
     $ ade terminal list --chat-session <id> --text  List terminals for a chat
     $ ade terminal active --chat-session <id> --text Show the active chat terminal
@@ -431,13 +495,13 @@ _    ____  _____
   Work chats
 
   Chat commands use ADE agent chat sessions. Live provider-backed chat normally
-  requires the desktop socket because the app owns provider/session state.
+  requires an attached runtime because the daemon owns provider/session state.
 
     $ ade chat list --text                          List chat sessions
     $ ade chat create --lane <lane> --provider codex --model <model> [--fast]
     $ ade chat send <session> --text "next step"    Send a message
     $ ade chat interrupt <session>                  Stop an active turn
-    $ ade chat resume <session>                     Resume a session
+    $ ade chat slash <session> --text               List slash commands for a session
     $ ade agent spawn --lane <lane> --prompt "fix"  Start a new agent work session
 
 ## ade agent --help
@@ -479,7 +543,10 @@ _    ____  _____
 
   Linear workflows
 
-    $ ade linear quick-view --text                 Show connected workspace, projects, and issues
+    $ ade --role cto linear quick-view --text      Show connected workspace, projects, and issues
+    $ ade --role cto linear picker-data --text     Read projects/users/states for the issue picker
+    $ ade --role cto linear search-issues --query "auth" --state-type started,unstarted --first 50
+                                                    Search issues for the lane Linear-issue picker
     $ ade linear workflows --text                   List configured workflows
     $ ade linear sync dashboard --text              Show sync dashboard
     $ ade linear sync run                           Trigger a sync run
@@ -502,13 +569,15 @@ _    ____  _____
     $ ade automations update <id> --from-file <path>
     $ ade automations delete <id>                   Remove a local rule
     $ ade automations toggle <id> --enabled true|false
-    $ ade automations run <id> [--dry-run]          Trigger a rule manually
+    $ ade automations run <id> [--lane <id>] [--dry-run]
+    $ ade automations trigger <id> [--lane <id>]
+                                                     Trigger a rule manually
     $ ade automations runs [--rule <id>] [--status <s>] [--limit 50]
     $ ade automations run-show <runId> [--json]     Inspect a run
     $ ade automations example                       Print an example rule (stdout)
 
   Lane mode flags (apply to create/update on top of --from-file/--stdin/--text):
-    --lane-mode <create|reuse>                      Spawn a new lane per run, or reuse one
+    --lane-mode <create|reuse|require-on-trigger>   Create, reuse, or require lane at trigger time
     --lane <id>                                     Target lane (only with --lane-mode reuse)
     --lane-name-preset <issue-title|issue-num-title|pr-title-author|custom>
     --lane-name-template <string>                   Template (only with preset custom)
@@ -577,8 +646,8 @@ _    ____  _____
   Prefer screenshots/images, screen recordings, and browser captures/traces.
   Console logs are supporting diagnostics, not a replacement for visual proof.
   Local screenshot/video fallback is macOS-only and runs headless by default
-  unless --socket is explicitly requested. Desktop socket mode has the best
-  parity for UI-owned proof state.
+  unless --socket is explicitly requested. Runtime socket mode has the best
+  parity for shared proof state.
 
     $ ade proof status --text                       Show proof backend capabilities
     $ ade proof list --text                         List captured artifacts
@@ -599,7 +668,7 @@ _    ____  _____
 
   iOS simulator commands build, launch, mirror, inspect, and control the ADE
   drawer simulator. Aliases: `ade ios` and `ade simulator` route to the same
-  surface. For drawer/shared session state, prefer desktop socket mode
+  surface. For drawer/shared session state, prefer runtime socket mode
   (--socket) so launch/select/tap operate on the same long-lived ADE service.
   Launch is headless by default; use --foreground only when you
   need the native Simulator window in front. idb is optional for direct
@@ -641,7 +710,7 @@ _    ____  _____
     $ ade ios-sim stream-stop                      Stop preview/live streaming (stopStream)
 
   Input and selection:
-    $ ade --socket ios-sim select --x 120 --y 420  Add UI context to drawer chat (selectPoint)
+    $ ade --socket ios-sim select --x 120 --y 420  Return/select simulator UI context (chat-owned sessions auto-attach)
     $ ade ios-sim tap 120 420                      Tap active simulator app (tap)
     $ ade ios-sim drag 120 700 120 250             Drag active simulator app (drag)
     $ ade ios-sim swipe 120 700 120 250            Swipe active simulator app (swipe)
@@ -695,7 +764,7 @@ _    ____  _____
     $ ade app-control screenshot --text            Capture the active renderer screenshot
     $ ade app-control snapshot --text              Screenshot + DOM element refs
     $ ade app-control inspect --x 120 --y 420      Hit-test a point without committing context
-    $ ade app-control select --x 120 --y 420       Add selected app context to the drawer chat
+    $ ade app-control select --x 120 --y 420       Return/select app context (chat-owned sessions auto-attach)
 
   Input:
     $ ade app-control click 120 420                Click screenshot coordinates
@@ -773,17 +842,27 @@ _    ____  _____
 
   Agent-focused command-line interface for ADE.
 
-  ADE CLI commands operate on the same project database and live desktop socket
-  used by the ADE app. By default the CLI connects to the app socket when it is
-  running; otherwise it falls back to a headless runtime for local-safe actions.
+  ADE CLI commands operate through the machine ADE runtime daemon by default.
+  If the daemon is not running, the CLI starts it, registers the selected
+  project, and routes project actions through that runtime.
 
     $ ade help <command...>                         Display help for a command
     $ ade auth status                               Check local ADE CLI readiness
+    $ ade code                                      Open ADE Work chat in the terminal
+    $ ade desktop                                   Launch the installed desktop app
+    $ ade runtime start | stop | status             Manage the machine runtime daemon
+    $ ade serve                                     Run the ADE runtime daemon in foreground
+    $ ade rpc --stdio                               Speak ADE JSON-RPC over stdin/stdout
+    $ ade init [path]                               Register a project with this machine runtime
+    $ ade projects list                             List projects registered on this machine
+    $ ade sync status | pin generate                Manage machine sync and phone pairing
     $ ade doctor                                    Inspect project, socket, runtime, and tool availability
     $ ade lanes list | show | create | child        Work with lanes and lane stacks
     $ ade git status | commit | push | stash        Run ADE-aware git operations
-    $ ade diff changes | file                       Inspect lane diffs
+    $ ade operations status | wait                  Poll operation/test/chat/run/mission status
+    $ ade diff changes | file | patch               Inspect lane diffs (including raw git patch text)
     $ ade files tree | read | write | search        Read and edit lane workspaces
+    $ ade missions launch | watch | graph           Create, start, and inspect mission runs
     $ ade prs list | create | path-to-merge         Manage PRs, queues, and Path to Merge repair rounds
     $ ade run defs | ps | start | logs              Manage Run tab process definitions and runtime
     $ ade shell start | write | resize | close      Launch and control tracked shell sessions
@@ -796,21 +875,23 @@ _    ____  _____
     $ ade coordinator <tool>                        Call coordinator runtime tools
     $ ade tests list | run | stop | runs | logs     Run configured test suites
     $ ade proof status | list | screenshot | record Manage proof and computer-use artifacts
-    $ ade ios-sim devices | apps | launch | tap   Control iOS Simulator apps, capture, and input
-    $ ade app-control launch | snapshot | click   Inspect and drive Electron apps
+    $ ade ios-sim devices | apps | launch | tap    Control iOS Simulator apps, capture, and input
+    $ ade app-control launch | snapshot | click    Inspect and drive Electron apps
+    $ ade macos-vm status | start | guide          Run lane-tied macOS VMs for agent work
     $ ade browser open | tabs | screenshot         Use ADE's built-in browser pane
     $ ade memory add | search | pin                 Use ADE memory
+    $ ade usage snapshot | refresh | budget         Read provider quota usage and edit automation guardrails
     $ ade settings action <method>                  Call project config actions
     $ ade update status | check | install | dismiss Read auto-update state and drive install
-    $ ade actions list | run | status               Escape hatch for every ADE service action
+    $ ade actions list | run | status | wait        Escape hatch for every ADE service action
     $ ade cursor cloud agents | runs | artifacts | repos | models | me
                                                     Drive Cursor Cloud agents via @cursor/sdk
 
   Global options:
     --project-root <path>   ADE project root. Inside .ade/worktrees/<lane>, this resolves to the parent project.
     --workspace-root <path> Lane/worktree to treat as the active workspace.
-    --headless              Skip the desktop socket and run an in-process ADE runtime.
-    --socket                Require the desktop socket; fail instead of falling back to headless.
+    --headless              Skip the runtime daemon and run an in-process ADE runtime.
+    --socket                Require a live ADE socket; fail instead of falling back to headless.
     --json                  Print machine-readable JSON. This is the default output mode.
     --text                  Print a compact human-readable summary when a formatter exists.
     --timeout-ms <ms>       Per-request timeout. Long agent/PR workflows may need several minutes.
@@ -820,14 +901,19 @@ _    ____  _____
     $ ade lanes list --text
     $ ade lanes create --name fix-login --description "Repair login redirect"
     $ ade git status --lane <lane> --text
+    $ ade git status --full --lane <lane> --text
+    $ ade git sync --lane <lane> --rebase --base main
     $ ade git stage --lane <lane> src/index.ts
     $ ade git commit --lane <lane> -m "Fix login redirect"
+    $ ade missions launch --prompt "Fix onboarding" --manual --text
     $ ade prs create --lane <lane> --base main --draft
     $ ade prs path-to-merge <pr-id-or-number-or-url> --model <model> --max-rounds 3 --no-auto-merge
     $ ade proof record --seconds 20
     $ ade ios-sim apps --text
     $ ade ios-sim launch --target <id> --text
     $ ade app-control launch --command "pnpm dev" --text
+    $ ade macos-vm start --lane <lane> --create --text
+    $ ade macos-vm guide --lane <lane> --text
     $ ade --socket browser open http://localhost:5173 --new-tab --text
     $ ade terminal read --chat-session <id> --text
 

From 60f60578bfb81d5831d424093327a92fabf2f5e0 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:33:25 -0400
Subject: [PATCH 08/24] perf(boot): defer header runtime status reads

boot.open-project fitness 902.72 -> 53.71; localRuntime.callAction p95 2025ms -> 97ms; slow IPC channels 2 -> 0.
---
 .../renderer/components/app/TopBar.test.tsx   | 104 ++++++++++++------
 .../src/renderer/components/app/TopBar.tsx    |  51 ++++++---
 .../components/usage/HeaderUsageControl.tsx   |  48 ++++----
 3 files changed, 136 insertions(+), 67 deletions(-)

diff --git a/apps/desktop/src/renderer/components/app/TopBar.test.tsx b/apps/desktop/src/renderer/components/app/TopBar.test.tsx
index aa97101c6..bba09ebae 100644
--- a/apps/desktop/src/renderer/components/app/TopBar.test.tsx
+++ b/apps/desktop/src/renderer/components/app/TopBar.test.tsx
@@ -143,6 +143,14 @@ function fireProjectTabDragEnd(
   fireEvent(element, event);
 }
 
+async function advancePhoneSyncStartupDelay() {
+  await act(async () => {
+    vi.advanceTimersByTime(5_000);
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+}
+
 describe("TopBar", () => {
   const originalAde = globalThis.window.ade;
 
@@ -360,24 +368,32 @@ describe("TopBar", () => {
   });
 
   it("opens the phone sync drawer from the host status control", async () => {
-    render(<TopBar />);
+    vi.useFakeTimers();
+    try {
+      render(<TopBar />);
 
-    expect(await screen.findByText("1 phone connected to ADE Desktop")).toBeTruthy();
+      expect(screen.getByText("Phone sync")).toBeTruthy();
+      expect(globalThis.window.ade.sync.getStatus).not.toHaveBeenCalled();
 
-    fireEvent.click(screen.getByTitle("Connect a phone to this machine"));
+      await advancePhoneSyncStartupDelay();
+      expect(screen.getByText("1 phone connected to ADE Desktop")).toBeTruthy();
 
-    expect(screen.getByText("Connect to the ADE mobile app")).toBeTruthy();
-    expect(screen.getByTestId("sync-devices-section")).toBeTruthy();
-    expect(screen.getByTitle("Connect a phone to this machine").getAttribute("aria-expanded")).toBe("true");
+      fireEvent.click(screen.getByTitle("Connect a phone to this machine"));
 
-    fireEvent.click(screen.getByTitle("Close phone sync"));
+      expect(screen.getByText("Connect to the ADE mobile app")).toBeTruthy();
+      expect(screen.getByTestId("sync-devices-section")).toBeTruthy();
+      expect(screen.getByTitle("Connect a phone to this machine").getAttribute("aria-expanded")).toBe("true");
+
+      fireEvent.click(screen.getByTitle("Close phone sync"));
 
-    await waitFor(() => {
       expect(screen.queryByTestId("sync-devices-section")).toBeNull();
-    });
+    } finally {
+      vi.useRealTimers();
+    }
   });
 
   it("refreshes the phone sync label from global sync events", async () => {
+    vi.useFakeTimers();
     let syncEventHandler: ((event: any) => void) | null = null;
     const getStatus = vi.fn()
       .mockResolvedValueOnce(makeSyncSnapshot({ connectedPeers: [] }));
@@ -389,25 +405,31 @@ describe("TopBar", () => {
       };
     }) as any;
 
-    render(<TopBar />);
+    try {
+      render(<TopBar />);
 
-    expect(await screen.findByText("Phone sync ready")).toBeTruthy();
+      await advancePhoneSyncStartupDelay();
+      expect(screen.getByText("Phone sync ready")).toBeTruthy();
 
-    await act(async () => {
-      syncEventHandler?.({
-        type: "sync-status",
-        snapshot: makeSyncSnapshot({
-          connectedPeers: [
-            { deviceId: "phone-1", deviceName: "Arul iPhone", platform: "iOS", deviceType: "phone" },
-          ],
-        }),
+      await act(async () => {
+        syncEventHandler?.({
+          type: "sync-status",
+          snapshot: makeSyncSnapshot({
+            connectedPeers: [
+              { deviceId: "phone-1", deviceName: "Arul iPhone", platform: "iOS", deviceType: "phone" },
+            ],
+          }),
+        });
       });
-    });
 
-    expect(await screen.findByText("1 phone connected to ADE Desktop")).toBeTruthy();
+      expect(screen.getByText("1 phone connected to ADE Desktop")).toBeTruthy();
+    } finally {
+      vi.useRealTimers();
+    }
   });
 
   it("labels disabled local runtime sync as unavailable", async () => {
+    vi.useFakeTimers();
     const snapshot = makeSyncSnapshot();
     globalThis.window.ade.sync.getStatus = vi.fn(async () => makeSyncSnapshot({
       connectedPeers: [],
@@ -420,10 +442,15 @@ describe("TopBar", () => {
       },
     })) as any;
 
-    render(<TopBar />);
+    try {
+      render(<TopBar />);
 
-    expect(await screen.findByText("Phone sync unavailable")).toBeTruthy();
-    expect(screen.queryByText("Phone sync ready")).toBeNull();
+      await advancePhoneSyncStartupDelay();
+      expect(screen.getByText("Phone sync unavailable")).toBeTruthy();
+      expect(screen.queryByText("Phone sync ready")).toBeNull();
+    } finally {
+      vi.useRealTimers();
+    }
   });
 
   it("does not refresh phone sync status on an idle interval", async () => {
@@ -438,7 +465,7 @@ describe("TopBar", () => {
         await Promise.resolve();
       });
 
-      expect(getStatus).toHaveBeenCalledTimes(1);
+      expect(getStatus).not.toHaveBeenCalled();
 
       await act(async () => {
         vi.advanceTimersByTime(15_000);
@@ -452,21 +479,34 @@ describe("TopBar", () => {
   });
 
   it("refreshes phone sync status when the window regains focus", async () => {
+    vi.useFakeTimers();
     const getStatus = vi.fn()
       .mockResolvedValueOnce(makeSyncSnapshot({ connectedPeers: [] }))
       .mockResolvedValueOnce(makeSyncSnapshot());
     globalThis.window.ade.sync.getStatus = getStatus as any;
 
-    render(<TopBar />);
+    try {
+      render(<TopBar />);
 
-    expect(await screen.findByText("Phone sync ready")).toBeTruthy();
+      await act(async () => {
+        window.dispatchEvent(new Event("focus"));
+        await Promise.resolve();
+        await Promise.resolve();
+      });
 
-    await act(async () => {
-      window.dispatchEvent(new Event("focus"));
-    });
+      expect(screen.getByText("Phone sync ready")).toBeTruthy();
+
+      await act(async () => {
+        window.dispatchEvent(new Event("focus"));
+        await Promise.resolve();
+        await Promise.resolve();
+      });
 
-    expect(await screen.findByText("1 phone connected to ADE Desktop")).toBeTruthy();
-    expect(getStatus).toHaveBeenCalledTimes(2);
+      expect(screen.getByText("1 phone connected to ADE Desktop")).toBeTruthy();
+      expect(getStatus).toHaveBeenCalledTimes(2);
+    } finally {
+      vi.useRealTimers();
+    }
   });
 
   it("opens Linear quick view and creates a linked lane from an issue", async () => {
diff --git a/apps/desktop/src/renderer/components/app/TopBar.tsx b/apps/desktop/src/renderer/components/app/TopBar.tsx
index b5973da0f..7227922c7 100644
--- a/apps/desktop/src/renderer/components/app/TopBar.tsx
+++ b/apps/desktop/src/renderer/components/app/TopBar.tsx
@@ -66,6 +66,7 @@ const projectIconCache = new Map<string, ProjectIcon>();
 const PROJECT_ICON_ACCENT_CACHE_MAX = 48;
 const projectIconAccentCache = new Map<string, string | null>();
 const RECENT_PROJECTS_CACHE_TTL_MS = 2_500;
+const PHONE_SYNC_STARTUP_DELAY_MS = 5_000;
 let recentProjectsCache:
   | { rows: RecentProjectSummary[]; fetchedAtMs: number }
   | null = null;
@@ -690,6 +691,7 @@ export function TopBar() {
   const connectedRemoteCount = remoteSnapshot?.connectedCount ?? 0;
   const remoteButtonLabel =
     connectedRemoteCount > 0 ? `Remote ${connectedRemoteCount}` : "Remote";
+  const showSyncControl = workspaceProjectOpen;
 
   const applyZoom = useCallback((pct: number) => {
     const clamped = Math.max(MIN_ZOOM_LEVEL, Math.min(MAX_ZOOM_LEVEL, pct));
@@ -852,6 +854,9 @@ export function TopBar() {
   useEffect(() => {
     let cancelled = false;
     let statusRequestVersion = 0;
+    let started = false;
+    let startupTimer: number | null = null;
+    let disposeSyncEvents: (() => void) | null = null;
     if (!project?.rootPath || remoteBinding) {
       setSyncSnapshot(null);
       setPhoneSyncOpen(false);
@@ -873,24 +878,40 @@ export function TopBar() {
         });
     };
     setSyncSnapshot(null);
-    refreshSyncStatus();
-    window.addEventListener("focus", refreshSyncStatus);
-    const dispose = window.ade.sync.onEvent((event) => {
-      if (!cancelled && event.type === "sync-status") {
-        statusRequestVersion += 1;
-        setSyncSnapshot(event.snapshot);
+    const startSyncStatus = () => {
+      if (cancelled || started) return;
+      started = true;
+      refreshSyncStatus();
+      disposeSyncEvents = window.ade.sync.onEvent((event) => {
+        if (!cancelled && event.type === "sync-status") {
+          statusRequestVersion += 1;
+          setSyncSnapshot(event.snapshot);
+        }
+      });
+    };
+    const onFocus = () => {
+      if (started) {
+        refreshSyncStatus();
+      } else {
+        startSyncStatus();
       }
-    });
+    };
+    startupTimer = window.setTimeout(
+      startSyncStatus,
+      phoneSyncOpen ? 0 : PHONE_SYNC_STARTUP_DELAY_MS,
+    );
+    window.addEventListener("focus", onFocus);
     return () => {
       cancelled = true;
-      window.removeEventListener("focus", refreshSyncStatus);
-      dispose();
+      if (startupTimer != null) window.clearTimeout(startupTimer);
+      window.removeEventListener("focus", onFocus);
+      disposeSyncEvents?.();
     };
     // Background projects don't broadcast sync-status events (main.ts filters
     // them to the active project), so we re-run this effect on rootPath change
-    // to force an immediate refetch. Focus refresh covers state changes that
-    // happen while ADE is not active.
-  }, [project?.rootPath, remoteBinding]);
+    // and let the delayed startup check pick up the current state. Focus and
+    // explicit drawer opens still refresh immediately.
+  }, [phoneSyncOpen, project?.rootPath, remoteBinding]);
 
   const checkForActiveWorkloads = useCallback(
     async (projectRootPath: string): Promise<boolean> => {
@@ -1334,7 +1355,7 @@ export function TopBar() {
     [],
   );
 
-  const syncLabel = deriveSyncLabel(syncSnapshot);
+  const syncLabel = deriveSyncLabel(syncSnapshot) ?? "Phone sync";
   const transitionTargetName = projectTransition?.rootPath
     ? (projectTabs.find(
         (entry) => entry.rootPath === projectTransition.rootPath,
@@ -1832,7 +1853,7 @@ export function TopBar() {
         {remoteButtonLabel}
       </button>
 
-      {syncSnapshot && syncLabel ? (
+      {showSyncControl ? (
         <button
           type="button"
           className={cn(
@@ -1853,7 +1874,7 @@ export function TopBar() {
           <span
             className={cn(
               "ade-status-dot h-1.5 w-1.5 shrink-0",
-              syncDotClass(syncSnapshot),
+              syncSnapshot ? syncDotClass(syncSnapshot) : "bg-white/30",
             )}
           />
           {syncLabel}
diff --git a/apps/desktop/src/renderer/components/usage/HeaderUsageControl.tsx b/apps/desktop/src/renderer/components/usage/HeaderUsageControl.tsx
index 51c6e9288..08332b512 100644
--- a/apps/desktop/src/renderer/components/usage/HeaderUsageControl.tsx
+++ b/apps/desktop/src/renderer/components/usage/HeaderUsageControl.tsx
@@ -45,6 +45,7 @@ function weeklyPercentFor(snapshot: UsageSnapshot | null, provider: UsageProvide
 }
 
 const OPEN_USAGE_EVENT = "ade-open-usage-drawer";
+const HEADER_USAGE_STARTUP_DELAY_MS = 5_000;
 
 export function HeaderUsageControl() {
   const [open, setOpen] = useState(false);
@@ -56,43 +57,50 @@ export function HeaderUsageControl() {
   const [guardrailsOpen, setGuardrailsOpen] = useState(false);
   const panelRef = useRef<HTMLDivElement | null>(null);
 
-  // Initial snapshot + live updates (always subscribed so the button reflects
-  // the latest poll whether or not the drawer is open).
+  // Delay background usage reads during project boot, but hydrate immediately
+  // when the drawer is opened.
   useEffect(() => {
     if (!window.ade?.usage) return;
     let cancelled = false;
-    window.ade.usage.getSnapshot()
-      .then((nextSnapshot) => {
-        if (!cancelled) setSnapshot(nextSnapshot);
-      })
-      .catch(() => {
-        if (!cancelled) setSnapshot(null);
+    let unsubscribe: (() => void) | undefined;
+    const timer = window.setTimeout(() => {
+      window.ade.usage.getSnapshot()
+        .then((nextSnapshot) => {
+          if (!cancelled) setSnapshot(nextSnapshot);
+        })
+        .catch(() => {
+          if (!cancelled) setSnapshot(null);
+        });
+      unsubscribe = window.ade.usage.onUpdate?.((next) => {
+        if (!cancelled) setSnapshot(next);
       });
-    const unsubscribe = window.ade.usage.onUpdate?.((next) => {
-      if (!cancelled) setSnapshot(next);
-    });
+    }, open ? 0 : HEADER_USAGE_STARTUP_DELAY_MS);
     return () => {
       cancelled = true;
+      window.clearTimeout(timer);
       unsubscribe?.();
     };
-  }, []);
+  }, [open]);
 
   // Fetch provider connection status so we can hide providers whose CLI is
   // not installed on this machine.
   useEffect(() => {
     if (!window.ade?.ai?.getStatus) return;
     let cancelled = false;
-    window.ade.ai.getStatus()
-      .then((status) => {
-        if (!cancelled) setProviderConnections(status.providerConnections ?? null);
-      })
-      .catch(() => {
-        if (!cancelled) setProviderConnections(null);
-      });
+    const timer = window.setTimeout(() => {
+      window.ade.ai.getStatus()
+        .then((status) => {
+          if (!cancelled) setProviderConnections(status.providerConnections ?? null);
+        })
+        .catch(() => {
+          if (!cancelled) setProviderConnections(null);
+        });
+    }, open ? 0 : HEADER_USAGE_STARTUP_DELAY_MS);
     return () => {
       cancelled = true;
+      window.clearTimeout(timer);
     };
-  }, []);
+  }, [open]);
 
   // Listen for programmatic open requests (used by the threshold toast).
   useEffect(() => {

From b94eec1883acb54b7be41abdadc4bd6947e237f9 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:35:52 -0400
Subject: [PATCH 09/24] fix(tui): scope ade code persisted state by project

Prevents last lane/chat choices from one project influencing another when lane ids overlap. Keeps legacy global keys as migration fallback.
---
 .../tuiClient/__tests__/connection.test.ts    |  6 ++
 .../src/tuiClient/__tests__/state.test.ts     | 64 +++++++++++++
 apps/ade-cli/src/tuiClient/app.tsx            | 10 +-
 apps/ade-cli/src/tuiClient/state.ts           | 92 ++++++++++++++++---
 4 files changed, 153 insertions(+), 19 deletions(-)
 create mode 100644 apps/ade-cli/src/tuiClient/__tests__/state.test.ts

diff --git a/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts b/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts
index 178d68d06..b27f51d62 100644
--- a/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts
+++ b/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts
@@ -539,7 +539,9 @@ describe("ade-code TUI state", () => {
     const { loadAdeCodeState } = await loadStateModule(home);
     expect(loadAdeCodeState()).toEqual({
       lastChatByLane: { "lane-1": "chat-1" },
+      lastChatByProjectLane: {},
       lastLaneId: null,
+      lastLaneByProject: {},
     });
   });
 
@@ -549,12 +551,16 @@ describe("ade-code TUI state", () => {
 
     saveAdeCodeState({
       lastChatByLane: { "lane-2": "chat-9" },
+      lastChatByProjectLane: {},
       lastLaneId: "lane-2",
+      lastLaneByProject: {},
     });
 
     expect(loadAdeCodeState()).toEqual({
       lastChatByLane: { "lane-2": "chat-9" },
+      lastChatByProjectLane: {},
       lastLaneId: "lane-2",
+      lastLaneByProject: {},
     });
   });
 });
diff --git a/apps/ade-cli/src/tuiClient/__tests__/state.test.ts b/apps/ade-cli/src/tuiClient/__tests__/state.test.ts
new file mode 100644
index 000000000..be240cc49
--- /dev/null
+++ b/apps/ade-cli/src/tuiClient/__tests__/state.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { normalizeAdeCodeState, scopedAdeCodeState } from "../state";
+
+describe("ade code persisted state", () => {
+  it("prefers project-scoped lane and chat state over legacy global fallback", () => {
+    const state = normalizeAdeCodeState({
+      lastChatByLane: { main: "legacy-chat" },
+      lastLaneId: "legacy-lane",
+      lastChatByProjectLane: {
+        "/repo-a": { main: "repo-a-chat" },
+        "/repo-b": { main: "repo-b-chat" },
+      },
+      lastLaneByProject: {
+        "/repo-a": "repo-a-lane",
+        "/repo-b": "repo-b-lane",
+      },
+    });
+
+    expect(scopedAdeCodeState(state, "/repo-b")).toEqual({
+      lastChatByLane: { main: "repo-b-chat" },
+      lastLaneId: "repo-b-lane",
+    });
+  });
+
+  it("uses legacy state as a migration fallback for projects without scoped entries", () => {
+    const state = normalizeAdeCodeState({
+      lastChatByLane: { main: "legacy-chat" },
+      lastLaneId: "legacy-lane",
+      lastChatByProjectLane: {
+        "/repo-a": { main: "repo-a-chat" },
+      },
+      lastLaneByProject: {
+        "/repo-a": "repo-a-lane",
+      },
+    });
+
+    expect(scopedAdeCodeState(state, "/repo-b")).toEqual({
+      lastChatByLane: { main: "legacy-chat" },
+      lastLaneId: "legacy-lane",
+    });
+  });
+
+  it("ignores malformed persisted records", () => {
+    const state = normalizeAdeCodeState({
+      lastChatByLane: { main: "legacy-chat", bad: 1 },
+      lastLaneId: 7,
+      lastChatByProjectLane: {
+        "/repo-a": { main: "repo-a-chat", bad: false },
+        "/empty": { bad: false },
+      },
+      lastLaneByProject: {
+        "/repo-a": "repo-a-lane",
+        "/repo-b": null,
+      },
+    });
+
+    expect(state).toEqual({
+      lastChatByLane: { main: "legacy-chat" },
+      lastChatByProjectLane: { "/repo-a": { main: "repo-a-chat" } },
+      lastLaneId: null,
+      lastLaneByProject: { "/repo-a": "repo-a-lane" },
+    });
+  });
+});
diff --git a/apps/ade-cli/src/tuiClient/app.tsx b/apps/ade-cli/src/tuiClient/app.tsx
index b58a0170e..dcf69a4b6 100644
--- a/apps/ade-cli/src/tuiClient/app.tsx
+++ b/apps/ade-cli/src/tuiClient/app.tsx
@@ -107,7 +107,7 @@ import { latestExpandableFailureId, renderObject, summarizeDiffChanges } from ".
 import { startTuiHeartbeat, type TuiHeartbeat } from "./heartbeat";
 import { isImageFilePath, latestOpenableImageTarget, readClipboardImageAttachment, readImageDimensions } from "./imageTargets";
 import { appendReservedTuiEvent, reserveTuiEventDedupKey, syncTuiEventDedupKeys } from "./eventDedup";
-import { loadAdeCodeState, saveAdeCodeState } from "./state";
+import { loadAdeCodeState, saveAdeCodeProjectState, scopedAdeCodeState } from "./state";
 import { SpinTickProvider } from "./spinTick";
 import { buildLinearToolRequest } from "./linearCommands";
 import {
@@ -1676,7 +1676,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
   const draftSeededFromHistoryRef = useRef(false);
   const initialNewChatPreviewRef = useRef(true);
   const attachProbeInFlightRef = useRef(false);
-  const [initialAdeCodeState] = useState(loadAdeCodeState);
+  const [initialAdeCodeState] = useState(() => scopedAdeCodeState(loadAdeCodeState(), project.projectRoot));
   const lastChatByLaneRef = useRef<Map<string, string>>(new Map(Object.entries(initialAdeCodeState.lastChatByLane)));
   const lastLaneIdRef = useRef<string | null>(initialAdeCodeState.lastLaneId);
   const lastChatByLaneWriteTimerRef = useRef<NodeJS.Timeout | null>(null);
@@ -1705,9 +1705,9 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
       for (const [laneId, sessionId] of lastChatByLaneRef.current) {
         lastChatByLane[laneId] = sessionId;
       }
-      saveAdeCodeState({ lastChatByLane, lastLaneId: lastLaneIdRef.current });
+      saveAdeCodeProjectState(project.projectRoot, { lastChatByLane, lastLaneId: lastLaneIdRef.current });
     }, 500);
-  }, []);
+  }, [project.projectRoot]);
 
   const setChatScrollOffset = useCallback((value: number | ((previous: number) => number)) => {
     setChatScrollOffsetRows((previous) => {
@@ -3279,7 +3279,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
         for (const [laneId, sessionId] of lastChatByLaneRef.current) {
           lastChatByLane[laneId] = sessionId;
         }
-        saveAdeCodeState({ lastChatByLane, lastLaneId: lastLaneIdRef.current });
+        saveAdeCodeProjectState(project.projectRoot, { lastChatByLane, lastLaneId: lastLaneIdRef.current });
       }
       if (pendingModelCommitTimerRef.current) {
         clearTimeout(pendingModelCommitTimerRef.current);
diff --git a/apps/ade-cli/src/tuiClient/state.ts b/apps/ade-cli/src/tuiClient/state.ts
index 829eab72b..5dc9d6899 100644
--- a/apps/ade-cli/src/tuiClient/state.ts
+++ b/apps/ade-cli/src/tuiClient/state.ts
@@ -4,7 +4,9 @@ import path from "node:path";
 
 export type AdeCodeState = {
   lastChatByLane: Record<string, string>;
+  lastChatByProjectLane: Record<string, Record<string, string>>;
   lastLaneId: string | null;
+  lastLaneByProject: Record<string, string>;
 };
 
 const STATE_DIR = path.join(os.homedir(), ".ade");
@@ -13,21 +15,9 @@ const STATE_PATH = path.join(STATE_DIR, "ade-code-state.json");
 export function loadAdeCodeState(): AdeCodeState {
   try {
     const raw = fs.readFileSync(STATE_PATH, "utf8");
-    const parsed = JSON.parse(raw) as Partial<AdeCodeState>;
-    const lastChatByLane: Record<string, string> = {};
-    if (parsed && typeof parsed.lastChatByLane === "object" && parsed.lastChatByLane) {
-      for (const [laneId, sessionId] of Object.entries(parsed.lastChatByLane)) {
-        if (typeof laneId === "string" && typeof sessionId === "string") {
-          lastChatByLane[laneId] = sessionId;
-        }
-      }
-    }
-    return {
-      lastChatByLane,
-      lastLaneId: typeof parsed.lastLaneId === "string" ? parsed.lastLaneId : null,
-    };
+    return normalizeAdeCodeState(JSON.parse(raw));
   } catch {
-    return { lastChatByLane: {}, lastLaneId: null };
+    return emptyAdeCodeState();
   }
 }
 
@@ -39,3 +29,77 @@ export function saveAdeCodeState(state: AdeCodeState): void {
     // best-effort persistence; ignore
   }
 }
+
+export function scopedAdeCodeState(
+  state: AdeCodeState,
+  projectRoot: string,
+): Pick<AdeCodeState, "lastChatByLane" | "lastLaneId"> {
+  const projectKey = normalizeProjectKey(projectRoot);
+  return {
+    lastChatByLane: state.lastChatByProjectLane[projectKey] ?? state.lastChatByLane,
+    lastLaneId: state.lastLaneByProject[projectKey] ?? state.lastLaneId,
+  };
+}
+
+export function saveAdeCodeProjectState(
+  projectRoot: string,
+  projectState: Pick<AdeCodeState, "lastChatByLane" | "lastLaneId">,
+): void {
+  const current = loadAdeCodeState();
+  const projectKey = normalizeProjectKey(projectRoot);
+  current.lastChatByProjectLane[projectKey] = { ...projectState.lastChatByLane };
+  if (projectState.lastLaneId) {
+    current.lastLaneByProject[projectKey] = projectState.lastLaneId;
+  } else {
+    delete current.lastLaneByProject[projectKey];
+  }
+  current.lastChatByLane = { ...projectState.lastChatByLane };
+  current.lastLaneId = projectState.lastLaneId;
+  saveAdeCodeState(current);
+}
+
+export function normalizeAdeCodeState(value: unknown): AdeCodeState {
+  const parsed = value && typeof value === "object" && !Array.isArray(value)
+    ? value as Partial<AdeCodeState>
+    : {};
+  return {
+    lastChatByLane: normalizeStringRecord(parsed.lastChatByLane),
+    lastChatByProjectLane: normalizeNestedStringRecord(parsed.lastChatByProjectLane),
+    lastLaneId: typeof parsed.lastLaneId === "string" ? parsed.lastLaneId : null,
+    lastLaneByProject: normalizeStringRecord(parsed.lastLaneByProject),
+  };
+}
+
+function emptyAdeCodeState(): AdeCodeState {
+  return {
+    lastChatByLane: {},
+    lastChatByProjectLane: {},
+    lastLaneId: null,
+    lastLaneByProject: {},
+  };
+}
+
+function normalizeProjectKey(projectRoot: string): string {
+  return path.resolve(projectRoot);
+}
+
+function normalizeStringRecord(value: unknown): Record<string, string> {
+  const normalized: Record<string, string> = {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) return normalized;
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof key === "string" && typeof entry === "string") {
+      normalized[key] = entry;
+    }
+  }
+  return normalized;
+}
+
+function normalizeNestedStringRecord(value: unknown): Record<string, Record<string, string>> {
+  const normalized: Record<string, Record<string, string>> = {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) return normalized;
+  for (const [key, entry] of Object.entries(value)) {
+    const child = normalizeStringRecord(entry);
+    if (Object.keys(child).length > 0) normalized[key] = child;
+  }
+  return normalized;
+}

From 6dbcd72623461d81e0a31e010f810179d343fe9e Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:38:20 -0400
Subject: [PATCH 10/24] fix(prs): preserve cached detail on rate limit

---
 .../components/prs/state/PrsContext.test.tsx  | 82 +++++++++++++++++++
 .../components/prs/state/PrsContext.tsx       | 14 +---
 2 files changed, 84 insertions(+), 12 deletions(-)

diff --git a/apps/desktop/src/renderer/components/prs/state/PrsContext.test.tsx b/apps/desktop/src/renderer/components/prs/state/PrsContext.test.tsx
index 90b913fce..b129b7fb6 100644
--- a/apps/desktop/src/renderer/components/prs/state/PrsContext.test.tsx
+++ b/apps/desktop/src/renderer/components/prs/state/PrsContext.test.tsx
@@ -534,6 +534,88 @@ describe("PrsContext refresh", () => {
     expect(screen.getByTestId("checks-count").textContent).toBe("0");
   });
 
+  it("keeps cached selected PR detail visible when live GitHub detail is rate limited", async () => {
+    const user = userEvent.setup();
+    vi.mocked(window.ade.prs.listWithConflicts).mockResolvedValue([makeFakePr("pr-1")]);
+    Object.assign(window.ade.prs, {
+      listSnapshots: vi.fn(async ({ prId }: { prId: string }) => [
+        {
+          prId,
+          detail: null,
+          status: {
+            prId,
+            state: "open",
+            checksStatus: "passing",
+            reviewStatus: "approved",
+            isMergeable: true,
+            mergeConflicts: false,
+            behindBaseBy: 0,
+          },
+          checks: [
+            {
+              name: "cached-ci",
+              status: "completed",
+              conclusion: "success",
+              detailsUrl: null,
+              startedAt: null,
+              completedAt: null,
+            },
+          ],
+          reviews: [
+            {
+              reviewer: "octocat",
+              reviewerAvatarUrl: null,
+              state: "approved",
+              body: null,
+              submittedAt: null,
+            },
+          ],
+          comments: [
+            {
+              id: "comment-1",
+              author: "octocat",
+              authorAvatarUrl: null,
+              body: "cached comment",
+              source: "issue",
+              url: null,
+              path: null,
+              line: null,
+              createdAt: null,
+            },
+          ],
+          files: [],
+          commits: [],
+          updatedAt: "2026-03-24T12:00:00.000Z",
+        },
+      ]),
+      getStatus: vi.fn(async () => {
+        throw new Error("GitHub API rate limit exceeded");
+      }),
+      getChecks: vi.fn(async () => []),
+      getReviews: vi.fn(async () => []),
+      getComments: vi.fn(async () => []),
+    });
+
+    render(
+      <PrsProvider>
+        <DetailHarness />
+      </PrsProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("loading").textContent).toBe("idle");
+    });
+
+    await user.click(screen.getByRole("button", { name: "select pr-1" }));
+    await waitFor(() => {
+      expect(screen.getByTestId("detail-busy").textContent).toBe("idle");
+      expect(screen.getByTestId("status").textContent).toBe("open");
+      expect(screen.getByTestId("checks-count").textContent).toBe("1");
+      expect(screen.getByTestId("reviews-count").textContent).toBe("1");
+      expect(screen.getByTestId("comments-count").textContent).toBe("1");
+    });
+  });
+
   it("falls back to single merge-context hydration for IDs missing from a batch response", async () => {
     vi.mocked(window.ade.prs.listWithConflicts).mockResolvedValue([makeFakePr("pr-1"), makeFakePr("pr-2")]);
     Object.assign(window.ade.prs, {
diff --git a/apps/desktop/src/renderer/components/prs/state/PrsContext.tsx b/apps/desktop/src/renderer/components/prs/state/PrsContext.tsx
index 89fc313f8..5b4753153 100644
--- a/apps/desktop/src/renderer/components/prs/state/PrsContext.tsx
+++ b/apps/desktop/src/renderer/components/prs/state/PrsContext.tsx
@@ -1020,8 +1020,6 @@ export function PrsProvider({ children }: { children: React.ReactNode }) {
     ])
       .then(([statusResult, checksResult, reviewsResult, commentsResult]) => {
         if (cancelled) return;
-        liveDetailApplied = true;
-
         // Check for rate-limit errors in any rejected result
         for (const result of [statusResult, checksResult, reviewsResult, commentsResult]) {
           if (result.status === "rejected") {
@@ -1029,22 +1027,14 @@ export function PrsProvider({ children }: { children: React.ReactNode }) {
             if (msg.includes("rate limit") || msg.includes("API rate")) {
               rateLimitedUntilRef.current = Date.now() + 5 * 60_000;
               console.warn("[PrsContext] GitHub rate limit hit — pausing detail polling for 5 min");
-              // Clear stale data on rate limit
-              detailStatePrIdRef.current = null;
+              // Keep cached snapshot/detail data visible while GitHub is degraded.
               setDetailLiveDataPrId(null);
-              setDetailStatus(null);
-              setDetailChecks([]);
-              setDetailReviews([]);
-              setDetailComments([]);
-              setDetailReviewThreads([]);
-              setDetailDeployments([]);
-              setDetailAiSummary(null);
-              setDetailSnapshot(null);
               return;
             }
           }
         }
 
+        liveDetailApplied = true;
         detailStatePrIdRef.current = prId;
         if (statusResult.status === "fulfilled") {
           setDetailStatus(statusResult.value ?? null);

From 7e3ff7078008e05d48f33367989d960e47c5b249 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:43:29 -0400
Subject: [PATCH 11/24] fix(work): lock tool controls on lane mismatch

---
 .../chat/ChatAppControlPanel.test.tsx         | 27 ++++++++
 .../components/chat/ChatAppControlPanel.tsx   | 59 +++++++++++------
 .../chat/ChatIosSimulatorPanel.test.tsx       | 28 ++++++++
 .../components/chat/ChatIosSimulatorPanel.tsx | 66 +++++++++++++------
 .../components/terminals/WorkSidebar.test.tsx | 16 ++++-
 .../components/terminals/WorkSidebar.tsx      |  5 +-
 6 files changed, 159 insertions(+), 42 deletions(-)

diff --git a/apps/desktop/src/renderer/components/chat/ChatAppControlPanel.test.tsx b/apps/desktop/src/renderer/components/chat/ChatAppControlPanel.test.tsx
index 3da1af2cb..20c6a9f2a 100644
--- a/apps/desktop/src/renderer/components/chat/ChatAppControlPanel.test.tsx
+++ b/apps/desktop/src/renderer/components/chat/ChatAppControlPanel.test.tsx
@@ -237,6 +237,33 @@ describe("ChatAppControlPanel", () => {
     expect(api.appControl.listTargets.mock.calls.length).toBeGreaterThan(targetRefreshCalls);
   });
 
+  it("keeps another-lane connected session read-only", async () => {
+    const api = installAdeMock({ status: connectedStatus, targetList: targets });
+
+    render(
+      <ChatAppControlPanel
+        sessionId="chat-connected"
+        laneId="lane-2"
+        projectRoot="/repo"
+        controlDisabledReason="This App Control view is attached to Lane 1, not Lane 2."
+      />,
+    );
+
+    const targetSelect = await screen.findByLabelText("Switch the controlled window") as HTMLSelectElement;
+    expect(targetSelect.disabled).toBe(true);
+    expect(screen.queryByLabelText("Stop App Control session")).toBeNull();
+    expect((screen.getByTitle("Re-capture screenshot and DOM snapshot") as HTMLButtonElement).disabled).toBe(true);
+
+    const typeInput = screen.getByLabelText("Text to type into the focused app element") as HTMLInputElement;
+    fireEvent.change(typeInput, { target: { value: "wrong lane" } });
+    expect((screen.getByLabelText("Type into focused app element") as HTMLButtonElement).disabled).toBe(true);
+
+    expect(api.appControl.stop).not.toHaveBeenCalled();
+    expect(api.appControl.attachToTarget).not.toHaveBeenCalled();
+    expect(api.appControl.typeText).not.toHaveBeenCalled();
+    expect(api.appControl.click).not.toHaveBeenCalled();
+  });
+
   it("hovers, attaches, and re-attaches an inspected app element", async () => {
     const api = installAdeMock({ status: connectedStatus, targetList: targets });
     const onAddContext = vi.fn();
diff --git a/apps/desktop/src/renderer/components/chat/ChatAppControlPanel.tsx b/apps/desktop/src/renderer/components/chat/ChatAppControlPanel.tsx
index cd1cbbc93..0fc202539 100644
--- a/apps/desktop/src/renderer/components/chat/ChatAppControlPanel.tsx
+++ b/apps/desktop/src/renderer/components/chat/ChatAppControlPanel.tsx
@@ -29,6 +29,7 @@ type ChatAppControlPanelProps = {
   sessionId: string | null;
   laneId: string | null;
   projectRoot: string | null;
+  controlDisabledReason?: string | null;
   onAddContext?: (item: AppControlContextItem) => void;
   onAddAttachment?: (attachment: AgentChatFileRef) => void;
   onInsertDraft?: (text: string) => void;
@@ -246,6 +247,7 @@ export function ChatAppControlPanel({
   sessionId,
   laneId,
   projectRoot,
+  controlDisabledReason = null,
   onAddContext,
   onAddAttachment,
   onInsertDraft,
@@ -292,6 +294,8 @@ export function ChatAppControlPanel({
 
   const activeSession = status?.activeSession ?? snapshot?.session ?? null;
   const sessionStatus = useMemo(() => statusInfo(activeSession), [activeSession]);
+  const controlsDisabled = Boolean(controlDisabledReason);
+  const controlsDisabledMessage = controlDisabledReason ?? "This App Control session is read-only from the current lane.";
 
   useEffect(() => {
     activeTargetIdRef.current = activeSession?.cdpTargetId ?? null;
@@ -380,7 +384,7 @@ export function ChatAppControlPanel({
           scrollRafRef.current = null;
           const next = scrollPendingRef.current;
           scrollPendingRef.current = null;
-          if (!next) return;
+          if (!next || controlsDisabled) return;
           void window.ade.appControl.scroll(next).catch(() => {});
         });
       }
@@ -391,7 +395,7 @@ export function ChatAppControlPanel({
     // that should re-bind is the live/empty mount flip. Only depending on
     // liveFrameActive here is intentional — re-binding on every snapshot
     // refresh would create a brief gap where wheel events get missed.
-  }, [liveFrameActive]);
+  }, [controlsDisabled, liveFrameActive]);
 
   useEffect(() => {
     setScreenshotBlank(false);
@@ -587,6 +591,7 @@ export function ChatAppControlPanel({
   const launchSelected = useCallback(
     () =>
       runBusy("launch", async () => {
+        if (controlsDisabled) throw new Error(controlsDisabledMessage);
         const command = launchCommand.trim();
         if (!command) throw new Error("Enter a launch command.");
         const cwd = launchCwd.trim();
@@ -618,7 +623,7 @@ export function ChatAppControlPanel({
           setMessage({ tone: "info", text: `Started ${launched.label} in the terminal.${cdpHint}` });
         }
       }),
-    [laneId, launchCommand, launchCwd, onShowTerminal, projectRoot, refreshSnapshot, runBusy, sessionId],
+    [controlsDisabled, controlsDisabledMessage, laneId, launchCommand, launchCwd, onShowTerminal, projectRoot, refreshSnapshot, runBusy, sessionId],
   );
 
   const pickProcess = useCallback((processId: string) => {
@@ -631,6 +636,10 @@ export function ChatAppControlPanel({
 
   const attachToTargetId = useCallback(
     (targetId: string) => {
+      if (controlsDisabled) {
+        setMessage({ tone: "error", text: controlsDisabledMessage });
+        return undefined;
+      }
       // Optimistically reflect the user's pick in the dropdown so it doesn't
       // appear to "snap back" while the new screencast spins up.
       setPendingTargetId(targetId);
@@ -644,12 +653,13 @@ export function ChatAppControlPanel({
         }
       });
     },
-    [refreshTargets, runBusy],
+    [controlsDisabled, controlsDisabledMessage, refreshTargets, runBusy],
   );
 
   const connectPort = useCallback(
     () =>
       runBusy("connect", async () => {
+        if (controlsDisabled) throw new Error(controlsDisabledMessage);
         const port = Number(cdpPort);
         if (!Number.isFinite(port) || port <= 0) throw new Error("Enter a valid CDP port.");
         const connected = await window.ade.appControl.connect({
@@ -665,12 +675,13 @@ export function ChatAppControlPanel({
         await refreshSnapshot();
         setMessage({ tone: "info", text: `Connected to ${connected.label}.` });
       }),
-    [cdpPort, laneId, projectRoot, refreshSnapshot, runBusy, sessionId],
+    [cdpPort, controlsDisabled, controlsDisabledMessage, laneId, projectRoot, refreshSnapshot, runBusy, sessionId],
   );
 
   const stopSession = useCallback(
     () =>
       runBusy("stop", async () => {
+        if (controlsDisabled) throw new Error(controlsDisabledMessage);
         await window.ade.appControl.stop();
         const nextStatus = await window.ade.appControl.getStatus();
         setStatus(nextStatus);
@@ -680,7 +691,7 @@ export function ChatAppControlPanel({
         setSelectedContextItem(null);
         setMessage({ tone: "info", text: "Session stopped." });
       }),
-    [runBusy],
+    [controlsDisabled, controlsDisabledMessage, runBusy],
   );
 
   const attachSelection = useCallback(
@@ -688,6 +699,9 @@ export function ChatAppControlPanel({
       if (modeRef.current !== "inspect") {
         throw new Error("Switch to Inspect mode to attach App Control context.");
       }
+      if (controlsDisabled) {
+        throw new Error(controlsDisabledMessage);
+      }
       if (screenshotBlank) {
         throw new Error("The renderer is attached but the screenshot is blank. Open the app window or menu bar item, then refresh the snapshot before attaching context.");
       }
@@ -765,7 +779,7 @@ export function ChatAppControlPanel({
         text: `Inserted ${attachedLabel} context.`,
       });
     },
-    [onAddAttachment, onAddContext, projectRoot, screenshotBlank, snapshot],
+    [controlsDisabled, controlsDisabledMessage, onAddAttachment, onAddContext, projectRoot, screenshotBlank, snapshot],
   );
 
   const handleImageClick = useCallback(
@@ -787,6 +801,10 @@ export function ChatAppControlPanel({
       const sourceHeight = useLive ? liveDims.height : snapshot?.screenshot?.height ?? 0;
       const sourceScale = useLive ? liveDims.scale : snapshot?.screen.scale ?? 1;
       if (sourceWidth <= 0 || sourceHeight <= 0) return;
+      if (controlsDisabled) {
+        setMessage({ tone: "error", text: controlsDisabledMessage });
+        return;
+      }
       if (!useLive && screenshotBlank) {
         setMessage({
           tone: "error",
@@ -814,12 +832,13 @@ export function ChatAppControlPanel({
         });
       setMessage(null);
     },
-    [attachSelection, liveFrameActive, runBusy, screenshotBlank, snapshot],
+    [attachSelection, controlsDisabled, controlsDisabledMessage, liveFrameActive, runBusy, screenshotBlank, snapshot],
   );
 
   const typeIntoApp = useCallback(
     () =>
       runBusy("type", async () => {
+        if (controlsDisabled) throw new Error(controlsDisabledMessage);
         if (modeRef.current !== "control") throw new Error("Switch to Control mode to type into the app.");
         if (!typeText.trim()) return;
         await window.ade.appControl.typeText({ text: typeText });
@@ -832,7 +851,7 @@ export function ChatAppControlPanel({
         }
         setMessage({ tone: "info", text: "Typed into focused element." });
       }),
-    [refreshSnapshot, runBusy, typeText],
+    [controlsDisabled, controlsDisabledMessage, refreshSnapshot, runBusy, typeText],
   );
 
   const requestDebugHelp = useCallback(() => {
@@ -856,9 +875,9 @@ export function ChatAppControlPanel({
     && !activeSession.cdpEndpoint,
   );
   const hasActiveSession = Boolean(activeSession) && !["exited", "stopped", "failed"].includes(activeSession?.status ?? "");
-  const canLaunch = launchCommand.trim().length > 0 && !hasActiveSession;
-  const canStop = hasActiveSession;
-  const canType = mode === "control" && typeText.trim().length > 0 && sessionConnected;
+  const canLaunch = launchCommand.trim().length > 0 && !hasActiveSession && !controlsDisabled;
+  const canStop = hasActiveSession && !controlsDisabled;
+  const canType = mode === "control" && typeText.trim().length > 0 && sessionConnected && !controlsDisabled;
 
   const processOptions = useMemo(() => {
     return processes.map((proc) => {
@@ -905,7 +924,7 @@ export function ChatAppControlPanel({
           <div className="relative shrink-0">
             <select
               value=""
-              disabled={!processesLoaded || processOptions.length === 0}
+              disabled={!processesLoaded || processOptions.length === 0 || controlsDisabled}
               onChange={(event) => {
                 const value = event.target.value;
                 if (!value) return;
@@ -1010,6 +1029,7 @@ export function ChatAppControlPanel({
             placeholder="CDP port"
             aria-label="CDP port"
             inputMode="numeric"
+            disabled={controlsDisabled}
             className="w-[100px] shrink-0 rounded-md border border-white/[0.07] bg-black/20 px-2 py-1.5 text-[11px] text-fg/80 outline-none placeholder:text-muted-fg/40 focus:border-sky-300/30"
             onKeyDown={(event) => {
               if (event.key === "Enter" && cdpPort.trim()) void connectPort();
@@ -1017,7 +1037,7 @@ export function ChatAppControlPanel({
           />
           <button
             type="button"
-            disabled={Boolean(busy) || !cdpPort.trim()}
+            disabled={Boolean(busy) || !cdpPort.trim() || controlsDisabled}
             onClick={connectPort}
             className="inline-flex h-7 shrink-0 items-center justify-center gap-1 rounded-md border border-white/[0.07] bg-white/[0.03] px-2 text-[10px] font-medium text-fg/72 transition-colors hover:bg-white/[0.06] disabled:cursor-not-allowed disabled:opacity-45"
             title="Connect to a running Electron app via CDP"
@@ -1053,7 +1073,7 @@ export function ChatAppControlPanel({
             }}
             className="min-w-0 flex-1 rounded-md border border-white/[0.06] bg-black/30 px-2 py-1 text-[11px] text-fg/85 outline-none focus:border-sky-300/30"
             aria-label="Switch the controlled window"
-            disabled={Boolean(busy) || targets.length < 2}
+            disabled={Boolean(busy) || targets.length < 2 || controlsDisabled}
           >
             {targets.map((target) => {
               const baseTitle = (target.title ?? "").trim();
@@ -1078,7 +1098,8 @@ export function ChatAppControlPanel({
           <button
             type="button"
             onClick={() => void refreshTargets()}
-            className="inline-flex h-6 shrink-0 items-center justify-center rounded border border-white/[0.06] bg-white/[0.02] px-1.5 text-[10px] text-muted-fg/65 hover:text-fg/85"
+            disabled={controlsDisabled}
+            className="inline-flex h-6 shrink-0 items-center justify-center rounded border border-white/[0.06] bg-white/[0.02] px-1.5 text-[10px] text-muted-fg/65 hover:text-fg/85 disabled:cursor-not-allowed disabled:opacity-45"
             title="Re-scan controlled app windows"
           >
             {targets.length}
@@ -1126,7 +1147,7 @@ export function ChatAppControlPanel({
         <div className="absolute left-2 top-2 z-10 flex flex-col items-start gap-1">
           <button
             type="button"
-            disabled={Boolean(busy) || !sessionConnected}
+            disabled={Boolean(busy) || !sessionConnected || controlsDisabled}
             onClick={() =>
               void runBusy("snapshot", async () => {
                 await refreshSnapshot();
@@ -1154,7 +1175,7 @@ export function ChatAppControlPanel({
               <button
                 key={nextMode}
                 type="button"
-                disabled={!hasActiveSession}
+                disabled={!hasActiveSession || controlsDisabled}
                 onClick={() => setMode(nextMode)}
                 className={cn(
                   "h-6 rounded px-2 text-[10px] font-medium transition-colors disabled:cursor-not-allowed",
@@ -1439,7 +1460,7 @@ export function ChatAppControlPanel({
             </div>
             <button
               type="button"
-              disabled={Boolean(busy) || screenshotBlank || !selectedPoint || !sessionConnected}
+              disabled={Boolean(busy) || screenshotBlank || !selectedPoint || !sessionConnected || controlsDisabled}
               onClick={() => {
                 if (selectedPoint) void runBusy("select", () => attachSelection(selectedPoint.x, selectedPoint.y));
               }}
diff --git a/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.test.tsx b/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.test.tsx
index 00c8de088..501cf6a49 100644
--- a/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.test.tsx
+++ b/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.test.tsx
@@ -587,6 +587,34 @@ describe("ChatIosSimulatorPanel", () => {
     expect(screen.getByPlaceholderText("Type into the active simulator app")).toBeTruthy();
   });
 
+  it("keeps another-lane simulator sessions read-only", async () => {
+    const { api } = installIosSimulatorApi();
+
+    render(
+      <ChatIosSimulatorPanel
+        sessionId="chat-1"
+        laneId="lane-2"
+        projectRoot="/tmp/project"
+        controlDisabledReason="This iOS Simulator view is attached to Lane 1, not Lane 2."
+        onAddContext={vi.fn()}
+      />,
+    );
+
+    const launchButton = await screen.findByRole("button", { name: "Launch" }) as HTMLButtonElement;
+    expect(launchButton.disabled).toBe(true);
+    expect(screen.queryByRole("button", { name: "Stop" })).toBeNull();
+    expect(screen.queryByPlaceholderText("Type into the active simulator app")).toBeNull();
+
+    fireEvent.click(screen.getByRole("button", { name: "Inspect" }));
+    const refreshButton = await screen.findByTitle("Refresh inspector snapshot") as HTMLButtonElement;
+    expect(refreshButton.disabled).toBe(true);
+
+    expect(api.launch).not.toHaveBeenCalled();
+    expect(api.shutdown).not.toHaveBeenCalled();
+    expect(api.typeText).not.toHaveBeenCalled();
+    expect(api.tap).not.toHaveBeenCalled();
+  });
+
   it("selects an inspected simulator element and opens Preview Lab for its matching target", async () => {
     vi.stubGlobal("PointerEvent", MouseEvent);
     vi.stubGlobal("Image", class {
diff --git a/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.tsx b/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.tsx
index 4ffda1e4f..74692587d 100644
--- a/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.tsx
+++ b/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.tsx
@@ -64,6 +64,7 @@ type ChatIosSimulatorPanelProps = {
   sessionId: string | null;
   laneId?: string | null;
   projectRoot: string | null;
+  controlDisabledReason?: string | null;
   onAddContext?: (item: IosElementContextItem) => void;
   onAddAttachment?: (attachment: AgentChatFileRef) => void;
   onInsertDraft?: (text: string) => void;
@@ -887,6 +888,7 @@ export function ChatIosSimulatorPanel({
   sessionId,
   laneId = null,
   projectRoot,
+  controlDisabledReason = null,
   onAddContext,
   onAddAttachment,
   onInsertDraft,
@@ -954,6 +956,8 @@ export function ChatIosSimulatorPanel({
     return status?.activeDevice ?? devices[0] ?? null;
   }, [devices, selectedDeviceUdid, status?.activeDevice]);
   const activeSession = status?.activeSession ?? null;
+  const controlsDisabled = Boolean(controlDisabledReason);
+  const controlsDisabledMessage = controlDisabledReason ?? "This iOS Simulator session is read-only from the current lane.";
   const discoveredDeviceBackedStreamActive = Boolean(
     activeDevice
     && !activeSession
@@ -1156,16 +1160,17 @@ export function ChatIosSimulatorPanel({
     return owner !== sessionId ? owner : null;
   }, [activeSession?.chatSessionId, sessionId]);
   const ownedByOtherChat = otherChatSessionId !== null;
+  const controlsOwnedElsewhere = ownedByOtherChat || controlsDisabled;
 
   const toggleSimulatorWindowMode = useCallback(() => {
-    if (!activeSession || ownedByOtherChat) return;
+    if (!activeSession || controlsOwnedElsewhere) return;
     const enable = simulatorWindowSessionId !== activeSession.id;
     liveDeviceStreamFailureTimestampsRef.current = [];
     setSimulatorWindowSessionId(enable ? activeSession.id : null);
     setMessage(enable
       ? "Opening Simulator.app and switching to window streaming..."
       : "Switching back to the headless simulator stream...");
-  }, [activeSession, ownedByOtherChat, simulatorWindowSessionId]);
+  }, [activeSession, controlsOwnedElsewhere, simulatorWindowSessionId]);
 
   const changeMediaZoom = useCallback((delta: number) => {
     setMediaZoom((current) => {
@@ -1229,6 +1234,10 @@ export function ChatIosSimulatorPanel({
   }, [syncExistingStreamStatus]);
 
   const shutdownSimulator = useCallback(async (force = false) => {
+    if (controlsDisabled) {
+      setMessage(controlsDisabledMessage);
+      return false;
+    }
     try {
       await window.ade.iosSimulator.shutdown({ force });
       await refreshStatus();
@@ -1240,7 +1249,7 @@ export function ChatIosSimulatorPanel({
       setMessage(error instanceof Error ? error.message : String(error));
       return false;
     }
-  }, [refreshStatus]);
+  }, [controlsDisabled, controlsDisabledMessage, refreshStatus]);
 
   const takeOver = useCallback(async () => {
     const stopped = await shutdownSimulator(true);
@@ -1475,7 +1484,7 @@ export function ChatIosSimulatorPanel({
   }, [refreshStatus, startWindowCaptureVisual]);
 
   const retryAdeStream = useCallback(() => {
-    if (!activeDevice || !activeSession || activeSession.deviceUdid !== activeDevice.udid || ownedByOtherChat) return;
+    if (!activeDevice || !activeSession || activeSession.deviceUdid !== activeDevice.udid || controlsOwnedElsewhere) return;
     liveDeviceStreamFailureTimestampsRef.current = [];
     setSimulatorWindowSessionId(null);
     setMessage("Retrying ADE simulator stream...");
@@ -1492,7 +1501,7 @@ export function ChatIosSimulatorPanel({
         setMessage(`ADE simulator stream failed. ${message}`);
       }
     })();
-  }, [activeDevice, activeSession, ownedByOtherChat, startDeviceBackedLiveVisual, stopRendererLiveVisual]);
+  }, [activeDevice, activeSession, controlsOwnedElsewhere, startDeviceBackedLiveVisual, stopRendererLiveVisual]);
 
   useEffect(() => {
     const video = videoRef.current;
@@ -2104,6 +2113,10 @@ export function ChatIosSimulatorPanel({
   ]);
 
   const launch = useCallback(async (options: { previewTarget?: IosSimulatorPreviewTarget | null } = {}) => {
+    if (controlsDisabled) {
+      setMessage(controlsDisabledMessage);
+      return;
+    }
     const previewTarget = options.previewTarget ?? null;
     setBusy(true);
     setLaunchBusy(true);
@@ -2140,7 +2153,7 @@ export function ChatIosSimulatorPanel({
       setLaunchBusy(false);
       setBusy(false);
     }
-  }, [activeTarget?.id, laneId, projectRoot, refreshSnapshot, refreshStatus, selectedDeviceUdid, selectedTargetId, sessionId]);
+  }, [activeTarget?.id, controlsDisabled, controlsDisabledMessage, laneId, projectRoot, refreshSnapshot, refreshStatus, selectedDeviceUdid, selectedTargetId, sessionId]);
 
   useEffect(() => {
     launchRef.current = launch;
@@ -2208,6 +2221,10 @@ export function ChatIosSimulatorPanel({
   const sendTypedText = useCallback(async () => {
     const text = typedText;
     if (!text.trim()) return;
+    if (controlsDisabled) {
+      setMessage(controlsDisabledMessage);
+      return;
+    }
     setTypedText("");
     armWindowCaptureRecoveryAfterInput();
     try {
@@ -2215,7 +2232,7 @@ export function ChatIosSimulatorPanel({
     } catch (error) {
       setMessage(error instanceof Error ? error.message : String(error));
     }
-  }, [armWindowCaptureRecoveryAfterInput, projectRoot, selectedDeviceUdid, typedText]);
+  }, [armWindowCaptureRecoveryAfterInput, controlsDisabled, controlsDisabledMessage, projectRoot, selectedDeviceUdid, typedText]);
 
   const updateInspectBounds = useCallback(() => {
     const image = imageRef.current;
@@ -2751,6 +2768,10 @@ export function ChatIosSimulatorPanel({
     const start = dragStartRef.current;
     dragStartRef.current = null;
     if (!start) return;
+    if (controlsDisabled) {
+      setMessage(controlsDisabledMessage);
+      return;
+    }
     const point = liveSimulatorPointFromPointer(event);
     if (!point) return;
     const moved = Math.hypot(event.clientX - start.clientX, event.clientY - start.clientY);
@@ -2777,10 +2798,14 @@ export function ChatIosSimulatorPanel({
         setMessage(error instanceof Error ? error.message : String(error));
       }
     })();
-  }, [armWindowCaptureRecoveryAfterInput, liveSimulatorPointFromPointer, projectRoot, selectedDeviceUdid, snapshot?.screen.scale]);
+  }, [armWindowCaptureRecoveryAfterInput, controlsDisabled, controlsDisabledMessage, liveSimulatorPointFromPointer, projectRoot, selectedDeviceUdid, snapshot?.screen.scale]);
 
   const handleVideoKeyDown = useCallback((event: KeyboardEvent<HTMLDivElement>) => {
     if (event.metaKey || event.ctrlKey || event.altKey) return;
+    if (controlsDisabled) {
+      setMessage(controlsDisabledMessage);
+      return;
+    }
     if (event.key === "Enter") {
       event.preventDefault();
       armWindowCaptureRecoveryAfterInput();
@@ -2796,7 +2821,7 @@ export function ChatIosSimulatorPanel({
         setMessage(error instanceof Error ? error.message : String(error));
       });
     }
-  }, [armWindowCaptureRecoveryAfterInput, projectRoot, selectedDeviceUdid]);
+  }, [armWindowCaptureRecoveryAfterInput, controlsDisabled, controlsDisabledMessage, projectRoot, selectedDeviceUdid]);
 
   const providerSummary = snapshot?.providers.map((provider) => {
     if (provider.source === "screenshot") return "screenshot";
@@ -2895,11 +2920,11 @@ export function ChatIosSimulatorPanel({
     && (liveVisual.status !== "error" || (liveVisual.kind === "mjpeg" && Boolean(liveVisual.url)));
   const canShowSnapshot = mode === "inspect" && Boolean(snapshotImage);
   const hasActiveSession = Boolean(activeSession);
-  const interactionDisabled = ownedByOtherChat || showSetupChecklist;
+  const interactionDisabled = controlsOwnedElsewhere || showSetupChecklist;
   const canRetryDeviceBackedStream = mode === "interact"
     && liveVisualKind === "mjpeg"
     && hasActiveSession
-    && !ownedByOtherChat
+    && !controlsOwnedElsewhere
     && Boolean(activeDevice);
   const showStreamRecoveryActions = canRetryDeviceBackedStream
     && (liveVisual?.status === "reconnecting" || liveVisual?.status === "error");
@@ -2948,7 +2973,7 @@ export function ChatIosSimulatorPanel({
               event.stopPropagation();
               if (!simulatorWindowModeEnabled) toggleSimulatorWindowMode();
             }}
-            disabled={!activeSession || ownedByOtherChat || simulatorWindowModeEnabled}
+            disabled={!activeSession || controlsOwnedElsewhere || simulatorWindowModeEnabled}
           >
             <Desktop size={11} />
             iOS window
@@ -3048,7 +3073,7 @@ export function ChatIosSimulatorPanel({
             <div className="font-sans text-[10px] text-muted-fg/52">
               {activeSurface === "simulator" ? "Simulator mode" : "Preview mode"}
             </div>
-            {activeSurface === "simulator" && hasActiveSession && !ownedByOtherChat ? (
+            {activeSurface === "simulator" && hasActiveSession && !controlsOwnedElsewhere ? (
               <div className="group relative">
                 <button
                   type="button"
@@ -3102,17 +3127,18 @@ export function ChatIosSimulatorPanel({
               </select>
               <button
                 type="button"
-                className="inline-flex h-8 w-8 items-center justify-center rounded-md border border-white/[0.07] bg-white/[0.03] text-fg/55 transition-colors hover:text-fg/85"
+                className="inline-flex h-8 w-8 items-center justify-center rounded-md border border-white/[0.07] bg-white/[0.03] text-fg/55 transition-colors hover:text-fg/85 disabled:cursor-not-allowed disabled:opacity-45"
                 onClick={() => {
                   void refreshStatus()
                     .then(() => refreshLaunchTargets(selectedDeviceUdid ?? activeDevice?.udid ?? undefined))
                     .catch((error) => setMessage(error instanceof Error ? error.message : String(error)));
                 }}
+                disabled={controlsOwnedElsewhere}
                 title="Refresh simulator state"
               >
                 <ArrowClockwise size={14} />
               </button>
-              {hasActiveSession && !ownedByOtherChat ? (
+              {hasActiveSession && !controlsOwnedElsewhere ? (
                 <button
                   type="button"
                   className="inline-flex h-8 items-center gap-1 rounded-md border border-rose-400/22 bg-rose-500/8 px-2 font-sans text-[11px] font-medium text-rose-200/80 transition-colors hover:bg-rose-500/12 disabled:cursor-not-allowed disabled:opacity-45"
@@ -3151,7 +3177,7 @@ export function ChatIosSimulatorPanel({
                 <Play size={13} weight="fill" />
                 Launch
               </button>
-              {hasActiveSession && !ownedByOtherChat ? (
+              {hasActiveSession && !controlsOwnedElsewhere ? (
                 <button
                   type="button"
                   className="inline-flex h-8 items-center gap-1.5 rounded-md border border-cyan-400/20 bg-cyan-500/10 px-2 font-sans text-[11px] font-medium text-cyan-100/85 transition-colors hover:bg-cyan-500/15 disabled:cursor-not-allowed disabled:opacity-45"
@@ -3725,7 +3751,7 @@ export function ChatIosSimulatorPanel({
                     setHoveredElement(null);
                   }}
                   onPointerDown={(event) => event.stopPropagation()}
-                  disabled={!snapshot?.screenshot.dataUrl || ownedByOtherChat}
+                  disabled={!snapshot?.screenshot.dataUrl || controlsOwnedElsewhere}
                   title="Drag a screenshot region to insert it with simulator context"
                 >
                   <ImageSquare size={11} />
@@ -3739,7 +3765,7 @@ export function ChatIosSimulatorPanel({
                   event.stopPropagation();
                   void refreshSnapshot({ priority: true }).catch(() => {});
                 }}
-                disabled={!hasActiveSession || snapshotRefreshing || ownedByOtherChat}
+                disabled={!hasActiveSession || snapshotRefreshing || controlsOwnedElsewhere}
                 title="Refresh inspector snapshot"
               >
                 <ArrowClockwise size={11} className={snapshotRefreshing ? "animate-spin" : undefined} />
@@ -3850,7 +3876,7 @@ export function ChatIosSimulatorPanel({
       </div>
 
       {!mediaExpanded ? <div className="shrink-0 space-y-2">
-        {mode === "interact" && !ownedByOtherChat && !showSetupChecklist ? (
+        {mode === "interact" && !controlsOwnedElsewhere && !showSetupChecklist ? (
           <div className="flex items-center gap-2">
             <TextT size={14} className="text-muted-fg/45" />
             <input
@@ -3882,7 +3908,7 @@ export function ChatIosSimulatorPanel({
             {footerStatus}
           </div>
         ) : null}
-        {mode === "interact" && !controlAvailable && !showSetupChecklist && !ownedByOtherChat ? (
+        {mode === "interact" && !controlAvailable && !showSetupChecklist && !controlsOwnedElsewhere ? (
           <div className="rounded-md border border-amber-400/15 bg-amber-500/10 px-2 py-1.5 font-sans text-[11px] text-amber-100/70">
             Install a supported full Xcode for native touch input, or idb + idb_companion for fallback tap, drag, and text.
           </div>
diff --git a/apps/desktop/src/renderer/components/terminals/WorkSidebar.test.tsx b/apps/desktop/src/renderer/components/terminals/WorkSidebar.test.tsx
index 4d290f830..82e6aeebb 100644
--- a/apps/desktop/src/renderer/components/terminals/WorkSidebar.test.tsx
+++ b/apps/desktop/src/renderer/components/terminals/WorkSidebar.test.tsx
@@ -19,10 +19,15 @@ vi.mock("../chat/ChatIosSimulatorPanel", async () => {
   return {
     ChatIosSimulatorPanel: (props: {
       sessionId: string | null;
+      controlDisabledReason?: string | null;
       onAddAttachment?: (attachment: { path: string; type: "image" }) => void;
       onAddContext?: (item: IosElementContextItem) => void;
       onInsertDraft?: (text: string) => void;
-    }) => React.createElement("div", { "data-testid": "ios-panel", "data-session-id": props.sessionId ?? "" }, [
+    }) => React.createElement("div", {
+      "data-testid": "ios-panel",
+      "data-session-id": props.sessionId ?? "",
+      "data-control-disabled": props.controlDisabledReason ?? "",
+    }, [
       React.createElement("button", {
         key: "context",
         type: "button",
@@ -50,8 +55,13 @@ vi.mock("../chat/ChatAppControlPanel", async () => {
   return {
     ChatAppControlPanel: (props: {
       sessionId: string | null;
+      controlDisabledReason?: string | null;
       onAddContext?: (item: AppControlContextItem) => void;
-    }) => React.createElement("div", { "data-testid": "app-control-panel", "data-session-id": props.sessionId ?? "" },
+    }) => React.createElement("div", {
+      "data-testid": "app-control-panel",
+      "data-session-id": props.sessionId ?? "",
+      "data-control-disabled": props.controlDisabledReason ?? "",
+    },
       React.createElement("button", {
         type: "button",
         disabled: !props.onAddContext,
@@ -418,6 +428,7 @@ describe("WorkSidebar context targets", () => {
     });
 
     expect(await screen.findByText(/This App Control view is attached to Lane 2, not Lane 1/)).toBeTruthy();
+    expect(screen.getByTestId("app-control-panel").getAttribute("data-control-disabled")).toMatch(/Lane 2/);
     expect((screen.getByText("Add App Control context") as HTMLButtonElement).disabled).toBe(true);
   });
 
@@ -431,6 +442,7 @@ describe("WorkSidebar context targets", () => {
     });
 
     expect(await screen.findByText(/This iOS Simulator view is attached to Lane 2, not Lane 1/)).toBeTruthy();
+    expect(screen.getByTestId("ios-panel").getAttribute("data-control-disabled")).toMatch(/Lane 2/);
     expect((screen.getByText("Add iOS context") as HTMLButtonElement).disabled).toBe(true);
   });
 
diff --git a/apps/desktop/src/renderer/components/terminals/WorkSidebar.tsx b/apps/desktop/src/renderer/components/terminals/WorkSidebar.tsx
index f3ae14b7b..8954d1e47 100644
--- a/apps/desktop/src/renderer/components/terminals/WorkSidebar.tsx
+++ b/apps/desktop/src/renderer/components/terminals/WorkSidebar.tsx
@@ -268,7 +268,8 @@ export function WorkSidebar({
     }
     return null;
   }
-  const contextDisabledReason = resolveLaneMismatchReason() ?? targetDisabledReason;
+  const laneMismatchReason = resolveLaneMismatchReason();
+  const contextDisabledReason = laneMismatchReason ?? targetDisabledReason;
   const canInsertContext = Boolean(contextTarget && !contextDisabledReason);
   const panelSessionId = contextTarget?.kind === "chat" ? contextTarget.sessionId : null;
 
@@ -487,6 +488,7 @@ export function WorkSidebar({
         sessionId={panelSessionId}
         laneId={laneId}
         projectRoot={laneRoot}
+        controlDisabledReason={laneMismatchReason}
         onAddAttachment={canInsertContext ? addAttachment : undefined}
         onAddContext={canInsertContext ? addIosContext : undefined}
         onInsertDraft={canInsertContext ? insertDraft : undefined}
@@ -496,6 +498,7 @@ export function WorkSidebar({
         sessionId={panelSessionId}
         laneId={laneId}
         projectRoot={laneRoot}
+        controlDisabledReason={laneMismatchReason}
         onAddAttachment={canInsertContext ? addAttachment : undefined}
         onAddContext={canInsertContext ? addAppControlContext : undefined}
         onInsertDraft={canInsertContext ? insertDraft : undefined}

From 6091843784170348817702c42c002a0dbc98d22b Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:45:29 -0400
Subject: [PATCH 12/24] fix(tui): skip runtime event replay on attach

---
 .../ade-cli/src/multiProjectRpcServer.test.ts | 69 +++++++++++++++++++
 apps/ade-cli/src/multiProjectRpcServer.ts     | 11 +--
 .../tuiClient/__tests__/connection.test.ts    |  2 +-
 apps/ade-cli/src/tuiClient/app.tsx            |  2 +-
 apps/ade-cli/src/tuiClient/connection.ts      |  4 +-
 apps/ade-cli/src/tuiClient/types.ts           |  2 +-
 6 files changed, 82 insertions(+), 8 deletions(-)

diff --git a/apps/ade-cli/src/multiProjectRpcServer.test.ts b/apps/ade-cli/src/multiProjectRpcServer.test.ts
index a35f71d65..07a827335 100644
--- a/apps/ade-cli/src/multiProjectRpcServer.test.ts
+++ b/apps/ade-cli/src/multiProjectRpcServer.test.ts
@@ -426,4 +426,73 @@ describe("multi-project RPC server", () => {
 
     handler.dispose();
   });
+
+  it("can subscribe to project runtime events without replaying buffered history", async () => {
+    const { projectRoot, registry } = createRegistry();
+    const added = registry.add(projectRoot);
+    const eventBuffer = createEventBuffer();
+    eventBuffer.push({
+      timestamp: "2026-05-10T00:00:00.000Z",
+      category: "runtime",
+      payload: { type: "file_change", event: { path: "old.ts" } },
+    });
+    const scopeRegistry = {
+      get: vi.fn(async () => ({
+        registryProjectId: added.projectId,
+        record: added,
+        runtime: {
+          eventBuffer,
+          dispose: vi.fn(),
+        },
+        dispose: vi.fn(),
+      })),
+      ensureSyncHost: vi.fn(),
+      dispose: vi.fn(),
+      disposeAll: vi.fn(),
+    } as unknown as ProjectScopeRegistry;
+    const handler = createMultiProjectRpcRequestHandler({
+      serverVersion: "test",
+      projectRegistry: registry,
+      scopeRegistry,
+    });
+    const notify = vi.fn();
+    handler.setNotifier(notify);
+
+    await handler({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "ade/initialize",
+      params: {},
+    });
+
+    const subscribed = await handler({
+      jsonrpc: "2.0",
+      id: 2,
+      method: "runtimeEvents.subscribe",
+      params: {
+        projectId: added.projectId,
+        category: "runtime",
+        replay: false,
+      },
+    }) as { subscriptionId: string; hasMore: boolean; nextCursor: number };
+
+    expect(subscribed.hasMore).toBe(false);
+    expect(notify).not.toHaveBeenCalled();
+
+    eventBuffer.push({
+      timestamp: "2026-05-10T00:00:01.000Z",
+      category: "runtime",
+      payload: { type: "file_change", event: { path: "new.ts" } },
+    });
+
+    expect(notify).toHaveBeenCalledTimes(1);
+    expect(notify).toHaveBeenCalledWith("runtime/event", expect.objectContaining({
+      subscriptionId: subscribed.subscriptionId,
+      event: expect.objectContaining({
+        payload: { type: "file_change", event: { path: "new.ts" } },
+      }),
+    }));
+
+    handler.dispose();
+  });
 });
diff --git a/apps/ade-cli/src/multiProjectRpcServer.ts b/apps/ade-cli/src/multiProjectRpcServer.ts
index dff4ae43f..04eff2f36 100644
--- a/apps/ade-cli/src/multiProjectRpcServer.ts
+++ b/apps/ade-cli/src/multiProjectRpcServer.ts
@@ -323,6 +323,7 @@ export function createMultiProjectRpcRequestHandler(
     }
     const cursor = readCursor(params.cursor);
     const limit = readLimit(params.limit);
+    const replay = params.replay !== false;
     const scope = await scopeRegistry.get(projectId);
     const subscriptionId = `runtime-events-${nextSubscriptionId++}`;
     const shouldForward = (event: BufferedEvent): boolean =>
@@ -337,15 +338,17 @@ export function createMultiProjectRpcRequestHandler(
       unsubscribe,
     });
 
-    const replay = scope.runtime.eventBuffer.drain(cursor, limit);
-    for (const event of replay.events) {
+    const replayResult = replay
+      ? scope.runtime.eventBuffer.drain(cursor, limit)
+      : { events: [], nextCursor: cursor, hasMore: false };
+    for (const event of replayResult.events) {
       if (shouldForward(event))
         emitRuntimeEvent(subscriptionId, projectId, event);
     }
     return {
       subscriptionId,
-      nextCursor: replay.nextCursor,
-      hasMore: replay.hasMore,
+      nextCursor: replayResult.nextCursor,
+      hasMore: replayResult.hasMore,
     };
   };
 
diff --git a/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts b/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts
index b27f51d62..af322dcf9 100644
--- a/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts
+++ b/apps/ade-cli/src/tuiClient/__tests__/connection.test.ts
@@ -276,7 +276,7 @@ describe("connectToAde embedded mode", () => {
         { timeout: 1000 },
       );
       expect(requests.find((request) => request.method === "runtimeEvents.subscribe")?.params)
-        .toMatchObject({ projectId: "project-daemon", category: "runtime" });
+        .toMatchObject({ projectId: "project-daemon", category: "runtime", replay: false });
 
       const envelope = {
         sessionId: "chat-1",
diff --git a/apps/ade-cli/src/tuiClient/app.tsx b/apps/ade-cli/src/tuiClient/app.tsx
index dcf69a4b6..f54420ca6 100644
--- a/apps/ade-cli/src/tuiClient/app.tsx
+++ b/apps/ade-cli/src/tuiClient/app.tsx
@@ -3360,7 +3360,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
     if (!connection) return;
     let disposed = false;
     let unsubscribe: (() => void) | null = null;
-    void connection.subscribeRuntimeEvents({ category: "runtime", cursor: 0, limit: 50 }, (event) => {
+    void connection.subscribeRuntimeEvents({ category: "runtime", cursor: 0, limit: 50, replay: false }, (event) => {
       const payload = event.payload as { type?: unknown; event?: unknown };
       const terminalEvent = payload.event as { sessionId?: unknown; data?: unknown } | undefined;
       const sessionId = typeof terminalEvent?.sessionId === "string" ? terminalEvent.sessionId : null;
diff --git a/apps/ade-cli/src/tuiClient/connection.ts b/apps/ade-cli/src/tuiClient/connection.ts
index 9a0ce122e..7b971057e 100644
--- a/apps/ade-cli/src/tuiClient/connection.ts
+++ b/apps/ade-cli/src/tuiClient/connection.ts
@@ -421,6 +421,7 @@ async function connectAttachedSocket(args: {
           category: "runtime",
           cursor: 0,
           limit: 100,
+          replay: false,
         }).then((response) => {
           if (disposed) {
             request("runtimeEvents.unsubscribe", { subscriptionId: response.subscriptionId }).catch(() => {});
@@ -461,6 +462,7 @@ async function connectAttachedSocket(args: {
             category: subscriptionArgs.category ?? "runtime",
             cursor: subscriptionArgs.cursor ?? 0,
             limit: subscriptionArgs.limit ?? 100,
+            replay: subscriptionArgs.replay,
           });
           subscriptionId = response.subscriptionId;
           for (const payload of pending) {
@@ -654,7 +656,7 @@ export async function connectToAde(args: {
       const eventBuffer = runtime.eventBuffer;
       if (!eventBuffer) return () => {};
       const shouldForward = (event: BufferedEvent) => !category || event.category === category;
-      const replay = typeof eventBuffer.drain === "function"
+      const replay = subscriptionArgs.replay !== false && typeof eventBuffer.drain === "function"
         ? eventBuffer.drain(subscriptionArgs.cursor ?? 0, subscriptionArgs.limit ?? 100)
         : { events: [] };
       for (const event of replay.events) {
diff --git a/apps/ade-cli/src/tuiClient/types.ts b/apps/ade-cli/src/tuiClient/types.ts
index 29ca23b60..cbee23cf9 100644
--- a/apps/ade-cli/src/tuiClient/types.ts
+++ b/apps/ade-cli/src/tuiClient/types.ts
@@ -54,7 +54,7 @@ export type AdeCodeConnection = {
   actionList<T = unknown>(domain: string, action: string, argsList: unknown[]): Promise<T>;
   onChatEvent(callback: (event: AgentChatEventEnvelope) => void): () => void;
   subscribeRuntimeEvents(
-    args: { category?: BufferedEvent["category"] | null; cursor?: number; limit?: number },
+    args: { category?: BufferedEvent["category"] | null; cursor?: number; limit?: number; replay?: boolean },
     callback: (event: BufferedEvent) => void,
   ): Promise<() => void>;
   close(): Promise<void>;

From fa6413891a2f83d202bd7db2361a8f2689e26604 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:46:29 -0400
Subject: [PATCH 13/24] fix(tui): ignore stale state refreshes

---
 apps/ade-cli/src/tuiClient/app.tsx | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/apps/ade-cli/src/tuiClient/app.tsx b/apps/ade-cli/src/tuiClient/app.tsx
index f54420ca6..30205b46d 100644
--- a/apps/ade-cli/src/tuiClient/app.tsx
+++ b/apps/ade-cli/src/tuiClient/app.tsx
@@ -1668,6 +1668,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
   const eventCountRef = useRef<number>(0);
   const eventDedupKeysRef = useRef<Set<string>>(new Set());
   const eventDedupKeyOrderRef = useRef<string[]>([]);
+  const refreshGenerationRef = useRef(0);
   const chatScrollOffsetRowsRef = useRef(0);
   const chatScrollMaxOffsetRef = useRef(0);
   const lastSeenAtBottomEventCountRef = useRef(0);
@@ -2995,6 +2996,10 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
   const refreshState = useCallback(async () => {
     const conn = connectionRef.current;
     if (!conn) return;
+    const generation = refreshGenerationRef.current + 1;
+    refreshGenerationRef.current = generation;
+    const isCurrentRefresh = () =>
+      refreshGenerationRef.current === generation && connectionRef.current === conn;
     const nextLanes = await listLanes(conn);
     const nextSessions = await listChatSessions(conn);
     const nextTerminalSessions = await listTerminalSessions(conn).catch(() => []);
@@ -3029,6 +3034,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
     let nextEvents: AgentChatEventEnvelope[] = [];
     if (nextSessionId && !nextTerminalSession) {
       const history = await getChatHistory(conn, nextSessionId);
+      if (!isCurrentRefresh()) return;
       setCurrentGoal(latestGoal(history.events));
       nextEvents = clearedAt
         ? history.events.filter((event) => event.timestamp > clearedAt)
@@ -3060,6 +3066,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
         ? { laneId: nextLaneId, provider: nextProvider }
         : null;
     const remoteCommands = commandArgs ? await getSlashCommands(conn, commandArgs).catch(() => []) : [];
+    if (!isCurrentRefresh()) return;
     const projectCommands = discoverProjectSlashCommands(nextLane?.worktreePath || project.workspaceRoot);
     const nextCommands = remoteCommands.length ? remoteCommands : projectCommands;
     const provider = normalizeProvider(nextProvider);

From 2016fad64167865ee04da2c4737505fb6a6e82db Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:48:36 -0400
Subject: [PATCH 14/24] fix(files): watch workspace before opening files

---
 .../src/renderer/components/files/FilesPage.test.tsx   | 10 ++++++++++
 .../src/renderer/components/files/FilesPage.tsx        |  2 +-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/renderer/components/files/FilesPage.test.tsx b/apps/desktop/src/renderer/components/files/FilesPage.test.tsx
index 513b90719..488586973 100644
--- a/apps/desktop/src/renderer/components/files/FilesPage.test.tsx
+++ b/apps/desktop/src/renderer/components/files/FilesPage.test.tsx
@@ -410,6 +410,16 @@ describe("FilesPage", () => {
     });
   });
 
+  it("starts the workspace watcher even before a file is opened", async () => {
+    renderFilesPage({ preferPrimaryWorkspace: true });
+
+    await waitForFilesWatcherStartup();
+    expect((window.ade.files.watchChanges as any).mock.calls[0]?.[0]).toMatchObject({
+      workspaceId: "primary",
+      includeIgnored: true,
+    });
+  });
+
   it("filters loaded tree paths locally and keeps content search explicit", async () => {
     renderFilesPage({
       openFilePath: ".ade/notes/project.md",
diff --git a/apps/desktop/src/renderer/components/files/FilesPage.tsx b/apps/desktop/src/renderer/components/files/FilesPage.tsx
index a04d48529..5c17523ab 100644
--- a/apps/desktop/src/renderer/components/files/FilesPage.tsx
+++ b/apps/desktop/src/renderer/components/files/FilesPage.tsx
@@ -650,7 +650,7 @@ export function FilesPage({
   const activeTabPreviewKind = getFilePreviewKind(activeTab);
   const activeTabIsText = isTextTab(activeTab);
   const canEdit = Boolean(activeWorkspace) && (!activeWorkspace?.isReadOnlyByDefault || allowPrimaryEdit);
-  const liveWatchEnabled = openTabs.length > 0;
+  const liveWatchEnabled = Boolean(workspaceId);
 
   useEffect(() => {
     if (!activeWorkspace?.rootPath) return;

From 09792c8cae05d6e94f2888356654da372c23c588 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 03:50:55 -0400
Subject: [PATCH 15/24] fix(work): track lane mismatch memo dependency

---
 apps/desktop/src/renderer/components/terminals/WorkSidebar.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/desktop/src/renderer/components/terminals/WorkSidebar.tsx b/apps/desktop/src/renderer/components/terminals/WorkSidebar.tsx
index 8954d1e47..b043540bd 100644
--- a/apps/desktop/src/renderer/components/terminals/WorkSidebar.tsx
+++ b/apps/desktop/src/renderer/components/terminals/WorkSidebar.tsx
@@ -521,6 +521,7 @@ export function WorkSidebar({
     contextDisabledReason,
     insertDraft,
     laneId,
+    laneMismatchReason,
     laneRoot,
     navigate,
     selectedCommit,

From c20fd3221a20cd989476a91d8efcc633d4f5e54e Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 04:01:12 -0400
Subject: [PATCH 16/24] perf(tui): avoid polling full chat history

---
 .../tuiClient/__tests__/appPolling.test.tsx   | 228 ++++++++++++++++++
 apps/ade-cli/src/tuiClient/app.tsx            |  95 +++++---
 2 files changed, 296 insertions(+), 27 deletions(-)
 create mode 100644 apps/ade-cli/src/tuiClient/__tests__/appPolling.test.tsx

diff --git a/apps/ade-cli/src/tuiClient/__tests__/appPolling.test.tsx b/apps/ade-cli/src/tuiClient/__tests__/appPolling.test.tsx
new file mode 100644
index 000000000..d7f12064c
--- /dev/null
+++ b/apps/ade-cli/src/tuiClient/__tests__/appPolling.test.tsx
@@ -0,0 +1,228 @@
+import React from "react";
+import { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { render } from "ink-testing-library";
+import type { AgentChatEventEnvelope, AgentChatSessionSummary } from "../../../../desktop/src/shared/types/chat";
+import type { LaneSummary } from "../../../../desktop/src/shared/types/lanes";
+import type { AdeCodeConnection, ProjectLaunchContext } from "../types";
+
+const mocks = vi.hoisted(() => ({
+  connectToAde: vi.fn(),
+  startTuiHeartbeat: vi.fn(),
+  listLanes: vi.fn(),
+  listChatSessions: vi.fn(),
+  listTerminalSessions: vi.fn(),
+  getChatHistory: vi.fn(),
+  getSlashCommands: vi.fn(),
+  getAvailableModels: vi.fn(),
+}));
+
+vi.mock("../connection", () => ({
+  connectToAde: mocks.connectToAde,
+}));
+
+vi.mock("../heartbeat", () => ({
+  startTuiHeartbeat: mocks.startTuiHeartbeat,
+}));
+
+vi.mock("../state", async () => {
+  const actual = await vi.importActual<typeof import("../state")>("../state");
+  return {
+    ...actual,
+    loadAdeCodeState: () => ({
+      lastChatByLane: {},
+      lastChatByProjectLane: { "/repo": { "lane-1": "chat-1" } },
+      lastLaneByProject: { "/repo": "lane-1" },
+      lastLaneId: null,
+    }),
+    saveAdeCodeProjectState: vi.fn(),
+  };
+});
+
+vi.mock("../adeApi", async () => {
+  const actual = await vi.importActual<typeof import("../adeApi")>("../adeApi");
+  return {
+    ...actual,
+    listLanes: mocks.listLanes,
+    listChatSessions: mocks.listChatSessions,
+    listTerminalSessions: mocks.listTerminalSessions,
+    getChatHistory: mocks.getChatHistory,
+    getSlashCommands: mocks.getSlashCommands,
+    getAvailableModels: mocks.getAvailableModels,
+  };
+});
+
+import { AdeCodeApp, shouldHydrateRefreshHistory } from "../app";
+
+function lane(overrides: Partial<LaneSummary> = {}): LaneSummary {
+  return {
+    id: "lane-1",
+    name: "main",
+    laneType: "primary",
+    baseRef: "main",
+    branchRef: "main",
+    worktreePath: "/repo",
+    parentLaneId: null,
+    childCount: 0,
+    stackDepth: 0,
+    parentStatus: null,
+    isEditProtected: false,
+    status: { dirty: false, ahead: 0, behind: 0, remoteBehind: 0, rebaseInProgress: false },
+    color: null,
+    icon: null,
+    tags: [],
+    createdAt: "2026-01-01T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+function chat(overrides: Partial<AgentChatSessionSummary> = {}): AgentChatSessionSummary {
+  return {
+    sessionId: "chat-1",
+    laneId: "lane-1",
+    provider: "codex",
+    model: "gpt-5.5",
+    modelId: "openai/gpt-5.5",
+    status: "active",
+    startedAt: "2026-01-01T00:00:00.000Z",
+    endedAt: null,
+    lastActivityAt: "2026-01-01T00:00:00.000Z",
+    lastOutputPreview: null,
+    summary: null,
+    ...overrides,
+  };
+}
+
+function event(sessionId: string, sequence: number, type: string): AgentChatEventEnvelope {
+  return {
+    sessionId,
+    sequence,
+    timestamp: `2026-01-01T00:00:0${sequence}.000Z`,
+    event: { type } as AgentChatEventEnvelope["event"],
+  };
+}
+
+async function flushAsyncEffects() {
+  await act(async () => {
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+}
+
+describe("AdeCodeApp polling", () => {
+  let chatListeners: Set<(event: AgentChatEventEnvelope) => void>;
+  let connection: AdeCodeConnection;
+  const project: ProjectLaunchContext = {
+    launchCwd: "/repo",
+    projectRoot: "/repo",
+    workspaceRoot: "/repo",
+    laneHint: null,
+  };
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    chatListeners = new Set();
+    connection = {
+      mode: "attached",
+      projectRoot: "/repo",
+      workspaceRoot: "/repo",
+      socketPath: "/tmp/ade.sock",
+      request: vi.fn(),
+      tool: vi.fn(),
+      action: vi.fn(),
+      actionList: vi.fn(),
+      onChatEvent: vi.fn((callback) => {
+        chatListeners.add(callback);
+        return () => {
+          chatListeners.delete(callback);
+        };
+      }),
+      subscribeRuntimeEvents: vi.fn(async () => () => {}),
+      close: vi.fn(async () => {}),
+    };
+    mocks.connectToAde.mockResolvedValue(connection);
+    mocks.startTuiHeartbeat.mockReturnValue({ stop: vi.fn() });
+    mocks.listLanes.mockResolvedValue([lane()]);
+    mocks.listChatSessions.mockResolvedValue([chat()]);
+    mocks.listTerminalSessions.mockResolvedValue([]);
+    mocks.getChatHistory.mockResolvedValue({
+      sessionId: "chat-1",
+      events: [event("chat-1", 1, "user_message")],
+      truncated: false,
+    });
+    mocks.getSlashCommands.mockResolvedValue([]);
+    mocks.getAvailableModels.mockResolvedValue([]);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.clearAllMocks();
+  });
+
+  it("keeps active polling on summary refreshes without hydrating chat history", async () => {
+    const instance = render(<AdeCodeApp project={project} />);
+    await flushAsyncEffects();
+
+    expect(mocks.getChatHistory).toHaveBeenCalledTimes(0);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1_000);
+    });
+    await flushAsyncEffects();
+
+    expect(mocks.listChatSessions).toHaveBeenCalledTimes(2);
+    expect(mocks.getChatHistory).toHaveBeenCalledTimes(0);
+
+    instance.unmount();
+  });
+
+  it("refreshes summaries for background chat events without hydrating active history", async () => {
+    const instance = render(<AdeCodeApp project={project} />);
+    await flushAsyncEffects();
+
+    expect(chatListeners.size).toBe(1);
+    expect(mocks.getChatHistory).toHaveBeenCalledTimes(0);
+
+    await act(async () => {
+      [...chatListeners][0]?.(event("background-chat", 2, "status"));
+      await Promise.resolve();
+    });
+    await flushAsyncEffects();
+
+    expect(mocks.listChatSessions).toHaveBeenCalledTimes(2);
+    expect(mocks.getChatHistory).toHaveBeenCalledTimes(0);
+
+    instance.unmount();
+  });
+});
+
+describe("shouldHydrateRefreshHistory", () => {
+  it("hydrates by default and when a lightweight refresh changes sessions", () => {
+    expect(shouldHydrateRefreshHistory({
+      currentSessionId: "chat-1",
+      loadedSessionId: "chat-1",
+      nextSessionId: "chat-1",
+    })).toBe(true);
+    expect(shouldHydrateRefreshHistory({
+      hydrateHistory: false,
+      currentSessionId: "chat-1",
+      loadedSessionId: "chat-1",
+      nextSessionId: "chat-2",
+    })).toBe(true);
+    expect(shouldHydrateRefreshHistory({
+      hydrateHistory: false,
+      currentSessionId: "chat-1",
+      loadedSessionId: null,
+      nextSessionId: "chat-1",
+    })).toBe(true);
+  });
+
+  it("skips history for lightweight refreshes of the already-loaded active session", () => {
+    expect(shouldHydrateRefreshHistory({
+      hydrateHistory: false,
+      currentSessionId: "chat-1",
+      loadedSessionId: "chat-1",
+      nextSessionId: "chat-1",
+    })).toBe(false);
+  });
+});
diff --git a/apps/ade-cli/src/tuiClient/app.tsx b/apps/ade-cli/src/tuiClient/app.tsx
index 30205b46d..ffebb7b6c 100644
--- a/apps/ade-cli/src/tuiClient/app.tsx
+++ b/apps/ade-cli/src/tuiClient/app.tsx
@@ -209,6 +209,21 @@ type AdeCodeAppProps = {
   socketPath?: string | null;
 };
 
+type RefreshStateOptions = {
+  hydrateHistory?: boolean;
+};
+
+export function shouldHydrateRefreshHistory(args: {
+  hydrateHistory?: boolean;
+  currentSessionId: string | null;
+  loadedSessionId: string | null;
+  nextSessionId: string;
+}): boolean {
+  return args.hydrateHistory !== false
+    || args.currentSessionId !== args.nextSessionId
+    || args.loadedSessionId !== args.nextSessionId;
+}
+
 function initialModelState(): AdeCodeModelState {
   const descriptor = getDefaultModelDescriptor("codex");
   return {
@@ -2241,6 +2256,19 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
     activeTerminalSessionRef.current = activeTerminalSession;
   }, [activeTerminalSession]);
 
+  useEffect(() => {
+    eventCountRef.current = events.length;
+    if (!activeSessionId || activeTerminalSession) return;
+    const fallbackContext = activeSession?.modelId
+      ? getModelById(activeSession.modelId)?.contextWindow ?? null
+      : null;
+    const stats = latestTokenStats(events, fallbackContext);
+    setCurrentGoal(latestGoal(events));
+    setContextPercent(stats.percent);
+    setTokenSummary(formatTokenSummary(stats));
+    setStatusLineStats(stats);
+  }, [activeSession?.modelId, activeSessionId, activeTerminalSession, events]);
+
   useEffect(() => {
     terminalSessionsRef.current = terminalSessions;
   }, [terminalSessions]);
@@ -2855,6 +2883,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
     lastUserOpenedPaneRef.current = null;
     eventDedupKeysRef.current.clear();
     eventDedupKeyOrderRef.current = [];
+    eventCountRef.current = 0;
     setEvents([]);
     setClearedAt(null);
     chatDraftRef.current = "";
@@ -2993,7 +3022,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
     };
   }, [activeMentionRange, displaySessions, lanes, selectedMentions]);
 
-  const refreshState = useCallback(async () => {
+  const refreshState = useCallback(async (options: RefreshStateOptions = {}) => {
     const conn = connectionRef.current;
     if (!conn) return;
     const generation = refreshGenerationRef.current + 1;
@@ -3031,23 +3060,32 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
     if (previewMode) {
       newChatPreviewLaneIdRef.current = nextLaneId;
     }
-    let nextEvents: AgentChatEventEnvelope[] = [];
+    let nextEvents: AgentChatEventEnvelope[] | null = null;
     if (nextSessionId && !nextTerminalSession) {
-      const history = await getChatHistory(conn, nextSessionId);
-      if (!isCurrentRefresh()) return;
-      setCurrentGoal(latestGoal(history.events));
-      nextEvents = clearedAt
-        ? history.events.filter((event) => event.timestamp > clearedAt)
-        : history.events;
-      const activeModelId = nextSession?.modelId ?? null;
-      const fallbackContext = activeModelId ? getModelById(activeModelId)?.contextWindow ?? null : null;
-      const stats = latestTokenStats(history.events, fallbackContext);
-      setContextPercent(stats.percent);
-      setTokenSummary(formatTokenSummary(stats));
-      setStatusLineStats(stats);
+      const shouldHydrateHistory = shouldHydrateRefreshHistory({
+        hydrateHistory: options.hydrateHistory,
+        currentSessionId: activeSessionIdRef.current,
+        loadedSessionId: loadedSessionIdRef.current,
+        nextSessionId,
+      });
+      if (shouldHydrateHistory) {
+        const history = await getChatHistory(conn, nextSessionId);
+        if (!isCurrentRefresh()) return;
+        setCurrentGoal(latestGoal(history.events));
+        nextEvents = clearedAt
+          ? history.events.filter((event) => event.timestamp > clearedAt)
+          : history.events;
+        const activeModelId = nextSession?.modelId ?? null;
+        const fallbackContext = activeModelId ? getModelById(activeModelId)?.contextWindow ?? null : null;
+        const stats = latestTokenStats(history.events, fallbackContext);
+        setContextPercent(stats.percent);
+        setTokenSummary(formatTokenSummary(stats));
+        setStatusLineStats(stats);
+        eventCountRef.current = history.events.length;
+        loadedSessionIdRef.current = nextSessionId;
+      }
       setStreaming(nextSession?.status === "active");
       if (nextSession?.status === "active") setInterrupted(false);
-      eventCountRef.current = history.events.length;
     } else {
       setContextPercent(null);
       setTokenSummary(null);
@@ -3056,6 +3094,8 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
       setStreaming(false);
       setInterrupted(false);
       eventCountRef.current = 0;
+      loadedSessionIdRef.current = null;
+      nextEvents = [];
     }
     const configSession = nextTerminalSession ? null : nextSession ?? (!draftSeededFromHistoryRef.current ? seedSession : null);
     const nextProvider = terminalSessionProvider(nextTerminalSession) ?? configSession?.provider ?? modelState.provider ?? "codex";
@@ -3088,8 +3128,10 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
     }
     selectActiveLaneId(nextLaneId);
     selectActiveSessionId(nextSessionId);
-    eventDedupKeyOrderRef.current = syncTuiEventDedupKeys(eventDedupKeysRef.current, nextEvents);
-    setEvents(nextEvents);
+    if (nextEvents !== null) {
+      eventDedupKeyOrderRef.current = syncTuiEventDedupKeys(eventDedupKeysRef.current, nextEvents);
+      setEvents(nextEvents);
+    }
     setSlashCommands(nextCommands);
     setModels(nextModels);
     if (launchToNewChatPreview) {
@@ -3267,6 +3309,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
         selectActiveSessionId(null);
         eventDedupKeysRef.current.clear();
         eventDedupKeyOrderRef.current = [];
+        eventCountRef.current = 0;
         setEvents([]);
         await refreshState();
       } catch (err) {
@@ -3303,16 +3346,11 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
     if (!connection) return;
     return connection.onChatEvent((envelope) => {
       if (envelope.sessionId !== activeSessionIdRef.current) {
-        void refreshState().catch(() => undefined);
+        void refreshState({ hydrateHistory: false }).catch(() => undefined);
         return;
       }
       if (clearedAt && envelope.timestamp <= clearedAt) return;
       const event = envelope.event as Record<string, unknown>;
-      if (event.type === "codex_goal_updated") {
-        setCurrentGoal((event as { goal?: CodexThreadGoal | null }).goal ?? null);
-      } else if (event.type === "codex_goal_cleared") {
-        setCurrentGoal(null);
-      }
       const reservedKey = reserveTuiEventDedupKey(envelope, eventDedupKeysRef.current);
       if (reservedKey !== null) {
         setEvents((prev) => {
@@ -3324,6 +3362,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
             reservedKey,
           );
           eventDedupKeyOrderRef.current = next.eventKeys;
+          eventCountRef.current = next.events.length;
           return next.events;
         });
       }
@@ -3380,7 +3419,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
         return;
       }
       if (payload.type === "pty_exit") {
-        void refreshState().catch(() => undefined);
+        void refreshState({ hydrateHistory: false }).catch(() => undefined);
       }
     }).then((stop) => {
       if (disposed) {
@@ -3401,8 +3440,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
       return;
     }
     if (loadedSessionIdRef.current === activeSessionId) return;
-    loadedSessionIdRef.current = activeSessionId;
-    void refreshState().catch((err) => {
+    void refreshState({ hydrateHistory: true }).catch((err) => {
       setError(err instanceof Error ? err.message : String(err));
     });
   }, [activeSessionId, connection, refreshState]);
@@ -3415,7 +3453,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
     if (!connection) return;
     const intervalMs = chatRefreshPollActive ? 1_000 : 15_000;
     const timer = setInterval(() => {
-      void refreshState().catch((err) => {
+      void refreshState({ hydrateHistory: false }).catch((err) => {
         setError(err instanceof Error ? err.message : String(err));
       });
     }, intervalMs);
@@ -4380,6 +4418,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
       setClearedAt(new Date().toISOString());
       eventDedupKeysRef.current.clear();
       eventDedupKeyOrderRef.current = [];
+      eventCountRef.current = 0;
       setEvents([]);
       setChatScrollOffset(0);
       addNotice("Local transcript view cleared. The durable chat remains in ADE.", "info");
@@ -5287,6 +5326,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
       setClearedAt(new Date().toISOString());
       eventDedupKeysRef.current.clear();
       eventDedupKeyOrderRef.current = [];
+      eventCountRef.current = 0;
       setEvents([]);
       setChatScrollOffset(0);
       addNotice("Cleared local transcript view.", "success");
@@ -5842,6 +5882,7 @@ export function AdeCodeApp({ project, forceEmbedded, requireSocket, socketPath }
       setClearedAt(new Date().toISOString());
       eventDedupKeysRef.current.clear();
       eventDedupKeyOrderRef.current = [];
+      eventCountRef.current = 0;
       setEvents([]);
       setChatScrollOffset(0);
       addNotice("Viewport cleared. Durable chat history is unchanged.", "info");

From e76327436626ba3d95197a7764194c03b3d2ab85 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 04:01:15 -0400
Subject: [PATCH 17/24] perf(agents): tighten ADE skill guidance

---
 .../main/services/chat/agentChatService.ts    |  4 +-
 .../chat/claudeSlashCommandDiscovery.test.ts  | 78 +++++++++++++------
 .../chat/claudeSlashCommandDiscovery.ts       | 11 ++-
 apps/desktop/src/shared/adeCliGuidance.ts     |  7 +-
 4 files changed, 68 insertions(+), 32 deletions(-)

diff --git a/apps/desktop/src/main/services/chat/agentChatService.ts b/apps/desktop/src/main/services/chat/agentChatService.ts
index 648cbc8db..b589c50ef 100644
--- a/apps/desktop/src/main/services/chat/agentChatService.ts
+++ b/apps/desktop/src/main/services/chat/agentChatService.ts
@@ -10090,7 +10090,7 @@ export function createAgentChatService(args: {
       ? [
           "",
           "## Project slash commands and skills",
-          "ADE walks up from the lane worktree to discover `.claude/commands/*.md` (slash commands) and `.claude/skills/<name>/SKILL.md` (skills) at every ancestor directory plus `~/.claude/`. Claude Code itself may discover some of these, but ADE also tells you about the full project-visible set here.",
+          "ADE walks up from the lane worktree to discover `.claude/commands/*.md` plus `.claude/skills/<name>/SKILL.md`, `.agents/skills/<name>/SKILL.md`, `.ade/skills/<name>/SKILL.md`, user skill roots, and ADE bundled skills. Claude Code itself may discover some of these, but ADE also tells you about the full project-visible set here.",
           "**User-invoked (`/<name>`):** When the user sends a message that is exactly `/<name>` or `/<name> <args>`, ADE may pre-expand the file's body and substitute `$ARGUMENTS` before it reaches you. You'll see the expanded instructions, not necessarily the literal `/<name>`.",
           "**Mid-sentence reference:** When the user mentions a command/skill mid-sentence, read the file at the path below and follow it.",
           "**Autonomous skill use:** If, while working on a task, you decide a discovered skill applies, read its SKILL.md file and follow it as if it had been invoked.",
@@ -13559,7 +13559,7 @@ export function createAgentChatService(args: {
         ? [
           "",
           "## Project slash commands and skills",
-          "ADE walks up from the lane worktree to discover `.claude/commands/*.md` (slash commands) and `.claude/skills/<name>/SKILL.md` (skills) at every ancestor directory plus `~/.claude/`. The Claude Agent SDK only auto-discovers `<cwd>/.claude/` and `~/.claude/`, so ADE injects the rest here.",
+          "ADE walks up from the lane worktree to discover `.claude/commands/*.md` plus `.claude/skills/<name>/SKILL.md`, `.agents/skills/<name>/SKILL.md`, `.ade/skills/<name>/SKILL.md`, user skill roots, and ADE bundled skills. The Claude Agent SDK only auto-discovers `<cwd>/.claude/` and `~/.claude/`, so ADE injects the rest here.",
           "**User-invoked (`/<name>`):** When the user sends a message that is exactly `/<name>` or `/<name> <args>`, ADE pre-expands the file's body (commands take precedence over same-named skills) and substitutes `$ARGUMENTS` before it reaches you. You'll see the expanded instructions, not the literal `/<name>`.",
           "**Mid-sentence reference:** When the user mentions a command/skill mid-sentence (e.g. \"please /audit this\", \"can you do a /security-review\") the message is NOT auto-expanded. Read the file at the path below and follow it.",
           "**Autonomous skill use:** If, while working on a task, you decide a discovered skill applies (its description matches the situation), Read its SKILL.md file and follow it as if it had been invoked. Don't ask the user — just use the skill when warranted.",
diff --git a/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.test.ts b/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.test.ts
index d8dd4975d..901253ac2 100644
--- a/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.test.ts
+++ b/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.test.ts
@@ -33,13 +33,13 @@ describe("discoverClaudeSlashCommands", () => {
       "",
     ].join("\n"));
 
-    expect(discoverClaudeSlashCommands(tmpRoot)).toMatchObject([
-      {
+    expect(discoverClaudeSlashCommands(tmpRoot)).toEqual(expect.arrayContaining([
+      expect.objectContaining({
         name: "/automate",
         description: "Generate comprehensive test suites",
         argumentHint: "[area]",
-      },
-    ]);
+      }),
+    ]));
   });
 
   it("uses nested project command paths for unambiguous discovery", () => {
@@ -54,12 +54,12 @@ describe("discoverClaudeSlashCommands", () => {
       "",
     ].join("\n"));
 
-    expect(discoverClaudeSlashCommands(tmpRoot)).toMatchObject([
-      {
+    expect(discoverClaudeSlashCommands(tmpRoot)).toEqual(expect.arrayContaining([
+      expect.objectContaining({
         name: "/frontend:test",
         description: "Run frontend tests",
-      },
-    ]);
+      }),
+    ]));
   });
 
   it("skips legacy command directories deeper than the traversal cap", () => {
@@ -84,12 +84,12 @@ describe("discoverClaudeSlashCommands", () => {
       "",
     ].join("\n"));
 
-    expect(discoverClaudeSlashCommands(tmpRoot)).toMatchObject([
-      {
+    expect(discoverClaudeSlashCommands(tmpRoot)).toEqual(expect.arrayContaining([
+      expect.objectContaining({
         name: "/level-0:level-1:level-2:level-3:level-4:level-5:level-6:level-7:level-8:level-9:visible",
         description: "Visible nested command",
-      },
-    ]);
+      }),
+    ]));
   });
 
   it("preserves command filename casing and dedupes case variants by project precedence", () => {
@@ -198,6 +198,36 @@ describe("discoverClaudeSlashCommands", () => {
     ]));
   });
 
+  it("discovers bundled ADE agent skills from the desktop resources directory in dev", () => {
+    const cwdRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ade-bundled-skills-cwd-"));
+    const skillDir = path.join(cwdRoot, "apps", "desktop", "resources", "agent-skills", "ade-cli-control-plane");
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(path.join(skillDir, "SKILL.md"), [
+      "---",
+      "name: ade-cli-control-plane",
+      "description: Operate ADE through the CLI",
+      "---",
+      "",
+      "Use ade doctor.",
+      "",
+    ].join("\n"));
+    vi.spyOn(process, "cwd").mockReturnValue(cwdRoot);
+
+    try {
+      const commands = discoverClaudeSlashCommands(tmpRoot);
+      expect(commands).toEqual(expect.arrayContaining([
+        expect.objectContaining({
+          name: "/ade-cli-control-plane",
+          description: "Operate ADE through the CLI",
+          source: "skill",
+          filePath: path.join(skillDir, "SKILL.md"),
+        }),
+      ]));
+    } finally {
+      fs.rmSync(cwdRoot, { recursive: true, force: true });
+    }
+  });
+
   it("walks up parent directories to discover .claude/commands at workspace root from a lane subdir", () => {
     const workspaceCommands = path.join(tmpRoot, ".claude", "commands");
     fs.mkdirSync(workspaceCommands, { recursive: true });
@@ -212,13 +242,13 @@ describe("discoverClaudeSlashCommands", () => {
     const laneWorktree = path.join(tmpRoot, "lanes", "feature-x", "worktree");
     fs.mkdirSync(laneWorktree, { recursive: true });
 
-    expect(discoverClaudeSlashCommands(laneWorktree)).toMatchObject([
-      {
+    expect(discoverClaudeSlashCommands(laneWorktree)).toEqual(expect.arrayContaining([
+      expect.objectContaining({
         name: "/audit",
         description: "Workspace-root audit",
         source: "command",
-      },
-    ]);
+      }),
+    ]));
   });
 
   it("walks up parent directories for resolveClaudeSlashCommandInvocation as well", () => {
@@ -270,12 +300,12 @@ describe("discoverClaudeSlashCommands", () => {
       "",
     ].join("\n"));
 
-    expect(discoverClaudeSlashCommands(tmpRoot)).toMatchObject([
-      {
+    expect(discoverClaudeSlashCommands(tmpRoot)).toEqual(expect.arrayContaining([
+      expect.objectContaining({
         name: "/ship",
         description: "Project ship",
-      },
-    ]);
+      }),
+    ]));
   });
 
   it("does not let home commands override project commands when the project is under home", () => {
@@ -285,12 +315,12 @@ describe("discoverClaudeSlashCommands", () => {
     fs.writeFileSync(path.join(homeRoot, ".claude", "commands", "audit.md"), "Personal audit.\n");
     fs.writeFileSync(path.join(projectRoot, ".claude", "commands", "audit.md"), "Project audit.\n");
 
-    expect(discoverClaudeSlashCommands(projectRoot)).toMatchObject([
-      {
+    expect(discoverClaudeSlashCommands(projectRoot)).toEqual(expect.arrayContaining([
+      expect.objectContaining({
         name: "/audit",
         description: "Project audit.",
-      },
-    ]);
+      }),
+    ]));
   });
 
   it("keeps nested commands with the same basename distinct", () => {
diff --git a/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.ts b/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.ts
index 764998058..b3e806408 100644
--- a/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.ts
+++ b/apps/desktop/src/main/services/chat/claudeSlashCommandDiscovery.ts
@@ -277,6 +277,12 @@ function bundledSkillRoots(): string[] {
   if (process.resourcesPath) {
     candidates.push(path.join(process.resourcesPath, "agent-skills"));
   }
+  candidates.push(path.resolve(process.cwd(), "resources", "agent-skills"));
+  candidates.push(path.resolve(process.cwd(), "apps", "desktop", "resources", "agent-skills"));
+  for (let depth = 0; depth < 8; depth += 1) {
+    candidates.push(path.resolve(__dirname, ...Array(depth).fill(".."), "resources", "agent-skills"));
+    candidates.push(path.resolve(__dirname, ...Array(depth).fill(".."), "apps", "desktop", "resources", "agent-skills"));
+  }
   return candidates;
 }
 
@@ -318,7 +324,10 @@ export function discoverClaudeSlashCommands(cwd: string): DiscoveredClaudeSlashC
     }
   }
 
-  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+  return [...byName.values()].sort((a, b) => {
+    if (a.source !== b.source) return a.source === "command" ? -1 : 1;
+    return a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
+  });
 }
 
 function resolveSkillFile(skillsDir: string, commandName: string): string | null {
diff --git a/apps/desktop/src/shared/adeCliGuidance.ts b/apps/desktop/src/shared/adeCliGuidance.ts
index 8a32c6a8e..7770e52ae 100644
--- a/apps/desktop/src/shared/adeCliGuidance.ts
+++ b/apps/desktop/src/shared/adeCliGuidance.ts
@@ -27,12 +27,9 @@ export const ADE_CLI_INLINE_GUIDANCE = [
   "ADE quick orientation:",
   "- ADE is a local-first desktop development environment for lanes (git worktrees), native chats, terminals, missions, PRs, memory, proof/artifacts, App Control, iOS Simulator/Preview Lab state, and lane-tied macOS VMs.",
   "- `ade` is the default control plane for ADE-managed sessions. Use shell for the immediate repo edit/test; use ADE CLI for ADE state, drawer/session state, proof registration, memory, missions, PR metadata, and managed app/simulator/VM control.",
-  "- First checks: `ade doctor --text`, `ade help <command>`, typed `ade ... --text` commands, and `ade actions list --text`. Common starts: `ade lanes list --text`, `ade chats list --text`, `ade proof status --text`.",
+  "- First checks: `ade doctor --text`, `ade help <command>`, typed `ade ... --text` commands, and `ade actions list --text`. Common starts: `ade lanes list --text`, `ade chat list --text`, `ade proof status --text`.",
   "- If `command -v ade` fails, try `${ADE_CLI_PATH:-}`, then `${ADE_CLI_BIN_DIR:-}/ade`, then `node apps/ade-cli/dist/cli.cjs ...` in an ADE source checkout after confirming it exists. The only normal reason to skip ADE CLI for an ADE action is that it is truly unreachable.",
+  "- ADE ships Agent Skills for deeper details. Read the relevant skill on demand instead of trial and error: `ade-cli-control-plane`, `ade-ios-simulator`, `ade-app-control`, `ade-browser`, `ade-pr-workflows`, `ade-lanes-git`, `ade-cto-missions`, `ade-proof-artifacts`, or `ade-macos-vm`.",
   "- Use `--socket` when the CLI and ADE desktop drawer need the same live state: App Control, iOS Simulator, Preview Lab, terminal logs, selections/context, and proof drawer updates.",
-  "- For iOS work use `ade help ios-sim`, `ade --socket ios-sim status --text`, `ade --socket ios-sim devices --text`, `ade --socket ios-sim apps --text`, `ade --socket ios-sim snapshot --text`, `ade --socket ios-sim select --x <x> --y <y>`, `ade --socket ios-sim stream-status --text`, and Preview Lab commands such as `ade --socket ios-sim preview-status --text`, `ade --socket ios-sim previews --source <swift-file> --text`, `ade --socket ios-sim preview-render --source <swift-file> --index <n> --text`. In standalone CLI sessions, use the returned inspect output directly because drawer selections only auto-inject into a chat when the session is chat-owned. Do not create symlink projects or fake schemes as a first fix for app detection; re-list ADE's launch targets and report exact build output.",
-  "- For App Control on Electron apps use `ade help app-control`, `ade --socket app-control status --text`, `ade --socket app-control launch --command ... --text`, `ade --socket app-control logs --text --max-bytes 8388608`, `ade --socket app-control snapshot --text`, `ade --socket app-control select --x <x> --y <y>`, `ade --socket app-control click`, and `ade --socket app-control type`.",
-  "- For ADE browser use `ade help browser`, `ade --socket browser panel --text`, `ade --socket browser status --text`, `ade --socket browser open <url> --new-tab --text`, `ade --socket browser switch --tab <id> --text`, `ade --socket browser screenshot --text`, and `ade --socket browser inspect-start --text` / `ade --socket browser select-current --text`. The ADE browser is global, not lane-scoped.",
-  "- For macOS VM work use `ade help macos-vm`, `ade --socket macos-vm status --lane <lane> --text`, `ade --socket macos-vm start --lane <lane> --create --text`, `ade --socket macos-vm guide --lane <lane> --text`, `ade --socket macos-vm screenshot --lane <lane> --text`, `ade --socket macos-vm select --lane <lane> --x <x> --y <y> --text`, `ade --socket macos-vm click --lane <lane> <x> <y>`, and `ade --socket macos-vm type --lane <lane> --value <text>`; keep code edits under the guest shared path.",
   "- If a live app/simulator/session is missing, report the exact blocker instead of guessing. When asked for proof, register artifacts with `ade proof ...` so they appear in the ADE proof drawer, and clean up old, stale, or finished processes before leaving the task.",
 ].join("\n");

From 32cf9c7ce458b95ebcd9fef0ae8a50f7bf25b4e8 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 04:01:21 -0400
Subject: [PATCH 18/24] perf(prs): target detail refresh work

---
 .../src/main/services/prs/prService.test.ts   | 70 +++++++++++++
 .../src/main/services/prs/prService.ts        | 65 ++++++------
 .../src/renderer/components/prs/PRsPage.tsx   | 10 +-
 .../PrDetailPane.issueResolver.test.tsx       | 18 ++++
 .../components/prs/detail/PrDetailPane.tsx    | 99 ++++++++++++++++---
 .../components/prs/state/PrsContext.test.tsx  | 33 +++++++
 .../components/prs/state/PrsContext.tsx       | 18 +++-
 .../components/prs/tabs/GitHubTab.tsx         | 23 +++--
 8 files changed, 279 insertions(+), 57 deletions(-)

diff --git a/apps/desktop/src/main/services/prs/prService.test.ts b/apps/desktop/src/main/services/prs/prService.test.ts
index d1646819d..8f75b6e90 100644
--- a/apps/desktop/src/main/services/prs/prService.test.ts
+++ b/apps/desktop/src/main/services/prs/prService.test.ts
@@ -1101,6 +1101,76 @@ describe("prService.refresh", () => {
   });
 });
 
+describe("prService.getActionRuns", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("bounds action run history and only hydrates jobs for the newest runs", async () => {
+    const row = makePrRow({ id: "pr-actions", github_pr_number: 90 });
+    const db = makeMockDb();
+    db.get.mockImplementation((sql: string, params: unknown[]) => {
+      const text = String(sql);
+      if (text.includes("from pull_requests") && text.includes("where id = ?")) {
+        return params[0] === row.id ? row : null;
+      }
+      return null;
+    });
+    const workflowRuns = Array.from({ length: 20 }, (_, index) => ({
+      id: index + 1,
+      name: `run-${index + 1}`,
+      status: "completed",
+      conclusion: "success",
+      html_url: `https://github.com/test-owner/test-repo/actions/runs/${index + 1}`,
+      created_at: `2026-01-01T00:${String(index).padStart(2, "0")}:00Z`,
+      updated_at: `2026-01-01T00:${String(index).padStart(2, "0")}:30Z`,
+    }));
+    const githubService = makeGithubService({
+      apiRequest: vi.fn(async (args: { path: string }) => {
+        if (args.path === "/repos/test-owner/test-repo/pulls/90") {
+          return { data: makeGitHubPull({ number: 90, head: { ref: "my-feature", sha: "head-sha" } }) };
+        }
+        if (args.path === "/repos/test-owner/test-repo/actions/runs") {
+          return { data: { workflow_runs: workflowRuns } };
+        }
+        const jobMatch = args.path.match(/\/actions\/runs\/(\d+)\/jobs$/);
+        if (jobMatch) {
+          const runId = Number(jobMatch[1]);
+          return {
+            data: {
+              jobs: [{
+                id: runId * 100,
+                name: `job-${runId}`,
+                status: "completed",
+                conclusion: "success",
+                steps: [],
+              }],
+            },
+          };
+        }
+        throw new Error(`Unexpected GitHub API path: ${args.path}`);
+      }),
+    });
+    const { service } = buildService({ db, githubService });
+
+    const runs = await service.getActionRuns("pr-actions");
+
+    expect(runs).toHaveLength(12);
+    expect(runs[0]?.jobs).toHaveLength(1);
+    expect(runs[5]?.jobs).toHaveLength(1);
+    expect(runs[6]?.jobs).toHaveLength(0);
+    const calls: Array<{ path: string; query?: Record<string, unknown> }> =
+      (githubService.apiRequest as ReturnType<typeof vi.fn>).mock.calls.map((call: unknown[]) =>
+        call[0] as { path: string; query?: Record<string, unknown> }
+      );
+    expect(calls.find((call) => call.path === "/repos/test-owner/test-repo/actions/runs")?.query).toEqual({
+      head_sha: "head-sha",
+      per_page: 12,
+    });
+    expect(calls.filter((call) => /\/actions\/runs\/\d+\/jobs$/.test(call.path))).toHaveLength(6);
+  });
+});
+
 describe("prService merge contexts", () => {
   beforeEach(() => {
     vi.clearAllMocks();
diff --git a/apps/desktop/src/main/services/prs/prService.ts b/apps/desktop/src/main/services/prs/prService.ts
index 05b2d816e..c9ae1c696 100644
--- a/apps/desktop/src/main/services/prs/prService.ts
+++ b/apps/desktop/src/main/services/prs/prService.ts
@@ -179,6 +179,8 @@ type LanePrLookupRow = {
 };
 
 const SQL_IN_CLAUSE_CHUNK_SIZE = 900;
+const PR_ACTION_RUNS_LIMIT = 12;
+const PR_ACTION_RUN_JOBS_LIMIT = 6;
 
 function chunkValues<T>(values: readonly T[], size = SQL_IN_CLAUSE_CHUNK_SIZE): T[][] {
   const chunks: T[][] = [];
@@ -6421,40 +6423,45 @@ export function createPrService({
       const { data: runsData } = await githubService.apiRequest<any>({
         method: "GET",
         path: `/repos/${repo.owner}/${repo.name}/actions/runs`,
-        query: { head_sha: headSha, per_page: 100 }
+        query: { head_sha: headSha, per_page: PR_ACTION_RUNS_LIMIT }
       });
-      const rawRuns: any[] = Array.isArray(runsData?.workflow_runs) ? runsData.workflow_runs : [];
+      const rawRuns: any[] = Array.isArray(runsData?.workflow_runs)
+        ? runsData.workflow_runs.slice(0, PR_ACTION_RUNS_LIMIT)
+        : [];
 
       const runs: PrActionRun[] = await Promise.all(
-        rawRuns.map(async (run: any): Promise<PrActionRun> => {
+        rawRuns.map(async (run: any, index): Promise<PrActionRun> => {
           const runId = Number(run?.id);
           let jobs: PrActionJob[] = [];
-          try {
-            const { data: jobsData } = await githubService.apiRequest<any>({
-              method: "GET",
-              path: `/repos/${repo.owner}/${repo.name}/actions/runs/${runId}/jobs`
-            });
-            const rawJobs: any[] = Array.isArray(jobsData?.jobs) ? jobsData.jobs : [];
-            jobs = rawJobs.map((j: any): PrActionJob => ({
-              id: Number(j?.id) || 0,
-              name: asString(j?.name) || "",
-              status: toJobStatus(j?.status),
-              conclusion: toJobConclusion(j?.conclusion),
-              startedAt: asString(j?.started_at) || null,
-              completedAt: asString(j?.completed_at) || null,
-              steps: Array.isArray(j?.steps)
-                ? j.steps.map((st: any): PrActionStep => ({
-                    name: asString(st?.name) || "",
-                    status: toJobStatus(st?.status),
-                    conclusion: toJobConclusion(st?.conclusion),
-                    number: Number(st?.number) || 0,
-                    startedAt: asString(st?.started_at) || null,
-                    completedAt: asString(st?.completed_at) || null
-                  }))
-                : []
-            }));
-          } catch {
-            // Jobs fetch failed; return empty jobs array
+          if (runId > 0 && index < PR_ACTION_RUN_JOBS_LIMIT) {
+            try {
+              const { data: jobsData } = await githubService.apiRequest<any>({
+                method: "GET",
+                path: `/repos/${repo.owner}/${repo.name}/actions/runs/${runId}/jobs`,
+                query: { per_page: 100 }
+              });
+              const rawJobs: any[] = Array.isArray(jobsData?.jobs) ? jobsData.jobs : [];
+              jobs = rawJobs.map((j: any): PrActionJob => ({
+                id: Number(j?.id) || 0,
+                name: asString(j?.name) || "",
+                status: toJobStatus(j?.status),
+                conclusion: toJobConclusion(j?.conclusion),
+                startedAt: asString(j?.started_at) || null,
+                completedAt: asString(j?.completed_at) || null,
+                steps: Array.isArray(j?.steps)
+                  ? j.steps.map((st: any): PrActionStep => ({
+                      name: asString(st?.name) || "",
+                      status: toJobStatus(st?.status),
+                      conclusion: toJobConclusion(st?.conclusion),
+                      number: Number(st?.number) || 0,
+                      startedAt: asString(st?.started_at) || null,
+                      completedAt: asString(st?.completed_at) || null
+                    }))
+                  : []
+              }));
+            } catch {
+              // Jobs fetch failed; return empty jobs array
+            }
           }
           return {
             id: runId,
diff --git a/apps/desktop/src/renderer/components/prs/PRsPage.tsx b/apps/desktop/src/renderer/components/prs/PRsPage.tsx
index 73d82547a..96be9b62a 100644
--- a/apps/desktop/src/renderer/components/prs/PRsPage.tsx
+++ b/apps/desktop/src/renderer/components/prs/PRsPage.tsx
@@ -22,6 +22,7 @@ import { resolveRouteRebaseSelection } from "./shared/rebaseNeedUtils";
 import type { PrSummary } from "../../../shared/types";
 
 type SurfaceMode = "github" | "workflows";
+type PrRefreshArgs = { prId?: string; prIds?: string[] };
 
 const LAST_WORKFLOW_TAB_KEY = "ade:prs:lastWorkflowTab";
 
@@ -99,12 +100,13 @@ function PRsPageInner() {
     }
   }, [activeTab, projectRoot]);
 
-  const handleRefresh = React.useCallback(async () => {
+  const handleRefresh = React.useCallback(async (args: PrRefreshArgs = {}) => {
+    const targeted = Boolean(args.prId || (args.prIds?.length ?? 0) > 0);
     await Promise.all([
-      refresh(),
-      refreshLanes({ includeStatus: false, includeSnapshots: false }).catch(() => {}),
+      refresh(args),
+      targeted ? Promise.resolve() : refreshLanes({ includeStatus: false, includeSnapshots: false }).catch(() => {}),
     ]);
-    setIntegrationRefreshNonce((prev) => prev + 1);
+    if (!targeted) setIntegrationRefreshNonce((prev) => prev + 1);
   }, [refresh, refreshLanes]);
 
   const openCreatePr = React.useCallback(() => setCreatePrOpen(true), []);
diff --git a/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.issueResolver.test.tsx b/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.issueResolver.test.tsx
index ed265da84..2f6020948 100644
--- a/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.issueResolver.test.tsx
+++ b/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.issueResolver.test.tsx
@@ -800,6 +800,22 @@ describe("PrDetailPane issue resolver CTA", () => {
     expect(screen.queryByText("Cached review body")).toBeNull();
   });
 
+  it("targets the selected PR when refreshing detail manually", async () => {
+    const user = userEvent.setup();
+    const { onRefresh } = renderPane({
+      checks: [],
+      reviewThreads: [],
+      actionRuns: [],
+    });
+    onRefresh.mockClear();
+
+    await user.click(screen.getByTitle("Refresh"));
+
+    await waitFor(() => {
+      expect(onRefresh).toHaveBeenCalledWith({ prId: "pr-80" });
+    });
+  });
+
   it("refreshes detail-side action runs when the selected PR status changes", async () => {
     const user = userEvent.setup();
     const { getActionRuns, rerenderPane } = renderPane({
@@ -1652,6 +1668,7 @@ describe("PrDetailPane issue resolver CTA", () => {
   });
 
   it("renders review activity bodies as markdown instead of raw source text", async () => {
+    const user = userEvent.setup();
     renderPane({
       checks: [makeCheck()],
       reviewThreads: [],
@@ -1668,6 +1685,7 @@ describe("PrDetailPane issue resolver CTA", () => {
       ],
     });
 
+    await user.click(screen.getByRole("button", { name: /activity/i }));
     expect(await screen.findByText("Actionable comments posted: 3")).toBeTruthy();
     expect(screen.queryByText(/\*\*Actionable comments posted: 3\*\*/)).toBeNull();
     expect(screen.getByText("Prompt for AI Agents")).toBeTruthy();
diff --git a/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.tsx b/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.tsx
index 8188584cf..87f9ffc5b 100644
--- a/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.tsx
+++ b/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.tsx
@@ -289,6 +289,57 @@ function activityEventColor(ev: PrActivityEvent): string {
   return COLORS.textMuted;
 }
 
+function buildActivityFromLoadedDetail(
+  checks: PrCheck[],
+  reviews: PrReview[],
+  comments: PrComment[],
+): PrActivityEvent[] {
+  const events: PrActivityEvent[] = [];
+  for (const comment of comments) {
+    events.push({
+      id: `comment-${comment.id}`,
+      type: "comment",
+      author: comment.author,
+      avatarUrl: comment.authorAvatarUrl ?? null,
+      body: comment.body,
+      timestamp: comment.createdAt ?? "",
+      metadata: {
+        source: comment.source,
+        path: comment.path,
+        line: comment.line,
+        url: comment.url,
+      },
+    });
+  }
+  for (const review of reviews) {
+    events.push({
+      id: `review-${review.reviewer}-${review.submittedAt ?? ""}`,
+      type: "review",
+      author: review.reviewer,
+      avatarUrl: review.reviewerAvatarUrl ?? null,
+      body: review.body,
+      timestamp: review.submittedAt ?? "",
+      metadata: { state: review.state },
+    });
+  }
+  for (const check of checks) {
+    events.push({
+      id: `ci-${check.name}`,
+      type: "ci_run",
+      author: "github-actions",
+      avatarUrl: null,
+      body: `${check.name}: ${check.conclusion ?? check.status}`,
+      timestamp: check.startedAt ?? check.completedAt ?? "",
+      metadata: {
+        status: check.status,
+        conclusion: check.conclusion,
+        detailsUrl: check.detailsUrl,
+      },
+    });
+  }
+  return events.sort((a, b) => Date.parse(b.timestamp || "0") - Date.parse(a.timestamp || "0"));
+}
+
 function activityEventLabel(ev: PrActivityEvent): string {
   if (ev.type === "comment") return ev.metadata?.source === "review" ? "review comment" : "comment";
   if (ev.type === "review") return "review";
@@ -427,7 +478,7 @@ type PrDetailPaneProps = {
   detailBusy: boolean;
   lanes: LaneSummary[];
   mergeMethod: MergeMethod;
-  onRefresh: () => Promise<void>;
+  onRefresh: (args?: { prId?: string; prIds?: string[] }) => Promise<void>;
   onNavigate: (path: string) => void;
   onShowInGraph?: (laneId: string) => void;
   onOpenRebaseTab?: (laneId?: string) => void;
@@ -504,6 +555,10 @@ export function PrDetailPane({
   const checks = liveDetailReady ? liveChecks : (hasSnapshotDetail ? snapshotChecks : liveChecks);
   const reviews = liveDetailReady ? liveReviews : (hasSnapshotDetail ? snapshotReviews : liveReviews);
   const comments = liveDetailReady ? liveComments : (hasSnapshotDetail ? snapshotComments : liveComments);
+  const loadedDetailActivityRef = React.useRef({ checks, reviews, comments });
+  React.useEffect(() => {
+    loadedDetailActivityRef.current = { checks, reviews, comments };
+  }, [checks, comments, reviews]);
 
   const setActiveTab = React.useCallback((tab: DetailTab) => {
     setActiveTabState(tab);
@@ -798,19 +853,19 @@ export function PrDetailPane({
           applySnapshotHydration(cachedSnapshot);
         }
       }
-      const [d, f, c, a, act] = await Promise.all([
+      const [d, f, c, a] = await Promise.all([
         window.ade.prs.getDetail(pr.id).catch(() => null),
         window.ade.prs.getFiles(pr.id).catch(() => []),
         (window.ade.prs.getCommits?.(pr.id) ?? Promise.resolve([])).catch(() => []),
         window.ade.prs.getActionRuns(pr.id).catch(() => []),
-        window.ade.prs.getActivity(pr.id).catch(() => []),
       ]);
       if (requestId !== detailLoadSeqRef.current) return;
       setDetail(d);
       setFiles(f);
       setCommits(c);
       setActionRuns(a);
-      setActivity(act);
+      const loaded = loadedDetailActivityRef.current;
+      setActivity((prev) => prev.length > 0 ? prev : buildActivityFromLoadedDetail(loaded.checks, loaded.reviews, loaded.comments));
     } catch {
       // silently fail - basic data still available from context
     }
@@ -855,6 +910,7 @@ export function PrDetailPane({
     setShowLabelEditor(false);
     setShowReviewerEditor(false);
     setShowReviewModal(false);
+    setActivity([]);
 
     const requestId = ++convergenceLoadSeqRef.current;
     const cachedRuntime = cachedConvergenceRuntimeRef.current;
@@ -897,31 +953,52 @@ export function PrDetailPane({
     void refreshReviewThreads();
   }, [loadDetail, pr.checksStatus, pr.id, pr.reviewStatus, pr.updatedAt, refreshReviewThreads]);
 
-  // Poll checks + actionRuns + activity + reviewThreads every 60s so the
+  React.useEffect(() => {
+    setActivity((prev) => prev.length > 0 ? prev : buildActivityFromLoadedDetail(checks, reviews, comments));
+  }, [checks, comments, pr.id, reviews]);
+
+  React.useEffect(() => {
+    const shouldLoadImmediately = activeTab === "activity" || Boolean(deepLinkState.eventId);
+    if (!shouldLoadImmediately) return undefined;
+    let cancelled = false;
+    window.ade.prs.getActivity(pr.id).then((events) => {
+      if (!cancelled) setActivity(events);
+    }).catch(() => {});
+    return () => {
+      cancelled = true;
+    };
+  }, [activeTab, deepLinkState.eventId, pr.id]);
+
+  // Poll checks + actionRuns + reviewThreads every 60s so the
   // Path to Merge readiness panel stays fresh without requiring a manual refresh.
+  // Full activity fetches include comments/reviews/checks again, so only do that
+  // while the Activity tab is actually visible.
   React.useEffect(() => {
     let cancelled = false;
     const id = window.setInterval(() => {
+      const activityPromise = activeTab === "activity"
+        ? window.ade.prs.getActivity(pr.id)
+        : Promise.resolve(null);
       Promise.allSettled([
         window.ade.prs.getChecks(pr.id),
         window.ade.prs.getActionRuns(pr.id),
-        window.ade.prs.getActivity(pr.id),
         window.ade.prs.getReviewThreads(pr.id),
-      ]).then(([checksResult, arResult, actResult, thrResult]) => {
+        activityPromise,
+      ]).then(([checksResult, arResult, thrResult, actResult]) => {
         if (cancelled) return;
         if (checksResult.status === "fulfilled" && checksResult.value.length > 0) {
           setConvergenceChecks(checksResult.value);
         }
         if (arResult.status === "fulfilled") setActionRuns(arResult.value);
-        if (actResult.status === "fulfilled") setActivity(actResult.value);
         if (thrResult.status === "fulfilled") setReviewThreads(thrResult.value);
+        if (actResult.status === "fulfilled" && actResult.value) setActivity(actResult.value);
       });
     }, 60_000);
     return () => {
       cancelled = true;
       window.clearInterval(id);
     };
-  }, [pr.id]);
+  }, [activeTab, pr.id]);
 
   React.useEffect(() => {
     if (!issueResolverCopyNotice) return;
@@ -1155,12 +1232,12 @@ export function PrDetailPane({
   }, [checks, pr.id, pr.state]);
 
   const refreshDetailSurface = React.useCallback(async (options: { includeInventory?: boolean } = {}) => {
-    const tasks: Array<Promise<unknown>> = [onRefresh(), loadDetail(), refreshReviewThreads()];
+    const tasks: Array<Promise<unknown>> = [onRefresh({ prId: pr.id }), loadDetail(), refreshReviewThreads()];
     if (options.includeInventory && pr.state !== "merged" && pr.state !== "closed") {
       tasks.push(syncInventory());
     }
     await Promise.all(tasks);
-  }, [loadDetail, onRefresh, pr.state, refreshReviewThreads, syncInventory]);
+  }, [loadDetail, onRefresh, pr.id, pr.state, refreshReviewThreads, syncInventory]);
 
   const handleRefresh = React.useCallback(async () => {
     try {
diff --git a/apps/desktop/src/renderer/components/prs/state/PrsContext.test.tsx b/apps/desktop/src/renderer/components/prs/state/PrsContext.test.tsx
index b129b7fb6..37554c25d 100644
--- a/apps/desktop/src/renderer/components/prs/state/PrsContext.test.tsx
+++ b/apps/desktop/src/renderer/components/prs/state/PrsContext.test.tsx
@@ -23,6 +23,18 @@ function Harness() {
   );
 }
 
+function TargetedRefreshHarness() {
+  const { refresh, loading } = usePrs();
+  return (
+    <div>
+      <button type="button" onClick={() => void refresh({ prId: "pr-1" })}>
+        refresh pr-1
+      </button>
+      <div data-testid="loading">{loading ? "loading" : "idle"}</div>
+    </div>
+  );
+}
+
 function RouteHarness() {
   const { activeTab, selectedPrId, selectedQueueGroupId, selectedRebaseItemId } = usePrs();
   return (
@@ -212,6 +224,27 @@ describe("PrsContext refresh", () => {
     });
   });
 
+  it("passes targeted PR refresh requests through to the PR service", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <PrsProvider>
+        <TargetedRefreshHarness />
+      </PrsProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("loading").textContent).toBe("idle");
+    });
+    expect(window.ade.prs.refresh).not.toHaveBeenCalled();
+
+    await user.click(screen.getByRole("button", { name: "refresh pr-1" }));
+
+    await waitFor(() => {
+      expect(window.ade.prs.refresh).toHaveBeenCalledWith({ prId: "pr-1" });
+    });
+  });
+
   it("does not run a GitHub PR refresh just because the local PR tab changes", async () => {
     const user = userEvent.setup();
 
diff --git a/apps/desktop/src/renderer/components/prs/state/PrsContext.tsx b/apps/desktop/src/renderer/components/prs/state/PrsContext.tsx
index 5b4753153..784840e1f 100644
--- a/apps/desktop/src/renderer/components/prs/state/PrsContext.tsx
+++ b/apps/desktop/src/renderer/components/prs/state/PrsContext.tsx
@@ -114,7 +114,7 @@ type PrsContextValue = PrsState & {
   loadConvergenceState: (prId: string, options?: { force?: boolean }) => Promise<PrConvergenceState>;
   saveConvergenceState: (prId: string, state: PrConvergenceStatePatch) => Promise<PrConvergenceState>;
   resetConvergenceState: (prId: string) => Promise<void>;
-  refresh: () => Promise<void>;
+  refresh: (args?: { prId?: string; prIds?: string[] }) => Promise<void>;
 
   // Timeline + rails controls
   setPrsTimelineRailsEnabled: (enabled: boolean) => void;
@@ -772,6 +772,7 @@ export function PrsProvider({ children }: { children: React.ReactNode }) {
   const refreshCore = useCallback(async (options: {
     skipFreshWarmCache?: boolean;
     githubRefreshMode?: "await" | "background";
+    githubRefreshArgs?: { prId?: string; prIds?: string[] };
   } = {}) => {
     if (refreshInFlight.current) {
       refreshPending.current = true;
@@ -796,7 +797,7 @@ export function PrsProvider({ children }: { children: React.ReactNode }) {
     setError(null);
     try {
       if (options.githubRefreshMode === "await") {
-        await window.ade.prs.refresh().catch(() => {});
+        await window.ade.prs.refresh(options.githubRefreshArgs).catch(() => {});
       }
       const shouldLoadWorkflowDiagnostics =
         activeTabRef.current !== "normal" || selectedPrIdRef.current !== null || currentRouteRequestsPrDiagnostics();
@@ -827,8 +828,17 @@ export function PrsProvider({ children }: { children: React.ReactNode }) {
     }
   }, [applyLocalPrState]);
 
-  const refresh = useCallback(async () => {
-    await refreshCore({ githubRefreshMode: "await" });
+  const refresh = useCallback(async (args: { prId?: string; prIds?: string[] } = {}) => {
+    const prIds = [
+      ...(args.prId ? [args.prId] : []),
+      ...(args.prIds ?? []),
+    ].map((prId) => String(prId ?? "").trim()).filter(Boolean);
+    const githubRefreshArgs = prIds.length === 1
+      ? { prId: prIds[0] }
+      : prIds.length > 1
+        ? { prIds }
+        : undefined;
+    await refreshCore({ githubRefreshMode: "await", githubRefreshArgs });
   }, [refreshCore]);
 
   // Initial load
diff --git a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
index aadc33f00..3d99c77f6 100644
--- a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
+++ b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
@@ -27,7 +27,7 @@ type GitHubTabProps = {
   onSelectPr: (id: string | null) => void;
   selectedDetailTab?: PrDetailRouteTab | null;
   onDetailTabChange?: (tab: PrDetailRouteTab) => void;
-  onRefreshAll: () => Promise<void>;
+  onRefreshAll: (args?: { prId?: string; prIds?: string[] }) => Promise<void>;
   onOpenRebaseTab?: (laneId?: string) => void;
   onOpenQueueView?: (groupId: string) => void;
 };
@@ -738,19 +738,24 @@ export function GitHubTab({
     };
   }, [mergeContextByPrId, selectedLinkedPr]);
 
-  const handleSync = React.useCallback(async () => {
+  const handleSync = React.useCallback(async (args: { prId?: string; prIds?: string[] } = {}) => {
     setSyncing(true);
     startHotRefreshWindow();
     try {
+      const targeted = Boolean(args.prId || (args.prIds?.length ?? 0) > 0);
       const includeExternalClosed =
         externalHistoryLoadedRef.current || filterRef.current !== "open";
-      await Promise.all([
-        onRefreshAll().catch(() => {}),
-        loadSnapshot({
-          force: true,
-          ...(includeExternalClosed ? { includeExternalClosed: true } : {}),
-        }),
-      ]);
+      if (targeted) {
+        await onRefreshAll(args).catch(() => {});
+      } else {
+        await Promise.all([
+          onRefreshAll().catch(() => {}),
+          loadSnapshot({
+            force: true,
+            ...(includeExternalClosed ? { includeExternalClosed: true } : {}),
+          }),
+        ]);
+      }
     } finally {
       setSyncing(false);
     }

From ade313c9bc2932f20f4c0556e677df2547a85a05 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 04:01:24 -0400
Subject: [PATCH 19/24] fix(work): reveal group runs and narrow conflicts

---
 .../components/files/FilesPage.test.tsx       | 39 +++++++-
 .../renderer/components/files/FilesPage.tsx   | 33 +++++--
 .../renderer/components/run/RunPage.test.tsx  | 70 +++++++++++++
 .../src/renderer/components/run/RunPage.tsx   | 97 +++++++++++++++----
 4 files changed, 209 insertions(+), 30 deletions(-)

diff --git a/apps/desktop/src/renderer/components/files/FilesPage.test.tsx b/apps/desktop/src/renderer/components/files/FilesPage.test.tsx
index 488586973..96d41f581 100644
--- a/apps/desktop/src/renderer/components/files/FilesPage.test.tsx
+++ b/apps/desktop/src/renderer/components/files/FilesPage.test.tsx
@@ -207,11 +207,11 @@ function LanesNavCapture() {
   return <div data-testid="lanes-nav">{`${loc.pathname}${loc.search}`}</div>;
 }
 
-function renderFilesPage(initialState?: Record<string, unknown>) {
+function renderFilesPage(initialState?: Record<string, unknown>, props?: React.ComponentProps<typeof FilesPage>) {
   return render(
     <MemoryRouter initialEntries={[{ pathname: "/files", state: initialState }]}>
       <Routes>
-        <Route path="/files" element={<FilesPage />} />
+        <Route path="/files" element={<FilesPage {...props} />} />
         <Route path="/lanes" element={<LanesNavCapture />} />
       </Routes>
     </MemoryRouter>,
@@ -556,6 +556,41 @@ describe("FilesPage", () => {
     expect(screen.queryByTestId("mock-monaco-editor")).toBeNull();
   });
 
+  it("stacks merge conflict panes when Files is embedded in a narrow Work drawer", async () => {
+    fileContents["src/index.ts"] = [
+      "export function title() {",
+      "<<<<<<< HEAD",
+      "  return \"ours\";",
+      "=======",
+      "  return \"theirs\";",
+      ">>>>>>> feature",
+      "}",
+      "",
+    ].join("\n");
+
+    renderFilesPage(
+      {
+        openFilePath: "src/index.ts",
+        preferPrimaryWorkspace: true,
+      },
+      { embedded: true },
+    );
+
+    await waitForEditorText("<<<<<<< HEAD");
+    fireEvent.click(screen.getByRole("button", { name: "MERGE" }));
+
+    const layout = await screen.findByTestId("files-conflict-layout");
+    expect(layout.getAttribute("data-layout")).toBe("stacked");
+    expect(layout.className).toContain("flex-col");
+    expect(layout.style.gridTemplateColumns).toBe("");
+
+    const hunks = screen.getByTestId("files-conflict-hunks");
+    expect(hunks.style.maxHeight).toBe("42%");
+    const mergeEditor = screen.getAllByRole("textbox")
+      .find((node): node is HTMLTextAreaElement => node instanceof HTMLTextAreaElement);
+    expect(mergeEditor?.value).toContain("<<<<<<< HEAD");
+  });
+
   it("remaps clean open tabs when files are renamed", async () => {
     renderFilesPage({
       openFilePath: "src/index.ts",
diff --git a/apps/desktop/src/renderer/components/files/FilesPage.tsx b/apps/desktop/src/renderer/components/files/FilesPage.tsx
index 5c17523ab..3bcf27cb2 100644
--- a/apps/desktop/src/renderer/components/files/FilesPage.tsx
+++ b/apps/desktop/src/renderer/components/files/FilesPage.tsx
@@ -2012,8 +2012,26 @@ export function FilesPage({
                 </div>
               )
             ) : (
-              <div className="grid h-full" style={{ gridTemplateColumns: "300px 1fr" }}>
-                <div style={{ padding: 12, borderRight: `1px solid ${COLORS.border}`, background: COLORS.cardBg }}>
+              <div
+                data-testid="files-conflict-layout"
+                data-layout={embedded ? "stacked" : "split"}
+                className={cn(
+                  "h-full min-h-0 min-w-0",
+                  embedded ? "flex flex-col" : "grid",
+                )}
+                style={embedded ? undefined : { gridTemplateColumns: "minmax(220px, 300px) minmax(0, 1fr)" }}
+              >
+                <div
+                  data-testid="files-conflict-hunks"
+                  className="min-h-0 min-w-0 overflow-auto"
+                  style={{
+                    padding: 12,
+                    borderRight: embedded ? "none" : `1px solid ${COLORS.border}`,
+                    borderBottom: embedded ? `1px solid ${COLORS.border}` : "none",
+                    background: COLORS.cardBg,
+                    maxHeight: embedded ? "42%" : undefined,
+                  }}
+                >
                   <div className="flex items-center justify-between" style={{ marginBottom: 10 }}>
                     <span style={{ ...LABEL_STYLE }}>CONFLICT HUNKS</span>
                     <span style={inlineBadge(
@@ -2067,7 +2085,7 @@ export function FilesPage({
                     ) : null}
                   </div>
                 </div>
-                <div className="h-full">
+                <div className="h-full min-h-0 min-w-0 flex-1">
                   <textarea
                     value={activeTab?.content ?? ""}
                     onChange={(e) => {
@@ -2075,7 +2093,7 @@ export function FilesPage({
                       setOpenTabs((prev) => prev.map((tab) => (tab.path === activeTab.path ? { ...tab, content: e.target.value } : tab)));
                     }}
                     style={{
-                      height: "100%", width: "100%", resize: "none", padding: 12,
+                      height: "100%", width: "100%", minWidth: 0, resize: "none", padding: 12,
                       fontFamily: MONO_FONT, fontSize: 12, outline: "none",
                       background: COLORS.recessedBg, color: COLORS.textPrimary, border: "none",
                     }}
@@ -2093,7 +2111,8 @@ export function FilesPage({
     searchQuery, inlineRenameRequest, selectedTreeNodePath, conflictHunks, editorTheme, editorModeHint,
     resolvedConflictKeys, createFileAt, createDirectoryAt, saveActive,
     closeTab, stagePath, unstagePath, discardPath, openFile, setShowQuickOpen, navigate,
-    applyConflictResolution, setEditorHostRef, workspaceComparisonRoot, toggleDirectory, renamePathTo
+    applyConflictResolution, setEditorHostRef, workspaceComparisonRoot, toggleDirectory, renamePathTo,
+    embedded
   ]);
 
   const renderPane = useCallback((paneId: keyof typeof paneConfigs) => {
@@ -2120,7 +2139,7 @@ export function FilesPage({
             background: "linear-gradient(180deg, color-mix(in srgb, var(--color-fg) 2%, transparent), transparent)",
           }}
         >
-          <div className="flex min-w-0 items-center gap-2">
+          <div className="flex min-w-0 flex-1 items-center gap-2">
             {Icon ? <Icon size={14} weight="fill" style={{ color: COLORS.accent }} /> : null}
             <span style={{ fontFamily: MONO_FONT, fontSize: 10, fontWeight: 700, letterSpacing: "1px", color: COLORS.textSecondary }}>
               {config.title.toUpperCase()}
@@ -2135,7 +2154,7 @@ export function FilesPage({
               </span>
             ) : null}
           </div>
-          <div className="ml-auto flex shrink-0 items-center gap-2">
+          <div className="ml-auto flex min-w-0 shrink items-center justify-end gap-2 overflow-x-auto">
             {config.headerActions}
           </div>
         </div>
diff --git a/apps/desktop/src/renderer/components/run/RunPage.test.tsx b/apps/desktop/src/renderer/components/run/RunPage.test.tsx
index 0ed00f24d..7d7152e0b 100644
--- a/apps/desktop/src/renderer/components/run/RunPage.test.tsx
+++ b/apps/desktop/src/renderer/components/run/RunPage.test.tsx
@@ -399,6 +399,76 @@ describe("RunPage Advanced lane runtime drawer", () => {
     expect((await screen.findByTestId("terminal-view")).textContent).toBe("terminal-run:pty-run");
   });
 
+  it("reveals and selects a terminal started from a group run event", async () => {
+    const { handlers } = installAdeStub();
+    const group = { id: "group-dev", name: "Dev" };
+    const definitions = [
+      {
+        id: "proc-1",
+        name: "API",
+        command: ["npm", "run", "api"],
+        cwd: ".",
+        env: {},
+        groupIds: [group.id],
+        autostart: false,
+        restart: "never",
+        gracefulShutdownMs: 7000,
+        dependsOn: [],
+        readiness: { type: "none" as const },
+      },
+      {
+        id: "proc-2",
+        name: "Web",
+        command: ["npm", "run", "web"],
+        cwd: ".",
+        env: {},
+        groupIds: [group.id],
+        autostart: false,
+        restart: "never",
+        gracefulShutdownMs: 7000,
+        dependsOn: [],
+        readiness: { type: "none" as const },
+      },
+    ];
+    const ade = (window as unknown as { ade: {
+      projectConfig: { get: ReturnType<typeof vi.fn> };
+      processes: { listDefinitions: ReturnType<typeof vi.fn>; startGroup: ReturnType<typeof vi.fn> };
+    } }).ade;
+    ade.projectConfig.get.mockResolvedValue({
+      effective: { processGroups: [group] },
+      shared: { processGroups: [group], processes: definitions },
+      local: { processGroups: [], processes: [] },
+    });
+    ade.processes.listDefinitions.mockResolvedValue(definitions);
+    ade.processes.startGroup.mockResolvedValue(undefined);
+
+    render(<RunPage />);
+    fireEvent.click(await screen.findByRole("button", { name: /Dev\s*2/i }));
+    fireEvent.click(screen.getByRole("button", { name: /run all/i }));
+
+    await waitFor(() => {
+      expect(ade.processes.startGroup).toHaveBeenCalledWith({
+        groupId: "group-dev",
+        laneByProcessId: { "proc-1": "lane-a", "proc-2": "lane-a" },
+      });
+    });
+
+    await act(async () => {
+      handlers.process?.({
+        type: "runtime",
+        runtime: {
+          ...baseRuntime,
+          runId: "run-2",
+          processId: "proc-2",
+          sessionId: "terminal-group",
+          ptyId: "pty-group",
+        },
+      });
+    });
+
+    expect((await screen.findByTestId("terminal-view")).textContent).toBe("terminal-group:pty-group");
+  });
+
   it("keeps the project root cwd when saving a new command", async () => {
     const ade = (window as unknown as {
       ade: {
diff --git a/apps/desktop/src/renderer/components/run/RunPage.tsx b/apps/desktop/src/renderer/components/run/RunPage.tsx
index a3b81a9fe..2e6265cc9 100644
--- a/apps/desktop/src/renderer/components/run/RunPage.tsx
+++ b/apps/desktop/src/renderer/components/run/RunPage.tsx
@@ -267,6 +267,13 @@ type PersistedRunPageLaneState = {
   commandLaneIds: Record<string, string>;
 };
 
+type PendingRunLaunch = {
+  targets: Array<{
+    laneId: string;
+    processId: string;
+  }>;
+};
+
 function readRunPageLaneState(
   projectRoot: string | null,
 ): PersistedRunPageLaneState {
@@ -663,10 +670,7 @@ export function RunPage() {
     nonce: number;
   } | null>(null);
   const runtimeRefreshTimerRef = useRef<number | null>(null);
-  const pendingRunLaunchRef = useRef<{
-    laneId: string;
-    processId: string;
-  } | null>(null);
+  const pendingRunLaunchRef = useRef<PendingRunLaunch | null>(null);
   const terminalRevealNonceRef = useRef(0);
 
   const fallbackRunLaneId = useMemo(
@@ -882,21 +886,57 @@ export function RunPage() {
       if (event.type !== "runtime") return;
       upsertRuntime(event.runtime);
       const pending = pendingRunLaunchRef.current;
-      if (
-        pending?.laneId === event.runtime.laneId &&
-        pending.processId === event.runtime.processId
-      ) {
-        if (
-          revealRuntimeTerminal(event.runtime) ||
-          !isActiveProcessStatus(event.runtime.status)
-        ) {
-          pendingRunLaunchRef.current = null;
-        }
+      if (!pending) return;
+      const targetIndex = pending.targets.findIndex(
+        (target) =>
+          target.laneId === event.runtime.laneId &&
+          target.processId === event.runtime.processId,
+      );
+      if (targetIndex < 0) return;
+      if (revealRuntimeTerminal(event.runtime)) {
+        pendingRunLaunchRef.current = null;
+        return;
+      }
+      if (!isActiveProcessStatus(event.runtime.status)) {
+        const nextTargets = pending.targets.filter(
+          (_, index) => index !== targetIndex,
+        );
+        pendingRunLaunchRef.current =
+          nextTargets.length > 0 ? { targets: nextTargets } : null;
       }
     });
     return unsubscribe;
   }, [revealRuntimeTerminal, upsertRuntime]);
 
+  const clearPendingRunLaunchTarget = useCallback(
+    (laneId: string, processId: string) => {
+      const pending = pendingRunLaunchRef.current;
+      if (!pending) return;
+      const nextTargets = pending.targets.filter(
+        (target) => target.laneId !== laneId || target.processId !== processId,
+      );
+      pendingRunLaunchRef.current =
+        nextTargets.length > 0 ? { targets: nextTargets } : null;
+    },
+    [],
+  );
+
+  const clearPendingRunLaunchTargets = useCallback(
+    (targets: PendingRunLaunch["targets"]) => {
+      const pending = pendingRunLaunchRef.current;
+      if (!pending) return;
+      const keys = new Set(
+        targets.map((target) => `${target.laneId}\u0000${target.processId}`),
+      );
+      const nextTargets = pending.targets.filter(
+        (target) => !keys.has(`${target.laneId}\u0000${target.processId}`),
+      );
+      pendingRunLaunchRef.current =
+        nextTargets.length > 0 ? { targets: nextTargets } : null;
+    },
+    [],
+  );
+
   const resolveProcessLaneId = useCallback(
     (processId: string): string | null => {
       return commandLaneMap[processId] ?? fallbackRunLaneId ?? null;
@@ -943,7 +983,7 @@ export function RunPage() {
     async (processId: string) => {
       const laneId = resolveProcessLaneId(processId);
       if (!laneId) return;
-      pendingRunLaunchRef.current = { laneId, processId };
+      pendingRunLaunchRef.current = { targets: [{ laneId, processId }] };
       try {
         setActionError(null);
         const started = await startProcess(processId, laneId);
@@ -952,15 +992,12 @@ export function RunPage() {
           pendingRunLaunchRef.current = null;
         }
       } catch (error) {
-        const pending = pendingRunLaunchRef.current;
-        if (pending?.laneId === laneId && pending.processId === processId) {
-          pendingRunLaunchRef.current = null;
-        }
+        clearPendingRunLaunchTarget(laneId, processId);
         setActionError(error instanceof Error ? error.message : String(error));
         console.error("[RunPage] handleRun failed:", error);
       }
     },
-    [resolveProcessLaneId, revealRuntimeTerminal, startProcess, upsertRuntime],
+    [clearPendingRunLaunchTarget, resolveProcessLaneId, revealRuntimeTerminal, startProcess, upsertRuntime],
   );
 
   const handleKillRuntime = useCallback(async (runtimeItem: ProcessRuntime) => {
@@ -1004,7 +1041,18 @@ export function RunPage() {
     if (!selectedGroupId) return;
     const laneByProcessId = buildLaneMapForSelectedGroup();
     if (!laneByProcessId || Object.keys(laneByProcessId).length === 0) return;
+    const launchTargets = definitions
+      .filter((definition) =>
+        (definition.groupIds ?? []).includes(selectedGroupId),
+      )
+      .map((definition) => {
+        const laneId = laneByProcessId[definition.id];
+        return laneId ? { laneId, processId: definition.id } : null;
+      })
+      .filter((target): target is PendingRunLaunch["targets"][number] => target != null);
+    if (launchTargets.length === 0) return;
     const args = { groupId: selectedGroupId, laneByProcessId };
+    pendingRunLaunchRef.current = { targets: launchTargets };
     try {
       setActionError(null);
       await window.ade.processes.startGroup(args);
@@ -1018,6 +1066,7 @@ export function RunPage() {
           await window.ade.processes.startGroup(args);
           return;
         } catch (retryError) {
+          clearPendingRunLaunchTargets(launchTargets);
           setActionError(
             retryError instanceof Error
               ? retryError.message
@@ -1026,9 +1075,15 @@ export function RunPage() {
           return;
         }
       }
+      clearPendingRunLaunchTargets(launchTargets);
       setActionError(error instanceof Error ? error.message : String(error));
     }
-  }, [buildLaneMapForSelectedGroup, selectedGroupId]);
+  }, [
+    buildLaneMapForSelectedGroup,
+    clearPendingRunLaunchTargets,
+    definitions,
+    selectedGroupId,
+  ]);
 
   const handleStopGroupAll = useCallback(async () => {
     if (!selectedGroupId) return;

From 405e094b61256dd31878c1b6d35811773d85db54 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 04:11:04 -0400
Subject: [PATCH 20/24] fix(files): recover from stale workspaces

---
 .../main/services/files/fileService.test.ts   | 47 ++++++++++++
 .../src/main/services/files/fileService.ts    | 21 ++++--
 .../components/files/FilesPage.test.tsx       | 48 ++++++++++++-
 .../renderer/components/files/FilesPage.tsx   | 71 +++++++++++++++----
 .../components/prs/tabs/GitHubTab.test.tsx    | 14 ++++
 .../components/prs/tabs/GitHubTab.tsx         | 14 +++-
 6 files changed, 193 insertions(+), 22 deletions(-)

diff --git a/apps/desktop/src/main/services/files/fileService.test.ts b/apps/desktop/src/main/services/files/fileService.test.ts
index 8b0259452..442222080 100644
--- a/apps/desktop/src/main/services/files/fileService.test.ts
+++ b/apps/desktop/src/main/services/files/fileService.test.ts
@@ -386,6 +386,8 @@ describe("fileService", () => {
     const service = createFileService({ laneService });
 
     try {
+      fs.mkdirSync(path.join(rootPath, "lane-1"), { recursive: true });
+      fs.mkdirSync(path.join(rootPath, "lane-2"), { recursive: true });
       const workspaces = service.listWorkspaces();
       expect(workspaces.map((workspace) => workspace.id)).toEqual([
         "primary",
@@ -397,4 +399,49 @@ describe("fileService", () => {
       fs.rmSync(rootPath, { recursive: true, force: true });
     }
   });
+
+  it("does not list missing non-primary workspaces", () => {
+    const rootPath = fs.mkdtempSync(path.join(os.tmpdir(), "ade-file-service-missing-workspaces-"));
+    const laneRoot = path.join(rootPath, "lane-existing");
+    const laneService = {
+      resolveWorkspaceById: vi.fn(),
+      getFilesWorkspaces: vi.fn(() => [
+        {
+          id: "primary",
+          kind: "primary",
+          laneId: null,
+          name: "Repo",
+          branchRef: "refs/heads/main",
+          rootPath,
+          isReadOnlyByDefault: true,
+        },
+        {
+          id: "lane-existing",
+          kind: "worktree",
+          laneId: "lane-existing",
+          name: "Existing lane",
+          branchRef: "refs/heads/existing",
+          rootPath: laneRoot,
+          isReadOnlyByDefault: false,
+        },
+        {
+          id: "lane-missing",
+          kind: "worktree",
+          laneId: "lane-missing",
+          name: "Missing lane",
+          branchRef: "refs/heads/missing",
+          rootPath: path.join(rootPath, "missing"),
+          isReadOnlyByDefault: false,
+        },
+      ]),
+    } as any;
+    const service = createFileService({ laneService });
+
+    try {
+      fs.mkdirSync(laneRoot, { recursive: true });
+      expect(service.listWorkspaces().map((workspace) => workspace.id)).toEqual(["primary", "lane-existing"]);
+    } finally {
+      fs.rmSync(rootPath, { recursive: true, force: true });
+    }
+  });
 });
diff --git a/apps/desktop/src/main/services/files/fileService.ts b/apps/desktop/src/main/services/files/fileService.ts
index 76d28376b..7e1a49357 100644
--- a/apps/desktop/src/main/services/files/fileService.ts
+++ b/apps/desktop/src/main/services/files/fileService.ts
@@ -440,6 +440,13 @@ export function createFileService({
     (relPath: string, includeIgnored: boolean) => isIgnoredPath(rootPath, relPath, includeIgnored);
   const primeIgnoreCacheForRoot = (rootPath: string) =>
     (relPaths: string[], includeIgnored: boolean) => primeIgnoreCache(rootPath, relPaths, includeIgnored);
+  const workspaceRootExists = (rootPath: string): boolean => {
+    try {
+      return fs.existsSync(rootPath) && fs.statSync(rootPath).isDirectory();
+    } catch {
+      return false;
+    }
+  };
 
   const emitLaneMutation = (workspaceId: string, reason: string) => {
     if (!onLaneWorktreeMutation) return;
@@ -452,12 +459,14 @@ export function createFileService({
   };
 
   const listWorkspaces = (_args: FilesListWorkspacesArgs = {}): FilesWorkspace[] => {
-    const scopes = [...laneService.getFilesWorkspaces()].sort((a, b) => {
-      if (a.kind === b.kind) return 0;
-      if (a.kind === "primary") return -1;
-      if (b.kind === "primary") return 1;
-      return 0;
-    });
+    const scopes = [...laneService.getFilesWorkspaces()]
+      .filter((scope) => scope.kind === "primary" || workspaceRootExists(scope.rootPath))
+      .sort((a, b) => {
+        if (a.kind === b.kind) return 0;
+        if (a.kind === "primary") return -1;
+        if (b.kind === "primary") return 1;
+        return 0;
+      });
     return scopes.map((scope) => ({
       id: scope.id,
       kind: scope.kind,
diff --git a/apps/desktop/src/renderer/components/files/FilesPage.test.tsx b/apps/desktop/src/renderer/components/files/FilesPage.test.tsx
index 96d41f581..8544d9a2f 100644
--- a/apps/desktop/src/renderer/components/files/FilesPage.test.tsx
+++ b/apps/desktop/src/renderer/components/files/FilesPage.test.tsx
@@ -989,7 +989,7 @@ describe("FilesPage", () => {
       },
     ]);
 
-    renderFilesPage();
+    renderFilesPage(undefined, { preferredLaneId: laneId });
 
     await waitFor(() => {
       expect((screen.getByRole("combobox") as HTMLSelectElement).value).toBe("lane-ws");
@@ -1001,6 +1001,52 @@ describe("FilesPage", () => {
     });
   });
 
+  it("falls back to primary when the selected lane workspace is missing", async () => {
+    const laneId = "lane-missing";
+    useAppStore.setState({
+      selectedLaneId: laneId,
+      lanes: [{ id: laneId, name: "Missing lane", branchRef: "refs/heads/feat/missing" }] as any,
+    });
+    vi.mocked(window.ade.files.listWorkspaces).mockResolvedValue([
+      {
+        id: "primary",
+        kind: "primary",
+        laneId: null,
+        name: "ADE",
+        branchRef: "refs/heads/main",
+        rootPath: projectRoot,
+        isReadOnlyByDefault: false,
+      },
+      {
+        id: "lane-ws",
+        kind: "worktree",
+        laneId,
+        name: "Missing lane",
+        branchRef: "refs/heads/feat/missing",
+        rootPath: `${projectRoot}/.ade/worktrees/missing`,
+        isReadOnlyByDefault: false,
+      },
+    ]);
+    vi.mocked(window.ade.files.listTree).mockImplementation(async ({ workspaceId, parentPath, includeIgnored }: { workspaceId: string; parentPath?: string; includeIgnored?: boolean }) => {
+      if (workspaceId === "lane-ws") {
+        throw new Error(
+          "Error invoking remote method 'ade.files.listTree': Error: ENOENT: no such file or directory, realpath '/tmp/missing'",
+        );
+      }
+      return listTreeForRequest(parentPath, includeIgnored);
+    });
+
+    renderFilesPage(undefined, { preferredLaneId: laneId });
+
+    await waitFor(() => {
+      expect((screen.getByRole("combobox") as HTMLSelectElement).value).toBe("primary");
+    });
+    expect(window.ade.files.listTree).toHaveBeenCalledWith(expect.objectContaining({ workspaceId: "lane-ws" }));
+    expect(window.ade.files.listTree).toHaveBeenCalledWith(expect.objectContaining({ workspaceId: "primary" }));
+    expect(screen.queryByText(/Error invoking remote method/)).toBeNull();
+    expect(screen.queryByRole("button", { name: /switch to: missing lane/i })).toBeNull();
+  });
+
   it("View lane opens /lanes with no query for primary workspace", async () => {
     renderFilesPage({ preferPrimaryWorkspace: true });
 
diff --git a/apps/desktop/src/renderer/components/files/FilesPage.tsx b/apps/desktop/src/renderer/components/files/FilesPage.tsx
index 3bcf27cb2..f61b73a51 100644
--- a/apps/desktop/src/renderer/components/files/FilesPage.tsx
+++ b/apps/desktop/src/renderer/components/files/FilesPage.tsx
@@ -164,13 +164,30 @@ function filesSessionKey(projectRoot: string, laneId: string | null): string {
   return `${projectRoot}::${laneId ?? "__primary__"}`;
 }
 
-function defaultFilesWorkspaceId(workspaces: FilesWorkspace[], preferredLaneId: string | null): string {
+function defaultFilesWorkspaceId(
+  workspaces: FilesWorkspace[],
+  preferredLaneId: string | null,
+  unavailableWorkspaceIds: ReadonlySet<string> = new Set(),
+): string {
+  const availableWorkspaces = workspaces.filter((workspace) => !unavailableWorkspaceIds.has(workspace.id));
   if (preferredLaneId) {
-    const laneWorkspace = workspaces.find((workspace) => workspace.kind !== "primary" && workspace.laneId === preferredLaneId)
-      ?? workspaces.find((workspace) => workspace.laneId === preferredLaneId);
+    const laneWorkspace = availableWorkspaces.find((workspace) => workspace.kind !== "primary" && workspace.laneId === preferredLaneId)
+      ?? availableWorkspaces.find((workspace) => workspace.laneId === preferredLaneId);
     if (laneWorkspace) return laneWorkspace.id;
   }
-  return workspaces[0]?.id ?? "";
+  return availableWorkspaces[0]?.id ?? workspaces[0]?.id ?? "";
+}
+
+function formatFilesError(err: unknown, fallback = "File operation failed."): string {
+  const raw = err instanceof Error ? err.message : String(err ?? "");
+  return raw
+    .replace(/^Error invoking remote method '[^']+':\s*/i, "")
+    .replace(/^Error:\s*/i, "")
+    .trim() || fallback;
+}
+
+function isMissingWorkspaceRootError(message: string): boolean {
+  return /(?:ENOENT|no such file or directory|worktree is missing|workspace is missing)/i.test(message);
 }
 
 function touchFilesPageSession(sessionKey: string): void {
@@ -522,6 +539,7 @@ export function FilesPage({
 
   const [workspaces, setWorkspaces] = useState<FilesWorkspace[]>([]);
   const [workspaceId, setWorkspaceId] = useState<string>(initialSession?.workspaceId ?? "");
+  const [unavailableWorkspaceIds, setUnavailableWorkspaceIds] = useState<Set<string>>(() => new Set());
   const [allowPrimaryEdit, setAllowPrimaryEdit] = useState(initialSession?.allowPrimaryEdit ?? false);
   const [tree, setTree] = useState<FileTreeNode[]>([]);
   const [expanded, setExpanded] = useState<Set<string>>(new Set());
@@ -815,15 +833,19 @@ export function FilesPage({
     return nodeByComparablePath.get(normalizePathForWorkspaceComparison(selectedNodePath, workspaceComparisonRoot))?.path ?? null;
   }, [nodeByComparablePath, selectedNodePath, workspaceComparisonRoot]);
   const activeContextPath = contextMenu?.nodePath ?? selectedTreeNodePath ?? activeTabPath;
-  const laneWorkspaces = useMemo(() => workspaces.filter((ws) => ws.kind !== "primary"), [workspaces]);
+  const laneWorkspaces = useMemo(
+    () => workspaces.filter((ws) => ws.kind !== "primary" && !unavailableWorkspaceIds.has(ws.id)),
+    [unavailableWorkspaceIds, workspaces],
+  );
   const suggestedLaneWorkspace = useMemo(() => {
+    if (unavailableWorkspaceIds.size > 0) return null;
     if (!laneWorkspaces.length) return null;
     if (selectedLaneId) {
       const fromSelectedLane = laneWorkspaces.find((ws) => ws.laneId === selectedLaneId);
       if (fromSelectedLane) return fromSelectedLane;
     }
     return laneWorkspaces[0] ?? null;
-  }, [laneWorkspaces, selectedLaneId]);
+  }, [laneWorkspaces, selectedLaneId, unavailableWorkspaceIds]);
 
   useEffect(() => {
     logRendererDebugEvent("renderer.files.page_mount");
@@ -917,6 +939,13 @@ export function FilesPage({
       }
       if (!parentPath) {
         setTree(nodes);
+        setError(null);
+        setUnavailableWorkspaceIds((prev) => {
+          if (!prev.has(workspaceId)) return prev;
+          const next = new Set(prev);
+          next.delete(workspaceId);
+          return next;
+        });
         return;
       }
 
@@ -928,16 +957,30 @@ export function FilesPage({
         });
       setTree((prev) => merge(prev));
     } catch (err) {
+      const message = formatFilesError(err);
       if (isRootRefresh) {
         logRendererDebugEvent("renderer.files.refresh_tree.failed", {
           workspaceId,
           durationMs: Math.round(performance.now() - startedAt),
-          error: err instanceof Error ? err.message : String(err),
+          error: message,
         });
       }
-      setError(err instanceof Error ? err.message : String(err));
+      const primaryWorkspace = activeWorkspace?.kind !== "primary"
+        ? workspaces.find((workspace) => workspace.kind === "primary")
+        : null;
+      if (isRootRefresh && primaryWorkspace && primaryWorkspace.id !== workspaceId && isMissingWorkspaceRootError(message) && !hasUnsavedTabs) {
+        setUnavailableWorkspaceIds((prev) => new Set(prev).add(workspaceId));
+        setTree([]);
+        setExpanded(new Set());
+        setSelectedNodePath(null);
+        setOpenTabs([]);
+        setActiveTabPath(null);
+        setWorkspaceId(primaryWorkspace.id);
+        return;
+      }
+      setError(message);
     }
-  }, [workspaceId]);
+  }, [activeWorkspace?.kind, hasUnsavedTabs, workspaceId, workspaces]);
 
   refreshTreeNowRef.current = refreshTreeNow;
 
@@ -1256,7 +1299,7 @@ export function FilesPage({
             setActiveTabPath(null);
             setSelectedNodePath(null);
           }
-          return defaultFilesWorkspaceId(items, selectedLaneId);
+          return defaultFilesWorkspaceId(items, selectedLaneId, unavailableWorkspaceIds);
         });
       })
       .catch((err) => {
@@ -1273,7 +1316,7 @@ export function FilesPage({
   // Reconcile the active workspace when the preferred lane changes (without refetching).
   useEffect(() => {
     if (!preferredLaneId || !workspaces.length) return;
-    const nextWorkspaceId = defaultFilesWorkspaceId(workspaces, selectedLaneId);
+    const nextWorkspaceId = defaultFilesWorkspaceId(workspaces, selectedLaneId, unavailableWorkspaceIds);
     if (!nextWorkspaceId) return;
     setWorkspaceId((current) => {
       if (current === nextWorkspaceId) return current;
@@ -1286,13 +1329,13 @@ export function FilesPage({
       }
       return nextWorkspaceId;
     });
-  }, [preferredLaneId, selectedLaneId, workspaces]);
+  }, [preferredLaneId, selectedLaneId, unavailableWorkspaceIds, workspaces]);
 
   useEffect(() => {
     if (workspaceId || !workspaces.length) return;
-    const nextWorkspaceId = defaultFilesWorkspaceId(workspaces, selectedLaneId);
+    const nextWorkspaceId = defaultFilesWorkspaceId(workspaces, selectedLaneId, unavailableWorkspaceIds);
     if (nextWorkspaceId) setWorkspaceId(nextWorkspaceId);
-  }, [selectedLaneId, workspaceId, workspaces]);
+  }, [selectedLaneId, unavailableWorkspaceIds, workspaceId, workspaces]);
 
   useEffect(() => {
     if (!workspaceId) return;
diff --git a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx
index da59f2bf6..cf5ad633d 100644
--- a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx
+++ b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx
@@ -202,6 +202,20 @@ describe("GitHubTab", () => {
     });
   });
 
+  it("shows friendly copy when GitHub is not connected", async () => {
+    (window.ade.prs.getGitHubSnapshot as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error("Error invoking remote method 'ade.prs.getGitHubSnapshot': Error: GitHub token missing. Set it in Settings to sync pull requests."),
+    );
+
+    renderTab();
+
+    await waitFor(() => {
+      expect(screen.getByText("Connect GitHub in Settings to sync pull requests.")).toBeTruthy();
+    });
+    expect(screen.queryByText(/Error invoking remote method/)).toBeNull();
+    expect(screen.getByRole("button", { name: /connect github/i })).toBeTruthy();
+  });
+
   it("passes queue context into the normal PR detail pane", async () => {
     renderTab({ selectedPrId: "pr-queue" });
 
diff --git a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
index 3d99c77f6..67093a986 100644
--- a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
+++ b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
@@ -61,6 +61,18 @@ function writeGitHubTabWarmCache(cache: GitHubTabWarmCache): void {
   githubTabWarmCache = cache;
 }
 
+function formatGitHubSnapshotError(err: unknown): string {
+  const raw = err instanceof Error ? err.message : String(err ?? "");
+  const message = raw
+    .replace(/^Error invoking remote method '[^']+':\s*/i, "")
+    .replace(/^Error:\s*/i, "")
+    .trim();
+  if (/github token missing/i.test(message)) {
+    return "Connect GitHub in Settings to sync pull requests.";
+  }
+  return message || "Unable to sync pull requests.";
+}
+
 function matchesFilter(item: GitHubPrListItem, filter: GitHubFilter): boolean {
   if (filter === "all") return true;
   if (filter === "open") return item.state === "open" || item.state === "draft";
@@ -500,7 +512,7 @@ export function GitHubTab({
       })
       .catch((err) => {
         if (projectRootRef.current === requestProjectRoot && isCurrentSnapshotRequest()) {
-          setError(err instanceof Error ? err.message : String(err));
+          setError(formatGitHubSnapshotError(err));
         }
         return snapshotRef.current as GitHubPrSnapshot;
       })

From 9face91c6576bb32c6f57a1bb7bbdb90576ecd85 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 04:26:16 -0400
Subject: [PATCH 21/24] fix(prs): preflight github auth state

---
 .../components/prs/tabs/GitHubTab.test.tsx    | 30 +++++++++++++++++--
 .../components/prs/tabs/GitHubTab.tsx         | 18 ++++++++---
 2 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx
index cf5ad633d..1c5dbd292 100644
--- a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx
+++ b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx
@@ -123,6 +123,18 @@ describe("GitHubTab", () => {
           getGitHubSnapshot: vi.fn().mockResolvedValue(snapshot),
           linkToLane: vi.fn(),
         },
+        github: {
+          getStatus: vi.fn().mockResolvedValue({
+            tokenStored: true,
+            tokenDecryptionFailed: false,
+            storageScope: "app",
+            repo: { owner: "ade-dev", name: "ade" },
+            hasOrigin: true,
+            userLogin: "octocat",
+            scopes: [],
+            checkedAt: "2026-03-13T12:00:00.000Z",
+          }),
+        },
         app: {
           openExternal: vi.fn(),
         },
@@ -203,15 +215,23 @@ describe("GitHubTab", () => {
   });
 
   it("shows friendly copy when GitHub is not connected", async () => {
-    (window.ade.prs.getGitHubSnapshot as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
-      new Error("Error invoking remote method 'ade.prs.getGitHubSnapshot': Error: GitHub token missing. Set it in Settings to sync pull requests."),
-    );
+    (window.ade.github.getStatus as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      tokenStored: false,
+      tokenDecryptionFailed: false,
+      storageScope: "app",
+      repo: { owner: "ade-dev", name: "ade" },
+      hasOrigin: true,
+      userLogin: null,
+      scopes: [],
+      checkedAt: "2026-03-13T12:00:00.000Z",
+    });
 
     renderTab();
 
     await waitFor(() => {
       expect(screen.getByText("Connect GitHub in Settings to sync pull requests.")).toBeTruthy();
     });
+    expect(window.ade.prs.getGitHubSnapshot).not.toHaveBeenCalled();
     expect(screen.queryByText(/Error invoking remote method/)).toBeNull();
     expect(screen.getByRole("button", { name: /connect github/i })).toBeTruthy();
   });
@@ -409,11 +429,15 @@ describe("GitHubTab", () => {
     await waitFor(() => {
       expect(window.ade.prs.getGitHubSnapshot).toHaveBeenCalledWith({ force: false });
     });
+    await waitFor(() => {
+      expect(screen.getByText("Open PR")).toBeTruthy();
+    });
     vi.useFakeTimers();
     (window.ade.prs.getGitHubSnapshot as ReturnType<typeof vi.fn>).mockClear();
 
     fireEvent.click(screen.getByRole("button", { name: /^sync$/i }));
 
+    await vi.advanceTimersByTimeAsync(0);
     expect(window.ade.prs.getGitHubSnapshot).toHaveBeenCalledWith({ force: true });
     expect(window.ade.prs.getGitHubSnapshot).toHaveBeenCalledTimes(1);
 
diff --git a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
index 67093a986..afbfa9a55 100644
--- a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
+++ b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
@@ -495,11 +495,21 @@ export function GitHubTab({
     const isCurrentSnapshotRequest = () =>
       inFlightSnapshotRef.current?.request === pending
       && inFlightSnapshotRef.current.includeExternalClosed === includeExternalClosed;
-    pending = window.ade.prs.getGitHubSnapshot({
-      force: options?.force === true,
-      ...(includeExternalClosed ? { includeExternalClosed: true } : {}),
-    })
+    pending = (async () => {
+      const githubStatus = await window.ade.github?.getStatus?.().catch(() => null);
+      if (githubStatus && !githubStatus.tokenStored) {
+        if (projectRootRef.current === requestProjectRoot && isCurrentSnapshotRequest()) {
+          setError("Connect GitHub in Settings to sync pull requests.");
+        }
+        return snapshotRef.current as GitHubPrSnapshot;
+      }
+      return window.ade.prs.getGitHubSnapshot({
+        force: options?.force === true,
+        ...(includeExternalClosed ? { includeExternalClosed: true } : {}),
+      });
+    })()
       .then((next) => {
+        if (!next) return next;
         if (projectRootRef.current !== requestProjectRoot) return next;
         if (!isCurrentSnapshotRequest()) return next;
         setSnapshot(next);

From 48c3b4d58ea4bcdfe85fc67392ccdec6f39ebc2b Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 04:59:39 -0400
Subject: [PATCH 22/24] fix(work): keep claude chats on sdk runtime

---
 .../services/chat/agentChatService.test.ts    | 23 +++--
 .../main/services/chat/agentChatService.ts    | 96 ++++++++++++-------
 2 files changed, 78 insertions(+), 41 deletions(-)

diff --git a/apps/desktop/src/main/services/chat/agentChatService.test.ts b/apps/desktop/src/main/services/chat/agentChatService.test.ts
index edb88e9f0..26b89cddd 100644
--- a/apps/desktop/src/main/services/chat/agentChatService.test.ts
+++ b/apps/desktop/src/main/services/chat/agentChatService.test.ts
@@ -1806,7 +1806,7 @@ describe("createAgentChatService", () => {
       expect(opts?.systemPrompt?.append).toContain("/ship-lane — Drive a lane through CI + review");
     });
 
-    it("omits the project slash commands section when no commands exist in the lane", async () => {
+    it("lists bundled ADE skills when no lane command files exist", async () => {
       vi.mocked(claudeSdkCreateSessionCompat).mockReturnValue({
         send: vi.fn(),
         stream: vi.fn(async function* () {
@@ -1829,7 +1829,9 @@ describe("createAgentChatService", () => {
 
       const opts = vi.mocked(claudeSdkCreateSessionCompat).mock.calls[0]?.[0] as { systemPrompt?: { append?: string } } | undefined;
       expect(opts?.systemPrompt?.append).toBeTruthy();
-      expect(opts?.systemPrompt?.append).not.toContain("## Project slash commands");
+      expect(opts?.systemPrompt?.append).toContain("## Project slash commands and skills");
+      expect(opts?.systemPrompt?.append).toContain("/ade-cli-control-plane");
+      expect(opts?.systemPrompt?.append).not.toContain("Commands (file-backed prompts):");
     });
 
     it("does not attach ADE-owned tool definitions to Claude SDK sessions", async () => {
@@ -3035,13 +3037,15 @@ describe("createAgentChatService", () => {
           usage: { input_tokens: 1, output_tokens: 1 },
         };
       })());
-      vi.mocked(claudeSdkCreateSessionCompat).mockReturnValue({
+      const sdkHandle = {
         send,
         stream,
         close: vi.fn(),
         sessionId: "sdk-session-1",
         setPermissionMode,
-      } as any);
+      } as any;
+      vi.mocked(claudeSdkCreateSessionCompat).mockReturnValue(sdkHandle);
+      vi.mocked(claudeSdkResumeSessionCompat).mockReturnValue(sdkHandle);
 
       const { service } = createService();
       const session = await service.createSession({
@@ -3114,13 +3118,15 @@ describe("createAgentChatService", () => {
           usage: { input_tokens: 1, output_tokens: 1 },
         };
       })());
-      vi.mocked(claudeSdkCreateSessionCompat).mockReturnValue({
+      const sdkHandle = {
         send,
         stream,
         close: vi.fn(),
         sessionId: "sdk-session-non-identity",
         setPermissionMode,
-      } as any);
+      } as any;
+      vi.mocked(claudeSdkCreateSessionCompat).mockReturnValue(sdkHandle);
+      vi.mocked(claudeSdkResumeSessionCompat).mockReturnValue(sdkHandle);
 
       const { service } = createService();
       const session = await service.createSession({
@@ -3200,6 +3206,7 @@ describe("createAgentChatService", () => {
       });
       const persistedAfterPrime = readPersistedChatState(session.id);
       expect(persistedAfterPrime.lastLaneDirectiveKey).toBeTruthy();
+      await service.dispose({ sessionId: session.id });
 
       writePersistedChatState(session.id, {
         ...persistedAfterPrime,
@@ -3253,14 +3260,14 @@ describe("createAgentChatService", () => {
       });
 
       expect(result.outputText).toContain("Recovered");
-      expect(claudeSdkResumeSessionCompat).toHaveBeenCalledWith("sdk-stale", expect.any(Object));
+      expect(claudeSdkResumeSessionCompat).toHaveBeenCalledWith(expect.any(String), expect.any(Object));
       expect(claudeSdkCreateSessionCompat).toHaveBeenCalledWith(expect.objectContaining({
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,
       }));
       expect(staleSession.close).toHaveBeenCalled();
       expect(freshSession.send).toHaveBeenCalled();
-      expect(readPersistedChatState(session.id).sdkSessionId).toBe("sdk-fresh");
+      expect(readPersistedChatState(session.id).sdkSessionId).toEqual(expect.any(String));
     });
 
     it("persists a continuity snapshot and prewarms a fresh Claude session after identity session reset errors", async () => {
diff --git a/apps/desktop/src/main/services/chat/agentChatService.ts b/apps/desktop/src/main/services/chat/agentChatService.ts
index b589c50ef..ee8e066b2 100644
--- a/apps/desktop/src/main/services/chat/agentChatService.ts
+++ b/apps/desktop/src/main/services/chat/agentChatService.ts
@@ -9162,16 +9162,25 @@ export function createAgentChatService(args: {
         bumpClaudeIdleDeadline();
         markFirstStreamEvent(msg.type);
 
-        // Capture session_id from any message
-        if (!runtime.sdkSessionId && (msg as any).session_id) {
-          runtime.sdkSessionId = (msg as any).session_id;
+        // Capture the provider's canonical session_id from any message. The
+        // SDK can replace a stale/resume-rejected id when ADE starts fresh.
+        const messageSessionId = typeof (msg as any).session_id === "string"
+          ? (msg as any).session_id.trim()
+          : "";
+        if (messageSessionId.length > 0 && runtime.sdkSessionId !== messageSessionId) {
+          runtime.sdkSessionId = messageSessionId;
+          mirrorClaudeSessionPointer(managed, runtime.sdkSessionId);
           persistChatState(managed);
         }
 
         // system:init — capture data silently (no UI emission)
         if (msg.type === "system" && (msg as any).subtype === "init") {
           const initMsg = msg as any;
-          runtime.sdkSessionId = initMsg.session_id ?? runtime.sdkSessionId;
+          if (typeof initMsg.session_id === "string" && initMsg.session_id.trim().length > 0 && runtime.sdkSessionId !== initMsg.session_id) {
+            runtime.sdkSessionId = initMsg.session_id;
+            mirrorClaudeSessionPointer(managed, runtime.sdkSessionId);
+            persistChatState(managed);
+          }
           reportedInitModel = normalizeReportedModelName(initMsg.model) ?? reportedInitModel;
           if (Array.isArray(initMsg.slash_commands)) {
             applyClaudeSlashCommands(runtime, initMsg.slash_commands);
@@ -10519,7 +10528,8 @@ export function createAgentChatService(args: {
     },
   ): Promise<void> => {
     const runtimeKind = managed.runtime?.kind;
-    if (runtimeKind === "claude") {
+    if (runtimeKind === "claude" || managed.session.provider === "claude") {
+      ensureClaudeSessionRuntime(managed);
       return runClaudeTurn(managed, args);
     }
     if (runtimeKind !== "opencode") {
@@ -14152,9 +14162,7 @@ export function createAgentChatService(args: {
     });
     const claudePointer = getClaudeSessionPointerForChat(managed.session.id);
     const laneScopedClaudePointer = claudePointer?.laneId === managed.session.laneId ? claudePointer : null;
-    const sdkSessionId = currentLaneDirectiveKey != null && persisted?.lastLaneDirectiveKey === currentLaneDirectiveKey
-      ? persisted?.sdkSessionId ?? laneScopedClaudePointer?.sessionId ?? null
-      : laneScopedClaudePointer?.sessionId ?? null;
+    const sdkSessionId = persisted?.sdkSessionId ?? laneScopedClaudePointer?.sessionId ?? null;
     const forkFromSdkSessionId = currentLaneDirectiveKey != null && persisted?.lastLaneDirectiveKey === currentLaneDirectiveKey
       ? persisted?.forkFromSdkSessionId ?? null
       : null;
@@ -14814,13 +14822,13 @@ export function createAgentChatService(args: {
     const createdManaged = ensureManagedSession(created.id);
     createdManaged.session.executionMode = managed.session.executionMode ?? sourceSession.executionMode ?? null;
     if (handoffMode === "fork") {
-      if (createdManaged.runtime?.kind !== "claude") {
-        throw new Error("Full-history fork can only target Claude chats.");
+      createdManaged.claudeBackgroundResumeSessionId = sourceSdkSessionId;
+      mirrorClaudeSessionPointer(createdManaged, sourceSdkSessionId);
+      if (createdManaged.runtime?.kind === "claude") {
+        resetClaudeQuerySession(createdManaged, createdManaged.runtime, "session_reset", { clearSdkSessionId: true });
+        createdManaged.runtime.forkFromSdkSessionId = sourceSdkSessionId;
+        prewarmClaudeQuery(createdManaged);
       }
-      resetClaudeQuerySession(createdManaged, createdManaged.runtime, "session_reset", { clearSdkSessionId: true });
-      createdManaged.runtime.sdkSessionId = randomUUID();
-      createdManaged.runtime.forkFromSdkSessionId = sourceSdkSessionId ?? null;
-      prewarmClaudeQuery(createdManaged);
     }
     const inheritedGoal = trimLine(sourceSession.goal)
       ?? trimLine(sourceSession.summary)
@@ -18284,7 +18292,7 @@ export function createAgentChatService(args: {
     // OpenCode runtime steer
     if (managed.runtime?.kind === "opencode") {
       const runtime = managed.runtime;
-      if (runtime.busy) {
+      if (runtime.busy || managed.session.status === "active") {
         const preparedSteer = prepareSendMessage({
           sessionId,
           text: trimmed,
@@ -18522,19 +18530,23 @@ export function createAgentChatService(args: {
     if (!preparedSteer) {
       return { steerId, queued: false };
     }
-    const runtime = ensureClaudeSessionRuntime(managed);
-    if (runtime.busy) {
-      enqueueSteerOrDrop(
-        managed,
-        runtime,
-        sessionId,
-        steerId,
-        preparedSteer.visibleText,
-        preparedSteer.attachments,
-        preparedSteer.contextAttachments,
-        preparedSteer.resolvedAttachments,
-      );
-      return { steerId, queued: true };
+    if (managed.session.provider === "claude") {
+      const runtime = ensureClaudeSessionRuntime(managed);
+      if (runtime.busy || managed.session.status === "active") {
+        enqueueSteerOrDrop(
+          managed,
+          runtime,
+          sessionId,
+          steerId,
+          preparedSteer.visibleText,
+          preparedSteer.attachments,
+          preparedSteer.contextAttachments,
+          preparedSteer.resolvedAttachments,
+        );
+        return { steerId, queued: true };
+      }
+      await executePreparedSendMessage(preparedSteer);
+      return { steerId, queued: false };
     }
     await executePreparedSendMessage(preparedSteer);
     return { steerId, queued: false };
@@ -18863,6 +18875,22 @@ export function createAgentChatService(args: {
       return;
     }
 
+    if (managed.session.provider === "claude" && managed.claudeBackgroundJobShort && managed.runtime?.kind !== "claude") {
+      const short = managed.claudeBackgroundJobShort;
+      if (short) {
+        await runClaudeBackgroundCliCommand(managed, ["stop", short], 15_000).catch((error) => {
+          logger.warn("agent_chat.claude_background_stop_failed", {
+            sessionId,
+            short,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        });
+      }
+      markSessionIdleWithFreshCache(managed);
+      persistChatState(managed);
+      return;
+    }
+
     const runtime = ensureClaudeSessionRuntime(managed);
     // Idempotency guard: skip if already interrupted (e.g. rapid cancel clicks)
     if (runtime.interrupted) return;
@@ -20564,12 +20592,14 @@ export function createAgentChatService(args: {
       return;
     }
 
-    // Only prewarm if the session is idle (not mid-turn) and not already warmed
-    if (managed.runtime?.kind === "claude" && (managed.runtime.query || managed.runtime.warmQuery || managed.runtime.warmupDone)) return;
-
-    // Ensure a Claude runtime exists and kick off pre-warming
-    ensureClaudeSessionRuntime(managed);
+    if (managed.session.provider !== "claude") return;
+    if (managed.session.modelId !== descriptor.id) return;
+    if (managed.session.status === "active") return;
+    const runtime = ensureClaudeSessionRuntime(managed);
+    if (runtime.busy) return;
+    if (runtime.query || runtime.warmQuery || runtime.warmupDone) return;
     prewarmClaudeQuery(managed);
+    persistChatState(managed);
   };
 
   const listSubagents = ({ sessionId }: AgentChatSubagentListArgs): AgentChatSubagentSnapshot[] => {

From 7bbba1d770a75c55e6d08953f75ca082fff29f77 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 05:10:13 -0400
Subject: [PATCH 23/24] fix(release): resolve final audit rebase findings

---
 apps/ade-cli/src/cli.test.ts                  |  1 +
 apps/ade-cli/src/cli.ts                       |  1 +
 .../src/tuiClient/__tests__/project.test.ts   | 13 +++++-
 apps/ade-cli/src/tuiClient/cli.tsx            |  7 +++-
 apps/ade-cli/src/tuiClient/project.ts         |  3 +-
 .../services/chat/agentChatService.test.ts    | 41 +++++++++++++++++++
 .../main/services/chat/agentChatService.ts    | 25 ++++++-----
 .../memory/skillRegistryService.test.ts       | 26 ++++++++++++
 .../services/memory/skillRegistryService.ts   |  3 +-
 .../components/prs/tabs/GitHubTab.test.tsx    | 15 ++-----
 .../components/prs/tabs/GitHubTab.tsx         |  7 ----
 11 files changed, 110 insertions(+), 32 deletions(-)

diff --git a/apps/ade-cli/src/cli.test.ts b/apps/ade-cli/src/cli.test.ts
index 6faed0c80..8d7026460 100644
--- a/apps/ade-cli/src/cli.test.ts
+++ b/apps/ade-cli/src/cli.test.ts
@@ -79,6 +79,7 @@ describe("ADE CLI", () => {
     if (plan.kind !== "help") return;
     expect(plan.text).toContain("ade code --socket /tmp/ade.sock");
     expect(plan.text).toContain("ade code --require-socket");
+    expect(plan.text).toContain("ade code --lane <id|name|branch>");
     expect(plan.text).toContain("Command palette");
   });
 
diff --git a/apps/ade-cli/src/cli.ts b/apps/ade-cli/src/cli.ts
index e6153df42..3a5d99831 100644
--- a/apps/ade-cli/src/cli.ts
+++ b/apps/ade-cli/src/cli.ts
@@ -855,6 +855,7 @@ const HELP_BY_COMMAND: Record<string, string> = {
     $ ade code --embedded                          Force the embedded runtime fallback
     $ ade code --require-socket                    Fail instead of embedding when no socket exists
     $ ade code --socket /tmp/ade.sock              Attach to a specific runtime socket
+    $ ade code --lane <id|name|branch>             Launch focused on a specific lane
     $ ade --project-root <path> code                Launch against a specific ADE project
 
   Keys:
diff --git a/apps/ade-cli/src/tuiClient/__tests__/project.test.ts b/apps/ade-cli/src/tuiClient/__tests__/project.test.ts
index 3e380f253..f56899b7c 100644
--- a/apps/ade-cli/src/tuiClient/__tests__/project.test.ts
+++ b/apps/ade-cli/src/tuiClient/__tests__/project.test.ts
@@ -1,6 +1,6 @@
 import path from "node:path";
 import { describe, expect, it } from "vitest";
-import { chooseInitialLane, chooseMostRecentSessionLane, chooseTuiLaunchLane, resolveTuiChatRefreshTarget } from "../project";
+import { chooseInitialLane, chooseMostRecentSessionLane, chooseTuiLaunchLane, detectProjectLaunchContext, resolveTuiChatRefreshTarget } from "../project";
 import type { AgentChatSessionSummary } from "../../../../desktop/src/shared/types/chat";
 import type { LaneSummary } from "../../../../desktop/src/shared/types/lanes";
 
@@ -42,6 +42,17 @@ function chat(sessionId: string, laneId: string, lastActivityAt: string): AgentC
 }
 
 describe("chooseInitialLane", () => {
+  it("accepts an explicit lane hint from the CLI launch context", () => {
+    const context = detectProjectLaunchContext({
+      cwd: "/tmp",
+      projectRoot: "/tmp",
+      workspaceRoot: "/tmp",
+      laneHint: "feature-a",
+    });
+
+    expect(context.laneHint).toBe("feature-a");
+  });
+
   it("prefers the ADE worktree lane hint", () => {
     const lanes = [
       lane({ id: "main", name: "main", laneType: "primary", worktreePath: "/repo" }),
diff --git a/apps/ade-cli/src/tuiClient/cli.tsx b/apps/ade-cli/src/tuiClient/cli.tsx
index 5087c2ac0..7ec25e3e8 100644
--- a/apps/ade-cli/src/tuiClient/cli.tsx
+++ b/apps/ade-cli/src/tuiClient/cli.tsx
@@ -10,6 +10,7 @@ type CliOptions = {
   requireSocket: boolean;
   projectRoot: string | null;
   workspaceRoot: string | null;
+  laneHint: string | null;
   socketPath: string | null;
 };
 
@@ -21,6 +22,7 @@ function parseArgs(argv: string[]): CliOptions {
     requireSocket: false,
     projectRoot: null,
     workspaceRoot: null,
+    laneHint: null,
     socketPath: null,
   };
   for (let i = 0; i < argv.length; i += 1) {
@@ -31,6 +33,7 @@ function parseArgs(argv: string[]): CliOptions {
     else if (arg === "--require-socket") options.requireSocket = true;
     else if (arg === "--project-root") options.projectRoot = argv[++i] ?? null;
     else if (arg === "--workspace-root") options.workspaceRoot = argv[++i] ?? null;
+    else if (arg === "--lane") options.laneHint = argv[++i] ?? null;
     else if (arg === "--socket") options.socketPath = argv[++i] ?? null;
   }
   return options;
@@ -42,7 +45,7 @@ function printHelp(): void {
 Terminal-native ADE Work chat.
 
 Usage:
-  ade code [--project-root <path>] [--workspace-root <path>] [--socket <path>]
+  ade code [--project-root <path>] [--workspace-root <path>] [--lane <id|name|branch>] [--socket <path>]
   ade code --embedded
   ade code --require-socket
   ade code --print-state
@@ -87,6 +90,7 @@ async function printState(options: CliOptions): Promise<void> {
   const project = detectProjectLaunchContext({
     projectRoot: options.projectRoot,
     workspaceRoot: options.workspaceRoot,
+    laneHint: options.laneHint,
   });
   const connection = await connectToAde({
     project,
@@ -126,6 +130,7 @@ export async function runAdeCodeCli(argv: string[] = process.argv.slice(2)): Pro
   const project = detectProjectLaunchContext({
     projectRoot: options.projectRoot,
     workspaceRoot: options.workspaceRoot,
+    laneHint: options.laneHint,
   });
   const instance = render(
     <AdeCodeApp
diff --git a/apps/ade-cli/src/tuiClient/project.ts b/apps/ade-cli/src/tuiClient/project.ts
index 192154de7..bab465f86 100644
--- a/apps/ade-cli/src/tuiClient/project.ts
+++ b/apps/ade-cli/src/tuiClient/project.ts
@@ -45,6 +45,7 @@ export function detectProjectLaunchContext(args: {
   cwd?: string;
   projectRoot?: string | null;
   workspaceRoot?: string | null;
+  laneHint?: string | null;
 } = {}): ProjectLaunchContext {
   const launchCwd = normalizeRoot(args.cwd ?? process.cwd());
   const explicitProjectRoot = args.projectRoot?.trim();
@@ -76,7 +77,7 @@ export function detectProjectLaunchContext(args: {
     launchCwd,
     projectRoot,
     workspaceRoot,
-    laneHint: worktree?.laneHint ?? null,
+    laneHint: args.laneHint?.trim() || worktree?.laneHint || null,
   };
 }
 
diff --git a/apps/desktop/src/main/services/chat/agentChatService.test.ts b/apps/desktop/src/main/services/chat/agentChatService.test.ts
index 26b89cddd..8a00195b9 100644
--- a/apps/desktop/src/main/services/chat/agentChatService.test.ts
+++ b/apps/desktop/src/main/services/chat/agentChatService.test.ts
@@ -1834,6 +1834,47 @@ describe("createAgentChatService", () => {
       expect(opts?.systemPrompt?.append).not.toContain("Commands (file-backed prompts):");
     });
 
+    it("caps discovered command listings in the injected Claude prompt", async () => {
+      const commandsDir = path.join(tmpRoot, ".claude", "commands");
+      fs.mkdirSync(commandsDir, { recursive: true });
+      for (let index = 0; index < 25; index += 1) {
+        fs.writeFileSync(path.join(commandsDir, `cmd-${String(index).padStart(2, "0")}.md`), [
+          "---",
+          `description: Command ${index}`,
+          "---",
+          "",
+          `Run command ${index}.`,
+          "",
+        ].join("\n"));
+      }
+
+      vi.mocked(claudeSdkCreateSessionCompat).mockReturnValue({
+        send: vi.fn(),
+        stream: vi.fn(async function* () {
+          return;
+        }),
+        close: vi.fn(),
+        sessionId: "sdk-session-many-slash-commands",
+      } as any);
+
+      const { service } = createService();
+      await service.createSession({
+        laneId: "lane-1",
+        provider: "claude",
+        model: "sonnet",
+      });
+
+      await vi.waitFor(() => {
+        expect(claudeSdkCreateSessionCompat).toHaveBeenCalled();
+      });
+
+      const opts = vi.mocked(claudeSdkCreateSessionCompat).mock.calls[0]?.[0] as { systemPrompt?: { append?: string } } | undefined;
+      expect(opts?.systemPrompt?.append).toContain("/cmd-00 — Command 0");
+      expect(opts?.systemPrompt?.append).toContain("/cmd-19 — Command 19");
+      expect(opts?.systemPrompt?.append).not.toContain("/cmd-24 — Command 24");
+      expect(opts?.systemPrompt?.append).toContain("5 more command(s) hidden to keep startup context lean");
+    });
+
     it("does not attach ADE-owned tool definitions to Claude SDK sessions", async () => {
       vi.mocked(claudeSdkCreateSessionCompat).mockReturnValue({
         send: vi.fn(),
diff --git a/apps/desktop/src/main/services/chat/agentChatService.ts b/apps/desktop/src/main/services/chat/agentChatService.ts
index ee8e066b2..5cbd615fa 100644
--- a/apps/desktop/src/main/services/chat/agentChatService.ts
+++ b/apps/desktop/src/main/services/chat/agentChatService.ts
@@ -1548,6 +1548,8 @@ type ResolvedChatConfig = {
 };
 
 const MAX_PENDING_STEERS = 10;
+const MAX_INJECTED_PROJECT_COMMANDS = 20;
+const MAX_INJECTED_PROJECT_SKILLS = 20;
 const CURSOR_SDK_AGENT_PROTOCOL_VERSION = 2;
 const CLAUDE_WARMUP_WAIT_TIMEOUT_MS = 20_000;
 
@@ -13565,6 +13567,15 @@ export function createAgentChatService(args: {
       })();
       const projectCommandFiles = projectSlashCommands.filter((cmd) => cmd.source === "command");
       const projectSkillFiles = projectSlashCommands.filter((cmd) => cmd.source === "skill");
+      const visibleProjectCommandFiles = projectCommandFiles.slice(0, MAX_INJECTED_PROJECT_COMMANDS);
+      const visibleProjectSkillFiles = projectSkillFiles.slice(0, MAX_INJECTED_PROJECT_SKILLS);
+      const hiddenProjectCommandCount = projectCommandFiles.length - visibleProjectCommandFiles.length;
+      const hiddenProjectSkillCount = projectSkillFiles.length - visibleProjectSkillFiles.length;
+      const formatDiscoveredCommand = (cmd: (typeof projectSlashCommands)[number]): string => {
+        const desc = cmd.description.trim();
+        const head = desc.length ? `- ${cmd.name} — ${desc}` : `- ${cmd.name}`;
+        return `${head}\n  file: ${cmd.filePath}`;
+      };
       const slashCommandsSection = projectSlashCommands.length
         ? [
           "",
@@ -13576,20 +13587,14 @@ export function createAgentChatService(args: {
           ...(projectCommandFiles.length ? [
             "",
             "Commands (file-backed prompts):",
-            ...projectCommandFiles.map((cmd) => {
-              const desc = cmd.description.trim();
-              const head = desc.length ? `- ${cmd.name} — ${desc}` : `- ${cmd.name}`;
-              return `${head}\n  file: ${cmd.filePath}`;
-            }),
+            ...visibleProjectCommandFiles.map(formatDiscoveredCommand),
+            ...(hiddenProjectCommandCount > 0 ? [`- ${hiddenProjectCommandCount} more command(s) hidden to keep startup context lean. Use slash command search or inspect project command folders if needed.`] : []),
           ] : []),
           ...(projectSkillFiles.length ? [
             "",
             "Skills (autonomously usable when relevant):",
-            ...projectSkillFiles.map((cmd) => {
-              const desc = cmd.description.trim();
-              const head = desc.length ? `- ${cmd.name} — ${desc}` : `- ${cmd.name}`;
-              return `${head}\n  file: ${cmd.filePath}`;
-            }),
+            ...visibleProjectSkillFiles.map(formatDiscoveredCommand),
+            ...(hiddenProjectSkillCount > 0 ? [`- ${hiddenProjectSkillCount} more skill(s) hidden to keep startup context lean. Use slash command search or inspect skill roots if needed.`] : []),
           ] : []),
         ]
         : [];
diff --git a/apps/desktop/src/main/services/memory/skillRegistryService.test.ts b/apps/desktop/src/main/services/memory/skillRegistryService.test.ts
index 96b7dab1d..4e6a86ca5 100644
--- a/apps/desktop/src/main/services/memory/skillRegistryService.test.ts
+++ b/apps/desktop/src/main/services/memory/skillRegistryService.test.ts
@@ -174,4 +174,30 @@ describe("skillRegistryService", () => {
     expect(superseded?.supersededByMemoryId).toBe(imported.memoryId);
     expect(duplicateMemory?.status).toBe("archived");
   });
+
+  it("indexes AGENTS.md as a root doc instead of importing it as a procedure", async () => {
+    const fixture = await createFixture();
+    const rootDocPath = path.join(fixture.projectRoot, "AGENTS.md");
+    fs.writeFileSync(rootDocPath, "# Project agent instructions\n\nKeep release checks honest.\n", "utf8");
+
+    const service = createSkillRegistryService({
+      db: fixture.db,
+      projectId: fixture.projectId,
+      projectRoot: fixture.projectRoot,
+      memoryService: fixture.memoryService,
+      proceduralLearningService: fixture.proceduralLearningService,
+    });
+
+    const indexed = await service.reindexSkills({ paths: [rootDocPath] });
+    const rootDoc = indexed.find((entry) => entry.path === rootDocPath);
+
+    expect(rootDoc?.kind).toBe("root_doc");
+    expect(rootDoc?.memoryId).toBeNull();
+    expect(fixture.memoryService.listMemories({
+      projectId: fixture.projectId,
+      scope: "project",
+      categories: ["procedure"],
+      limit: 10,
+    })).toHaveLength(0);
+  });
 });
diff --git a/apps/desktop/src/main/services/memory/skillRegistryService.ts b/apps/desktop/src/main/services/memory/skillRegistryService.ts
index 767066415..e8967c91e 100644
--- a/apps/desktop/src/main/services/memory/skillRegistryService.ts
+++ b/apps/desktop/src/main/services/memory/skillRegistryService.ts
@@ -51,7 +51,8 @@ function slugify(value: string): string {
 
 function inferKind(filePath: string): SkillIndexKind {
   const normalized = filePath.replace(/\\/g, "/");
-  if (normalized.endsWith("/CLAUDE.md") || normalized.endsWith("/agents.md")) return "root_doc";
+  const basename = path.basename(normalized);
+  if (basename === "CLAUDE.md" || basename.toLowerCase() === "agents.md") return "root_doc";
   if (normalized.includes("/.claude/commands/")) return "command";
   return "skill";
 }
diff --git a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx
index 1c5dbd292..f02990c78 100644
--- a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx
+++ b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.test.tsx
@@ -215,23 +215,16 @@ describe("GitHubTab", () => {
   });
 
   it("shows friendly copy when GitHub is not connected", async () => {
-    (window.ade.github.getStatus as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
-      tokenStored: false,
-      tokenDecryptionFailed: false,
-      storageScope: "app",
-      repo: { owner: "ade-dev", name: "ade" },
-      hasOrigin: true,
-      userLogin: null,
-      scopes: [],
-      checkedAt: "2026-03-13T12:00:00.000Z",
-    });
+    (window.ade.prs.getGitHubSnapshot as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error("Error invoking remote method 'prs:getGitHubSnapshot': Error: GitHub token missing. Set it in Settings to sync pull requests."),
+    );
 
     renderTab();
 
     await waitFor(() => {
       expect(screen.getByText("Connect GitHub in Settings to sync pull requests.")).toBeTruthy();
     });
-    expect(window.ade.prs.getGitHubSnapshot).not.toHaveBeenCalled();
+    expect(window.ade.prs.getGitHubSnapshot).toHaveBeenCalledWith({ force: false });
     expect(screen.queryByText(/Error invoking remote method/)).toBeNull();
     expect(screen.getByRole("button", { name: /connect github/i })).toBeTruthy();
   });
diff --git a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
index afbfa9a55..551849601 100644
--- a/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
+++ b/apps/desktop/src/renderer/components/prs/tabs/GitHubTab.tsx
@@ -496,13 +496,6 @@ export function GitHubTab({
       inFlightSnapshotRef.current?.request === pending
       && inFlightSnapshotRef.current.includeExternalClosed === includeExternalClosed;
     pending = (async () => {
-      const githubStatus = await window.ade.github?.getStatus?.().catch(() => null);
-      if (githubStatus && !githubStatus.tokenStored) {
-        if (projectRootRef.current === requestProjectRoot && isCurrentSnapshotRequest()) {
-          setError("Connect GitHub in Settings to sync pull requests.");
-        }
-        return snapshotRef.current as GitHubPrSnapshot;
-      }
       return window.ade.prs.getGitHubSnapshot({
         force: options?.force === true,
         ...(includeExternalClosed ? { includeExternalClosed: true } : {}),

From ab8331050aa2a249032fbeb6a33fcd231f71fc60 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Thu, 14 May 2026 05:39:58 -0400
Subject: [PATCH 24/24] fix(audit): address release gate review findings

---
 .../src/tuiClient/__tests__/state.test.ts     |  36 +++++-
 apps/ade-cli/src/tuiClient/state.ts           | 108 +++++++++++++---
 .../services/chat/agentChatService.test.ts    |  56 +++++++-
 .../main/services/chat/agentChatService.ts    | 121 +++++++++++++-----
 .../memory/skillRegistryService.test.ts       |  62 +++++++++
 .../services/memory/skillRegistryService.ts   |   6 +-
 .../src/main/services/prs/prService.test.ts   |  11 +-
 .../chat/ChatIosSimulatorPanel.test.tsx       |  44 +++++++
 .../components/chat/ChatIosSimulatorPanel.tsx |  27 ++--
 .../PrDetailPane.issueResolver.test.tsx       |  75 ++++++++++-
 .../components/prs/detail/PrDetailPane.tsx    |  51 +++++---
 11 files changed, 512 insertions(+), 85 deletions(-)

diff --git a/apps/ade-cli/src/tuiClient/__tests__/state.test.ts b/apps/ade-cli/src/tuiClient/__tests__/state.test.ts
index be240cc49..1c70fd560 100644
--- a/apps/ade-cli/src/tuiClient/__tests__/state.test.ts
+++ b/apps/ade-cli/src/tuiClient/__tests__/state.test.ts
@@ -1,5 +1,12 @@
-import { describe, expect, it } from "vitest";
-import { normalizeAdeCodeState, scopedAdeCodeState } from "../state";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { loadAdeCodeState, normalizeAdeCodeState, saveAdeCodeProjectState, scopedAdeCodeState } from "../state";
+
+afterEach(() => {
+  delete process.env.ADE_CODE_STATE_DIR;
+});
 
 describe("ade code persisted state", () => {
   it("prefers project-scoped lane and chat state over legacy global fallback", () => {
@@ -61,4 +68,29 @@ describe("ade code persisted state", () => {
       lastLaneByProject: { "/repo-a": "repo-a-lane" },
     });
   });
+
+  it("merges project-scoped saves with existing state under the shared state file", () => {
+    const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "ade-code-state-"));
+    process.env.ADE_CODE_STATE_DIR = stateDir;
+
+    saveAdeCodeProjectState("/repo-a", {
+      lastChatByLane: { main: "repo-a-chat" },
+      lastLaneId: "repo-a-lane",
+    });
+    saveAdeCodeProjectState("/repo-b", {
+      lastChatByLane: { main: "repo-b-chat" },
+      lastLaneId: "repo-b-lane",
+    });
+
+    const persisted = loadAdeCodeState();
+    expect(persisted.lastChatByProjectLane).toEqual({
+      [path.resolve("/repo-a")]: { main: "repo-a-chat" },
+      [path.resolve("/repo-b")]: { main: "repo-b-chat" },
+    });
+    expect(persisted.lastLaneByProject).toEqual({
+      [path.resolve("/repo-a")]: "repo-a-lane",
+      [path.resolve("/repo-b")]: "repo-b-lane",
+    });
+    expect(fs.existsSync(path.join(stateDir, "ade-code-state.json.lock"))).toBe(false);
+  });
 });
diff --git a/apps/ade-cli/src/tuiClient/state.ts b/apps/ade-cli/src/tuiClient/state.ts
index 5dc9d6899..1508fbb08 100644
--- a/apps/ade-cli/src/tuiClient/state.ts
+++ b/apps/ade-cli/src/tuiClient/state.ts
@@ -10,11 +10,15 @@ export type AdeCodeState = {
 };
 
 const STATE_DIR = path.join(os.homedir(), ".ade");
-const STATE_PATH = path.join(STATE_DIR, "ade-code-state.json");
+const STATE_FILE = "ade-code-state.json";
+const STATE_LOCK_FILE = `${STATE_FILE}.lock`;
+const STATE_LOCK_TIMEOUT_MS = 2_000;
+const STATE_LOCK_STALE_MS = 30_000;
+const STATE_LOCK_RETRY_MS = 25;
 
 export function loadAdeCodeState(): AdeCodeState {
   try {
-    const raw = fs.readFileSync(STATE_PATH, "utf8");
+    const raw = fs.readFileSync(getStatePath(), "utf8");
     return normalizeAdeCodeState(JSON.parse(raw));
   } catch {
     return emptyAdeCodeState();
@@ -22,9 +26,16 @@ export function loadAdeCodeState(): AdeCodeState {
 }
 
 export function saveAdeCodeState(state: AdeCodeState): void {
+  withStateLock(() => writeAdeCodeStateUnlocked(state));
+}
+
+function writeAdeCodeStateUnlocked(state: AdeCodeState): void {
   try {
-    fs.mkdirSync(STATE_DIR, { recursive: true });
-    fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), "utf8");
+    const { dir, path: statePath } = getStatePaths();
+    fs.mkdirSync(dir, { recursive: true });
+    const tempPath = `${statePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tempPath, JSON.stringify(state, null, 2), "utf8");
+    fs.renameSync(tempPath, statePath);
   } catch {
     // best-effort persistence; ignore
   }
@@ -45,17 +56,19 @@ export function saveAdeCodeProjectState(
   projectRoot: string,
   projectState: Pick<AdeCodeState, "lastChatByLane" | "lastLaneId">,
 ): void {
-  const current = loadAdeCodeState();
-  const projectKey = normalizeProjectKey(projectRoot);
-  current.lastChatByProjectLane[projectKey] = { ...projectState.lastChatByLane };
-  if (projectState.lastLaneId) {
-    current.lastLaneByProject[projectKey] = projectState.lastLaneId;
-  } else {
-    delete current.lastLaneByProject[projectKey];
-  }
-  current.lastChatByLane = { ...projectState.lastChatByLane };
-  current.lastLaneId = projectState.lastLaneId;
-  saveAdeCodeState(current);
+  withStateLock(() => {
+    const current = loadAdeCodeState();
+    const projectKey = normalizeProjectKey(projectRoot);
+    current.lastChatByProjectLane[projectKey] = { ...projectState.lastChatByLane };
+    if (projectState.lastLaneId) {
+      current.lastLaneByProject[projectKey] = projectState.lastLaneId;
+    } else {
+      delete current.lastLaneByProject[projectKey];
+    }
+    current.lastChatByLane = { ...projectState.lastChatByLane };
+    current.lastLaneId = projectState.lastLaneId;
+    writeAdeCodeStateUnlocked(current);
+  });
 }
 
 export function normalizeAdeCodeState(value: unknown): AdeCodeState {
@@ -83,6 +96,71 @@ function normalizeProjectKey(projectRoot: string): string {
   return path.resolve(projectRoot);
 }
 
+function getStatePaths(): { dir: string; path: string; lockPath: string } {
+  const dir = process.env.ADE_CODE_STATE_DIR || STATE_DIR;
+  return {
+    dir,
+    path: path.join(dir, STATE_FILE),
+    lockPath: path.join(dir, STATE_LOCK_FILE),
+  };
+}
+
+function getStatePath(): string {
+  return getStatePaths().path;
+}
+
+function withStateLock(write: () => void): void {
+  const { dir, lockPath } = getStatePaths();
+  let fd: number | null = null;
+  const deadline = Date.now() + STATE_LOCK_TIMEOUT_MS;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    while (fd === null) {
+      try {
+        fd = fs.openSync(lockPath, "wx");
+        fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== "EEXIST") throw error;
+        removeStaleStateLock(lockPath);
+        if (Date.now() >= deadline) return;
+        sleepSync(STATE_LOCK_RETRY_MS);
+      }
+    }
+    write();
+  } catch {
+    // best-effort persistence; ignore
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // ignore
+      }
+      try {
+        fs.unlinkSync(lockPath);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+function removeStaleStateLock(lockPath: string): void {
+  try {
+    const stat = fs.statSync(lockPath);
+    if (Date.now() - stat.mtimeMs > STATE_LOCK_STALE_MS) {
+      fs.unlinkSync(lockPath);
+    }
+  } catch {
+    // ignore
+  }
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
 function normalizeStringRecord(value: unknown): Record<string, string> {
   const normalized: Record<string, string> = {};
   if (!value || typeof value !== "object" || Array.isArray(value)) return normalized;
diff --git a/apps/desktop/src/main/services/chat/agentChatService.test.ts b/apps/desktop/src/main/services/chat/agentChatService.test.ts
index 8a00195b9..21aed911b 100644
--- a/apps/desktop/src/main/services/chat/agentChatService.test.ts
+++ b/apps/desktop/src/main/services/chat/agentChatService.test.ts
@@ -3301,14 +3301,17 @@ describe("createAgentChatService", () => {
       });
 
       expect(result.outputText).toContain("Recovered");
-      expect(claudeSdkResumeSessionCompat).toHaveBeenCalledWith(expect.any(String), expect.any(Object));
+      expect(claudeSdkResumeSessionCompat).toHaveBeenCalledWith(
+        "sdk-stale",
+        expect.objectContaining({ resume: "sdk-stale" }),
+      );
       expect(claudeSdkCreateSessionCompat).toHaveBeenCalledWith(expect.objectContaining({
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,
       }));
       expect(staleSession.close).toHaveBeenCalled();
       expect(freshSession.send).toHaveBeenCalled();
-      expect(readPersistedChatState(session.id).sdkSessionId).toEqual(expect.any(String));
+      expect(readPersistedChatState(session.id).sdkSessionId).toBe("sdk-fresh");
     });
 
     it("persists a continuity snapshot and prewarms a fresh Claude session after identity session reset errors", async () => {
@@ -5263,6 +5266,28 @@ describe("createAgentChatService", () => {
       );
       expect(sessionService.deleteSession).toHaveBeenCalledWith(session.id);
     });
+
+    it("does not follow transcript symlinks outside ADE during purge", async () => {
+      const { service, sessionService } = createService();
+      const session = await service.createSession({
+        laneId: "lane-1",
+        provider: "opencode",
+        model: "",
+        modelId: "opencode/anthropic/claude-sonnet-4-6",
+      });
+
+      const mainTranscriptPath = sessionService.get(session.id)?.transcriptPath ?? "";
+      const outsideTranscriptPath = path.join(tmpHomeRoot, "outside-transcript.jsonl");
+      fs.writeFileSync(outsideTranscriptPath, "{\"event\":\"done\"}\n", "utf8");
+      fs.mkdirSync(path.dirname(mainTranscriptPath), { recursive: true });
+      fs.rmSync(mainTranscriptPath, { force: true });
+      fs.symlinkSync(outsideTranscriptPath, mainTranscriptPath);
+
+      await service.deleteSession({ sessionId: session.id });
+
+      expect(fs.existsSync(outsideTranscriptPath)).toBe(true);
+      expect(sessionService.deleteSession).toHaveBeenCalledWith(session.id);
+    });
   });
 
   // --------------------------------------------------------------------------
@@ -7509,6 +7534,33 @@ describe("createAgentChatService", () => {
       ]);
     });
 
+    it("does not hydrate transcript symlinks that resolve outside ADE", async () => {
+      const { service } = createService();
+      const session = await service.createSession({
+        laneId: "lane-1",
+        provider: "codex",
+        model: "gpt-5.4",
+      });
+
+      const envelope: AgentChatEventEnvelope = {
+        sessionId: session.id,
+        timestamp: new Date().toISOString(),
+        event: { type: "text", text: "outside-transcript" },
+        sequence: 1,
+      };
+      const transcriptFile = path.join(tmpRoot, "transcripts", `${session.id}.chat.jsonl`);
+      const outsideTranscriptPath = path.join(tmpHomeRoot, "outside-transcript.jsonl");
+      fs.writeFileSync(outsideTranscriptPath, `${JSON.stringify(envelope)}\n`, "utf8");
+      fs.rmSync(transcriptFile, { force: true });
+      fs.symlinkSync(outsideTranscriptPath, transcriptFile);
+      vi.mocked(parseAgentChatTranscript).mockReturnValue([envelope]);
+
+      const history = service.getChatEventHistory(session.id);
+
+      expect(history.events).toEqual([]);
+      expect(parseAgentChatTranscript).not.toHaveBeenCalled();
+    });
+
     it("drops history when the underlying session is deleted", async () => {
       // We don't rely on sendMessage emitting events (mock streams vary across
       // providers), so we seed the transcript directly to verify the cleanup
diff --git a/apps/desktop/src/main/services/chat/agentChatService.ts b/apps/desktop/src/main/services/chat/agentChatService.ts
index 5cbd615fa..db4d642ce 100644
--- a/apps/desktop/src/main/services/chat/agentChatService.ts
+++ b/apps/desktop/src/main/services/chat/agentChatService.ts
@@ -1152,6 +1152,8 @@ type ClaudeDaemonResponse = {
   present?: boolean;
 };
 
+const MAX_CLAUDE_DAEMON_RESPONSE_BYTES = 1024 * 1024;
+
 function sleepMs(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1271,8 +1273,17 @@ function extractClaudeBackgroundTranscriptText(state: ClaudeBackgroundJobState |
   const configRoot = path.resolve(claudeConfigDir());
   if (!resolvedPath.startsWith(`${configRoot}${path.sep}`)) return "";
   if (!fs.existsSync(resolvedPath)) return "";
+  let realPath = resolvedPath;
+  let realConfigRoot = configRoot;
+  try {
+    realPath = fs.realpathSync(resolvedPath);
+    realConfigRoot = fs.realpathSync(configRoot);
+  } catch {
+    return "";
+  }
+  if (!realPath.startsWith(`${realConfigRoot}${path.sep}`)) return "";
   try {
-    const text = readFileTailUtf8(resolvedPath);
+    const text = readFileTailUtf8(realPath);
     let latest = "";
     for (const line of text.split(/\n+/)) {
       if (!line.trim()) continue;
@@ -1330,6 +1341,10 @@ async function sendClaudeDaemonRequest(
       socket.write(`${JSON.stringify({ proto: 1, ...request })}\n`);
     });
     socket.on("data", (chunk) => {
+      if (Buffer.byteLength(buffer, "utf8") + chunk.length > MAX_CLAUDE_DAEMON_RESPONSE_BYTES) {
+        finish(() => reject(new Error("Claude daemon response exceeded the 1MB limit.")));
+        return;
+      }
       buffer += chunk.toString("utf8");
       const newline = buffer.indexOf("\n");
       const raw = (newline >= 0 ? buffer.slice(0, newline) : buffer).trim();
@@ -5278,8 +5293,9 @@ export function createAgentChatService(args: {
 
   const readTranscriptConversationEntries = (managed: ManagedChatSession): string[] => {
     try {
-      flushQueuedTranscriptWrite(managed.transcriptPath);
-      const raw = fs.readFileSync(managed.transcriptPath, "utf8");
+      const transcriptPath = resolveReadableChatPath(managed.transcriptPath, "agent_chat.transcript_read_skipped_path_outside_ade");
+      if (!transcriptPath) return [];
+      const raw = fs.readFileSync(transcriptPath, "utf8");
       return parseAgentChatTranscript(raw)
         .filter((entry) => entry.sessionId === managed.session.id)
         .flatMap((entry) => {
@@ -5300,8 +5316,9 @@ export function createAgentChatService(args: {
 
   const readTranscriptEntries = (managed: ManagedChatSession): AgentChatTranscriptEntry[] => {
     try {
-      flushQueuedTranscriptWrite(managed.transcriptPath);
-      const raw = fs.readFileSync(managed.transcriptPath, "utf8");
+      const transcriptPath = resolveReadableChatPath(managed.transcriptPath, "agent_chat.transcript_read_skipped_path_outside_ade");
+      if (!transcriptPath) return [];
+      const raw = fs.readFileSync(transcriptPath, "utf8");
       const entries: AgentChatTranscriptEntry[] = [];
       for (const entry of parseAgentChatTranscript(raw)) {
         if (entry.sessionId !== managed.session.id) continue;
@@ -5341,8 +5358,9 @@ export function createAgentChatService(args: {
     managed: ManagedChatSession,
   ): Extract<AgentChatEvent, { type: "todo_update" }>["items"] => {
     try {
-      flushQueuedTranscriptWrite(managed.transcriptPath);
-      const raw = fs.readFileSync(managed.transcriptPath, "utf8");
+      const transcriptPath = resolveReadableChatPath(managed.transcriptPath, "agent_chat.transcript_read_skipped_path_outside_ade");
+      if (!transcriptPath) return [];
+      const raw = fs.readFileSync(transcriptPath, "utf8");
       let latest: Extract<AgentChatEvent, { type: "todo_update" }>["items"] = [];
       for (const entry of parseAgentChatTranscript(raw)) {
         if (entry.sessionId !== managed.session.id) continue;
@@ -5443,8 +5461,9 @@ export function createAgentChatService(args: {
 
   const readTranscriptEnvelopes = (managed: ManagedChatSession): AgentChatEventEnvelope[] => {
     try {
-      flushQueuedTranscriptWrite(managed.transcriptPath);
-      return parseAgentChatTranscript(fs.readFileSync(managed.transcriptPath, "utf8"))
+      const transcriptPath = resolveReadableChatPath(managed.transcriptPath, "agent_chat.transcript_read_skipped_path_outside_ade");
+      if (!transcriptPath) return [];
+      return parseAgentChatTranscript(fs.readFileSync(transcriptPath, "utf8"))
         .filter((entry) => entry.sessionId === managed.session.id);
     } catch {
       return [];
@@ -5480,8 +5499,9 @@ export function createAgentChatService(args: {
     const managed = managedSessions.get(sessionId);
     if (managed?.transcriptPath) {
       try {
-        flushQueuedTranscriptWrite(managed.transcriptPath);
-        return parseAgentChatTranscript(fs.readFileSync(managed.transcriptPath, "utf8"))
+        const transcriptPath = resolveReadableChatPath(managed.transcriptPath, "agent_chat.transcript_read_skipped_path_outside_ade");
+        if (!transcriptPath) return [];
+        return parseAgentChatTranscript(fs.readFileSync(transcriptPath, "utf8"))
           .filter((entry) => entry.sessionId === sessionId);
       } catch {
         return [];
@@ -5496,9 +5516,9 @@ export function createAgentChatService(args: {
     ];
     for (const candidatePath of candidates) {
       try {
-        flushQueuedTranscriptWrite(candidatePath);
-        if (!fs.existsSync(candidatePath)) continue;
-        const raw = fs.readFileSync(candidatePath, "utf8");
+        const transcriptPath = resolveReadableChatPath(candidatePath, "agent_chat.transcript_read_skipped_path_outside_ade");
+        if (!transcriptPath) continue;
+        const raw = fs.readFileSync(transcriptPath, "utf8");
         return parseAgentChatTranscript(raw).filter((entry) => entry.sessionId === sessionId);
       } catch {
         // try next candidate
@@ -6744,32 +6764,57 @@ export function createAgentChatService(args: {
 
   const metadataPathFor = (sessionId: string): string => path.join(chatSessionsDir, `${sessionId}.json`);
 
-  const deletePersistedChatFile = (filePath: string | null | undefined): void => {
+  const safeRealpath = (p: string): string | null => {
+    try { return fs.realpathSync(p); } catch { return null; }
+  };
+
+  const isWithinRoot = (target: string, root: string | null): boolean => {
+    if (!root) return false;
+    const rel = path.relative(root, target);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+  };
+
+  const resolveContainedChatPath = (
+    filePath: string | null | undefined,
+    warnEvent = "agent_chat.chat_file_skipped_path_outside_ade",
+    allowMissing = false,
+  ): string | null => {
     const trimmed = typeof filePath === "string" ? filePath.trim() : "";
-    if (!trimmed.length) return;
+    if (!trimmed.length) return null;
     const resolvedPath = path.resolve(trimmed);
-    // Resolve symlinks on the target and both roots before comparing, so a
-    // symlink placed inside the chat dir cannot redirect rmSync outside.
-    const safeRealpath = (p: string): string | null => {
-      try { return fs.realpathSync(p); } catch { return null; }
-    };
+    const resolvedAdeDir = path.resolve(layout.adeDir);
+    const resolvedTranscriptRoot = path.resolve(transcriptsDir);
+    if (!isWithinRoot(resolvedPath, resolvedAdeDir) && !isWithinRoot(resolvedPath, resolvedTranscriptRoot)) {
+      logger.warn(warnEvent, { filePath: resolvedPath });
+      return null;
+    }
     const realTarget = safeRealpath(resolvedPath);
-    // Missing target is safe to skip — nothing to delete.
-    if (!realTarget) return;
+    if (!realTarget) return allowMissing ? resolvedPath : null;
     const realAdeDir = safeRealpath(layout.adeDir);
     const realTranscriptRoot = safeRealpath(path.resolve(transcriptsDir));
-    const isWithin = (root: string | null): boolean => {
-      if (!root) return false;
-      const rel = path.relative(root, realTarget);
-      return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
-    };
-    if (!isWithin(realAdeDir) && !isWithin(realTranscriptRoot)) {
-      logger.warn("agent_chat.delete_skipped_path_outside_ade", {
+    if (!isWithinRoot(realTarget, realAdeDir) && !isWithinRoot(realTarget, realTranscriptRoot)) {
+      logger.warn(warnEvent, {
         filePath: resolvedPath,
         realTarget,
       });
-      return;
+      return null;
     }
+    return realTarget;
+  };
+
+  const resolveReadableChatPath = (
+    filePath: string | null | undefined,
+    warnEvent = "agent_chat.transcript_read_skipped_path_outside_ade",
+  ): string | null => {
+    if (!resolveContainedChatPath(filePath, warnEvent, true)) return null;
+    const trimmed = typeof filePath === "string" ? filePath.trim() : "";
+    flushQueuedTranscriptWrite(path.resolve(trimmed));
+    return resolveContainedChatPath(filePath, warnEvent);
+  };
+
+  const deletePersistedChatFile = (filePath: string | null | undefined): void => {
+    const realTarget = resolveContainedChatPath(filePath, "agent_chat.delete_skipped_path_outside_ade");
+    if (!realTarget) return;
     try {
       fs.rmSync(realTarget, { force: true });
     } catch (error) {
@@ -9178,8 +9223,11 @@ export function createAgentChatService(args: {
         // system:init — capture data silently (no UI emission)
         if (msg.type === "system" && (msg as any).subtype === "init") {
           const initMsg = msg as any;
-          if (typeof initMsg.session_id === "string" && initMsg.session_id.trim().length > 0 && runtime.sdkSessionId !== initMsg.session_id) {
-            runtime.sdkSessionId = initMsg.session_id;
+          const initSessionId = typeof initMsg.session_id === "string"
+            ? initMsg.session_id.trim()
+            : "";
+          if (initSessionId.length > 0 && runtime.sdkSessionId !== initSessionId) {
+            runtime.sdkSessionId = initSessionId;
             mirrorClaudeSessionPointer(managed, runtime.sdkSessionId);
             persistChatState(managed);
           }
@@ -10348,8 +10396,15 @@ export function createAgentChatService(args: {
       emitChatEvent(managed, { type: "text", text: stateText, turnId });
       persistChatState(managed);
     };
+    const isManagedSessionStopped = (): boolean =>
+      managed.closed
+      || managed.session.status !== "active"
+      || (managed.runtime?.kind === "claude" && managed.runtime.interrupted);
 
     while (Date.now() - start < maxDurationMs) {
+      if (isManagedSessionStopped()) {
+        return { status: "interrupted", assistantText, state: lastState };
+      }
       lastState = readClaudeBackgroundJobState(short);
       if (lastState) {
         rememberClaudeBackgroundJob(managed, short, lastState);
diff --git a/apps/desktop/src/main/services/memory/skillRegistryService.test.ts b/apps/desktop/src/main/services/memory/skillRegistryService.test.ts
index 4e6a86ca5..00031ee0b 100644
--- a/apps/desktop/src/main/services/memory/skillRegistryService.test.ts
+++ b/apps/desktop/src/main/services/memory/skillRegistryService.test.ts
@@ -125,6 +125,68 @@ describe("skillRegistryService", () => {
     expect(markExportedSkill).toHaveBeenCalledWith("proc-1", exported.path);
   });
 
+  it("quotes exported skill descriptions so trigger punctuation cannot break frontmatter", async () => {
+    const fixture = await createFixture();
+    const service = createSkillRegistryService({
+      db: fixture.db,
+      projectId: fixture.projectId,
+      projectRoot: fixture.projectRoot,
+      memoryService: fixture.memoryService,
+      proceduralLearningService: {
+        getProcedureDetail: () => ({
+          memory: {
+            id: "proc-yaml",
+            scope: "project",
+            scopeOwnerId: null,
+            tier: 2,
+            pinned: false,
+            category: "procedure",
+            content: "Trigger: fixing quoted branch names",
+            importance: "high",
+            createdAt: "2026-03-11T12:00:00.000Z",
+            updatedAt: "2026-03-11T12:00:00.000Z",
+            lastAccessedAt: "2026-03-11T12:00:00.000Z",
+            accessCount: 0,
+            observationCount: 1,
+            status: "promoted",
+            confidence: 0.8,
+            embedded: false,
+            sourceRunId: null,
+            sourceType: "system",
+            sourceId: null,
+            fileScopePattern: null,
+          },
+          procedural: {
+            id: "proc-yaml",
+            trigger: "fixing \"critical\" bugs: branch main\nwithout breaking YAML",
+            procedure: "## Recommended Procedure\n1. Keep frontmatter valid.",
+            confidence: 0.8,
+            successCount: 1,
+            failureCount: 0,
+            sourceEpisodeIds: [],
+            lastUsed: null,
+            createdAt: "2026-03-11T12:00:00.000Z",
+          },
+          exportedSkillPath: null,
+          exportedAt: null,
+          supersededByMemoryId: null,
+          sourceEpisodes: [],
+          confidenceHistory: [],
+        }),
+        markExportedSkill: vi.fn(),
+        markProcedureSuperseded: vi.fn(),
+      },
+    });
+
+    const exported = await service.exportProcedureSkill({ id: "proc-yaml", name: "YAML Skill" });
+    if (!exported) throw new Error("Expected exported skill");
+
+    const content = fs.readFileSync(exported.path, "utf8");
+    expect(content).toContain(
+      'description: "Use this skill when fixing \\"critical\\" bugs: branch main\\nwithout breaking YAML."',
+    );
+  });
+
   it("supersedes near-duplicate system procedures when importing user skills", async () => {
     const fixture = await createFixture();
     const skillPath = path.join(fixture.projectRoot, ".claude", "skills", "testing-guide.md");
diff --git a/apps/desktop/src/main/services/memory/skillRegistryService.ts b/apps/desktop/src/main/services/memory/skillRegistryService.ts
index e8967c91e..dc68e5d1a 100644
--- a/apps/desktop/src/main/services/memory/skillRegistryService.ts
+++ b/apps/desktop/src/main/services/memory/skillRegistryService.ts
@@ -144,7 +144,7 @@ function buildSkillMarkdown(input: {
   const lines = [
     "---",
     `name: ${slugify(input.title)}`,
-    `description: Use this skill when ${input.trigger.trim() || "the workflow applies"}.`,
+    `description: ${yamlQuotedScalar(`Use this skill when ${input.trigger.trim() || "the workflow applies"}.`)}`,
     "---",
     "",
     `# ${input.title}`,
@@ -165,6 +165,10 @@ function buildSkillMarkdown(input: {
   return lines.join("\n").trim();
 }
 
+function yamlQuotedScalar(value: string): string {
+  return JSON.stringify(value.replace(/\r\n?/g, "\n"));
+}
+
 export function createSkillRegistryService(args: {
   db: AdeDb;
   projectId: string;
diff --git a/apps/desktop/src/main/services/prs/prService.test.ts b/apps/desktop/src/main/services/prs/prService.test.ts
index 8f75b6e90..2efb3ed5d 100644
--- a/apps/desktop/src/main/services/prs/prService.test.ts
+++ b/apps/desktop/src/main/services/prs/prService.test.ts
@@ -1124,7 +1124,7 @@ describe("prService.getActionRuns", () => {
       html_url: `https://github.com/test-owner/test-repo/actions/runs/${index + 1}`,
       created_at: `2026-01-01T00:${String(index).padStart(2, "0")}:00Z`,
       updated_at: `2026-01-01T00:${String(index).padStart(2, "0")}:30Z`,
-    }));
+    })).reverse();
     const githubService = makeGithubService({
       apiRequest: vi.fn(async (args: { path: string }) => {
         if (args.path === "/repos/test-owner/test-repo/pulls/90") {
@@ -1167,7 +1167,14 @@ describe("prService.getActionRuns", () => {
       head_sha: "head-sha",
       per_page: 12,
     });
-    expect(calls.filter((call) => /\/actions\/runs\/\d+\/jobs$/.test(call.path))).toHaveLength(6);
+    expect(calls.filter((call) => /\/actions\/runs\/\d+\/jobs$/.test(call.path)).map((call) => call.path)).toEqual([
+      "/repos/test-owner/test-repo/actions/runs/20/jobs",
+      "/repos/test-owner/test-repo/actions/runs/19/jobs",
+      "/repos/test-owner/test-repo/actions/runs/18/jobs",
+      "/repos/test-owner/test-repo/actions/runs/17/jobs",
+      "/repos/test-owner/test-repo/actions/runs/16/jobs",
+      "/repos/test-owner/test-repo/actions/runs/15/jobs",
+    ]);
   });
 });
 
diff --git a/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.test.tsx b/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.test.tsx
index 501cf6a49..b1277d4db 100644
--- a/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.test.tsx
+++ b/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.test.tsx
@@ -615,6 +615,50 @@ describe("ChatIosSimulatorPanel", () => {
     expect(api.tap).not.toHaveBeenCalled();
   });
 
+  it("blocks live simulator input when another chat owns the controls", async () => {
+    const { api } = installIosSimulatorApi({
+      status: {
+        ...activeStatus,
+        activeSession: {
+          ...activeStatus.activeSession!,
+          chatSessionId: "chat-2",
+        },
+      },
+    });
+
+    render(
+      <ChatIosSimulatorPanel
+        sessionId="chat-1"
+        projectRoot="/tmp/project"
+        onAddContext={vi.fn()}
+      />,
+    );
+
+    const canvas = await screen.findByLabelText("iOS Simulator live stream") as HTMLCanvasElement;
+    const mediaRect = {
+      x: 0,
+      y: 0,
+      left: 0,
+      top: 0,
+      right: 393,
+      bottom: 852,
+      width: 393,
+      height: 852,
+      toJSON: () => ({}),
+    } as DOMRect;
+    canvas.getBoundingClientRect = () => mediaRect;
+    const liveSurface = canvas.closest("[tabindex]") as HTMLDivElement;
+
+    fireEvent.keyDown(liveSurface, { key: "a" });
+    fireEvent.pointerDown(liveSurface, { clientX: 50, clientY: 40, pointerId: 1 });
+    fireEvent.pointerUp(liveSurface, { clientX: 50, clientY: 40, pointerId: 1 });
+
+    expect(await screen.findByText("Another chat is already connected to the simulator. Use Take over to claim it.")).toBeTruthy();
+    expect(api.typeText).not.toHaveBeenCalled();
+    expect(api.tap).not.toHaveBeenCalled();
+    expect(api.drag).not.toHaveBeenCalled();
+  });
+
   it("selects an inspected simulator element and opens Preview Lab for its matching target", async () => {
     vi.stubGlobal("PointerEvent", MouseEvent);
     vi.stubGlobal("Image", class {
diff --git a/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.tsx b/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.tsx
index 74692587d..58bfec5be 100644
--- a/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.tsx
+++ b/apps/desktop/src/renderer/components/chat/ChatIosSimulatorPanel.tsx
@@ -1161,6 +1161,9 @@ export function ChatIosSimulatorPanel({
   }, [activeSession?.chatSessionId, sessionId]);
   const ownedByOtherChat = otherChatSessionId !== null;
   const controlsOwnedElsewhere = ownedByOtherChat || controlsDisabled;
+  const inputBlockedMessage = ownedByOtherChat
+    ? "Another chat is already connected to the simulator. Use Take over to claim it."
+    : controlsDisabledMessage;
 
   const toggleSimulatorWindowMode = useCallback(() => {
     if (!activeSession || controlsOwnedElsewhere) return;
@@ -2221,8 +2224,8 @@ export function ChatIosSimulatorPanel({
   const sendTypedText = useCallback(async () => {
     const text = typedText;
     if (!text.trim()) return;
-    if (controlsDisabled) {
-      setMessage(controlsDisabledMessage);
+    if (controlsOwnedElsewhere) {
+      setMessage(inputBlockedMessage);
       return;
     }
     setTypedText("");
@@ -2232,7 +2235,7 @@ export function ChatIosSimulatorPanel({
     } catch (error) {
       setMessage(error instanceof Error ? error.message : String(error));
     }
-  }, [armWindowCaptureRecoveryAfterInput, controlsDisabled, controlsDisabledMessage, projectRoot, selectedDeviceUdid, typedText]);
+  }, [armWindowCaptureRecoveryAfterInput, controlsOwnedElsewhere, inputBlockedMessage, projectRoot, selectedDeviceUdid, typedText]);
 
   const updateInspectBounds = useCallback(() => {
     const image = imageRef.current;
@@ -2753,6 +2756,10 @@ export function ChatIosSimulatorPanel({
   }, [liveVisualKind, mapLivePointToSimulatorPixel, mediaHeight, mediaWidth]);
 
   const handleSnapshotInteractPointerDown = useCallback((event: PointerEvent<HTMLDivElement>) => {
+    if (controlsOwnedElsewhere) {
+      setMessage(inputBlockedMessage);
+      return;
+    }
     const point = liveSimulatorPointFromPointer(event);
     if (!point) return;
     dragStartRef.current = {
@@ -2762,14 +2769,14 @@ export function ChatIosSimulatorPanel({
       clientY: event.clientY,
     };
     event.currentTarget.setPointerCapture(event.pointerId);
-  }, [liveSimulatorPointFromPointer]);
+  }, [controlsOwnedElsewhere, inputBlockedMessage, liveSimulatorPointFromPointer]);
 
   const handleSnapshotInteractPointerUp = useCallback((event: PointerEvent<HTMLDivElement>) => {
     const start = dragStartRef.current;
     dragStartRef.current = null;
     if (!start) return;
-    if (controlsDisabled) {
-      setMessage(controlsDisabledMessage);
+    if (controlsOwnedElsewhere) {
+      setMessage(inputBlockedMessage);
       return;
     }
     const point = liveSimulatorPointFromPointer(event);
@@ -2798,12 +2805,12 @@ export function ChatIosSimulatorPanel({
         setMessage(error instanceof Error ? error.message : String(error));
       }
     })();
-  }, [armWindowCaptureRecoveryAfterInput, controlsDisabled, controlsDisabledMessage, liveSimulatorPointFromPointer, projectRoot, selectedDeviceUdid, snapshot?.screen.scale]);
+  }, [armWindowCaptureRecoveryAfterInput, controlsOwnedElsewhere, inputBlockedMessage, liveSimulatorPointFromPointer, projectRoot, selectedDeviceUdid, snapshot?.screen.scale]);
 
   const handleVideoKeyDown = useCallback((event: KeyboardEvent<HTMLDivElement>) => {
     if (event.metaKey || event.ctrlKey || event.altKey) return;
-    if (controlsDisabled) {
-      setMessage(controlsDisabledMessage);
+    if (controlsOwnedElsewhere) {
+      setMessage(inputBlockedMessage);
       return;
     }
     if (event.key === "Enter") {
@@ -2821,7 +2828,7 @@ export function ChatIosSimulatorPanel({
         setMessage(error instanceof Error ? error.message : String(error));
       });
     }
-  }, [armWindowCaptureRecoveryAfterInput, controlsDisabled, controlsDisabledMessage, projectRoot, selectedDeviceUdid]);
+  }, [armWindowCaptureRecoveryAfterInput, controlsOwnedElsewhere, inputBlockedMessage, projectRoot, selectedDeviceUdid]);
 
   const providerSummary = snapshot?.providers.map((provider) => {
     if (provider.source === "screenshot") return "screenshot";
diff --git a/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.issueResolver.test.tsx b/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.issueResolver.test.tsx
index 2f6020948..62aef3c75 100644
--- a/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.issueResolver.test.tsx
+++ b/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.issueResolver.test.tsx
@@ -286,6 +286,8 @@ function renderPane(args: {
   freshChecks?: PrCheck[];
   actionRuns?: PrActionRun[];
   freshActionRuns?: PrActionRun[];
+  reviews?: PrReview[];
+  comments?: PrComment[];
   reviewThreads: PrReviewThread[];
   lanes?: LaneSummary[];
   laneStatusOverrides?: Partial<LaneSummary["status"]>;
@@ -526,14 +528,17 @@ function renderPane(args: {
     },
   });
 
+  let currentChecks = args.checks;
+  let currentReviews = args.reviews ?? [];
+  let currentComments = args.comments ?? [];
   const renderSubject = (prOverrides: Partial<PrWithConflicts> = args.prOverrides ?? {}) => (
     <MemoryRouter>
       <PrDetailPane
         pr={makePr(prOverrides)}
         status={args.status === undefined ? makeStatus(args.statusOverrides) : args.status}
-        checks={args.checks}
-        reviews={[]}
-        comments={[]}
+        checks={currentChecks}
+        reviews={currentReviews}
+        comments={currentComments}
         snapshotHydration={args.snapshotHydration}
         snapshotHydrationOwnedByContext={args.snapshotHydrationOwnedByContext}
         liveDetailReady={args.liveDetailReady}
@@ -571,7 +576,10 @@ function renderPane(args: {
     writeClipboardText,
     land,
     onRefresh,
-    rerenderPane: (prOverrides: Partial<PrWithConflicts>) => {
+    rerenderPane: (prOverrides: Partial<PrWithConflicts>, nextDetail?: { checks?: PrCheck[]; reviews?: PrReview[]; comments?: PrComment[] }) => {
+      currentChecks = nextDetail?.checks ?? currentChecks;
+      currentReviews = nextDetail?.reviews ?? currentReviews;
+      currentComments = nextDetail?.comments ?? currentComments;
       rendered.rerender(renderSubject({ ...(args.prOverrides ?? {}), ...prOverrides }));
     },
     ...rendered,
@@ -737,6 +745,65 @@ describe("PrDetailPane issue resolver CTA", () => {
     });
   });
 
+  it("updates synthesized activity when selected PR detail inputs refresh", async () => {
+    const user = userEvent.setup();
+    const { rerenderPane } = renderPane({
+      checks: [makeCheck({ name: "Old CI", conclusion: "success" })],
+      reviewThreads: [],
+      prOverrides: {
+        checksStatus: "passing",
+        updatedAt: "2026-03-23T12:00:00.000Z",
+      },
+    });
+
+    await user.click(screen.getByRole("button", { name: /activity/i }));
+    await waitFor(() => {
+      expect(screen.getByText("Old CI: success")).toBeTruthy();
+    });
+
+    rerenderPane(
+      {
+        checksStatus: "failing",
+        updatedAt: "2026-03-23T12:01:00.000Z",
+      },
+      { checks: [makeCheck({ name: "New CI", conclusion: "failure" })] },
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("New CI: failure")).toBeTruthy();
+      expect(screen.queryByText("Old CI: success")).toBeNull();
+    });
+  });
+
+  it("synthesizes unique activity keys for duplicate review and check identities", async () => {
+    const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    try {
+      const user = userEvent.setup();
+      renderPane({
+        checks: [
+          makeCheck({ name: "CodeRabbit", detailsUrl: null, startedAt: null, completedAt: null }),
+          makeCheck({ name: "CodeRabbit", detailsUrl: null, startedAt: null, completedAt: null }),
+        ],
+        reviews: [
+          makeReview({ reviewer: "reviewer", submittedAt: "2026-03-23T12:05:00.000Z", body: "First review" }),
+          makeReview({ reviewer: "reviewer", submittedAt: "2026-03-23T12:05:00.000Z", body: "Second review" }),
+        ],
+        reviewThreads: [],
+      });
+
+      await user.click(screen.getByRole("button", { name: /activity/i }));
+
+      await waitFor(() => {
+        expect(screen.getAllByText("CodeRabbit: failure")).toHaveLength(2);
+        expect(screen.getByText("First review")).toBeTruthy();
+        expect(screen.getByText("Second review")).toBeTruthy();
+      });
+      expect(consoleErrorSpy.mock.calls.some((call) => String(call[0]).includes("Encountered two children with the same key"))).toBe(false);
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
   it("uses context-owned snapshot hydration without a duplicate snapshot IPC", async () => {
     const user = userEvent.setup();
     const snapshot: PrSnapshotHydration = {
diff --git a/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.tsx b/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.tsx
index 87f9ffc5b..717c166e9 100644
--- a/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.tsx
+++ b/apps/desktop/src/renderer/components/prs/detail/PrDetailPane.tsx
@@ -289,15 +289,27 @@ function activityEventColor(ev: PrActivityEvent): string {
   return COLORS.textMuted;
 }
 
+function stableActivityIdPart(value: string | number | null | undefined): string {
+  return encodeURIComponent(String(value ?? "none"));
+}
+
+function makeUniqueActivityId(base: string, seenIds: Map<string, number>): string {
+  const seen = seenIds.get(base) ?? 0;
+  seenIds.set(base, seen + 1);
+  return seen === 0 ? base : `${base}-${seen + 1}`;
+}
+
 function buildActivityFromLoadedDetail(
   checks: PrCheck[],
   reviews: PrReview[],
   comments: PrComment[],
 ): PrActivityEvent[] {
   const events: PrActivityEvent[] = [];
+  const seenIds = new Map<string, number>();
   for (const comment of comments) {
+    const baseId = `comment-${stableActivityIdPart(comment.id)}`;
     events.push({
-      id: `comment-${comment.id}`,
+      id: makeUniqueActivityId(baseId, seenIds),
       type: "comment",
       author: comment.author,
       avatarUrl: comment.authorAvatarUrl ?? null,
@@ -312,8 +324,13 @@ function buildActivityFromLoadedDetail(
     });
   }
   for (const review of reviews) {
+    const baseId = [
+      "review",
+      stableActivityIdPart(review.reviewer),
+      stableActivityIdPart(review.submittedAt),
+    ].join("-");
     events.push({
-      id: `review-${review.reviewer}-${review.submittedAt ?? ""}`,
+      id: makeUniqueActivityId(baseId, seenIds),
       type: "review",
       author: review.reviewer,
       avatarUrl: review.reviewerAvatarUrl ?? null,
@@ -323,8 +340,14 @@ function buildActivityFromLoadedDetail(
     });
   }
   for (const check of checks) {
+    const baseId = [
+      "ci",
+      stableActivityIdPart(check.name),
+      stableActivityIdPart(check.detailsUrl),
+      stableActivityIdPart(check.startedAt),
+    ].join("-");
     events.push({
-      id: `ci-${check.name}`,
+      id: makeUniqueActivityId(baseId, seenIds),
       type: "ci_run",
       author: "github-actions",
       avatarUrl: null,
@@ -555,10 +578,6 @@ export function PrDetailPane({
   const checks = liveDetailReady ? liveChecks : (hasSnapshotDetail ? snapshotChecks : liveChecks);
   const reviews = liveDetailReady ? liveReviews : (hasSnapshotDetail ? snapshotReviews : liveReviews);
   const comments = liveDetailReady ? liveComments : (hasSnapshotDetail ? snapshotComments : liveComments);
-  const loadedDetailActivityRef = React.useRef({ checks, reviews, comments });
-  React.useEffect(() => {
-    loadedDetailActivityRef.current = { checks, reviews, comments };
-  }, [checks, comments, reviews]);
 
   const setActiveTab = React.useCallback((tab: DetailTab) => {
     setActiveTabState(tab);
@@ -864,8 +883,6 @@ export function PrDetailPane({
       setFiles(f);
       setCommits(c);
       setActionRuns(a);
-      const loaded = loadedDetailActivityRef.current;
-      setActivity((prev) => prev.length > 0 ? prev : buildActivityFromLoadedDetail(loaded.checks, loaded.reviews, loaded.comments));
     } catch {
       // silently fail - basic data still available from context
     }
@@ -953,9 +970,11 @@ export function PrDetailPane({
     void refreshReviewThreads();
   }, [loadDetail, pr.checksStatus, pr.id, pr.reviewStatus, pr.updatedAt, refreshReviewThreads]);
 
-  React.useEffect(() => {
-    setActivity((prev) => prev.length > 0 ? prev : buildActivityFromLoadedDetail(checks, reviews, comments));
-  }, [checks, comments, pr.id, reviews]);
+  const derivedActivity = React.useMemo(
+    () => buildActivityFromLoadedDetail(checks, reviews, comments),
+    [checks, comments, reviews],
+  );
+  const visibleActivity = activity.length > 0 ? activity : derivedActivity;
 
   React.useEffect(() => {
     const shouldLoadImmediately = activeTab === "activity" || Boolean(deepLinkState.eventId);
@@ -2233,7 +2252,7 @@ export function PrDetailPane({
     { id: "convergence", label: "Path to Merge", icon: Sparkle, count: newIssueCount > 0 ? newIssueCount : undefined },
     { id: "files", label: "Files", icon: Code, count: files.length },
     { id: "checks", label: "CI / Checks", icon: Play, count: buildUnifiedChecks(checks, actionRuns).length },
-    { id: "activity", label: "Activity", icon: ClockCounterClockwise, count: activity.length > 0 ? activity.length : (comments.length + reviews.length) },
+    { id: "activity", label: "Activity", icon: ClockCounterClockwise, count: visibleActivity.length },
   ];
 
   return (
@@ -2403,7 +2422,7 @@ export function PrDetailPane({
             checks={checks}
             reviews={reviews}
             comments={comments}
-            activity={activity}
+            activity={visibleActivity}
             commits={commits}
             files={files}
             reviewThreads={reviewThreadsForTimeline}
@@ -2443,7 +2462,7 @@ export function PrDetailPane({
             onOpenRebaseTab={onOpenRebaseTab}
             matchingRebaseItemId={matchingRebaseItemId}
             localBehindCount={localBehindCount}
-            activity={activity}
+            activity={visibleActivity}
             lanes={lanes}
           />
         )}
@@ -2551,7 +2570,7 @@ export function PrDetailPane({
         )}
         {activeTab === "activity" && (
           <ActivityTab
-            activity={activity} comments={comments} reviews={reviews}
+            activity={visibleActivity} comments={comments} reviews={reviews}
             commentDraft={commentDraft} setCommentDraft={setCommentDraft}
             actionBusy={actionBusy} onAddComment={handleAddComment}
           />