[issues/552] Claude Code cold-start re-focus loop

packages/rangelink-vscode-extension/CHANGELOG.md

@@ -116,6 +116,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Forgiving filename navigation** - Links with bare filenames (no directory path) now navigate when exactly one matching file exists in the workspace (#342)
   - Covers links generated by AI tools that omit directory prefixes (e.g., `RangeLinkNavigationHandler.ts#L10`)
   - When the filename is ambiguous (multiple matches) or not found, the existing "Cannot find file" warning is shown
+- **Claude Code cold-start re-focus loop** - Adds configurable `coldStartDelayMs` and `coldRefocusIntervalMs` settings under `rangelink.destinations.claudeCode.*` to ensure the chat panel is ready before the first paste dispatch after binding.
 
 <!-- TODO: #366 unhide when bookmarks graduate from beta — re-add these entries to the sections above
 - R-M menu: add "List Bookmarks / Manage Bookmarks" bullet
@@ -124,10 +125,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Save Selection as Bookmark (R-B-S)** - `Cmd+R Cmd+B Cmd+S` (Mac) / `Ctrl+R Ctrl+B Ctrl+S` (Win/Linux)
     - Save current selection as a reusable bookmark with custom label
     - Also available via Command Palette and editor context menu (right-click)
-  - **List Bookmarks (R-B-L)** - `Cmd+R Cmd+B Cmd+L` (Mac) / `Ctrl+R Ctrl+B Ctrl+L` (Win/Linux)
-    - Select a bookmark to paste its link to bound destination (or clipboard if unbound)
-    - Manage bookmarks via the gear icon action in the bookmark list
--->
+  - **List Bookmarks (R-B-L)** - `Cmd+R Cmd+B Cmd+L` (Mac) / `Ctrl+R Ctrl+B Ctrl+L` (Win/Linux) - Select a bookmark to paste its link to bound destination (or clipboard if unbound) - Manage bookmarks via the gear icon action in the bookmark list
+    -->
 
 ### Changed
 

packages/rangelink-vscode-extension/README.md

@@ -491,6 +491,13 @@ Set the navigation settings to `false` for a quieter workflow. Navigation itself
 
 When you have more terminals than this threshold, the destination picker shows a "More terminals..." option instead of listing all terminals individually.
 
+### Claude Code Settings <sup>Unreleased</sup>
+
+| Setting                                                   | Default | Description                                                                          |
+| --------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
+| `rangelink.destinations.claudeCode.coldStartDelayMs`      | `1500`  | Total duration (ms) of the cold-start re-focus window for Claude Code                |
+| `rangelink.destinations.claudeCode.coldRefocusIntervalMs` | `300`   | Interval (ms) between successive focus-command re-sends during the cold-start window |
+
 ### Delimiter Settings
 
 | Setting                       | Default | Description                         |

packages/rangelink-vscode-extension/package.json

@@ -532,6 +532,22 @@
           "description": "Delimiter used between start and end positions (e.g., - in #L10-L20)",
           "pattern": "^[^0-9]+$"
         },
