Merge remote-tracking branch 'origin/main' into cursor/critical-correctness-bugs-8d53

Author: arul28

.agents/skills/ade-web/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: ade-web
+description: >-
+  Launch the ADE desktop app's renderer as a standalone web app (Vite-only preview)
+  seeded with real data from the ADE database. Works from any lane worktree without
+  interfering with running ADE sockets or runtimes. Use when asked to start, run, or
+  preview the ADE desktop web renderer, open the ADE web app, or view ADE UI in a browser.
+metadata:
+  author: ADE
+  version: 0.1.0
+---
+
+# ade-web — Launch the ADE Desktop Web Renderer
+
+Starts the ADE desktop renderer as a browser-accessible web app on `http://localhost:5173`,
+seeded with a snapshot of the real ADE database. Safe to run alongside the ADE beta or
+any other running ADE runtime — it does **not** touch sockets or start new runtimes.
+
+## When to use
+
+- User asks to run, start, preview, or open the ADE web app / desktop web renderer
+- User wants to visually inspect or iterate on ADE desktop UI changes in a browser
+- User asks to launch ADE web from a specific lane or worktree
+
+## Procedure
+
+### 1. Resolve the workspace root
+
+The web renderer must run from the **current lane's worktree**, not the main project checkout.
+
+```
+WORKTREE_ROOT="$(pwd)"
+```
+
+If `pwd` is not already inside `.ade/worktrees/<lane>/`, resolve it:
+
+```
+# If inside a worktree, pwd is already correct.
+# If at the project root, there is no lane context — ask the user which lane.
+```
+
+Confirm the desktop app exists at `$WORKTREE_ROOT/apps/desktop/package.json`.
+
+### 2. Kill any stale Vite on port 5173
+
+```bash
+lsof -ti :5173 2>/dev/null | xargs kill 2>/dev/null
+```
+
+Do **not** kill processes on any other port. Do **not** touch ADE runtime sockets
+(`/tmp/ade-runtime-dev.sock`, `~/.ade-beta/sock/ade.sock`, etc.).
+
+### 3. Seed the database snapshot
+
+Export real data from the global ADE database into the browser mock:
+
+```bash
+cd "$WORKTREE_ROOT/apps/desktop" && node ./scripts/export-browser-mock-ade-snapshot.mjs
+```
+
+This reads `.ade/ade.db` from the primary project root (auto-detected even from worktrees)
+and writes `src/renderer/browser-mock-ade-snapshot.generated.json`.
+
+If this fails with "No database", the user hasn't opened the project in ADE desktop yet.
+The renderer will still work with built-in demo data.
+
+### 4. Start the Vite dev server
+
+```bash
+cd "$WORKTREE_ROOT/apps/desktop" && npm run dev:vite
+```
+
+This runs `vite --port 5173 --strictPort`. The `predev:vite` hook re-exports the
+snapshot automatically, so step 3 is optional if you go straight here.
+
+Wait for the `VITE ready` message confirming it's listening.
+
+### 5. Open in the ADE browser (optional)
+
+If the user wants it in ADE's built-in browser:
+
+```bash
+ade actions run built_in_browser createTab --socket --text --arg url=http://localhost:5173/work
+```
+
+Or navigate an existing tab:
+
+```bash
+ade actions run built_in_browser navigate --socket --text --arg url=http://localhost:5173/work
+```
+
+Use `--socket` to communicate with the running ADE instance. This does **not** start a
+new runtime or interfere with the existing socket.
+
+## Important constraints
+
+- **Never start a runtime or bridge.** Do not run `dev:vite:live`, `dev:browser-bridge`,
+  or `ensureRuntime`. These may detect version mismatches and restart the user's running
+  ADE beta/dev runtime.
+- **Never start or manage the ADE socket directly.** The Vite-only preview uses
+  `browserMock.ts` to stub `window.ade` — it does not need a runtime connection.
+  The `--socket` flag on `ade actions run` above is fine; it connects to the
+  running desktop instance rather than managing the socket itself.
+- **Always run from the worktree.** All `cd` commands, file reads, and file edits must
+  target paths under `$WORKTREE_ROOT`, never the main project checkout. When `grep` or
+  `find` returns absolute paths rooted at the main checkout, translate them to the
+  worktree before editing.
+- **Port 5173 only.** Do not change the port. The desktop app's Vite config uses
+  `--strictPort` so it will error if the port is taken rather than silently picking another.
+
+## Cleanup
+
+When done, kill the Vite server:
+
+```bash
+lsof -ti :5173 2>/dev/null | xargs kill 2>/dev/null
+```
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `Port 5173 is already in use` | Kill the stale process: `lsof -ti :5173 \| xargs kill` |
+| `No database at ...` | Run `export-browser-mock-ade-snapshot.mjs` with `ADE_PROJECT_ROOT=/path/to/ADE` pointing at the main checkout |
+| `ERR_CONNECTION_REFUSED` in ADE browser | Vite died — restart with `npm run dev:vite` from the worktree |
+| Mock data instead of real data | Re-run the export script, then restart Vite or hard-refresh the browser |
+| `proxy error: /health ECONNREFUSED 127.0.0.1:18765` | Expected — this is the browser bridge port. Vite-only mode doesn't use it. Ignore. |

