arul28 · arul28 · Apr 2, 2026 · Apr 2, 2026 · Apr 2, 2026 · Apr 2, 2026
@@ -4,7 +4,6 @@ local.secret.yaml
 ade.db
 ade.db-*
 ade.db-wal
-*.bak
 embeddings.db
 mcp.sock
 artifacts/

@@ -1,14 +1,7 @@
 name: CTO
-version: 2
-persona: >-
-  You are the CTO for this project inside ADE.
-
-  You are the persistent technical lead who owns architecture, execution
-  quality, engineering continuity, and team direction.
-
-  Use ADE's tools and project context to help the team move forward with clear,
-  concrete decisions.
-personality: strategic
+version: 3
+persona: Persistent project CTO with collaborative personality.
+personality: casual
 modelPreferences:
   provider: claude
   model: sonnet
@@ -29,6 +22,7 @@ openclawContextPolicy:
     - token
     - system_prompt
 onboardingState:
-  completedSteps: []
-  dismissedAt: 2026-04-01T23:35:05.209Z
-updatedAt: 2026-04-01T23:35:05.211Z
+  completedSteps:
+    - identity
+  completedAt: 2026-04-02T14:20:19.124Z
+updatedAt: 2026-04-02T14:20:19.127Z
@@ -5,6 +5,25 @@ All notable changes to ADE will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Packed session grid** — resizable tile layout for the Work view with per-session column/row spans, drag-handle resizing on all edges and corners, and a bin-packing algorithm for compact arrangement (`PackedSessionGrid`, `packedSessionGridMath`)
+- **Multi-select agent questions** — `AgentQuestionModal` now supports toggling multiple predefined options per question, with a Markdown/HTML preview pane for selected option descriptions (via `ReactMarkdown` + `rehype-sanitize`)
+- **New Chat quick-create** — faster optimistic session opening from the Work view with immediate tab activation before the backend session is ready
+- **Turn recap** — `chatTranscriptRows` emits a `turn_recap` summary row at the end of each turn, aggregating tool invocation counts and status
+- **Claude tool-use tracking** — per-invocation lifecycle tracking via `toolUseID`; `tool_use_start` and `tool_use_complete` events enable per-tool status indicators in the work log
+- **MCP initialize probe** — Claude runtime pre-checks MCP server availability before starting a session
+
+### Changed
+
+- **Terminal renderer fallback** — simplified from three tiers (WebGL/canvas/DOM) to two (WebGL-first with DOM fallback); added fit recovery with retry on invalid dimensions and `fitRecoveries` health counter
+- **Work log headings** — human-readable labels (e.g. "Read utils.ts", "Run shell", "Write index.ts") replace generic tool identifiers; default visible entries increased from 1 to 4
+- **Model catalog filtering** — `UnifiedModelSelector` accepts `catalogMode: "available-only"` to restrict the picker to models available via configured providers
+- **Git stash actions** — stash pop, drop, and clear now refresh workspace metadata after completion
+- **Composer sizing** — new compact and grid-tile sizing modes in `ChatComposerShell`
+
 ## [1.0.2] - 2026-03-15
 
 ### Added

@@ -1,52 +1,112 @@
 ---
 title: "Claude Code"
