fix(core): use debugLogger for skipped directory warnings

.gitignore

@@ -89,4 +89,4 @@ storybook-static
 
 # Dev symlink: qc-helper bundled skill docs (created by scripts/dev.js)
 packages/core/src/skills/bundled/qc-helper/docs
-tmp/
+tmp/

packages/core/src/config/config.test.ts

@@ -9,6 +9,7 @@ import type { Mock } from 'vitest';
 import type { ConfigParameters, SandboxConfig } from './config.js';
 import { Config, ApprovalMode } from './config.js';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { setGeminiMdFilename as mockSetGeminiMdFilename } from '../memory/const.js';
 import {
@@ -44,6 +45,21 @@ import { readAutoMemoryIndex } from '../memory/store.js';
 import { ExtensionManager } from '../extension/extensionManager.js';
 import { SkillManager } from '../skills/skill-manager.js';
 import { HookSystem } from '../hooks/index.js';
+import * as debugLoggerModule from '../utils/debugLogger.js';
+
+vi.mock('../utils/debugLogger.js', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('../utils/debugLogger.js')>();
+  return {
+    ...actual,
+    createDebugLogger: vi.fn().mockReturnValue({
+      warn: vi.fn(),
+      info: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    }),
+  };
+});
 
 function createToolMock(toolName: string) {
   const ToolMock = vi.fn();
@@ -898,10 +914,15 @@ describe('Server Config (config.ts)', () => {
   });
 
   it('should initialize WorkspaceContext with includeDirectories', () => {
-    const includeDirectories = ['/path/to/dir1', '/path/to/dir2'];
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'config-test-'));
+    const dir1 = path.join(tmpDir, 'dir1');
+    const dir2 = path.join(tmpDir, 'dir2');
+    fs.mkdirSync(dir1);
+    fs.mkdirSync(dir2);
+
     const paramsWithIncludeDirs: ConfigParameters = {
       ...baseParams,
-      includeDirectories,
+      includeDirectories: [dir1, dir2],
     };
     const config = new Config(paramsWithIncludeDirs);
     const workspaceContext = config.getWorkspaceContext();
@@ -910,8 +931,47 @@ describe('Server Config (config.ts)', () => {
     // Should include the target directory plus the included directories
     expect(directories).toHaveLength(3);
     expect(directories).toContain(path.resolve(baseParams.targetDir));
-    expect(directories).toContain('/path/to/dir1');
-    expect(directories).toContain('/path/to/dir2');
+    expect(directories).toContain(dir1);
+    expect(directories).toContain(dir2);
+
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('should warn when includeDirectories paths are skipped', () => {
+    const nonExistentDir = path.join(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'config-skip-test-')),
+      'nonexistent',
+    );
+
+    // Override existsSync to return false only for the non-existent dir,
+    // while keeping the default true for everything else.
+    vi.mocked(fs.existsSync).mockImplementation(
+      (p) => p.toString() !== nonExistentDir,
+    );
+
+    const mockWarn = vi.fn();
+    vi.mocked(debugLoggerModule.createDebugLogger).mockReturnValue({
+      warn: mockWarn,
+      info: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    } as unknown as debugLoggerModule.DebugLogger);
+
+    const paramsWithInvalidDir: ConfigParameters = {
+      ...baseParams,
+      includeDirectories: [nonExistentDir],
+    };
+
+    new Config(paramsWithInvalidDir);
+
+    expect(mockWarn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'The following --include-directories paths were skipped',
+      ),
+    );
+    expect(mockWarn).toHaveBeenCalledWith(
+      expect.stringContaining(nonExistentDir),
+    );
   });
 
   it('Config constructor should set telemetry to true when provided as true', () => {

packages/core/src/config/config.ts

@@ -48,6 +48,8 @@ import { CronScheduler } from '../services/cronScheduler.js';
 import type { SendSdkMcpMessage } from '../tools/mcp-client.js';
 import { setGeminiMdFilename } from '../memory/const.js';
 import { canUseRipgrep } from '../utils/ripgrepUtils.js';
+import { expandHomeDir } from '../utils/paths.js';
+
 import { ToolRegistry, type ToolFactory } from '../tools/tool-registry.js';
 import { ToolNames } from '../tools/tool-names.js';
 import type { LspClient } from '../lsp/types.js';
@@ -731,7 +733,14 @@ export class Config {
       this.targetDir,
       this.explicitIncludeDirectories,
     );
+    const skippedDirs = this.workspaceContext.getSkippedDirectories();
+    if (skippedDirs.length > 0) {
+      this.debugLogger.warn(
+        `The following --include-directories paths were skipped because they do not exist or are not readable:\n${skippedDirs.map((d) => `  - ${expandHomeDir(d)}`).join('\n')}`,
+      );
+    }
     this.debugMode = params.debugMode;
+
     this.inputFormat = params.inputFormat ?? InputFormat.TEXT;
     const normalizedOutputFormat = normalizeConfigOutputFormat(
       params.outputFormat ?? params.output?.format,

packages/core/src/utils/paths.test.ts

@@ -25,6 +25,7 @@ import {
   isSubpath,
   shortenPath,
   tildeifyPath,
+  expandHomeDir,
   getProjectHash,
   _resetValidatePathCacheForTest,
 } from './paths.js';
@@ -911,3 +912,51 @@ describe('getProjectHash', () => {
     platformSpy.mockRestore();
   });
 });
+
+describe('expandHomeDir', () => {
+  const homeDir = os.homedir();
+
+  it('should return empty string for empty input', () => {
+    expect(expandHomeDir('')).toBe('');
+  });
+
+  it('should expand ~ to home directory', () => {
+    expect(expandHomeDir('~')).toBe(path.normalize(homeDir));
+  });
+
+  it('should expand ~/path to home directory path', () => {
+    expect(expandHomeDir('~/documents')).toBe(path.join(homeDir, 'documents'));
+  });
+
+  it('should not expand ~path (no slash)', () => {
+    expect(expandHomeDir('~documents')).toBe('~documents');
+  });
+
+  it('should expand %userprofile% (case-insensitive) to home directory', () => {
+    expect(expandHomeDir('%userprofile%')).toBe(path.normalize(homeDir));
+    expect(expandHomeDir('%USERPROFILE%')).toBe(path.normalize(homeDir));
+  });
+
+  it('should expand %userprofile%\\path to home directory path', () => {
+    // We use path.join to get the correct separator for the current platform
+    const result = expandHomeDir('%userprofile%/documents');
+    expect(result).toBe(path.join(homeDir, 'documents'));
+
+    if (process.platform === 'win32') {
+      const resultWin = expandHomeDir('%userprofile%\\documents');
+      expect(resultWin).toBe(path.join(homeDir, 'documents'));
+    }
+  });
+
+  it('should return regular absolute path unchanged (but normalized)', () => {
+    const absPath =
+      process.platform === 'win32' ? 'C:\\absolute\\path' : '/absolute/path';
+    expect(expandHomeDir(absPath)).toBe(path.normalize(absPath));
+  });
+
+  it('should return relative path unchanged (but normalized)', () => {
+    expect(expandHomeDir('relative/path')).toBe(
+      path.normalize('relative/path'),
+    );
+  });
+});

packages/core/src/utils/paths.ts

@@ -75,6 +75,24 @@ export function tildeifyPath(path: string): string {
   return path;
 }
 
+/**
+ * Expands tilde (~) and Windows-style %userprofile% to the full home directory path.
+ * @param p - The path to expand.
+ * @returns The expanded path.
+ */
+export function expandHomeDir(p: string): string {
+  if (!p) {
+    return '';
+  }
+  let expandedPath = p;
+  if (p.toLowerCase().startsWith('%userprofile%')) {
+    expandedPath = os.homedir() + p.substring('%userprofile%'.length);
+  } else if (p === '~' || p.startsWith('~/')) {
+    expandedPath = os.homedir() + p.substring(1);
+  }
+  return path.normalize(expandedPath);
+}
+
 /**
  * Shortens a path string if it exceeds maxLen, prioritizing the start and end segments.
  * Shows root + first segment + "..." + end segments when middle segments are omitted.

packages/core/src/utils/workspaceContext.ts

@@ -22,7 +22,9 @@ export type Unsubscribe = () => void;
 export class WorkspaceContext {
   private directories = new Set<string>();
   private initialDirectories: Set<string>;
+  private readonly skippedDirectories = new Set<string>();
   private onDirectoriesChangedListeners = new Set<() => void>();
+
   /**
    * Memoized realpath results. Every workspace-bounded tool call ultimately
    * routes through {@link fullyResolvedPath} → `fs.realpathSync`; without
@@ -50,8 +52,17 @@ export class WorkspaceContext {
     }
   }
 
+  /**
+   * Returns directories that were skipped during construction because they
+   * did not exist or were not readable.
+   */
+  getSkippedDirectories(): readonly string[] {
+    return Array.from(this.skippedDirectories);
+  }
+
   /**
    * Registers a listener that is called when the workspace directories change.
+
    * @param listener The listener to call.
    * @returns A function to unsubscribe the listener.
    */
@@ -88,6 +99,7 @@ export class WorkspaceContext {
       this.directories.add(resolved);
       this.notifyDirectoriesChanged();
     } catch (err) {
+      this.skippedDirectories.add(directory);
       debugLogger.warn(
         `Skipping unreadable directory: ${directory} (${err instanceof Error ? err.message : String(err)})`,
       );