AGENTS.md

@@ -82,6 +82,22 @@ Desktop release:
 - Validation commands are documented in the "Validation" section above.
 - The desktop test suite is large; CI shards it. For local iteration, run a single file or one CI-style shard rather than the full suite.
 
+### Working in ADE lanes (worktrees)
+
+- When an agent session runs inside an ADE lane, its working directory is the lane's worktree (e.g. `/path/to/ADE/.ade/worktrees/<lane-slug>/`). **All file reads, edits, and writes MUST target paths under that worktree, never under the main project-root checkout.**
+- `grep`, `find`, and Explore agents may return absolute paths rooted at the main checkout. Before editing, translate those paths to the worktree: replace the project root prefix with the worktree root. For example, `/Users/admin/Projects/ADE/apps/desktop/src/foo.ts` becomes `<worktree>/apps/desktop/src/foo.ts`.
+- Use relative paths from your working directory whenever possible — they resolve to the worktree automatically.
+- If `ADE_REPO_ROOT` is set in the environment, use it as the canonical base for all file operations.
+- When launching dev servers (Vite, Electron, etc.) for a lane, run them from the worktree, not the main checkout: `cd <worktree>/apps/desktop && npm run dev:vite`.
+
+### Running the ADE desktop web renderer (Vite-only preview)
+
+- The desktop renderer can run standalone in a browser without Electron via `npm run dev:vite` in `apps/desktop`. This starts Vite on port 5173 with a browser mock for `window.ade`.
+- To seed the mock with real data from the ADE database, run `npm run export:browser-mock-ade` in `apps/desktop` first, or let the `predev:vite` hook do it automatically. The export script reads `.ade/ade.db` from the primary project root and writes a snapshot to `src/renderer/browser-mock-ade-snapshot.generated.json`.
+- This works from any lane worktree: `cd <worktree>/apps/desktop && npm run dev:vite`. The export script detects worktree paths and resolves the `.ade/ade.db` location from the parent project root.
+- For live data (connected to the ADE runtime socket instead of mock data), use `npm run dev:vite:live`. This starts both Vite and a browser-runtime bridge. Note: this calls `ensureRuntime` which may restart a stale dev runtime — avoid if the ADE beta or another runtime is already running on the target socket.
+- Open `http://localhost:5173/work` in a browser or ADE's built-in browser to view the Work tab.
+
 ### Inspecting the local Electron desktop app with Codex Computer Use on macOS
 
 - To inspect ADE desktop parity locally with Codex Computer Use, launch the dev app from the worktree with `npm run dev` in `apps/desktop`.

apps/ade-cli/README.md

@@ -234,6 +234,7 @@ ade lanes create "lin-123" --linear-issue-json '{"id":"...","identifier":"LIN-12
 ade lanes reparent lane-child --parent lane-parent --stack-base-branch main
 ade --role cto linear quick-view --text
 ade --role cto linear search-issues --query "auth" --state-type started,unstarted --first 50
+ade --role cto linear issue-comments --issue-id <linear-issue-uuid>
 ade git commit --lane lane-id
 ade git push --lane lane-id
 ade git pull --lane lane-id --rebase

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

@@ -654,6 +654,9 @@ function createRuntime() {
         issues: [{ id: "issue-1", identifier: "ADE-123", title: "Test", _query: query }],
         pageInfo: { hasNextPage: false, endCursor: null },
       })),
+      fetchIssueComments: vi.fn(async (issueId: string) => [
+        { id: "comment-1", body: "First comment", createdAt: "2026-03-17T19:00:00.000Z", userName: "arul", userDisplayName: "Arul" },
+      ]),
     } as any,
     linearSyncService: {
       getDashboard: vi.fn(() => ({ enabled: true, running: false, ingressMode: "webhook-first", reconciliationIntervalSec: 60, lastPollAt: null, lastSuccessAt: null, lastError: null, queue: { queued: 1, blocked: 0, failed: 0 }, workflowRuns: { active: 1, waiting: 0 }, recentIssues: [] })),
@@ -1584,6 +1587,21 @@ describe("adeRpcServer", () => {
     );
   });
 