-description: "Use Claude Code as a CLI coding agent inside ADE lanes."
+description: "Use Claude Code as a CLI coding agent inside ADE lanes — launch sessions, connect MCP tools, configure permissions, and track work across agent chat, missions, and CTO delegations."
 icon: "terminal"
 ---
 
 ## Overview
 
 ADE integrates with [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Anthropic's CLI agent for coding tasks. When Claude Code is installed on your machine, ADE can launch it as a managed session inside any lane.
 
+Claude Code is one of ADE's deepest integrations — it serves as both a chat provider (for Agent Chat) and an execution backend (for missions, CTO workers, and automations). ADE manages the Claude Code process lifecycle, injects MCP tools, forwards environment variables, and tracks every session in the History view.
+
+---
+
 ## Requirements
 
-- Claude Code installed (`npm install -g @anthropic-ai/claude-code`)
-- An active Anthropic API key or Claude subscription
+| Requirement | Details |
+|------------|---------|
+| **Claude Code installed** | `npm install -g @anthropic-ai/claude-code` |
+| **Authentication** | An active Anthropic API key or Claude subscription. ADE probes the Claude Code runtime at startup to verify authentication. If auth fails, the AI settings indicator shows amber with instructions. |
+
+ADE auto-detects the Claude Code executable from standard paths and PATH. If detection fails, check **Settings > AI Providers** for the status and diagnostic message.
+
+---
 
-## How ADE uses Claude Code
+## How ADE Uses Claude Code
 
-ADE launches Claude Code as a subprocess inside a lane's worktree. The session inherits the lane's environment variables, working directory, and port assignments.
+ADE launches Claude Code as a subprocess inside a lane's worktree. The session inherits the lane's environment variables, working directory, port assignments, and MCP tool configuration.
 
 Claude Code sessions are used in several places:
 
-- **Agent Chat** -- when you select Claude Code as the executor in a lane chat session
-- **Missions** -- as a worker executor (`claude_cli`) during mission execution phases
-- **CTO workers** -- when the CTO delegates a task to an employee agent using Claude Code
-- **Automations** -- as the execution backend for automation rules
+| Surface | How Claude Code is used |
+|---------|------------------------|
+| **Agent Chat** | Select Claude as the provider in the model selector. ADE starts a Claude Code session with MCP tools bridged in. |
+| **Missions** | Used as a worker executor (`claude_cli`) during mission execution phases. Each worker gets its own Claude Code process. |
+| **CTO Workers** | When the CTO delegates a task to an employee agent, it can use Claude Code as the execution backend. |
+| **Automations** | Automation rules with `agent-session` execution kind can use Claude Code as the underlying agent. |
+
+---
 
 ## Launching Claude Code from ADE
 
 <Steps>
   <Step title="Open a lane">
-    Navigate to the lane where you want to run Claude Code.
+    Navigate to the lane where you want to run Claude Code. The agent will work in this lane's worktree.
   </Step>
   <Step title="Open the Run tab">
     Click the **Run** tab or use the AI tool launcher in Project Home.
   </Step>
   <Step title="Launch Claude Code">
-    Click the **Claude Code** launcher. ADE starts a managed session with the lane's context pack injected as initial context.
+    Click the **Claude Code** launcher. ADE starts a managed session with:
+    - The lane's context pack injected as initial context
+    - MCP tools from ADE's server available to the agent
+    - Environment variables from the lane's overlay applied
+    - The working directory set to the lane's worktree path
   </Step>
 </Steps>
 
-## Permission modes
+---
+
+## MCP Tool Bridging
+
+When ADE launches Claude Code, it bridges ADE's MCP tools into the Claude Code session. This means the Claude Code agent can use ADE-specific tools (file operations, git operations, PR management, lane management) alongside its built-in capabilities.
+
+ADE runs a pre-session **MCP initialize probe** to verify that the MCP server is reachable before starting the Claude Code session. If the probe fails, ADE reports the error in the chat UI instead of starting a broken session.
+
+---
+
+## Permission Modes
 
 ADE supports several permission modes for Claude Code sessions:
 
 | Mode | Behavior |
 |------|----------|
-| `default` | Standard Claude Code permissions |
-| `plan` | Planning only, no file writes |
-| `acceptEdits` | Auto-accept file edits |
-| `bypassPermissions` | Skip all permission prompts |
+| `default` | Standard Claude Code permissions — the agent asks before making changes |
+| `plan` | Planning only — the agent can read files and reason but cannot write or execute |
+| `acceptEdits` | Auto-accept file edits — the agent can write files without asking, but still asks for terminal commands |
+| `bypassPermissions` | Skip all permission prompts — full autonomy. Use with caution. |
+
+Configure the default permission mode in **Settings > AI Providers** or per-mission in the mission creation dialog. For CTO-delegated workers, the CTO sets the permission mode based on the task's risk level.
+
+---
+
+## Connection Status
+
+ADE shows Claude Code's connection status in **Settings > AI Providers**:
+
+| Status | Meaning |
+|--------|---------|
+| **Ready** (green) | Claude Code executable found, authenticated, and runtime probe passed |
+| **Auth failed** (amber) | Claude Code is installed but not authenticated. Run `claude auth login` in a terminal or use `/login` in chat. |
+| **Not found** (gray) | Claude Code CLI not detected. Install it with `npm install -g @anthropic-ai/claude-code`. |
+| **Runtime failed** (red) | Claude Code is installed but the runtime probe failed. Check ADE's developer logs for details. |
+
+---
+
+## Troubleshooting
 
-Configure the default permission mode in **Settings > AI Providers** or per-mission in the mission creation dialog.
+<AccordionGroup>
+  <Accordion title="Claude Code not detected" icon="circle-question">
+    ADE checks standard installation paths and PATH for the Claude Code executable. If installed in a non-standard location, ensure `claude` is available in your PATH. Verify with `which claude` in a terminal.
+  </Accordion>
+  <Accordion title="Authentication errors in chat" icon="lock">
+    Run `claude auth login` in a terminal outside ADE, then restart ADE or click **Refresh** in Settings > AI Providers. ADE caches the runtime probe result for 30 seconds, so the status updates shortly after re-authentication.
+  </Accordion>
+  <Accordion title="MCP tools not available to the agent" icon="plug">
+    Check that the MCP initialize probe passed (visible in the chat session's startup messages). If the probe failed, verify that ADE's MCP server is running — check **Settings > MCP** for server status.
+  </Accordion>
+  <Accordion title="Session hangs or times out" icon="clock">
+    The runtime probe has a 20-second timeout. If your network is slow or the Anthropic API is under load, the probe may fail. Check your internet connection and try again. If sessions consistently hang, check the developer logs for detailed error information.
+  </Accordion>
+</AccordionGroup>
@@ -1,19 +1,104 @@
 ---
 title: "Windsurf"
-description: "Open your project in Windsurf from ADE and track the session."
+description: "Launch Windsurf from ADE to edit code in a lane's worktree with session tracking and environment inheritance."
 icon: "water"
 ---
 
 ## Overview
 
-ADE can launch [Windsurf](https://codeium.com/windsurf) for your project directly from the Run tab. When launched through ADE, the session is tracked as a managed session in the lane for visibility in the History view.
+ADE can launch [Windsurf](https://codeium.com/windsurf) (by Codeium) as an external editor for any lane. When you open Windsurf through ADE, the session is tracked in the lane's history, the correct worktree directory is opened, and any file changes you make in Windsurf appear in the lane's diff view as soon as they are saved.
+
+This is a one-way integration — ADE launches Windsurf and tracks the session, but does not route AI agent requests through Windsurf or manage Windsurf's internal AI features. You use Windsurf's built-in AI capabilities directly within the Windsurf editor.
+
+---
 
 ## Requirements
 
-- Windsurf installed on your machine
+| Requirement | Details |
+|------------|---------|
+| **Windsurf installed** | The Windsurf desktop app must be installed on your machine |
+| **CLI available** | The `windsurf` command must be available in your PATH. Windsurf typically adds this during installation. Verify with `which windsurf` in a terminal. |
+
+---
 
 ## Launching Windsurf from ADE
 
-Open the **Run** tab or **Project Home** and click the **Windsurf** launcher (if configured). ADE opens the current project (or the selected lane's worktree) in Windsurf as a separate application window.
+<Steps>
+  <Step title="Select a lane">
+    Navigate to the lane you want to work in. Windsurf will open the lane's worktree directory — not the primary checkout.
+  </Step>
+  <Step title="Open the Run tab or Project Home">
+    Click the **Run** tab in the lane's toolbar, or open **Project Home** from the sidebar.
+  </Step>
+  <Step title="Click the Windsurf launcher">
+    If Windsurf is detected or configured, a **Windsurf** button appears alongside other external tool launchers (Cursor, VS Code, Claude Code, etc.). Click it.
+  </Step>
+  <Step title="Windsurf opens">
+    ADE launches Windsurf pointed at the lane's worktree path. The session is registered in ADE's history system.
+  </Step>
+</Steps>
+
+---
+
+## What ADE Tracks
+
+When you launch Windsurf through ADE:
+
+- **Session registration** — the launch is recorded as a managed session in the lane, visible in the History view
+- **File change detection** — ADE watches the lane's worktree for filesystem changes. Edits made in Windsurf appear in the lane's diff view in real time.
+- **Environment inheritance** — Windsurf inherits the lane's environment variable overlays and port assignments
+
+ADE does not monitor Windsurf's internal AI usage, chat history, or token consumption. Those are managed entirely within Windsurf.
+
+---
+
+## Configuring a Custom Launcher
+
+If Windsurf does not appear in the Run tab by default, you can add it as a custom CLI launcher:
+
+<Steps>
+  <Step title="Open Settings">
+    Navigate to **Settings > Project Home > Custom CLI Launchers**.
+  </Step>
+  <Step title="Add a new launcher">
+    Click **Add Launcher** and configure:
+    - **Name:** `Windsurf`
+    - **Command:** `windsurf` (or the full path to the Windsurf executable if it is not in PATH)
+    - **Arguments:** `{worktreePath}` — ADE substitutes the lane's worktree directory at launch time
+  </Step>
+  <Step title="Save and verify">
+    Save the launcher. It now appears in the Run tab for all lanes.
+  </Step>
+</Steps>
+
+---
+
+## Windsurf vs. Cursor vs. Claude Code
+
+ADE supports multiple external AI tools. Here is how Windsurf compares:
+
+| Capability | Windsurf | Cursor | Claude Code |
+|-----------|----------|--------|-------------|
+| **Launch from ADE** | Yes | Yes | Yes |
+| **Session tracking** | Yes | Yes | Yes |
+| **Agent provider in ADE chat** | No | Yes (via ACP) | Yes (via CLI) |
+| **MCP tool bridging** | No | Yes | Yes |
+| **Model routing through ADE** | No | Yes | Yes |
+
+Windsurf is a good choice when you want to use Codeium's AI features directly in the editor while keeping the session tracked in ADE. For deeper integration where ADE manages the AI agent lifecycle, use Cursor (via ACP) or Claude Code (via CLI).
+
+---
+
+## Troubleshooting
 
-Configure custom CLI launchers in **Settings > Project Home > Custom CLI Launchers** if Windsurf does not appear by default.
+<AccordionGroup>
+  <Accordion title="Windsurf launcher does not appear" icon="circle-question">
+    ADE may not detect Windsurf automatically. Add it as a custom CLI launcher in **Settings > Project Home > Custom CLI Launchers** using the `windsurf` command.
+  </Accordion>
+  <Accordion title="Windsurf opens the wrong directory" icon="folder">
+    Verify you selected the correct lane before launching. If Windsurf opens the primary checkout instead of the lane worktree, check that the lane was created as a Worktree Lane (not the primary lane).
+  </Accordion>
+  <Accordion title="File changes not appearing in ADE" icon="file">
+    ADE watches the lane's worktree for filesystem changes. If changes are not appearing, check that you are editing files inside the lane's worktree path (visible in the lane detail header), not in a different directory.
+  </Accordion>
+</AccordionGroup>
@@ -56,6 +56,7 @@
     "@radix-ui/react-tabs": "^1.1.13",
     "@tanstack/react-virtual": "^3.13.21",
     "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-webgl": "^0.19.0",
     "@xterm/xterm": "^6.0.0",
     "@xyflow/react": "^12.5.0",
     "ai": "^6.0.141",

@@ -226,6 +226,23 @@ async function validatePackagedRuntime(appPath, description) {
   if (!payload?.proxyProbe?.ok) {
     throw new Error("[release:mac] Packaged smoke failed to launch the bundled ADE MCP proxy in probe mode");
   }
+  // Do not rely on probe mode alone here. The regression we fixed still let
+  // the packaged proxy start, but chat MCP failed once Claude/Codex attempted
+  // the first initialize handshake through that launch path.
+  if (!payload?.proxyInitialize?.ok) {
+    throw new Error(
+      `[release:mac] Packaged smoke failed to complete MCP initialize through the bundled ADE proxy: ${
+        String(payload?.proxyInitialize?.error || payload?.proxyInitialize?.stderr || "unknown error")
+      }`
+    );
+  }
+  if (payload?.proxyInitialize?.response?.result?.serverInfo?.name !== "ade-mcp-server") {
+    throw new Error(
+      `[release:mac] Packaged smoke expected ADE MCP initialize to report ade-mcp-server, got ${
+        JSON.stringify(payload?.proxyInitialize?.response ?? null)
+      }`
+    );
+  }
 
   console.log(`[release:mac] Packaged runtime smoke passed for ${description}: ${path.relative(appPath, nodePtyAddon)}`);
 }

@@ -45,13 +45,37 @@ function resolveRuntimeRoots(): RuntimeRoots {
   return { projectRoot, workspaceRoot };
 }
 
+function asBoolFlag(value: string | undefined): boolean | null {
+  const trimmed = value?.trim() ?? "";
+  return trimmed === "1" ? true : trimmed === "0" ? false : null;
+}
+
 function resolveProxyIdentityFromEnv(): ProxyIdentity {
+  const computerUseMode = asTrimmed(process.env.ADE_COMPUTER_USE_MODE);
+  const allowLocalFallback = asBoolFlag(process.env.ADE_COMPUTER_USE_ALLOW_LOCAL_FALLBACK);
+  const retainArtifacts = asBoolFlag(process.env.ADE_COMPUTER_USE_RETAIN_ARTIFACTS);
+  const preferredBackend = asTrimmed(process.env.ADE_COMPUTER_USE_PREFERRED_BACKEND);
+  const hasComputerUsePolicy =
+    computerUseMode
+    || typeof allowLocalFallback === "boolean"
+    || typeof retainArtifacts === "boolean"
+    || preferredBackend;
   return {
+    chatSessionId: asTrimmed(process.env.ADE_CHAT_SESSION_ID),
     missionId: asTrimmed(process.env.ADE_MISSION_ID),
     runId: asTrimmed(process.env.ADE_RUN_ID),
     stepId: asTrimmed(process.env.ADE_STEP_ID),
     attemptId: asTrimmed(process.env.ADE_ATTEMPT_ID),
+    ownerId: asTrimmed(process.env.ADE_OWNER_ID),
     role: asTrimmed(process.env.ADE_DEFAULT_ROLE),
+    computerUsePolicy: hasComputerUsePolicy
+      ? {
+          mode: computerUseMode,
+          allowLocalFallback,
+          retainArtifacts,
+          preferredBackend,
+        }
+      : null,
   };
 }