| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 19 | 10 | 0% |
| Commands | 0 | 3 | 5 | 0% |
| Section tags | 3 | 2 | 2 | 43% |
What each file covers
Sections
0 shared · 19 only in A · 10 only in B- − Debug Harness
- − Quick start
- − Build extension first if needed (protos + esbuild):
- − Launch (skip-build if already built). Run with node, NOT bun — Playwright's
- − Electron launch times out under bun:
- − In another terminal:
- − Data Isolation
- − Browser Capture & OAuth
- − OAuth API
- − OAuth testing flow
- − Navigating Views — Use Commands, Not Clicks
- − Key commands
- − Typical Session
- − 1. Launch
- − 2. Open sidebar + dismiss overlays (ALWAYS do this first)
- − 3. Navigate to view
- − 4. Check captured OAuth URLs if testing auth
- − 5. Verify
- − Caveats
- + Copilot Instructions for Cline
- + Architecture
- + Build & Test (Critical — non-obvious commands)
- + Protobuf RPC Workflow (4 steps)
- + Adding API Providers (silent failure risk)
- + Adding Tools to System Prompt (5+ file chain)
- + Modifying System Prompt
- + Global State Keys (silent failure risk)
- + Slash Commands (3 places)
- + Conventions
Commands
0 shared · 3 only in A · 5 only in B- − bun run protos && IS_DEV=true bun esbuild.mjs
- − node src/dev/debug-harness/server.ts --skip-build --auto-launch
- − bun run dev:mcp-oauth-test-server
- + bun run compile
- + bun run build
- + bun run watch
- + bun run protos
- + bun run test:unit
Section tags
3 shared · 2 only in A · 2 only in B- − testing-strategy
- − security
- + code-style
- + agent-behaviour
- build
- test
- api
Line diff
cline/cline · .clinerules/debug-harness.md
@@ −1 @@
1# Debug Harness
2
3HTTP-controlled debugger for the VSCode extension at `src/dev/debug-harness/server.ts`.
4
5## Quick start
6
7```bash
8# Build extension first if needed (protos + esbuild):
9bun run protos && IS_DEV=true bun esbuild.mjs
10
11# Launch (skip-build if already built). Run with node, NOT bun — Playwright's
12# Electron launch times out under bun:
13node src/dev/debug-harness/server.ts --skip-build --auto-launch
14
15# In another terminal:
16curl localhost:19229/api -d '{"method":"status"}'
17```
18
19## Data Isolation
20
21The debugee runs with `CLINE_DIR=~/.cline2` by default, separate from your real `~/.cline`.
22This prevents the debugee's logout from logging out the debugger, and vice versa.
23Override with `--cline-dir /tmp/test-dir`. Check with `status()` → `clineDir`.
24
25## Browser Capture & OAuth
26
27The debugee runs with `CLINE_CAPTURE_BROWSER=1`, which intercepts `openExternal()` in
28`src/utils/env.ts`. URLs are captured instead of opening a real browser:
29
30- Logged to `$CLINE_DIR/data/debug-captured-urls.jsonl`
31- POSTed in real-time to `/captured-url` on the harness server
32- Queryable via `oauth.captured_urls`
33
34### OAuth API
35
36- **`oauth.captured_urls`** `{clear?}` — URLs the debugee tried to open
37- **`oauth.read_stored_token`** — Check auth token presence in secrets.json
38- **`oauth.simulate_callback`** `{path, code?, state?, provider?, token?}` — Build vscode:// callback URI
39- **`oauth.read_captured_urls_file`** — Read on-disk JSONL of captured URLs
40
41### OAuth testing flow
42
43For **Cline OAuth** (SDK local callback): The SDK starts a local HTTP server, the auth URL
44is captured. To complete: open the captured URL in a real browser (it redirects back to the
45SDK's callback server), OR extract the callback port and `curl http://127.0.0.1:PORT/callback?code=...`.
46
47For **MCP/Provider OAuth** (vscode:// URI): The redirect goes to a vscode:// URI.
48`oauth.simulate_callback` only *builds* the URI — it does not deliver it, and the ESM
49extension host can't `require()` the handler. To actually deliver the callback, call the
50debug-only hook via `ext.evaluate` (with `awaitPromise: true`):
51`globalThis.__clineHandleUri("vscode://saoudrizwan.claude-dev/...?code=...&state=...")`.
52It runs the same `SharedUriHandler.handleUri` as VSCode's real URI handler and exists only
53when `CLINE_CAPTURE_BROWSER` is set (the harness always sets it; never ships in prod).
54For end-to-end MCP OAuth, get a real `code` from the local MCP OAuth test server
55(`bun run dev:mcp-oauth-test-server`).
56
57## Navigating Views — Use Commands, Not Clicks
58
59Don't try to find/click small sidebar icons. Use VSCode commands via command palette.
60Registered in `src/registry.ts`:
61
62| Command | View |
63|---------|------|
64| `cline.accountButtonClicked` | Account / sign-in |
65| `cline.historyButtonClicked` | Task history |
66| `cline.settingsButtonClicked` | Settings |
67| `cline.mcpButtonClicked` | MCP servers |
68| `cline.plusButtonClicked` | New task (chat) |
69| `cline.worktreesButtonClicked` | Worktrees |
70
71```bash
72curl localhost:19229/api -d '{"method":"ui.command_palette","params":{"command":"cline.accountButtonClicked"}}'
73```
74
75## Key commands
76
77All via `POST localhost:19229/api` with `{"method":"...", "params":{...}}`:
78
79- **`launch`** / **`shutdown`** — lifecycle
80- **`ui.screenshot`** — screenshot to `/tmp/cline-debug/`; returns `{path}` — **use `read_file` on the path to examine, do NOT `open` the file** (Preview.app covers the VSCode window)
81- **`ui.open_sidebar`** — open the Cline sidebar
82- **`ext.set_breakpoint`** `{file, line, condition?}` — breakpoint by source file (sourcemap-resolved)
83- **`ext.evaluate`** `{expression, callFrameId?}` — eval in extension host
84- **`ext.resume`** / **`ext.step_over`** / **`ext.step_into`** — stepping
85- **`ext.call_stack`** — inspect when paused
86- **`web.evaluate`** `{expression}` — eval in webview
87- **`web.post_message`** `{message}` — send postMessage to extension host via exposed vsCodeApi
88- **`wait_for_pause`** `{timeout?}` — block until breakpoint hit
89- **`ui.locator`** `{role?, testId?, text?, frame?}` — Playwright locator (auto-retries on stale sidebar frame)
90- **`ui.react_input`** `{text, selector?, clear?, submit?}` — set React textarea value via `execCommand('insertText')`; works reliably across multiple tasks
91- **`ui.send_message`** `{text, images?, files?, responseType?}` — send chat message bypassing the textarea entirely (via gRPC postMessage)
92- **`ui.command_palette`** `{command}` — run VSCode command
93
94## Typical Session
95
96```bash
97# 1. Launch
98curl localhost:19229/api -d '{"method":"launch","params":{"skipBuild":true}}'
99
100# 2. Open sidebar + dismiss overlays (ALWAYS do this first)
101curl localhost:19229/api -d '{"method":"ui.open_sidebar"}'
102curl localhost:19229/api -d '{"method":"web.evaluate","params":{"expression":"document.querySelectorAll(\".sr-only\").forEach(el => el.parentElement?.click())"}}'
103
104# 3. Navigate to view
105curl localhost:19229/api -d '{"method":"ui.command_palette","params":{"command":"cline.accountButtonClicked"}}'
106
107# 4. Check captured OAuth URLs if testing auth
108curl localhost:19229/api -d '{"method":"oauth.captured_urls"}'
109
110# 5. Verify
111curl localhost:19229/api -d '{"method":"ui.screenshot"}'
112```
113
114## Caveats
115
116- **⚠️ Dismiss promotional overlays FIRST**: On fresh launches, full-screen promo overlays block the sidebar. **Dismiss immediately after `ui.open_sidebar`**, before any other interaction or screenshot. May need to run twice:
117 ```bash
118 curl localhost:19229/api -d '{"method": "ui.open_sidebar"}'
119 curl localhost:19229/api -d '{"method": "web.evaluate", "params": {"expression": "document.querySelectorAll(\".sr-only\").forEach(el => el.parentElement?.click())"}}'
120 ```
121- **Screenshots — don't open the file**: `ui.screenshot` and `ui.sidebar_screenshot` save PNGs to `/tmp/cline-debug/` and return the `{path}`. Use `read_file` on that path to examine screenshots. Running `open <path>` launches Preview.app on macOS which covers the VSCode window.
122- **Scripts count = 0 after launch**: CDP connects after extension host starts, so scripts parsed during startup aren't tracked. Breakpoints still work via sourcemap resolution.
123- **Port 9230**: Extension host inspector. If another VSCode instance uses this port, the harness will fail to connect. Kill other debug instances first.
124- **macOS only** for now (Playwright Electron launch behavior).
125- **Webview CDP**: `connect_webview` may fail depending on Electron version. `web.evaluate` still works via Playwright's `frame.evaluate()` fallback.
126- **Sourcemap paths**: esbuild outputs relative paths like `../src/extension.ts` in the sourcemap. The resolver handles this, but if a file isn't found, use `ext.source_files` to see exact paths.
127- **OAuth with fake codes**: Browser capture intercepts the URL but doesn't provide a valid auth code. For real OAuth testing, open the captured URL in a browser. For unit testing, mock the token exchange.
128
129See `src/dev/debug-harness/README.md` for full API reference.
130
cline/cline · .github/copilot-instructions.md
@@ +1 @@
1# Copilot Instructions for Cline
2
3This is a VS Code extension. Read `.clinerules/general.md` for tribal knowledge and nuanced patterns.
4
5## Architecture
6- **Core** (`src/`): `extension.ts` → `WebviewProvider` → `Controller` (single source of truth) → `Task` (agent loop).
7- **Webview** (`webview-ui/`): React/Vite app. State via `ExtensionStateContext.tsx`, synced through message passing.
8- **Communication**: Protobuf-defined gRPC-like protocol over VS Code message passing. Schemas in `proto/`.
9- **MCP**: `src/services/mcp/McpHub.ts`.
10
11## Build & Test (Critical — non-obvious commands)
12- **Build**: `bun run compile` — NOT `bun run build`.
13- **Watch**: `bun run watch` (extension + webview).
14- **Protos**: `bun run protos` — run **immediately** after any `.proto` change. Generates into `src/shared/proto/`, `src/generated/`.
15- **Tests**: `bun run test:unit`. After prompt/tool changes: `UPDATE_SNAPSHOTS=true bun run test:unit`.
16
17## Protobuf RPC Workflow (4 steps)
181. **Define** in `proto/cline/*.proto`. Naming: `PascalCaseService`, `camelCase` RPCs, `PascalCase` Messages. Use `common.proto` shared types for simple data.
192. **Generate**: `bun run protos`.
203. **Backend handler**: `src/core/controller/<domain>/`.
214. **Frontend call**: `UiServiceClient.myMethod(Request.create({...}))`.
22- Adding enums (e.g. `ClineSay`) → also update `src/shared/proto-conversions/cline-message.ts`.
23
24## Adding API Providers (silent failure risk)
25Three proto conversion updates are **required** or the provider silently resets to Anthropic:
261. `proto/cline/models.proto` — add to `ApiProvider` enum.
272. `convertApiProviderToProto()` in `src/shared/proto-conversions/models/api-configuration-conversion.ts`.
283. `convertProtoToApiProvider()` in the same file.
29
30Also update: `src/shared/api.ts`, `src/shared/providers/providers.json`, `src/core/api/index.ts`, `webview-ui/.../providerUtils.ts`, `webview-ui/.../validate.ts`, `webview-ui/.../ApiOptions.tsx`.
31
32For Responses API providers: add to `isNextGenModelProvider()` in `src/utils/model-utils.ts` and set `apiFormat: ApiFormat.OPENAI_RESPONSES` on models.
33
34## Adding Tools to System Prompt (5+ file chain)
351. Add enum to `ClineDefaultTool` in `src/shared/tools.ts`.
362. Create definition in `src/core/prompts/system-prompt/tools/` (export `[GENERIC]` minimum).
373. Register in `src/core/prompts/system-prompt/tools/init.ts`.
384. Whitelist in `src/core/prompts/system-prompt/variants/*/config.ts` for each model family.
395. Handler in `src/core/task/tools/handlers/`, wire in `ToolExecutor.ts`.
406. If tool has UI: add `ClineSay` enum in proto → `ExtensionMessage.ts` → `cline-message.ts` → `ChatRow.tsx`.
417. Regenerate snapshots: `UPDATE_SNAPSHOTS=true bun run test:unit`.
42
43## Modifying System Prompt
44Modular: `components/` (shared) + `variants/` (model-specific) + `templates/` (`{{PLACEHOLDER}}`). Variants override components via `componentOverrides` in `config.ts` or custom `template.ts`. XS variant is heavily condensed inline. Always regenerate snapshots after changes.
45
46## Global State Keys (silent failure risk)
47Adding a key requires updating the typed storage definitions in `src/shared/storage/state-keys.ts`; runtime reads and writes should go through `StateManager`, not VS Code `ExtensionContext` storage. Persistent state is file-backed so it works across VS Code, CLI, and JetBrains hosts.
48
49## Slash Commands (3 places)
50- `src/core/slash-commands/index.ts` — definitions.
51- `src/core/prompts/commands.ts` — system prompt integration.
52- `webview-ui/src/utils/slash-commands.ts` — webview autocomplete.
53
54## Conventions
55- **Paths**: Always use `src/utils/path` helpers (`toPosixString`) for cross-platform compatibility.
56- **Logging**: `src/shared/services/Logger.ts`.
57- **Feature flags**: See PR #7566 as reference pattern.
58
@@ −1 +1 @@
1−# Debug Harness
1+# Copilot Instructions for Cline
22
3−HTTP-controlled debugger for the VSCode extension at `src/dev/debug-harness/server.ts`.
3+This is a VS Code extension. Read `.clinerules/general.md` for tribal knowledge and nuanced patterns.
44
5−## Quick start
5+## Architecture
6+- **Core** (`src/`): `extension.ts` → `WebviewProvider` → `Controller` (single source of truth) → `Task` (agent loop).
7+- **Webview** (`webview-ui/`): React/Vite app. State via `ExtensionStateContext.tsx`, synced through message passing.
8+- **Communication**: Protobuf-defined gRPC-like protocol over VS Code message passing. Schemas in `proto/`.
9+- **MCP**: `src/services/mcp/McpHub.ts`.
610
7−```bash
8−# Build extension first if needed (protos + esbuild):
9−bun run protos && IS_DEV=true bun esbuild.mjs
11+## Build & Test (Critical — non-obvious commands)
12+- **Build**: `bun run compile` — NOT `bun run build`.
13+- **Watch**: `bun run watch` (extension + webview).
14+- **Protos**: `bun run protos` — run **immediately** after any `.proto` change. Generates into `src/shared/proto/`, `src/generated/`.
15+- **Tests**: `bun run test:unit`. After prompt/tool changes: `UPDATE_SNAPSHOTS=true bun run test:unit`.
1016
11−# Launch (skip-build if already built). Run with node, NOT bun — Playwright's
12−# Electron launch times out under bun:
13−node src/dev/debug-harness/server.ts --skip-build --auto-launch
17+## Protobuf RPC Workflow (4 steps)
18+1. **Define** in `proto/cline/*.proto`. Naming: `PascalCaseService`, `camelCase` RPCs, `PascalCase` Messages. Use `common.proto` shared types for simple data.
19+2. **Generate**: `bun run protos`.
20+3. **Backend handler**: `src/core/controller/<domain>/`.
21+4. **Frontend call**: `UiServiceClient.myMethod(Request.create({...}))`.
22+- Adding enums (e.g. `ClineSay`) → also update `src/shared/proto-conversions/cline-message.ts`.
1423
15−# In another terminal:
16−curl localhost:19229/api -d '{"method":"status"}'
17−```
24+## Adding API Providers (silent failure risk)
25+Three proto conversion updates are **required** or the provider silently resets to Anthropic:
26+1. `proto/cline/models.proto` — add to `ApiProvider` enum.
27+2. `convertApiProviderToProto()` in `src/shared/proto-conversions/models/api-configuration-conversion.ts`.
28+3. `convertProtoToApiProvider()` in the same file.
1829
19−## Data Isolation
30+Also update: `src/shared/api.ts`, `src/shared/providers/providers.json`, `src/core/api/index.ts`, `webview-ui/.../providerUtils.ts`, `webview-ui/.../validate.ts`, `webview-ui/.../ApiOptions.tsx`.
2031
21−The debugee runs with `CLINE_DIR=~/.cline2` by default, separate from your real `~/.cline`.
22−This prevents the debugee's logout from logging out the debugger, and vice versa.
23−Override with `--cline-dir /tmp/test-dir`. Check with `status()` → `clineDir`.
32+For Responses API providers: add to `isNextGenModelProvider()` in `src/utils/model-utils.ts` and set `apiFormat: ApiFormat.OPENAI_RESPONSES` on models.
2433
25−## Browser Capture & OAuth
34+## Adding Tools to System Prompt (5+ file chain)
35+1. Add enum to `ClineDefaultTool` in `src/shared/tools.ts`.
36+2. Create definition in `src/core/prompts/system-prompt/tools/` (export `[GENERIC]` minimum).
37+3. Register in `src/core/prompts/system-prompt/tools/init.ts`.
38+4. Whitelist in `src/core/prompts/system-prompt/variants/*/config.ts` for each model family.
39+5. Handler in `src/core/task/tools/handlers/`, wire in `ToolExecutor.ts`.
40+6. If tool has UI: add `ClineSay` enum in proto → `ExtensionMessage.ts` → `cline-message.ts` → `ChatRow.tsx`.
41+7. Regenerate snapshots: `UPDATE_SNAPSHOTS=true bun run test:unit`.
2642
27−The debugee runs with `CLINE_CAPTURE_BROWSER=1`, which intercepts `openExternal()` in
28−`src/utils/env.ts`. URLs are captured instead of opening a real browser:
43+## Modifying System Prompt
44+Modular: `components/` (shared) + `variants/` (model-specific) + `templates/` (`{{PLACEHOLDER}}`). Variants override components via `componentOverrides` in `config.ts` or custom `template.ts`. XS variant is heavily condensed inline. Always regenerate snapshots after changes.
2945
30−- Logged to `$CLINE_DIR/data/debug-captured-urls.jsonl`
31−- POSTed in real-time to `/captured-url` on the harness server
32−- Queryable via `oauth.captured_urls`
46+## Global State Keys (silent failure risk)
47+Adding a key requires updating the typed storage definitions in `src/shared/storage/state-keys.ts`; runtime reads and writes should go through `StateManager`, not VS Code `ExtensionContext` storage. Persistent state is file-backed so it works across VS Code, CLI, and JetBrains hosts.
3348
34−### OAuth API
49+## Slash Commands (3 places)
50+- `src/core/slash-commands/index.ts` — definitions.
51+- `src/core/prompts/commands.ts` — system prompt integration.
52+- `webview-ui/src/utils/slash-commands.ts` — webview autocomplete.
3553
36−- **`oauth.captured_urls`** `{clear?}` — URLs the debugee tried to open
37−- **`oauth.read_stored_token`** — Check auth token presence in secrets.json
38−- **`oauth.simulate_callback`** `{path, code?, state?, provider?, token?}` — Build vscode:// callback URI
39−- **`oauth.read_captured_urls_file`** — Read on-disk JSONL of captured URLs
40−
41−### OAuth testing flow
42−
43−For **Cline OAuth** (SDK local callback): The SDK starts a local HTTP server, the auth URL
44−is captured. To complete: open the captured URL in a real browser (it redirects back to the
45−SDK's callback server), OR extract the callback port and `curl http://127.0.0.1:PORT/callback?code=...`.
46−
47−For **MCP/Provider OAuth** (vscode:// URI): The redirect goes to a vscode:// URI.
48−`oauth.simulate_callback` only *builds* the URI — it does not deliver it, and the ESM
49−extension host can't `require()` the handler. To actually deliver the callback, call the
50−debug-only hook via `ext.evaluate` (with `awaitPromise: true`):
51−`globalThis.__clineHandleUri("vscode://saoudrizwan.claude-dev/...?code=...&state=...")`.
52−It runs the same `SharedUriHandler.handleUri` as VSCode's real URI handler and exists only
53−when `CLINE_CAPTURE_BROWSER` is set (the harness always sets it; never ships in prod).
54−For end-to-end MCP OAuth, get a real `code` from the local MCP OAuth test server
55−(`bun run dev:mcp-oauth-test-server`).
56−
57−## Navigating Views — Use Commands, Not Clicks
58−
59−Don't try to find/click small sidebar icons. Use VSCode commands via command palette.
60−Registered in `src/registry.ts`:
61−
62−| Command | View |
63−|---------|------|
64−| `cline.accountButtonClicked` | Account / sign-in |
65−| `cline.historyButtonClicked` | Task history |
66−| `cline.settingsButtonClicked` | Settings |
67−| `cline.mcpButtonClicked` | MCP servers |
68−| `cline.plusButtonClicked` | New task (chat) |
69−| `cline.worktreesButtonClicked` | Worktrees |
70−
71−```bash
72−curl localhost:19229/api -d '{"method":"ui.command_palette","params":{"command":"cline.accountButtonClicked"}}'
73−```
74−
75−## Key commands
76−
77−All via `POST localhost:19229/api` with `{"method":"...", "params":{...}}`:
78−
79−- **`launch`** / **`shutdown`** — lifecycle
80−- **`ui.screenshot`** — screenshot to `/tmp/cline-debug/`; returns `{path}` — **use `read_file` on the path to examine, do NOT `open` the file** (Preview.app covers the VSCode window)
81−- **`ui.open_sidebar`** — open the Cline sidebar
82−- **`ext.set_breakpoint`** `{file, line, condition?}` — breakpoint by source file (sourcemap-resolved)
83−- **`ext.evaluate`** `{expression, callFrameId?}` — eval in extension host
84−- **`ext.resume`** / **`ext.step_over`** / **`ext.step_into`** — stepping
85−- **`ext.call_stack`** — inspect when paused
86−- **`web.evaluate`** `{expression}` — eval in webview
87−- **`web.post_message`** `{message}` — send postMessage to extension host via exposed vsCodeApi
88−- **`wait_for_pause`** `{timeout?}` — block until breakpoint hit
89−- **`ui.locator`** `{role?, testId?, text?, frame?}` — Playwright locator (auto-retries on stale sidebar frame)
90−- **`ui.react_input`** `{text, selector?, clear?, submit?}` — set React textarea value via `execCommand('insertText')`; works reliably across multiple tasks
91−- **`ui.send_message`** `{text, images?, files?, responseType?}` — send chat message bypassing the textarea entirely (via gRPC postMessage)
92−- **`ui.command_palette`** `{command}` — run VSCode command
93−
94−## Typical Session
95−
96−```bash
97−# 1. Launch
98−curl localhost:19229/api -d '{"method":"launch","params":{"skipBuild":true}}'
99−
100−# 2. Open sidebar + dismiss overlays (ALWAYS do this first)
101−curl localhost:19229/api -d '{"method":"ui.open_sidebar"}'
102−curl localhost:19229/api -d '{"method":"web.evaluate","params":{"expression":"document.querySelectorAll(\".sr-only\").forEach(el => el.parentElement?.click())"}}'
103−
104−# 3. Navigate to view
105−curl localhost:19229/api -d '{"method":"ui.command_palette","params":{"command":"cline.accountButtonClicked"}}'
106−
107−# 4. Check captured OAuth URLs if testing auth
108−curl localhost:19229/api -d '{"method":"oauth.captured_urls"}'
109−
110−# 5. Verify
111−curl localhost:19229/api -d '{"method":"ui.screenshot"}'
112−```
113−
114−## Caveats
115−
116−- **⚠️ Dismiss promotional overlays FIRST**: On fresh launches, full-screen promo overlays block the sidebar. **Dismiss immediately after `ui.open_sidebar`**, before any other interaction or screenshot. May need to run twice:
117− ```bash
118− curl localhost:19229/api -d '{"method": "ui.open_sidebar"}'
119− curl localhost:19229/api -d '{"method": "web.evaluate", "params": {"expression": "document.querySelectorAll(\".sr-only\").forEach(el => el.parentElement?.click())"}}'
120− ```
121−- **Screenshots — don't open the file**: `ui.screenshot` and `ui.sidebar_screenshot` save PNGs to `/tmp/cline-debug/` and return the `{path}`. Use `read_file` on that path to examine screenshots. Running `open <path>` launches Preview.app on macOS which covers the VSCode window.
122−- **Scripts count = 0 after launch**: CDP connects after extension host starts, so scripts parsed during startup aren't tracked. Breakpoints still work via sourcemap resolution.
123−- **Port 9230**: Extension host inspector. If another VSCode instance uses this port, the harness will fail to connect. Kill other debug instances first.
124−- **macOS only** for now (Playwright Electron launch behavior).
125−- **Webview CDP**: `connect_webview` may fail depending on Electron version. `web.evaluate` still works via Playwright's `frame.evaluate()` fallback.
126−- **Sourcemap paths**: esbuild outputs relative paths like `../src/extension.ts` in the sourcemap. The resolver handles this, but if a file isn't found, use `ext.source_files` to see exact paths.
127−- **OAuth with fake codes**: Browser capture intercepts the URL but doesn't provide a valid auth code. For real OAuth testing, open the captured URL in a browser. For unit testing, mock the token exchange.
128−
129−See `src/dev/debug-harness/README.md` for full API reference.
54+## Conventions
55+- **Paths**: Always use `src/utils/path` helpers (`toPosixString`) for cross-platform compatibility.
56+- **Logging**: `src/shared/services/Logger.ts`.
57+- **Feature flags**: See PR #7566 as reference pattern.
13058
