@gracker/smartperfetto 1.0.13

package/dist/agentv3/claudeMcpServer.js

@@ -0,0 +1,3785 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_PHASE_SUMMARY_CHARS = exports.MCP_NAME_PREFIX = void 0;
+exports.loadLearnedSqlFixPairs = loadLearnedSqlFixPairs;
+exports.createClaudeMcpServer = createClaudeMcpServer;
+const claude_agent_sdk_1 = require("@anthropic-ai/claude-agent-sdk");
+const zod_1 = require("zod");
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const skillAnalysisAdapter_1 = require("../services/skillEngine/skillAnalysisAdapter");
+const skillLoader_1 = require("../services/skillEngine/skillLoader");
+const architectureDetector_1 = require("../agent/detectors/architectureDetector");
+const dataContract_1 = require("../types/dataContract");
+const types_1 = require("./types");
+const sqlSummarizer_1 = require("./sqlSummarizer");
+const analysisPatternMemory_1 = require("./analysisPatternMemory");
+const skillNotesInjector_1 = require("./selfImprove/skillNotesInjector");
+const perfettoStdlibScanner_1 = require("../services/perfettoStdlibScanner");
+const perfettoSqlDocs_1 = require("../services/perfettoSqlDocs");
+const traceProcessorConnectionModel_1 = require("../services/traceProcessorConnectionModel");
+const identityGate_1 = require("../services/processIdentity/identityGate");
+const sqlIncludeInjector_1 = require("./sqlIncludeInjector");
+const rawSqlNormalizer_1 = require("./rawSqlNormalizer");
+const strategyLoader_1 = require("./strategyLoader");
+const phaseHintMatcher_1 = require("./phaseHintMatcher");
+const activePhaseReminder_1 = require("./activePhaseReminder");
+const scenePlanTemplates_1 = require("./scenePlanTemplates");
+const toolCallSummary_1 = require("./toolCallSummary");
+const toolNarration_1 = require("./toolNarration");
+const outputLanguage_1 = require("./outputLanguage");
+const ragStore_1 = require("../services/ragStore");
+const baselineStore_1 = require("../services/baselineStore");
+const baselineDiffer_1 = require("../services/baselineDiffer");
+const projectMemory_1 = require("./projectMemory");
+const caseLibrary_1 = require("../services/caseLibrary");
+const scopedKnowledgeStore_1 = require("../services/scopedKnowledgeStore");
+const mcpToolRegistry_1 = require("./mcpToolRegistry");
+const runtimePaths_1 = require("../runtimePaths");
+/**
+ * Process-wide RagStore singleton, lazily initialized on first MCP tool
+ * call. Backs the `lookup_blog_knowledge` tool (Plan 55) and will back
+ * the project-memory recall tool (Plan 44) when that lands.
+ *
+ * Storage path lives next to the existing analysis_*.json files so
+ * operators can find every long-lived agent state in one directory.
+ */
+const RAG_STORE_PATH = (0, runtimePaths_1.backendLogPath)('rag_store.json');
+let cachedRagStore = null;
+function getRagStore() {
+    if (!cachedRagStore)
+        cachedRagStore = new ragStore_1.RagStore(RAG_STORE_PATH);
+    return cachedRagStore;
+}
+/** Process-wide BaselineStore singleton (Plan 50). Storage lives next
+ * to the other long-lived JSON files so operators have one mental
+ * model for agent state. */
+const BASELINE_STORE_PATH = (0, runtimePaths_1.backendLogPath)('baselines.json');
+let cachedBaselineStore = null;
+function getBaselineStore() {
+    if (!cachedBaselineStore)
+        cachedBaselineStore = new baselineStore_1.BaselineStore(BASELINE_STORE_PATH);
+    return cachedBaselineStore;
+}
+function quoteLooseObjectKeys(value) {
+    let out = '';
+    let i = 0;
+    let inString = false;
+    let escaped = false;
+    while (i < value.length) {
+        const char = value[i];
+        if (inString) {
+            out += char;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === '\\') {
+                escaped = true;
+            }
+            else if (char === '"') {
+                inString = false;
+            }
+            i++;
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            out += char;
+            i++;
+            continue;
+        }
+        if (char === '{' || char === ',') {
+            out += char;
+            i++;
+            while (i < value.length && /\s/.test(value[i])) {
+                out += value[i++];
+            }
+            const keyStart = i;
+            if (/[A-Za-z_$]/.test(value[i] || '')) {
+                i++;
+                while (i < value.length && /[A-Za-z0-9_$]/.test(value[i]))
+                    i++;
+                const keyEnd = i;
+                let hasDanglingClosingQuote = false;
+                if (value[i] === '"') {
+                    let colonIndex = i + 1;
+                    while (colonIndex < value.length && /\s/.test(value[colonIndex]))
+                        colonIndex++;
+                    if (value[colonIndex] === ':') {
+                        hasDanglingClosingQuote = true;
+                    }
+                }
+                if (hasDanglingClosingQuote) {
+                    let colonIndex = i + 1;
+                    while (colonIndex < value.length && /\s/.test(value[colonIndex]))
+                        colonIndex++;
+                    out += `"${value.slice(keyStart, keyEnd)}"`;
+                    out += value.slice(keyEnd + 1, colonIndex + 1);
+                    i = colonIndex + 1;
+                    continue;
+                }
+                let colonIndex = i;
+                while (colonIndex < value.length && /\s/.test(value[colonIndex]))
+                    colonIndex++;
+                if (value[colonIndex] === ':') {
+                    out += `"${value.slice(keyStart, keyEnd)}"`;
+                    out += value.slice(keyEnd, colonIndex + 1);
+                    i = colonIndex + 1;
+                    continue;
+                }
+            }
+            out += value.slice(keyStart, i);
+            continue;
+        }
+        out += char;
+        i++;
+    }
+    return out;
+}
+function parseToolArrayInput(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    const withoutTrailingComma = trimmed.replace(/,\s*$/, '');
+    const candidates = [
+        trimmed,
+        withoutTrailingComma,
+        quoteLooseObjectKeys(trimmed),
+        quoteLooseObjectKeys(withoutTrailingComma),
+    ].filter((entry, index, all) => entry.length > 0 && all.indexOf(entry) === index);
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            return Array.isArray(parsed) ? parsed : null;
+        }
+        catch {
+            // Try the next normalization variant.
+        }
+    }
+    return null;
+}
+function parseOptionalToolArrayInput(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (typeof value === 'string') {
+        const trimmed = value.trim().toLowerCase();
+        if (!trimmed || trimmed === 'null' || trimmed === 'undefined')
+            return [];
+    }
+    return parseToolArrayInput(value);
+}
+function parseToolStringArrayInput(value) {
+    if (Array.isArray(value)) {
+        return value.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+    }
+    if (typeof value !== 'string')
+        return [];
+    const trimmed = value.trim();
+    if (!trimmed)
+        return [];
+    const parsed = parseToolArrayInput(trimmed);
+    if (parsed) {
+        return parsed.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+    }
+    return trimmed
+        .split(',')
+        .map(entry => entry.trim())
+        .filter(Boolean);
+}
+function coerceOptionalInteger(value, field, options) {
+    if (value === undefined || value === null || value === '') {
+        return {};
+    }
+    const numeric = typeof value === 'number'
+        ? value
+        : typeof value === 'string'
+            ? Number(value.trim())
+            : Number.NaN;
+    if (!Number.isInteger(numeric)) {
+        return { error: `${field} must be an integer` };
+    }
+    if (numeric < options.min) {
+        return { error: `${field} must be >= ${options.min}` };
+    }
+    if (options.max !== undefined && numeric > options.max) {
+        return { error: `${field} must be <= ${options.max}` };
+    }
+    return { value: numeric };
+}
+function normalizePlanPhaseToolInput(input) {
+    const expectedCalls = parseToolArrayInput(input.expectedCalls);
+    return {
+        id: input.id,
+        name: input.name,
+        goal: input.goal,
+        expectedTools: parseToolStringArrayInput(input.expectedTools),
+        ...(expectedCalls ? { expectedCalls } : {}),
+    };
+}
+function isConclusionLikePlanPhase(phase) {
+    const text = `${phase.id} ${phase.name} ${phase.goal}`.toLowerCase();
+    return /(综合结论|最终结论|结论输出|输出结论|输出最终报告|最终报告|综合报告|final conclusion|conclusion|final report|write final answer)/i
+        .test(text);
+}
+function moveConclusionPhasesLast(phases) {
+    const conclusionPhases = phases.filter(isConclusionLikePlanPhase);
+    if (conclusionPhases.length === 0)
+        return phases;
+    const nonConclusionPhases = phases.filter(phase => !isConclusionLikePlanPhase(phase));
+    return [...nonConclusionPhases, ...conclusionPhases];
+}
+const PHASE_SEMANTIC_LABELS = {
+    architecture: '架构检测',
+    overview: '概览采集',
+    global_context: '全局上下文',
+    root_drill: '根因深钻',
+    gap_detection: '缺帧检测',
+    conclusion: '综合结论',
+};
+const PHASE_SEMANTIC_PATTERNS = [
+    {
+        kind: 'conclusion',
+        pattern: /(综合结论|最终结论|结论输出|输出.*(?:结论|报告)|最终报告|优化建议|final conclusion|conclusion|final report|write final answer)/i,
+    },
+    {
+        kind: 'gap_detection',
+        pattern: /(缺帧|帧生产\s*gap|frame[_ -]?production[_ -]?gap|rt_no_drawframe|ui_no_frame|sf_backpressure|buffer stuffing 假阳性|gap 列表|gap overview)/i,
+    },
+    {
+        kind: 'root_drill',
+        pattern: /(根因深钻|根因诊断|代表帧|四象限|机制级|jank_frame_detail|blocking_chain|workload_heavy|lock_binder_wait|top slices?|主线程耗时|renderthread 耗时|root cause|drill)/i,
+    },
+    {
+        kind: 'global_context',
+        pattern: /(全局上下文|温控|thermal|视频|插帧|后台|background|干扰|系统干扰|global context)/i,
+    },
+    {
+        kind: 'architecture',
+        pattern: /(架构检测|渲染架构|textureview|surfaceview|webview|detect_architecture|architecture)/i,
+    },
+    {
+        kind: 'overview',
+        pattern: /(概览|批量根因分类|滑动性能概览|启动概览|启动事件|启动类型|数据质量|ttid|ttfd|dur\s*=|帧统计|掉帧分布|scrolling_analysis|startup_overview|overview|startup event|launch type)/i,
+    },
+];
+function inferPhaseSemanticKinds(text) {
+    if (!text)
+        return [];
+    return PHASE_SEMANTIC_PATTERNS
+        .filter(({ pattern }) => pattern.test(text))
+        .map(({ kind }) => kind);
+}
+function findPhaseSemanticMismatch(plan, phase, summary) {
+    const summaryKinds = inferPhaseSemanticKinds(summary);
+    if (summaryKinds.length === 0)
+        return null;
+    const phaseKinds = new Set(inferPhaseSemanticKinds(`${phase.name} ${phase.goal}`));
+    if (phaseKinds.size === 0)
+        return null;
+    if (summaryKinds.some(kind => phaseKinds.has(kind)))
+        return null;
+    const mismatchedKind = summaryKinds.find(kind => !phaseKinds.has(kind));
+    if (!mismatchedKind)
+        return null;
+    const suggestedPhase = plan.phases.find(candidate => {
+        if (candidate.id === phase.id)
+            return false;
+        if (candidate.status === 'completed' || candidate.status === 'skipped')
+            return false;
+        return inferPhaseSemanticKinds(`${candidate.name} ${candidate.goal}`).includes(mismatchedKind);
+    });
+    return suggestedPhase ? { summaryKind: mismatchedKind, suggestedPhase } : null;
+}
+const TIMESTAMP_EXPRESSION_PARAM_KEYS = new Set([
+    'ts',
+    'start_ts',
+    'end_ts',
+    'frame_ts',
+    'startTs',
+    'endTs',
+    'frameTs',
+]);
+function normalizeTimestampExpression(value) {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    const match = trimmed.match(/^(\d{6,})([+-])(\d{1,15})$/);
+    if (!match)
+        return value;
+    try {
+        const left = BigInt(match[1]);
+        const right = BigInt(match[3]);
+        const result = match[2] === '+' ? left + right : left - right;
+        return result.toString();
+    }
+    catch {
+        return value;
+    }
+}
+/** Process-wide ProjectMemory singleton (Plan 44). Independent of the
+ * existing `analysisPatternMemory.ts` session-scope store. */
+const PROJECT_MEMORY_PATH = (0, runtimePaths_1.backendLogPath)('analysis_project_memory.json');
+let cachedProjectMemory = null;
+function getProjectMemory() {
+    if (!cachedProjectMemory)
+        cachedProjectMemory = new projectMemory_1.ProjectMemory(PROJECT_MEMORY_PATH);
+    return cachedProjectMemory;
+}
+/** Process-wide CaseLibrary singleton (Plan 54). Storage path matches
+ * the other long-lived agent-state JSON files. */
+const CASE_LIBRARY_PATH = (0, runtimePaths_1.backendLogPath)('case_library.json');
+let cachedCaseLibrary = null;
+function getCaseLibrary() {
+    if (!cachedCaseLibrary)
+        cachedCaseLibrary = new caseLibrary_1.CaseLibrary(CASE_LIBRARY_PATH);
+    return cachedCaseLibrary;
+}
+/** MCP tool name prefix — derived from the server name 'smartperfetto'.
+ * Re-exported from `mcpToolRegistry.ts` so consumers (claudeAgentDefinitions,
+ * tests) keep their existing import path. */
+exports.MCP_NAME_PREFIX = mcpToolRegistry_1.MCP_NAME_PREFIX;
+let sqlSchemaCache = null;
+/**
+ * SQL structural keywords to exclude when computing Jaccard similarity
+ * for error-fix pair matching. Without this filter, any two Perfetto SQL
+ * queries match at >30% simply by sharing common keywords like SELECT/FROM/WHERE.
+ */
+const SQL_STOP_WORDS = new Set([
+    // SQL structural keywords
+    'select', 'from', 'where', 'and', 'or', 'not', 'in', 'is', 'as', 'on',
+    'join', 'left', 'right', 'inner', 'outer', 'cross', 'full',
+    'group', 'by', 'order', 'limit', 'having', 'offset',
+    'with', 'case', 'when', 'then', 'else', 'end',
+    'null', 'like', 'glob', 'between',
+    'cast', 'count', 'sum', 'avg', 'max', 'min', 'round', 'coalesce',
+    'lag', 'lead', 'over', 'partition', 'row_number', 'rank',
+    'distinct', 'union', 'all', 'exists', 'into',
+    'asc', 'desc', 'true', 'false', 'integer', 'text', 'real',
+    'printf', 'substr', 'instr', 'replace', 'length', 'trim', 'upper', 'lower',
+    // Perfetto domain-structural tokens — appear in virtually all trace queries
+    // and inflate Jaccard similarity between unrelated queries
+    'upid', 'utid', 'track_id', 'layer_name', 'jank_type', 'dur', 'name',
+    'surface_frame_token', 'display_frame_token', 'frame_number',
+    'process', 'thread', 'slice', 'counter', 'counter_track',
+    'actual_frame_timeline_slice', 'expected_frame_timeline_slice',
+]);
+/** Extract meaningful content tokens from SQL, filtering out structural keywords. */
+function sqlContentTokens(sql) {
+    return new Set(sql.toLowerCase()
+        .split(/[\s,()=<>!+\-*/|;'"]+/)
+        .filter(t => t.length > 2 && !SQL_STOP_WORDS.has(t)));
+}
+const SQL_ERROR_LOG_DIR = (0, runtimePaths_1.backendLogPath)('sql_learning');
+/**
+ * Load previously learned SQL error-fix pairs from disk.
+ * Returns only pairs that have a fixedSql (i.e., successfully corrected).
+ * Used to seed new sessions with cross-session learning.
+ */
+/** TTL for error-fix pairs: 30 days. Older pairs may reference outdated schemas. */
+const ERROR_FIX_PAIR_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * P0-G2: ReAct reasoning nudge — appended to successful data tool results.
+ * Prompts Claude to explicitly reason about observations before next action.
+ * Cost: ~20 tokens per data tool call, ~200-300 total per analysis.
+ */
+const REASONING_NUDGE_ZH = '\n\n[REFLECT] 在执行下一步之前：这个数据的关键发现是什么？是否支持/反驳你的假设？如有重要推断，请用 submit_hypothesis 或 write_analysis_note 记录。';
+const REASONING_NUDGE_EN = '\n\n[REFLECT] Before the next action: what is the key finding from this data? Does it support or refute your hypothesis? If there is an important inference, record it with submit_hypothesis or write_analysis_note.';
+exports.MIN_PHASE_SUMMARY_CHARS = 15;
+function sqlErrorLogFile(scope) {
+    if (!(0, scopedKnowledgeStore_1.enterpriseKnowledgeStoreEnabled)() && !scope) {
+        return path.join(SQL_ERROR_LOG_DIR, 'error_fix_pairs.json');
+    }
+    const resolved = (0, scopedKnowledgeStore_1.resolveKnowledgeScope)(scope);
+    return path.join(SQL_ERROR_LOG_DIR, resolved.tenantId, resolved.workspaceId, 'error_fix_pairs.json');
+}
+function loadLearnedSqlFixPairs(maxPairs = 10, scope) {
+    try {
+        const logFile = sqlErrorLogFile(scope);
+        if (!fs.existsSync(logFile))
+            return [];
+        const data = fs.readFileSync(logFile, 'utf-8');
+        const pairs = JSON.parse(data);
+        const cutoff = Date.now() - ERROR_FIX_PAIR_TTL_MS;
+        // Only return pairs that have successful fixes and are within TTL
+        return pairs
+            .filter(p => p.fixedSql && p.timestamp >= cutoff)
+            .slice(-maxPairs);
+    }
+    catch {
+        return [];
+    }
+}
+async function logSqlErrorFixPair(pair, scope) {
+    try {
+        const logFile = sqlErrorLogFile(scope);
+        let pairs = [];
+        try {
+            const data = await fs.promises.readFile(logFile, 'utf-8');
+            pairs = JSON.parse(data);
+        }
+        catch { /* fresh start */ }
+        // Deduplicate: if an equivalent error+fix pair already exists, update timestamp instead of appending
+        const existingIdx = pairs.findIndex(p => p.errorMessage === pair.errorMessage && p.fixedSql === pair.fixedSql);
+        if (existingIdx >= 0) {
+            pairs[existingIdx].timestamp = pair.timestamp;
+        }
+        else {
+            pairs.push(pair);
+        }
+        // Keep last 200 pairs
+        if (pairs.length > 200)
+            pairs = pairs.slice(-200);
+        await fs.promises.mkdir(path.dirname(logFile), { recursive: true });
+        // Atomic write: write to tmp file, then rename
+        const tmpFile = logFile + '.tmp';
+        await fs.promises.writeFile(tmpFile, JSON.stringify(pairs));
+        await fs.promises.rename(tmpFile, logFile);
+    }
+    catch (err) {
+        console.warn('[ClaudeMCP] Failed to log SQL error-fix pair:', err.message);
+    }
+}
+function loadSqlSchema() {
+    if (sqlSchemaCache)
+        return sqlSchemaCache;
+    const indexPath = path.resolve(__dirname, '../../data/perfettoSqlIndex.light.json');
+    try {
+        const raw = fs.readFileSync(indexPath, 'utf-8');
+        sqlSchemaCache = JSON.parse(raw);
+    }
+    catch (err) {
+        console.warn('[ClaudeMCP] Failed to load SQL schema index:', err.message);
+        sqlSchemaCache = { version: '0.0.0', generatedAt: '', templates: [] };
+    }
+    return sqlSchemaCache;
+}
+function compactSqlDocEntry(entry) {
+    const out = {
+        name: entry.name,
+        type: entry.type,
+        category: entry.category,
+        module: entry.module,
+        description: entry.description,
+        include: entry.include,
+    };
+    if (entry.tags?.length)
+        out.tags = entry.tags;
+    if (entry.columns?.length)
+        out.columns = entry.columns;
+    if (entry.params?.length)
+        out.params = entry.params;
+    if (entry.returnType)
+        out.returnType = entry.returnType;
+    if (entry.moduleIncludes?.length)
+        out.moduleIncludes = entry.moduleIncludes;
+    if (entry.transitiveIncludes?.length)
+        out.transitiveIncludes = entry.transitiveIncludes;
+    if (entry.lineage)
+        out.lineage = entry.lineage;
+    if (entry.dataCheckSql)
+        out.dataCheckSql = entry.dataCheckSql;
+    if (entry.sourcePath)
+        out.sourcePath = entry.sourcePath;
+    return out;
+}
+function compactLegacySqlSchemaEntry(entry) {
+    const out = {
+        name: entry.name,
+        type: entry.type,
+        category: entry.category,
+        description: entry.description,
+    };
+    if (entry.module)
+        out.module = entry.module;
+    if (entry.include)
+        out.include = entry.include;
+    if (entry.columns?.length)
+        out.columns = entry.columns;
+    if (entry.params?.length)
+        out.params = entry.params;
+    if (entry.returnType)
+        out.returnType = entry.returnType;
+    return out;
+}
+/**
+ * Normalize synthesizeData entry's `data` field into { columns, rows } format.
+ * synthesizeData entries can be:
+ *   - Array of objects: [{ col1: val1, col2: val2 }, ...]
+ *   - Already columnar: { columns: [...], rows: [[...], ...] }
+ *   - Iterator results: [{ itemIndex, item, result: { ... } }]
+ *   - Single object: { key: value, ... }
+ * All are normalized to { columns: string[], rows: any[][] } for ArtifactStore.
+ */
+function normalizeSynthesizeDataForStorage(data) {
+    if (!data)
+        return { columns: [], rows: [] };
+    // Already columnar format
+    if (data.columns && Array.isArray(data.rows)) {
+        return { columns: data.columns, rows: data.rows };
+    }
+    // Array of objects
+    if (Array.isArray(data) && data.length > 0) {
+        const first = data[0];
+        // Iterator format: flatten item + result
+        if (first && typeof first === 'object' && 'itemIndex' in first && 'result' in first) {
+            const allKeys = new Set();
+            const flatRows = data.map((entry) => {
+                const flat = { itemIndex: entry.itemIndex };
+                // Merge item fields
+                if (entry.item && typeof entry.item === 'object') {
+                    for (const [k, v] of Object.entries(entry.item)) {
+                        flat[k] = v;
+                        allKeys.add(k);
+                    }
+                }
+                // Merge result fields (top-level scalars only, skip nested objects)
+                if (entry.result && typeof entry.result === 'object') {
+                    for (const [k, v] of Object.entries(entry.result)) {
+                        if (typeof v !== 'object' || v === null) {
+                            flat[`result_${k}`] = v;
+                            allKeys.add(`result_${k}`);
+                        }
+                    }
+                }
+                allKeys.add('itemIndex');
+                return flat;
+            });
+            const columns = ['itemIndex', ...Array.from(allKeys).filter(k => k !== 'itemIndex')];
+            const rows = flatRows.map((row) => columns.map(c => row[c] ?? null));
+            return { columns, rows };
+        }
+        // Plain array of objects
+        if (typeof first === 'object' && first !== null) {
+            const columns = Object.keys(first);
+            const rows = data.map((row) => columns.map(c => row[c] ?? null));
+            return { columns, rows };
+        }
+        // Array of primitives — single column
+        return { columns: ['value'], rows: data.map((v) => [v]) };
+    }
+    // Single object → single row
+    if (typeof data === 'object' && data !== null) {
+        const columns = Object.keys(data);
+        const rows = [columns.map(c => data[c] ?? null)];
+        return { columns, rows };
+    }
+    // Scalar
+    return { columns: ['value'], rows: [[data]] };
+}
+/**
+ * Creates an in-process MCP server scoped to a specific trace session.
+ * Exposes domain tools: execute_sql, invoke_skill, list_skills,
+ * detect_architecture, lookup_sql_schema, and optionally write_analysis_note.
+ */
+function createClaudeMcpServer(options) {
+    const { traceId, traceProcessorService, skillExecutor, packageName, emitUpdate, onSkillResult, analysisNotes, artifactStore } = options;
+    const recentSqlErrors = options.recentSqlErrors || [];
+    const skillAdapter = (0, skillAnalysisAdapter_1.getSkillAnalysisAdapter)(traceProcessorService);
+    const watchdogRef = options.watchdogWarning;
+    const skillNotesBudget = options.skillNotesBudget;
+    const outputLanguage = options.outputLanguage ?? outputLanguage_1.DEFAULT_OUTPUT_LANGUAGE;
+    const knowledgeScope = options.knowledgeScope;
+    /** Normalize skill params: ensure process_name ↔ package are both set. */
+    function normalizeSkillParams(params, defaultPackage) {
+        const p = { ...params };
+        for (const key of Object.keys(p)) {
+            if (TIMESTAMP_EXPRESSION_PARAM_KEYS.has(key)) {
+                p[key] = normalizeTimestampExpression(p[key]);
+            }
+        }
+        if (defaultPackage && !p.process_name)
+            p.process_name = defaultPackage;
+        if (p.process_name && !p.package)
+            p.package = p.process_name;
+        if (p.package && !p.process_name)
+            p.process_name = p.package;
+        return p;
+    }
+    /**
+     * Consume and prepend any watchdog warning to a tool result.
+     * This is the feedback channel from runtime watchdog → Claude's execution context.
+     * When the watchdog detects repetitive tool failures, the warning appears
+     * in the NEXT tool result, which Claude reads and can act upon.
+     */
+    function consumeWatchdogWarning(resultText) {
+        if (watchdogRef?.current) {
+            const warning = watchdogRef.current;
+            watchdogRef.current = null; // consume once
+            return `⚠️ SYSTEM WARNING: ${warning}\n\n${resultText}`;
+        }
+        return resultText;
+    }
+    function rawSqlProcessIdentityWarning(sql) {
+        if (!(0, identityGate_1.sqlUsesProcessNameFilter)(sql))
+            return undefined;
+        return (0, outputLanguage_1.localize)(outputLanguage, 'Raw SQL 使用了进程/包名过滤；Process Identity Gate 只会自动保护 invoke_skill。信任这个 SQL 结论前，先用 process_identity_resolver 确认 canonical_package_name 与 recommended_process_name_param，或优先改用对应 Skill。', 'Raw SQL uses process/package-name filters; Process Identity Gate only protects invoke_skill automatically. Before trusting this SQL result, verify canonical_package_name and recommended_process_name_param with process_identity_resolver, or prefer the matching skill.');
+    }
+    function skipSqlQuotedText(sql, index, quote) {
+        let i = index + 1;
+        while (i < sql.length) {
+            if (sql[i] === quote) {
+                if (sql[i + 1] === quote) {
+                    i += 2;
+                    continue;
+                }
+                return i + 1;
+            }
+            i += 1;
+        }
+        return sql.length;
+    }
+    function skipSqlIgnoredText(sql, index) {
+        const char = sql[index];
+        const next = sql[index + 1];
+        if (char === '-' && next === '-') {
+            let i = index + 2;
+            while (i < sql.length && sql[i] !== '\n' && sql[i] !== '\r')
+                i += 1;
+            return i;
+        }
+        if (char === '/' && next === '*') {
+            let i = index + 2;
+            while (i < sql.length && !(sql[i] === '*' && sql[i + 1] === '/'))
+                i += 1;
+            return Math.min(sql.length, i + 2);
+        }
+        if (char === '\'' || char === '"' || char === '`')
+            return skipSqlQuotedText(sql, index, char);
+        if (char === '[') {
+            let i = index + 1;
+            while (i < sql.length && sql[i] !== ']')
+                i += 1;
+            return Math.min(sql.length, i + 1);
+        }
+        return index;
+    }
+    function readSqlIdentifierToken(sql, index) {
+        const char = sql[index];
+        if (char === '\'' || char === '"' || char === '`') {
+            const end = skipSqlQuotedText(sql, index, char);
+            const inner = sql.slice(index + 1, end - 1).split(`${char}${char}`).join(char);
+            return { value: inner, end };
+        }
+        if (char === '[') {
+            const end = skipSqlIgnoredText(sql, index);
+            return { value: sql.slice(index + 1, end - 1), end };
+        }
+        let i = index;
+        while (i < sql.length && /[A-Za-z0-9_$-]/.test(sql[i]))
+            i += 1;
+        if (i === index)
+            return null;
+        return { value: sql.slice(index, i), end: i };
+    }
+    function readSqlTableNameAfterFromOrJoin(sql, index) {
+        let i = index;
+        while (i < sql.length && /\s/.test(sql[i]))
+            i += 1;
+        if (sql[i] === '(')
+            return null;
+        let token = readSqlIdentifierToken(sql, i);
+        if (!token)
+            return null;
+        let tableName = token.value;
+        i = token.end;
+        while (i < sql.length && /\s/.test(sql[i]))
+            i += 1;
+        if (sql[i] === '.') {
+            i += 1;
+            while (i < sql.length && /\s/.test(sql[i]))
+                i += 1;
+            token = readSqlIdentifierToken(sql, i);
+            if (!token)
+                return { tableName, end: i };
+            tableName = token.value;
+            i = token.end;
+        }
+        return { tableName, end: i };
+    }
+    const tableAliasBoundaryWord = /^(WHERE|JOIN|LEFT|RIGHT|INNER|OUTER|CROSS|FULL|NATURAL|GROUP|ORDER|LIMIT|ON|USING|HAVING|UNION|EXCEPT|INTERSECT|WINDOW|QUALIFY|VALUES)$/i;
+    function readOptionalSqlAliasEnd(sql, index) {
+        let i = index;
+        while (i < sql.length && /\s/.test(sql[i]))
+            i += 1;
+        const asMatch = /^AS\b/i.exec(sql.slice(i));
+        if (asMatch) {
+            i += asMatch[0].length;
+            while (i < sql.length && /\s/.test(sql[i]))
+                i += 1;
+        }
+        const token = readSqlIdentifierToken(sql, i);
+        if (!token || tableAliasBoundaryWord.test(token.value))
+            return index;
+        return token.end;
+    }
+    function isArtifactPseudoTableName(tableName) {
+        const lower = tableName.toLowerCase();
+        return (lower !== '__intrinsic_batch_frame_root_cause' &&
+            (/^__intrinsic_[a-z_]\w*$/i.test(tableName) ||
+                /^art-\d+$/i.test(tableName) ||
+                lower === 'synthesizeartifacts' ||
+                lower === 'synthesize_artifacts' ||
+                lower === 'artifacts'));
+    }
+    function findArtifactPseudoTableNameInReference(sql, index) {
+        const table = readSqlTableNameAfterFromOrJoin(sql, index);
+        if (!table)
+            return { tableName: null, end: null };
+        const end = readOptionalSqlAliasEnd(sql, table.end);
+        return {
+            tableName: isArtifactPseudoTableName(table.tableName) ? table.tableName : null,
+            end: Math.max(table.end, end),
+        };
+    }
+    function findArtifactPseudoTableName(sql) {
+        let i = 0;
+        while (i < sql.length) {
+            const skipped = skipSqlIgnoredText(sql, i);
+            if (skipped !== i) {
+                i = skipped;
+                continue;
+            }
+            if (/[A-Za-z_]/.test(sql[i])) {
+                const wordStart = i;
+                while (i < sql.length && /[A-Za-z0-9_]/.test(sql[i]))
+                    i += 1;
+                const word = sql.slice(wordStart, i);
+                if (/^FROM$/i.test(word)) {
+                    while (i < sql.length) {
+                        const reference = findArtifactPseudoTableNameInReference(sql, i);
+                        if (reference.tableName)
+                            return reference.tableName;
+                        if (reference.end === null)
+                            break;
+                        i = reference.end;
+                        while (i < sql.length && /\s/.test(sql[i]))
+                            i += 1;
+                        if (sql[i] !== ',')
+                            break;
+                        i += 1;
+                    }
+                    continue;
+                }
+                if (/^JOIN$/i.test(word)) {
+                    const reference = findArtifactPseudoTableNameInReference(sql, i);
+                    if (reference.tableName)
+                        return reference.tableName;
+                    if (reference.end !== null)
+                        i = Math.max(i, reference.end);
+                }
+                continue;
+            }
+            i += 1;
+        }
+        return null;
+    }
+    function artifactSqlMisuseHint(sql, language) {
+        const tableName = findArtifactPseudoTableName(sql);
+        if (!tableName)
+            return null;
+        return {
+            success: false,
+            blocked: true,
+            error: (0, outputLanguage_1.localize)(language, `${tableName} 不是 trace_processor SQL 表。Skill 返回的 art-* / synthesizeArtifacts 是 SmartPerfetto artifact 引用，不能用 execute_sql 查询。`, `${tableName} is not a trace_processor SQL table. art-* / synthesizeArtifacts from Skill results are SmartPerfetto artifact references and cannot be queried with execute_sql.`),
+            action_required: 'fetch_artifact',
+            hint: 'Use fetch_artifact(artifactId="art-N", detail="rows", offset=0, limit=50) with the artifactId returned by invoke_skill.',
+            sql,
+        };
+    }
+    /**
+     * P0-G10: Enforce planning before analysis.
+     * Returns error JSON if plan is required but not yet submitted, null if OK.
+     * Only action tools (execute_sql, invoke_skill) are gated — informational
+     * and planning tools are exempt to allow plan formation.
+     */
+    const analysisPlanRef = options.analysisPlan;
+    /** Track submit_plan attempts for hard-gate: reject first incomplete plan, accept on retry. */
+    let planSubmitAttempts = 0;
+    function requirePlan(toolName) {
+        if (!analysisPlanRef)
+            return null; // Planning feature not enabled
+        if (analysisPlanRef.current)
+            return null; // Plan already submitted
+        return JSON.stringify({
+            success: false,
+            error: (0, outputLanguage_1.localize)(outputLanguage, `必须先调用 submit_plan 提交分析计划，然后才能使用 ${toolName}。请先制定你的分析计划，包含分析阶段、目标和预期工具。`, `You must call submit_plan before using ${toolName}. Create an analysis plan with phases, goals, and expected tools first.`),
+            action_required: 'submit_plan',
+        });
+    }
+    // Phase 1-C: Conditional REASONING_NUDGE — only append for first N data tool calls.
+    // After N calls, Claude should have internalized the reflect habit from system prompt.
+    const REASONING_NUDGE_MAX_CALLS = 4;
+    let dataToolCallCount = 0;
+    function getReasoningNudge() {
+        dataToolCallCount++;
+        if (dataToolCallCount > REASONING_NUDGE_MAX_CALLS)
+            return '';
+        return outputLanguage === 'en' ? REASONING_NUDGE_EN : REASONING_NUDGE_ZH;
+    }
+    let evidenceProducerOrdinal = 0;
+    function phaseHasToolExpectation(phase) {
+        return (phase.expectedCalls?.length || 0) > 0 || (phase.expectedTools?.length || 0) > 0;
+    }
+    function phaseMatchesToolInput(phase, toolName, input) {
+        const skillId = typeof input.skillId === 'string' ? input.skillId : undefined;
+        return (0, types_1.phaseMatchesCall)(phase, {
+            toolName,
+            timestamp: Date.now(),
+            skillId,
+        });
+    }
+    function phaseSemanticScore(phase, toolName, input) {
+        const skillId = typeof input.skillId === 'string' ? input.skillId : undefined;
+        const sql = typeof input.sql === 'string' ? input.sql : '';
+        const expected = [
+            ...(phase.expectedTools || []),
+            ...(phase.expectedCalls || []).map(call => call.skillId || call.tool),
+        ].join(' ');
+        const text = `${phase.id} ${phase.name} ${phase.goal} ${expected}`.toLowerCase();
+        const inputText = JSON.stringify(input ?? {}).toLowerCase();
+        let score = 0;
+        if (skillId) {
+            const id = skillId.toLowerCase();
+            if (text.includes(id))
+                score += 100;
+            if (text.includes(id.replace(/_/g, ' ')))
+                score += 60;
+            const hints = {
+                detect_architecture: ['架构', '渲染架构', '架构确认', '架构检测', '管线', 'pipeline', 'architecture'],
+                scrolling_analysis: ['滑动', 'scroll', '概览', '掉帧列表', '帧统计', '数据收集'],
+                startup_analysis: ['启动概览', '启动类型', '启动事件', 'startup', 'launch'],
+                startup_detail: ['启动详情', '四象限', '阻塞关系', '热点slice', '调度'],
+                startup_slow_reasons: ['慢原因', 'sr01', 'sr20', '交叉验证'],
+                memory_pressure_in_range: ['内存压力', 'memory', 'd状态', 'lmk', 'kswapd'],
+                blocking_chain_analysis: ['阻塞链', '阻塞关系', '唤醒', 'waker', 'blocked_functions', 'blocking_chain'],
+                lock_contention_in_range: ['锁竞争', 'futex', 'blocked_functions', '阻塞'],
+                binder_blocking_in_range: ['binder', '阻塞', '同步binder', 'ipc'],
+                jank_frame_detail: ['根因深钻', '单帧', '逐帧', 'jank_frame_detail', 'blocking_chain'],
+                frame_blocking_calls: ['根因深钻', '阻塞调用', 'frame_blocking_calls', 'blocking_chain'],
+                lock_binder_wait: ['根因深钻', '锁', 'binder', '阻塞', '等待', 'blocking_chain'],
+                frame_production_gap: ['缺帧', 'gap', '帧间', '隐形缺帧', '生产'],
+                batch_frame_root_cause: ['逐帧根因', 'reason_code', '根因分类'],
+            };
+            for (const hint of hints[id] || []) {
+                if (text.includes(hint.toLowerCase()))
+                    score += 20;
+            }
+            if (id === 'jank_frame_detail') {
+                if (/根因深钻|深钻|单帧|代表帧|最严重帧|机制级|detail|drill/.test(text))
+                    score += 60;
+                if (/分布|分类|聚合|统计|batch|reason_code/.test(text) && !/深钻|单帧|代表帧|最严重帧|机制级/.test(text))
+                    score -= 15;
+            }
+            if (id === 'blocking_chain_analysis') {
+                if (/阻塞链|阻塞关系|唤醒|waker|blocked_functions|blocking_chain|锁竞争|binder/.test(text))
+                    score += 70;
+                if (/根因|深钻|机制|代表帧|最严重帧|单帧|深入诊断|detail|drill|root cause/.test(text))
+                    score += 60;
+            }
+            if (id === 'memory_pressure_in_range') {
+                if (/内存压力|memory|lmk|kswapd|reclaim|gc|根因|交叉验证|排除/.test(text))
+                    score += 70;
+            }
+            if (id === 'startup_slow_reasons') {
+                if (/慢原因|启动慢|sr\d+|sr01|sr20|根因|交叉验证|已知原因/.test(text))
+                    score += 70;
+            }
+        }
+        if (toolName === 'detect_architecture') {
+            if (/架构|渲染架构|架构确认|架构检测|管线|architecture|pipeline|trace 时间范围|time range/.test(text))
+                score += 120;
+            if (/缺帧检测|frame_production_gap|gap detection/.test(text))
+                score -= 120;
+            if (/综合结论|结论|conclusion|报告|report/.test(text))
+                score -= 40;
+        }
+        if (toolName === 'fetch_artifact') {
+            if (/fetch_artifact|artifact|分页|全量|完整|掉帧数据|batch_frame_root_cause|根因数据/.test(text) &&
+                /全量|完整|掉帧|root_cause|batch_frame_root_cause|reason_code|artifact/.test(inputText)) {
+                score += 120;
+            }
+            if (/全量|完整|分页|batch_frame_root_cause|根因数据/.test(text) &&
+                /全量|完整|batch_frame_root_cause|reason_code|根因分布/.test(inputText)) {
+                score += 90;
+            }
+            if (/根因深钻|深钻|代表帧|最严重帧|机制级|blocking|jank_frame_detail|frame_blocking/.test(text) &&
+                /阻塞|blocking|代表|最严重|top_slice|jank_frame_detail|frame_blocking|主线程/.test(inputText)) {
+                score += 85;
+            }
+            if (/根因深钻|深钻|代表帧|最严重帧|机制级/.test(text) &&
+                /全量|完整|根因分布|batch_frame_root_cause/.test(inputText) &&
+                !/代表|最严重|阻塞|blocking|top_slice/.test(inputText)) {
+                score -= 40;
+            }
+            if (/概览|overview|滑动区间|帧统计|掉帧分布/.test(text) &&
+                /概览|summary|滑动区间|session|jank_type|性能概览/.test(inputText)) {
+                score += 60;
+            }
+            if (/综合结论|结论|conclusion|报告|report/.test(text))
+                score -= 30;
+        }
+        if (toolName === 'execute_sql' || toolName === 'execute_sql_on') {
+            const sqlText = sql.toLowerCase();
+            const isFrameOverviewSql = /actual_frame_timeline_slice/.test(sqlText) &&
+                (/min\s*\(\s*ts\s*\)/.test(sqlText) ||
+                    /max\s*\(\s*ts\s*\+\s*dur\s*\)/.test(sqlText) ||
+                    /count\s*\(\s*\*\s*\)/.test(sqlText) ||
+                    /\b(frame_count|total_frames|layer_count)\b/.test(sqlText));
+            const isTraceRangeSql = /actual_frame_timeline_slice/.test(sqlText) &&
+                /min\s*\(\s*ts\s*\)/.test(sqlText) &&
+                /max\s*\(\s*ts\s*\+\s*dur\s*\)/.test(sqlText);
+            const hasFrameOverviewPhaseHint = /概览|overview|数据收集|采集|帧统计|帧率统计|滑动区间|时间范围|time range/.test(text);
+            if (isTraceRangeSql) {
+                if (/trace|时间范围|时间边界|边界|time range|range/.test(text))
+                    score += 180;
+                if (/架构确认|确认.*架构|架构检测|检测.*架构|detect.*architecture|architecture.*detect/.test(text))
+                    score += 60;
+                if (/hwui|producer|surfaceflinger|sf|合成|链路/.test(text) && !hasFrameOverviewPhaseHint)
+                    score -= 50;
+                if (/根因|深钻|逐帧|reason_code|综合结论|报告/.test(text) && !hasFrameOverviewPhaseHint)
+                    score -= 50;
+            }
+            if (isFrameOverviewSql) {
+                if (hasFrameOverviewPhaseHint)
+                    score += 80;
+                if (/根因|深钻|逐帧|diagnos|root cause/.test(text))
+                    score -= 20;
+            }
+            const isRootCauseDrillSql = /\b(thread|thread_state|thread_slice|thread_track|slice|slice_self_dur|sched|futex|binder|blocking|root_cause|reason_code|top_slice|main_q4b|__intrinsic_batch_frame_root_cause)\b/.test(sqlText);
+            if (isRootCauseDrillSql) {
+                if (/根因|深钻|机制|阻塞|代表帧|逐帧|单帧|detail|drill|root cause|blocking/.test(text))
+                    score += 80;
+                if (/概览|overview|帧统计|掉帧分布|数据收集|采集/.test(text))
+                    score -= 10;
+            }
+            const isWebViewStartupSql = /webview|chromium|v8|crrenderermain|parsehtml|drawgl/.test(sqlText);
+            if (isWebViewStartupSql) {
+                if (/webview|chromium|v8|crrenderermain|parsehtml|drawgl|页面渲染/.test(text))
+                    score += 140;
+                if (/综合结论|结论|conclusion|报告|report/.test(text) && !/webview|chromium|v8/.test(text))
+                    score -= 30;
+            }
+            const sqlHints = [
+                [/webview|chromium|v8|crrenderermain|parsehtml|drawgl/, ['webview', 'chromium', 'v8', '页面渲染']],
+                [/actual_frame_timeline|expected_frame_timeline|jank|frame/, ['滑动', '掉帧', '帧', 'frame']],
+                [/\bthread\b|thread_state|thread_slice|slice_self_dur|sched|cpu|freq/, ['线程', '调度', 'cpu', '频率', '热点', '主线程', '阻塞']],
+                [/memory|lmk|kswapd|reclaim/, ['内存', 'memory', 'lmk']],
+            ];
+            for (const [pattern, hints] of sqlHints) {
+                if (!pattern.test(sqlText))
+                    continue;
+                for (const hint of hints) {
+                    if (text.includes(hint.toLowerCase()))
+                        score += 15;
+                }
+            }
+        }
+        return score;
+    }
+    function inferSemanticPhase(phases, toolName, input) {
+        const scored = phases
+            .map(phase => ({ phase, score: phaseSemanticScore(phase, toolName, input) }))
+            .filter(item => item.score > 0)
+            .sort((a, b) => b.score - a.score);
+        if (scored.length === 0)
+            return undefined;
+        if (scored.length === 1 || scored[0].score > scored[1].score)
+            return scored[0].phase;
+        return undefined;
+    }
+    function autoStartPhaseForEvidence(phase, toolName, input) {
+        const plan = analysisPlanRef?.current;
+        if (!plan || phase.status !== 'pending')
+            return false;
+        closeSupersededInProgressPhases(plan, phase);
+        phase.status = 'in_progress';
+        phase.completedAt = undefined;
+        phase.summary = undefined;
+        const narration = (0, toolNarration_1.formatToolCallNarration)(toolName, input, outputLanguage);
+        const summary = (0, outputLanguage_1.localize)(outputLanguage, `自动进入阶段：${narration}`, `Auto-started phase for: ${narration}`).slice(0, 260);
+        emitUpdate?.({
+            type: 'plan_phase_updated',
+            content: { phaseId: phase.id, status: 'in_progress', summary, phaseName: phase.name },
+            timestamp: Date.now(),
+        });
+        return true;
+    }
+    function autoClosedPhaseSummary(closedPhase, nextPhase) {
+        const artifacts = typeof artifactStore?.serialize === 'function'
+            ? artifactStore.serialize().filter(artifact => artifact.planPhaseId === closedPhase.id)
+            : [];
+        const titles = Array.from(new Set(artifacts
+            .map(artifact => artifact.title || artifact.stepId)
+            .filter((title) => typeof title === 'string' && title.trim().length > 0))).slice(0, 4);
+        const skillIds = Array.from(new Set(artifacts
+            .map(artifact => artifact.skillId)
+            .filter((skillId) => typeof skillId === 'string' && skillId.trim().length > 0))).slice(0, 3);
+        const moreCount = Math.max(0, artifacts.length - titles.length);
+        const titleSummary = titles.length
+            ? (0, outputLanguage_1.localize)(outputLanguage, `：${titles.join('、')}${moreCount > 0 ? `等 ${moreCount} 个` : ''}`, `: ${titles.join(', ')}${moreCount > 0 ? ` and ${moreCount} more` : ''}`)
+            : '';
+        const evidenceSummary = artifacts.length > 0
+            ? (0, outputLanguage_1.localize)(outputLanguage, `本阶段已产生 ${artifacts.length} 个证据表${skillIds.length ? `（来源：${skillIds.join('、')}）` : ''}${titleSummary}。`, `This phase produced ${artifacts.length} evidence table(s)${skillIds.length ? ` from ${skillIds.join(', ')}` : ''}${titleSummary}.`)
+            : (0, outputLanguage_1.localize)(outputLanguage, `本阶段未记录 artifact，但已保留该阶段的工具调用和时间线事件。`, `This phase did not record artifacts, but its tool calls and timeline events remain available.`);
+        return (0, outputLanguage_1.localize)(outputLanguage, `自动完成阶段「${closedPhase.name}」：已进入后续阶段「${nextPhase.name}」。${evidenceSummary}阶段目标：${closedPhase.goal}。上一阶段未收到显式完成摘要。`, `Auto-completed phase "${closedPhase.name}" after moving to "${nextPhase.name}". ${evidenceSummary} Phase goal: ${closedPhase.goal}. The previous phase did not provide an explicit completion summary.`);
+    }
+    function closeSupersededInProgressPhases(plan, nextPhase) {
+        const nextIndex = plan.phases.findIndex(p => p.id === nextPhase.id);
+        for (const other of plan.phases) {
+            if (other.id === nextPhase.id || other.status !== 'in_progress')
+                continue;
+            const otherIndex = plan.phases.findIndex(p => p.id === other.id);
+            if (otherIndex >= 0 && nextIndex >= 0 && otherIndex < nextIndex) {
+                const summary = autoClosedPhaseSummary(other, nextPhase);
+                other.status = 'completed';
+                other.completedAt = Date.now();
+                other.summary = summary;
+                emitUpdate?.({
+                    type: 'plan_phase_updated',
+                    content: { phaseId: other.id, status: 'completed', summary, phaseName: other.name },
+                    timestamp: Date.now(),
+                });
+            }
+            else {
+                other.status = 'pending';
+                other.completedAt = undefined;
+                other.summary = undefined;
+            }
+        }
+    }
+    function laterInProgressPhase(plan, phase) {
+        const phaseIndex = plan.phases.findIndex(p => p.id === phase.id);
+        if (phaseIndex < 0)
+            return undefined;
+        return plan.phases.find((p, index) => p.status === 'in_progress' && index > phaseIndex);
+    }
+    function bindPendingPhaseForEvidence(phase, toolName, input) {
+        const plan = analysisPlanRef?.current;
+        const laterActive = plan ? laterInProgressPhase(plan, phase) : undefined;
+        if (plan && phase.status === 'pending' && laterActive) {
+            const narration = (0, toolNarration_1.formatToolCallNarration)(toolName, input, outputLanguage);
+            const summary = (0, outputLanguage_1.localize)(outputLanguage, `自动补记阶段：收到本阶段证据（${narration}），但当前已在后续阶段「${laterActive.name}」。该阶段直接标记完成，证据以推断方式绑定。`, `Backfilled phase evidence (${narration}) while later phase "${laterActive.name}" was active. Marked this phase complete and bound the evidence as inferred.`).slice(0, 260);
+            phase.status = 'completed';
+            phase.completedAt = Date.now();
+            phase.summary = summary;
+            emitUpdate?.({
+                type: 'plan_phase_updated',
+                content: { phaseId: phase.id, status: 'completed', summary, phaseName: phase.name },
+                timestamp: Date.now(),
+            });
+            return {
+                phase,
+                attribution: 'inferred',
+                warning: (0, outputLanguage_1.localize)(outputLanguage, `证据语义匹配较早阶段 "${phase.name}"，但当前已在后续阶段 "${laterActive.name}"；已按补记阶段绑定，需要核对顺序。`, `Evidence semantically matched earlier phase "${phase.name}" while later phase "${laterActive.name}" was active; bound as a backfilled phase and should be checked for ordering.`),
+            };
+        }
+        autoStartPhaseForEvidence(phase, toolName, input);
+        return { phase, attribution: 'active' };
+    }
+    function activePlanPhaseForEvidence(toolName, input) {
+        const plan = analysisPlanRef?.current;
+        if (!plan)
+            return { attribution: 'none' };
+        const active = plan.phases.filter(p => p.status === 'in_progress');
+        if (active.length === 0) {
+            const isRawSqlTool = toolName === 'execute_sql' || toolName === 'execute_sql_on';
+            if (isRawSqlTool) {
+                const semanticPending = inferSemanticPhase(plan.phases.filter(p => p.status === 'pending'), toolName, input);
+                if (semanticPending) {
+                    return bindPendingPhaseForEvidence(semanticPending, toolName, input);
+                }
+                const semanticRecentCompleted = inferSemanticPhase(plan.phases
+                    .filter(p => p.status === 'completed' &&
+                    typeof p.completedAt === 'number' &&
+                    Date.now() - p.completedAt <= 5 * 60 * 1000)
+                    .sort((a, b) => (b.completedAt || 0) - (a.completedAt || 0)), toolName, input);
+                if (semanticRecentCompleted) {
+                    return {
+                        phase: semanticRecentCompleted,
+                        attribution: 'inferred',
+                        warning: (0, outputLanguage_1.localize)(outputLanguage, `当前没有明确进行中的 plan 阶段；已按 SQL 内容绑定到最近完成的阶段 "${semanticRecentCompleted.name}"，需要核对。`, `No plan phase is explicitly in progress; bound to the recently completed phase "${semanticRecentCompleted.name}" by SQL content and should be verified.`),
+                    };
+                }
+            }
+            const matchingPending = plan.phases.filter(p => p.status === 'pending' &&
+                phaseHasToolExpectation(p) &&
+                phaseMatchesToolInput(p, toolName, input));
+            if (matchingPending.length === 1) {
+                const phase = matchingPending[0];
+                return bindPendingPhaseForEvidence(phase, toolName, input);
+            }
+            if (matchingPending.length > 1) {
+                const phase = inferSemanticPhase(matchingPending, toolName, input);
+                if (phase) {
+                    return bindPendingPhaseForEvidence(phase, toolName, input);
+                }
+                return {
+                    attribution: 'ambiguous',
+                    warning: (0, outputLanguage_1.localize)(outputLanguage, `当前没有明确进行中的 plan 阶段，且 ${matchingPending.length} 个待执行阶段都匹配 ${toolName}；此数据未绑定具体阶段。`, `No plan phase is explicitly in progress and ${matchingPending.length} pending phases match ${toolName}; this data is not bound to a concrete phase.`),
+                };
+            }
+            const recentCompleted = plan.phases
+                .filter(p => p.status === 'completed' &&
+                typeof p.completedAt === 'number' &&
+                Date.now() - p.completedAt <= 5 * 60 * 1000 &&
+                phaseHasToolExpectation(p) &&
+                phaseMatchesToolInput(p, toolName, input))
+                .sort((a, b) => (b.completedAt || 0) - (a.completedAt || 0));
+            if (recentCompleted.length > 0) {
+                const phase = inferSemanticPhase(recentCompleted, toolName, input) || recentCompleted[0];
+                return {
+                    phase,
+                    attribution: 'inferred',
+                    warning: (0, outputLanguage_1.localize)(outputLanguage, `当前没有明确进行中的 plan 阶段；已绑定到最近完成且匹配工具的阶段 "${phase.name}"，需要核对。`, `No plan phase is explicitly in progress; bound to the most recently completed matching phase "${phase.name}" and should be verified.`),
+                };
+            }
+            const semanticPending = inferSemanticPhase(plan.phases.filter(p => p.status === 'pending' && phaseHasToolExpectation(p)), toolName, input);
+            if (semanticPending) {
+                return bindPendingPhaseForEvidence(semanticPending, toolName, input);
+            }
+            return {
+                attribution: 'missing',
+                warning: (0, outputLanguage_1.localize)(outputLanguage, '当前没有明确进行中的 plan 阶段；此数据未绑定具体阶段。', 'No plan phase is explicitly in progress; this data is not bound to a concrete phase.'),
+            };
+        }
+        if (active.length > 1) {
+            return {
+                attribution: 'ambiguous',
+                warning: (0, outputLanguage_1.localize)(outputLanguage, `当前有 ${active.length} 个 plan 阶段同时进行；此数据未绑定具体阶段。`, `${active.length} plan phases are in progress at the same time; this data is not bound to a concrete phase.`),
+            };
+        }
+        const phase = active[0];
+        const skillId = typeof input.skillId === 'string' ? input.skillId : undefined;
+        if (phaseHasToolExpectation(phase) && !phaseMatchesToolInput(phase, toolName, input)) {
+            const activeSemanticScore = phaseSemanticScore(phase, toolName, input);
+            const matchingPending = plan.phases.filter(p => p.status === 'pending' &&
+                phaseHasToolExpectation(p) &&
+                phaseMatchesToolInput(p, toolName, input));
+            const inferredPhase = matchingPending.length === 1
+                ? matchingPending[0]
+                : inferSemanticPhase(matchingPending, toolName, input);
+            if (inferredPhase) {
+                const inferredSemanticScore = phaseSemanticScore(inferredPhase, toolName, input);
+                if (activeSemanticScore >= 50 && inferredSemanticScore < activeSemanticScore + 30) {
+                    return { phase, attribution: 'active' };
+                }
+                return bindPendingPhaseForEvidence(inferredPhase, toolName, input);
+            }
+            const semanticPending = inferSemanticPhase(plan.phases.filter(p => p.status === 'pending' && phaseHasToolExpectation(p)), toolName, input);
+            if (semanticPending && phaseSemanticScore(semanticPending, toolName, input) >= 50) {
+                return bindPendingPhaseForEvidence(semanticPending, toolName, input);
+            }
+            if (activeSemanticScore >= 50) {
+                return { phase, attribution: 'active' };
+            }
+            return {
+                phase,
+                attribution: 'unexpected_tool',
+                warning: (0, outputLanguage_1.localize)(outputLanguage, `当前阶段 "${phase.name}" 未声明会调用 ${toolName}${skillId ? `(${skillId})` : ''}；此阶段归因需要人工核对。`, `Active phase "${phase.name}" did not declare ${toolName}${skillId ? `(${skillId})` : ''}; verify this phase attribution.`),
+            };
+        }
+        const activeSemanticScore = phaseSemanticScore(phase, toolName, input);
+        const semanticPending = inferSemanticPhase(plan.phases.filter(p => p.status === 'pending' && phaseHasToolExpectation(p)), toolName, input);
+        if (semanticPending) {
+            const pendingSemanticScore = phaseSemanticScore(semanticPending, toolName, input);
+            if (pendingSemanticScore >= 50 && pendingSemanticScore >= activeSemanticScore + 30) {
+                return bindPendingPhaseForEvidence(semanticPending, toolName, input);
+            }
+        }
+        return { phase, attribution: 'active' };
+    }
+    function createEvidenceProducerContext(toolName, input, producerReason, suffix, phaseOverride) {
+        const summary = (0, toolCallSummary_1.summarizeToolCallInput)(toolName, input);
+        const phaseResolution = phaseOverride?.phaseId
+            ? undefined
+            : activePlanPhaseForEvidence(toolName, input);
+        const phase = phaseResolution?.phase;
+        const lightweightPhase = !phaseOverride?.phaseId && !phase?.id && options.lightweight
+            ? {
+                id: 'quick',
+                name: (0, outputLanguage_1.localize)(outputLanguage, '快速回答', 'Quick answer'),
+                goal: (0, outputLanguage_1.localize)(outputLanguage, '用轻量工具链快速回答当前问题', 'Answer the current question with the lightweight tool chain.'),
+            }
+            : undefined;
+        const paramsHash = summary.paramsHash || evidenceHash(input);
+        const ordinal = ++evidenceProducerOrdinal;
+        const sourceToolCallId = [
+            toolName,
+            ordinal,
+            paramsHash,
+            suffix,
+        ].filter(Boolean).join(':');
+        return {
+            sourceToolCallId,
+            paramsHash,
+            planPhaseId: phaseOverride?.phaseId ?? phase?.id ?? lightweightPhase?.id,
+            planPhaseTitle: phaseOverride?.phaseTitle ?? phase?.name ?? lightweightPhase?.name,
+            planPhaseGoal: phaseOverride?.phaseGoal ?? phase?.goal ?? lightweightPhase?.goal,
+            planPhaseAttribution: phaseOverride?.attribution ?? (lightweightPhase ? 'active' : phaseResolution?.attribution),
+            planPhaseWarning: phaseOverride?.warning ?? phaseResolution?.warning,
+            toolNarration: (0, toolNarration_1.formatToolCallNarration)(toolName, input, outputLanguage),
+            producerReason,
+        };
+    }
+    async function detectArchitecturePayload() {
+        if (options.cachedArchitecture) {
+            const info = options.cachedArchitecture;
+            return {
+                type: info.type,
+                confidence: info.confidence,
+                evidence: (info.evidence ?? []).map(e => ({ source: e.source, type: e.type, weight: e.weight })),
+                flutter: info.flutter,
+                compose: info.compose,
+                webview: info.webview,
+                cached: true,
+            };
+        }
+        const detector = (0, architectureDetector_1.createArchitectureDetector)();
+        const info = await detector.detect({ traceId, traceProcessorService, packageName });
+        return {
+            type: info.type,
+            confidence: info.confidence,
+            evidence: (info.evidence ?? []).map(e => ({ source: e.source, type: e.type, weight: e.weight })),
+            flutter: info.flutter,
+            compose: info.compose,
+            webview: info.webview,
+        };
+    }
+    // Auto-inject `INCLUDE PERFETTO MODULE ...;` for stdlib tables/functions
+    // referenced in raw SQL. Shared between execute_sql and execute_sql_on
+    // so comparison-mode queries get the same treatment. See
+    // sqlIncludeInjector.ts for the full rationale.
+    async function runRawSqlWithIncludeInjection(targetTraceId, sql, traceSide = 'current') {
+        const normalized = (0, rawSqlNormalizer_1.normalizeRawSql)(sql);
+        const { sql: finalSql, injected } = (0, sqlIncludeInjector_1.injectStdlibIncludes)(normalized.sql);
+        const traceProvenance = (0, traceProcessorConnectionModel_1.buildTraceProcessorQueryProvenance)({
+            traceId: targetTraceId,
+            traceSide,
+        });
+        if (emitUpdate && injected.length > 0) {
+            emitUpdate({
+                type: 'progress',
+                content: {
+                    phase: 'analyzing',
+                    message: (0, outputLanguage_1.localize)(outputLanguage, `自动加载 stdlib 模块: ${injected.join(', ')}`, `Auto-loaded stdlib module(s): ${injected.join(', ')}`),
+                },
+                timestamp: Date.now(),
+            });
+        }
+        const result = await traceProcessorService.query(targetTraceId, finalSql);
+        return {
+            result,
+            finalSql,
+            injected,
+            traceProvenance,
+            normalizedSql: normalized.sql,
+            sqlRewrites: normalized.rewrites,
+        };
+    }
+    const executeSql = (0, claude_agent_sdk_1.tool)('execute_sql', 'Execute a raw SQL query against the Perfetto trace_processor for the currently loaded trace. ' +
+        'Returns columnar results. Set summary=true for large result sets to get column statistics + sample rows.\n\n' +
+        'Use when: ad-hoc queries not covered by existing skills, verifying hypotheses with specific SQL, checking raw data.\n' +
+        'Don\'t use when: a matching skill exists (use invoke_skill instead — richer layered output), or you need schema info (use lookup_sql_schema first).\n\n' +
+        'SQL safety rules: qualify duplicate column names after JOINs. Do not write bare SELECT name/ts/dur when joining slice/thread/process; use s.name AS slice_name, s.ts, s.dur, t.name AS thread_name, p.name AS process_name, or prefer the thread_slice stdlib view. FrameTimeline rows expose upid, not utid/process_name; use JOIN process USING(upid) for actual_frame_timeline_slice. thread_slice does not expose self_dur directly; JOIN slice_self_dur USING(id) when self time is needed. When using thread_slice, read thread_name and process_name directly; do not write t.name or p.name unless JOIN thread t or JOIN process p is present. The thread table main-thread column is is_main_thread, not main_thread. Do not query __intrinsic_* names or skill step names such as batch_frame_root_cause as SQL tables; they are skill artifacts, use fetch_artifact for those rows.\n\n' +
+        'Examples:\n' +
+        '1. Count jank frames: sql="SELECT COUNT(*) as jank_count FROM actual_frame_timeline_slice WHERE jank_type != \'None\'", summary=false\n' +
+        '2. CPU frequency overview: sql="SELECT cpu, MIN(value) as min_freq, MAX(value) as max_freq, AVG(value) as avg_freq FROM counter JOIN counter_track ON counter.track_id=counter_track.id WHERE counter_track.name GLOB \'cpu*freq\' GROUP BY cpu", summary=true\n' +
+        '3. Thread state in time range: sql="SELECT state, SUM(dur)/1e6 as total_ms FROM thread_state WHERE utid=123 AND ts BETWEEN 1000 AND 2000 GROUP BY state", summary=false', {
+        sql: zod_1.z.string().describe('The SQL query to execute. Use Perfetto stdlib tables/functions (e.g. android_jank_cuj, slice, thread, process).'),
+        summary: zod_1.z.boolean().optional().describe('When true, returns column statistics (min/max/avg/percentiles) + 10 most interesting sample rows instead of full results. Use for large result sets where you need aggregate understanding, not row-level data. Default: false.'),
+    }, async ({ sql, summary }) => {
+        // P0-G10: Block analysis tools until plan is submitted
+        const planError = requirePlan('execute_sql');
+        if (planError) {
+            return { content: [{ type: 'text', text: planError }] };
+        }
+        const artifactSqlHint = artifactSqlMisuseHint(sql, outputLanguage);
+        if (artifactSqlHint) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify(artifactSqlHint) }],
+                isError: true,
+            };
+        }
+        const producer = createEvidenceProducerContext('execute_sql', { sql, summary }, (0, outputLanguage_1.localize)(outputLanguage, '执行当前 Trace SQL，验证本阶段的具体数据点。', 'Run SQL on the current trace to verify this phase of evidence.'));
+        try {
+            const sqlStart = Date.now();
+            const { result, finalSql, injected, traceProvenance, normalizedSql, sqlRewrites } = await runRawSqlWithIncludeInjection(traceId, sql, 'current');
+            const processIdentityWarning = rawSqlProcessIdentityWarning(normalizedSql);
+            const truncated = result.rows.length > 200;
+            const rows = truncated ? result.rows.slice(0, 200) : result.rows;
+            const success = !result.error;
+            const sqlDuration = Date.now() - sqlStart;
+            if (emitUpdate && sqlDuration > 500) {
+                emitUpdate({
+                    type: 'progress',
+                    content: {
+                        phase: 'analyzing',
+                        message: (0, outputLanguage_1.localize)(outputLanguage, `SQL 查询完成 (${result.rows.length} 行, ${sqlDuration}ms)`, `SQL query completed (${result.rows.length} rows, ${sqlDuration}ms)`),
+                    },
+                    timestamp: Date.now(),
+                });
+            }
+            let emittedEvidence;
+            if (emitUpdate && !success && result.error) {
+                emitUpdate({
+                    type: 'progress',
+                    content: {
+                        phase: 'analyzing',
+                        message: (0, outputLanguage_1.localize)(outputLanguage, `SQL 查询错误: ${result.error.substring(0, 200)}`, `SQL query error: ${result.error.substring(0, 200)}`),
+                    },
+                    timestamp: Date.now(),
+                });
+            }
+            // SQL error-fix pair learning: capture errors and match subsequent fixes
+            if (!success && result.error) {
+                recentSqlErrors.push({ errorSql: sql, errorMessage: result.error, timestamp: Date.now() });
+                // Keep only last 10 errors in memory
+                if (recentSqlErrors.length > 10)
+                    recentSqlErrors.shift();
+            }
+            else if (success && recentSqlErrors.length > 0) {
+                // Match error-fix pairs by timestamp proximity (same turn, within 60s)
+                // and structural similarity (>30% token overlap via Jaccard similarity).
+                // SQL structural keywords + Perfetto domain tokens are excluded to avoid
+                // false matches between unrelated queries that share common vocabulary.
+                const matchingError = recentSqlErrors.find(e => {
+                    // Must be within 60 seconds (covers multi-turn reasoning gaps)
+                    if (Date.now() - e.timestamp > 60000)
+                        return false;
+                    // Require reasonable structural similarity (not a totally different query)
+                    const errorTokens = sqlContentTokens(e.errorSql);
+                    const fixTokens = sqlContentTokens(sql);
+                    if (errorTokens.size === 0)
+                        return false;
+                    let intersection = 0;
+                    for (const t of errorTokens) {
+                        if (fixTokens.has(t))
+                            intersection++;
+                    }
+                    const union = new Set([...errorTokens, ...fixTokens]).size;
+                    const jaccard = union > 0 ? intersection / union : 0;
+                    return jaccard > 0.3; // At least 30% token overlap
+                });
+                if (matchingError) {
+                    await logSqlErrorFixPair({ ...matchingError, fixedSql: sql }, knowledgeScope);
+                    const idx = recentSqlErrors.indexOf(matchingError);
+                    if (idx >= 0)
+                        recentSqlErrors.splice(idx, 1);
+                }
+            }
+            // Summary mode: return column statistics + sample rows instead of raw data
+            if (summary && success && rows.length > 0) {
+                const summaryResult = (0, sqlSummarizer_1.summarizeSqlResult)(result.columns, result.rows);
+                if (emitUpdate) {
+                    emittedEvidence = emitSqlSummaryDataEnvelope(emitUpdate, summaryResult, finalSql, injected, traceProvenance, producer);
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: consumeWatchdogWarning(JSON.stringify({
+                                success: true,
+                                mode: 'summary',
+                                totalRows: summaryResult.totalRows,
+                                columns: summaryResult.columns,
+                                columnStats: summaryResult.columnStats,
+                                sampleRows: summaryResult.sampleRows,
+                                durationMs: result.durationMs,
+                                traceSide: traceProvenance.traceSide,
+                                traceId: traceProvenance.traceId,
+                                traceProvenance,
+                                evidenceRefId: emittedEvidence?.evidenceRefId,
+                                sourceToolCallId: producer.sourceToolCallId,
+                                paramsHash: producer.paramsHash,
+                                planPhaseId: producer.planPhaseId,
+                                executableSql: finalSql,
+                                ...(sqlRewrites.length > 0 ? { sqlRewrites } : {}),
+                                stdlibInjectedModules: injected,
+                                ...(processIdentityWarning ? { processIdentityWarning } : {}),
+                            })) + getReasoningNudge(),
+                        }],
+                };
+            }
+            if (emitUpdate && success && result.columns.length > 0) {
+                emittedEvidence = emitSqlDataEnvelope(emitUpdate, result.columns, rows, finalSql, injected, traceProvenance, producer);
+            }
+            else if (emitUpdate && !success) {
+                emittedEvidence = emitSqlDiagnosticDataEnvelope(emitUpdate, result.error || (0, outputLanguage_1.localize)(outputLanguage, 'SQL 执行失败', 'SQL execution failed'), finalSql, injected, traceProvenance, producer, outputLanguage);
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: consumeWatchdogWarning(JSON.stringify({
+                            success,
+                            columns: result.columns,
+                            rows,
+                            totalRows: result.rows.length,
+                            truncated,
+                            durationMs: result.durationMs,
+                            traceSide: traceProvenance.traceSide,
+                            traceId: traceProvenance.traceId,
+                            traceProvenance,
+                            evidenceRefId: emittedEvidence?.evidenceRefId,
+                            sourceToolCallId: producer.sourceToolCallId,
+                            paramsHash: producer.paramsHash,
+                            planPhaseId: producer.planPhaseId,
+                            executableSql: finalSql,
+                            ...(sqlRewrites.length > 0 ? { sqlRewrites } : {}),
+                            stdlibInjectedModules: injected,
+                            ...(processIdentityWarning ? { processIdentityWarning } : {}),
+                            ...(result.error ? { error: result.error } : {}),
+                        })) + (success ? getReasoningNudge() : ''),
+                    }],
+            };
+        }
+        catch (err) {
+            const errMsg = err.message;
+            const traceProvenance = (0, traceProcessorConnectionModel_1.buildTraceProcessorQueryProvenance)({
+                traceId,
+                traceSide: 'current',
+            });
+            const emittedEvidence = emitUpdate ? emitSqlDiagnosticDataEnvelope(emitUpdate, errMsg, sql, undefined, traceProvenance, producer, outputLanguage) : undefined;
+            emitUpdate?.({
+                type: 'progress',
+                content: {
+                    phase: 'analyzing',
+                    message: (0, outputLanguage_1.localize)(outputLanguage, `SQL 查询失败: ${errMsg}`, `SQL query failed: ${errMsg}`),
+                },
+                timestamp: Date.now(),
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            success: false,
+                            traceSide: 'current',
+                            traceId,
+                            traceProvenance,
+                            evidenceRefId: emittedEvidence?.evidenceRefId,
+                            sourceToolCallId: producer.sourceToolCallId,
+                            paramsHash: producer.paramsHash,
+                            planPhaseId: producer.planPhaseId,
+                            error: errMsg,
+                        }) }],
+                isError: true,
+            };
+        }
+    }, { annotations: { readOnlyHint: true } });
+    const invokeSkill = (0, claude_agent_sdk_1.tool)('invoke_skill', 'Execute a named SmartPerfetto skill pipeline against the current trace. ' +
+        'Skills are pre-built analysis routines that produce layered results (overview → list → diagnosis → deep). ' +
+        'Use list_skills first to find the right skill ID.\n\n' +
+        'Use when: a pre-built skill covers your analysis need — always prefer this over raw SQL for supported scenarios.\n' +
+        'Don\'t use when: you need a custom query not covered by any skill (use execute_sql), or exploring what skills exist (use list_skills).\n\n' +
+        'Examples:\n' +
+        '1. Full scrolling analysis: skillId="scrolling_analysis", params={process_name: "com.example.app"}\n' +
+        '2. Single jank frame detail: skillId="jank_frame_detail", params={frame_number: 42, process_name: "com.example.app"}\n' +
+        '3. Startup analysis: skillId="startup_analysis", params={process_name: "com.example.app"}', {
+        skillId: zod_1.z.string().describe('Skill identifier (e.g. "scrolling_analysis", "jank_frame_detail", "cpu_analysis")'),
+        params: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Optional parameters to pass to the skill. Common: { process_name, start_ts, end_ts, max_frames_per_session }'),
+    }, async ({ skillId, params }) => {
+        // P0-G10: Block analysis tools until plan is submitted
+        const skillPlanError = requirePlan('invoke_skill');
+        if (skillPlanError) {
+            return { content: [{ type: 'text', text: skillPlanError }] };
+        }
+        if (skillId === 'detect_architecture') {
+            const effectiveParams = normalizeSkillParams(params, packageName);
+            const producer = createEvidenceProducerContext('invoke_skill', { skillId, params: effectiveParams }, (0, outputLanguage_1.localize)(outputLanguage, '调用 Skill detect_architecture，确认渲染架构并决定后续分析链路。', 'Run Skill detect_architecture to identify the rendering pipeline for later analysis.'));
+            try {
+                emitUpdate?.({
+                    type: 'progress',
+                    content: {
+                        phase: 'analyzing',
+                        message: (0, outputLanguage_1.localize)(outputLanguage, '检测渲染架构...', 'Detecting rendering architecture...'),
+                    },
+                    timestamp: Date.now(),
+                });
+                const payload = await detectArchitecturePayload();
+                emitUpdate?.({
+                    type: 'progress',
+                    content: {
+                        phase: 'analyzing',
+                        message: (0, outputLanguage_1.localize)(outputLanguage, `架构检测完成: ${String(payload.type ?? 'unknown')} (置信度 ${Math.round(Number(payload.confidence ?? 0) * 100)}%)`, `Architecture detection completed: ${String(payload.type ?? 'unknown')} (${Math.round(Number(payload.confidence ?? 0) * 100)}% confidence)`),
+                    },
+                    timestamp: Date.now(),
+                });
+                return {
+                    content: [{
+                            type: 'text',
+                            text: consumeWatchdogWarning(JSON.stringify({
+                                success: true,
+                                skillId: 'detect_architecture',
+                                delegatedTool: 'detect_architecture',
+                                sourceToolCallId: producer.sourceToolCallId,
+                                paramsHash: producer.paramsHash,
+                                planPhaseId: producer.planPhaseId,
+                                ...payload,
+                            })) + getReasoningNudge(),
+                        }],
+                };
+            }
+            catch (err) {
+                const errMsg = err.message;
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({
+                                success: false,
+                                skillId,
+                                sourceToolCallId: producer.sourceToolCallId,
+                                paramsHash: producer.paramsHash,
+                                planPhaseId: producer.planPhaseId,
+                                error: errMsg,
+                            }) }],
+                    isError: true,
+                };
+            }
+        }
+        // Guard: metadata-only skills are not executable single-trace analysis skills
+        const skillDef = skillLoader_1.skillRegistry.getSkill(skillId);
+        if (skillDef?.type === 'pipeline_definition' || skillDef?.type === 'comparison') {
+            const useHint = skillDef.type === 'comparison'
+                ? 'It describes analysis result comparison. Use the multi-trace comparison API/tools instead.'
+                : 'Use `detect_architecture` to detect the rendering pipeline, or call a composite analysis skill like `scrolling_analysis`, `gpu_analysis`, etc.';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Skill "${skillId}" is metadata-only and cannot be used for single-trace analysis. ${useHint}`,
+                        }),
+                    }],
+            };
+        }
+        try {
+            const effectiveParams = normalizeSkillParams(params, packageName);
+            const producer = createEvidenceProducerContext('invoke_skill', { skillId, params: effectiveParams }, (0, outputLanguage_1.localize)(outputLanguage, `调用 Skill ${skillId}，收集本阶段结构化证据。`, `Run Skill ${skillId} to collect structured evidence for this phase.`));
+            emitUpdate?.({
+                type: 'progress',
+                content: {
+                    phase: 'analyzing',
+                    message: (0, outputLanguage_1.localize)(outputLanguage, `运行分析技能: ${skillId}...`, `Running analysis skill: ${skillId}...`),
+                },
+                timestamp: Date.now(),
+            });
+            const skillStart = Date.now();
+            const result = await skillExecutor.execute(skillId, traceId, effectiveParams);
+            const skillDuration = Date.now() - skillStart;
+            emitUpdate?.({
+                type: 'progress',
+                content: {
+                    phase: 'analyzing',
+                    message: (0, outputLanguage_1.localize)(outputLanguage, `技能 ${skillId} 完成 (${skillDuration}ms, ${result.displayResults?.length || 0} 个结果层)`, `Skill ${skillId} completed (${skillDuration}ms, ${result.displayResults?.length || 0} result layers)`),
+                },
+                timestamp: Date.now(),
+            });
+            // Capture skill SQL errors in the learning system — skill SQL is the most complex
+            // and most likely to break across Perfetto versions.
+            // P1-3: Also persist to disk for cross-session learning (same as execute_sql errors).
+            if (!result.success && result.error && result.error.includes('SQL')) {
+                const errorPair = {
+                    errorSql: `[skill:${skillId}] ${JSON.stringify(effectiveParams)}`,
+                    errorMessage: result.error,
+                    timestamp: Date.now(),
+                };
+                recentSqlErrors.push(errorPair);
+                if (recentSqlErrors.length > 10)
+                    recentSqlErrors.shift();
+                // Persist to disk (fire-and-forget) for cross-session learning
+                logSqlErrorFixPair(errorPair, knowledgeScope).catch(() => { });
+            }
+            if (emitUpdate && result.displayResults?.length) {
+                emitSkillDataEnvelopes(result.displayResults, result.skillId || skillId, emitUpdate, undefined, producer);
+            }
+            if (onSkillResult && result.success && result.displayResults?.length) {
+                onSkillResult({ skillId: result.skillId || skillId, displayResults: result.displayResults });
+            }
+            // Prepend skill notes when the per-analysis budget allows. Notes
+            // only attach on the success path so a failed skill doesn't pollute
+            // the agent's context with unrelated guidance.
+            let skillNotesPrefix = '';
+            if (skillNotesBudget && result.success) {
+                try {
+                    const candidates = (0, skillNotesInjector_1.loadSkillNotes)(result.skillId || skillId);
+                    if (candidates.length > 0) {
+                        const consumed = skillNotesBudget.tryConsume(result.skillId || skillId, candidates);
+                        if (consumed)
+                            skillNotesPrefix = `${consumed.text}\n\n`;
+                    }
+                }
+                catch (err) {
+                    console.warn('[invoke_skill] skill notes injection failed:', err.message);
+                }
+            }
+            // Vendor override hint: if a vendor is detected and overrides exist for this skill,
+            // include a hint in the result so Claude can consider vendor-specific analysis steps.
+            let vendorOverrideHint;
+            const detectedVendor = options.cachedVendor;
+            if (detectedVendor && detectedVendor !== 'aosp' && result.success) {
+                const vendorOverride = skillLoader_1.skillRegistry.getVendorOverride(skillId, detectedVendor);
+                if (vendorOverride && vendorOverride.additionalSteps.length > 0) {
+                    vendorOverrideHint = {
+                        vendor: vendorOverride.vendor,
+                        displayName: vendorOverride.displayName,
+                        additionalStepIds: vendorOverride.additionalSteps
+                            .map((s) => s.id || s.name)
+                            .filter(Boolean),
+                    };
+                }
+            }
+            // Artifact mode: store displayResults AND synthesizeData as artifacts, return compact references
+            if (artifactStore && result.displayResults?.length) {
+                const artifacts = result.displayResults.map(dr => {
+                    const artId = artifactStore.store({
+                        skillId: result.skillId || skillId,
+                        stepId: dr.stepId,
+                        layer: dr.layer,
+                        title: dr.title,
+                        data: dr.data,
+                        diagnostics: undefined,
+                        planPhaseId: producer.planPhaseId,
+                        planPhaseTitle: producer.planPhaseTitle,
+                        planPhaseGoal: producer.planPhaseGoal,
+                        sourceToolCallId: producer.sourceToolCallId,
+                        paramsHash: producer.paramsHash,
+                    });
+                    const summary = artifactStore.generateCompactSummary(artId);
+                    return summary;
+                });
+                // Store diagnostics as a separate artifact if present
+                let diagnosticsArtifactId;
+                if (result.diagnostics && Array.isArray(result.diagnostics) && result.diagnostics.length > 0) {
+                    diagnosticsArtifactId = artifactStore.store({
+                        skillId: result.skillId || skillId,
+                        stepId: '_diagnostics',
+                        layer: 'diagnosis',
+                        title: `${skillId} diagnostics`,
+                        data: { columns: ['diagnostic'], rows: result.diagnostics.map((d) => [d]) },
+                        diagnostics: result.diagnostics,
+                        planPhaseId: producer.planPhaseId,
+                        planPhaseTitle: producer.planPhaseTitle,
+                        planPhaseGoal: producer.planPhaseGoal,
+                        sourceToolCallId: producer.sourceToolCallId,
+                        paramsHash: producer.paramsHash,
+                    });
+                }
+                // Store synthesizeData entries as artifacts too — these contain the raw step data
+                // (e.g. batch_frame_root_cause with 487 rows) that would otherwise overflow token limits.
+                // Claude can fetch them on demand via fetch_artifact with pagination.
+                let synthesizeArtifacts;
+                if (result.synthesizeData && Array.isArray(result.synthesizeData) && result.synthesizeData.length > 0) {
+                    synthesizeArtifacts = result.synthesizeData
+                        .filter((sd) => sd.data && sd.success !== false)
+                        .map((sd) => {
+                        // synthesizeData entries have data as array-of-objects or { columns, rows }
+                        const normalizedData = normalizeSynthesizeDataForStorage(sd.data);
+                        const artId = artifactStore.store({
+                            skillId: result.skillId || skillId,
+                            stepId: sd.stepId,
+                            layer: sd.layer || 'synthesize',
+                            title: sd.stepName || sd.stepId,
+                            data: normalizedData,
+                            planPhaseId: producer.planPhaseId,
+                            planPhaseTitle: producer.planPhaseTitle,
+                            planPhaseGoal: producer.planPhaseGoal,
+                            sourceToolCallId: producer.sourceToolCallId,
+                            paramsHash: producer.paramsHash,
+                        });
+                        return {
+                            artifactId: artId,
+                            stepId: sd.stepId,
+                            rowCount: normalizedData.rows?.length ?? 0,
+                            columns: normalizedData.columns ?? [],
+                        };
+                    });
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: skillNotesPrefix + consumeWatchdogWarning(JSON.stringify({
+                                success: result.success,
+                                skillId: result.skillId,
+                                skillName: result.skillName,
+                                ...(result.error ? { error: result.error } : {}),
+                                artifacts,
+                                ...(diagnosticsArtifactId ? { diagnosticsArtifactId } : {}),
+                                ...(synthesizeArtifacts && synthesizeArtifacts.length > 0
+                                    ? { synthesizeArtifacts }
+                                    : {}),
+                                ...(vendorOverrideHint ? { vendorOverride: vendorOverrideHint } : {}),
+                                hint: 'Use fetch_artifact(artifactId=<id>, detail="rows", offset=0, limit=50) to page through large datasets. All data is accessible — use offset/limit to paginate.',
+                            })) + (result.success ? getReasoningNudge() : ''),
+                        }],
+                };
+            }
+            // Default: return full displayResults (backward compatible)
+            return {
+                content: [{
+                        type: 'text',
+                        text: skillNotesPrefix + consumeWatchdogWarning(JSON.stringify({
+                            success: result.success,
+                            skillId: result.skillId,
+                            skillName: result.skillName,
+                            ...(result.error ? { error: result.error } : {}),
+                            ...(vendorOverrideHint ? { vendorOverride: vendorOverrideHint } : {}),
+                            displayResults: result.displayResults?.map(dr => ({
+                                stepId: dr.stepId,
+                                title: dr.title,
+                                layer: dr.layer,
+                                data: dr.data,
+                            })),
+                            diagnostics: result.diagnostics,
+                            synthesizeData: result.synthesizeData,
+                        })) + (result.success ? getReasoningNudge() : ''),
+                    }],
+            };
+        }
+        catch (err) {
+            const errMsg = err.message;
+            emitUpdate?.({
+                type: 'progress',
+                content: {
+                    phase: 'analyzing',
+                    message: (0, outputLanguage_1.localize)(outputLanguage, `技能 ${skillId} 执行失败: ${errMsg}`, `Skill ${skillId} failed: ${errMsg}`),
+                },
+                timestamp: Date.now(),
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: errMsg }) }],
+                isError: true,
+            };
+        }
+    }, { annotations: { readOnlyHint: true } });
+    const listSkills = (0, claude_agent_sdk_1.tool)('list_skills', 'List all available SmartPerfetto analysis skills. ' +
+        'Use this to discover which skills exist before invoking one. ' +
+        'Filter by category to narrow results (e.g. "scrolling", "startup", "cpu", "memory").', {
+        category: zod_1.z.string().optional().describe('Optional filter: only return skills whose keywords or tags match this category'),
+    }, async ({ category }) => {
+        try {
+            const allSkills = await skillAdapter.listSkills();
+            const filtered = category
+                ? allSkills.filter(s => s.keywords.some(k => k.toLowerCase().includes(category.toLowerCase())) ||
+                    s.tags?.some(t => t.toLowerCase().includes(category.toLowerCase())) ||
+                    s.id.toLowerCase().includes(category.toLowerCase()))
+                : allSkills;
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(filtered.map(s => ({
+                            id: s.id,
+                            displayName: s.displayName,
+                            description: s.description,
+                            type: s.type,
+                            keywords: s.keywords.slice(0, 5),
+                        }))),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: err.message }) }],
+                isError: true,
+            };
+        }
+    }, { annotations: { readOnlyHint: true } });
+    const detectArchitecture = (0, claude_agent_sdk_1.tool)('detect_architecture', 'Detect the rendering architecture of the app in the current trace. ' +
+        'Returns architecture type (STANDARD/FLUTTER/COMPOSE/WEBVIEW/etc.), confidence, and evidence. ' +
+        'Call this early to understand which analysis approach to use.', {}, async () => {
+        const producer = createEvidenceProducerContext('detect_architecture', {}, (0, outputLanguage_1.localize)(outputLanguage, '检测渲染架构，确定后续分析路径。', 'Detect rendering architecture to choose the later analysis path.'));
+        try {
+            const payload = await detectArchitecturePayload();
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            ...payload,
+                            sourceToolCallId: producer.sourceToolCallId,
+                            paramsHash: producer.paramsHash,
+                            planPhaseId: producer.planPhaseId,
+                        }),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            success: false,
+                            sourceToolCallId: producer.sourceToolCallId,
+                            paramsHash: producer.paramsHash,
+                            planPhaseId: producer.planPhaseId,
+                            error: err.message,
+                        }) }],
+                isError: true,
+            };
+        }
+    }, { annotations: { readOnlyHint: true } });
+    const lookupSqlSchema = (0, claude_agent_sdk_1.tool)('lookup_sql_schema', 'Search the Perfetto SQL stdlib index for table, view, and function definitions matching a keyword. ' +
+        'Use this to discover available SQL entities before writing raw SQL queries.\n\n' +
+        'Use when: you need to find table/view/function names before writing SQL, or verifying column names exist.\n' +
+        'Don\'t use when: you already know the exact table name, or need the full stdlib module list (use list_stdlib_modules).\n\n' +
+        'Examples:\n' +
+        '1. Find frame-related tables: keyword="frame_timeline"\n' +
+        '2. Find binder tables: keyword="binder"\n' +
+        '3. Find thread state columns: keyword="thread_state"', {
+        keyword: zod_1.z.string().describe('Search keyword (e.g. "jank", "slice", "thread_state", "android_frames")'),
+    }, async ({ keyword }) => {
+        const schema = loadSqlSchema();
+        const lower = keyword.toLowerCase();
+        const docResults = (0, perfettoSqlDocs_1.searchPerfettoSqlDocs)(keyword, { limit: 30 });
+        // P2-G8: Token-based fuzzy matching — split keyword into tokens and match independently
+        const tokens = lower.split(/[\s_]+/).filter(t => t.length >= 2);
+        // Scoring function: exact substring match scores highest, token prefix matches next
+        function scoreEntry(t) {
+            const name = t.name.toLowerCase();
+            const cat = t.category.toLowerCase();
+            const desc = t.description.toLowerCase();
+            const searchable = `${name} ${cat} ${desc}`;
+            // Exact substring match (original behavior)
+            if (name.includes(lower) || cat.includes(lower) || desc.includes(lower))
+                return 10;
+            // Token-based matching: count how many query tokens match
+            if (tokens.length <= 1)
+                return 0;
+            let matchedTokens = 0;
+            for (const tok of tokens) {
+                if (searchable.includes(tok))
+                    matchedTokens++;
+                // Prefix match on name segments (e.g., "frame_time" matches "frame_timeline")
+                else if (name.split('_').some(seg => seg.startsWith(tok)))
+                    matchedTokens += 0.5;
+            }
+            return matchedTokens >= tokens.length * 0.5 ? matchedTokens : 0;
+        }
+        const scored = schema.templates
+            .map(t => ({ entry: t, score: scoreEntry(t) }))
+            .filter(s => s.score > 0)
+            .sort((a, b) => b.score - a.score);
+        const merged = new Map();
+        for (const result of docResults) {
+            const key = `${result.entry.module}\n${result.entry.name}\n${result.entry.type}`;
+            merged.set(key, {
+                score: result.score + 1000,
+                source: 'stdlib_docs',
+                entry: compactSqlDocEntry(result.entry),
+            });
+        }
+        for (const legacy of scored) {
+            const module = legacy.entry.module || '';
+            const key = `${module}\n${legacy.entry.name}\n${legacy.entry.type}`;
+            if (merged.has(key))
+                continue;
+            merged.set(key, {
+                score: legacy.score,
+                source: 'legacy_index',
+                entry: compactLegacySqlSchemaEntry(legacy.entry),
+            });
+        }
+        const entries = Array.from(merged.values())
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 30)
+            .map(item => ({ ...item.entry, source: item.source }));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        totalMatches: entries.length,
+                        sources: {
+                            stdlibDocs: docResults.length,
+                            legacyIndex: scored.length,
+                        },
+                        entries,
+                    }),
+                }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // Conditional tool: write_analysis_note (only available when analysisNotes array is provided)
+    const MAX_NOTES = 20;
+    const writeAnalysisNote = analysisNotes ? (0, claude_agent_sdk_1.tool)('write_analysis_note', 'Persist a structured analysis note that survives context compression. ' +
+        'Use this for important cross-domain observations, hypotheses, or findings that you want to reference later. ' +
+        'Do NOT overuse — only record observations that would be lost if context is compressed.', {
+        section: zod_1.z.enum(['hypothesis', 'finding', 'observation', 'next_step']).describe('Note category: hypothesis (untested theory), finding (confirmed result), observation (data point), next_step (planned action)'),
+        content: zod_1.z.string().describe('The note content — be specific, include data references'),
+        priority: zod_1.z.enum(['high', 'medium', 'low']).optional().describe('Priority for retention when notes exceed limit. Default: medium'),
+    }, async ({ section, content, priority }) => {
+        const note = { section, content, priority: priority || 'medium', timestamp: Date.now() };
+        analysisNotes.push(note);
+        // Evict notes when over limit.
+        // Priority order: next_step (ephemeral) → low (oldest first) → medium (oldest first) → oldest high
+        if (analysisNotes.length > MAX_NOTES) {
+            const priorityRank = { low: 0, medium: 1, high: 2 };
+            // Find the best candidate to evict: lowest priority, then oldest timestamp
+            let evictIdx = -1;
+            let evictRank = Infinity;
+            let evictTs = Infinity;
+            for (let i = 0; i < analysisNotes.length; i++) {
+                const n = analysisNotes[i];
+                // Always prefer evicting next_step (ephemeral planning notes)
+                if (n.section === 'next_step') {
+                    evictIdx = i;
+                    break;
+                }
+                const rank = priorityRank[n.priority] ?? 1;
+                if (rank < evictRank || (rank === evictRank && n.timestamp < evictTs)) {
+                    evictRank = rank;
+                    evictTs = n.timestamp;
+                    evictIdx = i;
+                }
+            }
+            if (evictIdx >= 0)
+                analysisNotes.splice(evictIdx, 1);
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ success: true, totalNotes: analysisNotes.length, section, priority: priority || 'medium' }),
+                }],
+        };
+    }) : null;
+    // Conditional tool: fetch_artifact (only available when artifactStore is provided)
+    const fetchArtifact = artifactStore ? (0, claude_agent_sdk_1.tool)('fetch_artifact', 'Retrieve detailed data for a previously stored artifact from invoke_skill results. ' +
+        'Supports pagination for large datasets — use offset/limit to page through rows without token overflow. ' +
+        'Response includes totalRows and hasMore to guide pagination. ALL data is accessible; nothing is hidden.\n\n' +
+        'Use when: you need detailed data from a previous invoke_skill result (artifacts are referenced by ID in skill responses).\n' +
+        'Don\'t use when: you need new data (use invoke_skill or execute_sql instead).\n' +
+        'Always set purpose to one short sentence explaining why this artifact is needed for the current plan phase.\n\n' +
+        'Examples:\n' +
+        '1. Get summary of skill result: artifactId="art-1", detail="summary"\n' +
+        '2. Page through jank frames: artifactId="art-2", detail="rows", offset=0, limit=50\n' +
+        '3. Get next page: artifactId="art-2", detail="rows", offset=50, limit=50', {
+        artifactId: zod_1.z.string().describe('Artifact ID (e.g. "art-1") from a previous invoke_skill response'),
+        detail: zod_1.z.enum(['summary', 'rows', 'full']).optional().describe('Detail level: summary (default, compact stats), rows (paginated data rows), full (complete original structure — use with caution on large artifacts)'),
+        offset: zod_1.z.coerce.number().int().min(0).optional().describe('Row offset for pagination (detail="rows" only). Default: 0. Use with limit to page through large datasets.'),
+        limit: zod_1.z.coerce.number().int().min(1).max(200).optional().describe('Maximum rows to return (detail="rows" only). Default: 50. Increase up to 200 if you need more rows per page.'),
+        purpose: zod_1.z.string().optional().describe('One short sentence explaining why this artifact is needed for the current plan phase. Used in the user-visible timeline.'),
+    }, async ({ artifactId, detail, offset, limit, purpose }) => {
+        const effectiveDetail = detail || 'summary';
+        const normalizedOffset = coerceOptionalInteger(offset, 'offset', { min: 0 });
+        const normalizedLimit = coerceOptionalInteger(limit, 'limit', { min: 1, max: 200 });
+        const paginationErrors = [normalizedOffset.error, normalizedLimit.error].filter(Boolean);
+        const producerReason = purpose || (0, outputLanguage_1.localize)(outputLanguage, '读取前序证据表的明细数据，用于当前阶段判断。', 'Read detailed rows from a previous evidence artifact for the current phase.');
+        if (paginationErrors.length > 0) {
+            const producer = createEvidenceProducerContext('fetch_artifact', { artifactId, detail: effectiveDetail, offset, limit, purpose }, producerReason);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            success: false,
+                            error: `Invalid pagination arguments: ${paginationErrors.join('; ')}`,
+                        }) }],
+                isError: true,
+            };
+        }
+        const result = artifactStore.fetch(artifactId, effectiveDetail, normalizedOffset.value, normalizedLimit.value);
+        const originPhase = result?.planPhaseId
+            ? {
+                phaseId: result.planPhaseId,
+                phaseTitle: result.planPhaseTitle,
+                phaseGoal: result.planPhaseGoal,
+                attribution: 'inferred',
+            }
+            : undefined;
+        const producer = createEvidenceProducerContext('fetch_artifact', {
+            artifactId,
+            detail: effectiveDetail,
+            offset,
+            limit,
+            purpose,
+            artifactPlanPhaseId: result?.planPhaseId,
+            artifactPlanPhaseTitle: result?.planPhaseTitle,
+            artifactTitle: result?.title,
+            artifactStepId: result?.stepId,
+        }, producerReason, undefined, originPhase);
+        if (!result) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            success: false,
+                            error: `Artifact ${artifactId} not found — it may have been evicted (LRU cap: 50) or lost after a backend restart. Use invoke_skill to re-execute the skill if you need this data again.`,
+                            sourceToolCallId: producer.sourceToolCallId,
+                            paramsHash: producer.paramsHash,
+                            planPhaseId: producer.planPhaseId,
+                        }) }],
+                isError: true,
+            };
+        }
+        // Phase 3-4 of v2.1 — high-risk path recitation. `full` and `rows` detail
+        // levels return large payloads that push the agent's working memory; in
+        // those cases append a one-line plan reminder so the agent doesn't drift
+        // away from the active phase's constraints. Summary mode skips the
+        // reminder (compact responses already keep the agent on-track).
+        const reminder = (effectiveDetail === 'full' || effectiveDetail === 'rows')
+            ? (0, activePhaseReminder_1.buildActivePhaseReminder)(analysisPlanRef?.current, options.sceneType)
+            : '';
+        const payload = JSON.stringify({
+            success: true,
+            detail: effectiveDetail,
+            ...result,
+            sourceToolCallId: producer.sourceToolCallId,
+            paramsHash: producer.paramsHash,
+            planPhaseId: producer.planPhaseId,
+            planPhaseTitle: producer.planPhaseTitle,
+            planPhaseGoal: producer.planPhaseGoal,
+            planPhaseAttribution: producer.planPhaseAttribution,
+            sourceArtifactId: artifactId,
+            ...(purpose ? { purpose } : {}),
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: reminder ? payload + reminder : payload,
+                }],
+        };
+    }, { annotations: { readOnlyHint: true } }) : null;
+    // list_stdlib_modules: Expose Perfetto stdlib module inventory to the agent.
+    // Enables Claude to discover available stdlib modules by namespace (e.g., "android.frames", "sched").
+    const listStdlibModules = (0, claude_agent_sdk_1.tool)('list_stdlib_modules', 'List available Perfetto SQL stdlib modules by namespace. Use this to discover what pre-built tables, views, and functions ' +
+        'are available before writing custom SQL. Modules can be loaded via INCLUDE PERFETTO MODULE <name> in SQL queries. ' +
+        'Core modules (android.frames.timeline, android.startup.startups, android.binder) are pre-loaded; ' +
+        'others load on-demand via skill prerequisites or INCLUDE PERFETTO MODULE in your SQL.', {
+        namespace: zod_1.z.string().optional().describe('Filter by namespace prefix (e.g., "android", "android.frames", "sched", "chrome", "wattson"). Omit to list all.'),
+    }, async ({ namespace }) => {
+        const allModules = (0, perfettoStdlibScanner_1.getPerfettoStdlibModules)();
+        const docsModules = (0, perfettoSqlDocs_1.listPerfettoSqlModuleDocs)(namespace);
+        // Enforce dot-boundary matching to avoid "android" matching a hypothetical "androidos.*"
+        const filtered = namespace
+            ? allModules.filter(m => m === namespace || m.startsWith(namespace + '.'))
+            : allModules;
+        // Group by top-level namespace
+        const grouped = {};
+        for (const mod of filtered) {
+            const ns = mod.split('.')[0];
+            if (!grouped[ns])
+                grouped[ns] = [];
+            grouped[ns].push(mod);
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        totalModules: filtered.length,
+                        namespaces: Object.keys(grouped).sort(),
+                        // When filtering by namespace, return full module list.
+                        // When unfiltered, return only counts per namespace to save context tokens (~1500 tokens).
+                        modules: namespace
+                            ? filtered.sort()
+                            : Object.fromEntries(Object.entries(grouped).map(([ns, mods]) => [ns, mods.length])),
+                        moduleDocs: namespace
+                            ? docsModules.slice(0, 50).map(mod => ({
+                                module: mod.module,
+                                description: mod.moduleDoc,
+                                tags: mod.tags,
+                                includes: mod.includes,
+                                transitiveIncludes: mod.transitiveIncludes,
+                                symbols: mod.symbols.slice(0, 30),
+                                missingIncludes: mod.missingIncludes,
+                                errors: mod.errors,
+                                sourcePath: mod.sourcePath,
+                            }))
+                            : undefined,
+                        hint: namespace
+                            ? 'Use lookup_sql_schema to find specific tables/views/functions within a module.'
+                            : 'Call again with a namespace (e.g., "android.frames") to see full module list. ' +
+                                'Critical modules (android.frames.*, android.binder*, android.startup.*, sched.*) are pre-loaded.',
+                    }),
+                }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // lookup_knowledge: Load background knowledge on performance analysis topics on demand.
+    // The agent calls this when it needs to explain a root cause mechanism to the user.
+    // Topics are auto-discovered from knowledge-*.template.md files in the strategies directory.
+    const knowledgeTopics = (() => {
+        const strategiesDir = path.resolve(__dirname, '../../../strategies');
+        try {
+            return fs.readdirSync(strategiesDir)
+                .filter(f => f.startsWith('knowledge-') && f.endsWith('.template.md'))
+                .map(f => f.replace('knowledge-', '').replace('.template.md', ''))
+                .sort();
+        }
+        catch {
+            return ['rendering-pipeline', 'binder-ipc', 'gc-dynamics', 'cpu-scheduler', 'thermal-throttling', 'lock-contention'];
+        }
+    })();
+    const lookupKnowledge = (0, claude_agent_sdk_1.tool)('lookup_knowledge', 'Load background knowledge about a performance analysis topic. Use this when you discover a root cause ' +
+        'and want to explain the underlying mechanism to the user. Returns concise explanations of how the ' +
+        'system works, common trace signatures, and typical solutions. ' +
+        `Available topics: ${knowledgeTopics.join(', ')}.`, {
+        topic: zod_1.z.string().describe(`Knowledge topic: ${knowledgeTopics.map(t => `"${t}"`).join(' | ')}`),
+    }, async ({ topic }) => {
+        const content = (0, strategyLoader_1.loadPromptTemplate)('knowledge-' + topic);
+        if (!content) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Unknown topic "${topic}". Available: ${knowledgeTopics.join(', ')}`,
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: 'text', text: content }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // lookup_blog_knowledge (Plan 55): retrieve indexed chunks from
+    // androidperformance.com (and, once Plan 44 lands, world memory).
+    // Read-only — calls ragStore.search() which never writes. The index
+    // is populated by the M2 admin route + ingester; until then the
+    // search returns `unsupportedReason='index empty'` so the agent
+    // never invents content.
+    const lookupBlogKnowledge = (0, claude_agent_sdk_1.tool)('lookup_blog_knowledge', 'Retrieve indexed knowledge chunks from androidperformance.com to ground analysis claims in published material. ' +
+        'Returns ranked snippets matching the query plus provenance (chunkId, uri, title, author) so the agent can cite. ' +
+        'When the result carries an `unsupportedReason` (e.g. "index empty", "all chunks blocked by unsupportedReason"), ' +
+        'the agent must say the source is unavailable and must NOT summarize, paraphrase, or invent content from this source.', {
+        query: zod_1.z.string().describe('Search query — natural language is fine; tokens are lowercased and matched against snippet + title.'),
+        top_k: zod_1.z.number().int().min(1).max(20).optional().describe('Maximum hits returned (1-20, default 5).'),
+    }, async ({ query, top_k }) => {
+        const store = getRagStore();
+        const result = store.search(query, {
+            topK: top_k ?? 5,
+            kinds: ['androidperformance.com'],
+            scope: knowledgeScope,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // lookup_baseline (Plan 50): fetch a stored App/Device/Build/CUJ
+    // baseline by id or by composite key. Read-only — no store mutation.
+    // The agent uses this to pull the canonical "what this app/device
+    // historically does" record before making regression claims.
+    const lookupBaseline = (0, claude_agent_sdk_1.tool)('lookup_baseline', 'Fetch a stored App/Device/Build/CUJ baseline. ' +
+        'Pass either `baseline_id` (canonical "appId/deviceId/buildId/cuj") OR all four key components. ' +
+        'Returns the BaselineRecord with metrics, status, redactionState, and curatorNote. ' +
+        'When the baseline does not exist, the result carries `success: false` and the agent must NOT fabricate baseline values.', {
+        baseline_id: zod_1.z.string().optional().describe('Canonical baselineId, e.g. "com.example.feed/pixel-9-android-15/main-abc/scroll_feed".'),
+        app_id: zod_1.z.string().optional().describe('Component appId; required when baseline_id is omitted.'),
+        device_id: zod_1.z.string().optional().describe('Component deviceId; required when baseline_id is omitted.'),
+        build_id: zod_1.z.string().optional().describe('Component buildId; required when baseline_id is omitted.'),
+        cuj: zod_1.z.string().optional().describe('Component CUJ id; required when baseline_id is omitted.'),
+    }, async ({ baseline_id, app_id, device_id, build_id, cuj }) => {
+        const store = getBaselineStore();
+        let id = baseline_id;
+        if (!id) {
+            if (app_id && device_id && build_id && cuj) {
+                id = (0, baselineStore_1.deriveBaselineId)({ appId: app_id, deviceId: device_id, buildId: build_id, cuj });
+            }
+            else {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: 'Provide either `baseline_id` or all four key components (app_id, device_id, build_id, cuj).',
+                            }),
+                        }],
+                    isError: true,
+                };
+            }
+        }
+        const baseline = store.getBaseline(id, knowledgeScope);
+        if (!baseline) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: `Baseline '${id}' not found` }),
+                    }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ success: true, baseline }) }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // compare_baselines (Plan 50): diff two stored baselines and
+    // optionally evaluate a CI-style regression gate. Read-only —
+    // computes from the stored baselines without mutating either.
+    // Trace-vs-baseline (compare_to_baseline) is deferred until the
+    // trace metric extraction pipeline is built.
+    const compareBaselines = (0, claude_agent_sdk_1.tool)('compare_baselines', 'Diff two stored baselines and (optionally) evaluate a regression gate. ' +
+        'Returns a BaselineDiffArtifact with per-metric deltas plus an optional RegressionGateResult when `rules` are supplied. ' +
+        'Per-metric `severity` is one of none / info / warning / regression / unsupported; consult `unsupportedReason` whenever severity is "unsupported" — the agent must NOT treat unsupported metrics as confirming or refuting a regression claim.', {
+        base_baseline_id: zod_1.z.string().describe('Canonical baselineId for the historical/reference side.'),
+        candidate_baseline_id: zod_1.z.string().describe('Canonical baselineId for the candidate/new side.'),
+        rules: zod_1.z.array(zod_1.z.object({
+            metric_id: zod_1.z.string().describe('Metric id to gate on.'),
+            threshold: zod_1.z.number().describe('Maximum allowed absolute fractional delta. 0.10 == 10%.'),
+            expect_increase: zod_1.z.boolean().optional().describe('When false, gate fails on improvements (must-decrease metrics). Defaults to true.'),
+        })).optional().describe('Optional gate rules. When supplied a RegressionGateResult is returned alongside the diff.'),
+        gate_id: zod_1.z.string().optional().describe('Stable id for the gate result. Required when `rules` is supplied; otherwise ignored.'),
+    }, async ({ base_baseline_id, candidate_baseline_id, rules, gate_id }) => {
+        const store = getBaselineStore();
+        const base = store.getBaseline(base_baseline_id, knowledgeScope);
+        const candidate = store.getBaseline(candidate_baseline_id, knowledgeScope);
+        if (!base) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: `Base baseline '${base_baseline_id}' not found` }),
+                    }],
+            };
+        }
+        if (!candidate) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: `Candidate baseline '${candidate_baseline_id}' not found` }),
+                    }],
+            };
+        }
+        const diff = (0, baselineDiffer_1.computeBaselineDiff)(base, candidate);
+        let gate = undefined;
+        if (rules && rules.length > 0) {
+            if (!gate_id) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({ success: false, error: '`gate_id` is required when `rules` is supplied.' }),
+                        }],
+                    isError: true,
+                };
+            }
+            const mappedRules = rules.map(r => ({
+                metricId: r.metric_id,
+                threshold: r.threshold,
+                ...(r.expect_increase !== undefined ? { expectIncrease: r.expect_increase } : {}),
+            }));
+            gate = (0, baselineDiffer_1.evaluateRegressionGate)(base_baseline_id, diff, mappedRules, { gateId: gate_id });
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ success: true, diff, ...(gate ? { gate } : {}) }),
+                }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // lookup_aosp_source (Plan 55 M1): retrieve indexed AOSP source
+    // chunks. Public read-only. License gate at ingestion guarantees
+    // every retrieved chunk carries an explicit license; the agent
+    // contract still applies — when the result is `unsupportedReason
+    // === 'license_blocked'` (or empty index), do NOT summarize, do
+    // NOT cite as evidence, say the source is unavailable.
+    const lookupAospSource = (0, claude_agent_sdk_1.tool)('lookup_aosp_source', 'Retrieve indexed AOSP source chunks (frameworks/base, system/, etc.) to ground analysis claims in the actual implementation. ' +
+        'Returns ranked snippets with license + commit-anchored chunkId. ' +
+        'When the result carries `unsupportedReason` (license_blocked, index empty), the agent must say the source is unavailable and must NOT summarize, paraphrase, or invent content.', {
+        query: zod_1.z.string().describe('Search query — typically a function or class name, or a behavior description.'),
+        top_k: zod_1.z.number().int().min(1).max(20).optional().describe('Maximum hits returned (1-20, default 5).'),
+    }, async ({ query, top_k }) => {
+        const store = getRagStore();
+        const result = store.search(query, {
+            topK: top_k ?? 5,
+            kinds: ['aosp'],
+            scope: knowledgeScope,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // lookup_oem_sdk (Plan 55 M2): retrieve indexed OEM SDK chunks
+    // (MTK / Qualcomm / Samsung tuning docs etc.). Public read-only.
+    // Same agent contract as lookup_aosp_source: blocked / empty
+    // results must NOT be paraphrased or fabricated.
+    const lookupOemSdk = (0, claude_agent_sdk_1.tool)('lookup_oem_sdk', 'Retrieve indexed OEM SDK / tuning documentation chunks. Optionally restrict by vendor via the URI prefix (`oem://<vendor>/...`). ' +
+        'Read-only over the RagStore. When the result carries `unsupportedReason` (license_blocked, index empty), the agent must say the source is unavailable and must NOT summarize or invent.', {
+        query: zod_1.z.string().describe('Search query — typically a tuning concept or vendor-specific knob.'),
+        top_k: zod_1.z.number().int().min(1).max(20).optional().describe('Maximum hits returned (1-20, default 5).'),
+    }, async ({ query, top_k }) => {
+        const store = getRagStore();
+        const result = store.search(query, {
+            topK: top_k ?? 5,
+            kinds: ['oem_sdk'],
+            scope: knowledgeScope,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // recall_project_memory (Plan 44): pure-read recall over project +
+    // world memory entries. Strict invariant: handler MUST NOT cause any
+    // disk writes; ProjectMemory.recallProjectMemory() is enforced via
+    // the "1000 calls / mtime unchanged" unit test in projectMemory.test.ts.
+    // Use this when the agent wants to ground claims in past analysis
+    // insights for the same project (or in world-scope insights consolidated
+    // by reviewer approval). The session-scope `recall_patterns` tool is a
+    // separate path that runs against the existing analysisPatternMemory store.
+    const recallProjectMemory = (0, claude_agent_sdk_1.tool)('recall_project_memory', 'Recall project- or world-scope memory entries by tag overlap with the query. Read-only — never writes. ' +
+        'Returns up to top_k hits ranked by tag-overlap score; entries with `unsupportedReason` (evicted, retracted) are skipped. ' +
+        'Session-scope memory lives elsewhere (use `recall_patterns` for that path).', {
+        tags: zod_1.z.array(zod_1.z.string()).optional().describe('Tags to score against. Without tags, entries rank by their stored confidence.'),
+        project_key: zod_1.z.string().optional().describe('Restrict to entries created under this project key (e.g. "appId/deviceId").'),
+        scope: zod_1.z.enum(['project', 'world']).optional().describe('Restrict to a scope. Defaults to both project and world.'),
+        top_k: zod_1.z.number().int().min(1).max(20).optional().describe('Maximum hits returned (1-20, default 5).'),
+    }, async ({ tags, project_key, scope, top_k }) => {
+        const memory = getProjectMemory();
+        const hits = memory.recallProjectMemory({
+            tags,
+            projectKey: project_key,
+            scope,
+            topK: top_k ?? 5,
+        }, knowledgeScope);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ success: true, hits, count: hits.length }),
+                }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // recall_similar_case (Plan 54): pure-read recall over the case
+    // library. The agent uses this to ground claims in prior curated
+    // cases ("similar root cause to case-...") instead of repeating
+    // analysis. Read-only. Note: `cite_case_in_report` (the session-side
+    // writer counterpart) is intentionally deferred — it requires
+    // deeper integration with the report generation path and lands as
+    // its own commit later.
+    const recallSimilarCase = (0, claude_agent_sdk_1.tool)('recall_similar_case', 'Recall published or reviewed cases that share tags with the current trace, optionally restricted to the same App/Device/Build/CUJ key. ' +
+        'Read-only over the case library. Returns up to top_k cases ranked by tag-overlap score; published cases rank above reviewed when scores tie. ' +
+        'When the result is empty the agent must NOT fabricate prior cases — say "no matching prior case in the library" explicitly.', {
+        tags: zod_1.z.array(zod_1.z.string()).optional().describe('Tag tokens to score against. Without tags, results rank by published > reviewed > others.'),
+        app_id: zod_1.z.string().optional().describe('Restrict to cases whose key.appId matches.'),
+        device_id: zod_1.z.string().optional().describe('Restrict to cases whose key.deviceId matches.'),
+        cuj: zod_1.z.string().optional().describe('Restrict to cases whose key.cuj matches.'),
+        include_unpublished: zod_1.z.boolean().optional().describe('Include reviewed/draft cases (default false — only published surface to the agent).'),
+        top_k: zod_1.z.number().int().min(1).max(20).optional().describe('Maximum cases returned (1-20, default 5).'),
+    }, async ({ tags, app_id, device_id, cuj, include_unpublished, top_k }) => {
+        const library = getCaseLibrary();
+        const wantedTags = tags ? new Set(tags) : null;
+        const limit = top_k ?? 5;
+        // Pull either published-only or published+reviewed depending on the
+        // include_unpublished flag. Drafts and private cases never surface
+        // through this tool — those are operator-side concerns.
+        const allCases = include_unpublished
+            ? [
+                ...library.listCases({ status: 'published' }, knowledgeScope),
+                ...library.listCases({ status: 'reviewed' }, knowledgeScope),
+            ]
+            : library.listCases({ status: 'published' }, knowledgeScope);
+        const candidates = [];
+        for (const c of allCases) {
+            if (app_id && c.key?.appId !== app_id)
+                continue;
+            if (device_id && c.key?.deviceId !== device_id)
+                continue;
+            if (cuj && c.key?.cuj !== cuj)
+                continue;
+            let score = 0;
+            if (wantedTags) {
+                for (const t of c.tags)
+                    if (wantedTags.has(t))
+                        score += 1;
+                if (score === 0)
+                    continue;
+                score = score / Math.max(wantedTags.size, 1);
+            }
+            else {
+                // Without tags, prefer published over reviewed; both above 0.
+                score = c.status === 'published' ? 1 : 0.5;
+            }
+            candidates.push({ caseScore: score, case: c });
+        }
+        candidates.sort((a, b) => {
+            if (a.caseScore !== b.caseScore)
+                return b.caseScore - a.caseScore;
+            // Tie-break: published before reviewed before others.
+            const rank = (s) => s === 'published' ? 0 : s === 'reviewed' ? 1 : 2;
+            return rank(a.case.status) - rank(b.case.status);
+        });
+        const hits = candidates.slice(0, limit).map(c => ({
+            caseId: c.case.caseId,
+            score: c.caseScore,
+            title: c.case.title,
+            status: c.case.status,
+            tags: c.case.tags,
+            findings: c.case.findings,
+            traceArtifactId: c.case.traceArtifactId,
+            traceUnavailableReason: c.case.traceUnavailableReason,
+        }));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ success: true, hits, count: hits.length }),
+                }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // query_perfetto_source: Search the Perfetto stdlib for SQL patterns and usage examples.
+    // Enables Claude to self-learn by finding how official code uses tables/functions.
+    const queryPerfettoSource = (0, claude_agent_sdk_1.tool)('query_perfetto_source', 'Search the Perfetto SQL stdlib source code for usage patterns. Packaged builds fall back to the bundled SQL schema index when the source tree is unavailable. Use this when you encounter an unfamiliar table/function, get an SQL error, or need to find how the official codebase uses a specific table or column.', {
+        keyword: zod_1.z.string().describe('Search keyword (table name, function name, column name, or SQL pattern)'),
+        max_results: zod_1.z.number().optional().describe('Maximum number of matching files to return (default: 5)'),
+    }, async ({ keyword, max_results }) => {
+        const maxFiles = max_results ?? 5;
+        const stdlibDir = (0, perfettoStdlibScanner_1.getPerfettoStdlibPath)();
+        const docsMatches = (0, perfettoSqlDocs_1.searchPerfettoSqlDocs)(keyword, { limit: maxFiles });
+        const compactDocs = docsMatches.map(result => compactSqlDocEntry(result.entry));
+        if (!fs.existsSync(stdlibDir)) {
+            const lowerKeyword = keyword.toLowerCase();
+            const schema = loadSqlSchema();
+            const results = schema.templates
+                .filter(t => {
+                const searchable = `${t.name} ${t.category} ${t.description ?? ''}`.toLowerCase();
+                return searchable.includes(lowerKeyword);
+            })
+                .slice(0, maxFiles)
+                .map(t => ({
+                file: t.id,
+                matches: [
+                    [
+                        `name: ${t.name}`,
+                        `category: ${t.category}`,
+                        `type: ${t.type ?? 'unknown'}`,
+                        `description: ${t.description ?? ''}`,
+                    ].join('\n'),
+                ],
+            }));
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            keyword,
+                            source: 'bundled_schema_index',
+                            docs: compactDocs,
+                            matchedFiles: results.length,
+                            results: results.map(r => ({
+                                file: r.file,
+                                matchCount: r.matches.length,
+                                matches: r.matches,
+                            })),
+                            note: 'Perfetto stdlib source tree is unavailable in this runtime; returned bundled schema-index matches instead.',
+                        }),
+                    }],
+            };
+        }
+        try {
+            const results = [];
+            const lowerKeyword = keyword.toLowerCase();
+            // Recursively search .sql files (async to avoid blocking event loop)
+            const searchDir = async (dir) => {
+                if (results.length >= maxFiles)
+                    return;
+                const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (results.length >= maxFiles)
+                        return;
+                    const fullPath = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        await searchDir(fullPath);
+                    }
+                    else if (entry.name.endsWith('.sql')) {
+                        const content = await fs.promises.readFile(fullPath, 'utf-8');
+                        if (content.toLowerCase().includes(lowerKeyword)) {
+                            const relPath = path.relative(stdlibDir, fullPath);
+                            const lines = content.split('\n');
+                            const matchLines = [];
+                            for (let i = 0; i < lines.length; i++) {
+                                if (lines[i].toLowerCase().includes(lowerKeyword)) {
+                                    // Include 1 line of context before and after
+                                    const start = Math.max(0, i - 1);
+                                    const end = Math.min(lines.length - 1, i + 1);
+                                    const context = lines.slice(start, end + 1)
+                                        .map((l, j) => `${start + j + 1}: ${l}`)
+                                        .join('\n');
+                                    matchLines.push(context);
+                                    if (matchLines.length >= 8)
+                                        break; // Cap matches per file
+                                }
+                            }
+                            results.push({ file: relPath, matches: matchLines });
+                        }
+                    }
+                }
+            };
+            await searchDir(stdlibDir);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            keyword,
+                            source: 'stdlib_source',
+                            docs: compactDocs,
+                            matchedFiles: results.length,
+                            results: results.map(r => ({
+                                file: r.file,
+                                matchCount: r.matches.length,
+                                matches: r.matches,
+                            })),
+                        }),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: err.message }) }],
+                isError: true,
+            };
+        }
+    }, { annotations: { readOnlyHint: true } });
+    // P1-G11: Scene plan templates extracted to `./scenePlanTemplates` (Phase 0.2 of
+    // v2.1). The previous inline `'touch-tracking'` key (hyphen) silently disabled
+    // hard-gate for the touch_tracking scene because strategy frontmatter uses
+    // underscore-form `scene: touch_tracking`; coverage test now guards this.
+    // Planning tools: submit_plan + update_plan_phase (P0-1: Explicit planning capability)
+    // analysisPlanRef is declared above (P0-G10) and shared with planning tools
+    const submitPlan = analysisPlanRef ? (0, claude_agent_sdk_1.tool)('submit_plan', 'Submit your structured analysis plan BEFORE starting any analysis. ' +
+        'Define phases with goals and expected tools. The system tracks plan adherence and warns on deviation. ' +
+        'You MUST call this tool as your first action in every analysis.\n\n' +
+        'Use when: starting any new analysis — this is mandatory before execute_sql or invoke_skill.\n' +
+        'Don\'t use when: plan already submitted (use revise_plan to modify, update_plan_phase to track progress).\n\n' +
+        'Examples:\n' +
+        '1. Scrolling plan: phases=[{id:"p1", name:"概览采集", goal:"获取帧统计和卡顿分布", expectedTools:["invoke_skill"]}, ' +
+        '{id:"p2", name:"根因分析", goal:"逐帧诊断卡顿原因", expectedTools:["invoke_skill","execute_sql"]}, ' +
+        '{id:"p3", name:"深入验证", goal:"验证根因假设", expectedTools:["execute_sql","fetch_artifact"]}], ' +
+        'successCriteria="识别卡顿根因并提供量化证据"', {
+        phases: zod_1.z.array(zod_1.z.object({
+            id: zod_1.z.string().describe('Phase identifier (e.g. "p1", "p2")'),
+            name: zod_1.z.string().describe('Phase name (e.g. "Overview Collection")'),
+            goal: zod_1.z.string().describe('What this phase aims to achieve'),
+            expectedTools: zod_1.z.array(zod_1.z.string()).describe('Tool names this phase will use (e.g. ["invoke_skill", "execute_sql"])'),
+            expectedCalls: zod_1.z.array(zod_1.z.object({
+                tool: zod_1.z.string().describe('Short tool name without prefix (e.g. "invoke_skill")'),
+                skillId: zod_1.z.string().optional().describe('For invoke_skill, the required skillId'),
+            })).optional().describe('Optional structured matchers — preferred over expectedTools when set. Use to require a specific skillId, e.g. [{tool:"invoke_skill", skillId:"startup_slow_reasons"}].'),
+        })).min(1).describe('Ordered list of analysis phases (at least 1 phase required)'),
+        successCriteria: zod_1.z.string().describe('What constitutes a successful analysis (e.g. "Identify root cause of jank frames with evidence")'),
+        waivers: zod_1.z.array(zod_1.z.object({
+            aspectId: zod_1.z.string().describe('Mandatory aspect id to opt out of (matches a `missingAspectIds` entry from a prior reject).'),
+            reason: zod_1.z.string().describe(`Justification for why this aspect cannot be covered. MUST be at least ${scenePlanTemplates_1.MIN_WAIVER_REASON_CHARS} characters.`),
+        })).optional().describe('Optional opt-outs for scene-template aspects when the trace genuinely cannot support them.'),
+    }, async ({ phases, successCriteria, waivers }) => {
+        const phaseInputs = parseToolArrayInput(phases);
+        if (!phaseInputs) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, 'submit_plan 参数 phases 必须是数组或 JSON 数组字符串。', 'submit_plan argument phases must be an array or JSON array string.'),
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const waiverInputs = parseOptionalToolArrayInput(waivers);
+        if (!waiverInputs) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, 'submit_plan 参数 waivers 必须是数组或 JSON 数组字符串。', 'submit_plan argument waivers must be an array or JSON array string.'),
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const normalizedPhases = moveConclusionPhasesLast(phaseInputs.map(normalizePlanPhaseToolInput));
+        // P1-G11: Validate against the scene template, honouring agent waivers.
+        const validation = (0, scenePlanTemplates_1.validatePlanAgainstSceneTemplate)(normalizedPhases, options.sceneType, waiverInputs);
+        const { warnings: planWarnings, missingAspectIds } = validation;
+        // Track only waivers whose reason met the minimum threshold; the rest
+        // are reported back so the agent knows they didn't count.
+        const acceptedWaivers = waiverInputs.filter(w => typeof w.reason === 'string' && w.reason.trim().length >= scenePlanTemplates_1.MIN_WAIVER_REASON_CHARS);
+        const tooShortWaivers = waiverInputs.filter(w => !acceptedWaivers.some(a => a.aspectId === w.aspectId));
+        planSubmitAttempts++;
+        // Phase 2.3: 真硬拦截 — keep rejecting until plan covers all aspects
+        // or supplies a substantial waiver. After MAX_PLAN_ATTEMPTS the gate
+        // gives up and force-accepts, but missing aspects are persisted to
+        // `unresolvedAspects` so `verifyPlanAdherence` still flags the gap.
+        const MAX_PLAN_ATTEMPTS = 5;
+        if (planWarnings.length > 0 && planSubmitAttempts < MAX_PLAN_ATTEMPTS) {
+            console.log(`[MCP] Plan rejected (attempt ${planSubmitAttempts}/${MAX_PLAN_ATTEMPTS}): missing ${missingAspectIds.length} aspects for ${options.sceneType ?? 'unknown scene'}`);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, `计划缺少 ${options.sceneType ?? '当前'} 场景的必要分析阶段`, `The plan is missing mandatory analysis phases for the ${options.sceneType ?? 'current'} scene`),
+                            missingAspectIds,
+                            missingAspectSuggestions: planWarnings,
+                            attempt: planSubmitAttempts,
+                            maxAttempts: MAX_PLAN_ATTEMPTS,
+                            tooShortWaivers: tooShortWaivers.length > 0 ? tooShortWaivers : undefined,
+                            hint: (0, outputLanguage_1.localize)(outputLanguage, `修复 plan 添加缺失阶段并重新调用 submit_plan，或在 waivers 中给出 ≥${scenePlanTemplates_1.MIN_WAIVER_REASON_CHARS} 字符的理由说明为什么无法覆盖。`, `Add the missing phases and call submit_plan again, or provide a waiver reason of at least ${scenePlanTemplates_1.MIN_WAIVER_REASON_CHARS} characters explaining why it cannot be covered.`),
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const forcedAccept = planWarnings.length > 0; // hit the attempt cap
+        const plan = {
+            phases: normalizedPhases.map((p) => ({
+                ...p,
+                status: 'pending',
+            })),
+            successCriteria,
+            submittedAt: Date.now(),
+            toolCallLog: [],
+            ...(acceptedWaivers.length > 0 ? { waivers: acceptedWaivers } : {}),
+            ...(forcedAccept ? { unresolvedAspects: missingAspectIds } : {}),
+        };
+        analysisPlanRef.current = plan;
+        if (forcedAccept) {
+            console.warn(`[MCP] Plan force-accepted at attempt ${planSubmitAttempts} with ${missingAspectIds.length} unresolved aspects: ${missingAspectIds.join(', ')}`);
+        }
+        emitUpdate?.({
+            type: 'plan_submitted',
+            content: {
+                phases: plan.phases.map(p => ({ id: p.id, name: p.name, goal: p.goal, status: p.status })),
+                successCriteria,
+            },
+            timestamp: Date.now(),
+        });
+        const response = { success: true };
+        if (acceptedWaivers.length > 0) {
+            response.acceptedWaivers = acceptedWaivers.map(w => w.aspectId);
+        }
+        if (tooShortWaivers.length > 0) {
+            response.tooShortWaivers = tooShortWaivers;
+            response.waiverHint = (0, outputLanguage_1.localize)(outputLanguage, `已忽略 ${tooShortWaivers.length} 条理由不足 ${scenePlanTemplates_1.MIN_WAIVER_REASON_CHARS} 字符的 waiver。`, `Ignored ${tooShortWaivers.length} waiver(s) whose reason is shorter than ${scenePlanTemplates_1.MIN_WAIVER_REASON_CHARS} characters.`);
+        }
+        if (forcedAccept) {
+            response.unresolvedAspects = missingAspectIds;
+            response.warning = (0, outputLanguage_1.localize)(outputLanguage, `已强制接受 plan（达到第 ${MAX_PLAN_ATTEMPTS} 次尝试上限），但未覆盖的 aspect 会在最终 verifier 中报错。`, `Plan force-accepted after reaching the ${MAX_PLAN_ATTEMPTS}-attempt limit, but uncovered aspects will be reported by the final verifier.`);
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response),
+                }],
+        };
+    }) : null;
+    const updatePlanPhase = analysisPlanRef ? (0, claude_agent_sdk_1.tool)('update_plan_phase', 'Update the status of a plan phase. Call this when transitioning between phases or when skipping a phase. ' +
+        'This helps track analysis progress and enables plan adherence verification. ' +
+        'When completing a phase, you MUST provide a summary with key evidence collected (e.g. "发现 5 帧卡顿，主因是 RenderThread 阻塞，最长耗时 45ms"). ' +
+        'When skipping, explain why (e.g. "trace 中无启动数据，跳过启动分析").', {
+        phaseId: zod_1.z.string().describe('Phase ID to update (e.g. "p1")'),
+        status: zod_1.z.enum(['in_progress', 'completed', 'skipped', 'active']).describe('New phase status. "active" is accepted as an alias for "in_progress".'),
+        summary: zod_1.z.string().optional().describe('REQUIRED for completed/skipped: key evidence or reason. Must include specific data (numbers, names, findings).'),
+    }, async ({ phaseId, status, summary }) => {
+        const plan = analysisPlanRef.current;
+        if (!plan) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, '还没有提交 plan，请先调用 submit_plan。', 'No plan submitted yet. Call submit_plan first.'),
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const phase = plan.phases.find(p => p.id === phaseId);
+        if (!phase) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, `plan 中没有找到阶段 "${phaseId}"`, `Phase "${phaseId}" not found in plan`),
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const trimmedSummary = summary?.trim();
+        const normalizedStatus = status === 'active' ? 'in_progress' : status;
+        if ((normalizedStatus === 'completed' || normalizedStatus === 'skipped') &&
+            (!trimmedSummary || trimmedSummary.length < exports.MIN_PHASE_SUMMARY_CHARS)) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, `阶段 ${phaseId} 的 summary 太短。完成/跳过阶段时必须给出具体证据、数据或原因，至少 ${exports.MIN_PHASE_SUMMARY_CHARS} 个字符。`, `Phase ${phaseId} summary is too brief. Completed/skipped phases require concrete evidence, data, or reason with at least ${exports.MIN_PHASE_SUMMARY_CHARS} characters.`),
+                            action_required: 'retry_update_plan_phase_with_evidence',
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        if (normalizedStatus === 'skipped' && isConclusionLikePlanPhase(phase)) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, `阶段 ${phaseId} 是最终结论阶段，不能标记为 skipped。请先补齐必要证据，然后将该阶段标记为 completed，并输出最终结论。`, `Phase ${phaseId} is the final conclusion phase and cannot be skipped. Collect the required evidence first, then mark it completed and produce the final conclusion.`),
+                            action_required: 'complete_final_conclusion_phase',
+                            currentPhaseId: phase.id,
+                            currentPhaseName: phase.name,
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const semanticMismatch = findPhaseSemanticMismatch(plan, phase, trimmedSummary);
+        if (semanticMismatch) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, `阶段 ${phaseId} 是「${phase.name}」，但 summary 更像「${PHASE_SEMANTIC_LABELS[semanticMismatch.summaryKind]}」。请改用阶段 ${semanticMismatch.suggestedPhase.id}（${semanticMismatch.suggestedPhase.name}）或重写 summary。`, `Phase ${phaseId} is "${phase.name}", but the summary looks like "${PHASE_SEMANTIC_LABELS[semanticMismatch.summaryKind]}". Use phase ${semanticMismatch.suggestedPhase.id} (${semanticMismatch.suggestedPhase.name}) or rewrite the summary.`),
+                            action_required: 'retry_update_plan_phase_with_correct_phase',
+                            currentPhaseId: phase.id,
+                            currentPhaseName: phase.name,
+                            suggestedPhaseId: semanticMismatch.suggestedPhase.id,
+                            suggestedPhaseName: semanticMismatch.suggestedPhase.name,
+                            detectedSummaryKind: semanticMismatch.summaryKind,
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        if (normalizedStatus === 'in_progress') {
+            closeSupersededInProgressPhases(plan, phase);
+            phase.completedAt = undefined;
+            phase.summary = undefined;
+        }
+        phase.status = normalizedStatus;
+        if (normalizedStatus === 'completed' || normalizedStatus === 'skipped') {
+            phase.completedAt = Date.now();
+            phase.summary = trimmedSummary;
+        }
+        emitUpdate?.({
+            type: 'plan_phase_updated',
+            content: { phaseId, status: normalizedStatus, summary: trimmedSummary || '', phaseName: phase.name },
+            timestamp: Date.now(),
+        });
+        // Report overall plan progress
+        const allPhasesClosed = plan.phases.every(p => p.status === 'completed' || p.status === 'skipped');
+        const nextPhase = plan.phases.find(p => p.status === 'pending');
+        // Compact return: only include feedback when needed (normal path = minimal ACK)
+        const response = { success: true };
+        if (allPhasesClosed)
+            response.allPhasesComplete = true;
+        // Restatement injection: leverage tool response's high-attention position
+        // to re-state next-phase constraints from strategy frontmatter phase_hints.
+        // Match logic lives in `phaseHintMatcher` so it can be unit tested.
+        const shouldReportNextPhase = normalizedStatus === 'completed' || normalizedStatus === 'skipped';
+        if (shouldReportNextPhase && nextPhase && options.sceneType) {
+            const hints = (0, strategyLoader_1.getPhaseHints)(options.sceneType);
+            const matchedHint = (0, phaseHintMatcher_1.matchPhaseHintForNextPhase)({
+                hints,
+                nextPhase: { name: nextPhase.name, goal: nextPhase.goal },
+                finishedPhases: plan.phases.map(p => ({
+                    name: p.name,
+                    goal: p.goal,
+                    summary: p.summary,
+                    status: p.status,
+                })),
+            });
+            if (matchedHint) {
+                response.next_phase_reminder = {
+                    phaseId: nextPhase.id,
+                    name: nextPhase.name,
+                    constraints: matchedHint.constraints,
+                    criticalTools: matchedHint.criticalTools,
+                };
+                console.log(`[MCP] Phase hint injected: ${matchedHint.id} for ${options.sceneType}`);
+            }
+            else if (hints.length > 0) {
+                console.log(`[MCP] Phase hint not found for: "${nextPhase.name}" in ${options.sceneType}`);
+            }
+            // Always include basic next phase info for non-hint scenarios
+            if (!response.next_phase_reminder) {
+                response.next = {
+                    phaseId: nextPhase.id,
+                    name: nextPhase.name,
+                    expectedTools: nextPhase.expectedTools,
+                };
+            }
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response),
+                }],
+        };
+    }) : null;
+    // P1-3: Dynamic replan — allows Claude to revise the plan mid-analysis when new information emerges
+    const revisePlan = analysisPlanRef ? (0, claude_agent_sdk_1.tool)('revise_plan', 'Revise your analysis plan mid-execution when new information changes priorities. ' +
+        'Use this when initial data reveals unexpected conditions (e.g., discovered Flutter architecture but planned for Standard, ' +
+        'or found ANR signals in a scrolling query). Preserves completed phases and audit trail.', {
+        reason: zod_1.z.string().describe('Why the plan needs revision (what new information triggered this)'),
+        updatedPhases: zod_1.z.array(zod_1.z.object({
+            id: zod_1.z.string().describe('Phase identifier (keep existing IDs for unchanged phases, use new IDs for added phases)'),
+            name: zod_1.z.string().describe('Phase name'),
+            goal: zod_1.z.string().describe('What this phase aims to achieve'),
+            expectedTools: zod_1.z.array(zod_1.z.string()).describe('Tool names this phase will use'),
+            expectedCalls: zod_1.z.array(zod_1.z.object({
+                tool: zod_1.z.string(),
+                skillId: zod_1.z.string().optional(),
+            })).optional().describe('Optional structured matchers — see submit_plan for semantics.'),
+            status: zod_1.z.enum(['pending', 'in_progress', 'completed', 'skipped']).optional()
+                .describe('Phase status. Omit for new/pending phases. Completed/skipped phases from original plan are preserved.'),
+        })).describe('The revised phase list. Must include all completed/in-progress phases from original plan.'),
+        updatedSuccessCriteria: zod_1.z.string().optional().describe('Updated success criteria (only if the goal changed)'),
+    }, async ({ reason, updatedPhases, updatedSuccessCriteria }) => {
+        const updatedPhaseInputs = parseToolArrayInput(updatedPhases);
+        if (!updatedPhaseInputs) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, 'revise_plan 参数 updatedPhases 必须是数组或 JSON 数组字符串。', 'revise_plan argument updatedPhases must be an array or JSON array string.'),
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const normalizedUpdatedPhases = moveConclusionPhasesLast(updatedPhaseInputs.map((p) => ({
+            ...normalizePlanPhaseToolInput(p),
+            status: p.status,
+        })));
+        // Reset submit attempts so a revised plan can trigger hard-gate validation again
+        planSubmitAttempts = 0;
+        const plan = analysisPlanRef.current;
+        if (!plan) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, '还没有提交 plan，请先调用 submit_plan。', 'No plan submitted yet. Call submit_plan first.'),
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        // Validate: completed phases from original plan must be preserved
+        const originalCompleted = plan.phases.filter(p => p.status === 'completed' || p.status === 'skipped');
+        const preservedIds = new Set(normalizedUpdatedPhases.map(p => p.id));
+        const missingCompleted = originalCompleted.filter(p => !preservedIds.has(p.id));
+        if (missingCompleted.length > 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: (0, outputLanguage_1.localize)(outputLanguage, `已完成阶段必须保留: ${missingCompleted.map(p => p.id).join(', ')}。请把它们放入 updatedPhases。`, `Completed phases must be preserved: ${missingCompleted.map(p => p.id).join(', ')}. Include them in updatedPhases.`),
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        // Save revision history for audit trail
+        const revision = {
+            revisedAt: Date.now(),
+            reason,
+            previousPhases: plan.phases.map(p => ({ ...p })),
+        };
+        if (!plan.revisionHistory)
+            plan.revisionHistory = [];
+        plan.revisionHistory.push(revision);
+        // Apply revision: merge completed phase data (summary, completedAt) with updated structure
+        plan.phases = normalizedUpdatedPhases.map((up) => {
+            const original = plan.phases.find(p => p.id === up.id);
+            if (original && (original.status === 'completed' || original.status === 'skipped')) {
+                // Preserve completed phase data
+                return { ...original };
+            }
+            return {
+                id: up.id,
+                name: up.name,
+                goal: up.goal,
+                expectedTools: up.expectedTools,
+                expectedCalls: up.expectedCalls,
+                status: (up.status || 'pending'),
+            };
+        });
+        if (updatedSuccessCriteria) {
+            plan.successCriteria = updatedSuccessCriteria;
+        }
+        emitUpdate?.({
+            type: 'plan_revised',
+            content: {
+                reason,
+                phases: plan.phases.map(p => ({ id: p.id, name: p.name, goal: p.goal, status: p.status })),
+                revisionCount: plan.revisionHistory.length,
+            },
+            timestamp: Date.now(),
+        });
+        const pending = plan.phases.filter(p => p.status === 'pending');
+        // P1-G11: Run scene-template validation on the revised plan too — otherwise
+        // an agent could submit a compliant plan and then revise mandatory phases
+        // away to bypass the hard-gate. Phase 2.3 will upgrade these warnings to
+        // a real reject when sceneType is known.
+        const { warnings: revisedPlanWarnings } = (0, scenePlanTemplates_1.validatePlanAgainstSceneTemplate)(plan.phases, options.sceneType);
+        const reviseResponse = {
+            success: true,
+            message: (0, outputLanguage_1.localize)(outputLanguage, `Plan 已修订（第 ${plan.revisionHistory.length} 次）: ${reason}`, `Plan revised (revision #${plan.revisionHistory.length}): ${reason}`),
+            totalPhases: plan.phases.length,
+            pendingPhases: pending.length,
+            nextPhase: pending[0]?.id,
+        };
+        if (revisedPlanWarnings.length > 0) {
+            reviseResponse.sceneWarnings = revisedPlanWarnings;
+            console.log(`[MCP] Revised plan has ${revisedPlanWarnings.length} unmet aspects for ${options.sceneType ?? 'unknown scene'}`);
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(reviseResponse),
+                }],
+        };
+    }) : null;
+    // P0-G4: Hypothesis-verify cycle tools
+    const hypothesesRef = options.hypotheses;
+    let hypothesisCounter = 0;
+    const submitHypothesis = hypothesesRef ? (0, claude_agent_sdk_1.tool)('submit_hypothesis', 'Record a formal hypothesis that needs verification through data. ' +
+        'Use this when you form a testable theory about the root cause of a performance issue. ' +
+        'Every hypothesis MUST be resolved (confirmed/rejected with evidence) before concluding.', {
+        id: zod_1.z.string().optional().describe('Optional caller-provided hypothesis ID (e.g., "h1"). If omitted, the system assigns one.'),
+        statement: zod_1.z.string().optional().describe('The hypothesis statement (e.g., "RenderThread is blocked by Binder transactions causing jank frames"). Alias: title.'),
+        title: zod_1.z.string().optional().describe('Alias for statement, accepted for Claude SDK argument compatibility.'),
+        basis: zod_1.z.string().optional().describe('What observation prompted this hypothesis (e.g., "Observed 3 frames with RenderThread in sleeping state"). Alias: reasoning.'),
+        reasoning: zod_1.z.string().optional().describe('Alias for basis, accepted for Claude SDK argument compatibility.'),
+    }, async ({ id, statement, title, basis, reasoning }) => {
+        const effectiveStatement = (statement ?? title)?.trim();
+        const effectiveBasis = (basis ?? reasoning)?.trim();
+        if (!effectiveStatement) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: 'submit_hypothesis requires statement (or title)',
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const requestedId = id?.trim();
+        const existing = requestedId ? hypothesesRef.find(h => h.id === requestedId) : undefined;
+        if (existing) {
+            if (existing.status === 'formed') {
+                existing.statement = effectiveStatement;
+                existing.basis = effectiveBasis;
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            hypothesisId: existing.id,
+                            reused: true,
+                        }),
+                    }],
+            };
+        }
+        const hypothesisId = requestedId || `h${++hypothesisCounter}`;
+        const numericId = /^h(\d+)$/i.exec(hypothesisId);
+        if (numericId) {
+            hypothesisCounter = Math.max(hypothesisCounter, Number(numericId[1]));
+        }
+        const hypothesis = {
+            id: hypothesisId,
+            statement: effectiveStatement,
+            status: 'formed',
+            basis: effectiveBasis,
+            formedAt: Date.now(),
+        };
+        hypothesesRef.push(hypothesis);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        hypothesisId,
+                    }),
+                }],
+        };
+    }) : null;
+    const resolveHypothesis = hypothesesRef ? (0, claude_agent_sdk_1.tool)('resolve_hypothesis', 'Resolve a previously submitted hypothesis as confirmed or rejected. ' +
+        'Provide the evidence that supports your conclusion. ' +
+        'All hypotheses MUST be resolved before writing your final conclusion.', {
+        hypothesisId: zod_1.z.string().optional().describe('Hypothesis ID to resolve (e.g., "h1"). Alias: id.'),
+        id: zod_1.z.string().optional().describe('Alias for hypothesisId, accepted for Claude SDK argument compatibility.'),
+        status: zod_1.z.enum(['confirmed', 'rejected']).optional().describe('Resolution: confirmed (evidence supports) or rejected (evidence contradicts). Alias: verdict.'),
+        verdict: zod_1.z.enum(['confirmed', 'rejected']).optional().describe('Alias for status, accepted for Claude SDK argument compatibility.'),
+        evidence: zod_1.z.string().describe('The evidence supporting this resolution (specific data, timestamps, tool results)'),
+    }, async ({ hypothesisId, id, status, verdict, evidence }) => {
+        const effectiveHypothesisId = (hypothesisId ?? id)?.trim();
+        const effectiveStatus = status ?? verdict;
+        if (!effectiveHypothesisId || !effectiveStatus) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: 'resolve_hypothesis requires hypothesisId (or id) and status (or verdict)',
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const hypothesis = hypothesesRef.find(h => h.id === effectiveHypothesisId);
+        if (!hypothesis) {
+            const now = Date.now();
+            const backfilled = {
+                id: effectiveHypothesisId,
+                statement: `Backfilled hypothesis ${effectiveHypothesisId}`,
+                status: effectiveStatus,
+                basis: 'resolve_hypothesis was called before submit_hypothesis; preserving the resolution evidence instead of failing the run.',
+                evidence,
+                formedAt: now,
+                resolvedAt: now,
+            };
+            hypothesesRef.push(backfilled);
+            const numericId = /^h(\d+)$/i.exec(effectiveHypothesisId);
+            if (numericId) {
+                hypothesisCounter = Math.max(hypothesisCounter, Number(numericId[1]));
+            }
+            const unresolvedCount = hypothesesRef.filter(h => h.status === 'formed').length;
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            hypothesisId: effectiveHypothesisId,
+                            status: effectiveStatus,
+                            backfilled: true,
+                            unresolvedCount,
+                        }),
+                    }],
+            };
+        }
+        if (hypothesis.status !== 'formed') {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: `Hypothesis "${effectiveHypothesisId}" already resolved as ${hypothesis.status}` }) }],
+                isError: true,
+            };
+        }
+        hypothesis.status = effectiveStatus;
+        hypothesis.evidence = evidence;
+        hypothesis.resolvedAt = Date.now();
+        const unresolvedCount = hypothesesRef.filter(h => h.status === 'formed').length;
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        hypothesisId: effectiveHypothesisId,
+                        status: effectiveStatus,
+                        unresolvedCount,
+                    }),
+                }],
+        };
+    }) : null;
+    // ── P1-G1: flag_uncertainty — non-blocking human interaction ──
+    const uncertaintyFlagsRef = options.uncertaintyFlags;
+    const flagUncertainty = uncertaintyFlagsRef ? (0, claude_agent_sdk_1.tool)('flag_uncertainty', 'Signal that you are uncertain about an aspect and making an assumption to proceed. ' +
+        'Use this when you encounter ambiguity (e.g., unclear which process is the focus app, ' +
+        'multiple possible root causes, unclear user intent). Analysis continues without blocking — ' +
+        'the user sees your flag and can provide clarification in the next turn.', {
+        topic: zod_1.z.string().describe('What aspect you are uncertain about'),
+        assumption: zod_1.z.string().describe('What assumption you are making to proceed'),
+        question: zod_1.z.string().describe('What you would ask the user if you could'),
+    }, async ({ topic, assumption, question }) => {
+        const flag = { topic, assumption, question, timestamp: Date.now() };
+        uncertaintyFlagsRef.push(flag);
+        // Emit as SSE event so the user sees it in real-time
+        emitUpdate?.({
+            type: 'progress',
+            content: {
+                phase: 'analyzing',
+                message: (0, outputLanguage_1.localize)(outputLanguage, `⚠️ 不确定性标记: ${topic}\n假设: ${assumption}\n建议确认: ${question}`, `⚠️ Uncertainty flagged: ${topic}\nAssumption: ${assumption}\nSuggested confirmation: ${question}`),
+            },
+            timestamp: Date.now(),
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        message: (0, outputLanguage_1.localize)(outputLanguage, `已标记不确定性。将基于假设继续: "${assumption}"。用户会看到该标记，并可在下一轮纠正。`, `Uncertainty flagged. Proceeding with assumption: "${assumption}". The user will see this flag and can correct it in the next turn.`),
+                        flagCount: uncertaintyFlagsRef.length,
+                    }),
+                }],
+        };
+    }) : null;
+    // ── P1-G19: recall_patterns — agent-queryable long-term memory ──
+    const recallPatterns = (0, claude_agent_sdk_1.tool)('recall_patterns', 'Query long-term analysis pattern memory for insights from past sessions with similar traces. ' +
+        'Use this when you want to check if similar traces have been analyzed before and what was discovered. ' +
+        'Provide trace characteristics like architecture type, scene type, and domain keywords.', {
+        architectureType: zod_1.z.string().optional().describe('Architecture type (e.g., "standard", "flutter_surfaceview", "compose")'),
+        sceneType: zod_1.z.string().optional().describe('Scene type (e.g., "scrolling", "startup", "anr")'),
+        keywords: zod_1.z.array(zod_1.z.string()).optional().describe('Domain keywords (e.g., ["jank", "binder", "gpu"])'),
+    }, async ({ architectureType, sceneType: querySceneType, keywords }) => {
+        const features = (0, analysisPatternMemory_1.extractTraceFeatures)({
+            architectureType,
+            sceneType: querySceneType,
+            packageName,
+        });
+        // Add extra keyword features if provided
+        if (keywords) {
+            for (const kw of keywords) {
+                features.push(`domain:${kw.toLowerCase()}`);
+            }
+        }
+        const positiveMatches = (0, analysisPatternMemory_1.matchPatterns)(features, knowledgeScope);
+        const negativeMatches = (0, analysisPatternMemory_1.matchNegativePatterns)(features, knowledgeScope);
+        if (positiveMatches.length === 0 && negativeMatches.length === 0) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            success: true,
+                            message: 'No matching patterns found in memory. This may be a novel trace configuration.',
+                            positivePatterns: [],
+                            negativePatterns: [],
+                        }) }],
+            };
+        }
+        const positive = positiveMatches.map(m => ({
+            sceneType: m.sceneType,
+            architectureType: m.architectureType,
+            score: Math.round(m.score * 100),
+            insights: m.keyInsights.slice(0, 3),
+            matchCount: m.matchCount,
+        }));
+        const negative = negativeMatches.flatMap(m => m.failedApproaches.slice(0, 3).map(a => ({
+            type: a.type,
+            approach: a.approach,
+            reason: a.reason,
+            workaround: a.workaround,
+        })));
+        // P1-10: Also include verifier's learned misdiagnosis patterns
+        let learnedMisdiagnosis = [];
+        try {
+            const learnedPatternsFile = (0, runtimePaths_1.backendLogPath)('learned_misdiagnosis_patterns.json');
+            if (fs.existsSync(learnedPatternsFile)) {
+                const raw = JSON.parse(fs.readFileSync(learnedPatternsFile, 'utf-8'));
+                const cutoff = Date.now() - 60 * 24 * 60 * 60 * 1000; // 60-day TTL
+                learnedMisdiagnosis = raw
+                    .filter((p) => p.createdAt >= cutoff && p.occurrences >= 2)
+                    .slice(0, 10)
+                    .map((p) => ({
+                    keywords: p.keywords,
+                    message: p.message,
+                    occurrences: p.occurrences,
+                }));
+            }
+        }
+        catch { /* non-fatal */ }
+        return {
+            content: [{ type: 'text', text: JSON.stringify({
+                        success: true,
+                        positivePatterns: positive,
+                        negativePatterns: negative,
+                        learnedMisdiagnosis: learnedMisdiagnosis.length > 0 ? learnedMisdiagnosis : undefined,
+                        message: `Found ${positive.length} positive and ${negative.length} negative patterns from past sessions.` +
+                            (learnedMisdiagnosis.length > 0 ? ` Also ${learnedMisdiagnosis.length} learned misdiagnosis avoidance patterns.` : ''),
+                    }) }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    // ---------------------------------------------------------------------------
+    // Comparison mode tools — conditional on referenceTraceId
+    // ---------------------------------------------------------------------------
+    const { referenceTraceId, comparisonContext } = options;
+    const executeSqlOn = referenceTraceId ? (0, claude_agent_sdk_1.tool)('execute_sql_on', 'Execute a SQL query against a specific trace in comparison mode. ' +
+        'Use "current" for the primary trace, "reference" for the comparison trace.\n\n' +
+        'Use when: you need to drill into a specific trace during comparison analysis, ' +
+        'or verify a finding from compare_skill with more targeted SQL.\n\n' +
+        'SQL safety rules: qualify duplicate column names after JOINs. Do not write bare SELECT name/ts/dur when joining slice/thread/process; use s.name AS slice_name, s.ts, s.dur, t.name AS thread_name, p.name AS process_name, or prefer the thread_slice stdlib view. FrameTimeline rows expose upid, not utid/process_name; use JOIN process USING(upid) for actual_frame_timeline_slice. thread_slice does not expose self_dur directly; JOIN slice_self_dur USING(id) when self time is needed. When using thread_slice, read thread_name and process_name directly; do not write t.name or p.name unless JOIN thread t or JOIN process p is present. The thread table main-thread column is is_main_thread, not main_thread.\n\n' +
+        'Examples:\n' +
+        '1. Check reference trace jank: trace="reference", sql="SELECT COUNT(*) FROM actual_frame_timeline_slice WHERE jank_type != \'None\'"\n' +
+        '2. Compare CPU freq: trace="current", sql="SELECT cpu, AVG(value) as avg_freq FROM counter JOIN counter_track ON counter.track_id=counter_track.id WHERE counter_track.name GLOB \'cpu*freq\' GROUP BY cpu"', {
+        trace: zod_1.z.enum(['current', 'reference']).describe('Which trace to query: "current" = primary trace loaded in Perfetto, "reference" = comparison trace.'),
+        sql: zod_1.z.string().describe('The SQL query to execute against the specified trace.'),
+        summary: zod_1.z.boolean().optional().describe('When true, returns column statistics + sample rows instead of full results. Default: false.'),
+    }, async ({ trace, sql, summary }) => {
+        const planError = requirePlan('execute_sql_on');
+        if (planError) {
+            return { content: [{ type: 'text', text: planError }] };
+        }
+        const artifactSqlHint = artifactSqlMisuseHint(sql, outputLanguage);
+        if (artifactSqlHint) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify(artifactSqlHint) }],
+                isError: true,
+            };
+        }
+        const targetTraceId = trace === 'reference' ? referenceTraceId : traceId;
+        const traceLabel = trace === 'reference'
+            ? (0, outputLanguage_1.localize)(outputLanguage, '[参考 Trace]', '[reference trace]')
+            : (0, outputLanguage_1.localize)(outputLanguage, '[当前 Trace]', '[current trace]');
+        const producer = createEvidenceProducerContext('execute_sql_on', { trace, sql, summary }, trace === 'reference'
+            ? (0, outputLanguage_1.localize)(outputLanguage, '执行参考 Trace SQL，验证对比差异。', 'Run SQL on the reference trace to verify comparison deltas.')
+            : (0, outputLanguage_1.localize)(outputLanguage, '执行当前 Trace SQL，验证对比差异。', 'Run SQL on the current trace to verify comparison deltas.'), trace);
+        try {
+            const sqlStart = Date.now();
+            const { result, finalSql, injected, traceProvenance, normalizedSql, sqlRewrites } = await runRawSqlWithIncludeInjection(targetTraceId, sql, trace);
+            const processIdentityWarning = rawSqlProcessIdentityWarning(normalizedSql);
+            const truncated = result.rows.length > 200;
+            const rows = truncated ? result.rows.slice(0, 200) : result.rows;
+            const success = !result.error;
+            let emittedEvidence;
+            if (success && summary && result.rows.length > 0) {
+                const summaryResult = (0, sqlSummarizer_1.summarizeSqlResult)(result.columns, result.rows);
+                const durationMs = Date.now() - sqlStart;
+                if (emitUpdate) {
+                    emittedEvidence = emitSqlSummaryDataEnvelope(emitUpdate, summaryResult, finalSql, injected, traceProvenance, producer);
+                }
+                const text = JSON.stringify({
+                    success: true,
+                    trace: traceLabel,
+                    traceSide: trace,
+                    traceId: targetTraceId,
+                    traceProvenance,
+                    summary: summaryResult,
+                    totalRows: result.rows.length,
+                    durationMs,
+                    evidenceRefId: emittedEvidence?.evidenceRefId,
+                    sourceToolCallId: producer.sourceToolCallId,
+                    paramsHash: producer.paramsHash,
+                    planPhaseId: producer.planPhaseId,
+                    executableSql: finalSql,
+                    ...(sqlRewrites.length > 0 ? { sqlRewrites } : {}),
+                    stdlibInjectedModules: injected,
+                    ...(processIdentityWarning ? { processIdentityWarning } : {}),
+                });
+                return { content: [{ type: 'text', text: consumeWatchdogWarning(text + getReasoningNudge()) }] };
+            }
+            const durationMs = Date.now() - sqlStart;
+            if (emitUpdate && success && result.columns.length > 0) {
+                emittedEvidence = emitSqlDataEnvelope(emitUpdate, result.columns, rows, finalSql, injected, traceProvenance, producer);
+            }
+            else if (emitUpdate && !success) {
+                emittedEvidence = emitSqlDiagnosticDataEnvelope(emitUpdate, result.error || (0, outputLanguage_1.localize)(outputLanguage, 'SQL 执行失败', 'SQL execution failed'), finalSql, injected, traceProvenance, producer);
+            }
+            const text = JSON.stringify({
+                success,
+                trace: traceLabel,
+                traceSide: trace,
+                traceId: targetTraceId,
+                traceProvenance,
+                columns: result.columns,
+                rows,
+                totalRows: result.rows.length,
+                truncated,
+                durationMs,
+                evidenceRefId: emittedEvidence?.evidenceRefId,
+                sourceToolCallId: producer.sourceToolCallId,
+                paramsHash: producer.paramsHash,
+                planPhaseId: producer.planPhaseId,
+                executableSql: finalSql,
+                ...(sqlRewrites.length > 0 ? { sqlRewrites } : {}),
+                stdlibInjectedModules: injected,
+                ...(processIdentityWarning ? { processIdentityWarning } : {}),
+                error: result.error,
+            });
+            return { content: [{ type: 'text', text: consumeWatchdogWarning(success ? text + getReasoningNudge() : text) }] };
+        }
+        catch (e) {
+            const traceProvenance = (0, traceProcessorConnectionModel_1.buildTraceProcessorQueryProvenance)({
+                traceId: targetTraceId,
+                traceSide: trace,
+            });
+            const emittedEvidence = emitUpdate ? emitSqlDiagnosticDataEnvelope(emitUpdate, e.message, sql, undefined, traceProvenance, producer, outputLanguage) : undefined;
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            trace: traceLabel,
+                            traceSide: trace,
+                            traceId: targetTraceId,
+                            traceProvenance,
+                            evidenceRefId: emittedEvidence?.evidenceRefId,
+                            sourceToolCallId: producer.sourceToolCallId,
+                            paramsHash: producer.paramsHash,
+                            planPhaseId: producer.planPhaseId,
+                            error: e.message,
+                        }),
+                    }],
+            };
+        }
+    }, { annotations: { readOnlyHint: true } }) : null;
+    const compareSkill = referenceTraceId ? (0, claude_agent_sdk_1.tool)('compare_skill', 'Run the same skill on both current and reference traces in parallel, returning side-by-side results with schema alignment info.\n\n' +
+        'Use when: you want to compare the same analysis dimension across both traces (e.g., scrolling_analysis, cpu_analysis).\n' +
+        'Don\'t use when: you need different skills on each trace, or ad-hoc SQL queries (use execute_sql_on instead).\n\n' +
+        'Examples:\n' +
+        '1. Compare scrolling: skillId="scrolling_analysis", params={process_name: "com.example.app"}\n' +
+        '2. Compare CPU: skillId="cpu_analysis"', {
+        skillId: zod_1.z.string().describe('Skill identifier to run on both traces'),
+        params: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Parameters passed to both skill executions. Common: { process_name, start_ts, end_ts }'),
+    }, async ({ skillId, params }) => {
+        const planError = requirePlan('compare_skill');
+        if (planError) {
+            return { content: [{ type: 'text', text: planError }] };
+        }
+        try {
+            const effectiveParams = normalizeSkillParams(params, packageName);
+            // For reference trace: use its own package name if detected, otherwise
+            // omit process_name filter entirely (safer than silently using current's package)
+            const refParams = comparisonContext?.referencePackageName
+                ? normalizeSkillParams(params, comparisonContext.referencePackageName)
+                : normalizeSkillParams(params); // No default package — skill runs unfiltered
+            const baseProducer = createEvidenceProducerContext('compare_skill', { skillId, params }, (0, outputLanguage_1.localize)(outputLanguage, `对比 Skill ${skillId}，在当前和参考 Trace 上收集同构证据。`, `Compare Skill ${skillId} to collect aligned evidence on current and reference traces.`));
+            emitUpdate?.({
+                type: 'progress',
+                content: {
+                    phase: 'analyzing',
+                    message: (0, outputLanguage_1.localize)(outputLanguage, `对比技能 ${skillId}：在两个 Trace 上并行执行...`, `Comparing skill ${skillId}: running on both traces in parallel...`),
+                },
+                timestamp: Date.now(),
+            });
+            const compareStart = Date.now();
+            const currentTraceProvenance = (0, traceProcessorConnectionModel_1.buildTraceProcessorQueryProvenance)({
+                traceId,
+                traceSide: 'current',
+            });
+            const referenceTraceProvenance = (0, traceProcessorConnectionModel_1.buildTraceProcessorQueryProvenance)({
+                traceId: referenceTraceId,
+                traceSide: 'reference',
+            });
+            const [currentResult, refResult] = await Promise.all([
+                skillExecutor.execute(skillId, traceId, effectiveParams),
+                skillExecutor.execute(skillId, referenceTraceId, refParams),
+            ]);
+            const compareDuration = Date.now() - compareStart;
+            // Schema alignment: check which steps are comparable
+            const currentStepIds = new Set((currentResult.displayResults || []).map(r => r.stepId));
+            const refStepIds = new Set((refResult.displayResults || []).map(r => r.stepId));
+            const comparableSteps = [...currentStepIds].filter(id => refStepIds.has(id));
+            const incompatibleSteps = [
+                ...[...currentStepIds]
+                    .filter(id => !refStepIds.has(id))
+                    .map(id => `${id} ${(0, outputLanguage_1.localize)(outputLanguage, '(仅当前 Trace)', '(current trace only)')}`),
+                ...[...refStepIds]
+                    .filter(id => !currentStepIds.has(id))
+                    .map(id => `${id} ${(0, outputLanguage_1.localize)(outputLanguage, '(仅参考 Trace)', '(reference trace only)')}`),
+            ];
+            // Emit data envelopes for both sides (labeled)
+            if (emitUpdate && currentResult.displayResults?.length) {
+                emitSkillDataEnvelopes(currentResult.displayResults, skillId, emitUpdate, currentTraceProvenance, {
+                    ...baseProducer,
+                    sourceToolCallId: `${baseProducer.sourceToolCallId}:current`,
+                    producerReason: (0, outputLanguage_1.localize)(outputLanguage, `当前 Trace 对比 Skill ${skillId} 结果。`, `Current trace result for comparison Skill ${skillId}.`),
+                });
+            }
+            if (emitUpdate && refResult.displayResults?.length) {
+                emitSkillDataEnvelopes(refResult.displayResults, skillId, emitUpdate, referenceTraceProvenance, {
+                    ...baseProducer,
+                    sourceToolCallId: `${baseProducer.sourceToolCallId}:reference`,
+                    producerReason: (0, outputLanguage_1.localize)(outputLanguage, `参考 Trace 对比 Skill ${skillId} 结果。`, `Reference trace result for comparison Skill ${skillId}.`),
+                });
+            }
+            // Build compact comparison summary for Claude
+            const buildStepSummary = (results) => results.map(r => ({
+                stepId: r.stepId,
+                title: r.title,
+                rowCount: r.data?.rows?.length || 0,
+                columns: r.data?.columns || [],
+            }));
+            const text = JSON.stringify({
+                success: true,
+                durationMs: compareDuration,
+                current: {
+                    traceSide: 'current',
+                    traceId,
+                    traceProvenance: currentTraceProvenance,
+                    success: currentResult.success,
+                    stepCount: currentResult.displayResults?.length || 0,
+                    steps: buildStepSummary(currentResult.displayResults || []),
+                    diagnosticCount: currentResult.diagnostics?.length || 0,
+                    error: currentResult.error,
+                },
+                reference: {
+                    traceSide: 'reference',
+                    traceId: referenceTraceId,
+                    traceProvenance: referenceTraceProvenance,
+                    success: refResult.success,
+                    stepCount: refResult.displayResults?.length || 0,
+                    steps: buildStepSummary(refResult.displayResults || []),
+                    diagnosticCount: refResult.diagnostics?.length || 0,
+                    error: refResult.error,
+                },
+                alignment: {
+                    comparableSteps,
+                    incompatibleSteps: incompatibleSteps.length > 0 ? incompatibleSteps : undefined,
+                },
+                hint: (0, outputLanguage_1.localize)(outputLanguage, '使用 execute_sql_on 深钻具体差异指标，或使用 fetch_artifact 获取详细数据。', 'Use execute_sql_on to drill into specific delta metrics, or fetch_artifact for detailed data.'),
+            });
+            return { content: [{ type: 'text', text: consumeWatchdogWarning(text + getReasoningNudge()) }] };
+        }
+        catch (e) {
+            return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: e.message }) }] };
+        }
+    }) : null;
+    const getComparisonContext = (referenceTraceId && comparisonContext) ? (0, claude_agent_sdk_1.tool)('get_comparison_context', 'Get metadata comparison between the current trace and the reference trace. ' +
+        'Returns device info, focus app, architecture, and capability alignment for both traces.\n\n' +
+        'ALWAYS call this first in comparison mode to understand what you are comparing ' +
+        'and confirm the traces are comparable (same app, compatible capabilities).', {}, async () => {
+        const ctx = comparisonContext;
+        const text = JSON.stringify({
+            success: true,
+            current: {
+                traceId,
+                packageName: packageName || 'unknown',
+                architecture: options.cachedArchitecture?.type || 'unknown',
+                focusApps: options.cachedArchitecture ? undefined : 'detect with detect_architecture',
+            },
+            reference: {
+                traceId: referenceTraceId,
+                packageName: ctx.referencePackageName || 'unknown',
+                architecture: ctx.referenceArchitecture?.type || 'unknown',
+            },
+            packageAlignment: packageName && ctx.referencePackageName
+                ? (packageName === ctx.referencePackageName ? 'same' : 'different')
+                : 'unknown',
+            commonCapabilities: ctx.commonCapabilities,
+            capabilityDiff: ctx.capabilityDiff,
+        });
+        return { content: [{ type: 'text', text }] };
+    }, { annotations: { readOnlyHint: true } }) : null;
+    // Plan 41 M0 (P2-G1 evolution): the canonical tool list lives in
+    // `McpToolRegistry`. Each register call carries the §4.5 exposure
+    // level so future hosts (stdio, A2A) can filter without
+    // re-deciding policy. Registration order is preserved exactly to
+    // keep SDK behavior identical to the pre-refactor toolEntries
+    // array — trace regression validates that.
+    const registry = new mcpToolRegistry_1.McpToolRegistry();
+    if (options.lightweight) {
+        // Lightweight mode: core data-access tools only — no planning,
+        // hypothesis, notes, or advanced tools. Plan gate is automatically
+        // disabled because analysisPlan is not passed in lightweight mode.
+        // `invoke_skill` returns artifact references, so `fetch_artifact` must
+        // stay available or lightweight models try to query artifact IDs as SQL.
+        registry.registerSdk(executeSql, 'execute_sql', 'public');
+        registry.registerSdk(invokeSkill, 'invoke_skill', 'public');
+        registry.registerSdk(lookupSqlSchema, 'lookup_sql_schema', 'public');
+        if (fetchArtifact)
+            registry.registerSdk(fetchArtifact, 'fetch_artifact', 'public');
+    }
+    else {
+        // Full mode: all always-on tools + conditional tools.
+        registry.registerSdk(executeSql, 'execute_sql', 'public');
+        registry.registerSdk(invokeSkill, 'invoke_skill', 'public');
+        registry.registerSdk(listSkills, 'list_skills', 'public');
+        registry.registerSdk(detectArchitecture, 'detect_architecture', 'public');
+        registry.registerSdk(lookupSqlSchema, 'lookup_sql_schema', 'public');
+        registry.registerSdk(queryPerfettoSource, 'query_perfetto_source', 'public');
+        registry.registerSdk(listStdlibModules, 'list_stdlib_modules', 'public');
+        registry.registerSdk(lookupKnowledge, 'lookup_knowledge', 'public');
+        registry.registerSdk(lookupBlogKnowledge, 'lookup_blog_knowledge', 'public');
+        registry.registerSdk(lookupAospSource, 'lookup_aosp_source', 'public');
+        registry.registerSdk(lookupOemSdk, 'lookup_oem_sdk', 'public');
+        registry.registerSdk(lookupBaseline, 'lookup_baseline', 'public');
+        registry.registerSdk(compareBaselines, 'compare_baselines', 'public');
+        registry.registerSdk(recallProjectMemory, 'recall_project_memory', 'public');
+        registry.registerSdk(recallSimilarCase, 'recall_similar_case', 'public');
+        if (writeAnalysisNote)
+            registry.registerSdk(writeAnalysisNote, 'write_analysis_note', 'internal');
+        if (fetchArtifact)
+            registry.registerSdk(fetchArtifact, 'fetch_artifact', 'public');
+        if (submitPlan)
+            registry.registerSdk(submitPlan, 'submit_plan', 'internal');
+        if (updatePlanPhase)
+            registry.registerSdk(updatePlanPhase, 'update_plan_phase', 'internal');
+        if (revisePlan)
+            registry.registerSdk(revisePlan, 'revise_plan', 'internal');
+        if (submitHypothesis)
+            registry.registerSdk(submitHypothesis, 'submit_hypothesis', 'internal');
+        if (resolveHypothesis)
+            registry.registerSdk(resolveHypothesis, 'resolve_hypothesis', 'internal');
+        if (flagUncertainty)
+            registry.registerSdk(flagUncertainty, 'flag_uncertainty', 'internal');
+        // recall_patterns stays 'internal' for one more commit. Plan 41 M1b
+        // routes the recall path through openSupersedeStoreReadOnly so it no
+        // longer mkdir's or migrates the supersede DB on first call. The
+        // public-readonly exposure flip is gated on the M1b invariant test
+        // soaking for one release cycle to catch any hidden writable code
+        // path; that flip is the M1b commit 2 follow-up.
+        registry.registerSdk(recallPatterns, 'recall_patterns', 'internal');
+        // Comparison mode tools — only when referenceTraceId is provided.
+        if (compareSkill)
+            registry.registerSdk(compareSkill, 'compare_skill', 'internal');
+        if (executeSqlOn)
+            registry.registerSdk(executeSqlOn, 'execute_sql_on', 'internal');
+        if (getComparisonContext)
+            registry.registerSdk(getComparisonContext, 'get_comparison_context', 'internal');
+    }
+    return {
+        server: registry.buildSdkServer(),
+        allowedTools: registry.buildAllowedTools(),
+        toolDefinitions: registry.list(),
+    };
+}
+function evidenceHash(input) {
+    const text = typeof input === 'string'
+        ? input
+        : JSON.stringify(input, (_key, value) => typeof value === 'bigint' ? value.toString() : value);
+    return (0, crypto_1.createHash)('sha256').update(text || '').digest('hex').slice(0, 12);
+}
+function evidencePart(value, fallback = 'unknown') {
+    const text = String(value ?? fallback)
+        .trim()
+        .replace(/[^a-zA-Z0-9_.-]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 80);
+    return text || fallback;
+}
+function evidenceTracePart(traceProvenance) {
+    if (!traceProvenance)
+        return 'trace_unknown';
+    const side = evidencePart(traceProvenance.traceSide || 'current', 'current');
+    const trace = evidenceHash(traceProvenance.traceId);
+    return `${side}:${trace}`;
+}
+function stableSqlEvidenceRefId(sql, columns, rows, traceProvenance, producer, mode = 'table') {
+    const queryHash = evidenceHash(sql || { columns, sampleRows: rows.slice(0, 5), rowCount: rows.length });
+    const toolPart = evidencePart(producer?.paramsHash || 'tool', 'tool');
+    return {
+        evidenceRefId: `data:sql_${mode}:${evidenceTracePart(traceProvenance)}:${queryHash}:${toolPart}`,
+        queryHash,
+    };
+}
+function stableSkillEvidenceRefId(skillId, stepId, title, data, traceProvenance, producer) {
+    const dataHash = evidenceHash({
+        title,
+        data,
+    });
+    const toolPart = evidencePart(producer?.paramsHash || 'tool', 'tool');
+    return `data:skill:${evidencePart(skillId, 'skill')}:${evidencePart(stepId || title, 'step')}:${evidenceTracePart(traceProvenance)}:${dataHash}:${toolPart}`;
+}
+function sqlSummaryMarkdown(summary) {
+    const stats = Array.isArray(summary.columnStats) ? summary.columnStats : [];
+    const lines = [
+        `Total rows: ${summary.totalRows}`,
+        '',
+        '| Column | Type | Min | Avg | P95 | Max | Nulls |',
+        '| --- | --- | ---: | ---: | ---: | ---: | ---: |',
+    ];
+    for (const stat of stats.slice(0, 20)) {
+        lines.push([
+            stat.column,
+            stat.type,
+            stat.min ?? '',
+            stat.avg ?? '',
+            stat.p95 ?? '',
+            stat.max ?? '',
+            stat.nullCount,
+        ].join(' | '));
+    }
+    return lines.join('\n');
+}
+function sqlSummaryMetrics(summary) {
+    const metrics = [
+        { label: 'total_rows', value: summary.totalRows, severity: 'info' },
+    ];
+    const stats = Array.isArray(summary.columnStats) ? summary.columnStats : [];
+    for (const stat of stats.slice(0, 8)) {
+        if (stat.type !== 'numeric')
+            continue;
+        if (stat.avg !== undefined)
+            metrics.push({ label: `${stat.column}.avg`, value: stat.avg, severity: 'info' });
+        if (stat.p95 !== undefined)
+            metrics.push({ label: `${stat.column}.p95`, value: stat.p95, severity: 'info' });
+    }
+    return metrics;
+}
+function producerEnvelopeOptions(producer) {
+    return {
+        sourceToolCallId: producer?.sourceToolCallId,
+        paramsHash: producer?.paramsHash,
+        planPhaseId: producer?.planPhaseId,
+        planPhaseTitle: producer?.planPhaseTitle,
+        planPhaseGoal: producer?.planPhaseGoal,
+        planPhaseAttribution: producer?.planPhaseAttribution,
+        planPhaseWarning: producer?.planPhaseWarning,
+        toolNarration: producer?.toolNarration,
+        producerReason: producer?.producerReason,
+    };
+}
+/** Emit a DataEnvelope for SQL query results. */
+function emitSqlDataEnvelope(emit, columns, rows, sql, stdlibInjectedModules, traceProvenance, producer) {
+    const { evidenceRefId, queryHash } = stableSqlEvidenceRefId(sql, columns, rows, traceProvenance, producer);
+    const envelope = (0, dataContract_1.createDataEnvelope)({ columns, rows }, {
+        type: 'sql_result',
+        source: 'execute_sql',
+        title: `SQL Query (${rows.length} rows)`,
+        layer: 'list',
+        format: 'table',
+        columns: columns.map((col) => ({
+            name: col,
+            type: inferSqlColumnType(col),
+        })),
+        evidenceRefId,
+        traceSide: traceProvenance?.traceSide,
+        traceId: traceProvenance?.traceId,
+        queryHash,
+        ...producerEnvelopeOptions(producer),
+        intent: 'ad_hoc_sql_verification',
+    });
+    emit({
+        type: 'data',
+        content: [{
+                ...envelope,
+                ...(sql ? { sql } : {}),
+                ...(stdlibInjectedModules?.length ? { stdlibInjectedModules } : {}),
+                ...(traceProvenance ? {
+                    traceSide: traceProvenance.traceSide,
+                    traceId: traceProvenance.traceId,
+                    traceProvenance,
+                } : {}),
+            }],
+        timestamp: Date.now(),
+    });
+    return { evidenceRefId, queryHash };
+}
+/** Emit a DataEnvelope for SQL summary-mode results. */
+function emitSqlSummaryDataEnvelope(emit, summary, sql, stdlibInjectedModules, traceProvenance, producer) {
+    const { evidenceRefId, queryHash } = stableSqlEvidenceRefId(sql, summary.columns, summary.sampleRows, traceProvenance, producer, 'summary');
+    const envelope = (0, dataContract_1.createDataEnvelope)({
+        summary: {
+            title: `SQL Summary (${summary.totalRows} rows)`,
+            content: sqlSummaryMarkdown(summary),
+            metrics: sqlSummaryMetrics(summary),
+        },
+    }, {
+        type: 'sql_result',
+        source: 'execute_sql',
+        title: `SQL Summary (${summary.totalRows} rows)`,
+        layer: 'overview',
+        format: 'summary',
+        evidenceRefId,
+        traceSide: traceProvenance?.traceSide,
+        traceId: traceProvenance?.traceId,
+        queryHash,
+        ...producerEnvelopeOptions(producer),
+        intent: 'ad_hoc_sql_summary',
+    });
+    emit({
+        type: 'data',
+        content: [{
+                ...envelope,
+                ...(sql ? { sql } : {}),
+                ...(stdlibInjectedModules?.length ? { stdlibInjectedModules } : {}),
+                ...(traceProvenance ? {
+                    traceSide: traceProvenance.traceSide,
+                    traceId: traceProvenance.traceId,
+                    traceProvenance,
+                } : {}),
+            }],
+        timestamp: Date.now(),
+    });
+    return { evidenceRefId, queryHash };
+}
+/** Emit a diagnostic DataEnvelope for failed SQL so missing tables remain explainable. */
+function emitSqlDiagnosticDataEnvelope(emit, error, sql, stdlibInjectedModules, traceProvenance, producer, outputLanguage = outputLanguage_1.DEFAULT_OUTPUT_LANGUAGE) {
+    const { evidenceRefId, queryHash } = stableSqlEvidenceRefId(sql, [], [[error]], traceProvenance, producer, 'diagnostic');
+    const envelope = (0, dataContract_1.createDataEnvelope)({
+        text: [
+            (0, outputLanguage_1.localize)(outputLanguage, 'SQL 执行未产出可用表格。', 'SQL execution did not produce a table.'),
+            (0, outputLanguage_1.localize)(outputLanguage, '这是一条失败诊断，不是可引用的性能证据；需要修正 SQL 后重试。', 'This is a failure diagnostic, not citable performance evidence; fix the SQL and retry.'),
+            `Error: ${error}`,
+            sql ? `SQL: ${sql}` : '',
+        ].filter(Boolean).join('\n'),
+    }, {
+        type: 'diagnostic',
+        source: 'execute_sql',
+        title: (0, outputLanguage_1.localize)(outputLanguage, 'SQL 执行诊断', 'SQL diagnostic'),
+        layer: 'diagnosis',
+        format: 'text',
+        evidenceRefId,
+        traceSide: traceProvenance?.traceSide,
+        traceId: traceProvenance?.traceId,
+        queryHash,
+        ...producerEnvelopeOptions(producer),
+        intent: 'ad_hoc_sql_diagnostic',
+    });
+    emit({
+        type: 'data',
+        content: [{
+                ...envelope,
+                ...(sql ? { sql } : {}),
+                ...(stdlibInjectedModules?.length ? { stdlibInjectedModules } : {}),
+                ...(traceProvenance ? {
+                    traceSide: traceProvenance.traceSide,
+                    traceId: traceProvenance.traceId,
+                    traceProvenance,
+                } : {}),
+            }],
+        timestamp: Date.now(),
+    });
+    return { evidenceRefId, queryHash };
+}
+function inferSqlColumnType(col) {
+    if (col.includes('ts') || col.includes('timestamp'))
+        return 'timestamp';
+    if (col.includes('dur'))
+        return 'duration';
+    if (col.includes('pct') || col.includes('percent'))
+        return 'percentage';
+    return 'string';
+}
+/**
+ * Convert skill DisplayResults to DataEnvelopes and emit as SSE 'data' events.
+ * This enables interactive tables (clickable timestamps, expandable rows) in the frontend.
+ */
+function emitSkillDataEnvelopes(displayResults, skillId, emit, traceProvenance, producer) {
+    const envelopes = displayResults
+        .filter(dr => Array.isArray(dr.data?.rows))
+        .map(dr => {
+        const explicitColumns = dr.columnDefinitions;
+        const envelope = (0, dataContract_1.displayResultToEnvelope)(dr, skillId, explicitColumns);
+        const evidenceRefId = stableSkillEvidenceRefId(skillId, envelope.meta.stepId, envelope.display.title, envelope.data, traceProvenance, producer);
+        const withEvidence = {
+            ...envelope,
+            meta: {
+                ...envelope.meta,
+                evidenceRefId,
+                traceSide: traceProvenance?.traceSide,
+                traceId: traceProvenance?.traceId,
+                ...producerEnvelopeOptions(producer),
+                intent: 'skill_structured_result',
+            },
+        };
+        return traceProvenance
+            ? {
+                ...withEvidence,
+                traceSide: traceProvenance.traceSide,
+                traceId: traceProvenance.traceId,
+                traceProvenance,
+            }
+            : withEvidence;
+    });
+    if (envelopes.length > 0) {
+        emit({ type: 'data', content: envelopes, timestamp: Date.now() });
+    }
+}
+//# sourceMappingURL=claudeMcpServer.js.map