+        "rangelink.destinations.claudeCode.coldStartDelayMs": {
+          "type": "number",
+          "default": 1500,
+          "minimum": 500,
+          "maximum": 15000,
+          "description": "Total duration (ms) of the cold-start re-focus window for Claude Code. During this window, focus commands are re-sent at the coldRefocusIntervalMs cadence to ensure the chat panel is ready before paste dispatch.",
+          "title": "Claude Code Cold Start Delay"
+        },
+        "rangelink.destinations.claudeCode.coldRefocusIntervalMs": {
+          "type": "number",
+          "default": 300,
+          "minimum": 100,
+          "maximum": 5000,
+          "description": "Interval (ms) between successive focus-command re-sends during the Claude Code cold-start window.",
+          "title": "Claude Code Cold Re-focus Interval"
+        },
         "rangelink.features.bookmarks.enabled": {
           "type": "boolean",
           "default": false,

packages/rangelink-vscode-extension/qa/qa-test-cases-v1.1.0.yaml

@@ -3141,6 +3141,42 @@ test_cases:
     command_to_run: 'pnpm test:release:with-extensions --grep "claude-code-005"'
     automated: assisted
 
+  - id: claude-code-006
+    labels:
+      - requires-extensions
+      - cold-start
+    feature: 'Built-in AI Assistants'
+    scenario: 'Cold-start default settings produce a valid ColdRefocusConfig where totalMs > intervalMs'
+    preconditions:
+      - 'Claude Code extension (anthropic.claude-code) is installed and active'
+      - 'VS Code is running with the standard test:release:with-extensions configuration'
+    steps:
+      - 'Read the rangelink.destinations.claudeCode.coldStartDelayMs and coldRefocusIntervalMs defaults from VS Code configuration'
+      - 'Confirm coldStartDelayMs > coldRefocusIntervalMs'
+    expected_result: 'Default settings produce a valid ColdRefocusConfig. coldStartDelayMs is greater than coldRefocusIntervalMs.'
+    command_to_run: 'pnpm test:release:with-extensions --grep "claude-code-006"'
+    automated: true
+
+  - id: claude-code-007
+    labels:
+      - requires-extensions
+      - cold-start
+      - validation
+    feature: 'Built-in AI Assistants'
+    scenario: 'Cold-start validation rejects invalid config (totalMs <= intervalMs) and falls back to defaults with a warning'
+    preconditions:
+      - 'Claude Code extension (anthropic.claude-code) is installed and active'
+      - 'VS Code is running with the standard test:release:with-extensions configuration'
+    steps:
+      - 'Set rangelink.destinations.claudeCode.coldStartDelayMs to 100 and coldRefocusIntervalMs to 400 (invalid: delay <= interval)'
+      - 'Bind to Claude Code Chat to trigger getColdRefocus validation'
+      - 'Confirm a warning log is emitted about invalid cold-start config'
+      - 'Confirm the fallback defaults from coldStartDelayMs / coldRefocusIntervalMs are used instead of the invalid values'
+      - 'Restore original configuration values'
+    expected_result: 'Invalid config is rejected. Warning is logged. Defaults from coldStartDelayMs / coldRefocusIntervalMs are used as fallback.'
+    command_to_run: 'pnpm test:release:with-extensions --grep "claude-code-007"'
+    automated: true
+
   - id: cursor-ai-003
     labels:
       - clipboard

packages/rangelink-vscode-extension/src/__integration-tests__/helpers/editorHelpers.ts

@@ -35,6 +35,22 @@ export const clearEditorSelection = async (): Promise<void> => {
   }
 };
 
