Issue Queue: issue-exec-20260106-160325 (#52)

* feat(security): Secure dashboard server by default

## Solution Summary
- Solution-ID: SOL-DSC-002-1
- Issue-ID: DSC-002

## Tasks Completed
- [T1] JWT token manager (24h expiry, persisted secret/token)
- [T2] API auth middleware + localhost token endpoint
- [T3] Default bind 127.0.0.1, add --host with warning
- [T4] Localhost-only CORS with credentials + Vary
- [T5] SECURITY.md documentation + README link

## Verification
- npm run build
- npm test -- ccw/tests/token-manager.test.ts ccw/tests/middleware.test.ts ccw/tests/server-auth.integration.test.ts ccw/tests/server.test.ts ccw/tests/cors.test.ts

* fix(security): Prevent command injection in Windows spawn()

## Solution Summary
- **Solution-ID**: SOL-DSC-001-1
- **Issue-ID**: DSC-001
- **Risk/Impact/Complexity**: high/high/medium

## Tasks Completed
- [T1] Create Windows shell escape utility
- [T2] Escape cli-executor spawn() args on Windows
- [T3] Add command injection regression tests

## Files Modified
- ccw/src/utils/shell-escape.ts
- ccw/src/tools/cli-executor.ts
- ccw/tests/shell-escape.test.ts
- ccw/tests/security/command-injection.test.ts

## Verification
- npm run build
- npm test -- ccw/tests/shell-escape.test.ts ccw/tests/security/command-injection.test.ts

* fix(security): Harden path validation (DSC-005)

## Solution Summary
- Solution-ID: SOL-DSC-005-1
- Issue-ID: DSC-005

## Tasks Completed
- T1: Refactor path validation to pre-resolution checking
- T2: Implement allowlist-based path validation
- T3: Add path validation to API routes
- T4: Add path security regression tests

## Files Modified
- ccw/src/utils/path-resolver.ts
- ccw/src/utils/path-validator.ts
- ccw/src/core/routes/graph-routes.ts
- ccw/src/core/routes/files-routes.ts
- ccw/src/core/routes/skills-routes.ts
- ccw/tests/path-resolver.test.ts
- ccw/tests/graph-routes.test.ts
- ccw/tests/files-routes.test.ts
- ccw/tests/skills-routes.test.ts
- ccw/tests/security/path-traversal.test.ts

## Verification
- npm run build
- npm test -- path-resolver.test.ts
- npm test -- path-validator.test.ts
- npm test -- graph-routes.test.ts
- npm test -- files-routes.test.ts
- npm test -- skills-routes.test.ts
- npm test -- ccw/tests/security/path-traversal.test.ts

* fix(security): Prevent credential leakage (DSC-004)

## Solution Summary
- Solution-ID: SOL-DSC-004-1
- Issue-ID: DSC-004

## Tasks Completed
- T1: Create credential handling security tests
- T2: Add log sanitization tests
- T3: Add env var leakage prevention tests
- T4: Add secure storage tests

## Files Modified
- ccw/src/config/litellm-api-config-manager.ts
- ccw/src/core/routes/litellm-api-routes.ts
- ccw/tests/security/credential-handling.test.ts

## Verification
- npm run build
- node --experimental-strip-types --test ccw/tests/security/credential-handling.test.ts

* test(ranking): expand normalize_weights edge case coverage (ISS-1766920108814-0)

## Solution Summary
- Solution-ID: SOL-20251228113607
- Issue-ID: ISS-1766920108814-0

## Tasks Completed
- T1: Fix NaN and invalid total handling in normalize_weights
- T2: Add unit tests for NaN edge cases in normalize_weights

## Files Modified
- codex-lens/tests/test_rrf_fusion.py

## Verification
- python -m pytest codex-lens/tests/test_rrf_fusion.py::TestNormalizeBM25Score -v
- python -m pytest codex-lens/tests/test_rrf_fusion.py -v -k normalize
- python -m pytest codex-lens/tests/test_rrf_fusion.py::TestReciprocalRankFusion::test_weight_normalization codex-lens/tests/test_cli_hybrid_search.py::TestCLIHybridSearch::test_weights_normalization -v

* feat(security): Add CSRF protection and tighten CORS (DSC-006)

## Solution Summary
- Solution-ID: SOL-DSC-006-1
- Issue-ID: DSC-006
- Risk/Impact/Complexity: high/high/medium

## Tasks Completed
- T1: Create CSRF token generation system
- T2: Add CSRF token endpoints
- T3: Implement CSRF validation middleware
- T4: Restrict CORS to trusted origins
- T5: Add CSRF security tests

## Files Modified
- ccw/src/core/auth/csrf-manager.ts
- ccw/src/core/auth/csrf-middleware.ts
- ccw/src/core/routes/auth-routes.ts
- ccw/src/core/server.ts
- ccw/tests/csrf-manager.test.ts
- ccw/tests/auth-routes.test.ts
- ccw/tests/csrf-middleware.test.ts
- ccw/tests/security/csrf.test.ts

## Verification
- npm run build
- node --experimental-strip-types --test ccw/tests/csrf-manager.test.ts
- node --experimental-strip-types --test ccw/tests/auth-routes.test.ts
- node --experimental-strip-types --test ccw/tests/csrf-middleware.test.ts
- node --experimental-strip-types --test ccw/tests/cors.test.ts
- node --experimental-strip-types --test ccw/tests/security/csrf.test.ts

* fix(cli-executor): prevent stale SIGKILL timeouts

## Solution Summary

- Solution-ID: SOL-DSC-007-1

- Issue-ID: DSC-007

- Risk/Impact/Complexity: low/low/low

## Tasks Completed

- [T1] Store timeout handle in killCurrentCliProcess

## Files Modified

- ccw/src/tools/cli-executor.ts

- ccw/tests/cli-executor-kill.test.ts

## Verification

- node --experimental-strip-types --test ccw/tests/cli-executor-kill.test.ts

* fix(cli-executor): enhance merge validation guards

## Solution Summary

- Solution-ID: SOL-DSC-008-1

- Issue-ID: DSC-008

- Risk/Impact/Complexity: low/low/low

## Tasks Completed

- [T1] Enhance sourceConversations array validation

## Files Modified

- ccw/src/tools/cli-executor.ts

- ccw/tests/cli-executor-merge-validation.test.ts

## Verification

- node --experimental-strip-types --test ccw/tests/cli-executor-merge-validation.test.ts

* refactor(core): remove @ts-nocheck from core routes

## Solution Summary
- Solution-ID: SOL-DSC-003-1
- Issue-ID: DSC-003
- Queue-ID: QUE-20260106-164500
- Item-ID: S-9

## Tasks Completed
- T1: Create shared RouteContext type definition
- T2: Remove @ts-nocheck from small route files
- T3: Remove @ts-nocheck from medium route files
- T4: Remove @ts-nocheck from large route files
- T5: Remove @ts-nocheck from remaining core files

## Files Modified
- ccw/src/core/dashboard-generator-patch.ts
- ccw/src/core/dashboard-generator.ts
- ccw/src/core/routes/ccw-routes.ts
- ccw/src/core/routes/claude-routes.ts
- ccw/src/core/routes/cli-routes.ts
- ccw/src/core/routes/codexlens-routes.ts
- ccw/src/core/routes/discovery-routes.ts
- ccw/src/core/routes/files-routes.ts
- ccw/src/core/routes/graph-routes.ts
- ccw/src/core/routes/help-routes.ts
- ccw/src/core/routes/hooks-routes.ts
- ccw/src/core/routes/issue-routes.ts
- ccw/src/core/routes/litellm-api-routes.ts
- ccw/src/core/routes/litellm-routes.ts
- ccw/src/core/routes/mcp-routes.ts
- ccw/src/core/routes/mcp-routes.ts.backup
- ccw/src/core/routes/mcp-templates-db.ts
- ccw/src/core/routes/nav-status-routes.ts
- ccw/src/core/routes/rules-routes.ts
- ccw/src/core/routes/session-routes.ts
- ccw/src/core/routes/skills-routes.ts
- ccw/src/core/routes/status-routes.ts
- ccw/src/core/routes/system-routes.ts
- ccw/src/core/routes/types.ts
- ccw/src/core/server.ts
- ccw/src/core/websocket.ts

## Verification
- npm run build
- npm test

* refactor: split cli-executor and codexlens routes into modules

## Solution Summary
- Solution-ID: SOL-DSC-012-1
- Issue-ID: DSC-012
- Risk/Impact/Complexity: medium/medium/high

## Tasks Completed
- [T1] Extract execution orchestration from cli-executor.ts (Refactor ccw/src/tools)
- [T2] Extract route handlers from codexlens-routes.ts (Refactor ccw/src/core/routes)
- [T3] Extract prompt concatenation logic from cli-executor (Refactor ccw/src/tools)
- [T4] Document refactored module architecture (Docs)

## Files Modified
- ccw/src/tools/cli-executor.ts
- ccw/src/tools/cli-executor-core.ts
- ccw/src/tools/cli-executor-utils.ts
- ccw/src/tools/cli-executor-state.ts
- ccw/src/tools/cli-prompt-builder.ts
- ccw/src/tools/README.md
- ccw/src/core/routes/codexlens-routes.ts
- ccw/src/core/routes/codexlens/config-handlers.ts
- ccw/src/core/routes/codexlens/index-handlers.ts
- ccw/src/core/routes/codexlens/semantic-handlers.ts
- ccw/src/core/routes/codexlens/watcher-handlers.ts
- ccw/src/core/routes/codexlens/utils.ts
- ccw/src/core/routes/codexlens/README.md

## Verification
- npm run build
- npm test

* test(issue): Add comprehensive issue command tests

## Solution Summary
- **Solution-ID**: SOL-DSC-009-1
- **Issue-ID**: DSC-009
- **Risk/Impact/Complexity**: low/high/medium

## Tasks Completed
- [T1] Create issue command test file structure: Create isolated test harness
- [T2] Add JSONL read/write operation tests: Verify JSONL correctness and errors
- [T3] Add issue lifecycle tests: Verify status transitions and timestamps
- [T4] Add solution binding tests: Verify binding flows and error cases
- [T5] Add queue formation tests: Verify queue creation, IDs, and DAG behavior
- [T6] Add queue execution tests: Verify next/done/retry and status sync

## Files Modified
- ccw/src/commands/issue.ts
- ccw/tests/issue-command.test.ts

## Verification
- node --experimental-strip-types --test ccw/tests/issue-command.test.ts

* test(routes): Add integration tests for route modules

## Solution Summary
- Solution-ID: SOL-DSC-010-1
- Issue-ID: DSC-010
- Queue-ID: QUE-20260106-164500

## Tasks Completed
- [T1] Add tests for ccw-routes.ts
- [T2] Add tests for files-routes.ts
- [T3] Add tests for claude-routes.ts (includes Windows path fix for create)
- [T4] Add tests for issue-routes.ts
- [T5] Add tests for help-routes.ts (avoid hanging watchers)
- [T6] Add tests for nav-status-routes.ts
- [T7] Add tests for hooks/graph/rules/skills/litellm-api routes

## Files Modified
- ccw/src/core/routes/claude-routes.ts
- ccw/src/core/routes/help-routes.ts
- ccw/tests/integration/ccw-routes.test.ts
- ccw/tests/integration/claude-routes.test.ts
- ccw/tests/integration/files-routes.test.ts
- ccw/tests/integration/issue-routes.test.ts
- ccw/tests/integration/help-routes.test.ts
- ccw/tests/integration/nav-status-routes.test.ts
- ccw/tests/integration/hooks-routes.test.ts
- ccw/tests/integration/graph-routes.test.ts
- ccw/tests/integration/rules-routes.test.ts
- ccw/tests/integration/skills-routes.test.ts
- ccw/tests/integration/litellm-api-routes.test.ts

## Verification
- node --experimental-strip-types --test ccw/tests/integration/ccw-routes.test.ts
- node --experimental-strip-types --test ccw/tests/integration/files-routes.test.ts
- node --experimental-strip-types --test ccw/tests/integration/claude-routes.test.ts
- node --experimental-strip-types --test ccw/tests/integration/issue-routes.test.ts
- node --experimental-strip-types --test ccw/tests/integration/help-routes.test.ts
- node --experimental-strip-types --test ccw/tests/integration/nav-status-routes.test.ts
- node --experimental-strip-types --test ccw/tests/integration/hooks-routes.test.ts
- node --experimental-strip-types --test ccw/tests/integration/graph-routes.test.ts
- node --experimental-strip-types --test ccw/tests/integration/rules-routes.test.ts
- node --experimental-strip-types --test ccw/tests/integration/skills-routes.test.ts
- node --experimental-strip-types --test ccw/tests/integration/litellm-api-routes.test.ts

* refactor(core): Switch cache and lite scanning to async fs

## Solution Summary
- Solution-ID: SOL-DSC-013-1
- Issue-ID: DSC-013
- Queue-ID: QUE-20260106-164500

## Tasks Completed
- [T1] Convert cache-manager.ts to async file operations
- [T2] Convert lite-scanner.ts to async file operations
- [T3] Update cache-manager call sites to await async API
- [T4] Update lite-scanner call sites to await async API

## Files Modified
- ccw/src/core/cache-manager.ts
- ccw/src/core/lite-scanner.ts
- ccw/src/core/data-aggregator.ts

## Verification
- npm run build
- npm test

* fix(exec): Add timeout protection for execSync

## Solution Summary
- Solution-ID: SOL-DSC-014-1
- Issue-ID: DSC-014
- Queue-ID: QUE-20260106-164500

## Tasks Completed
- [T1] Add timeout to execSync calls in python-utils.ts
- [T2] Add timeout to execSync calls in detect-changed-modules.ts
- [T3] Add timeout to execSync calls in claude-freshness.ts
- [T4] Add timeout to execSync calls in issue.ts
- [T5] Consolidate execSync timeout constants and audit coverage

## Files Modified
- ccw/src/utils/exec-constants.ts
- ccw/src/utils/python-utils.ts
- ccw/src/tools/detect-changed-modules.ts
- ccw/src/core/claude-freshness.ts
- ccw/src/commands/issue.ts
- ccw/src/tools/smart-search.ts
- ccw/src/tools/codex-lens.ts
- ccw/src/core/routes/codexlens/config-handlers.ts

## Verification
- npm run build
- npm test
- node --experimental-strip-types --test ccw/tests/issue-command.test.ts

* feat(cli): Add progress spinner with elapsed time for long-running operations

## Solution Summary
- Solution-ID: SOL-DSC-015-1
- Issue-ID: DSC-015
- Queue-Item: S-15
- Risk/Impact/Complexity: low/medium/low

## Tasks Completed
- [T1] Add progress spinner to CLI execution: Update ccw/src/commands/cli.ts

## Files Modified
- ccw/src/commands/cli.ts
- ccw/tests/cli-command.test.ts

## Verification
- node --experimental-strip-types --test ccw/tests/cli-command.test.ts
- node --experimental-strip-types --test ccw/tests/cli-executor-kill.test.ts
- node --experimental-strip-types --test ccw/tests/cli-executor-merge-validation.test.ts

* fix(cli): Move full output hint immediately after truncation notice

## Solution Summary
- Solution-ID: SOL-DSC-016-1
- Issue-ID: DSC-016
- Queue-Item: S-16
- Risk/Impact/Complexity: low/high/low

## Tasks Completed
- [T1] Relocate output hint after truncation: Update ccw/src/commands/cli.ts

## Files Modified
- ccw/src/commands/cli.ts
- ccw/tests/cli-command.test.ts

## Verification
- npm run build
- node --experimental-strip-types --test ccw/tests/cli-command.test.ts

* feat(cli): Add confirmation prompts for destructive operations

## Solution Summary
- Solution-ID: SOL-DSC-017-1
- Issue-ID: DSC-017
- Queue-Item: S-17
- Risk/Impact/Complexity: low/high/low

## Tasks Completed
- [T1] Add confirmation to storage clean operations: Update ccw/src/commands/cli.ts
- [T2] Add confirmation to issue queue delete: Update ccw/src/commands/issue.ts

## Files Modified
- ccw/src/commands/cli.ts
- ccw/src/commands/issue.ts
- ccw/tests/cli-command.test.ts
- ccw/tests/issue-command.test.ts

## Verification
- npm run build
- node --experimental-strip-types --test ccw/tests/cli-command.test.ts
- node --experimental-strip-types --test ccw/tests/issue-command.test.ts

* feat(cli): Improve multi-line prompt guidance

## Solution Summary
- Solution-ID: SOL-DSC-018-1
- Issue-ID: DSC-018
- Queue-Item: S-18
- Risk/Impact/Complexity: low/medium/low

## Tasks Completed
- [T1] Update CLI help to emphasize --file option: Update ccw/src/commands/cli.ts
- [T2] Add inline hint for multi-line detection: Update ccw/src/commands/cli.ts

## Files Modified
- ccw/src/commands/cli.ts
- ccw/tests/cli-command.test.ts

## Verification
- npm run build
- node --experimental-strip-types --test ccw/tests/cli-command.test.ts

---------

Co-authored-by: catlog22 <catlog22@github.com>

ccw/tests/auth-routes.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Unit tests for auth routes (ccw/dist/core/routes/auth-routes.js).
+ */
+
+import { afterEach, before, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+
+type JsonResponse = {
+  status: number;
+  json: any;
+  text: string;
+  headers: http.IncomingHttpHeaders;
+};
+
+async function requestJson(baseUrl: string, method: string, reqPath: string, headers?: Record<string, string>): Promise<JsonResponse> {
+  const url = new URL(reqPath, baseUrl);
+
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      url,
+      {
+        method,
+        headers: { Accept: 'application/json', ...(headers ?? {}) },
+      },
+      (res) => {
+        let responseBody = '';
+        res.on('data', (chunk) => {
+          responseBody += chunk.toString();
+        });
+        res.on('end', () => {
+          let json: any = null;
+          try {
+            json = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            json = null;
+          }
+          resolve({ status: res.statusCode || 0, json, text: responseBody, headers: res.headers });
+        });
+      },
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function cookiePairsFromSetCookie(setCookie: string | string[] | undefined): string {
+  if (!setCookie) return '';
+  const items = Array.isArray(setCookie) ? setCookie : [setCookie];
+  const pairs: string[] = [];
+  for (const item of items) {
+    const pair = item.split(';')[0]?.trim();
+    if (pair) pairs.push(pair);
+  }
+  return pairs.join('; ');
+}
+
+async function createServer(): Promise<{ server: http.Server; baseUrl: string }> {
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const pathname = url.pathname;
+
+    const ctx = {
+      pathname,
+      url,
+      req,
+      res,
+      initialPath: process.cwd(),
+      handlePostRequest() {},
+      broadcastToClients() {},
+    };
+
+    try {
+      const handled = await authRoutes.handleAuthRoutes(ctx);
+      if (!handled) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not Found' }));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.listen(0, '127.0.0.1', () => resolve());
+    server.on('error', reject);
+  });
+
+  const address = server.address();
+  if (!address || typeof address === 'string') throw new Error('Expected server to listen on a TCP port');
+  return { server, baseUrl: `http://127.0.0.1:${address.port}` };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let authRoutes: any;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let csrfManager: any;
+
+describe('auth routes: csrf-token endpoint', async () => {
+  before(async () => {
+    authRoutes = await import(new URL('../dist/core/routes/auth-routes.js', import.meta.url).href);
+    csrfManager = await import(new URL('../dist/core/auth/csrf-manager.js', import.meta.url).href);
+  });
+
+  afterEach(() => {
+    csrfManager.resetCsrfTokenManager();
+  });
+
+  it('GET /api/csrf-token returns token in body, header, and cookie', async () => {
+    const { server, baseUrl } = await createServer();
+    try {
+      const res = await requestJson(baseUrl, 'GET', '/api/csrf-token');
+      assert.equal(res.status, 200);
+      assert.ok(res.json?.csrfToken);
+
+      const token = String(res.json.csrfToken);
+      assert.match(token, /^[a-f0-9]{64}$/);
+      assert.equal(res.headers['x-csrf-token'], token);
+
+      const setCookie = res.headers['set-cookie'];
+      const cookies = Array.isArray(setCookie) ? setCookie.join('\n') : String(setCookie || '');
+      assert.ok(cookies.includes('XSRF-TOKEN='));
+      assert.ok(cookies.includes('HttpOnly'));
+      assert.ok(cookies.includes('SameSite=Strict'));
+      assert.ok(cookies.includes(token));
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it('GET /api/csrf-token returns a new token per request (same session)', async () => {
+    const { server, baseUrl } = await createServer();
+    try {
+      const first = await requestJson(baseUrl, 'GET', '/api/csrf-token');
+      assert.equal(first.status, 200);
+      const cookieHeader = cookiePairsFromSetCookie(first.headers['set-cookie']);
+      assert.ok(cookieHeader.includes('ccw_session_id='));
+
+      const second = await requestJson(baseUrl, 'GET', '/api/csrf-token', { Cookie: cookieHeader });
+      assert.equal(second.status, 200);
+
+      assert.notEqual(first.json.csrfToken, second.json.csrfToken);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+});

ccw/tests/cli-command.test.ts

@@ -10,9 +10,10 @@
 import { after, afterEach, before, describe, it, mock } from 'node:test';
 import assert from 'node:assert/strict';
 import http from 'node:http';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import inquirer from 'inquirer';
 
 const TEST_CCW_HOME = mkdtempSync(join(tmpdir(), 'ccw-cli-command-'));
 process.env.CCW_DATA_DIR = TEST_CCW_HOME;
@@ -20,6 +21,7 @@ process.env.CCW_DATA_DIR = TEST_CCW_HOME;
 const cliCommandPath = new URL('../dist/commands/cli.js', import.meta.url).href;
 const cliExecutorPath = new URL('../dist/tools/cli-executor.js', import.meta.url).href;
 const historyStorePath = new URL('../dist/tools/cli-history-store.js', import.meta.url).href;
+const storageManagerPath = new URL('../dist/tools/storage-manager.js', import.meta.url).href;
 
 function stubHttpRequest(): void {
   mock.method(http, 'request', () => {
@@ -50,11 +52,14 @@ describe('cli command module', async () => {
   let cliExecutorModule: any;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let historyStoreModule: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let storageManagerModule: any;
 
   before(async () => {
     cliModule = await import(cliCommandPath);
     cliExecutorModule = await import(cliExecutorPath);
     historyStoreModule = await import(historyStorePath);
+    storageManagerModule = await import(storageManagerPath);
   });
 
   afterEach(() => {
@@ -112,6 +117,117 @@ describe('cli command module', async () => {
     assert.deepEqual(exitCodes, [0, 0, 0]);
   });
 
+  it('prints a --file tip when a multi-line prompt is provided via --prompt', async () => {
+    stubHttpRequest();
+
+    const logs: string[] = [];
+    mock.method(console, 'log', (...args: any[]) => {
+      logs.push(args.map(String).join(' '));
+    });
+    mock.method(console, 'error', (...args: any[]) => {
+      logs.push(args.map(String).join(' '));
+    });
+
+    mock.method(cliExecutorModule.cliExecutorTool, 'execute', async () => {
+      return {
+        success: true,
+        stdout: '',
+        stderr: '',
+        execution: { id: 'EXEC-ML', duration_ms: 1, status: 'success' },
+        conversation: { turn_count: 1, total_duration_ms: 1 },
+      };
+    });
+
+    const exitCodes: Array<number | undefined> = [];
+    mock.method(process as any, 'exit', (code?: number) => {
+      exitCodes.push(code);
+    });
+
+    await cliModule.cliCommand('exec', [], { prompt: 'line1\nline2\nline3\nline4', tool: 'gemini', stream: true });
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    assert.ok(logs.some((l) => l.includes('Tip: Use --file option to avoid shell escaping issues with multi-line prompts')));
+    assert.ok(logs.some((l) => l.includes('Example: ccw cli -f prompt.txt --tool gemini')));
+    assert.deepEqual(exitCodes, [0]);
+  });
+
+  it('does not print the --file tip for single-line prompts', async () => {
+    stubHttpRequest();
+
+    const logs: string[] = [];
+    mock.method(console, 'log', (...args: any[]) => {
+      logs.push(args.map(String).join(' '));
+    });
+    mock.method(console, 'error', (...args: any[]) => {
+      logs.push(args.map(String).join(' '));
+    });
+
+    mock.method(cliExecutorModule.cliExecutorTool, 'execute', async () => {
+      return {
+        success: true,
+        stdout: '',
+        stderr: '',
+        execution: { id: 'EXEC-SL', duration_ms: 1, status: 'success' },
+        conversation: { turn_count: 1, total_duration_ms: 1 },
+      };
+    });
+
+    const exitCodes: Array<number | undefined> = [];
+    mock.method(process as any, 'exit', (code?: number) => {
+      exitCodes.push(code);
+    });
+
+    await cliModule.cliCommand('exec', [], { prompt: 'Hello', tool: 'gemini', stream: true });
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    assert.equal(
+      logs.some((l) => l.includes('Tip: Use --file option to avoid shell escaping issues with multi-line prompts')),
+      false,
+    );
+    assert.deepEqual(exitCodes, [0]);
+  });
+
+  it('prints full output hint immediately after stderr truncation (no troubleshooting duplicate)', async () => {
+    stubHttpRequest();
+
+    const logs: string[] = [];
+    mock.method(console, 'log', (...args: any[]) => {
+      logs.push(args.map(String).join(' '));
+    });
+    mock.method(console, 'error', (...args: any[]) => {
+      logs.push(args.map(String).join(' '));
+    });
+
+    mock.method(cliExecutorModule.cliExecutorTool, 'execute', async () => {
+      const stderr = Array.from({ length: 31 }, (_, i) => `stderr-line-${i}`).join('\n');
+      return {
+        success: false,
+        stdout: '',
+        stderr,
+        execution: { id: 'EXEC-ERR', duration_ms: 12, status: 'error', exit_code: 1 },
+        conversation: { turn_count: 1, total_duration_ms: 12 },
+      };
+    });
+
+    const exitCodes: Array<number | undefined> = [];
+    mock.method(process as any, 'exit', (code?: number) => {
+      exitCodes.push(code);
+    });
+
+    await cliModule.cliCommand('exec', [], { prompt: 'Hello', tool: 'gemini', stream: true });
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const truncationIndex = logs.findIndex((l) => l.includes('... 1 more lines'));
+    const hintIndex = logs.findIndex((l) => l.includes('💡 View full output: ccw cli output EXEC-ERR'));
+    assert.ok(truncationIndex >= 0);
+    assert.ok(hintIndex >= 0);
+    assert.equal(hintIndex, truncationIndex + 1);
+
+    assert.equal(logs.filter((l) => l.includes('View full output: ccw cli output EXEC-ERR')).length, 1);
+    assert.equal(logs.filter((l) => l.includes('• View full output')).length, 0);
+    assert.deepEqual(exitCodes, [1]);
+  });
+
   it('supports resume with conversation ID and latest (no prompt required)', async () => {
     stubHttpRequest();
     mock.method(console, 'log', () => {});
@@ -181,6 +297,100 @@ describe('cli command module', async () => {
     assert.equal(executed, false);
   });
 
+  it('shows --file guidance first in help output (multi-line prompts)', async () => {
+    const logs: string[] = [];
+    mock.method(console, 'log', (...args: any[]) => {
+      logs.push(args.map(String).join(' '));
+    });
+    mock.method(console, 'error', (...args: any[]) => {
+      logs.push(args.map(String).join(' '));
+    });
+
+    await cliModule.cliCommand('--help', [], {});
+
+    const usageFileIndex = logs.findIndex((l) => l.includes('ccw cli -f prompt.txt'));
+    const usagePromptIndex = logs.findIndex((l) => l.includes('ccw cli -p "<prompt>"'));
+    assert.ok(usageFileIndex >= 0);
+    assert.ok(usagePromptIndex >= 0);
+    assert.ok(usageFileIndex < usagePromptIndex);
+
+    const optionFileIndex = logs.findIndex((l) => l.includes('-f, --file <file>'));
+    const optionPromptIndex = logs.findIndex((l) => l.includes('-p, --prompt <text>'));
+    assert.ok(optionFileIndex >= 0);
+    assert.ok(optionPromptIndex >= 0);
+    assert.ok(optionFileIndex < optionPromptIndex);
+    assert.ok(logs.some((l) => l.includes('Read prompt from file (recommended for multi-line prompts)')));
+
+    assert.ok(logs.some((l) => l.includes('Examples:')));
+    assert.ok(logs.some((l) => l.includes('ccw cli -f my-prompt.txt --tool gemini')));
+    assert.ok(logs.some((l) => l.includes("ccw cli -f <(cat <<'EOF'")));
+    assert.ok(logs.some((l) => l.includes("@'")));
+    assert.ok(logs.some((l) => l.includes('Out-File -Encoding utf8 prompt.tmp; ccw cli -f prompt.tmp --tool gemini')));
+    assert.ok(logs.some((l) => l.includes('Tip: For complex prompts, use --file to avoid shell escaping issues')));
+  });
+
+  it('prompts for confirmation before cleaning all storage (and cancels safely)', async () => {
+    const projectRoot = join(TEST_CCW_HOME, 'projects', 'test-project-cancel');
+    const markerDir = join(projectRoot, 'cli-history');
+    mkdirSync(markerDir, { recursive: true });
+    writeFileSync(join(markerDir, 'dummy.txt'), '1234');
+
+    const stats = storageManagerModule.getStorageStats();
+    const expectedSize = storageManagerModule.formatBytes(stats.totalSize);
+
+    const promptCalls: any[] = [];
+    mock.method(inquirer, 'prompt', async (questions: any) => {
+      promptCalls.push(questions);
+      return { proceed: false };
+    });
+
+    const logs: string[] = [];
+    mock.method(console, 'log', (...args: any[]) => {
+      logs.push(args.map(String).join(' '));
+    });
+    mock.method(console, 'error', (...args: any[]) => {
+      logs.push(args.map(String).join(' '));
+    });
+
+    await cliModule.cliCommand('storage', ['clean'], { force: false });
+
+    assert.equal(promptCalls.length, 1);
+    assert.equal(promptCalls[0][0].type, 'confirm');
+    assert.equal(promptCalls[0][0].default, false);
+    assert.ok(promptCalls[0][0].message.includes(`${stats.projectCount} projects`));
+    assert.ok(promptCalls[0][0].message.includes(`(${expectedSize})`));
+
+    assert.ok(logs.some((l) => l.includes('Storage clean cancelled')));
+    assert.equal(existsSync(projectRoot), true);
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  it('bypasses confirmation prompt when --force is set for storage clean', async () => {
+    const projectRoot = join(TEST_CCW_HOME, 'projects', 'test-project-force');
+    const markerDir = join(projectRoot, 'cli-history');
+    mkdirSync(markerDir, { recursive: true });
+    writeFileSync(join(markerDir, 'dummy.txt'), '1234');
+
+    mock.method(inquirer, 'prompt', async () => {
+      throw new Error('inquirer.prompt should not be called when --force is set');
+    });
+
+    await cliModule.cliCommand('storage', ['clean'], { force: true });
+    assert.equal(existsSync(projectRoot), false);
+  });
+
+  it('deletes all storage after interactive confirmation', async () => {
+    const projectRoot = join(TEST_CCW_HOME, 'projects', 'test-project-confirm');
+    const markerDir = join(projectRoot, 'cli-history');
+    mkdirSync(markerDir, { recursive: true });
+    writeFileSync(join(markerDir, 'dummy.txt'), '1234');
+
+    mock.method(inquirer, 'prompt', async () => ({ proceed: true }));
+
+    await cliModule.cliCommand('storage', ['clean'], { force: false });
+    assert.equal(existsSync(projectRoot), false);
+  });
+
   it('prints history and retrieves conversation detail from SQLite store', async () => {
     stubHttpRequest();
 

ccw/tests/cli-executor-kill.test.ts

@@ -0,0 +1,195 @@
+/**
+ * Regression tests for killCurrentCliProcess timeout handling (DSC-007).
+ *
+ * Focus:
+ * - Avoid stale SIGKILL timers killing a subsequent child process
+ * - Ensure SIGKILL is sent when SIGTERM does not terminate the process
+ */
+
+import { after, before, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const cliExecutorUrl = new URL('../dist/tools/cli-executor.js', import.meta.url).href;
+const historyStoreUrl = new URL('../dist/tools/cli-history-store.js', import.meta.url).href;
+
+type FakeChild = EventEmitter & {
+  pid?: number;
+  killed: boolean;
+  stdin: PassThrough;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  kill: (signal?: string) => boolean;
+  killCalls: string[];
+  close: (code?: number) => void;
+};
+
+type ToolChildBehavior = {
+  closeOnSigterm: boolean;
+};
+
+describe('cli-executor: killCurrentCliProcess regression', async () => {
+  const require = createRequire(import.meta.url);
+  const childProcess = require('child_process');
+  const originalSpawn = childProcess.spawn;
+  const originalSetTimeout = globalThis.setTimeout;
+
+  const envSnapshot: Record<string, string | undefined> = {};
+  let ccwHome = '';
+  let projectDir = '';
+
+  const toolChildren: FakeChild[] = [];
+  const plannedBehaviors: ToolChildBehavior[] = [];
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let cliExecutorModule: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let historyStoreModule: any;
+
+  function unrefFastSetTimeout<TArgs extends unknown[]>(
+    fn: (...args: TArgs) => void,
+    delay?: number,
+    ...args: TArgs
+  ): ReturnType<typeof setTimeout> {
+    const t = originalSetTimeout(fn as (...args: unknown[]) => void, 25, ...args);
+    (t as unknown as { unref?: () => void }).unref?.();
+    return t;
+  }
+
+  function createFakeChild(behavior: ToolChildBehavior, pid: number): FakeChild {
+    const child = new EventEmitter() as FakeChild;
+    child.pid = pid;
+    child.killed = false;
+    child.stdin = new PassThrough();
+    child.stdout = new PassThrough();
+    child.stderr = new PassThrough();
+    child.killCalls = [];
+
+    let closed = false;
+    child.close = (code: number = 0) => {
+      if (closed) return;
+      closed = true;
+      child.stdout.end();
+      child.stderr.end();
+      child.emit('close', code);
+    };
+
+    child.kill = (signal?: string) => {
+      const sig = signal || 'SIGTERM';
+      child.killCalls.push(sig);
+
+      if (sig === 'SIGTERM') {
+        if (behavior.closeOnSigterm) {
+          child.killed = true;
+          queueMicrotask(() => child.close(0));
+        }
+        return true;
+      }
+
+      if (sig === 'SIGKILL') {
+        child.killed = true;
+        queueMicrotask(() => child.close(0));
+        return true;
+      }
+
+      return true;
+    };
+
+    return child;
+  }
+
+  before(async () => {
+    envSnapshot.CCW_DATA_DIR = process.env.CCW_DATA_DIR;
+
+    ccwHome = mkdtempSync(join(tmpdir(), 'ccw-cli-executor-kill-home-'));
+    projectDir = mkdtempSync(join(tmpdir(), 'ccw-cli-executor-kill-project-'));
+    process.env.CCW_DATA_DIR = ccwHome;
+
+    globalThis.setTimeout = unrefFastSetTimeout as unknown as typeof setTimeout;
+
+    childProcess.spawn = (command: unknown, args: unknown[], options: Record<string, unknown>) => {
+      const cmd = String(command);
+      const argv = Array.isArray(args) ? args.map((a) => String(a)) : [];
+
+      // Tool lookup helpers.
+      if (cmd === 'where' || cmd === 'which') {
+        const child = createFakeChild({ closeOnSigterm: true }, 4000);
+        queueMicrotask(() => {
+          child.stdout.write(`C:\\\\fake\\\\${argv[0] || 'tool'}.cmd\r\n`);
+          child.close(0);
+        });
+        return child;
+      }
+
+      const behavior = plannedBehaviors.shift() ?? { closeOnSigterm: true };
+      const child = createFakeChild(behavior, 5000 + toolChildren.length);
+      toolChildren.push(child);
+
+      // Keep the process running until explicitly closed or killed.
+      return child;
+    };
+
+    cliExecutorModule = await import(cliExecutorUrl);
+    historyStoreModule = await import(historyStoreUrl);
+  });
+
+  after(async () => {
+    childProcess.spawn = originalSpawn;
+    globalThis.setTimeout = originalSetTimeout;
+
+    try {
+      historyStoreModule?.closeAllStores?.();
+    } catch {
+      // ignore
+    }
+
+    if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+    if (ccwHome) rmSync(ccwHome, { recursive: true, force: true });
+
+    process.env.CCW_DATA_DIR = envSnapshot.CCW_DATA_DIR;
+  });
+
+  it('does not kill a subsequent child via a stale SIGKILL timeout', async () => {
+    plannedBehaviors.push({ closeOnSigterm: true });
+    plannedBehaviors.push({ closeOnSigterm: false });
+
+    const run1 = cliExecutorModule.handler({ tool: 'codex', prompt: 'test', cd: projectDir });
+    await new Promise((resolve) => setImmediate(resolve));
+
+    assert.equal(cliExecutorModule.killCurrentCliProcess(), true);
+    await run1;
+
+    const run2 = cliExecutorModule.handler({ tool: 'codex', prompt: 'test-2', cd: projectDir });
+    await new Promise((resolve) => setImmediate(resolve));
+
+    // Wait long enough for the (patched) kill timeout to fire if not cleared.
+    await new Promise((resolve) => originalSetTimeout(resolve, 60));
+
+    assert.equal(toolChildren.length >= 2, true);
+    assert.deepEqual(toolChildren[1].killCalls, []);
+
+    toolChildren[1].close(0);
+    await run2;
+  });
+
+  it('sends SIGKILL when SIGTERM does not terminate the process', async () => {
+    plannedBehaviors.push({ closeOnSigterm: false });
+
+    const run = cliExecutorModule.handler({ tool: 'codex', prompt: 'timeout-test', cd: projectDir });
+    await new Promise((resolve) => setImmediate(resolve));
+
+    assert.equal(cliExecutorModule.killCurrentCliProcess(), true);
+    // Keep the event loop alive long enough for the (unref'd) timeout to fire.
+    await new Promise((resolve) => originalSetTimeout(resolve, 60));
+    await run;
+
+    assert.equal(toolChildren.length >= 1, true);
+    assert.ok(toolChildren[toolChildren.length - 1].killCalls.includes('SIGTERM'));
+    assert.ok(toolChildren[toolChildren.length - 1].killCalls.includes('SIGKILL'));
+  });
+});

ccw/tests/cli-executor-merge-validation.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Regression tests for conversation merge validation (DSC-008).
+ *
+ * Focus:
+ * - Merge with all invalid IDs returns a descriptive error including attempted IDs
+ * - Merge proceeds when at least one source conversation is valid
+ */
+
+import { after, before, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const cliExecutorUrl = new URL('../dist/tools/cli-executor.js', import.meta.url).href;
+const historyStoreUrl = new URL('../dist/tools/cli-history-store.js', import.meta.url).href;
+
+type FakeChild = EventEmitter & {
+  pid?: number;
+  killed: boolean;
+  stdin: PassThrough;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  kill: (signal?: string) => boolean;
+  close: (code?: number) => void;
+};
+
+function createFakeChild(pid: number): FakeChild {
+  const child = new EventEmitter() as FakeChild;
+  child.pid = pid;
+  child.killed = false;
+  child.stdin = new PassThrough();
+  child.stdout = new PassThrough();
+  child.stderr = new PassThrough();
+
+  let closed = false;
+  child.close = (code: number = 0) => {
+    if (closed) return;
+    closed = true;
+    child.stdout.end();
+    child.stderr.end();
+    child.emit('close', code);
+  };
+
+  child.kill = (signal?: string) => {
+    child.killed = true;
+    queueMicrotask(() => child.close(0));
+    return true;
+  };
+
+  return child;
+}
+
+describe('cli-executor: merge validation regression', async () => {
+  const require = createRequire(import.meta.url);
+  const childProcess = require('child_process');
+  const originalSpawn = childProcess.spawn;
+
+  const envSnapshot: Record<string, string | undefined> = {};
+  let ccwHome = '';
+  let projectDir = '';
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let cliExecutorModule: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let historyStoreModule: any;
+
+  before(async () => {
+    envSnapshot.CCW_DATA_DIR = process.env.CCW_DATA_DIR;
+
+    ccwHome = mkdtempSync(join(tmpdir(), 'ccw-cli-executor-merge-home-'));
+    projectDir = mkdtempSync(join(tmpdir(), 'ccw-cli-executor-merge-project-'));
+    process.env.CCW_DATA_DIR = ccwHome;
+
+    childProcess.spawn = (command: unknown, args: unknown[]) => {
+      const cmd = String(command);
+      const argv = Array.isArray(args) ? args.map((a) => String(a)) : [];
+
+      // Tool lookup helpers.
+      if (cmd === 'where' || cmd === 'which') {
+        const child = createFakeChild(4000);
+        queueMicrotask(() => {
+          child.stdout.write(`C:\\\\fake\\\\${argv[0] || 'tool'}.cmd\r\n`);
+          child.close(0);
+        });
+        return child;
+      }
+
+      const child = createFakeChild(5000);
+      queueMicrotask(() => {
+        child.stdout.write('OK\n');
+        child.close(0);
+      });
+      return child;
+    };
+
+    historyStoreModule = await import(historyStoreUrl);
+    cliExecutorModule = await import(cliExecutorUrl);
+  });
+
+  after(() => {
+    childProcess.spawn = originalSpawn;
+
+    try {
+      historyStoreModule?.closeAllStores?.();
+    } catch {
+      // ignore
+    }
+
+    if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+    if (ccwHome) rmSync(ccwHome, { recursive: true, force: true });
+    process.env.CCW_DATA_DIR = envSnapshot.CCW_DATA_DIR;
+  });
+
+  it('throws a descriptive error when all merge IDs are invalid', async () => {
+    await assert.rejects(
+      () => cliExecutorModule.cliExecutorTool.execute({
+        tool: 'codex',
+        prompt: 'test',
+        cd: projectDir,
+        resume: 'MISSING-1, MISSING-2'
+      }),
+      (err: unknown) => {
+        assert.ok(err instanceof Error);
+        assert.ok(err.message.includes('No valid conversations found for merge'));
+        assert.ok(err.message.includes('MISSING-1'));
+        assert.ok(err.message.includes('MISSING-2'));
+        return true;
+      }
+    );
+  });
+
+  it('merges when at least one source conversation is valid', async () => {
+    const store = historyStoreModule.getHistoryStore(projectDir);
+    store.saveConversation({
+      id: 'CONV-MERGE-VALID-1',
+      created_at: new Date('2025-01-01T00:00:00.000Z').toISOString(),
+      updated_at: new Date('2025-01-01T00:00:01.000Z').toISOString(),
+      tool: 'codex',
+      model: 'default',
+      mode: 'analysis',
+      category: 'user',
+      total_duration_ms: 1,
+      turn_count: 1,
+      latest_status: 'success',
+      turns: [
+        {
+          turn: 1,
+          timestamp: new Date('2025-01-01T00:00:00.000Z').toISOString(),
+          prompt: 'Previous prompt',
+          duration_ms: 1,
+          status: 'success',
+          exit_code: 0,
+          output: { stdout: 'Previous output', stderr: '', truncated: false, cached: false }
+        }
+      ]
+    });
+
+    const result = await cliExecutorModule.cliExecutorTool.execute({
+      tool: 'codex',
+      prompt: 'Next prompt',
+      cd: projectDir,
+      resume: 'CONV-MERGE-VALID-1, MISSING-99'
+    });
+
+    assert.equal(result.success, true);
+    assert.ok(result.execution?.id);
+  });
+});
+

ccw/tests/cors.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Unit tests for CORS origin validation (ccw/dist/core/cors.js)
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+const corsUrl = new URL('../dist/core/cors.js', import.meta.url).href;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let corsMod: any;
+
+describe('CORS origin validation', async () => {
+  corsMod = await import(corsUrl);
+
+  it('allows localhost origins on the server port', () => {
+    assert.equal(corsMod.validateCorsOrigin('http://localhost:3456', 3456), true);
+    assert.equal(corsMod.validateCorsOrigin('http://127.0.0.1:3456', 3456), true);
+  });
+
+  it('rejects external origins', () => {
+    assert.equal(corsMod.validateCorsOrigin('http://evil.com', 3456), false);
+    assert.equal(corsMod.validateCorsOrigin('http://localhost:3457', 3456), false);
+  });
+
+  it('defaults missing or rejected Origin to localhost', () => {
+    assert.equal(corsMod.getCorsOrigin(undefined, 3456), 'http://localhost:3456');
+    assert.equal(corsMod.getCorsOrigin('http://evil.com', 3456), 'http://localhost:3456');
+  });
+});
+

ccw/tests/csrf-manager.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Unit tests for CsrfTokenManager (ccw/dist/core/auth/csrf-manager.js).
+ *
+ * Notes:
+ * - Targets the runtime implementation shipped in `ccw/dist`.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+const csrfManagerUrl = new URL('../dist/core/auth/csrf-manager.js', import.meta.url).href;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+describe('CsrfTokenManager', async () => {
+  mod = await import(csrfManagerUrl);
+
+  it('generateToken produces a 64-character hex token', () => {
+    const manager = new mod.CsrfTokenManager({ cleanupIntervalMs: 0 });
+    const token = manager.generateToken('session-1');
+
+    assert.match(token, /^[a-f0-9]{64}$/);
+    manager.dispose();
+  });
+
+  it('validateToken accepts correct session token once', () => {
+    const manager = new mod.CsrfTokenManager({ cleanupIntervalMs: 0 });
+    const token = manager.generateToken('session-1');
+
+    assert.equal(manager.validateToken(token, 'session-1'), true);
+    assert.equal(manager.validateToken(token, 'session-1'), false);
+    manager.dispose();
+  });
+
+  it('validateToken rejects expired tokens', () => {
+    const manager = new mod.CsrfTokenManager({ tokenTtlMs: -1000, cleanupIntervalMs: 0 });
+    const token = manager.generateToken('session-1');
+
+    assert.equal(manager.validateToken(token, 'session-1'), false);
+    assert.equal(manager.getActiveTokenCount(), 0);
+    manager.dispose();
+  });
+
+  it('cleanupExpiredTokens removes expired entries', () => {
+    const manager = new mod.CsrfTokenManager({ tokenTtlMs: 10, cleanupIntervalMs: 0 });
+    manager.generateToken('session-1');
+
+    const removed = manager.cleanupExpiredTokens(Date.now() + 100);
+    assert.equal(removed, 1);
+    assert.equal(manager.getActiveTokenCount(), 0);
+    manager.dispose();
+  });
+
+  it('session association prevents cross-session token reuse', () => {
+    const manager = new mod.CsrfTokenManager({ cleanupIntervalMs: 0 });
+    const token = manager.generateToken('session-1');
+
+    assert.equal(manager.validateToken(token, 'session-2'), false);
+    assert.equal(manager.validateToken(token, 'session-1'), true);
+    manager.dispose();
+  });
+});
+

ccw/tests/csrf-middleware.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Unit tests for CSRF middleware (ccw/dist/core/auth/csrf-middleware.js)
+ */
+
+import { afterEach, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { PassThrough } from 'node:stream';
+
+type MockResponse = {
+  status: number | null;
+  headers: Record<string, unknown>;
+  body: string;
+  writeHead: (status: number, headers?: Record<string, string>) => void;
+  setHeader: (name: string, value: unknown) => void;
+  getHeader: (name: string) => unknown;
+  end: (body?: string) => void;
+};
+
+function createMockRes(): MockResponse {
+  const headers: Record<string, unknown> = {};
+  const response: MockResponse = {
+    status: null,
+    headers,
+    body: '',
+    writeHead: (status: number, nextHeaders?: Record<string, string>) => {
+      response.status = status;
+      if (nextHeaders) {
+        for (const [k, v] of Object.entries(nextHeaders)) {
+          headers[k.toLowerCase()] = v;
+        }
+      }
+    },
+    setHeader: (name: string, value: unknown) => {
+      headers[name.toLowerCase()] = value;
+    },
+    getHeader: (name: string) => headers[name.toLowerCase()],
+    end: (body?: string) => {
+      response.body = body ? String(body) : '';
+    },
+  };
+  return response;
+}
+
+const middlewareUrl = new URL('../dist/core/auth/csrf-middleware.js', import.meta.url);
+
+const managerUrl = new URL('../dist/core/auth/csrf-manager.js', import.meta.url);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let middleware: any;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let csrfManager: any;
+
+const ORIGINAL_ENV = { ...process.env };
+
+describe('csrf middleware', async () => {
+  middleware = await import(middlewareUrl.href);
+  csrfManager = await import(managerUrl.href);
+
+  afterEach(() => {
+    csrfManager.resetCsrfTokenManager();
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it('allows non-state-changing requests without tokens', async () => {
+    const req: any = { method: 'GET', headers: {} };
+    const res = createMockRes();
+
+    const ok = await middleware.csrfValidation({ pathname: '/api/health', req, res });
+    assert.equal(ok, true);
+    assert.equal(res.status, null);
+  });
+
+  it('rejects state-changing requests when tokens are missing', async () => {
+    const req = new PassThrough() as any;
+    req.method = 'POST';
+    req.headers = {};
+    const res = createMockRes();
+
+    const promise = middleware.csrfValidation({ pathname: '/api/remove-recent-path', req, res });
+    queueMicrotask(() => {
+      req.end();
+    });
+    const ok = await promise;
+    assert.equal(ok, false);
+    assert.equal(res.status, 403);
+    assert.ok(res.body.includes('CSRF validation failed'));
+  });
+
+  it('accepts valid CSRF token from cookies and rotates token', async () => {
+    const sessionId = 'session-1';
+    const manager = csrfManager.getCsrfTokenManager({ cleanupIntervalMs: 0 });
+    const token = manager.generateToken(sessionId);
+
+    const req: any = { method: 'POST', headers: { cookie: `ccw_session_id=${sessionId}; XSRF-TOKEN=${token}` } };
+    const res = createMockRes();
+
+    const ok = await middleware.csrfValidation({ pathname: '/api/remove-recent-path', req, res });
+    assert.equal(ok, true);
+
+    const rotated = res.headers['x-csrf-token'];
+    assert.ok(typeof rotated === 'string');
+    assert.notEqual(rotated, token);
+    assert.match(rotated, /^[a-f0-9]{64}$/);
+
+    const setCookie = res.headers['set-cookie'];
+    const cookieString = Array.isArray(setCookie) ? setCookie.join('\n') : String(setCookie ?? '');
+    assert.ok(cookieString.includes('XSRF-TOKEN='));
+    assert.ok(cookieString.includes(String(rotated)));
+  });
+
+  it('rejects token reuse', async () => {
+    const sessionId = 'session-1';
+    const manager = csrfManager.getCsrfTokenManager({ cleanupIntervalMs: 0 });
+    const token = manager.generateToken(sessionId);
+
+    const req1: any = { method: 'POST', headers: { cookie: `ccw_session_id=${sessionId}; XSRF-TOKEN=${token}` } };
+    const res1 = createMockRes();
+    assert.equal(await middleware.csrfValidation({ pathname: '/api/remove-recent-path', req: req1, res: res1 }), true);
+
+    const req2: any = { method: 'POST', headers: { cookie: `ccw_session_id=${sessionId}; XSRF-TOKEN=${token}` } };
+    const res2 = createMockRes();
+    assert.equal(await middleware.csrfValidation({ pathname: '/api/remove-recent-path', req: req2, res: res2 }), false);
+    assert.equal(res2.status, 403);
+  });
+
+  it('accepts valid CSRF token from JSON body when cookies are absent', async () => {
+    const sessionId = 'session-1';
+    const manager = csrfManager.getCsrfTokenManager({ cleanupIntervalMs: 0 });
+    const token = manager.generateToken(sessionId);
+
+    const req = new PassThrough() as any;
+    req.method = 'POST';
+    req.headers = { cookie: `ccw_session_id=${sessionId}` };
+
+    const res = createMockRes();
+    const promise = middleware.csrfValidation({ pathname: '/api/remove-recent-path', req, res });
+    queueMicrotask(() => {
+      req.end(JSON.stringify({ csrfToken: token }));
+    });
+
+    const ok = await promise;
+    assert.equal(ok, true);
+  });
+
+  it('skips CSRF validation when CCW_DISABLE_CSRF is enabled', async () => {
+    process.env.CCW_DISABLE_CSRF = 'true';
+    const req: any = { method: 'POST', headers: {} };
+    const res = createMockRes();
+
+    const ok = await middleware.csrfValidation({ pathname: '/api/remove-recent-path', req, res });
+    assert.equal(ok, true);
+  });
+});

ccw/tests/files-routes.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Integration tests for files routes path validation.
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Focuses on access control for user-provided file paths.
+ */
+
+import { after, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const PROJECT_ROOT = mkdtempSync(join(tmpdir(), 'ccw-files-routes-project-'));
+const OUTSIDE_ROOT = mkdtempSync(join(tmpdir(), 'ccw-files-routes-outside-'));
+
+const filesRoutesUrl = new URL('../dist/core/routes/files-routes.js', import.meta.url);
+filesRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+type JsonResponse = { status: number; json: any; text: string };
+
+async function requestJson(baseUrl: string, method: string, path: string, body?: unknown): Promise<JsonResponse> {
+  const url = new URL(path, baseUrl);
+  const payload = body === undefined ? null : Buffer.from(JSON.stringify(body), 'utf8');
+
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      url,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          ...(payload ? { 'Content-Type': 'application/json', 'Content-Length': String(payload.length) } : {}),
+        },
+      },
+      (res) => {
+        let responseBody = '';
+        res.on('data', (chunk) => {
+          responseBody += chunk.toString();
+        });
+        res.on('end', () => {
+          let json: any = null;
+          try {
+            json = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            json = null;
+          }
+          resolve({ status: res.statusCode || 0, json, text: responseBody });
+        });
+      },
+    );
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+function handlePostRequest(req: http.IncomingMessage, res: http.ServerResponse, handler: (body: unknown) => Promise<any>): void {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', async () => {
+    try {
+      const parsed = body ? JSON.parse(body) : {};
+      const result = await handler(parsed);
+
+      if (result?.error) {
+        res.writeHead(result.status || 500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error }));
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+}
+
+async function createServer(initialPath: string): Promise<{ server: http.Server; baseUrl: string }> {
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const pathname = url.pathname;
+
+    const ctx = {
+      pathname,
+      url,
+      req,
+      res,
+      initialPath,
+      handlePostRequest,
+      broadcastToClients() {},
+    };
+
+    try {
+      const handled = await mod.handleFilesRoutes(ctx);
+      if (!handled) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not Found' }));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+
+  await new Promise<void>((resolve) => server.listen(0, () => resolve()));
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : 0;
+  return { server, baseUrl: `http://127.0.0.1:${port}` };
+}
+
+describe('files routes path validation', async () => {
+  before(async () => {
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'error', () => {});
+    mod = await import(filesRoutesUrl.href);
+  });
+
+  after(() => {
+    mock.restoreAll();
+    rmSync(PROJECT_ROOT, { recursive: true, force: true });
+    rmSync(OUTSIDE_ROOT, { recursive: true, force: true });
+  });
+
+  it('GET /api/files rejects paths outside initialPath', async () => {
+    const { server, baseUrl } = await createServer(PROJECT_ROOT);
+    try {
+      const res = await requestJson(baseUrl, 'GET', `/api/files?path=${encodeURIComponent(OUTSIDE_ROOT)}`);
+      assert.equal(res.status, 403);
+      assert.equal(res.json.error, 'Access denied');
+      assert.equal(Array.isArray(res.json.files), true);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it('GET /api/file-content rejects paths outside initialPath', async () => {
+    const { server, baseUrl } = await createServer(PROJECT_ROOT);
+    try {
+      const res = await requestJson(baseUrl, 'GET', `/api/file-content?path=${encodeURIComponent(join(OUTSIDE_ROOT, 'secret.txt'))}`);
+      assert.equal(res.status, 403);
+      assert.equal(res.json.error, 'Access denied');
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it('POST /api/update-claude-md rejects paths outside initialPath', async () => {
+    const { server, baseUrl } = await createServer(PROJECT_ROOT);
+    try {
+      const res = await requestJson(baseUrl, 'POST', '/api/update-claude-md', { path: OUTSIDE_ROOT, tool: 'gemini', strategy: 'single-layer' });
+      assert.equal(res.status, 403);
+      assert.equal(res.json.error, 'Access denied');
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+});
+

ccw/tests/graph-routes.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Integration tests for graph routes path validation.
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Focuses on path validation behavior (rejects paths outside initialPath).
+ */
+
+import { after, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const PROJECT_ROOT = mkdtempSync(join(tmpdir(), 'ccw-graph-routes-project-'));
+const OUTSIDE_ROOT = mkdtempSync(join(tmpdir(), 'ccw-graph-routes-outside-'));
+
+const graphRoutesUrl = new URL('../dist/core/routes/graph-routes.js', import.meta.url);
+graphRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+type JsonResponse = { status: number; json: any; text: string };
+
+async function requestJson(baseUrl: string, method: string, path: string, body?: unknown): Promise<JsonResponse> {
+  const url = new URL(path, baseUrl);
+  const payload = body === undefined ? null : Buffer.from(JSON.stringify(body), 'utf8');
+
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      url,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          ...(payload ? { 'Content-Type': 'application/json', 'Content-Length': String(payload.length) } : {}),
+        },
+      },
+      (res) => {
+        let responseBody = '';
+        res.on('data', (chunk) => {
+          responseBody += chunk.toString();
+        });
+        res.on('end', () => {
+          let json: any = null;
+          try {
+            json = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            json = null;
+          }
+          resolve({ status: res.statusCode || 0, json, text: responseBody });
+        });
+      },
+    );
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+function handlePostRequest(req: http.IncomingMessage, res: http.ServerResponse, handler: (body: unknown) => Promise<any>): void {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', async () => {
+    try {
+      const parsed = body ? JSON.parse(body) : {};
+      const result = await handler(parsed);
+
+      if (result?.error) {
+        res.writeHead(result.status || 500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error }));
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+}
+
+async function createServer(initialPath: string): Promise<{ server: http.Server; baseUrl: string }> {
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const pathname = url.pathname;
+
+    const ctx = {
+      pathname,
+      url,
+      req,
+      res,
+      initialPath,
+      handlePostRequest,
+      broadcastToClients() {},
+    };
+
+    try {
+      const handled = await mod.handleGraphRoutes(ctx);
+      if (!handled) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not Found' }));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+
+  await new Promise<void>((resolve) => server.listen(0, () => resolve()));
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : 0;
+  return { server, baseUrl: `http://127.0.0.1:${port}` };
+}
+
+describe('graph routes path validation', async () => {
+  before(async () => {
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'error', () => {});
+    mod = await import(graphRoutesUrl.href);
+  });
+
+  after(() => {
+    mock.restoreAll();
+    rmSync(PROJECT_ROOT, { recursive: true, force: true });
+    rmSync(OUTSIDE_ROOT, { recursive: true, force: true });
+  });
+
+  it('GET /api/graph/nodes rejects paths outside initialPath', async () => {
+    const { server, baseUrl } = await createServer(PROJECT_ROOT);
+    try {
+      const res = await requestJson(baseUrl, 'GET', `/api/graph/nodes?path=${encodeURIComponent(OUTSIDE_ROOT)}`);
+      assert.equal(res.status, 403);
+      assert.equal(res.json.error, 'Access denied');
+      assert.equal(Array.isArray(res.json.nodes), true);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+});
+

ccw/tests/integration/ccw-routes.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Integration tests for CCW routes (installations/tools).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Exercises real HTTP request/response flow via a minimal test server.
+ */
+
+import { after, before, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+
+const ccwRoutesUrl = new URL('../../dist/core/routes/ccw-routes.js', import.meta.url);
+ccwRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+type JsonResponse = { status: number; json: any; text: string };
+
+async function requestJson(baseUrl: string, method: string, path: string): Promise<JsonResponse> {
+  const url = new URL(path, baseUrl);
+
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      url,
+      { method, headers: { Accept: 'application/json' } },
+      (res) => {
+        let body = '';
+        res.on('data', (chunk) => {
+          body += chunk.toString();
+        });
+        res.on('end', () => {
+          let json: any = null;
+          try {
+            json = body ? JSON.parse(body) : null;
+          } catch {
+            json = null;
+          }
+          resolve({ status: res.statusCode || 0, json, text: body });
+        });
+      },
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function handlePostRequest(req: http.IncomingMessage, res: http.ServerResponse, handler: (body: unknown) => Promise<any>): void {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', async () => {
+    try {
+      const parsed = body ? JSON.parse(body) : {};
+      const result = await handler(parsed);
+
+      if (result?.error) {
+        res.writeHead(result.status || 500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error }));
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+}
+
+describe('ccw routes integration', async () => {
+  let server: http.Server | null = null;
+  let baseUrl = '';
+
+  before(async () => {
+    mod = await import(ccwRoutesUrl.href);
+
+    server = http.createServer(async (req, res) => {
+      const url = new URL(req.url || '/', 'http://localhost');
+      const pathname = url.pathname;
+
+      const ctx = {
+        pathname,
+        url,
+        req,
+        res,
+        initialPath: process.cwd(),
+        handlePostRequest,
+        broadcastToClients() {},
+      };
+
+      try {
+        const handled = await mod.handleCcwRoutes(ctx);
+        if (!handled) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Not Found' }));
+        }
+      } catch (err: any) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err?.message || String(err) }));
+      }
+    });
+
+    await new Promise<void>((resolve) => {
+      server!.listen(0, () => resolve());
+    });
+
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+    baseUrl = `http://127.0.0.1:${port}`;
+  });
+
+  after(async () => {
+    if (!server) return;
+    await new Promise<void>((resolve) => server!.close(() => resolve()));
+  });
+
+  it('GET /api/ccw/installations returns installation manifests', async () => {
+    const res = await requestJson(baseUrl, 'GET', '/api/ccw/installations');
+    assert.equal(res.status, 200);
+    assert.ok(res.json);
+    assert.equal(Array.isArray(res.json.installations), true);
+  });
+
+  it('GET /api/ccw/tools returns available tools', async () => {
+    const res = await requestJson(baseUrl, 'GET', '/api/ccw/tools');
+    assert.equal(res.status, 200);
+    assert.ok(res.json);
+    assert.equal(Array.isArray(res.json.tools), true);
+  });
+
+  it('GET /api/ccw/upgrade returns 404 (POST-only endpoint)', async () => {
+    const res = await requestJson(baseUrl, 'GET', '/api/ccw/upgrade');
+    assert.equal(res.status, 404);
+    assert.ok(res.json?.error);
+  });
+
+  it('returns 404 for unknown /api/ccw/* routes', async () => {
+    const res = await requestJson(baseUrl, 'GET', '/api/ccw/nope');
+    assert.equal(res.status, 404);
+    assert.ok(res.json?.error);
+  });
+});
+

ccw/tests/integration/claude-routes.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Integration tests for CLAUDE.md routes (scan + CRUD).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Uses temporary HOME/USERPROFILE to isolate user-level files.
+ * - Uses a temporary project root as initialPath for project/module operations.
+ */
+
+import { after, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const claudeRoutesUrl = new URL('../../dist/core/routes/claude-routes.js', import.meta.url);
+claudeRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+const originalEnv = {
+  HOME: process.env.HOME,
+  USERPROFILE: process.env.USERPROFILE,
+  HOMEDRIVE: process.env.HOMEDRIVE,
+  HOMEPATH: process.env.HOMEPATH,
+};
+
+type JsonResponse = { status: number; json: any; text: string };
+
+async function requestJson(
+  baseUrl: string,
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<JsonResponse> {
+  const url = new URL(path, baseUrl);
+  const payload = body === undefined ? null : Buffer.from(JSON.stringify(body), 'utf8');
+
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      url,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          ...(payload
+            ? { 'Content-Type': 'application/json', 'Content-Length': String(payload.length) }
+            : {}),
+        },
+      },
+      (res) => {
+        let responseBody = '';
+        res.on('data', (chunk) => {
+          responseBody += chunk.toString();
+        });
+        res.on('end', () => {
+          let json: any = null;
+          try {
+            json = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            json = null;
+          }
+          resolve({ status: res.statusCode || 0, json, text: responseBody });
+        });
+      },
+    );
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+function handlePostRequest(req: http.IncomingMessage, res: http.ServerResponse, handler: (body: unknown) => Promise<any>): void {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', async () => {
+    try {
+      const parsed = body ? JSON.parse(body) : {};
+      const result = await handler(parsed);
+
+      if (result?.error) {
+        res.writeHead(result.status || 500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error }));
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+}
+
+describe('claude routes integration', async () => {
+  let server: http.Server | null = null;
+  let baseUrl = '';
+  let homeDir = '';
+  let projectRoot = '';
+
+  before(async () => {
+    homeDir = mkdtempSync(join(tmpdir(), 'ccw-claude-home-'));
+    projectRoot = mkdtempSync(join(tmpdir(), 'ccw-claude-project-'));
+
+    process.env.HOME = homeDir;
+    process.env.USERPROFILE = homeDir;
+    process.env.HOMEDRIVE = undefined;
+    process.env.HOMEPATH = undefined;
+
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'error', () => {});
+
+    mod = await import(claudeRoutesUrl.href);
+
+    server = http.createServer(async (req, res) => {
+      const url = new URL(req.url || '/', 'http://localhost');
+      const pathname = url.pathname;
+
+      const ctx = {
+        pathname,
+        url,
+        req,
+        res,
+        initialPath: projectRoot,
+        handlePostRequest,
+        broadcastToClients() {},
+      };
+
+      try {
+        const handled = await mod.handleClaudeRoutes(ctx);
+        if (!handled) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Not Found' }));
+        }
+      } catch (err: any) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err?.message || String(err) }));
+      }
+    });
+
+    await new Promise<void>((resolve) => server!.listen(0, () => resolve()));
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+    baseUrl = `http://127.0.0.1:${port}`;
+  });
+
+  after(async () => {
+    mock.restoreAll();
+    process.env.HOME = originalEnv.HOME;
+    process.env.USERPROFILE = originalEnv.USERPROFILE;
+    process.env.HOMEDRIVE = originalEnv.HOMEDRIVE;
+    process.env.HOMEPATH = originalEnv.HOMEPATH;
+
+    if (server) {
+      await new Promise<void>((resolve) => server!.close(() => resolve()));
+      server = null;
+    }
+
+    if (projectRoot) {
+      rmSync(projectRoot, { recursive: true, force: true });
+      projectRoot = '';
+    }
+
+    if (homeDir) {
+      rmSync(homeDir, { recursive: true, force: true });
+      homeDir = '';
+    }
+  });
+
+  it('POST /api/memory/claude/create creates a project-level CLAUDE.md', async () => {
+    const res = await requestJson(baseUrl, 'POST', '/api/memory/claude/create', { level: 'project', template: 'minimal' });
+    assert.equal(res.status, 200);
+    assert.equal(res.json?.success, true);
+    assert.ok(typeof res.json.path === 'string' && res.json.path.endsWith('CLAUDE.md'));
+    assert.equal(existsSync(res.json.path), true);
+  });
+
+  it('GET /api/memory/claude/file parses frontmatter for project CLAUDE.md', async () => {
+    const claudePath = join(projectRoot, '.claude', 'CLAUDE.md');
+    mkdirSync(join(projectRoot, '.claude'), { recursive: true });
+    writeFileSync(
+      claudePath,
+      ['---', 'paths: [src, docs]', '---', '', '# Project Rules', '', 'ok'].join('\n'),
+      'utf8',
+    );
+
+    const res = await requestJson(baseUrl, 'GET', `/api/memory/claude/file?path=${encodeURIComponent(claudePath)}`);
+    assert.equal(res.status, 200);
+    assert.equal(res.json.level, 'project');
+    assert.deepEqual(res.json.frontmatter?.paths, ['src', 'docs']);
+    assert.match(res.json.content, /# Project Rules/);
+    assert.equal(String(res.json.content).includes('paths:'), false);
+  });
+
+  it('POST /api/memory/claude/file saves updated content', async () => {
+    const claudePath = join(projectRoot, '.claude', 'CLAUDE.md');
+    mkdirSync(join(projectRoot, '.claude'), { recursive: true });
+    writeFileSync(claudePath, 'before\n', 'utf8');
+
+    const res = await requestJson(baseUrl, 'POST', '/api/memory/claude/file', { path: claudePath, content: 'after\n' });
+    assert.equal(res.status, 200);
+    assert.equal(res.json?.success, true);
+    assert.equal(readFileSync(claudePath, 'utf8'), 'after\n');
+  });
+
+  it('GET /api/memory/claude/scan separates user/project/module levels', async () => {
+    const userClaudePath = join(homeDir, '.claude', 'CLAUDE.md');
+    mkdirSync(join(homeDir, '.claude'), { recursive: true });
+    writeFileSync(userClaudePath, '# User CLAUDE\n', 'utf8');
+
+    const projectClaudePath = join(projectRoot, '.claude', 'CLAUDE.md');
+    mkdirSync(join(projectRoot, '.claude'), { recursive: true });
+    writeFileSync(projectClaudePath, ['---', 'paths: [src]', '---', '', '# Project CLAUDE'].join('\n'), 'utf8');
+
+    const moduleDir = join(projectRoot, 'module-a');
+    mkdirSync(moduleDir, { recursive: true });
+    writeFileSync(join(moduleDir, 'CLAUDE.md'), '# Module CLAUDE\n', 'utf8');
+
+    const res = await requestJson(baseUrl, 'GET', `/api/memory/claude/scan?path=${encodeURIComponent(projectRoot)}`);
+    assert.equal(res.status, 200);
+    assert.equal(res.json.user?.main?.level, 'user');
+    assert.ok(String(res.json.user.main.path).includes(homeDir));
+
+    assert.equal(res.json.project?.main?.level, 'project');
+    assert.ok(String(res.json.project.main.path).includes(projectRoot));
+    assert.deepEqual(res.json.project.main.frontmatter?.paths, ['src']);
+    assert.equal(String(res.json.project.main.content).includes('paths:'), false);
+
+    assert.equal(Array.isArray(res.json.modules), true);
+    assert.ok(res.json.modules.length >= 1);
+    const moduleFile = res.json.modules.find((m: any) => String(m.path).includes('module-a'));
+    assert.ok(moduleFile);
+    assert.equal(moduleFile.level, 'module');
+    assert.equal(moduleFile.parentDirectory, 'module-a');
+  });
+
+  it('DELETE /api/memory/claude/file requires confirm=true', async () => {
+    const moduleDir = join(projectRoot, 'module-del');
+    const moduleFilePath = join(moduleDir, 'CLAUDE.md');
+    mkdirSync(moduleDir, { recursive: true });
+    writeFileSync(moduleFilePath, '# To delete\n', 'utf8');
+
+    const res = await requestJson(baseUrl, 'DELETE', `/api/memory/claude/file?path=${encodeURIComponent(moduleFilePath)}`);
+    assert.equal(res.status, 400);
+    assert.equal(res.json?.error, 'Confirmation required');
+    assert.equal(existsSync(moduleFilePath), true);
+  });
+
+  it('DELETE /api/memory/claude/file deletes the file and creates a backup', async () => {
+    const moduleDir = join(projectRoot, 'module-del-ok');
+    const moduleFilePath = join(moduleDir, 'CLAUDE.md');
+    mkdirSync(moduleDir, { recursive: true });
+    writeFileSync(moduleFilePath, '# Bye\n', 'utf8');
+
+    const res = await requestJson(
+      baseUrl,
+      'DELETE',
+      `/api/memory/claude/file?path=${encodeURIComponent(moduleFilePath)}&confirm=true`,
+    );
+    assert.equal(res.status, 200);
+    assert.equal(res.json?.success, true);
+    assert.equal(existsSync(moduleFilePath), false);
+
+    const backups = readdirSync(moduleDir).filter((name) => name.startsWith('CLAUDE.md.deleted-'));
+    assert.equal(backups.length, 1);
+  });
+});
+

ccw/tests/integration/files-routes.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Integration tests for files routes (directory listing + file preview).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Uses a temporary project directory as the allowed root (initialPath).
+ */
+
+import { after, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const filesRoutesUrl = new URL('../../dist/core/routes/files-routes.js', import.meta.url);
+filesRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+type JsonResponse = { status: number; json: any; text: string };
+
+async function requestJson(baseUrl: string, method: string, path: string): Promise<JsonResponse> {
+  const url = new URL(path, baseUrl);
+
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      url,
+      { method, headers: { Accept: 'application/json' } },
+      (res) => {
+        let body = '';
+        res.on('data', (chunk) => {
+          body += chunk.toString();
+        });
+        res.on('end', () => {
+          let json: any = null;
+          try {
+            json = body ? JSON.parse(body) : null;
+          } catch {
+            json = null;
+          }
+          resolve({ status: res.statusCode || 0, json, text: body });
+        });
+      },
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function handlePostRequest(req: http.IncomingMessage, res: http.ServerResponse, handler: (body: unknown) => Promise<any>): void {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', async () => {
+    try {
+      const parsed = body ? JSON.parse(body) : {};
+      const result = await handler(parsed);
+
+      if (result?.error) {
+        res.writeHead(result.status || 500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error }));
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+}
+
+describe('files routes integration', async () => {
+  let server: http.Server | null = null;
+  let baseUrl = '';
+  let projectRoot = '';
+
+  before(async () => {
+    projectRoot = mkdtempSync(join(tmpdir(), 'ccw-files-routes-project-'));
+
+    mkdirSync(join(projectRoot, 'subdir'), { recursive: true });
+    mkdirSync(join(projectRoot, '.claude'), { recursive: true });
+    mkdirSync(join(projectRoot, '.workflow'), { recursive: true });
+    mkdirSync(join(projectRoot, 'node_modules'), { recursive: true });
+    mkdirSync(join(projectRoot, 'ignored-dir'), { recursive: true });
+
+    writeFileSync(join(projectRoot, 'visible.txt'), 'ok\n', 'utf8');
+    writeFileSync(join(projectRoot, 'ignored.txt'), 'nope\n', 'utf8');
+    writeFileSync(join(projectRoot, '.secret'), 'hidden\n', 'utf8');
+    writeFileSync(join(projectRoot, 'readme.md'), '# Hello\n', 'utf8');
+    writeFileSync(join(projectRoot, '.gitignore'), ['ignored.txt', 'ignored-dir/'].join('\n') + '\n', 'utf8');
+
+    mock.method(console, 'error', () => {});
+    mod = await import(filesRoutesUrl.href);
+
+    server = http.createServer(async (req, res) => {
+      const url = new URL(req.url || '/', 'http://localhost');
+      const pathname = url.pathname;
+
+      const ctx = {
+        pathname,
+        url,
+        req,
+        res,
+        initialPath: projectRoot,
+        handlePostRequest,
+      };
+
+      try {
+        const handled = await mod.handleFilesRoutes(ctx);
+        if (!handled) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Not Found' }));
+        }
+      } catch (err: any) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err?.message || String(err) }));
+      }
+    });
+
+    await new Promise<void>((resolve) => {
+      server!.listen(0, () => resolve());
+    });
+
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+    baseUrl = `http://127.0.0.1:${port}`;
+  });
+
+  after(async () => {
+    mock.restoreAll();
+    if (server) {
+      await new Promise<void>((resolve) => server!.close(() => resolve()));
+      server = null;
+    }
+    if (projectRoot) {
+      rmSync(projectRoot, { recursive: true, force: true });
+      projectRoot = '';
+    }
+  });
+
+  it('GET /api/files lists entries and respects gitignore/exclude rules', async () => {
+    const res = await requestJson(baseUrl, 'GET', `/api/files?path=${encodeURIComponent(projectRoot)}`);
+    assert.equal(res.status, 200);
+    assert.ok(res.json);
+    assert.equal(Array.isArray(res.json.files), true);
+
+    const names = res.json.files.map((f: any) => f.name);
+    assert.ok(names.includes('subdir'));
+    assert.ok(names.includes('visible.txt'));
+    assert.ok(names.includes('.claude'));
+    assert.ok(names.includes('.workflow'));
+
+    // Hidden dotfiles (except .claude/.workflow) are excluded.
+    assert.equal(names.includes('.secret'), false);
+    // Common excluded dirs are always removed.
+    assert.equal(names.includes('node_modules'), false);
+    // .gitignore patterns should be enforced.
+    assert.equal(names.includes('ignored.txt'), false);
+    assert.equal(names.includes('ignored-dir'), false);
+    assert.equal(Array.isArray(res.json.gitignorePatterns), true);
+    assert.ok(res.json.gitignorePatterns.includes('ignored.txt'));
+  });
+
+  it('GET /api/files returns 400 for non-existent path', async () => {
+    const missing = join(projectRoot, 'missing-dir');
+    const res = await requestJson(baseUrl, 'GET', `/api/files?path=${encodeURIComponent(missing)}`);
+    assert.equal(res.status, 400);
+    assert.equal(res.json?.error, 'Invalid path');
+    assert.equal(Array.isArray(res.json?.files), true);
+    assert.equal(res.json.files.length, 0);
+  });
+
+  it('GET /api/files blocks traversal outside initialPath', async () => {
+    const outside = join(projectRoot, '..');
+    const res = await requestJson(baseUrl, 'GET', `/api/files?path=${encodeURIComponent(outside)}`);
+    assert.equal(res.status, 403);
+    assert.equal(res.json?.error, 'Access denied');
+  });
+
+  it('GET /api/file-content returns preview content for files', async () => {
+    const target = join(projectRoot, 'readme.md');
+    const res = await requestJson(baseUrl, 'GET', `/api/file-content?path=${encodeURIComponent(target)}`);
+    assert.equal(res.status, 200);
+    assert.ok(res.json);
+    assert.equal(res.json.fileName, 'readme.md');
+    assert.equal(res.json.language, 'markdown');
+    assert.equal(res.json.isMarkdown, true);
+    assert.ok(String(res.json.content).includes('# Hello'));
+  });
+
+  it('GET /api/file-content returns 400 when path is missing', async () => {
+    const res = await requestJson(baseUrl, 'GET', '/api/file-content');
+    assert.equal(res.status, 400);
+    assert.ok(res.json?.error);
+  });
+
+  it('GET /api/file-content returns 404 when path is a directory', async () => {
+    const res = await requestJson(baseUrl, 'GET', `/api/file-content?path=${encodeURIComponent(projectRoot)}`);
+    assert.equal(res.status, 404);
+    assert.equal(res.json?.error, 'Cannot read directory');
+  });
+});

ccw/tests/integration/graph-routes.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Integration tests for graph routes (CodexLens graph API helpers).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Calls route handler directly (no HTTP server required).
+ */
+import { after, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const graphRoutesUrl = new URL('../../dist/core/routes/graph-routes.js', import.meta.url);
+graphRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+async function callGraph(
+  projectRoot: string,
+  path: string,
+): Promise<{ handled: boolean; status: number; json: any }> {
+  const url = new URL(path, 'http://localhost');
+  let status = 0;
+  let body = '';
+
+  const res = {
+    writeHead(code: number) {
+      status = code;
+    },
+    end(chunk?: any) {
+      body = chunk === undefined ? '' : String(chunk);
+    },
+  };
+
+  const handled = await mod.handleGraphRoutes({
+    pathname: url.pathname,
+    url,
+    req: { method: 'GET' },
+    res,
+    initialPath: projectRoot,
+  });
+
+  return { handled, status, json: body ? JSON.parse(body) : null };
+}
+
+describe('graph routes integration', async () => {
+  let projectRoot = '';
+
+  before(async () => {
+    projectRoot = mkdtempSync(join(tmpdir(), 'ccw-graph-project-'));
+    mock.method(console, 'error', () => {});
+    mod = await import(graphRoutesUrl.href);
+  });
+
+  after(() => {
+    mock.restoreAll();
+    if (projectRoot) {
+      rmSync(projectRoot, { recursive: true, force: true });
+      projectRoot = '';
+    }
+  });
+
+  it('GET /api/graph/search-process returns placeholder pipeline data', async () => {
+    const res = await callGraph(projectRoot, '/api/graph/search-process');
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(Array.isArray(res.json.stages), true);
+    assert.equal(res.json.stages.length, 5);
+    assert.equal(typeof res.json.message, 'string');
+  });
+
+  it('GET /api/graph/files returns empty lists when no index exists', async () => {
+    const res = await callGraph(projectRoot, `/api/graph/files?path=${encodeURIComponent(projectRoot)}`);
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(Array.isArray(res.json.files), true);
+    assert.equal(Array.isArray(res.json.modules), true);
+    assert.equal(res.json.files.length, 0);
+    assert.equal(res.json.modules.length, 0);
+  });
+
+  it('GET /api/graph/impact validates required symbol parameter', async () => {
+    const res = await callGraph(projectRoot, `/api/graph/impact?path=${encodeURIComponent(projectRoot)}`);
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 400);
+    assert.ok(String(res.json.error).includes('symbol'));
+    assert.equal(Array.isArray(res.json.directDependents), true);
+    assert.equal(Array.isArray(res.json.affectedFiles), true);
+  });
+});
+

ccw/tests/integration/help-routes.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Integration tests for help routes (command guide + CodexLens docs).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Avoids spinning up a real HTTP server; calls route handler directly.
+ * - Uses a temporary HOME/USERPROFILE to isolate ~/.claude/skills/command-guide/index data.
+ */
+
+import { after, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const helpRoutesUrl = new URL('../../dist/core/routes/help-routes.js', import.meta.url);
+helpRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+const originalEnv = {
+  HOME: process.env.HOME,
+  USERPROFILE: process.env.USERPROFILE,
+  HOMEDRIVE: process.env.HOMEDRIVE,
+  HOMEPATH: process.env.HOMEPATH,
+};
+
+async function callRoute(path: string): Promise<{ handled: boolean; status: number; json: any; text: string }> {
+  const url = new URL(path, 'http://localhost');
+  let status = 0;
+  let text = '';
+
+  const res = {
+    writeHead(code: number) {
+      status = code;
+    },
+    end(chunk?: any) {
+      text = chunk === undefined ? '' : String(chunk);
+    },
+  };
+
+  const ctx = {
+    pathname: url.pathname,
+    url,
+    req: { method: 'GET' },
+    res,
+  };
+
+  const handled = await mod.handleHelpRoutes(ctx);
+
+  let json: any = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+
+  return { handled, status, json, text };
+}
+
+describe('help routes integration', async () => {
+  let homeDir = '';
+
+  before(async () => {
+    homeDir = mkdtempSync(join(tmpdir(), 'ccw-help-home-'));
+    process.env.HOME = homeDir;
+    process.env.USERPROFILE = homeDir;
+    process.env.HOMEDRIVE = undefined;
+    process.env.HOMEPATH = undefined;
+
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'warn', () => {});
+    mock.method(console, 'error', () => {});
+
+    const indexDir = join(homeDir, '.claude', 'skills', 'command-guide', 'index');
+    mkdirSync(indexDir, { recursive: true });
+
+    writeFileSync(
+      join(indexDir, 'all-commands.json'),
+      JSON.stringify(
+        [
+          { name: 'Issue Next', command: 'ccw issue next', description: 'Fetch next item', category: 'issue', subcategory: 'queue' },
+          { name: 'Serve', command: 'ccw serve', description: 'Start dashboard server', category: 'core' },
+        ],
+        null,
+        2,
+      ),
+      'utf8',
+    );
+
+    writeFileSync(
+      join(indexDir, 'command-relationships.json'),
+      JSON.stringify({ workflows: [{ name: 'Issue Queue', commands: ['ccw issue next', 'ccw issue done'] }] }, null, 2),
+      'utf8',
+    );
+
+    writeFileSync(
+      join(indexDir, 'by-category.json'),
+      JSON.stringify({ issue: ['ccw issue next'], core: ['ccw serve'] }, null, 2),
+      'utf8',
+    );
+
+    mod = await import(helpRoutesUrl.href);
+  });
+
+  after(() => {
+    mock.restoreAll();
+    process.env.HOME = originalEnv.HOME;
+    process.env.USERPROFILE = originalEnv.USERPROFILE;
+    process.env.HOMEDRIVE = originalEnv.HOMEDRIVE;
+    process.env.HOMEPATH = originalEnv.HOMEPATH;
+
+    const activeHandles: any[] = (process as any)._getActiveHandles?.() || [];
+    for (const handle of activeHandles) {
+      if (handle?.constructor?.name === 'FSWatcher' && typeof handle.close === 'function') {
+        try {
+          handle.close();
+        } catch {
+          // ignore
+        }
+      }
+    }
+
+    if (homeDir) {
+      rmSync(homeDir, { recursive: true, force: true });
+      homeDir = '';
+    }
+  });
+
+  it('GET /api/help/commands returns commands and grouped categories', async () => {
+    const res = await callRoute('/api/help/commands');
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(Array.isArray(res.json.commands), true);
+    assert.equal(res.json.total, 2);
+    assert.equal(typeof res.json.grouped, 'object');
+    assert.ok(res.json.grouped.issue);
+  });
+
+  it('GET /api/help/commands?q filters commands by search query', async () => {
+    const res = await callRoute('/api/help/commands?q=issue');
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(res.json.total, 1);
+    assert.equal(res.json.commands[0].command, 'ccw issue next');
+  });
+
+  it('GET /api/help/workflows returns workflow relationships data', async () => {
+    const res = await callRoute('/api/help/workflows');
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(Array.isArray(res.json.workflows), true);
+    assert.equal(res.json.workflows[0].name, 'Issue Queue');
+  });
+
+  it('GET /api/help/commands/by-category returns category index data', async () => {
+    const res = await callRoute('/api/help/commands/by-category');
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(Array.isArray(res.json.issue), true);
+    assert.equal(res.json.issue[0], 'ccw issue next');
+  });
+
+  it('GET /api/help/codexlens returns CodexLens quick start content', async () => {
+    const res = await callRoute('/api/help/codexlens');
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(res.json.title, 'CodexLens Quick Start');
+    assert.equal(Array.isArray(res.json.sections), true);
+    assert.ok(res.json.sections.length > 0);
+  });
+});
+

ccw/tests/integration/hooks-routes.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Integration tests for hooks routes (hooks configuration CRUD).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Uses temporary HOME/USERPROFILE for global settings isolation.
+ * - Calls route handler directly (no HTTP server required).
+ */
+
+import { after, before, beforeEach, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const hooksRoutesUrl = new URL('../../dist/core/routes/hooks-routes.js', import.meta.url);
+hooksRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+const originalEnv = {
+  HOME: process.env.HOME,
+  USERPROFILE: process.env.USERPROFILE,
+  HOMEDRIVE: process.env.HOMEDRIVE,
+  HOMEPATH: process.env.HOMEPATH,
+};
+
+async function callHooks(
+  initialPath: string,
+  method: string,
+  pathname: string,
+  body?: any,
+): Promise<{ handled: boolean; status: number; json: any }> {
+  const url = new URL(pathname, 'http://localhost');
+  let status = 0;
+  let text = '';
+
+  const res = {
+    writeHead(code: number) {
+      status = code;
+    },
+    end(chunk?: any) {
+      text = chunk === undefined ? '' : String(chunk);
+    },
+  };
+
+  const handlePostRequest = async (_req: any, _res: any, handler: (parsed: any) => Promise<any>) => {
+    const result = await handler(body ?? {});
+    if (result && typeof result === 'object' && typeof result.error === 'string' && result.error.length > 0) {
+      res.writeHead(typeof result.status === 'number' ? result.status : 500);
+      res.end(JSON.stringify({ error: result.error }));
+      return;
+    }
+    res.writeHead(200);
+    res.end(JSON.stringify(result));
+  };
+
+  const handled = await mod.handleHooksRoutes({
+    pathname: url.pathname,
+    url,
+    req: { method },
+    res,
+    initialPath,
+    handlePostRequest,
+    broadcastToClients() {},
+    extractSessionIdFromPath() {
+      return null;
+    },
+  });
+
+  return { handled, status, json: text ? JSON.parse(text) : null };
+}
+
+describe('hooks routes integration', async () => {
+  let homeDir = '';
+  let projectRoot = '';
+
+  before(async () => {
+    homeDir = mkdtempSync(join(tmpdir(), 'ccw-hooks-home-'));
+    projectRoot = mkdtempSync(join(tmpdir(), 'ccw-hooks-project-'));
+
+    process.env.HOME = homeDir;
+    process.env.USERPROFILE = homeDir;
+    process.env.HOMEDRIVE = undefined;
+    process.env.HOMEPATH = undefined;
+
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'warn', () => {});
+    mock.method(console, 'error', () => {});
+
+    mod = await import(hooksRoutesUrl.href);
+  });
+
+  beforeEach(() => {
+    rmSync(join(homeDir, '.claude'), { recursive: true, force: true });
+    rmSync(join(projectRoot, '.claude'), { recursive: true, force: true });
+  });
+
+  after(() => {
+    mock.restoreAll();
+    process.env.HOME = originalEnv.HOME;
+    process.env.USERPROFILE = originalEnv.USERPROFILE;
+    process.env.HOMEDRIVE = originalEnv.HOMEDRIVE;
+    process.env.HOMEPATH = originalEnv.HOMEPATH;
+
+    rmSync(projectRoot, { recursive: true, force: true });
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  it('GET /api/hooks returns global and project hook configs', async () => {
+    const res = await callHooks(projectRoot, 'GET', '/api/hooks');
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.ok(res.json);
+    assert.ok(res.json.global);
+    assert.ok(res.json.project);
+    assert.deepEqual(res.json.global.hooks, {});
+    assert.deepEqual(res.json.project.hooks, {});
+  });
+
+  it('POST /api/hooks saves a global hook and GET reflects it', async () => {
+    const save = await callHooks(projectRoot, 'POST', '/api/hooks', {
+      scope: 'global',
+      event: 'PreToolUse',
+      hookData: { command: 'echo hi' },
+    });
+    assert.equal(save.handled, true);
+    assert.equal(save.status, 200);
+    assert.equal(save.json.success, true);
+
+    const read = await callHooks(projectRoot, 'GET', '/api/hooks');
+    assert.equal(read.status, 200);
+    assert.equal(Array.isArray(read.json.global.hooks.PreToolUse), true);
+    assert.equal(read.json.global.hooks.PreToolUse.length, 1);
+    assert.equal(read.json.global.hooks.PreToolUse[0].command, 'echo hi');
+  });
+
+  it('DELETE /api/hooks removes a hook by index', async () => {
+    await callHooks(projectRoot, 'POST', '/api/hooks', {
+      scope: 'global',
+      event: 'PreToolUse',
+      hookData: { command: 'echo hi' },
+    });
+
+    const del = await callHooks(projectRoot, 'DELETE', '/api/hooks', {
+      scope: 'global',
+      event: 'PreToolUse',
+      hookIndex: 0,
+    });
+    assert.equal(del.status, 200);
+    assert.equal(del.json.success, true);
+
+    const read = await callHooks(projectRoot, 'GET', '/api/hooks');
+    assert.equal(read.status, 200);
+    assert.deepEqual(read.json.global.hooks, {});
+  });
+});
+

ccw/tests/integration/issue-routes.test.ts

@@ -0,0 +1,296 @@
+/**
+ * Integration tests for issue routes (issues + solutions + queue).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Uses a temporary project root to isolate `.workflow/issues` JSONL storage.
+ */
+
+import { after, before, beforeEach, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const issueRoutesUrl = new URL('../../dist/core/routes/issue-routes.js', import.meta.url);
+issueRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+type JsonResponse = { status: number; json: any; text: string };
+
+async function requestJson(
+  baseUrl: string,
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<JsonResponse> {
+  const url = new URL(path, baseUrl);
+  const payload = body === undefined ? null : Buffer.from(JSON.stringify(body), 'utf8');
+
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      url,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          ...(payload
+            ? { 'Content-Type': 'application/json', 'Content-Length': String(payload.length) }
+            : {}),
+        },
+      },
+      (res) => {
+        let responseBody = '';
+        res.on('data', (chunk) => {
+          responseBody += chunk.toString();
+        });
+        res.on('end', () => {
+          let json: any = null;
+          try {
+            json = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            json = null;
+          }
+          resolve({ status: res.statusCode || 0, json, text: responseBody });
+        });
+      },
+    );
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+function handlePostRequest(req: http.IncomingMessage, res: http.ServerResponse, handler: (body: any) => Promise<any>): void {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', async () => {
+    try {
+      const parsed = body ? JSON.parse(body) : {};
+      const result = await handler(parsed);
+
+      if (result?.error) {
+        res.writeHead(result.status || 500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error }));
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+}
+
+function readJsonl(path: string): any[] {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8')
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .map((line) => JSON.parse(line));
+}
+
+describe('issue routes integration', async () => {
+  let server: http.Server | null = null;
+  let baseUrl = '';
+  let projectRoot = '';
+
+  before(async () => {
+    projectRoot = mkdtempSync(join(tmpdir(), 'ccw-issue-routes-project-'));
+
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'error', () => {});
+
+    mod = await import(issueRoutesUrl.href);
+
+    server = http.createServer(async (req, res) => {
+      const url = new URL(req.url || '/', 'http://localhost');
+      const pathname = url.pathname;
+
+      const ctx = {
+        pathname,
+        url,
+        req,
+        res,
+        initialPath: projectRoot,
+        handlePostRequest,
+      };
+
+      try {
+        const handled = await mod.handleIssueRoutes(ctx);
+        if (!handled) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Not Found' }));
+        }
+      } catch (err: any) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err?.message || String(err) }));
+      }
+    });
+
+    await new Promise<void>((resolve) => server!.listen(0, () => resolve()));
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+    baseUrl = `http://127.0.0.1:${port}`;
+  });
+
+  beforeEach(() => {
+    rmSync(join(projectRoot, '.workflow'), { recursive: true, force: true });
+  });
+
+  after(async () => {
+    mock.restoreAll();
+    if (server) {
+      await new Promise<void>((resolve) => server!.close(() => resolve()));
+      server = null;
+    }
+    if (projectRoot) {
+      rmSync(projectRoot, { recursive: true, force: true });
+      projectRoot = '';
+    }
+  });
+
+  it('GET /api/issues returns empty issues list with metadata', async () => {
+    const res = await requestJson(baseUrl, 'GET', '/api/issues');
+    assert.equal(res.status, 200);
+    assert.ok(res.json);
+    assert.equal(Array.isArray(res.json.issues), true);
+    assert.equal(res.json.issues.length, 0);
+    assert.equal(res.json._metadata.storage, 'jsonl');
+  });
+
+  it('POST /api/issues creates a new issue and writes JSONL', async () => {
+    const issueId = 'ISS-IR-1';
+    const res = await requestJson(baseUrl, 'POST', '/api/issues', { id: issueId, title: 'Issue routes test' });
+    assert.equal(res.status, 200);
+    assert.equal(res.json?.success, true);
+    assert.equal(res.json.issue.id, issueId);
+
+    const issuesPath = join(projectRoot, '.workflow', 'issues', 'issues.jsonl');
+    const lines = readJsonl(issuesPath);
+    assert.equal(lines.length, 1);
+    assert.equal(lines[0].id, issueId);
+    assert.equal(typeof lines[0].created_at, 'string');
+  });
+
+  it('GET /api/issues returns enriched issue list with counts', async () => {
+    const issueId = 'ISS-IR-2';
+    await requestJson(baseUrl, 'POST', '/api/issues', { id: issueId, title: 'Counts' });
+
+    const res = await requestJson(baseUrl, 'GET', '/api/issues');
+    assert.equal(res.status, 200);
+    const issue = res.json.issues.find((i: any) => i.id === issueId);
+    assert.ok(issue);
+    assert.equal(issue.solution_count, 0);
+    assert.equal(issue.task_count, 0);
+  });
+
+  it('GET /api/issues/:id returns issue detail with solutions/tasks arrays', async () => {
+    const issueId = 'ISS-IR-3';
+    await requestJson(baseUrl, 'POST', '/api/issues', { id: issueId, title: 'Detail' });
+
+    const res = await requestJson(baseUrl, 'GET', `/api/issues/${encodeURIComponent(issueId)}`);
+    assert.equal(res.status, 200);
+    assert.equal(res.json.id, issueId);
+    assert.equal(Array.isArray(res.json.solutions), true);
+    assert.equal(Array.isArray(res.json.tasks), true);
+    assert.equal(res.json.solutions.length, 0);
+    assert.equal(res.json.tasks.length, 0);
+  });
+
+  it('POST /api/issues/:id/solutions appends a solution to solutions JSONL', async () => {
+    const issueId = 'ISS-IR-4';
+    const solutionId = 'SOL-ISS-IR-4-1';
+    await requestJson(baseUrl, 'POST', '/api/issues', { id: issueId, title: 'Solution add' });
+
+    const tasks = [{ id: 'T1', title: 'Do thing' }];
+    const res = await requestJson(baseUrl, 'POST', `/api/issues/${encodeURIComponent(issueId)}/solutions`, { id: solutionId, tasks });
+    assert.equal(res.status, 200);
+    assert.equal(res.json?.success, true);
+    assert.equal(res.json.solution.id, solutionId);
+    assert.equal(res.json.solution.is_bound, false);
+
+    const solutionsPath = join(projectRoot, '.workflow', 'issues', 'solutions', `${issueId}.jsonl`);
+    const lines = readJsonl(solutionsPath);
+    assert.equal(lines.length, 1);
+    assert.equal(lines[0].id, solutionId);
+    assert.equal(Array.isArray(lines[0].tasks), true);
+  });
+
+  it('PATCH /api/issues/:id binds solution and updates planned status', async () => {
+    const issueId = 'ISS-IR-5';
+    const solutionId = 'SOL-ISS-IR-5-1';
+    await requestJson(baseUrl, 'POST', '/api/issues', { id: issueId, title: 'Bind' });
+    await requestJson(baseUrl, 'POST', `/api/issues/${encodeURIComponent(issueId)}/solutions`, { id: solutionId, tasks: [{ id: 'T1' }] });
+
+    const res = await requestJson(baseUrl, 'PATCH', `/api/issues/${encodeURIComponent(issueId)}`, { bound_solution_id: solutionId });
+    assert.equal(res.status, 200);
+    assert.equal(res.json?.success, true);
+    assert.ok(res.json.updated.includes('bound_solution_id'));
+
+    const detail = await requestJson(baseUrl, 'GET', `/api/issues/${encodeURIComponent(issueId)}`);
+    assert.equal(detail.status, 200);
+    assert.equal(detail.json.bound_solution_id, solutionId);
+    assert.equal(detail.json.status, 'planned');
+    assert.ok(detail.json.planned_at);
+    assert.equal(detail.json.tasks.length, 1);
+
+    const solutionsPath = join(projectRoot, '.workflow', 'issues', 'solutions', `${issueId}.jsonl`);
+    const lines = readJsonl(solutionsPath);
+    assert.equal(lines.length, 1);
+    assert.equal(lines[0].is_bound, true);
+  });
+
+  it('PATCH /api/issues/:id/tasks/:taskId updates bound solution task fields', async () => {
+    const issueId = 'ISS-IR-6';
+    const solutionId = 'SOL-ISS-IR-6-1';
+    await requestJson(baseUrl, 'POST', '/api/issues', { id: issueId, title: 'Task update' });
+    await requestJson(baseUrl, 'POST', `/api/issues/${encodeURIComponent(issueId)}/solutions`, { id: solutionId, tasks: [{ id: 'T1', status: 'pending' }] });
+    await requestJson(baseUrl, 'PATCH', `/api/issues/${encodeURIComponent(issueId)}`, { bound_solution_id: solutionId });
+
+    const res = await requestJson(baseUrl, 'PATCH', `/api/issues/${encodeURIComponent(issueId)}/tasks/T1`, { status: 'completed', result: { ok: true } });
+    assert.equal(res.status, 200);
+    assert.equal(res.json?.success, true);
+    assert.ok(res.json.updated.includes('status'));
+    assert.ok(res.json.updated.includes('result'));
+
+    const solutionsPath = join(projectRoot, '.workflow', 'issues', 'solutions', `${issueId}.jsonl`);
+    const lines = readJsonl(solutionsPath);
+    const task = lines[0].tasks.find((t: any) => t.id === 'T1');
+    assert.equal(task.status, 'completed');
+    assert.deepEqual(task.result, { ok: true });
+    assert.ok(task.updated_at);
+  });
+
+  it('DELETE /api/issues/:id removes issue and deletes solutions JSONL', async () => {
+    const issueId = 'ISS-IR-7';
+    const solutionId = 'SOL-ISS-IR-7-1';
+    await requestJson(baseUrl, 'POST', '/api/issues', { id: issueId, title: 'Delete me' });
+    await requestJson(baseUrl, 'POST', `/api/issues/${encodeURIComponent(issueId)}/solutions`, { id: solutionId, tasks: [{ id: 'T1' }] });
+
+    const res = await requestJson(baseUrl, 'DELETE', `/api/issues/${encodeURIComponent(issueId)}`);
+    assert.equal(res.status, 200);
+    assert.equal(res.json?.success, true);
+
+    const issuesPath = join(projectRoot, '.workflow', 'issues', 'issues.jsonl');
+    assert.equal(readJsonl(issuesPath).length, 0);
+
+    const solutionsPath = join(projectRoot, '.workflow', 'issues', 'solutions', `${issueId}.jsonl`);
+    assert.equal(existsSync(solutionsPath), false);
+  });
+
+  it('GET /api/queue returns grouped queue structure', async () => {
+    const res = await requestJson(baseUrl, 'GET', '/api/queue');
+    assert.equal(res.status, 200);
+    assert.ok(res.json);
+    assert.equal(Array.isArray(res.json.execution_groups), true);
+    assert.equal(typeof res.json.grouped_items, 'object');
+  });
+});
+

ccw/tests/integration/litellm-api-routes.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Integration tests for LiteLLM API routes (providers + model discovery).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Calls route handler directly (no HTTP server required).
+ * - Uses temporary CCW_DATA_DIR to isolate ~/.ccw config writes.
+ */
+
+import { after, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const CCW_HOME = mkdtempSync(join(tmpdir(), 'ccw-litellm-api-home-'));
+const PROJECT_ROOT = mkdtempSync(join(tmpdir(), 'ccw-litellm-api-project-'));
+
+const litellmApiRoutesUrl = new URL('../../dist/core/routes/litellm-api-routes.js', import.meta.url);
+litellmApiRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+const originalEnv = { CCW_DATA_DIR: process.env.CCW_DATA_DIR };
+
+async function callLiteLLMApi(
+  initialPath: string,
+  method: string,
+  path: string,
+  body?: any,
+): Promise<{ handled: boolean; status: number; json: any; broadcasts: any[] }> {
+  const url = new URL(path, 'http://localhost');
+  let status = 0;
+  let text = '';
+  const broadcasts: any[] = [];
+
+  const res = {
+    writeHead(code: number) {
+      status = code;
+    },
+    end(chunk?: any) {
+      text = chunk === undefined ? '' : String(chunk);
+    },
+  };
+
+  const handlePostRequest = async (_req: any, _res: any, handler: (parsed: any) => Promise<any>) => {
+    const result = await handler(body ?? {});
+    const errorValue = result && typeof result === 'object' ? (result as any).error : undefined;
+    const statusValue = result && typeof result === 'object' ? (result as any).status : undefined;
+
+    if (typeof errorValue === 'string' && errorValue.length > 0) {
+      res.writeHead(typeof statusValue === 'number' ? statusValue : 500);
+      res.end(JSON.stringify({ error: errorValue }));
+      return;
+    }
+
+    res.writeHead(200);
+    res.end(JSON.stringify(result));
+  };
+
+  const handled = await mod.handleLiteLLMApiRoutes({
+    pathname: url.pathname,
+    url,
+    req: { method },
+    res,
+    initialPath,
+    handlePostRequest,
+    broadcastToClients(data: unknown) {
+      broadcasts.push(data);
+    },
+  });
+
+  return { handled, status, json: text ? JSON.parse(text) : null, broadcasts };
+}
+
+describe('litellm-api routes integration', async () => {
+  before(async () => {
+    process.env.CCW_DATA_DIR = CCW_HOME;
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'warn', () => {});
+    mock.method(console, 'error', () => {});
+    mod = await import(litellmApiRoutesUrl.href);
+  });
+
+  after(() => {
+    mock.restoreAll();
+    process.env.CCW_DATA_DIR = originalEnv.CCW_DATA_DIR;
+    rmSync(CCW_HOME, { recursive: true, force: true });
+    rmSync(PROJECT_ROOT, { recursive: true, force: true });
+  });
+
+  it('GET /api/litellm-api/models/openai returns static model list', async () => {
+    const res = await callLiteLLMApi(PROJECT_ROOT, 'GET', '/api/litellm-api/models/openai');
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(res.json.providerType, 'openai');
+    assert.equal(Array.isArray(res.json.models), true);
+    assert.ok(res.json.models.length > 0);
+  });
+
+  it('GET /api/litellm-api/providers returns default empty config', async () => {
+    const res = await callLiteLLMApi(PROJECT_ROOT, 'GET', '/api/litellm-api/providers');
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(Array.isArray(res.json.providers), true);
+    assert.equal(typeof res.json.count, 'number');
+  });
+
+  it('POST /api/litellm-api/providers validates required fields', async () => {
+    const res = await callLiteLLMApi(PROJECT_ROOT, 'POST', '/api/litellm-api/providers', { name: 'x' });
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 400);
+    assert.ok(String(res.json.error).includes('required'));
+    assert.equal(res.broadcasts.length, 0);
+  });
+});
+

ccw/tests/integration/nav-status-routes.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Integration tests for nav-status routes (badge count aggregation).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Calls route handler directly (no HTTP server required).
+ * - Uses temporary HOME/USERPROFILE and project root to isolate filesystem reads.
+ */
+
+import { after, before, beforeEach, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const navStatusRoutesUrl = new URL('../../dist/core/routes/nav-status-routes.js', import.meta.url);
+navStatusRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+const originalEnv = {
+  HOME: process.env.HOME,
+  USERPROFILE: process.env.USERPROFILE,
+  HOMEDRIVE: process.env.HOMEDRIVE,
+  HOMEPATH: process.env.HOMEPATH,
+};
+
+async function getNavStatus(projectRoot: string): Promise<{ status: number; json: any }> {
+  const url = new URL('/api/nav-status', 'http://localhost');
+  let status = 0;
+  let body = '';
+
+  const res = {
+    writeHead(code: number) {
+      status = code;
+    },
+    end(chunk?: any) {
+      body = chunk === undefined ? '' : String(chunk);
+    },
+  };
+
+  const handled = await mod.handleNavStatusRoutes({
+    pathname: '/api/nav-status',
+    url,
+    req: { method: 'GET' },
+    res,
+    initialPath: projectRoot,
+  });
+
+  assert.equal(handled, true);
+  return { status, json: JSON.parse(body) };
+}
+
+describe('nav-status routes integration', async () => {
+  let homeDir = '';
+  let projectRoot = '';
+
+  before(async () => {
+    homeDir = mkdtempSync(join(tmpdir(), 'ccw-nav-home-'));
+    projectRoot = mkdtempSync(join(tmpdir(), 'ccw-nav-project-'));
+
+    process.env.HOME = homeDir;
+    process.env.USERPROFILE = homeDir;
+    process.env.HOMEDRIVE = undefined;
+    process.env.HOMEPATH = undefined;
+
+    mock.method(console, 'error', () => {});
+    mod = await import(navStatusRoutesUrl.href);
+  });
+
+  beforeEach(() => {
+    // Reset relevant trees per test.
+    rmSync(join(projectRoot, '.workflow'), { recursive: true, force: true });
+    rmSync(join(projectRoot, '.claude'), { recursive: true, force: true });
+    rmSync(join(homeDir, '.claude'), { recursive: true, force: true });
+
+    const rootClaude = join(projectRoot, 'CLAUDE.md');
+    if (existsSync(rootClaude)) rmSync(rootClaude, { force: true });
+  });
+
+  after(() => {
+    mock.restoreAll();
+    process.env.HOME = originalEnv.HOME;
+    process.env.USERPROFILE = originalEnv.USERPROFILE;
+    process.env.HOMEDRIVE = originalEnv.HOMEDRIVE;
+    process.env.HOMEPATH = originalEnv.HOMEPATH;
+
+    rmSync(projectRoot, { recursive: true, force: true });
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  it('returns zero counts when no data exists', async () => {
+    const res = await getNavStatus(projectRoot);
+    assert.equal(res.status, 200);
+    assert.ok(res.json);
+
+    for (const key of ['issues', 'discoveries', 'skills', 'rules', 'claude', 'hooks', 'timestamp']) {
+      assert.ok(Object.prototype.hasOwnProperty.call(res.json, key), `missing key: ${key}`);
+    }
+
+    assert.equal(res.json.issues.count, 0);
+    assert.equal(res.json.discoveries.count, 0);
+    assert.equal(res.json.skills.count, 0);
+    assert.equal(res.json.rules.count, 0);
+    assert.equal(res.json.claude.count, 0);
+    assert.equal(res.json.hooks.count, 0);
+    assert.equal(typeof res.json.timestamp, 'string');
+  });
+
+  it('counts issues.jsonl lines and discovery index entries', async () => {
+    const issuesDir = join(projectRoot, '.workflow', 'issues');
+    const discoveriesDir = join(issuesDir, 'discoveries');
+    mkdirSync(discoveriesDir, { recursive: true });
+
+    writeFileSync(join(issuesDir, 'issues.jsonl'), '{"id":"ISS-1"}\n{"id":"ISS-2"}\n', 'utf8');
+    writeFileSync(join(discoveriesDir, 'index.json'), JSON.stringify({ discoveries: [{ id: 'DSC-1' }, { id: 'DSC-2' }, { id: 'DSC-3' }] }), 'utf8');
+
+    const res = await getNavStatus(projectRoot);
+    assert.equal(res.status, 200);
+    assert.equal(res.json.issues.count, 2);
+    assert.equal(res.json.discoveries.count, 3);
+  });
+
+  it('aggregates skills, rules, CLAUDE.md files, and hooks across user/project', async () => {
+    // Skills
+    mkdirSync(join(projectRoot, '.claude', 'skills', 'proj-skill'), { recursive: true });
+    writeFileSync(join(projectRoot, '.claude', 'skills', 'proj-skill', 'SKILL.md'), '# skill\n', 'utf8');
+    mkdirSync(join(homeDir, '.claude', 'skills', 'user-skill-1'), { recursive: true });
+    mkdirSync(join(homeDir, '.claude', 'skills', 'user-skill-2'), { recursive: true });
+    writeFileSync(join(homeDir, '.claude', 'skills', 'user-skill-1', 'SKILL.md'), '# skill\n', 'utf8');
+    writeFileSync(join(homeDir, '.claude', 'skills', 'user-skill-2', 'SKILL.md'), '# skill\n', 'utf8');
+
+    // Rules (recursive)
+    mkdirSync(join(projectRoot, '.claude', 'rules', 'nested'), { recursive: true });
+    writeFileSync(join(projectRoot, '.claude', 'rules', 'a.md'), '# a\n', 'utf8');
+    writeFileSync(join(projectRoot, '.claude', 'rules', 'nested', 'b.md'), '# b\n', 'utf8');
+    mkdirSync(join(homeDir, '.claude', 'rules'), { recursive: true });
+    writeFileSync(join(homeDir, '.claude', 'rules', 'c.md'), '# c\n', 'utf8');
+
+    // CLAUDE.md files (user main + project main + root + module)
+    mkdirSync(join(homeDir, '.claude'), { recursive: true });
+    writeFileSync(join(homeDir, '.claude', 'CLAUDE.md'), '# user\n', 'utf8');
+    mkdirSync(join(projectRoot, '.claude'), { recursive: true });
+    writeFileSync(join(projectRoot, '.claude', 'CLAUDE.md'), '# project\n', 'utf8');
+    writeFileSync(join(projectRoot, 'CLAUDE.md'), '# root\n', 'utf8');
+    const moduleDir = join(projectRoot, 'module-a');
+    mkdirSync(moduleDir, { recursive: true });
+    writeFileSync(join(moduleDir, 'CLAUDE.md'), '# module\n', 'utf8');
+
+    // Hooks in settings.json
+    mkdirSync(join(homeDir, '.claude'), { recursive: true });
+    writeFileSync(
+      join(homeDir, '.claude', 'settings.json'),
+      JSON.stringify({ hooks: { PreToolUse: [{}, {}], PostToolUse: {} } }),
+      'utf8',
+    );
+    writeFileSync(
+      join(projectRoot, '.claude', 'settings.json'),
+      JSON.stringify({ hooks: { PreToolUse: [{}] } }),
+      'utf8',
+    );
+
+    const res = await getNavStatus(projectRoot);
+    assert.equal(res.status, 200);
+
+    assert.equal(res.json.skills.project, 1);
+    assert.equal(res.json.skills.user, 2);
+    assert.equal(res.json.skills.count, 3);
+
+    assert.equal(res.json.rules.project, 2);
+    assert.equal(res.json.rules.user, 1);
+    assert.equal(res.json.rules.count, 3);
+
+    assert.equal(res.json.claude.count, 4);
+
+    assert.equal(res.json.hooks.global, 3);
+    assert.equal(res.json.hooks.project, 1);
+    assert.equal(res.json.hooks.count, 4);
+  });
+});
+

ccw/tests/integration/rules-routes.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Integration tests for rules routes (rules management CRUD).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Calls route handler directly (no HTTP server required).
+ * - Uses temporary HOME/USERPROFILE to isolate user rules directory.
+ */
+
+import { after, before, beforeEach, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const rulesRoutesUrl = new URL('../../dist/core/routes/rules-routes.js', import.meta.url);
+rulesRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+const originalEnv = {
+  HOME: process.env.HOME,
+  USERPROFILE: process.env.USERPROFILE,
+  HOMEDRIVE: process.env.HOMEDRIVE,
+  HOMEPATH: process.env.HOMEPATH,
+};
+
+async function callRules(
+  initialPath: string,
+  method: string,
+  path: string,
+  body?: any,
+): Promise<{ handled: boolean; status: number; json: any }> {
+  const url = new URL(path, 'http://localhost');
+  let status = 0;
+  let text = '';
+  let postPromise: Promise<void> | null = null;
+
+  const res = {
+    writeHead(code: number) {
+      status = code;
+    },
+    end(chunk?: any) {
+      text = chunk === undefined ? '' : String(chunk);
+    },
+  };
+
+  const handlePostRequest = (_req: any, _res: any, handler: (parsed: any) => Promise<any>) => {
+    postPromise = (async () => {
+      const result = await handler(body ?? {});
+      const errorValue = result && typeof result === 'object' ? (result as any).error : undefined;
+      const statusValue = result && typeof result === 'object' ? (result as any).status : undefined;
+
+      if (typeof errorValue === 'string' && errorValue.length > 0) {
+        res.writeHead(typeof statusValue === 'number' ? statusValue : 500);
+        res.end(JSON.stringify({ error: errorValue }));
+        return;
+      }
+
+      res.writeHead(200);
+      res.end(JSON.stringify(result));
+    })();
+  };
+
+  const handled = await mod.handleRulesRoutes({
+    pathname: url.pathname,
+    url,
+    req: { method },
+    res,
+    initialPath,
+    handlePostRequest,
+  });
+
+  if (postPromise) await postPromise;
+
+  return { handled, status, json: text ? JSON.parse(text) : null };
+}
+
+describe('rules routes integration', async () => {
+  let homeDir = '';
+  let projectRoot = '';
+
+  before(async () => {
+    homeDir = mkdtempSync(join(tmpdir(), 'ccw-rules-home-'));
+    projectRoot = mkdtempSync(join(tmpdir(), 'ccw-rules-project-'));
+
+    process.env.HOME = homeDir;
+    process.env.USERPROFILE = homeDir;
+    process.env.HOMEDRIVE = undefined;
+    process.env.HOMEPATH = undefined;
+
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'warn', () => {});
+    mock.method(console, 'error', () => {});
+
+    mod = await import(rulesRoutesUrl.href);
+  });
+
+  beforeEach(() => {
+    rmSync(join(homeDir, '.claude'), { recursive: true, force: true });
+    rmSync(join(projectRoot, '.claude'), { recursive: true, force: true });
+  });
+
+  after(() => {
+    mock.restoreAll();
+    process.env.HOME = originalEnv.HOME;
+    process.env.USERPROFILE = originalEnv.USERPROFILE;
+    process.env.HOMEDRIVE = originalEnv.HOMEDRIVE;
+    process.env.HOMEPATH = originalEnv.HOMEPATH;
+
+    rmSync(projectRoot, { recursive: true, force: true });
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  it('GET /api/rules returns projectRules and userRules arrays', async () => {
+    const res = await callRules(projectRoot, 'GET', '/api/rules');
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(Array.isArray(res.json.projectRules), true);
+    assert.equal(Array.isArray(res.json.userRules), true);
+  });
+
+  it('POST /api/rules/create writes a project rule and GET reflects it', async () => {
+    const create = await callRules(projectRoot, 'POST', '/api/rules/create', {
+      fileName: 'test-rule.md',
+      content: '# Hello rule\n',
+      paths: ['src/**'],
+      location: 'project',
+    });
+
+    assert.equal(create.handled, true);
+    assert.equal(create.status, 200);
+    assert.equal(create.json.success, true);
+    assert.ok(typeof create.json.path === 'string' && create.json.path.length > 0);
+    assert.equal(existsSync(create.json.path), true);
+
+    const config = await callRules(projectRoot, 'GET', '/api/rules');
+    assert.equal(config.status, 200);
+    assert.equal(config.json.projectRules.length, 1);
+    assert.equal(config.json.projectRules[0].name, 'test-rule.md');
+
+    const detail = await callRules(projectRoot, 'GET', '/api/rules/test-rule.md?location=project');
+    assert.equal(detail.status, 200);
+    assert.equal(detail.json.rule.name, 'test-rule.md');
+    assert.ok(String(detail.json.rule.content).includes('Hello rule'));
+
+    // Ensure frontmatter was persisted.
+    const raw = readFileSync(create.json.path, 'utf8');
+    assert.ok(raw.startsWith('---'));
+    assert.ok(raw.includes('paths: [src/**]'));
+  });
+});

ccw/tests/integration/skills-routes.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Integration tests for skills routes (skills listing + details).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Calls route handler directly (no HTTP server required).
+ * - Uses temporary HOME/USERPROFILE to isolate user skills directory.
+ */
+
+import { after, before, beforeEach, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const skillsRoutesUrl = new URL('../../dist/core/routes/skills-routes.js', import.meta.url);
+skillsRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+const originalEnv = {
+  HOME: process.env.HOME,
+  USERPROFILE: process.env.USERPROFILE,
+  HOMEDRIVE: process.env.HOMEDRIVE,
+  HOMEPATH: process.env.HOMEPATH,
+};
+
+async function callSkills(
+  initialPath: string,
+  method: string,
+  path: string,
+): Promise<{ handled: boolean; status: number; json: any }> {
+  const url = new URL(path, 'http://localhost');
+  let status = 0;
+  let body = '';
+
+  const res = {
+    writeHead(code: number) {
+      status = code;
+    },
+    end(chunk?: any) {
+      body = chunk === undefined ? '' : String(chunk);
+    },
+  };
+
+  const handled = await mod.handleSkillsRoutes({
+    pathname: url.pathname,
+    url,
+    req: { method },
+    res,
+    initialPath,
+    handlePostRequest() {
+      throw new Error('handlePostRequest should not be called for these tests');
+    },
+  });
+
+  return { handled, status, json: body ? JSON.parse(body) : null };
+}
+
+describe('skills routes integration', async () => {
+  let homeDir = '';
+  let projectRoot = '';
+
+  before(async () => {
+    homeDir = mkdtempSync(join(tmpdir(), 'ccw-skills-home-'));
+    projectRoot = mkdtempSync(join(tmpdir(), 'ccw-skills-project-'));
+
+    process.env.HOME = homeDir;
+    process.env.USERPROFILE = homeDir;
+    process.env.HOMEDRIVE = undefined;
+    process.env.HOMEPATH = undefined;
+
+    mock.method(console, 'error', () => {});
+    mod = await import(skillsRoutesUrl.href);
+  });
+
+  beforeEach(() => {
+    rmSync(join(homeDir, '.claude'), { recursive: true, force: true });
+    rmSync(join(projectRoot, '.claude'), { recursive: true, force: true });
+
+    const skillDir = join(projectRoot, '.claude', 'skills', 'test-skill');
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      join(skillDir, 'SKILL.md'),
+      `---
+name: "Test Skill"
+description: "A test skill"
+version: "1.0.0"
+allowed-tools: [ccw issue next]
+---
+
+# Test
+`,
+      'utf8',
+    );
+    writeFileSync(join(skillDir, 'extra.txt'), 'extra', 'utf8');
+  });
+
+  after(() => {
+    mock.restoreAll();
+    process.env.HOME = originalEnv.HOME;
+    process.env.USERPROFILE = originalEnv.USERPROFILE;
+    process.env.HOMEDRIVE = originalEnv.HOMEDRIVE;
+    process.env.HOMEPATH = originalEnv.HOMEPATH;
+
+    rmSync(projectRoot, { recursive: true, force: true });
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  it('GET /api/skills lists projectSkills and userSkills', async () => {
+    const res = await callSkills(projectRoot, 'GET', `/api/skills?path=${encodeURIComponent(projectRoot)}`);
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(Array.isArray(res.json.projectSkills), true);
+    assert.equal(Array.isArray(res.json.userSkills), true);
+    assert.equal(res.json.projectSkills.length, 1);
+    assert.equal(res.json.projectSkills[0].folderName, 'test-skill');
+    assert.equal(res.json.projectSkills[0].name, 'Test Skill');
+    assert.ok(res.json.projectSkills[0].supportingFiles.includes('extra.txt'));
+  });
+
+  it('GET /api/skills/:name returns skill detail with parsed content', async () => {
+    const res = await callSkills(projectRoot, 'GET', `/api/skills/test-skill?location=project&path=${encodeURIComponent(projectRoot)}`);
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 200);
+    assert.equal(res.json.skill.folderName, 'test-skill');
+    assert.equal(res.json.skill.name, 'Test Skill');
+    assert.equal(Array.isArray(res.json.skill.allowedTools), true);
+    assert.ok(String(res.json.skill.content).includes('# Test'));
+  });
+
+  it('returns 404 when skill is missing', async () => {
+    const res = await callSkills(projectRoot, 'GET', `/api/skills/nope?location=project&path=${encodeURIComponent(projectRoot)}`);
+    assert.equal(res.handled, true);
+    assert.equal(res.status, 404);
+    assert.ok(res.json.error);
+  });
+});
+

ccw/tests/middleware.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Unit tests for auth middleware (ccw/dist/core/auth/middleware.js)
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+const middlewareUrl = new URL('../dist/core/auth/middleware.js', import.meta.url).href;
+const tokenManagerUrl = new URL('../dist/core/auth/token-manager.js', import.meta.url).href;
+
+type MockResponse = {
+  status: number | null;
+  headers: Record<string, string>;
+  body: string;
+  writeHead: (status: number, headers?: Record<string, string>) => void;
+  setHeader: (name: string, value: string) => void;
+  end: (body?: string) => void;
+};
+
+function createMockRes(): MockResponse {
+  const headers: Record<string, string> = {};
+  const response: MockResponse = {
+    status: null,
+    headers,
+    body: '',
+    writeHead: (status: number, nextHeaders?: Record<string, string>) => {
+      response.status = status;
+      if (nextHeaders) {
+        for (const [k, v] of Object.entries(nextHeaders)) {
+          headers[k.toLowerCase()] = v;
+        }
+      }
+    },
+    setHeader: (name: string, value: string) => {
+      headers[name.toLowerCase()] = value;
+    },
+    end: (body?: string) => {
+      response.body = body ? String(body) : '';
+    },
+  };
+  return response;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let middleware: any;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let tokenMod: any;
+
+describe('auth middleware', async () => {
+  middleware = await import(middlewareUrl);
+  tokenMod = await import(tokenManagerUrl);
+
+  it('rejects requests without tokens', () => {
+    const tokenManager = new tokenMod.TokenManager();
+    const secretKey = 'secret';
+
+    const req: any = { headers: {}, socket: { remoteAddress: '127.0.0.1' } };
+    const res = createMockRes();
+
+    const ok = middleware.authMiddleware({
+      pathname: '/api/health',
+      req,
+      res,
+      tokenManager,
+      secretKey,
+      unauthenticatedPaths: new Set(['/api/auth/token']),
+    });
+
+    assert.equal(ok, false);
+    assert.equal(res.status, 401);
+    assert.ok(res.body.includes('Unauthorized'));
+  });
+
+  it('accepts Authorization: Bearer tokens', () => {
+    const tokenManager = new tokenMod.TokenManager();
+    const secretKey = 'secret';
+    const { token } = tokenManager.generateToken(secretKey);
+
+    const req: any = { headers: { authorization: `Bearer ${token}` }, socket: { remoteAddress: '127.0.0.1' } };
+    const res = createMockRes();
+
+    const ok = middleware.authMiddleware({
+      pathname: '/api/health',
+      req,
+      res,
+      tokenManager,
+      secretKey,
+    });
+
+    assert.equal(ok, true);
+    assert.equal(req.authenticated, true);
+  });
+
+  it('accepts auth_token cookies', () => {
+    const tokenManager = new tokenMod.TokenManager();
+    const secretKey = 'secret';
+    const { token } = tokenManager.generateToken(secretKey);
+
+    const req: any = { headers: { cookie: `auth_token=${encodeURIComponent(token)}` }, socket: { remoteAddress: '127.0.0.1' } };
+    const res = createMockRes();
+
+    const ok = middleware.authMiddleware({
+      pathname: '/api/health',
+      req,
+      res,
+      tokenManager,
+      secretKey,
+    });
+
+    assert.equal(ok, true);
+  });
+
+  it('isLocalhostRequest detects loopback addresses', () => {
+    assert.equal(middleware.isLocalhostRequest({ socket: { remoteAddress: '127.0.0.1' } } as any), true);
+    assert.equal(middleware.isLocalhostRequest({ socket: { remoteAddress: '::1' } } as any), true);
+    assert.equal(middleware.isLocalhostRequest({ socket: { remoteAddress: '::ffff:127.0.0.1' } } as any), true);
+    assert.equal(middleware.isLocalhostRequest({ socket: { remoteAddress: '10.0.0.5' } } as any), false);
+  });
+});

ccw/tests/path-resolver.test.ts

@@ -177,6 +177,32 @@ describe('path-resolver utility module', async () => {
     assert.ok(res.error?.includes('Path must be within'));
   });
 
+  it('validatePath blocks symlink escapes even when target path does not exist', () => {
+    const baseDir = 'C:\\allowed';
+    const linkPath = 'C:\\allowed\\link';
+    setExists(linkPath, true);
+    setDir(linkPath, true);
+    setRealpath(linkPath, 'C:\\secret');
+
+    const res = pathResolver.validatePath(path.join(linkPath, 'newfile.txt'), { baseDir });
+    assert.equal(res.valid, false);
+    assert.equal(res.path, null);
+    assert.ok(res.error?.includes('Path must be within'));
+  });
+
+  it('validatePath allows symlinked parent directories that resolve within baseDir', () => {
+    const baseDir = 'C:\\allowed';
+    const linkPath = 'C:\\allowed\\link';
+    setExists(linkPath, true);
+    setDir(linkPath, true);
+    setRealpath(linkPath, 'C:\\allowed\\real');
+
+    const res = pathResolver.validatePath(path.join(linkPath, 'newfile.txt'), { baseDir });
+    assert.equal(res.valid, true);
+    assert.equal(res.path, path.join('C:\\allowed\\real', 'newfile.txt'));
+    assert.equal(res.error, null);
+  });
+
   it('validateOutputPath rejects directories and resolves relative output paths', () => {
     assert.equal(pathResolver.validateOutputPath('').valid, false);
 

ccw/tests/security/command-injection.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Regression tests for command injection protections in cli-executor.
+ *
+ * Focus: ensure args are escaped on Windows when `shell: true` is required.
+ */
+
+import { after, before, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const cliExecutorUrl = new URL('../../dist/tools/cli-executor.js', import.meta.url).href;
+const historyStoreUrl = new URL('../../dist/tools/cli-history-store.js', import.meta.url).href;
+const shellEscapeUrl = new URL('../../dist/utils/shell-escape.js', import.meta.url).href;
+
+describe('cli-executor: command injection regression', async () => {
+  const isWindows = process.platform === 'win32';
+
+  const require = createRequire(import.meta.url);
+  const childProcess = require('child_process');
+  const originalSpawn = childProcess.spawn;
+
+  const originalSetTimeout = globalThis.setTimeout;
+
+  const spawnCalls: Array<{ command: string; args: string[]; options: Record<string, unknown> }> = [];
+
+  const envSnapshot: Record<string, string | undefined> = {};
+  let ccwHome = '';
+  let projectDir = '';
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let cliExecutorModule: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let historyStoreModule: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let shellEscapeModule: any;
+
+  function unrefSetTimeout<TArgs extends unknown[]>(
+    fn: (...args: TArgs) => void,
+    delay?: number,
+    ...args: TArgs
+  ): ReturnType<typeof setTimeout> {
+    const t = originalSetTimeout(fn as (...args: unknown[]) => void, delay as number, ...args);
+    (t as unknown as { unref?: () => void }).unref?.();
+    return t;
+  }
+
+  before(async () => {
+    envSnapshot.CCW_DATA_DIR = process.env.CCW_DATA_DIR;
+    envSnapshot.DEBUG = process.env.DEBUG;
+    envSnapshot.CCW_DEBUG = process.env.CCW_DEBUG;
+
+    ccwHome = mkdtempSync(join(tmpdir(), 'ccw-command-injection-home-'));
+    projectDir = mkdtempSync(join(tmpdir(), 'ccw-command-injection-project-'));
+    process.env.CCW_DATA_DIR = ccwHome;
+    delete process.env.DEBUG;
+    delete process.env.CCW_DEBUG;
+
+    // Prevent long-lived timeouts in the module under test from delaying process exit.
+    globalThis.setTimeout = unrefSetTimeout as unknown as typeof setTimeout;
+
+    shellEscapeModule = await import(shellEscapeUrl);
+
+    // Patch child_process.spawn BEFORE importing cli-executor (it captures spawn at module init).
+    childProcess.spawn = (command: unknown, args: unknown[], options: Record<string, unknown>) => {
+      const cmd = String(command);
+      const argv = Array.isArray(args) ? args.map((a) => String(a)) : [];
+      spawnCalls.push({ command: cmd, args: argv, options: options || {} });
+
+      const child = new EventEmitter() as any;
+      child.pid = 4242;
+      child.killed = false;
+      child.stdin = new PassThrough();
+      child.stdout = new PassThrough();
+      child.stderr = new PassThrough();
+
+      let closed = false;
+      child.kill = () => {
+        child.killed = true;
+        if (!closed) {
+          closed = true;
+          child.stdout.end();
+          child.stderr.end();
+          child.emit('close', 0);
+        }
+        return true;
+      };
+
+      process.nextTick(() => {
+        if (closed) return;
+        if (cmd === 'where' || cmd === 'which') {
+          const tool = argv[0] || 'tool';
+          child.stdout.write(`C:\\\\fake\\\\${tool}.cmd\r\n`);
+          child.stdout.end();
+          child.stderr.end();
+          closed = true;
+          child.emit('close', 0);
+          return;
+        }
+
+        child.stdout.write('ok\n');
+        child.stdout.end();
+        child.stderr.end();
+        closed = true;
+        child.emit('close', 0);
+      });
+
+      return child;
+    };
+
+    cliExecutorModule = await import(cliExecutorUrl);
+    historyStoreModule = await import(historyStoreUrl);
+  });
+
+  after(async () => {
+    childProcess.spawn = originalSpawn;
+    globalThis.setTimeout = originalSetTimeout;
+
+    try {
+      historyStoreModule?.closeAllStores?.();
+    } catch {
+      // ignore
+    }
+
+    if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+    if (ccwHome) rmSync(ccwHome, { recursive: true, force: true });
+
+    process.env.CCW_DATA_DIR = envSnapshot.CCW_DATA_DIR;
+    if (envSnapshot.DEBUG === undefined) delete process.env.DEBUG;
+    else process.env.DEBUG = envSnapshot.DEBUG;
+    if (envSnapshot.CCW_DEBUG === undefined) delete process.env.CCW_DEBUG;
+    else process.env.CCW_DEBUG = envSnapshot.CCW_DEBUG;
+  });
+
+  it('escapes dangerous metacharacters for Windows shell execution', async () => {
+    const escapeWindowsArg = shellEscapeModule.escapeWindowsArg as (arg: string) => string;
+
+    const cases: Array<{
+      name: string;
+      params: Record<string, unknown>;
+      expectedCommand: string;
+      expectedArgs: string[];
+    }> = [
+      {
+        name: 'gemini: model includes &',
+        params: { tool: 'gemini', prompt: 'hi', cd: projectDir, id: 'case-gemini-model-amp', model: 'gpt-4 & calc' },
+        expectedCommand: 'gemini',
+        expectedArgs: ['-m', 'gpt-4 & calc'],
+      },
+      {
+        name: 'gemini: model includes |',
+        params: { tool: 'gemini', prompt: 'hi', cd: projectDir, id: 'case-gemini-model-pipe', model: 'gpt|calc' },
+        expectedCommand: 'gemini',
+        expectedArgs: ['-m', 'gpt|calc'],
+      },
+      {
+        name: 'gemini: model includes >',
+        params: { tool: 'gemini', prompt: 'hi', cd: projectDir, id: 'case-gemini-model-gt', model: 'gpt>out.txt' },
+        expectedCommand: 'gemini',
+        expectedArgs: ['-m', 'gpt>out.txt'],
+      },
+      {
+        name: 'gemini: model includes <',
+        params: { tool: 'gemini', prompt: 'hi', cd: projectDir, id: 'case-gemini-model-lt', model: 'gpt<input.txt' },
+        expectedCommand: 'gemini',
+        expectedArgs: ['-m', 'gpt<input.txt'],
+      },
+      {
+        name: 'gemini: model includes parentheses',
+        params: { tool: 'gemini', prompt: 'hi', cd: projectDir, id: 'case-gemini-model-paren', model: '(gpt)' },
+        expectedCommand: 'gemini',
+        expectedArgs: ['-m', '(gpt)'],
+      },
+      {
+        name: 'gemini: model includes %',
+        params: { tool: 'gemini', prompt: 'hi', cd: projectDir, id: 'case-gemini-model-percent', model: '%PATH%' },
+        expectedCommand: 'gemini',
+        expectedArgs: ['-m', '%PATH%'],
+      },
+      {
+        name: 'gemini: model includes !',
+        params: { tool: 'gemini', prompt: 'hi', cd: projectDir, id: 'case-gemini-model-bang', model: '!VAR!' },
+        expectedCommand: 'gemini',
+        expectedArgs: ['-m', '!VAR!'],
+      },
+      {
+        name: 'gemini: model includes caret',
+        params: { tool: 'gemini', prompt: 'hi', cd: projectDir, id: 'case-gemini-model-caret', model: 'a^b' },
+        expectedCommand: 'gemini',
+        expectedArgs: ['-m', 'a^b'],
+      },
+      {
+        name: 'gemini: includeDirs includes spaces and &',
+        params: { tool: 'gemini', prompt: 'hi', cd: projectDir, id: 'case-gemini-include', includeDirs: 'C:\\Program Files\\A & B', model: 'test-model' },
+        expectedCommand: 'gemini',
+        expectedArgs: ['-m', 'test-model', '--include-directories', 'C:\\Program Files\\A & B'],
+      },
+      {
+        name: 'qwen: model includes double quote',
+        params: { tool: 'qwen', prompt: 'hi', cd: projectDir, id: 'case-qwen-model-quote', model: 'qwen\"model' },
+        expectedCommand: 'qwen',
+        expectedArgs: ['-m', 'qwen\"model'],
+      },
+      {
+        name: 'qwen: includeDirs includes |',
+        params: { tool: 'qwen', prompt: 'hi', cd: projectDir, id: 'case-qwen-include-pipe', includeDirs: 'C:\\a|b', model: 'test-model' },
+        expectedCommand: 'qwen',
+        expectedArgs: ['-m', 'test-model', '--include-directories', 'C:\\a|b'],
+      },
+      {
+        name: 'codex: --add-dir values include metacharacters and spaces',
+        params: { tool: 'codex', prompt: 'hi', cd: projectDir, id: 'case-codex-include', includeDirs: 'C:\\a&b,C:\\c d', model: 'gpt-4' },
+        expectedCommand: 'codex',
+        expectedArgs: ['exec', '--full-auto', '-m', 'gpt-4', '--add-dir', 'C:\\a&b', '--add-dir', 'C:\\c d', '-'],
+      },
+    ];
+
+    for (const testCase of cases) {
+      spawnCalls.length = 0;
+
+      await cliExecutorModule.executeCliTool(testCase.params, null);
+
+      const execCall = spawnCalls.find((c) => c.command === testCase.expectedCommand);
+      assert.ok(execCall, `Expected spawn call for ${testCase.expectedCommand} (${testCase.name})`);
+
+      assert.equal(
+        execCall.options?.shell,
+        isWindows,
+        `Expected shell=${String(isWindows)} for ${testCase.expectedCommand} (${testCase.name})`
+      );
+
+      const expectedCommand = isWindows ? escapeWindowsArg(testCase.expectedCommand) : testCase.expectedCommand;
+      const expectedArgs = isWindows ? testCase.expectedArgs.map(escapeWindowsArg) : testCase.expectedArgs;
+
+      assert.equal(execCall.command, expectedCommand, `spawn command (${testCase.name})`);
+      assert.deepEqual(execCall.args, expectedArgs, `spawn args (${testCase.name})`);
+    }
+  });
+});

ccw/tests/security/credential-handling.test.ts

@@ -0,0 +1,447 @@
+/**
+ * Security tests for credential handling (DSC-004).
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Uses an isolated CCW data directory (CCW_DATA_DIR) to avoid touching real user config.
+ */
+
+import { after, afterEach, before, beforeEach, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const CCW_HOME = mkdtempSync(path.join(tmpdir(), 'ccw-credential-tests-home-'));
+const PROJECT_ROOT = mkdtempSync(path.join(tmpdir(), 'ccw-credential-tests-project-'));
+const CONFIG_DIR = path.join(CCW_HOME, 'config');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'litellm-api-config.json');
+
+const originalEnv = {
+  CCW_DATA_DIR: process.env.CCW_DATA_DIR,
+  TEST_API_KEY: process.env.TEST_API_KEY,
+};
+
+process.env.CCW_DATA_DIR = CCW_HOME;
+
+const configManagerUrl = new URL('../../dist/config/litellm-api-config-manager.js', import.meta.url);
+configManagerUrl.searchParams.set('t', String(Date.now()));
+
+const litellmRoutesUrl = new URL('../../dist/core/routes/litellm-api-routes.js', import.meta.url);
+litellmRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let routes: any;
+
+type JsonResponse = { status: number; json: any; text: string };
+
+async function requestJson(baseUrl: string, method: string, reqPath: string, body?: unknown): Promise<JsonResponse> {
+  const url = new URL(reqPath, baseUrl);
+  const payload = body === undefined ? null : Buffer.from(JSON.stringify(body), 'utf8');
+
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      url,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          ...(payload ? { 'Content-Type': 'application/json', 'Content-Length': String(payload.length) } : {}),
+        },
+      },
+      (res) => {
+        let responseBody = '';
+        res.on('data', (chunk) => {
+          responseBody += chunk.toString();
+        });
+        res.on('end', () => {
+          let json: any = null;
+          try {
+            json = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            json = null;
+          }
+          resolve({ status: res.statusCode || 0, json, text: responseBody });
+        });
+      },
+    );
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+function handlePostRequest(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  handler: (body: unknown) => Promise<any>,
+): void {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', async () => {
+    try {
+      const parsed = body ? JSON.parse(body) : {};
+      const result = await handler(parsed);
+
+      if (result?.error) {
+        res.writeHead(result.status || 500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error }));
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+}
+
+async function createServer(initialPath: string): Promise<{ server: http.Server; baseUrl: string }> {
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const pathname = url.pathname;
+
+    const ctx = {
+      pathname,
+      url,
+      req,
+      res,
+      initialPath,
+      handlePostRequest,
+      broadcastToClients() {},
+    };
+
+    try {
+      const handled = await routes.handleLiteLLMApiRoutes(ctx);
+      if (!handled) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not Found' }));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+
+  await new Promise<void>((resolve) => server.listen(0, () => resolve()));
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : 0;
+  return { server, baseUrl: `http://127.0.0.1:${port}` };
+}
+
+function loadMaskApiKey(): (apiKey: string) => string {
+  const filePath = new URL('../../src/templates/dashboard-js/views/api-settings.js', import.meta.url);
+  const source = readFileSync(filePath, 'utf8');
+
+  const match = source.match(/function\s+maskApiKey\(apiKey\)\s*\{[\s\S]*?\r?\n\}/);
+  if (!match) {
+    throw new Error('maskApiKey function not found in api-settings.js');
+  }
+
+  // eslint-disable-next-line no-new-func
+  const fn = new Function(`${match[0]}; return maskApiKey;`) as () => (apiKey: string) => string;
+  return fn();
+}
+
+describe('security: credential handling', async () => {
+  const maskApiKey = loadMaskApiKey();
+
+  function listFilesRecursive(dirPath: string): string[] {
+    const results: string[] = [];
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) results.push(...listFilesRecursive(fullPath));
+      else if (entry.isFile()) results.push(fullPath);
+    }
+    return results;
+  }
+
+  before(async () => {
+    mod = await import(configManagerUrl.href);
+    routes = await import(litellmRoutesUrl.href);
+  });
+
+  beforeEach(() => {
+    process.env.TEST_API_KEY = originalEnv.TEST_API_KEY;
+    rmSync(CONFIG_PATH, { force: true });
+  });
+
+  afterEach(() => {
+    mock.restoreAll();
+  });
+
+  after(() => {
+    process.env.CCW_DATA_DIR = originalEnv.CCW_DATA_DIR;
+    process.env.TEST_API_KEY = originalEnv.TEST_API_KEY;
+    rmSync(CCW_HOME, { recursive: true, force: true });
+    rmSync(PROJECT_ROOT, { recursive: true, force: true });
+  });
+
+  it('resolveEnvVar returns input unchanged when not ${ENV_VAR}', () => {
+    assert.equal(mod.resolveEnvVar('sk-test-1234'), 'sk-test-1234');
+    assert.equal(mod.resolveEnvVar(''), '');
+  });
+
+  it('resolveEnvVar resolves ${ENV_VAR} syntax', () => {
+    process.env.TEST_API_KEY = 'sk-test-resolved';
+    assert.equal(mod.resolveEnvVar('${TEST_API_KEY}'), 'sk-test-resolved');
+  });
+
+  it('resolveEnvVar returns empty string when env var is missing', () => {
+    delete process.env.TEST_API_KEY;
+    assert.equal(mod.resolveEnvVar('${TEST_API_KEY}'), '');
+  });
+
+  it('getProviderWithResolvedEnvVars returns provider with resolvedApiKey', () => {
+    process.env.TEST_API_KEY = 'sk-test-resolved';
+
+    const provider = mod.addProvider(PROJECT_ROOT, {
+      name: 'Test Provider',
+      type: 'openai',
+      apiKey: '${TEST_API_KEY}',
+      apiBase: undefined,
+      enabled: true,
+    });
+
+    const resolved = mod.getProviderWithResolvedEnvVars(PROJECT_ROOT, provider.id);
+    assert.ok(resolved);
+    assert.equal(resolved.id, provider.id);
+    assert.equal(resolved.resolvedApiKey, 'sk-test-resolved');
+  });
+
+  it('resolveEnvVar does not log resolved credential values', () => {
+    const secret = 'sk-test-secret-1234567890';
+    process.env.TEST_API_KEY = secret;
+
+    const calls: string[] = [];
+    mock.method(console, 'log', (...args: unknown[]) => calls.push(args.map(String).join(' ')));
+    mock.method(console, 'error', (...args: unknown[]) => calls.push(args.map(String).join(' ')));
+
+    assert.equal(mod.resolveEnvVar('${TEST_API_KEY}'), secret);
+    assert.equal(calls.some((line) => line.includes(secret)), false);
+  });
+
+  it('getProviderWithResolvedEnvVars does not log resolved credential values', () => {
+    const secret = 'sk-test-secret-abcdef123456';
+    process.env.TEST_API_KEY = secret;
+
+    const calls: string[] = [];
+    mock.method(console, 'log', (...args: unknown[]) => calls.push(args.map(String).join(' ')));
+    mock.method(console, 'error', (...args: unknown[]) => calls.push(args.map(String).join(' ')));
+
+    const provider = mod.addProvider(PROJECT_ROOT, {
+      name: 'Test Provider',
+      type: 'openai',
+      apiKey: '${TEST_API_KEY}',
+      apiBase: undefined,
+      enabled: true,
+    });
+
+    const resolved = mod.getProviderWithResolvedEnvVars(PROJECT_ROOT, provider.id);
+    assert.ok(resolved);
+    assert.equal(resolved.resolvedApiKey, secret);
+    assert.equal(calls.some((line) => line.includes(secret)), false);
+  });
+
+  it('loadLiteLLMApiConfig logs parse errors without leaking credentials', () => {
+    const secret = 'sk-test-secret-in-file-1234';
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_PATH, `{\"providers\":[{\"apiKey\":\"${secret}\"`, 'utf8');
+
+    const calls: string[] = [];
+    mock.method(console, 'error', (...args: unknown[]) => calls.push(args.map(String).join(' ')));
+
+    const config = mod.loadLiteLLMApiConfig(PROJECT_ROOT);
+    assert.equal(Array.isArray(config.providers), true);
+    assert.equal(config.providers.length, 0);
+    assert.equal(calls.length > 0, true);
+    assert.equal(calls.some((line) => line.includes(secret)), false);
+  });
+
+  it('loadLiteLLMApiConfig stack traces do not include raw credentials', () => {
+    const secret = 'sk-test-secret-stack-9999';
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_PATH, `{\"providers\":[{\"apiKey\":\"${secret}\"`, 'utf8');
+
+    const errorArgs: unknown[][] = [];
+    mock.method(console, 'error', (...args: unknown[]) => errorArgs.push(args));
+
+    mod.loadLiteLLMApiConfig(PROJECT_ROOT);
+
+    const errorObj = errorArgs.flat().find((arg) => arg instanceof Error) as Error | undefined;
+    assert.ok(errorObj);
+    assert.equal(String(errorObj.stack ?? '').includes(secret), false);
+  });
+
+  it('maskApiKey hides raw keys but keeps env var references readable', () => {
+    assert.equal(maskApiKey(''), '');
+    assert.equal(maskApiKey('${TEST_API_KEY}'), '${TEST_API_KEY}');
+    assert.equal(maskApiKey('short'), '***');
+    assert.equal(maskApiKey('sk-test-1234567890'), 'sk-t...7890');
+  });
+
+  it('getProviderWithResolvedEnvVars is safe to stringify (no env var syntax or resolved secrets)', () => {
+    const secret = 'sk-test-secret-json-0000';
+    process.env.TEST_API_KEY = secret;
+
+    const provider = mod.addProvider(PROJECT_ROOT, {
+      name: 'Test Provider',
+      type: 'openai',
+      apiKey: '${TEST_API_KEY}',
+      apiBase: undefined,
+      enabled: true,
+    });
+
+    const resolved = mod.getProviderWithResolvedEnvVars(PROJECT_ROOT, provider.id);
+    assert.ok(resolved);
+
+    const payload = JSON.stringify(resolved);
+    assert.equal(payload.includes(secret), false);
+    assert.equal(payload.includes('${TEST_API_KEY}'), false);
+    assert.equal(payload.includes('resolvedApiKey'), false);
+  });
+
+  it('API responses do not expose env var syntax for provider apiKey', async () => {
+    process.env.TEST_API_KEY = 'sk-test-secret-api-1111';
+
+    mod.addProvider(PROJECT_ROOT, {
+      name: 'Test Provider',
+      type: 'openai',
+      apiKey: '${TEST_API_KEY}',
+      apiBase: undefined,
+      enabled: true,
+    });
+
+    const { server, baseUrl } = await createServer(PROJECT_ROOT);
+    try {
+      const res = await requestJson(baseUrl, 'GET', '/api/litellm-api/providers');
+      assert.equal(res.status, 200);
+      assert.ok(res.json?.providers);
+
+      assert.equal(res.text.includes('${TEST_API_KEY}'), false);
+      assert.equal(res.text.includes('${'), false);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it('API responses do not expose resolved secrets in generated rotation endpoints', async () => {
+    const secret = 'sk-test-secret-rotation-2222';
+    process.env.TEST_API_KEY = secret;
+
+    const provider = mod.addProvider(PROJECT_ROOT, {
+      name: 'Embed Provider',
+      type: 'openai',
+      apiKey: '${TEST_API_KEY}',
+      apiBase: undefined,
+      enabled: true,
+    });
+
+    // Ensure provider has an enabled embedding model.
+    mod.updateProvider(PROJECT_ROOT, provider.id, {
+      embeddingModels: [{
+        id: 'emb-1',
+        name: 'text-embedding-test',
+        type: 'embedding',
+        series: 'Test',
+        enabled: true,
+      }],
+    });
+
+    // Configure legacy rotation directly in the config file (avoid auto-sync side effects).
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    const config = mod.loadLiteLLMApiConfig(PROJECT_ROOT);
+    config.codexlensEmbeddingRotation = {
+      enabled: true,
+      strategy: 'round_robin',
+      defaultCooldown: 60,
+      targetModel: 'text-embedding-test',
+      providers: [{
+        providerId: provider.id,
+        modelId: 'emb-1',
+        useAllKeys: true,
+        weight: 1.0,
+        maxConcurrentPerKey: 4,
+        enabled: true,
+      }],
+    };
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf8');
+
+    const { server, baseUrl } = await createServer(PROJECT_ROOT);
+    try {
+      const res = await requestJson(baseUrl, 'GET', '/api/litellm-api/codexlens/rotation/endpoints');
+      assert.equal(res.status, 200);
+      assert.ok(res.json?.endpoints);
+
+      assert.equal(res.text.includes(secret), false);
+      assert.equal(res.text.includes('${TEST_API_KEY}'), false);
+      assert.equal(res.text.includes('${'), false);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it('stores env var references without persisting resolved secrets when available', () => {
+    const secret = 'sk-test-secret-storage-3333';
+    process.env.TEST_API_KEY = secret;
+
+    mod.addProvider(PROJECT_ROOT, {
+      name: 'Stored Provider',
+      type: 'openai',
+      apiKey: '${TEST_API_KEY}',
+      apiBase: undefined,
+      enabled: true,
+    });
+
+    const content = readFileSync(CONFIG_PATH, 'utf8');
+    assert.equal(content.includes('${TEST_API_KEY}'), true);
+    assert.equal(content.includes(secret), false);
+  });
+
+  it('does not write resolved secrets into ancillary files under CCW_DATA_DIR', () => {
+    const secret = 'sk-test-secret-storage-scan-4444';
+    process.env.TEST_API_KEY = secret;
+
+    mod.addProvider(PROJECT_ROOT, {
+      name: 'Stored Provider',
+      type: 'openai',
+      apiKey: '${TEST_API_KEY}',
+      apiBase: undefined,
+      enabled: true,
+    });
+
+    const files = listFilesRecursive(CCW_HOME);
+    assert.ok(files.length > 0);
+
+    for (const filePath of files) {
+      const content = readFileSync(filePath, 'utf8');
+      assert.equal(content.includes(secret), false);
+    }
+  });
+
+  it('writes config file with restrictive permissions where supported', () => {
+    mod.addProvider(PROJECT_ROOT, {
+      name: 'Perms Provider',
+      type: 'openai',
+      apiKey: 'sk-test-raw-key',
+      apiBase: undefined,
+      enabled: true,
+    });
+
+    const stat = statSync(CONFIG_PATH);
+    assert.equal(stat.isFile(), true);
+
+    if (process.platform === 'win32') return;
+
+    // Require no permissions for group/others (0600).
+    const mode = stat.mode & 0o777;
+    assert.equal(mode & 0o077, 0);
+  });
+});

ccw/tests/security/csrf.test.ts

@@ -0,0 +1,294 @@
+/**
+ * Security regression tests for CSRF protection (DSC-006).
+ *
+ * Verifies:
+ * - State-changing API routes require a valid CSRF token (cookie/header/body)
+ * - Tokens are single-use and session-bound
+ * - CORS rejects non-localhost origins (browser-enforced via mismatched Allow-Origin)
+ * - Development bypass flag disables CSRF validation
+ */
+
+import { after, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+type HttpResult = {
+  status: number;
+  body: string;
+  headers: http.IncomingHttpHeaders;
+};
+
+function httpRequest(options: http.RequestOptions, body?: string, timeout = 10000): Promise<HttpResult> {
+  return new Promise((resolve, reject) => {
+    const req = http.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve({ status: res.statusCode || 0, body: data, headers: res.headers }));
+    });
+    req.on('error', reject);
+    req.setTimeout(timeout, () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+function updateCookieJar(jar: Record<string, string>, setCookie: string | string[] | undefined): void {
+  if (!setCookie) return;
+  const cookies = Array.isArray(setCookie) ? setCookie : [setCookie];
+  for (const cookie of cookies) {
+    const pair = cookie.split(';')[0]?.trim();
+    if (!pair) continue;
+    const [name, ...valueParts] = pair.split('=');
+    jar[name] = valueParts.join('=');
+  }
+}
+
+function cookieHeader(jar: Record<string, string>): string {
+  return Object.entries(jar)
+    .map(([name, value]) => `${name}=${value}`)
+    .join('; ');
+}
+
+function cloneJar(jar: Record<string, string>): Record<string, string> {
+  return { ...jar };
+}
+
+async function getDashboardSession(port: number): Promise<{ jar: Record<string, string>; csrfHeader: string | null }> {
+  const jar: Record<string, string> = {};
+  const res = await httpRequest({ hostname: '127.0.0.1', port, path: '/', method: 'GET' });
+  updateCookieJar(jar, res.headers['set-cookie']);
+  return { jar, csrfHeader: typeof res.headers['x-csrf-token'] === 'string' ? res.headers['x-csrf-token'] : null };
+}
+
+async function postNotify(port: number, jar: Record<string, string>, extraHeaders?: Record<string, string>, body?: unknown): Promise<HttpResult> {
+  const payload = body === undefined ? { type: 'REFRESH_REQUIRED', scope: 'all' } : body;
+  const encoded = JSON.stringify(payload);
+  return httpRequest(
+    {
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/system/notify',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(Object.keys(jar).length ? { Cookie: cookieHeader(jar) } : {}),
+        ...(extraHeaders ?? {}),
+      },
+    },
+    encoded,
+  );
+}
+
+const ORIGINAL_ENV = { ...process.env };
+const serverUrl = new URL('../../dist/core/server.js', import.meta.url).href;
+const csrfManagerUrl = new URL('../../dist/core/auth/csrf-manager.js', import.meta.url).href;
+
+describe('security: CSRF protection', async () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let serverMod: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let csrfMod: any;
+
+  let server: http.Server;
+  let port: number;
+  let projectRoot: string;
+  let ccwHome: string;
+
+  before(async () => {
+    projectRoot = mkdtempSync(join(tmpdir(), 'ccw-csrf-project-'));
+    ccwHome = mkdtempSync(join(tmpdir(), 'ccw-csrf-home-'));
+
+    process.env = { ...ORIGINAL_ENV, CCW_DATA_DIR: ccwHome };
+
+    serverMod = await import(serverUrl);
+    csrfMod = await import(csrfManagerUrl);
+
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'error', () => {});
+
+    server = await serverMod.startServer({ initialPath: projectRoot, port: 0 });
+    const addr = server.address();
+    port = typeof addr === 'object' && addr ? addr.port : 0;
+    assert.ok(port > 0, 'Server should start on a valid port');
+  });
+
+  after(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    mock.restoreAll();
+    process.env = ORIGINAL_ENV;
+    rmSync(projectRoot, { recursive: true, force: true });
+    rmSync(ccwHome, { recursive: true, force: true });
+  });
+
+  it('blocks POST requests without CSRF token', async () => {
+    const { jar } = await getDashboardSession(port);
+    delete jar['XSRF-TOKEN'];
+
+    const res = await postNotify(port, jar);
+    assert.equal(res.status, 403);
+    assert.ok(res.body.includes('CSRF validation failed'));
+  });
+
+  it('blocks POST requests with forged CSRF token', async () => {
+    const { jar } = await getDashboardSession(port);
+    jar['XSRF-TOKEN'] = 'forged-token';
+
+    const res = await postNotify(port, jar);
+    assert.equal(res.status, 403);
+  });
+
+  it('blocks expired CSRF tokens', async () => {
+    csrfMod.resetCsrfTokenManager();
+    csrfMod.getCsrfTokenManager({ tokenTtlMs: 1, cleanupIntervalMs: 0 });
+
+    const { jar } = await getDashboardSession(port);
+    await new Promise(resolve => setTimeout(resolve, 10));
+
+    const res = await postNotify(port, jar);
+    assert.equal(res.status, 403);
+
+    csrfMod.resetCsrfTokenManager();
+  });
+
+  it('blocks token reuse (single-use tokens)', async () => {
+    const { jar } = await getDashboardSession(port);
+    const oldToken = jar['XSRF-TOKEN'];
+
+    const first = await postNotify(port, jar);
+    assert.equal(first.status, 200);
+    updateCookieJar(jar, first.headers['set-cookie']);
+
+    // Try again using the old token explicitly (should fail).
+    const reuseJar = cloneJar(jar);
+    reuseJar['XSRF-TOKEN'] = oldToken;
+    const secondUse = await postNotify(port, reuseJar);
+    assert.equal(secondUse.status, 403);
+  });
+
+  it('blocks CSRF token theft across sessions', async () => {
+    const sessionA = await getDashboardSession(port);
+    const sessionB = await getDashboardSession(port);
+
+    const jar = cloneJar(sessionB.jar);
+    jar['XSRF-TOKEN'] = sessionA.jar['XSRF-TOKEN'];
+
+    const res = await postNotify(port, jar);
+    assert.equal(res.status, 403);
+  });
+
+  it('does not require CSRF on GET requests', async () => {
+    const { jar } = await getDashboardSession(port);
+    const res = await httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/health',
+      method: 'GET',
+      headers: { Cookie: cookieHeader(jar) },
+    });
+    assert.equal(res.status, 200);
+  });
+
+  it('accepts CSRF token provided via cookie (legitimate flow)', async () => {
+    const { jar } = await getDashboardSession(port);
+    const res = await postNotify(port, jar);
+    assert.equal(res.status, 200);
+  });
+
+  it('accepts CSRF token provided via header', async () => {
+    const { jar } = await getDashboardSession(port);
+    const token = jar['XSRF-TOKEN'];
+    delete jar['XSRF-TOKEN'];
+
+    const res = await postNotify(port, jar, { 'X-CSRF-Token': token });
+    assert.equal(res.status, 200);
+  });
+
+  it('accepts CSRF token provided via request body', async () => {
+    const { jar } = await getDashboardSession(port);
+    const token = jar['XSRF-TOKEN'];
+    delete jar['XSRF-TOKEN'];
+
+    const res = await postNotify(port, jar, undefined, { type: 'REFRESH_REQUIRED', scope: 'all', csrfToken: token });
+    assert.equal(res.status, 200);
+  });
+
+  it('rotates CSRF token after successful POST', async () => {
+    const { jar } = await getDashboardSession(port);
+    const firstToken = jar['XSRF-TOKEN'];
+
+    const res = await postNotify(port, jar);
+    assert.equal(res.status, 200);
+    updateCookieJar(jar, res.headers['set-cookie']);
+
+    assert.notEqual(jar['XSRF-TOKEN'], firstToken);
+  });
+
+  it('allows localhost origins and rejects external origins (CORS)', async () => {
+    const allowedOrigin = `http://localhost:${port}`;
+    const allowed = await httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/health',
+      method: 'GET',
+      headers: { Origin: allowedOrigin },
+    });
+    assert.equal(allowed.headers['access-control-allow-origin'], allowedOrigin);
+    assert.equal(allowed.headers['vary'], 'Origin');
+
+    const evilOrigin = 'http://evil.com';
+    const denied = await httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/health',
+      method: 'GET',
+      headers: { Origin: evilOrigin },
+    });
+    assert.notEqual(denied.headers['access-control-allow-origin'], evilOrigin);
+    assert.equal(denied.headers['access-control-allow-origin'], `http://localhost:${port}`);
+  });
+
+  it('bypasses CSRF validation when CCW_DISABLE_CSRF=true', async () => {
+    process.env.CCW_DISABLE_CSRF = 'true';
+    const { jar } = await getDashboardSession(port);
+    delete jar['XSRF-TOKEN'];
+
+    const res = await postNotify(port, jar);
+    assert.equal(res.status, 200);
+
+    delete process.env.CCW_DISABLE_CSRF;
+  });
+
+  it('skips CSRF validation for Authorization header auth', async () => {
+    const tokenRes = await httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/auth/token',
+      method: 'GET',
+    });
+
+    const parsed = JSON.parse(tokenRes.body) as { token: string };
+    assert.ok(parsed.token);
+
+    const res = await httpRequest(
+      {
+        hostname: '127.0.0.1',
+        port,
+        path: '/api/system/notify',
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${parsed.token}`,
+          'Content-Type': 'application/json',
+        },
+      },
+      JSON.stringify({ type: 'REFRESH_REQUIRED', scope: 'all' }),
+    );
+
+    assert.equal(res.status, 200);
+  });
+});

ccw/tests/security/path-traversal.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Regression tests for path traversal protections (DSC-005).
+ *
+ * Focus:
+ * - Allowlist enforcement + boundary checks (no "/allowedness" bypass)
+ * - Symlink target re-validation via realpath
+ * - Non-existent path handling via parent-directory validation
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Uses stubbed fs + fs/promises to avoid touching real filesystem.
+ */
+
+import { after, before, beforeEach, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const fsp = require('node:fs/promises') as typeof import('node:fs/promises');
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const fs = require('node:fs') as typeof import('node:fs');
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const os = require('node:os') as typeof import('node:os');
+
+const pathValidatorUrl = new URL('../../dist/utils/path-validator.js', import.meta.url);
+pathValidatorUrl.searchParams.set('t', String(Date.now()));
+
+const pathResolverUrl = new URL('../../dist/utils/path-resolver.js', import.meta.url);
+pathResolverUrl.searchParams.set('t', String(Date.now()));
+
+const ORIGINAL_ENV = { ...process.env };
+
+function resetEnv(): void {
+  for (const key of Object.keys(process.env)) {
+    if (!(key in ORIGINAL_ENV)) delete process.env[key];
+  }
+  for (const [key, value] of Object.entries(ORIGINAL_ENV)) {
+    process.env[key] = value;
+  }
+}
+
+function enoent(message: string): Error & { code: string } {
+  const err = new Error(message) as Error & { code: string };
+  err.code = 'ENOENT';
+  return err;
+}
+
+type RealpathPlan = Map<string, { type: 'return'; value: string } | { type: 'throw'; error: any }>;
+const realpathPlan: RealpathPlan = new Map();
+const realpathCalls: string[] = [];
+
+const originalRealpath = fsp.realpath;
+fsp.realpath = (async (p: string) => {
+  realpathCalls.push(p);
+  const planned = realpathPlan.get(p);
+  if (!planned) {
+    throw enoent(`ENOENT: no such file or directory, realpath '${p}'`);
+  }
+  if (planned.type === 'throw') throw planned.error;
+  return planned.value;
+}) as any;
+
+type FsState = {
+  existing: Set<string>;
+  realpaths: Map<string, string>;
+};
+
+const fsState: FsState = {
+  existing: new Set(),
+  realpaths: new Map(),
+};
+
+function key(filePath: string): string {
+  return path.resolve(filePath).replace(/\\/g, '/').toLowerCase();
+}
+
+function setExists(filePath: string, exists: boolean): void {
+  const normalized = key(filePath);
+  if (exists) fsState.existing.add(normalized);
+  else fsState.existing.delete(normalized);
+}
+
+function setRealpath(filePath: string, realPath: string): void {
+  fsState.realpaths.set(key(filePath), realPath);
+}
+
+const originalFs = {
+  existsSync: fs.existsSync,
+  realpathSync: fs.realpathSync,
+};
+
+fs.existsSync = ((filePath: string) => fsState.existing.has(key(filePath))) as any;
+fs.realpathSync = ((filePath: string) => {
+  const mapped = fsState.realpaths.get(key(filePath));
+  return mapped ?? filePath;
+}) as any;
+
+const originalHomedir = os.homedir;
+const TEST_HOME = path.join(process.cwd(), '.tmp-ccw-security-home');
+os.homedir = () => TEST_HOME;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let pathValidator: any;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let pathResolver: any;
+
+describe('security: path traversal regression', async () => {
+  const isWindows = process.platform === 'win32';
+  const allowedRoot = isWindows ? 'C:\\allowed' : '/allowed';
+  const disallowedRoot = isWindows ? 'C:\\secret' : '/secret';
+
+  before(async () => {
+    pathValidator = await import(pathValidatorUrl.href);
+    pathResolver = await import(pathResolverUrl.href);
+  });
+
+  beforeEach(() => {
+    realpathCalls.length = 0;
+    realpathPlan.clear();
+    fsState.existing.clear();
+    fsState.realpaths.clear();
+    resetEnv();
+  });
+
+  it('path-validator rejects traversal/absolute escapes before realpath', async () => {
+    process.env.CCW_PROJECT_ROOT = allowedRoot;
+    const allowedDirectories = [allowedRoot];
+
+    const vectors: Array<{ name: string; input: string }> = [
+      { name: 'absolute outside allowlist', input: path.join(disallowedRoot, 'secret.txt') },
+      { name: 'allowed prefix but different dir (allowedness)', input: `${allowedRoot}ness${isWindows ? '\\\\' : '/'}file.txt` },
+      { name: 'allowed prefix but different dir (allowed-evil)', input: `${allowedRoot}-evil${isWindows ? '\\\\' : '/'}file.txt` },
+      { name: 'absolute contains .. segment escaping allowlist', input: `${allowedRoot}${isWindows ? '\\\\' : '/'}..${isWindows ? '\\\\' : '/'}secret.txt` },
+      { name: 'absolute multi-.. escaping allowlist', input: `${allowedRoot}${isWindows ? '\\\\' : '/'}sub${isWindows ? '\\\\' : '/'}..${isWindows ? '\\\\' : '/'}..${isWindows ? '\\\\' : '/'}secret.txt` },
+      { name: 'relative traversal one level', input: `..${isWindows ? '\\\\' : '/'}secret.txt` },
+      { name: 'relative traversal two levels', input: `..${isWindows ? '\\\\' : '/'}..${isWindows ? '\\\\' : '/'}secret.txt` },
+      { name: 'mixed separators traversal', input: `sub${isWindows ? '/' : '/'}..${isWindows ? '\\\\' : '/'}..${isWindows ? '\\\\' : '/'}secret.txt` },
+      { name: 'posix absolute escape', input: '/etc/passwd' },
+      { name: 'encoded traversal (decoded once)', input: decodeURIComponent('%2e%2e%2f%2e%2e%2fetc%2fpasswd') },
+      { name: 'double-encoded traversal (decoded twice)', input: decodeURIComponent(decodeURIComponent('%252e%252e%252f%252e%252e%252fetc%252fpasswd')) },
+      { name: 'leading dot traversal', input: `.${isWindows ? '\\\\' : '/'}..${isWindows ? '\\\\' : '/'}secret.txt` },
+      { name: 'nested traversal escape', input: 'sub/../../secret.txt' },
+      { name: 'alt-drive absolute escape', input: isWindows ? 'D:\\\\secret\\\\file.txt' : '/var/secret/file.txt' },
+      { name: 'UNC/extended path escape', input: isWindows ? '\\\\\\\\?\\\\C:\\\\secret\\\\file.txt' : '/private/secret/file.txt' },
+    ];
+
+    for (const vector of vectors) {
+      await assert.rejects(
+        pathValidator.validatePath(vector.input, { allowedDirectories }),
+        (err: any) => err instanceof Error && err.message.includes('Access denied: path'),
+        vector.name,
+      );
+    }
+
+    assert.deepEqual(realpathCalls, []);
+  });
+
+  it('path-validator enforces directory-boundary allowlists', async () => {
+    process.env.CCW_PROJECT_ROOT = allowedRoot;
+    const allowedDirectories = [path.join(allowedRoot, 'dir')];
+
+    await assert.rejects(
+      pathValidator.validatePath(path.join(allowedRoot, 'dir-malicious', 'file.txt'), { allowedDirectories }),
+      (err: any) => err instanceof Error && err.message.includes('Access denied: path'),
+    );
+
+    const okPath = path.join(allowedRoot, 'dir', 'file.txt');
+    const resolvedOk = await pathValidator.validatePath(okPath, { allowedDirectories });
+    assert.equal(pathValidator.isPathWithinAllowedDirectories(resolvedOk, allowedDirectories), true);
+  });
+
+  it('path-validator rejects symlink targets outside allowlist', async () => {
+    const linkPath = path.join(allowedRoot, 'link.txt');
+    realpathPlan.set(linkPath, { type: 'return', value: path.join(disallowedRoot, 'target.txt') });
+
+    await assert.rejects(
+      pathValidator.validatePath(linkPath, { allowedDirectories: [allowedRoot] }),
+      (err: any) => err instanceof Error && err.message.includes('symlink target'),
+    );
+  });
+
+  it('path-validator rejects non-existent paths when the parent resolves outside allowlist', async () => {
+    const linkDir = path.join(allowedRoot, 'linkdir');
+    const newFile = path.join(linkDir, 'newfile.txt');
+
+    realpathPlan.set(newFile, { type: 'throw', error: enoent('missing') });
+    realpathPlan.set(linkDir, { type: 'return', value: disallowedRoot });
+
+    await assert.rejects(
+      pathValidator.validatePath(newFile, { allowedDirectories: [allowedRoot] }),
+      (err: any) => err instanceof Error && err.message.includes('parent directory'),
+    );
+  });
+
+  it('path-resolver validates baseDir before and after symlink resolution', () => {
+    const baseDir = allowedRoot;
+    setExists(baseDir, true);
+
+    const traversal = pathResolver.validatePath(`${baseDir}${isWindows ? '\\\\' : '/'}..${isWindows ? '\\\\' : '/'}secret`, { baseDir });
+    assert.equal(traversal.valid, false);
+    assert.ok(traversal.error?.includes('Path must be within'));
+
+    const linkPath = path.join(baseDir, 'link');
+    setExists(linkPath, true);
+    setRealpath(linkPath, disallowedRoot);
+    const symlinkEscape = pathResolver.validatePath(linkPath, { baseDir });
+    assert.equal(symlinkEscape.valid, false);
+    assert.ok(symlinkEscape.error?.includes('Path must be within'));
+
+    setExists(linkPath, true);
+    const symlinkParentEscape = pathResolver.validatePath(path.join(linkPath, 'newfile.txt'), { baseDir });
+    assert.equal(symlinkParentEscape.valid, false);
+    assert.ok(symlinkParentEscape.error?.includes('Path must be within'));
+  });
+});
+
+after(() => {
+  fsp.realpath = originalRealpath;
+  fs.existsSync = originalFs.existsSync;
+  fs.realpathSync = originalFs.realpathSync;
+  os.homedir = originalHomedir;
+  resetEnv();
+});

ccw/tests/server-auth.integration.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Integration tests for server authentication flow.
+ *
+ * Verifies:
+ * - API routes require auth token
+ * - /api/auth/token returns token + cookie for localhost requests
+ * - Authorization header and cookie auth both work
+ */
+
+import { after, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+type HttpResult = {
+  status: number;
+  body: string;
+  headers: http.IncomingHttpHeaders;
+};
+
+function httpRequest(options: http.RequestOptions, body?: string, timeout = 10000): Promise<HttpResult> {
+  return new Promise((resolve, reject) => {
+    const req = http.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve({ status: res.statusCode || 0, body: data, headers: res.headers }));
+    });
+    req.on('error', reject);
+    req.setTimeout(timeout, () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+const ORIGINAL_ENV = { ...process.env };
+const serverUrl = new URL('../dist/core/server.js', import.meta.url);
+serverUrl.searchParams.set('t', String(Date.now()));
+
+describe('server authentication integration', async () => {
+  let server: http.Server;
+  let port: number;
+  let projectRoot: string;
+  let ccwHome: string;
+
+  before(async () => {
+    projectRoot = mkdtempSync(join(tmpdir(), 'ccw-auth-project-'));
+    ccwHome = mkdtempSync(join(tmpdir(), 'ccw-auth-home-'));
+
+    process.env = { ...ORIGINAL_ENV, CCW_DATA_DIR: ccwHome };
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const serverMod: any = await import(serverUrl.href);
+
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'error', () => {});
+
+    server = await serverMod.startServer({ initialPath: projectRoot, port: 0 });
+    const addr = server.address();
+    port = typeof addr === 'object' && addr ? addr.port : 0;
+    assert.ok(port > 0, 'Server should start on a valid port');
+  });
+
+  after(async () => {
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+    mock.restoreAll();
+    process.env = ORIGINAL_ENV;
+    rmSync(projectRoot, { recursive: true, force: true });
+    rmSync(ccwHome, { recursive: true, force: true });
+  });
+
+  it('rejects unauthenticated API requests with 401', async () => {
+    const response = await httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/health',
+      method: 'GET',
+    });
+
+    assert.equal(response.status, 401);
+    assert.ok(response.body.includes('Unauthorized'));
+  });
+
+  it('returns auth token and cookie for localhost requests', async () => {
+    const response = await httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/auth/token',
+      method: 'GET',
+    });
+
+    assert.equal(response.status, 200);
+    const data = JSON.parse(response.body) as { token: string; expiresAt: string };
+    assert.ok(data.token);
+    assert.ok(data.expiresAt);
+
+    const setCookie = response.headers['set-cookie'];
+    assert.ok(setCookie && setCookie.length > 0, 'Expected Set-Cookie header');
+  });
+
+  it('accepts Authorization header on API routes', async () => {
+    const tokenResponse = await httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/auth/token',
+      method: 'GET',
+    });
+
+    const { token } = JSON.parse(tokenResponse.body) as { token: string };
+    const response = await httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/health',
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    });
+
+    assert.equal(response.status, 200);
+  });
+
+  it('accepts cookie auth on API routes', async () => {
+    const tokenResponse = await httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/auth/token',
+      method: 'GET',
+    });
+
+    const { token } = JSON.parse(tokenResponse.body) as { token: string };
+    const response = await httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/health',
+      method: 'GET',
+      headers: {
+        Cookie: `auth_token=${encodeURIComponent(token)}`,
+      },
+    });
+
+    assert.equal(response.status, 200);
+  });
+});
+

ccw/tests/server.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Unit tests for server binding defaults and host option plumbing.
+ */
+
+import { afterEach, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const ORIGINAL_ENV = { ...process.env };
+
+const serverUrl = new URL('../dist/core/server.js', import.meta.url);
+serverUrl.searchParams.set('t', String(Date.now()));
+
+const serveUrl = new URL('../dist/commands/serve.js', import.meta.url);
+serveUrl.searchParams.set('t', String(Date.now()));
+
+describe('server binding', async () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let serverMod: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let serveMod: any;
+
+  before(async () => {
+    serverMod = await import(serverUrl.href);
+    serveMod = await import(serveUrl.href);
+  });
+
+  afterEach(() => {
+    mock.restoreAll();
+    process.env = ORIGINAL_ENV;
+  });
+
+  it('binds to 127.0.0.1 by default', async () => {
+    const ccwHome = mkdtempSync(join(tmpdir(), 'ccw-server-bind-home-'));
+    process.env = { ...ORIGINAL_ENV, CCW_DATA_DIR: ccwHome };
+
+    const listenCalls: any[] = [];
+    const originalListen = http.Server.prototype.listen;
+
+    mock.method(http.Server.prototype as any, 'listen', function (this: any, ...args: any[]) {
+      listenCalls.push(args);
+      return (originalListen as any).apply(this, args);
+    });
+
+    const server: http.Server = await serverMod.startServer({ initialPath: process.cwd(), port: 0 });
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+
+    rmSync(ccwHome, { recursive: true, force: true });
+
+    assert.ok(listenCalls.length > 0, 'Expected server.listen to be called');
+    assert.equal(listenCalls[0][1], '127.0.0.1');
+  });
+
+  it('passes host option through serve command', async () => {
+    const ccwHome = mkdtempSync(join(tmpdir(), 'ccw-serve-bind-home-'));
+    process.env = { ...ORIGINAL_ENV, CCW_DATA_DIR: ccwHome };
+
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'error', () => {});
+
+    let sigintHandler: (() => void) | null = null;
+    const originalOn = process.on.bind(process);
+    mock.method(process as any, 'on', (event: string, handler: any) => {
+      if (event === 'SIGINT') {
+        sigintHandler = handler;
+        return process;
+      }
+      return originalOn(event, handler);
+    });
+
+    const exitCodes: Array<number | undefined> = [];
+    mock.method(process as any, 'exit', (code?: number) => {
+      exitCodes.push(code);
+    });
+
+    const listenCalls: any[] = [];
+    const originalListen = http.Server.prototype.listen;
+    mock.method(http.Server.prototype as any, 'listen', function (this: any, ...args: any[]) {
+      listenCalls.push(args);
+      return (originalListen as any).apply(this, args);
+    });
+
+    await serveMod.serveCommand({ port: 0, browser: false, path: process.cwd(), host: '0.0.0.0' });
+    assert.ok(sigintHandler, 'Expected serveCommand to register SIGINT handler');
+
+    sigintHandler?.();
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    rmSync(ccwHome, { recursive: true, force: true });
+
+    assert.ok(exitCodes.includes(0));
+    assert.ok(listenCalls.some((args) => args[1] === '0.0.0.0'));
+  });
+});
+

ccw/tests/shell-escape.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Unit tests for Windows cmd.exe argument escaping (ccw/dist/utils/shell-escape.js)
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+const shellEscapeUrl = new URL('../dist/utils/shell-escape.js', import.meta.url).href;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+describe('escapeWindowsArg', async () => {
+  mod = await import(shellEscapeUrl);
+
+  it('escapes cmd.exe metacharacters with caret', () => {
+    const cases: Array<{ input: string; expected: string }> = [
+      { input: 'arg|command', expected: 'arg^|command' },
+      { input: 'arg&command', expected: 'arg^&command' },
+      { input: 'arg&&command', expected: 'arg^&^&command' },
+      { input: 'arg||command', expected: 'arg^|^|command' },
+      { input: 'arg>out.txt', expected: 'arg^>out.txt' },
+      { input: 'arg>>out.txt', expected: 'arg^>^>out.txt' },
+      { input: 'arg<input.txt', expected: 'arg^<input.txt' },
+      { input: '(test)', expected: '^(test^)' },
+      { input: '%PATH%', expected: '^%PATH^%' },
+      { input: '!VAR!', expected: '^!VAR^!' },
+      { input: 'arg"cmd', expected: 'arg^"cmd' },
+      { input: 'a^b', expected: 'a^^b' },
+    ];
+
+    for (const { input, expected } of cases) {
+      assert.equal(mod.escapeWindowsArg(input), expected, `escapeWindowsArg(${JSON.stringify(input)})`);
+    }
+  });
+
+  it('wraps whitespace-containing args in double quotes', () => {
+    assert.equal(mod.escapeWindowsArg('hello world'), '"hello world"');
+    assert.equal(mod.escapeWindowsArg('test & echo'), '"test ^& echo"');
+    assert.equal(mod.escapeWindowsArg('a|b c'), '"a^|b c"');
+  });
+
+  it('handles empty arguments', () => {
+    assert.equal(mod.escapeWindowsArg(''), '""');
+  });
+});
+

ccw/tests/skills-routes.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Integration tests for skills routes path validation.
+ *
+ * Notes:
+ * - Targets runtime implementation shipped in `ccw/dist`.
+ * - Focuses on access control for projectPath and traversal attempts.
+ */
+
+import { after, before, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const PROJECT_ROOT = mkdtempSync(join(tmpdir(), 'ccw-skills-routes-project-'));
+const OUTSIDE_ROOT = mkdtempSync(join(tmpdir(), 'ccw-skills-routes-outside-'));
+
+const skillsRoutesUrl = new URL('../dist/core/routes/skills-routes.js', import.meta.url);
+skillsRoutesUrl.searchParams.set('t', String(Date.now()));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+type JsonResponse = { status: number; json: any; text: string };
+
+async function requestJson(baseUrl: string, method: string, path: string, body?: unknown): Promise<JsonResponse> {
+  const url = new URL(path, baseUrl);
+  const payload = body === undefined ? null : Buffer.from(JSON.stringify(body), 'utf8');
+
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      url,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          ...(payload ? { 'Content-Type': 'application/json', 'Content-Length': String(payload.length) } : {}),
+        },
+      },
+      (res) => {
+        let responseBody = '';
+        res.on('data', (chunk) => {
+          responseBody += chunk.toString();
+        });
+        res.on('end', () => {
+          let json: any = null;
+          try {
+            json = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            json = null;
+          }
+          resolve({ status: res.statusCode || 0, json, text: responseBody });
+        });
+      },
+    );
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+function handlePostRequest(req: http.IncomingMessage, res: http.ServerResponse, handler: (body: unknown) => Promise<any>): void {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', async () => {
+    try {
+      const parsed = body ? JSON.parse(body) : {};
+      const result = await handler(parsed);
+
+      if (result?.error) {
+        res.writeHead(result.status || 500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error }));
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+}
+
+async function createServer(initialPath: string): Promise<{ server: http.Server; baseUrl: string }> {
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const pathname = url.pathname;
+
+    const ctx = {
+      pathname,
+      url,
+      req,
+      res,
+      initialPath,
+      handlePostRequest,
+      broadcastToClients() {},
+    };
+
+    try {
+      const handled = await mod.handleSkillsRoutes(ctx);
+      if (!handled) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not Found' }));
+      }
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err?.message || String(err) }));
+    }
+  });
+
+  await new Promise<void>((resolve) => server.listen(0, () => resolve()));
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : 0;
+  return { server, baseUrl: `http://127.0.0.1:${port}` };
+}
+
+describe('skills routes path validation', async () => {
+  before(async () => {
+    mock.method(console, 'log', () => {});
+    mock.method(console, 'error', () => {});
+    mod = await import(skillsRoutesUrl.href);
+  });
+
+  after(() => {
+    mock.restoreAll();
+    rmSync(PROJECT_ROOT, { recursive: true, force: true });
+    rmSync(OUTSIDE_ROOT, { recursive: true, force: true });
+  });
+
+  it('GET /api/skills rejects projectPath outside initialPath', async () => {
+    const { server, baseUrl } = await createServer(PROJECT_ROOT);
+    try {
+      const res = await requestJson(baseUrl, 'GET', `/api/skills?path=${encodeURIComponent(OUTSIDE_ROOT)}`);
+      assert.equal(res.status, 403);
+      assert.equal(res.json.error, 'Access denied');
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it('GET /api/skills/:name/dir rejects traversal via subpath', async () => {
+    const { server, baseUrl } = await createServer(PROJECT_ROOT);
+    try {
+      const subpath = encodeURIComponent('../..');
+      const pathParam = encodeURIComponent(PROJECT_ROOT);
+      const res = await requestJson(baseUrl, 'GET', `/api/skills/demo/dir?subpath=${subpath}&path=${pathParam}&location=project`);
+      assert.equal(res.status, 403);
+      assert.equal(res.json.error, 'Access denied');
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it('GET /api/skills/:name rejects traversal via path segment', async () => {
+    const { server, baseUrl } = await createServer(PROJECT_ROOT);
+    try {
+      const res = await requestJson(baseUrl, 'GET', '/api/skills/../../secret?location=project');
+      assert.equal(res.status, 403);
+      assert.equal(res.json.error, 'Access denied');
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it('GET /api/skills/:name/dir rejects unsafe skill names', async () => {
+    const { server, baseUrl } = await createServer(PROJECT_ROOT);
+    try {
+      const pathParam = encodeURIComponent(PROJECT_ROOT);
+      const res = await requestJson(baseUrl, 'GET', `/api/skills/${encodeURIComponent('bad..name')}/dir?path=${pathParam}&location=project`);
+      assert.equal(res.status, 400);
+      assert.ok(String(res.json.error).includes('Invalid skill name'));
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+});

ccw/tests/token-manager.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Unit tests for TokenManager authentication helper.
+ *
+ * Notes:
+ * - Targets the runtime implementation shipped in `ccw/dist`.
+ * - Uses in-memory fs stubs (no real file IO).
+ */
+
+import { after, beforeEach, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const fs = require('node:fs') as typeof import('node:fs');
+
+const ORIGINAL_ENV = { ...process.env };
+const TEST_CCW_HOME = path.join(process.cwd(), '.tmp-ccw-auth-home');
+process.env.CCW_DATA_DIR = TEST_CCW_HOME;
+
+type FsState = {
+  existing: Set<string>;
+  files: Map<string, string>;
+  mkdirCalls: Array<{ path: string; options: unknown }>;
+  writeCalls: Array<{ path: string; data: string; options: unknown }>;
+  chmodCalls: Array<{ path: string; mode: number }>;
+};
+
+const state: FsState = {
+  existing: new Set(),
+  files: new Map(),
+  mkdirCalls: [],
+  writeCalls: [],
+  chmodCalls: [],
+};
+
+function key(filePath: string): string {
+  return path.resolve(filePath).replace(/\\/g, '/').toLowerCase();
+}
+
+function setExists(filePath: string): void {
+  state.existing.add(key(filePath));
+}
+
+function setFile(filePath: string, content: string): void {
+  const normalized = key(filePath);
+  state.files.set(normalized, content);
+  state.existing.add(normalized);
+}
+
+const originalFs = {
+  existsSync: fs.existsSync,
+  mkdirSync: fs.mkdirSync,
+  readFileSync: fs.readFileSync,
+  writeFileSync: fs.writeFileSync,
+  chmodSync: fs.chmodSync,
+};
+
+fs.existsSync = ((filePath: string) => state.existing.has(key(filePath))) as any;
+fs.mkdirSync = ((dirPath: string, options: unknown) => {
+  state.mkdirCalls.push({ path: dirPath, options });
+  setExists(dirPath);
+}) as any;
+fs.readFileSync = ((filePath: string, encoding: string) => {
+  assert.equal(encoding, 'utf8');
+  const content = state.files.get(key(filePath));
+  if (content !== undefined) return content;
+
+  // Allow Node/third-party modules (e.g., jsonwebtoken) to load normally.
+  return originalFs.readFileSync(filePath, encoding);
+}) as any;
+fs.writeFileSync = ((filePath: string, data: string, options: unknown) => {
+  state.writeCalls.push({ path: filePath, data: String(data), options });
+  setFile(filePath, String(data));
+}) as any;
+fs.chmodSync = ((filePath: string, mode: number) => {
+  state.chmodCalls.push({ path: filePath, mode });
+}) as any;
+
+const tokenManagerUrl = new URL('../dist/core/auth/token-manager.js', import.meta.url).href;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mod: any;
+
+beforeEach(() => {
+  state.existing.clear();
+  state.files.clear();
+  state.mkdirCalls.length = 0;
+  state.writeCalls.length = 0;
+  state.chmodCalls.length = 0;
+});
+
+describe('TokenManager authentication helper', async () => {
+  mod = await import(tokenManagerUrl);
+
+  it('generateToken produces a valid HS256 JWT with 24h expiry', () => {
+    const manager = new mod.TokenManager();
+    const secret = 's'.repeat(64);
+    const now = Date.now();
+
+    const result = manager.generateToken(secret);
+    assert.ok(result.token.includes('.'));
+    assert.ok(result.expiresAt instanceof Date);
+
+    const [headerB64] = result.token.split('.');
+    const header = JSON.parse(Buffer.from(headerB64, 'base64url').toString('utf8')) as { alg?: string };
+    assert.equal(header.alg, 'HS256');
+
+    const msUntilExpiry = result.expiresAt.getTime() - now;
+    assert.ok(msUntilExpiry > 23 * 60 * 60 * 1000);
+    assert.ok(msUntilExpiry < 24 * 60 * 60 * 1000 + 60 * 1000);
+  });
+
+  it('validateToken accepts correct secret and rejects wrong secret', () => {
+    const manager = new mod.TokenManager();
+    const secret = 'my-secret';
+    const { token } = manager.generateToken(secret);
+
+    assert.equal(manager.validateToken(token, secret), true);
+    assert.equal(manager.validateToken(token, 'wrong-secret'), false);
+  });
+
+  it('validateToken rejects expired tokens', () => {
+    const manager = new mod.TokenManager({ tokenTtlMs: -1000 });
+    const secret = 'my-secret';
+    const { token } = manager.generateToken(secret);
+
+    assert.equal(manager.validateToken(token, secret), false);
+  });
+
+  it('persists and reloads secret key with restrictive permissions', () => {
+    const authDir = path.join(TEST_CCW_HOME, 'auth');
+    const secretPath = path.join(authDir, 'secret.key');
+
+    const manager1 = new mod.TokenManager({ authDir, secretKeyPath: secretPath });
+    const secret1 = manager1.getSecretKey();
+
+    assert.equal(secret1.length, 64); // 32 bytes hex
+    assert.equal(state.writeCalls.length, 1);
+    assert.equal(state.writeCalls[0].path, secretPath);
+    assert.deepEqual(state.writeCalls[0].options, { encoding: 'utf8', mode: 0o600 });
+    assert.deepEqual(state.chmodCalls, [{ path: secretPath, mode: 0o600 }]);
+
+    const manager2 = new mod.TokenManager({ authDir, secretKeyPath: secretPath });
+    const secret2 = manager2.getSecretKey();
+    assert.equal(secret2, secret1);
+  });
+
+  it('rotates token before expiry and persists updated token', () => {
+    const authDir = path.join(TEST_CCW_HOME, 'auth');
+    const tokenPath = path.join(authDir, 'token.jwt');
+
+    const manager = new mod.TokenManager({
+      authDir,
+      tokenPath,
+      tokenTtlMs: 1000,
+      rotateBeforeExpiryMs: 2000,
+    });
+
+    const first = manager.getOrCreateAuthToken();
+    const tokenFileFirst = state.files.get(key(tokenPath));
+    assert.equal(tokenFileFirst, first.token);
+
+    const second = manager.getOrCreateAuthToken();
+    const tokenFileSecond = state.files.get(key(tokenPath));
+    assert.equal(tokenFileSecond, second.token);
+    assert.notEqual(second.token, first.token);
+  });
+});
+
+after(() => {
+  fs.existsSync = originalFs.existsSync;
+  fs.mkdirSync = originalFs.mkdirSync;
+  fs.readFileSync = originalFs.readFileSync;
+  fs.writeFileSync = originalFs.writeFileSync;
+  fs.chmodSync = originalFs.chmodSync;
+  process.env = ORIGINAL_ENV;
+});