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>
2026-02-09 02:24:11 +08:00 · 2026-01-07 22:35:46 +08:00
parent fae2f7e279
commit 09d99abee6
100 changed files with 14300 additions and 6456 deletions
--- a/ccw/src/tools/README.md
+++ b/ccw/src/tools/README.md
@@ -0,0 +1,29 @@
+# Tools
+
+This directory contains CCW “tools”: self-contained modules that implement concrete functionality (executors, integrations, etc.) that higher-level CLI and route layers call into.
+
+## CLI Executor
+
+The CLI executor is split into focused modules to keep responsibilities clear and keep the public API stable via re-exports.
+
+**Entry point**
+- `ccw/src/tools/cli-executor.ts` – thin facade that re-exports from `cli-executor-core.ts` (stable import path for callers).
+
+**Modules**
+- `ccw/src/tools/cli-executor-core.ts` – orchestrates tool execution, resume/merge logic, and conversation persistence wiring.
+- `ccw/src/tools/cli-executor-utils.ts` – debug logging, tool availability checks (with cache), command building.
+- `ccw/src/tools/cli-executor-state.ts` – conversation/history types + SQLite-backed storage helpers.
+- `ccw/src/tools/cli-prompt-builder.ts` – prompt concatenation helpers (plain/YAML/JSON) and merged-conversation prompt formatting.
+
+**Dependency flow (high level)**
+```
+cli-executor.ts
+  -> cli-executor-core.ts
+      -> cli-executor-utils.ts
+      -> cli-executor-state.ts
+      -> cli-prompt-builder.ts
+```
+
+**Public API**
+- Prefer importing from `ccw/src/tools/cli-executor.ts`.
+- `cli-executor-core.ts` re-exports prompt helpers/types from `cli-prompt-builder.ts` to preserve existing imports (`PromptConcatenator`, `buildPrompt`, `PromptFormat`, etc.).
--- a/ccw/src/tools/cli-executor-core.ts
+++ b/ccw/src/tools/cli-executor-core.ts
--- a/ccw/src/tools/cli-executor-state.ts
+++ b/ccw/src/tools/cli-executor-state.ts
@@ -0,0 +1,553 @@
+/**
+ * CLI Executor State
+ * Conversation history + execution record storage (SQLite-backed)
+ */
+
+import type { HistoryIndexEntry } from './cli-history-store.js';
+import { StoragePaths, ensureStorageDir } from '../config/storage-paths.js';
+
+// Lazy-loaded SQLite store module
+let sqliteStoreModule: typeof import('./cli-history-store.js') | null = null;
+
+/**
+ * Get or initialize SQLite store (async)
+ */
+export async function getSqliteStore(baseDir: string) {
+  if (!sqliteStoreModule) {
+    sqliteStoreModule = await import('./cli-history-store.js');
+  }
+  return sqliteStoreModule.getHistoryStore(baseDir);
+}
+
+/**
+ * Get SQLite store (sync - uses cached module)
+ */
+function getSqliteStoreSync(baseDir: string) {
+  if (!sqliteStoreModule) {
+    throw new Error('SQLite store not initialized. Call an async function first.');
+  }
+  return sqliteStoreModule.getHistoryStore(baseDir);
+}
+
+// Execution category types
+export type ExecutionCategory = 'user' | 'internal' | 'insight';
+
+// Single turn in a conversation
+export interface ConversationTurn {
+  turn: number;
+  timestamp: string;
+  prompt: string;
+  duration_ms: number;
+  status: 'success' | 'error' | 'timeout';
+  exit_code: number | null;
+  output: {
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+  };
+}
+
+// Multi-turn conversation record
+export interface ConversationRecord {
+  id: string;
+  created_at: string;
+  updated_at: string;
+  tool: string;
+  model: string;
+  mode: string;
+  category: ExecutionCategory; // user | internal | insight
+  total_duration_ms: number;
+  turn_count: number;
+  latest_status: 'success' | 'error' | 'timeout';
+  turns: ConversationTurn[];
+  parent_execution_id?: string; // For fork/retry scenarios
+}
+
+// Legacy single execution record (for backward compatibility)
+export interface ExecutionRecord {
+  id: string;
+  timestamp: string;
+  tool: string;
+  model: string;
+  mode: string;
+  prompt: string;
+  status: 'success' | 'error' | 'timeout';
+  exit_code: number | null;
+  duration_ms: number;
+  output: {
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+  };
+}
+
+interface HistoryIndex {
+  version: number;
+  total_executions: number;
+  executions: {
+    id: string;
+    timestamp: string;      // created_at for conversations
+    updated_at?: string;    // last update time
+    tool: string;
+    status: string;
+    duration_ms: number;
+    turn_count?: number;    // number of turns in conversation
+    prompt_preview: string;
+  }[];
+}
+
+export interface ExecutionOutput {
+  success: boolean;
+  execution: ExecutionRecord;
+  conversation: ConversationRecord;  // Full conversation record
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Ensure history directory exists (uses centralized storage)
+ */
+export function ensureHistoryDir(baseDir: string): string {
+  const paths = StoragePaths.project(baseDir);
+  ensureStorageDir(paths.cliHistory);
+  return paths.cliHistory;
+}
+
+/**
+ * Save conversation to SQLite
+ * @param baseDir - Project base directory (NOT historyDir)
+ */
+async function saveConversationAsync(baseDir: string, conversation: ConversationRecord): Promise<void> {
+  const store = await getSqliteStore(baseDir);
+  store.saveConversation(conversation);
+}
+
+/**
+ * Sync wrapper for saveConversation (uses cached SQLite module)
+ * @param baseDir - Project base directory (NOT historyDir)
+ */
+export function saveConversation(baseDir: string, conversation: ConversationRecord): void {
+  try {
+    const store = getSqliteStoreSync(baseDir);
+    store.saveConversation(conversation);
+  } catch {
+    // If sync not available, queue for async save
+    saveConversationAsync(baseDir, conversation).catch(err => {
+      console.error('[CLI Executor] Failed to save conversation:', err.message);
+    });
+  }
+}
+
+/**
+ * Load existing conversation by ID from SQLite
+ * @param baseDir - Project base directory (NOT historyDir)
+ */
+async function loadConversationAsync(baseDir: string, conversationId: string): Promise<ConversationRecord | null> {
+  const store = await getSqliteStore(baseDir);
+  return store.getConversation(conversationId);
+}
+
+/**
+ * Sync wrapper for loadConversation (uses cached SQLite module)
+ * @param baseDir - Project base directory (NOT historyDir)
+ */
+export function loadConversation(baseDir: string, conversationId: string): ConversationRecord | null {
+  try {
+    const store = getSqliteStoreSync(baseDir);
+    return store.getConversation(conversationId);
+  } catch {
+    // SQLite not initialized yet, return null
+    return null;
+  }
+}
+
+/**
+ * Convert legacy ExecutionRecord to ConversationRecord
+ */
+export function convertToConversation(record: ExecutionRecord): ConversationRecord {
+  return {
+    id: record.id,
+    created_at: record.timestamp,
+    updated_at: record.timestamp,
+    tool: record.tool,
+    model: record.model,
+    mode: record.mode,
+    category: 'user', // Legacy records default to user category
+    total_duration_ms: record.duration_ms,
+    turn_count: 1,
+    latest_status: record.status,
+    turns: [{
+      turn: 1,
+      timestamp: record.timestamp,
+      prompt: record.prompt,
+      duration_ms: record.duration_ms,
+      status: record.status,
+      exit_code: record.exit_code,
+      output: record.output
+    }]
+  };
+}
+
+/**
+ * Get execution history from SQLite (centralized storage)
+ */
+export async function getExecutionHistoryAsync(baseDir: string, options: {
+  limit?: number;
+  tool?: string | null;
+  status?: string | null;
+  category?: ExecutionCategory | null;
+  search?: string | null;
+  recursive?: boolean;
+} = {}): Promise<{
+  total: number;
+  count: number;
+  executions: (HistoryIndex['executions'][0] & { sourceDir?: string })[];
+}> {
+  const { limit = 50, tool = null, status = null, category = null, search = null, recursive = false } = options;
+
+  // Recursive mode: aggregate data from parent and all child projects
+  if (recursive) {
+    const { scanChildProjectsAsync } = await import('../config/storage-paths.js');
+    const childProjects = await scanChildProjectsAsync(baseDir);
+
+    let allExecutions: (HistoryIndex['executions'][0] & { sourceDir?: string })[] = [];
+    let totalCount = 0;
+
+    // Query parent project - apply limit at source to reduce memory footprint
+    try {
+      const parentStore = await getSqliteStore(baseDir);
+      const parentResult = parentStore.getHistory({ limit, tool, status, category, search });
+      totalCount += parentResult.total;
+
+      for (const exec of parentResult.executions) {
+        allExecutions.push({ ...exec, sourceDir: baseDir });
+      }
+    } catch (error) {
+      if (process.env.DEBUG) {
+        console.error(`[CLI History] Failed to query parent project ${baseDir}:`, error);
+      }
+    }
+
+    // Query all child projects - apply limit to each child
+    for (const child of childProjects) {
+      try {
+        const childStore = await getSqliteStore(child.projectPath);
+        const childResult = childStore.getHistory({ limit, tool, status, category, search });
+        totalCount += childResult.total;
+
+        for (const exec of childResult.executions) {
+          allExecutions.push({
+            ...exec,
+            sourceDir: child.relativePath // Show relative path for clarity
+          });
+        }
+      } catch (error) {
+        if (process.env.DEBUG) {
+          console.error(`[CLI History] Failed to query child project ${child.projectPath}:`, error);
+        }
+      }
+    }
+
+    // Sort by timestamp (newest first) and apply limit
+    allExecutions.sort((a, b) => Number(b.timestamp) - Number(a.timestamp));
+    const limitedExecutions = allExecutions.slice(0, limit);
+
+    return {
+      total: totalCount,
+      count: limitedExecutions.length,
+      executions: limitedExecutions
+    };
+  }
+
+  // Non-recursive mode: only query current project
+  const store = await getSqliteStore(baseDir);
+  return store.getHistory({ limit, tool, status, category, search });
+}
+
+/**
+ * Get execution history (sync version - uses cached SQLite module)
+ */
+export function getExecutionHistory(baseDir: string, options: {
+  limit?: number;
+  tool?: string | null;
+  status?: string | null;
+  recursive?: boolean;
+} = {}): {
+  total: number;
+  count: number;
+  executions: (HistoryIndex['executions'][0] & { sourceDir?: string })[];
+} {
+  const { limit = 50, tool = null, status = null, recursive = false } = options;
+
+  try {
+    if (recursive) {
+      const { scanChildProjects } = require('../config/storage-paths.js');
+      const childProjects = scanChildProjects(baseDir);
+
+      let allExecutions: (HistoryIndex['executions'][0] & { sourceDir?: string })[] = [];
+      let totalCount = 0;
+
+      // Query parent project - apply limit at source
+      try {
+        const parentStore = getSqliteStoreSync(baseDir);
+        const parentResult = parentStore.getHistory({ limit, tool, status });
+        totalCount += parentResult.total;
+
+        for (const exec of parentResult.executions) {
+          allExecutions.push({ ...exec, sourceDir: baseDir });
+        }
+      } catch (error) {
+        if (process.env.DEBUG) {
+          console.error(`[CLI History] Failed to query parent project ${baseDir}:`, error);
+        }
+      }
+
+      // Query all child projects - apply limit to each child
+      for (const child of childProjects) {
+        try {
+          const childStore = getSqliteStoreSync(child.projectPath);
+          const childResult = childStore.getHistory({ limit, tool, status });
+          totalCount += childResult.total;
+
+          for (const exec of childResult.executions) {
+            allExecutions.push({
+              ...exec,
+              sourceDir: child.relativePath // Show relative path for clarity
+            });
+          }
+        } catch (error) {
+          if (process.env.DEBUG) {
+            console.error(`[CLI History] Failed to query child project ${child.projectPath}:`, error);
+          }
+        }
+      }
+
+      // Sort by timestamp (newest first) and apply limit
+      allExecutions.sort((a, b) => Number(b.timestamp) - Number(a.timestamp));
+      const limitedExecutions = allExecutions.slice(0, limit);
+
+      return {
+        total: totalCount,
+        count: limitedExecutions.length,
+        executions: limitedExecutions
+      };
+    }
+
+    const store = getSqliteStoreSync(baseDir);
+    return store.getHistory({ limit, tool, status });
+  } catch {
+    // SQLite not initialized yet, return empty
+    return { total: 0, count: 0, executions: [] };
+  }
+}
+
+/**
+ * Get conversation detail by ID
+ */
+export function getConversationDetail(baseDir: string, conversationId: string): ConversationRecord | null {
+  // Pass baseDir directly - loadConversation will resolve the correct storage path
+  return loadConversation(baseDir, conversationId);
+}
+
+/**
+ * Get conversation detail with native session mapping info
+ */
+export function getConversationDetailWithNativeInfo(baseDir: string, conversationId: string) {
+  try {
+    const store = getSqliteStoreSync(baseDir);
+    return store.getConversationWithNativeInfo(conversationId);
+  } catch {
+    // SQLite not initialized, return null
+    return null;
+  }
+}
+
+/**
+ * Get execution detail by ID (legacy, returns ExecutionRecord for backward compatibility)
+ */
+export function getExecutionDetail(baseDir: string, executionId: string): ExecutionRecord | null {
+  const conversation = getConversationDetail(baseDir, executionId);
+  if (!conversation) return null;
+
+  // Convert to legacy ExecutionRecord format (using latest turn)
+  const latestTurn = conversation.turns[conversation.turns.length - 1];
+  return {
+    id: conversation.id,
+    timestamp: conversation.created_at,
+    tool: conversation.tool,
+    model: conversation.model,
+    mode: conversation.mode,
+    prompt: latestTurn.prompt,
+    status: conversation.latest_status,
+    exit_code: latestTurn.exit_code,
+    duration_ms: conversation.total_duration_ms,
+    output: latestTurn.output
+  };
+}
+
+/**
+ * Delete execution by ID (async version)
+ */
+export async function deleteExecutionAsync(baseDir: string, executionId: string): Promise<{ success: boolean; error?: string }> {
+  const store = await getSqliteStore(baseDir);
+  return store.deleteConversation(executionId);
+}
+
+/**
+ * Delete execution by ID (sync version - uses cached SQLite module)
+ */
+export function deleteExecution(baseDir: string, executionId: string): { success: boolean; error?: string } {
+  try {
+    const store = getSqliteStoreSync(baseDir);
+    return store.deleteConversation(executionId);
+  } catch {
+    return { success: false, error: 'SQLite store not initialized' };
+  }
+}
+
+/**
+ * Batch delete executions (async)
+ */
+export async function batchDeleteExecutionsAsync(baseDir: string, ids: string[]): Promise<{
+  success: boolean;
+  deleted: number;
+  total: number;
+  errors?: string[];
+}> {
+  const store = await getSqliteStore(baseDir);
+  const result = store.batchDelete(ids);
+  return { ...result, total: ids.length };
+}
+
+/**
+ * Get latest execution for a specific tool
+ */
+export function getLatestExecution(baseDir: string, tool?: string): ExecutionRecord | null {
+  const history = getExecutionHistory(baseDir, { limit: 1, tool: tool || null });
+  if (history.executions.length === 0) {
+    return null;
+  }
+  return getExecutionDetail(baseDir, history.executions[0].id);
+}
+
+// ========== Native Session Content Functions ==========
+
+/**
+ * Get native session content by CCW ID
+ * Parses the native session file and returns full conversation data
+ */
+export async function getNativeSessionContent(baseDir: string, ccwId: string) {
+  const store = await getSqliteStore(baseDir);
+  return store.getNativeSessionContent(ccwId);
+}
+
+/**
+ * Get formatted native conversation text
+ */
+export async function getFormattedNativeConversation(baseDir: string, ccwId: string, options?: {
+  includeThoughts?: boolean;
+  includeToolCalls?: boolean;
+  includeTokens?: boolean;
+  maxContentLength?: number;
+}) {
+  const store = await getSqliteStore(baseDir);
+  return store.getFormattedNativeConversation(ccwId, options);
+}
+
+/**
+ * Get conversation pairs from native session
+ */
+export async function getNativeConversationPairs(baseDir: string, ccwId: string) {
+  const store = await getSqliteStore(baseDir);
+  return store.getNativeConversationPairs(ccwId);
+}
+
+/**
+ * Get enriched conversation (CCW + native session merged)
+ */
+export async function getEnrichedConversation(baseDir: string, ccwId: string) {
+  const store = await getSqliteStore(baseDir);
+  return store.getEnrichedConversation(ccwId);
+}
+
+/**
+ * Get history with native session info
+ * Supports recursive querying of child projects
+ */
+export async function getHistoryWithNativeInfo(baseDir: string, options?: {
+  limit?: number;
+  offset?: number;
+  tool?: string | null;
+  status?: string | null;
+  category?: ExecutionCategory | null;
+  search?: string | null;
+  recursive?: boolean;
+}) {
+  const { limit = 50, recursive = false, ...queryOptions } = options || {};
+
+  // Non-recursive mode: query single project
+  if (!recursive) {
+    const store = await getSqliteStore(baseDir);
+    return store.getHistoryWithNativeInfo({ limit, ...queryOptions });
+  }
+
+  // Recursive mode: aggregate data from parent and all child projects
+  const { scanChildProjectsAsync } = await import('../config/storage-paths.js');
+  const childProjects = await scanChildProjectsAsync(baseDir);
+
+  // Use the same type as store.getHistoryWithNativeInfo returns
+  type ExecutionWithNativeAndSource = HistoryIndexEntry & {
+    hasNativeSession: boolean;
+    nativeSessionId?: string;
+    nativeSessionPath?: string;
+  };
+
+  const allExecutions: ExecutionWithNativeAndSource[] = [];
+  let totalCount = 0;
+
+  // Query parent project
+  try {
+    const parentStore = await getSqliteStore(baseDir);
+    const parentResult = parentStore.getHistoryWithNativeInfo({ limit, ...queryOptions });
+    totalCount += parentResult.total;
+
+    for (const exec of parentResult.executions) {
+      allExecutions.push({ ...exec, sourceDir: baseDir });
+    }
+  } catch (error) {
+    if (process.env.DEBUG) {
+      console.error(`[CLI History] Failed to query parent project ${baseDir}:`, error);
+    }
+  }
+
+  // Query all child projects
+  for (const child of childProjects) {
+    try {
+      const childStore = await getSqliteStore(child.projectPath);
+      const childResult = childStore.getHistoryWithNativeInfo({ limit, ...queryOptions });
+      totalCount += childResult.total;
+
+      for (const exec of childResult.executions) {
+        allExecutions.push({ ...exec, sourceDir: child.projectPath });
+      }
+    } catch (error) {
+      if (process.env.DEBUG) {
+        console.error(`[CLI History] Failed to query child project ${child.projectPath}:`, error);
+      }
+    }
+  }
+
+  // Sort by updated_at descending and apply limit
+  allExecutions.sort((a, b) => {
+    const timeA = a.updated_at ? new Date(a.updated_at).getTime() : new Date(a.timestamp).getTime();
+    const timeB = b.updated_at ? new Date(b.updated_at).getTime() : new Date(b.timestamp).getTime();
+    return timeB - timeA;
+  });
+  const limitedExecutions = allExecutions.slice(0, limit);
+
+  return {
+    total: totalCount,
+    count: limitedExecutions.length,
+    executions: limitedExecutions
+  };
+}
--- a/ccw/src/tools/cli-executor-utils.ts
+++ b/ccw/src/tools/cli-executor-utils.ts
@@ -0,0 +1,306 @@
+import { spawn } from 'child_process';
+
+// Debug logging utility - check env at runtime for --debug flag support
+export function isDebugEnabled(): boolean {
+  return process.env.DEBUG === 'true' || process.env.DEBUG === '1' || process.env.CCW_DEBUG === 'true';
+}
+
+export function debugLog(category: string, message: string, data?: Record<string, unknown>): void {
+  if (!isDebugEnabled()) return;
+  const timestamp = new Date().toISOString();
+  const prefix = `[${timestamp}] [CLI-DEBUG] [${category}]`;
+  if (data) {
+    console.error(`${prefix} ${message}`, JSON.stringify(data, null, 2));
+  } else {
+    console.error(`${prefix} ${message}`);
+  }
+}
+
+export function errorLog(
+  category: string,
+  message: string,
+  error?: Error | unknown,
+  context?: Record<string, unknown>
+): void {
+  const timestamp = new Date().toISOString();
+  const prefix = `[${timestamp}] [CLI-ERROR] [${category}]`;
+  console.error(`${prefix} ${message}`);
+  if (error instanceof Error) {
+    console.error(`${prefix} Error: ${error.message}`);
+    if (isDebugEnabled() && error.stack) {
+      console.error(`${prefix} Stack: ${error.stack}`);
+    }
+  } else if (error) {
+    console.error(`${prefix} Error: ${String(error)}`);
+  }
+  if (context) {
+    console.error(`${prefix} Context:`, JSON.stringify(context, null, 2));
+  }
+}
+
+export interface ToolAvailability {
+  available: boolean;
+  path: string | null;
+}
+
+// Tool availability cache with TTL
+interface CachedToolAvailability {
+  result: ToolAvailability;
+  timestamp: number;
+}
+
+// Cache storage: Map<toolName, CachedToolAvailability>
+const toolAvailabilityCache = new Map<string, CachedToolAvailability>();
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+function isCacheValid(cached: CachedToolAvailability): boolean {
+  return Date.now() - cached.timestamp < CACHE_TTL_MS;
+}
+
+function clearExpiredCache(): void {
+  const now = Date.now();
+  const entriesToDelete: string[] = [];
+
+  toolAvailabilityCache.forEach((cached, tool) => {
+    if (now - cached.timestamp >= CACHE_TTL_MS) {
+      entriesToDelete.push(tool);
+    }
+  });
+
+  entriesToDelete.forEach((tool) => toolAvailabilityCache.delete(tool));
+}
+
+export function clearToolCache(): void {
+  toolAvailabilityCache.clear();
+}
+
+/**
+ * Check if a CLI tool is available (with caching)
+ */
+export async function checkToolAvailability(tool: string): Promise<ToolAvailability> {
+  debugLog('TOOL_CHECK', `Checking availability for tool: ${tool}`);
+
+  const cached = toolAvailabilityCache.get(tool);
+  if (cached && isCacheValid(cached)) {
+    debugLog('TOOL_CHECK', `Cache hit for ${tool}`, { available: cached.result.available, path: cached.result.path });
+    return cached.result;
+  }
+
+  clearExpiredCache();
+
+  return new Promise((resolve) => {
+    const isWindows = process.platform === 'win32';
+    const command = isWindows ? 'where' : 'which';
+
+    debugLog('TOOL_CHECK', `Running ${command} ${tool}`, { platform: process.platform });
+
+    const child = spawn(command, [tool], {
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout!.on('data', (data) => {
+      stdout += data.toString();
+    });
+    child.stderr?.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code) => {
+      const result: ToolAvailability = code === 0 && stdout.trim()
+        ? { available: true, path: stdout.trim().split('\n')[0] }
+        : { available: false, path: null };
+
+      if (result.available) {
+        debugLog('TOOL_CHECK', `Tool ${tool} found`, { path: result.path });
+        toolAvailabilityCache.set(tool, {
+          result,
+          timestamp: Date.now(),
+        });
+      } else {
+        debugLog('TOOL_CHECK', `Tool ${tool} not found`, { exitCode: code, stderr: stderr.trim() || '(empty)' });
+      }
+
+      resolve(result);
+    });
+
+    child.on('error', (error) => {
+      errorLog('TOOL_CHECK', `Failed to check tool availability: ${tool}`, error, { command, tool });
+      resolve({ available: false, path: null });
+    });
+
+    setTimeout(() => {
+      child.kill();
+      debugLog('TOOL_CHECK', `Timeout checking tool ${tool} (5s)`);
+      resolve({ available: false, path: null });
+    }, 5000);
+  });
+}
+
+// Native resume configuration
+export interface NativeResumeConfig {
+  enabled: boolean;
+  sessionId?: string; // Native UUID
+  isLatest?: boolean; // Use latest/--last flag
+}
+
+/**
+ * Build command arguments based on tool and options
+ */
+export function buildCommand(params: {
+  tool: string;
+  prompt: string;
+  mode: string;
+  model?: string;
+  dir?: string;
+  include?: string;
+  nativeResume?: NativeResumeConfig;
+}): { command: string; args: string[]; useStdin: boolean } {
+  const { tool, prompt, mode = 'analysis', model, dir, include, nativeResume } = params;
+
+  debugLog('BUILD_CMD', `Building command for tool: ${tool}`, {
+    mode,
+    model: model || '(default)',
+    dir: dir || '(cwd)',
+    include: include || '(none)',
+    nativeResume: nativeResume
+      ? { enabled: nativeResume.enabled, isLatest: nativeResume.isLatest, sessionId: nativeResume.sessionId }
+      : '(none)',
+    promptLength: prompt.length,
+  });
+
+  let command = tool;
+  let args: string[] = [];
+  // Default to stdin for all tools to avoid escaping issues on Windows
+  let useStdin = true;
+
+  switch (tool) {
+    case 'gemini':
+      if (nativeResume?.enabled) {
+        if (nativeResume.isLatest) {
+          args.push('-r', 'latest');
+        } else if (nativeResume.sessionId) {
+          args.push('-r', nativeResume.sessionId);
+        }
+      }
+      if (model) {
+        args.push('-m', model);
+      }
+      if (mode === 'write') {
+        args.push('--approval-mode', 'yolo');
+      }
+      if (include) {
+        args.push('--include-directories', include);
+      }
+      break;
+
+    case 'qwen':
+      if (nativeResume?.enabled) {
+        if (nativeResume.isLatest) {
+          args.push('--continue');
+        } else if (nativeResume.sessionId) {
+          args.push('--resume', nativeResume.sessionId);
+        }
+      }
+      if (model) {
+        args.push('-m', model);
+      }
+      if (mode === 'write') {
+        args.push('--approval-mode', 'yolo');
+      }
+      if (include) {
+        args.push('--include-directories', include);
+      }
+      break;
+
+    case 'codex':
+      useStdin = true;
+      if (nativeResume?.enabled) {
+        args.push('resume');
+        if (nativeResume.isLatest) {
+          args.push('--last');
+        } else if (nativeResume.sessionId) {
+          args.push(nativeResume.sessionId);
+        }
+        if (mode === 'write' || mode === 'auto') {
+          args.push('--dangerously-bypass-approvals-and-sandbox');
+        } else {
+          args.push('--full-auto');
+        }
+        if (model) {
+          args.push('-m', model);
+        }
+        if (include) {
+          const dirs = include.split(',').map((d) => d.trim()).filter((d) => d);
+          for (const addDir of dirs) {
+            args.push('--add-dir', addDir);
+          }
+        }
+        args.push('-');
+      } else {
+        args.push('exec');
+        if (mode === 'write' || mode === 'auto') {
+          args.push('--dangerously-bypass-approvals-and-sandbox');
+        } else {
+          args.push('--full-auto');
+        }
+        if (model) {
+          args.push('-m', model);
+        }
+        if (include) {
+          const dirs = include.split(',').map((d) => d.trim()).filter((d) => d);
+          for (const addDir of dirs) {
+            args.push('--add-dir', addDir);
+          }
+        }
+        args.push('-');
+      }
+      break;
+
+    case 'claude':
+      // Claude Code: claude -p "prompt" for non-interactive mode
+      args.push('-p'); // Print mode (non-interactive)
+      // Native resume: claude --resume <session-id> or --continue
+      if (nativeResume?.enabled) {
+        if (nativeResume.isLatest) {
+          args.push('--continue');
+        } else if (nativeResume.sessionId) {
+          args.push('--resume', nativeResume.sessionId);
+        }
+      }
+      if (model) {
+        args.push('--model', model);
+      }
+      // Permission modes: write/auto → bypassPermissions, analysis → default
+      if (mode === 'write' || mode === 'auto') {
+        args.push('--permission-mode', 'bypassPermissions');
+      } else {
+        args.push('--permission-mode', 'default');
+      }
+      // Output format for better parsing
+      args.push('--output-format', 'text');
+      // Add directories
+      if (include) {
+        const dirs = include.split(',').map((d) => d.trim()).filter((d) => d);
+        for (const addDir of dirs) {
+          args.push('--add-dir', addDir);
+        }
+      }
+      break;
+
+    default:
+      errorLog('BUILD_CMD', `Unknown CLI tool: ${tool}`);
+      throw new Error(`Unknown CLI tool: ${tool}`);
+  }
+
+  debugLog('BUILD_CMD', `Command built successfully`, {
+    command,
+    args,
+    useStdin,
+    fullCommand: `${command} ${args.join(' ')}${useStdin ? ' (stdin)' : ''}`,
+  });
+
+  return { command, args, useStdin };
+}
--- a/ccw/src/tools/cli-executor.ts
+++ b/ccw/src/tools/cli-executor.ts
--- a/ccw/src/tools/cli-prompt-builder.ts
+++ b/ccw/src/tools/cli-prompt-builder.ts
@@ -0,0 +1,434 @@
+/**
+ * CLI Prompt Builder
+ * Prompt concatenation + multi-turn formatting helpers
+ */
+
+import type { ConversationRecord, ConversationTurn } from './cli-executor-state.js';
+
+// Prompt concatenation format types
+export type PromptFormat = 'plain' | 'yaml' | 'json';
+
+/**
+ * Merge multiple conversations into a unified context
+ * Returns merged turns sorted by timestamp with source tracking
+ */
+export interface MergedTurn extends ConversationTurn {
+  source_id: string; // Original conversation ID
+}
+
+export interface MergeResult {
+  mergedTurns: MergedTurn[];
+  sourceConversations: ConversationRecord[];
+  totalDuration: number;
+}
+
+export function mergeConversations(conversations: ConversationRecord[]): MergeResult {
+  const mergedTurns: MergedTurn[] = [];
+
+  // Collect all turns with source tracking
+  for (const conv of conversations) {
+    for (const turn of conv.turns) {
+      mergedTurns.push({
+        ...turn,
+        source_id: conv.id
+      });
+    }
+  }
+
+  // Sort by timestamp
+  mergedTurns.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+
+  // Re-number turns
+  mergedTurns.forEach((turn, idx) => {
+    turn.turn = idx + 1;
+  });
+
+  // Calculate total duration
+  const totalDuration = mergedTurns.reduce((sum, t) => sum + t.duration_ms, 0);
+
+  return {
+    mergedTurns,
+    sourceConversations: conversations,
+    totalDuration
+  };
+}
+
+/**
+ * Build prompt from merged conversations
+ */
+export function buildMergedPrompt(
+  mergeResult: MergeResult,
+  newPrompt: string,
+  format: PromptFormat = 'plain'
+): string {
+  const concatenator = createPromptConcatenator({ format });
+
+  // Set metadata for merged conversations
+  concatenator.setMetadata(
+    'merged_sources',
+    mergeResult.sourceConversations.map(c => c.id).join(', ')
+  );
+
+  // Add all merged turns with source tracking
+  for (const turn of mergeResult.mergedTurns) {
+    concatenator.addFromConversationTurn(turn, turn.source_id);
+  }
+
+  return concatenator.build(newPrompt);
+}
+
+/**
+ * Turn data structure for concatenation
+ */
+interface TurnData {
+  turn: number;
+  timestamp?: string;
+  role: 'user' | 'assistant';
+  content: string;
+  status?: string;
+  duration_ms?: number;
+  source_id?: string; // For merged conversations
+}
+
+/**
+ * Prompt concatenation options
+ */
+export interface ConcatOptions {
+  format: PromptFormat;
+  includeMetadata?: boolean;
+  includeTurnMarkers?: boolean;
+  maxOutputLength?: number; // Truncate output for context efficiency
+}
+
+/**
+ * PromptConcatenator - Dedicated class for building multi-turn prompts
+ * Supports multiple output formats: plain text, YAML, JSON
+ */
+export class PromptConcatenator {
+  private turns: TurnData[] = [];
+  private options: ConcatOptions;
+  private metadata: Record<string, unknown> = {};
+
+  constructor(options: Partial<ConcatOptions> = {}) {
+    this.options = {
+      format: options.format || 'plain',
+      includeMetadata: options.includeMetadata ?? true,
+      includeTurnMarkers: options.includeTurnMarkers ?? true,
+      maxOutputLength: options.maxOutputLength || 8192
+    };
+  }
+
+  /**
+   * Set metadata for the conversation
+   */
+  setMetadata(key: string, value: unknown): this {
+    this.metadata[key] = value;
+    return this;
+  }
+
+  /**
+   * Add a user turn
+   */
+  addUserTurn(content: string, options: Partial<Omit<TurnData, 'role' | 'content'>> = {}): this {
+    this.turns.push({
+      turn: this.turns.length + 1,
+      role: 'user',
+      content,
+      ...options
+    });
+    return this;
+  }
+
+  /**
+   * Add an assistant turn
+   */
+  addAssistantTurn(content: string, options: Partial<Omit<TurnData, 'role' | 'content'>> = {}): this {
+    // Truncate output if needed
+    const truncatedContent = content.length > this.options.maxOutputLength!
+      ? content.substring(0, this.options.maxOutputLength!) + '\n... [truncated]'
+      : content;
+
+    this.turns.push({
+      turn: this.turns.length + 1,
+      role: 'assistant',
+      content: truncatedContent,
+      ...options
+    });
+    return this;
+  }
+
+  /**
+   * Add a conversation turn from ConversationTurn
+   */
+  addFromConversationTurn(turn: ConversationTurn, sourceId?: string): this {
+    this.addUserTurn(turn.prompt, {
+      turn: turn.turn * 2 - 1,
+      timestamp: turn.timestamp,
+      source_id: sourceId
+    });
+    this.addAssistantTurn(turn.output.stdout || '[No output]', {
+      turn: turn.turn * 2,
+      timestamp: turn.timestamp,
+      status: turn.status,
+      duration_ms: turn.duration_ms,
+      source_id: sourceId
+    });
+    return this;
+  }
+
+  /**
+   * Load turns from an existing conversation
+   */
+  loadConversation(conversation: ConversationRecord): this {
+    for (const turn of conversation.turns) {
+      this.addFromConversationTurn(turn);
+    }
+    return this;
+  }
+
+  /**
+   * Build the final prompt in plain text format
+   */
+  private buildPlainText(newPrompt: string): string {
+    const parts: string[] = [];
+
+    // Metadata section
+    if (this.options.includeMetadata && Object.keys(this.metadata).length > 0) {
+      parts.push('=== CONTEXT ===');
+      for (const [key, value] of Object.entries(this.metadata)) {
+        parts.push(`${key}: ${String(value)}`);
+      }
+      parts.push('');
+    }
+
+    // Conversation history
+    if (this.turns.length > 0) {
+      parts.push('=== CONVERSATION HISTORY ===');
+      parts.push('');
+
+      let currentTurn = 0;
+      for (let i = 0; i < this.turns.length; i += 2) {
+        currentTurn++;
+        const userTurn = this.turns[i];
+        const assistantTurn = this.turns[i + 1];
+
+        if (this.options.includeTurnMarkers) {
+          const sourceMarker = userTurn.source_id ? ` [${userTurn.source_id}]` : '';
+          parts.push(`--- Turn ${currentTurn}${sourceMarker} ---`);
+        }
+
+        parts.push('USER:');
+        parts.push(userTurn.content);
+        parts.push('');
+
+        if (assistantTurn) {
+          parts.push('ASSISTANT:');
+          parts.push(assistantTurn.content);
+          parts.push('');
+        }
+      }
+    }
+
+    // New request
+    parts.push('=== NEW REQUEST ===');
+    parts.push('');
+    parts.push(newPrompt);
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Build the final prompt in YAML format
+   */
+  private buildYaml(newPrompt: string): string {
+    const yamlLines: string[] = [];
+
+    // Metadata
+    if (this.options.includeMetadata && Object.keys(this.metadata).length > 0) {
+      yamlLines.push('context:');
+      for (const [key, value] of Object.entries(this.metadata)) {
+        yamlLines.push(`  ${key}: ${this.yamlValue(value)}`);
+      }
+      yamlLines.push('');
+    }
+
+    // Conversation history
+    if (this.turns.length > 0) {
+      yamlLines.push('conversation:');
+
+      let currentTurn = 0;
+      for (let i = 0; i < this.turns.length; i += 2) {
+        currentTurn++;
+        const userTurn = this.turns[i];
+        const assistantTurn = this.turns[i + 1];
+
+        yamlLines.push(`  - turn: ${currentTurn}`);
+        if (userTurn.source_id) {
+          yamlLines.push(`    source: ${userTurn.source_id}`);
+        }
+        if (userTurn.timestamp) {
+          yamlLines.push(`    timestamp: ${userTurn.timestamp}`);
+        }
+
+        // User message
+        yamlLines.push('    user: |');
+        const userLines = userTurn.content.split('\n');
+        for (const line of userLines) {
+          yamlLines.push(`      ${line}`);
+        }
+
+        // Assistant message
+        if (assistantTurn) {
+          if (assistantTurn.status) {
+            yamlLines.push(`    status: ${assistantTurn.status}`);
+          }
+          if (assistantTurn.duration_ms) {
+            yamlLines.push(`    duration_ms: ${assistantTurn.duration_ms}`);
+          }
+          yamlLines.push('    assistant: |');
+          const assistantLines = assistantTurn.content.split('\n');
+          for (const line of assistantLines) {
+            yamlLines.push(`      ${line}`);
+          }
+        }
+        yamlLines.push('');
+      }
+    }
+
+    // New request
+    yamlLines.push('new_request: |');
+    const requestLines = newPrompt.split('\n');
+    for (const line of requestLines) {
+      yamlLines.push(`  ${line}`);
+    }
+
+    return yamlLines.join('\n');
+  }
+
+  /**
+   * Build the final prompt in JSON format
+   */
+  private buildJson(newPrompt: string): string {
+    const data: Record<string, unknown> = {};
+
+    // Metadata
+    if (this.options.includeMetadata && Object.keys(this.metadata).length > 0) {
+      data.context = this.metadata;
+    }
+
+    // Conversation history
+    if (this.turns.length > 0) {
+      const conversation: Array<{
+        turn: number;
+        source?: string;
+        timestamp?: string;
+        user: string;
+        assistant?: string;
+        status?: string;
+        duration_ms?: number;
+      }> = [];
+
+      for (let i = 0; i < this.turns.length; i += 2) {
+        const userTurn = this.turns[i];
+        const assistantTurn = this.turns[i + 1];
+
+        const turnData: typeof conversation[0] = {
+          turn: Math.ceil((i + 1) / 2),
+          user: userTurn.content
+        };
+
+        if (userTurn.source_id) turnData.source = userTurn.source_id;
+        if (userTurn.timestamp) turnData.timestamp = userTurn.timestamp;
+        if (assistantTurn) {
+          turnData.assistant = assistantTurn.content;
+          if (assistantTurn.status) turnData.status = assistantTurn.status;
+          if (assistantTurn.duration_ms) turnData.duration_ms = assistantTurn.duration_ms;
+        }
+
+        conversation.push(turnData);
+      }
+
+      data.conversation = conversation;
+    }
+
+    data.new_request = newPrompt;
+
+    return JSON.stringify(data, null, 2);
+  }
+
+  /**
+   * Helper to format YAML values
+   */
+  private yamlValue(value: unknown): string {
+    if (typeof value === 'string') {
+      // Quote strings that might be interpreted as other types
+      if (/[:\[\]{}#&*!|>'"@`]/.test(value) || value === '') {
+        return `"${value.replace(/"/g, '\\"')}"`;
+      }
+      return value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+      return String(value);
+    }
+    if (value === null || value === undefined) {
+      return 'null';
+    }
+    return JSON.stringify(value);
+  }
+
+  /**
+   * Build the final prompt string
+   */
+  build(newPrompt: string): string {
+    switch (this.options.format) {
+      case 'yaml':
+        return this.buildYaml(newPrompt);
+      case 'json':
+        return this.buildJson(newPrompt);
+      case 'plain':
+      default:
+        return this.buildPlainText(newPrompt);
+    }
+  }
+
+  /**
+   * Reset the concatenator for reuse
+   */
+  reset(): this {
+    this.turns = [];
+    this.metadata = {};
+    return this;
+  }
+}
+
+/**
+ * Create a prompt concatenator with specified options
+ */
+export function createPromptConcatenator(options?: Partial<ConcatOptions>): PromptConcatenator {
+  return new PromptConcatenator(options);
+}
+
+/**
+ * Quick helper to build a multi-turn prompt in any format
+ */
+export function buildPrompt(
+  conversation: ConversationRecord,
+  newPrompt: string,
+  format: PromptFormat = 'plain'
+): string {
+  return createPromptConcatenator({ format })
+    .loadConversation(conversation)
+    .build(newPrompt);
+}
+
+/**
+ * Build multi-turn prompt with full conversation history
+ * Uses the PromptConcatenator with plain text format by default
+ */
+export function buildMultiTurnPrompt(
+  conversation: ConversationRecord,
+  newPrompt: string,
+  format: PromptFormat = 'plain'
+): string {
+  return buildPrompt(conversation, newPrompt, format);
+}
--- a/ccw/src/tools/codex-lens.ts
+++ b/ccw/src/tools/codex-lens.ts
@@ -17,6 +17,7 @@ import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { getSystemPython } from '../utils/python-utils.js';
+import { EXEC_TIMEOUTS } from '../utils/exec-constants.js';

 // Get directory of this module
 const __filename = fileURLToPath(import.meta.url);
@@ -340,7 +341,7 @@ async function ensureLiteLLMEmbedderReady(): Promise<BootstrapResult> {
    for (const localPath of possiblePaths) {
      if (existsSync(join(localPath, 'pyproject.toml'))) {
        console.log(`[CodexLens] Installing ccw-litellm from local path: ${localPath}`);
-        execSync(`"${pipPath}" install -e "${localPath}"`, { stdio: 'inherit' });
+        execSync(`"${pipPath}" install -e "${localPath}"`, { stdio: 'inherit', timeout: EXEC_TIMEOUTS.PACKAGE_INSTALL });
        installed = true;
        break;
      }
@@ -348,7 +349,7 @@ async function ensureLiteLLMEmbedderReady(): Promise<BootstrapResult> {

    if (!installed) {
      console.log('[CodexLens] Installing ccw-litellm from PyPI...');
-      execSync(`"${pipPath}" install ccw-litellm`, { stdio: 'inherit' });
+      execSync(`"${pipPath}" install ccw-litellm`, { stdio: 'inherit', timeout: EXEC_TIMEOUTS.PACKAGE_INSTALL });
    }

    return { success: true };
@@ -426,11 +427,11 @@ async function detectGpuSupport(): Promise<{ mode: GpuMode; available: GpuMode[]
  // Check for NVIDIA GPU (CUDA)
  try {
    if (process.platform === 'win32') {
-      execSync('nvidia-smi', { stdio: 'pipe' });
+      execSync('nvidia-smi', { stdio: 'pipe', timeout: EXEC_TIMEOUTS.SYSTEM_INFO });
      available.push('cuda');
      detectedInfo = 'NVIDIA GPU detected (CUDA available)';
    } else {
-      execSync('which nvidia-smi', { stdio: 'pipe' });
+      execSync('which nvidia-smi', { stdio: 'pipe', timeout: EXEC_TIMEOUTS.SYSTEM_INFO });
      available.push('cuda');
      detectedInfo = 'NVIDIA GPU detected (CUDA available)';
    }
@@ -503,7 +504,7 @@ async function installSemantic(gpuMode: GpuMode = 'cpu'): Promise<BootstrapResul

  for (const pkg of onnxVariants) {
    try {
-      execSync(`"${pipPath}" uninstall ${pkg} -y`, { stdio: 'pipe' });
+      execSync(`"${pipPath}" uninstall ${pkg} -y`, { stdio: 'pipe', timeout: EXEC_TIMEOUTS.PACKAGE_INSTALL });
      console.log(`[CodexLens] Removed ${pkg}`);
    } catch {
      // Package not installed, ignore
@@ -587,7 +588,7 @@ async function installSemantic(gpuMode: GpuMode = 'cpu'): Promise<BootstrapResul
          if (gpuMode !== 'cpu') {
            try {
              console.log(`[CodexLens] Reinstalling ${onnxPackage} to ensure GPU provider works...`);
-              execSync(`"${pipPath}" install --force-reinstall ${onnxPackage}`, { stdio: 'pipe', timeout: 300000 });
+              execSync(`"${pipPath}" install --force-reinstall ${onnxPackage}`, { stdio: 'pipe', timeout: EXEC_TIMEOUTS.PACKAGE_INSTALL });
              console.log(`[CodexLens] ${onnxPackage} reinstalled successfully`);
            } catch (e) {
              console.warn(`[CodexLens] Warning: Failed to reinstall ${onnxPackage}: ${(e as Error).message}`);
@@ -626,7 +627,7 @@ async function bootstrapVenv(): Promise<BootstrapResult> {
    try {
      console.log('[CodexLens] Creating virtual environment...');
      const pythonCmd = getSystemPython();
-      execSync(`${pythonCmd} -m venv "${CODEXLENS_VENV}"`, { stdio: 'inherit' });
+      execSync(`${pythonCmd} -m venv "${CODEXLENS_VENV}"`, { stdio: 'inherit', timeout: EXEC_TIMEOUTS.PROCESS_SPAWN });
    } catch (err) {
      return { success: false, error: `Failed to create venv: ${(err as Error).message}` };
    }
@@ -651,7 +652,7 @@ async function bootstrapVenv(): Promise<BootstrapResult> {
    for (const localPath of possiblePaths) {
      if (existsSync(join(localPath, 'pyproject.toml'))) {
        console.log(`[CodexLens] Installing from local path: ${localPath}`);
-        execSync(`"${pipPath}" install -e "${localPath}"`, { stdio: 'inherit' });
+        execSync(`"${pipPath}" install -e "${localPath}"`, { stdio: 'inherit', timeout: EXEC_TIMEOUTS.PACKAGE_INSTALL });
        installed = true;
        break;
      }
@@ -659,7 +660,7 @@ async function bootstrapVenv(): Promise<BootstrapResult> {

    if (!installed) {
      console.log('[CodexLens] Installing from PyPI...');
-      execSync(`"${pipPath}" install codexlens`, { stdio: 'inherit' });
+      execSync(`"${pipPath}" install codexlens`, { stdio: 'inherit', timeout: EXEC_TIMEOUTS.PACKAGE_INSTALL });
    }

    // Clear cache after successful installation
@@ -1368,7 +1369,7 @@ async function uninstallCodexLens(): Promise<BootstrapResult> {
      const { execSync } = await import('child_process');
      try {
        // Kill any python processes from our venv that might be holding file locks
-        execSync(`taskkill /F /IM python.exe /FI "MODULES eq sqlite3" 2>nul`, { stdio: 'ignore' });
+        execSync(`taskkill /F /IM python.exe /FI "MODULES eq sqlite3" 2>nul`, { stdio: 'ignore', timeout: EXEC_TIMEOUTS.SYSTEM_INFO });
      } catch {
        // Ignore errors - no processes to kill
      }
@@ -1397,7 +1398,7 @@ async function uninstallCodexLens(): Promise<BootstrapResult> {
                try {
                  const { execSync } = await import('child_process');
                  // Try to close handles on the specific file
-                  execSync(`handle -c ${err.path} -y 2>nul`, { stdio: 'ignore' });
+                  execSync(`handle -c ${err.path} -y 2>nul`, { stdio: 'ignore', timeout: EXEC_TIMEOUTS.SYSTEM_INFO });
                } catch {
                  // handle.exe may not be installed, ignore
                }
@@ -1454,7 +1455,7 @@ function cancelIndexing(): { success: boolean; message?: string; error?: string
      // On Windows, use taskkill to kill the process tree
      const { execSync } = require('child_process');
      try {
-        execSync(`taskkill /pid ${currentIndexingProcess.pid} /T /F`, { stdio: 'ignore' });
+        execSync(`taskkill /pid ${currentIndexingProcess.pid} /T /F`, { stdio: 'ignore', timeout: EXEC_TIMEOUTS.SYSTEM_INFO });
      } catch {
        // Process may have already exited
      }
--- a/ccw/src/tools/detect-changed-modules.ts
+++ b/ccw/src/tools/detect-changed-modules.ts
@@ -8,6 +8,15 @@ import type { ToolSchema, ToolResult } from '../types/tool.js';
 import { readdirSync, statSync, existsSync } from 'fs';
 import { join, resolve, dirname, extname, relative } from 'path';
 import { execSync } from 'child_process';
+import { EXEC_TIMEOUTS } from '../utils/exec-constants.js';
+
+function isExecTimeoutError(error: unknown): boolean {
+  const err = error as { code?: unknown; errno?: unknown; message?: unknown } | null;
+  const code = err?.code ?? err?.errno;
+  if (code === 'ETIMEDOUT') return true;
+  const message = typeof err?.message === 'string' ? err.message : '';
+  return message.includes('ETIMEDOUT');
+}

 // Source file extensions to track
 const SOURCE_EXTENSIONS = [
@@ -53,9 +62,12 @@ interface ToolOutput {
 */
 function isGitRepo(basePath: string): boolean {
  try {
-    execSync('git rev-parse --git-dir', { cwd: basePath, stdio: 'pipe' });
+    execSync('git rev-parse --git-dir', { cwd: basePath, stdio: 'pipe', timeout: EXEC_TIMEOUTS.GIT_QUICK });
    return true;
-  } catch (e) {
+  } catch (e: unknown) {
+    if (isExecTimeoutError(e)) {
+      console.warn(`[detect_changed_modules] git rev-parse timed out after ${EXEC_TIMEOUTS.GIT_QUICK}ms`);
+    }
    return false;
  }
 }
@@ -69,13 +81,15 @@ function getGitChangedFiles(basePath: string): string[] {
    let output = execSync('git diff --name-only HEAD 2>/dev/null', {
      cwd: basePath,
      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: EXEC_TIMEOUTS.GIT_DIFF,
    }).trim();

    const cachedOutput = execSync('git diff --name-only --cached 2>/dev/null', {
      cwd: basePath,
      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: EXEC_TIMEOUTS.GIT_DIFF,
    }).trim();

    if (cachedOutput) {
@@ -87,12 +101,16 @@ function getGitChangedFiles(basePath: string): string[] {
      output = execSync('git diff --name-only HEAD~1 HEAD 2>/dev/null', {
        cwd: basePath,
        encoding: 'utf8',
-        stdio: ['pipe', 'pipe', 'pipe']
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: EXEC_TIMEOUTS.GIT_DIFF,
      }).trim();
    }

    return output ? output.split('\n').filter(f => f.trim()) : [];
-  } catch (e) {
+  } catch (e: unknown) {
+    if (isExecTimeoutError(e)) {
+      console.warn(`[detect_changed_modules] git diff timed out after ${EXEC_TIMEOUTS.GIT_DIFF}ms`);
+    }
    return [];
  }
 }
--- a/ccw/src/tools/smart-search.ts
+++ b/ccw/src/tools/smart-search.ts
@@ -26,6 +26,7 @@ import {
 } from './codex-lens.js';
 import type { ProgressInfo } from './codex-lens.js';
 import { getProjectRoot } from '../utils/path-validator.js';
+import { EXEC_TIMEOUTS } from '../utils/exec-constants.js';

 // Timing utilities for performance analysis
 const TIMING_ENABLED = process.env.SMART_SEARCH_TIMING === '1' || process.env.DEBUG?.includes('timing');
@@ -603,7 +604,7 @@ function checkToolAvailability(toolName: string): boolean {
  try {
    const isWindows = process.platform === 'win32';
    const command = isWindows ? 'where' : 'which';
-    execSync(`${command} ${toolName}`, { stdio: 'ignore' });
+    execSync(`${command} ${toolName}`, { stdio: 'ignore', timeout: EXEC_TIMEOUTS.SYSTEM_INFO });
    return true;
  } catch {
    return false;