+export const openUntitledDoc = async (options?: {
+  content?: string;
+  language?: string;
+  viewColumn?: vscode.ViewColumn;
+}): Promise<vscode.TextDocument> => {
+  const {
+    content = '',
+    language = 'plaintext',
+    viewColumn = vscode.ViewColumn.One,
+  } = options ?? {};
+  const doc = await vscode.workspace.openTextDocument({ content, language });
+  await vscode.window.showTextDocument(doc, viewColumn);
+  await settle();
+  return doc;
+};
+
 export const selectAll = (editor: vscode.TextEditor): void => {
   const lastLine = editor.document.lineCount - 1;
   const lastChar = editor.document.lineAt(lastLine).text.length;

packages/rangelink-vscode-extension/src/__integration-tests__/helpers/index.ts

@@ -12,7 +12,12 @@ export {
   CLIPBOARD_SENTINEL,
   writeClipboardSentinel,
 } from './clipboardHelpers';
-export { clearEditorSelection, selectAll, waitForActiveEditor } from './editorHelpers';
+export {
+  clearEditorSelection,
+  openUntitledDoc,
+  selectAll,
+  waitForActiveEditor,
+} from './editorHelpers';
 export {
   cleanupFiles,
   closeAllEditors,

packages/rangelink-vscode-extension/src/__integration-tests__/helpers/standardSuite.ts

@@ -1,4 +1,11 @@
+import assert from 'node:assert';
+
+import * as vscode from 'vscode';
+
+import { CMD_UNBIND_DESTINATION } from '../../constants/commandIds';
+
 import { closeAllEditors } from './fileHelpers';
+import { getLogCapture } from './getLogCapture';
 import { createLogger } from './logHelpers';
 import { resetRangelinkSettings } from './settingsHelpers';
 import { activateExtension, settle } from './testEnv';
@@ -12,11 +19,19 @@ export const standardSuite = (name: string, fn: (log: (msg: string) => void) =>
     });
 
     setup(async () => {
+      assert.ok(
+        getLogCapture().isCapturing,
+        'RANGELINK_CAPTURE_LOGS must be true for toast assertions',
+      );
       await resetRangelinkSettings(log);
+      await vscode.commands.executeCommand(CMD_UNBIND_DESTINATION);
+      await closeAllEditors();
       await settle();
     });
 
     suiteTeardown(async () => {
+      await vscode.commands.executeCommand(CMD_UNBIND_DESTINATION);
+      await settle();
       await closeAllEditors();
     });
 

packages/rangelink-vscode-extension/src/__integration-tests__/suite/bindToDestination.test.ts

@@ -29,12 +29,10 @@ standardSuite('R-D Bind to Destination', (log) => {
   const tmpFileUris: vscode.Uri[] = [];
 
   teardown(async () => {
-    await vscode.commands.executeCommand('rangelink.unbindDestination');
     for (const t of terminals) {
       t.dispose();
     }
     terminals.length = 0;
-    await closeAllEditors();
     cleanupFiles(tmpFileUris);
     tmpFileUris.length = 0;
     await settle();

packages/rangelink-vscode-extension/src/__integration-tests__/suite/builtInAiAssistants.test.ts

@@ -7,15 +7,12 @@ import {
   CMD_BIND_TO_CLAUDE_CODE,
   CMD_BIND_TO_DESTINATION,
   CMD_COPY_LINK_RELATIVE,
-  CMD_UNBIND_DESTINATION,
+  CMD_JUMP_TO_DESTINATION,
 } from '../../constants/commandIds';
 import { CLAUDE_CODE_EXTENSION_ID } from '../../utils/aiAssistants/isClaudeCodeAvailable';
 import {
-  activateExtension,
   assertStatusBarMsgLogged,
   cleanupFiles,
-  closeAllEditors,
-  createLogger,
   createWorkspaceFile,
   extractQuickPickItemsLogged,
   getLogCapture,
@@ -30,17 +27,10 @@ const AI_ASSISTANTS_GROUP_LABEL = 'AI Assistants';
 const CLAUDE_CODE_DISPLAY_NAME = 'Claude Code Chat';
 const CLAUDE_CODE_BIND_STATUS_BAR_MESSAGE = '✓ RangeLink bound to Claude Code Chat';
 
-suite('Built-in AI Assistants', () => {
-  const log = createLogger('builtInAiAssistants');
+standardSuite('Built-in AI Assistants', (log) => {
   const tmpFileUris: vscode.Uri[] = [];
 
-  suiteSetup(async () => {
-    await activateExtension();
-  });
-
   teardown(async () => {
-    await vscode.commands.executeCommand(CMD_UNBIND_DESTINATION);
-    await closeAllEditors();
     cleanupFiles(tmpFileUris);
     tmpFileUris.length = 0;
     await settle();
@@ -194,7 +184,10 @@ suite('Built-in AI Assistants', () => {
       'Human reported the cold-send RangeLink did not appear in Claude Code chat',
     );
 
-    // Select lines 3-4 for warm send
+    // Select lines 3-4 for warm send. Re-focus the editor first — the cold
+    // verdict dialog stole focus and the editor must be active for the send
+    // command to see the selection.
+    await vscode.window.showTextDocument(doc);
     editor.selection = new vscode.Selection(2, 0, 3, 6);
     await settle();
 
@@ -309,4 +302,65 @@ standardSuite('Built-in AI Assistants — Destination Picker', (log) => {
 
     log('✓ github-copilot-chat-001 — log confirms "GitHub Copilot Chat" appears in R-D picker');
   });
+
+  test('claude-code-006: Cold-start default settings produce correct ColdRefocusConfig', async function (this: MochaContext) {
+    const config = vscode.workspace.getConfiguration('rangelink.destinations.claudeCode');
+    const totalMs = config.get<number>('coldStartDelayMs', 1500);
+    const intervalMs = config.get<number>('coldRefocusIntervalMs', 300);
+
+    assert.strictEqual(totalMs, 1500, 'Expected default coldStartDelayMs to be 1500');
+    assert.strictEqual(intervalMs, 300, 'Expected default coldRefocusIntervalMs to be 300');
+    assert.ok(
+      totalMs > intervalMs,
+      `Expected coldStartDelayMs (${totalMs}) > coldRefocusIntervalMs (${intervalMs})`,
+    );
+
+    log('✓ Default cold-start config produces valid ColdRefocusConfig');
+  });
+
+  test('claude-code-007: Cold-start validation rejects invalid config and falls back to defaults', async function (this: MochaContext) {
+    if (!vscode.extensions.getExtension(CLAUDE_CODE_EXTENSION_ID)) {
+      log('Skipping claude-code-007 — Claude Code extension not installed in this test config');
+      this.skip();
+    }
+
+    const config = vscode.workspace.getConfiguration('rangelink.destinations.claudeCode');
+
+    // Set delay <= interval so the validation rejects it (by default, delay >
+    // interval so the config is valid; flipping that relationship makes it invalid).
+    const INVALID_DELAY_MS = 100;
+    const INVALID_INTERVAL_MS = 400;
+    await config.update('coldStartDelayMs', INVALID_DELAY_MS, vscode.ConfigurationTarget.Workspace);
+    await config.update(
+      'coldRefocusIntervalMs',
+      INVALID_INTERVAL_MS,
+      vscode.ConfigurationTarget.Workspace,
+    );
+    await settle();
+
+    const logCapture = getLogCapture();
+    logCapture.mark('before-cc-007');
+
+    // Validation lives inside getColdRefocus, which is a thunk only invoked
+    // during focus() — not at bind() time. CMD_JUMP_TO_DESTINATION triggers
+    // focusBoundDestination() → focus() → getColdRefocus() → validation warning.
+    await vscode.commands.executeCommand(CMD_BIND_TO_CLAUDE_CODE);
+    await settle();
+
+    await vscode.commands.executeCommand(CMD_JUMP_TO_DESTINATION);
+    await settle();
+
+    const lines = logCapture.getLinesSince('before-cc-007');
+    const warningLog = lines.find(
+      (line) =>
+        line.includes('coldStartDelayMs must be greater than coldRefocusIntervalMs') &&
+        line.includes('using defaults'),
+    );
+    assert.ok(
+      warningLog,
+      'Expected validation warning log with "using defaults" when coldStartDelayMs <= coldRefocusIntervalMs',
+    );
+
+    log('✓ claude-code-007 — invalid config triggers fallback to defaults');
+  });
 });

packages/rangelink-vscode-extension/src/__integration-tests__/suite/clipboardPreservation.test.ts

@@ -4,10 +4,10 @@ import * as vscode from 'vscode';
 
 import {
   CMD_BIND_TO_TEXT_EDITOR_HERE,
+  CMD_BIND_TO_TERMINAL_HERE,
   CMD_COPY_LINK_RELATIVE,
   CMD_PASTE_CURRENT_FILE_PATH_RELATIVE,
   CMD_TERMINAL_PASTE_SELECTED_TEXT,
-  CMD_UNBIND_DESTINATION,
 } from '../../constants/commandIds';
 import { VSCODE_CMD_TERMINAL_SELECT_ALL } from '../../constants/vscodeCommandIds';
 import {
@@ -16,7 +16,6 @@ import {
   assertTerminalBufferContains,
   type CapturingTerminal,
   cleanupFiles,
-  closeAllEditors,
   CLIPBOARD_SENTINEL,
   createAndBindCapturingTerminal,
   createTerminal,
@@ -52,17 +51,14 @@ standardSuite('Clipboard Preservation', (_log) => {
   });
 
   setup(async () => {
+    capturing.terminal.show(true);
+    await vscode.commands.executeCommand(CMD_BIND_TO_TERMINAL_HERE);
+    await settle();
     editor = await vscode.window.showTextDocument(editor.document);
     await writeClipboardSentinel();
     editor.selection = new vscode.Selection(new vscode.Position(0, 0), new vscode.Position(0, 7));
   });
 
-  teardown(async () => {
-    await vscode.workspace
-      .getConfiguration('rangelink')
-      .update('clipboard.preserve', undefined, vscode.ConfigurationTarget.Global);
-  });
-
   test('clipboard-preservation-003: R-F with preserve=always restores clipboard to sentinel after send', async () => {
     await vscode.workspace
       .getConfiguration('rangelink')
@@ -123,10 +119,8 @@ standardSuite('Clipboard Preservation — Assisted', (log) => {
   const tmpTerminals: vscode.Terminal[] = [];
 
   teardown(async () => {
-    await vscode.commands.executeCommand(CMD_UNBIND_DESTINATION);
     await vscode.commands.executeCommand('dummyAi.clearAll');
     for (const t of tmpTerminals.splice(0)) t.dispose();
-    await closeAllEditors();
     cleanupFiles(tmpFileUris);
     tmpFileUris.splice(0);
     await settle();
@@ -301,8 +295,6 @@ standardSuite('Clipboard Preservation — Assisted', (log) => {
   });
 
   test('clipboard-preservation-009: always mode — dismissed picker leaves clipboard unchanged', async () => {
-    await vscode.commands.executeCommand(CMD_UNBIND_DESTINATION);
-
     const lines = Array.from({ length: 5 }, (_, i) => `line ${i + 1}`);
     const fileUri = createWorkspaceFile('cbp-009', lines.join('\n') + '\n');
     tmpFileUris.push(fileUri);

packages/rangelink-vscode-extension/src/__integration-tests__/suite/contextMenuEditorContent.test.ts

@@ -3,7 +3,6 @@ import * as path from 'node:path';
 
 import * as vscode from 'vscode';
 
-import { CMD_UNBIND_DESTINATION } from '../../constants/commandIds';
 import {
   assertClipboardWriteLogged,
   assertFilePathLogged,
@@ -12,7 +11,6 @@ import {
   assertStatusBarMsgLogged,
   assertTerminalBufferContains,
   cleanupFiles,
-  closeAllEditors,
   createAndBindCapturingTerminal,
   createAndOpenFile,
   getLogCapture,
@@ -57,12 +55,10 @@ standardSuite('Context Menus — Editor Content', (log) => {
   });
 
   teardown(async () => {
-    await vscode.commands.executeCommand(CMD_UNBIND_DESTINATION);
     for (const t of terminals) {
       t.dispose();
     }
     terminals.length = 0;
-    await closeAllEditors();
     cleanupFiles(tmpFileUris);
     tmpFileUris.length = 0;
     await settle();