+  it("fetches Linear issue comments via getLinearIssueComments", async () => {
+    const { runtime } = createRuntime();
+    const handler = createAdeRpcRequestHandler({ runtime, serverVersion: "test" });
+
+    await initialize(handler, { callerId: "cto-1", role: "cto" });
+    const result = await callTool(handler, "getLinearIssueComments", {
+      issueId: "issue-1",
+    });
+
+    expect((runtime.linearIssueTracker as any).fetchIssueComments).toHaveBeenCalledWith("issue-1");
+    expect(result.structuredContent).toEqual([
+      expect.objectContaining({ id: "comment-1", body: "First comment" }),
+    ]);
+  });
+
   it("forwards employeeOverride and laneId when resuming a Linear sync queue item", async () => {
     const { runtime } = createRuntime();
     const handler = createAdeRpcRequestHandler({ runtime, serverVersion: "test" });

apps/ade-cli/src/adeRpcServer.ts

@@ -1533,6 +1533,18 @@ const CTO_LINEAR_SYNC_TOOL_SPECS: ToolSpec[] = [
       }
     }
   },
+  {
+    name: "getLinearIssueComments",
+    description: "Fetch comments on a Linear issue by its ID.",
+    inputSchema: {
+      type: "object",
+      required: ["issueId"],
+      additionalProperties: false,
+      properties: {
+        issueId: { type: "string", minLength: 1 }
+      }
+    }
+  },
   {
     name: "getLinearSyncDashboard",
     description: "Read the ADE Linear sync dashboard.",
@@ -1692,6 +1704,7 @@ const READ_ONLY_TOOLS = new Set([
   "getLinearQuickView",
   "getLinearIssuePickerData",
   "searchLinearIssues",
+  "getLinearIssueComments",
   "listLinearWorkflows",
   "getLinearRunStatus",
   "getLinearSyncDashboard",
@@ -3477,6 +3490,12 @@ async function runTool(args: {
       });
     }
 
+    if (name === "getLinearIssueComments") {
+      const issueId = assertNonEmptyString(toolArgs.issueId, "issueId");
+      const tracker = requireLinearIssueTracker(runtime);
+      return await tracker.fetchIssueComments(issueId);
+    }
+
     if (name === "getLinearSyncDashboard") {
       return requireLinearSyncService(runtime).getDashboard();
     }
@@ -5202,55 +5221,6 @@ export function createAdeRpcRequestHandler(args: {
     },
   };
 
-  const auditActionCall = async (
-    actionName: string,
-    actionArgs: Record<string, unknown>,
-    runner: () => Promise<unknown>
-  ): Promise<unknown> => {
-    const startedAt = Date.now();
-    const laneId = resolveRequestedOrSessionLaneId(runtime, session, actionArgs);
-    const operation = runtime.operationService.start({
-      laneId,
-      kind: "ade_action_call",
-      metadata: {
-        action: actionName,
-        callerId: session.identity.callerId,
-        role: session.identity.role,
-        chatSessionId: session.identity.chatSessionId,
-        runId: session.identity.runId,
-        stepId: session.identity.stepId,
-        attemptId: session.identity.attemptId,
-        ownerId: session.identity.ownerId,
-        args: sanitizeForAudit(actionArgs)
-      }
-    });
-
-    try {
-      const result = await runner();
-      runtime.operationService.finish({
-        operationId: operation.operationId,
-        status: "succeeded",
-        metadataPatch: {
-          resultStatus: "success",
-          durationMs: Date.now() - startedAt,
-          result: sanitizeForAudit(result)
-        }
-      });
-      return result;
-    } catch (error) {
-      runtime.operationService.finish({
-        operationId: operation.operationId,
-        status: "failed",
-        metadataPatch: {
-          resultStatus: "failed",
-          durationMs: Date.now() - startedAt,
-          errorMessage: error instanceof Error ? error.message : String(error)
-        }
-      });
-      throw error;
-    }
-  };
-
   const listActions = async (): Promise<Record<string, unknown>> => {
     const actionSpecs = await listToolSpecsForSession(runtime, session);
     return {
@@ -5263,18 +5233,16 @@ export function createAdeRpcRequestHandler(args: {
   };
 
   const callAction = async (actionName: string, actionArgs: Record<string, unknown>): Promise<unknown> => {
-    return await auditActionCall(actionName, actionArgs, async () => {
-      if (
-        READ_ONLY_TOOLS.has(actionName) ||
-        MUTATION_TOOLS.has(actionName) ||
-        actionName === "spawn_agent" ||
-        actionName === "ask_user"
-      ) {
-        return await runTool({ runtime, session, name: actionName, toolArgs: actionArgs });
-      }
+    if (
+      READ_ONLY_TOOLS.has(actionName) ||
+      MUTATION_TOOLS.has(actionName) ||
+      actionName === "spawn_agent" ||
+      actionName === "ask_user"
+    ) {
+      return await runTool({ runtime, session, name: actionName, toolArgs: actionArgs });
+    }
 
-      throw new JsonRpcError(JsonRpcErrorCode.methodNotFound, `Unsupported ADE action: ${actionName}`);
-    });
+    throw new JsonRpcError(JsonRpcErrorCode.methodNotFound, `Unsupported ADE action: ${actionName}`);
   };
 
   const handler = (async (request: JsonRpcRequest): Promise<unknown | null> => {
@@ -5405,48 +5373,35 @@ export function createAdeRpcRequestHandler(args: {
       if (isCtoOnlyAdeAction("pty", ptyAction) && !callerHasRoleAtLeast(session.identity.role, "cto")) {
         throw new JsonRpcError(JsonRpcErrorCode.methodNotFound, `Unsupported PTY method: ${method}`);
       }
-      const runPtyAction = async (runner: () => Promise<unknown> | unknown): Promise<unknown> =>
-        auditActionCall(method, ptyArgs, async () => runner());
       if (method === "pty.create") {
         ensurePtyCreateAuthorized(runtime, session, method, ptyArgs);
-        return await runPtyAction(async () => {
-          const result = await runtime.ptyService.create(ptyArgs as Parameters<typeof runtime.ptyService.create>[0]);
-          return {
-            ...result,
-            session: runtime.sessionService.get(result.sessionId),
-          };
-        });
+        const result = await runtime.ptyService.create(ptyArgs as Parameters<typeof runtime.ptyService.create>[0]);
+        return {
+          ...result,
+          session: runtime.sessionService.get(result.sessionId),
+        };
       }
       if (method === "pty.sendToSession") {
         ensurePtyTargetAuthorized(runtime, session, method, ptyArgs);
-        return await runPtyAction(() =>
-          runtime.ptyService.sendToSession(ptyArgs as Parameters<typeof runtime.ptyService.sendToSession>[0]));
+        return await runtime.ptyService.sendToSession(ptyArgs as Parameters<typeof runtime.ptyService.sendToSession>[0]);
       }
       if (method === "pty.write") {
         ensurePtyTargetAuthorized(runtime, session, method, ptyArgs);
-        return await runPtyAction(() => {
-          runtime.ptyService.write(ptyArgs as Parameters<typeof runtime.ptyService.write>[0]);
-          return null;
-        });
+        runtime.ptyService.write(ptyArgs as Parameters<typeof runtime.ptyService.write>[0]);
+        return null;
       }
       if (method === "pty.resize") {
         ensurePtyTargetAuthorized(runtime, session, method, ptyArgs);
-        return await runPtyAction(() => {
-          runtime.ptyService.resize(ptyArgs as Parameters<typeof runtime.ptyService.resize>[0]);
-          return null;
-        });
+        runtime.ptyService.resize(ptyArgs as Parameters<typeof runtime.ptyService.resize>[0]);
+        return null;
       }
       if (method === "pty.dispose") {
         ensurePtyTargetAuthorized(runtime, session, method, ptyArgs);
-        return await runPtyAction(() => {
-          runtime.ptyService.dispose(ptyArgs as Parameters<typeof runtime.ptyService.dispose>[0]);
-          return null;
-        });
+        runtime.ptyService.dispose(ptyArgs as Parameters<typeof runtime.ptyService.dispose>[0]);
+        return null;
       }
       if (method === "pty.list") {
-        return await runPtyAction(() => ({
-          sessions: listAuthorizedPtySessions(runtime, session, method, ptyArgs),
-        }));
+        return { sessions: listAuthorizedPtySessions(runtime, session, method, ptyArgs) };
       }
       throw new JsonRpcError(JsonRpcErrorCode.methodNotFound, `Unsupported PTY method: ${method}`);
     }

apps/ade-cli/src/bootstrap.ts

@@ -977,7 +977,6 @@ export async function createAdeRuntime(args: {
     logger,
     pollIntervalMs: 120_000,
     onUpdate: (snapshot) => pushEvent("runtime", { type: "usage", snapshot }),
-    onThresholdEvent: (event) => pushEvent("runtime", { type: "usage_threshold", event }),
   });
   const budgetCapService = createBudgetCapService({
     db,