@gracker/smartperfetto 1.0.13

package/dist/routes/agentRoutes.js

@@ -0,0 +1,4349 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Agent Analysis Routes
+ *
+ * API endpoints for Agent-based trace analysis using the agent-driven architecture
+ */
+const express_1 = __importDefault(require("express"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const traceProcessorService_1 = require("../services/traceProcessorService");
+const sessionLogger_1 = require("../services/sessionLogger");
+const htmlReportGenerator_1 = require("../services/htmlReportGenerator");
+const agentReportData_1 = require("../services/agentReportData");
+const persistAgentSession_1 = require("../services/persistAgentSession");
+const comparisonAppendixService_1 = require("../services/comparisonAppendixService");
+const agentResultNormalizer_1 = require("../services/agentResultNormalizer");
+const reportRoutes_1 = require("./reportRoutes");
+const sessionPersistenceService_1 = require("../services/sessionPersistenceService");
+const auth_1 = require("../middleware/auth");
+const resourceOwnership_1 = require("../services/resourceOwnership");
+const rbac_1 = require("../services/rbac");
+const traceMetadataStore_1 = require("../services/traceMetadataStore");
+const enhancedSessionContext_1 = require("../agent/context/enhancedSessionContext");
+const agent_1 = require("../agent");
+const modelRouterSingleton_1 = require("../agent/core/modelRouterSingleton");
+const conclusionSceneTemplates_1 = require("../agent/core/conclusionSceneTemplates");
+const analysisNarrative_1 = require("../utils/analysisNarrative");
+const agentSceneReconstructRoutes_1 = require("./agentSceneReconstructRoutes");
+const sceneStoryService_1 = require("../agent/scene/sceneStoryService");
+const sceneReportStore_1 = require("../services/sceneReport/sceneReportStore");
+const sceneReportMemoryCache_1 = require("../services/sceneReport/sceneReportMemoryCache");
+const traceHash_1 = require("../agent/scene/traceHash");
+const sceneTraceDurationProbe_1 = require("../agent/scene/sceneTraceDurationProbe");
+const config_1 = require("../config");
+const traceProcessorLeaseStore_1 = require("../services/traceProcessorLeaseStore");
+const traceProcessorLeaseModeDecision_1 = require("../services/traceProcessorLeaseModeDecision");
+const enterpriseQuotaPolicyService_1 = require("../services/enterpriseQuotaPolicyService");
+const enterpriseTenantLifecycleService_1 = require("../services/enterpriseTenantLifecycleService");
+const traceProcessorRamBudget_1 = require("../services/traceProcessorRamBudget");
+const workingTraceProcessor_1 = require("../services/workingTraceProcessor");
+const agentLogsRoutes_1 = require("./agentLogsRoutes");
+const agentQuickSceneRoutes_1 = require("./agentQuickSceneRoutes");
+const agentReportRoutes_1 = require("./agentReportRoutes");
+const agentResumeRoutes_1 = require("./agentResumeRoutes");
+const agentSessionCatalogRoutes_1 = require("./agentSessionCatalogRoutes");
+const agentTeachingRoutes_1 = require("./agentTeachingRoutes");
+const assistantApplicationService_1 = require("../assistant/application/assistantApplicationService");
+const streamProjector_1 = require("../assistant/stream/streamProjector");
+const sessionSseReplay_1 = require("../assistant/stream/sessionSseReplay");
+const agentEventStore_1 = require("../services/agentEventStore");
+const analysisRunStore_1 = require("../services/analysisRunStore");
+const agentAnalyzeSessionService_1 = require("../assistant/application/agentAnalyzeSessionService");
+const assistantResultContract_1 = require("../assistant/contracts/assistantResultContract");
+const analysisResultSnapshotPipeline_1 = require("../services/analysisResultSnapshotPipeline");
+// DataEnvelope types for v2.0 data contract
+const dataContract_1 = require("../types/dataContract");
+const skillExecutor_1 = require("../services/skillEngine/skillExecutor");
+const skillLoader_1 = require("../services/skillEngine/skillLoader");
+const feedbackEnricher_1 = require("../agentv3/selfImprove/feedbackEnricher");
+const toolNarration_1 = require("../agentv3/toolNarration");
+const analysisPatternMemory_1 = require("../agentv3/analysisPatternMemory");
+const runtimePaths_1 = require("../runtimePaths");
+const router = express_1.default.Router();
+const REQUEST_ID_HEADER = 'x-request-id';
+const MAX_REQUEST_ID_LENGTH = 128;
+function sanitizeRequestId(raw) {
+    const text = String(raw || '').trim();
+    if (!text)
+        return '';
+    const normalized = text.replace(/[^a-zA-Z0-9._:-]/g, '').slice(0, MAX_REQUEST_ID_LENGTH);
+    return normalized;
+}
+function generateRequestId() {
+    return `req-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function resolveRequestIdFromRequest(req) {
+    const headerId = req.header(REQUEST_ID_HEADER) ||
+        req.header('x-correlation-id') ||
+        req.header('x-amzn-trace-id');
+    const bodyId = req.body && typeof req.body === 'object' && !Array.isArray(req.body)
+        ? req.body.requestId
+        : undefined;
+    return sanitizeRequestId(headerId) || sanitizeRequestId(bodyId) || generateRequestId();
+}
+function getRequestId(req) {
+    return req.assistantRequestId || resolveRequestIdFromRequest(req);
+}
+function normalizeRunSequence(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.floor(Number(value)));
+}
+function buildRunId(sessionId, sequence) {
+    return `run-${sessionId}-${sequence}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function sendAgentQuotaDenied(res, decision) {
+    return res.status(decision.httpStatus).json({
+        success: false,
+        code: decision.code,
+        status: decision.status,
+        error: decision.message,
+        details: decision.details,
+    });
+}
+function terminalRunStatusForResult(result) {
+    if (result.terminationReason === 'max_budget_usd')
+        return 'quota_exceeded';
+    return result.success ? 'completed' : 'failed';
+}
+function enterpriseLeasesEnabled() {
+    return (0, config_1.resolveFeatureConfig)().enterprise;
+}
+function leaseScopeFromRequestContext(context) {
+    return {
+        tenantId: context.tenantId,
+        workspaceId: context.workspaceId,
+        userId: context.userId,
+    };
+}
+function leaseScopeFromSession(session) {
+    if (!session.tenantId || !session.workspaceId)
+        return null;
+    return {
+        tenantId: session.tenantId,
+        workspaceId: session.workspaceId,
+        userId: session.userId,
+    };
+}
+function markLeaseReadyIfNew(lease, scope) {
+    if (lease.state !== 'pending')
+        return lease;
+    const store = (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)();
+    const starting = store.markStarting(scope, lease.id);
+    return store.markReady(scope, starting.id);
+}
+function buildLeaseModeDecisionForTrace(scope, traceId, holderType, options = {}) {
+    const store = (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)();
+    const processorStats = workingTraceProcessor_1.TraceProcessorFactory.getStats();
+    return (0, traceProcessorLeaseModeDecision_1.buildTraceProcessorLeaseModeDecision)({
+        traceId,
+        holderType,
+        analysisMode: options.analysisMode,
+        estimatedSqlMs: options.estimatedSqlMs,
+        heavySkill: options.heavySkill,
+        longTask: options.longTask,
+        estimatedNewLeaseRssBytes: typeof options.traceSizeBytes === 'number'
+            ? (0, traceProcessorRamBudget_1.estimateTraceProcessorRssBytes)(options.traceSizeBytes)
+            : undefined,
+        leases: store.listLeases(scope, { traceId }),
+        processors: processorStats.processors,
+        ramBudget: processorStats.ramBudget,
+    });
+}
+function buildSessionObservability(session) {
+    const run = session.activeRun || session.lastRun;
+    if (!run)
+        return undefined;
+    return {
+        runId: run.runId,
+        requestId: run.requestId,
+        runSequence: normalizeRunSequence(run.sequence),
+        status: run.status,
+    };
+}
+function buildStreamObservability(session) {
+    const run = session.activeRun || session.lastRun;
+    if (!run)
+        return {};
+    return {
+        runId: run.runId,
+        requestId: run.requestId,
+        runSequence: normalizeRunSequence(run.sequence),
+    };
+}
+function startSessionRun(session, query, requestId) {
+    const nextSequence = normalizeRunSequence(session.runSequence) + 1;
+    session.runSequence = nextSequence;
+    const run = {
+        runId: buildRunId(session.sessionId, nextSequence),
+        requestId: sanitizeRequestId(requestId) || generateRequestId(),
+        sequence: nextSequence,
+        query,
+        startedAt: Date.now(),
+        status: 'pending',
+    };
+    session.activeRun = run;
+    session.lastRun = run;
+    // Record query in cross-turn history (append-only, never overwritten)
+    if (!session.queryHistory)
+        session.queryHistory = [];
+    session.queryHistory.push({ turn: nextSequence, query, timestamp: Date.now() });
+    // Inject turn boundary marker for multi-turn conversations
+    if (nextSequence > 1) {
+        session.conversationOrdinal = (Number.isFinite(session.conversationOrdinal) ? session.conversationOrdinal : 0) + 1;
+        const boundaryOrdinal = session.conversationOrdinal;
+        session.conversationSteps.push({
+            eventId: `turn-boundary-${session.sessionId}-${nextSequence}`,
+            ordinal: boundaryOrdinal,
+            phase: 'progress',
+            role: 'system',
+            text: `── 第 ${nextSequence} 轮对话开始 ──`,
+            timestamp: Date.now(),
+            sourceEventType: 'turn_boundary',
+        });
+    }
+    persistSessionRunState(session, 'pending');
+    return run;
+}
+function markSessionRunStatus(session, status, error) {
+    if (!session.activeRun)
+        return;
+    session.activeRun.status = status;
+    if (status === 'completed' || status === 'failed' || status === 'quota_exceeded') {
+        session.activeRun.completedAt = Date.now();
+    }
+    session.activeRun.error = error;
+    session.lastRun = { ...session.activeRun };
+    persistSessionRunState(session, status, error);
+}
+// Attach/echo requestId for all agent endpoints.
+router.use((req, res, next) => {
+    const requestId = resolveRequestIdFromRequest(req);
+    req.assistantRequestId = requestId;
+    res.setHeader(REQUEST_ID_HEADER, requestId);
+    next();
+});
+// Apply API-key auth and RequestContext to all Agent endpoints (dev fallback still applies when key is not configured).
+router.use(auth_1.authenticate);
+const assistantAppService = new assistantApplicationService_1.AssistantApplicationService();
+const streamProjector = new streamProjector_1.StreamProjector();
+function agentEventScopeFromSession(session) {
+    const run = session.activeRun || session.lastRun;
+    if (!(0, config_1.resolveFeatureConfig)().enterprise ||
+        !session.tenantId ||
+        !session.workspaceId ||
+        !run?.runId) {
+        return null;
+    }
+    return {
+        tenantId: session.tenantId,
+        workspaceId: session.workspaceId,
+        userId: session.userId,
+        sessionId: session.sessionId,
+        runId: run.runId,
+        traceId: session.traceId,
+        query: run.query || session.query,
+    };
+}
+function analysisRunScopeFromSession(session) {
+    return agentEventScopeFromSession(session);
+}
+function persistSessionRunState(session, status, error) {
+    const scope = analysisRunScopeFromSession(session);
+    if (!scope)
+        return;
+    try {
+        (0, analysisRunStore_1.persistAnalysisRunState)(scope, status, { error });
+    }
+    catch (persistError) {
+        const message = persistError instanceof Error ? persistError.message : String(persistError);
+        session.logger.warn('AnalysisRun', 'Failed to persist run state', {
+            sessionId: session.sessionId,
+            runId: scope.runId,
+            status,
+            error: message,
+        });
+    }
+}
+function heartbeatSessionRun(session) {
+    const scope = analysisRunScopeFromSession(session);
+    if (!scope)
+        return;
+    try {
+        (0, analysisRunStore_1.heartbeatAnalysisRun)(scope);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        session.logger.warn('AnalysisRun', 'Failed to persist run heartbeat', {
+            sessionId: session.sessionId,
+            runId: scope.runId,
+            error: message,
+        });
+    }
+}
+function startSessionRunHeartbeat(session) {
+    if (!analysisRunScopeFromSession(session))
+        return undefined;
+    heartbeatSessionRun(session);
+    return setInterval(() => heartbeatSessionRun(session), AGENT_RUN_HEARTBEAT_INTERVAL_MS);
+}
+function isPersistedSessionRunFresh(session, now) {
+    const scope = analysisRunScopeFromSession(session);
+    if (!scope)
+        return false;
+    try {
+        return (0, analysisRunStore_1.isAnalysisRunHeartbeatFresh)(scope, scope.runId, now, AGENT_RUN_HEARTBEAT_MAX_STALE_MS);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        session.logger.warn('AnalysisRun', 'Failed to inspect persisted run heartbeat', {
+            sessionId: session.sessionId,
+            runId: scope.runId,
+            error: message,
+        });
+        return true;
+    }
+}
+function persistBufferedAgentEvent(session, event) {
+    const scope = agentEventScopeFromSession(session);
+    if (!scope)
+        return;
+    try {
+        (0, agentEventStore_1.persistSerializedAgentEvent)(scope, event);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        session.logger.warn('AgentEvents', 'Failed to persist SSE event', {
+            sessionId: session.sessionId,
+            runId: scope.runId,
+            eventType: event.eventType,
+            cursor: event.cursor,
+            error: message,
+        });
+    }
+}
+function replayPersistedAgentEvents(session, res, lastEventId) {
+    const scope = agentEventScopeFromSession(session);
+    if (!scope)
+        return { replayed: 0, includesTerminal: false, lastCursor: lastEventId };
+    let events = [];
+    try {
+        events = (0, agentEventStore_1.listSerializedAgentEventsAfter)(scope, scope.runId, lastEventId);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        session.logger.warn('AgentEvents', 'Failed to load persisted SSE replay events', {
+            sessionId: session.sessionId,
+            runId: scope.runId,
+            lastEventId,
+            error: message,
+        });
+        return { replayed: 0, includesTerminal: false, lastCursor: lastEventId };
+    }
+    let replayed = 0;
+    let includesTerminal = false;
+    let lastCursor = lastEventId;
+    for (const event of events) {
+        try {
+            res.write(`id: ${event.cursor}\n`);
+            res.write(`event: ${event.eventType}\n`);
+            res.write(`data: ${event.eventData}\n\n`);
+            replayed++;
+            lastCursor = event.cursor;
+            if (sessionSseReplay_1.TERMINAL_SSE_EVENT_TYPES.has(event.eventType)) {
+                includesTerminal = true;
+            }
+        }
+        catch {
+            break;
+        }
+    }
+    return { replayed, includesTerminal, lastCursor };
+}
+function sendReplayableSessionEvent(session, res, eventType, payload) {
+    const event = (0, sessionSseReplay_1.appendReplayableSseEvent)(session, eventType, payload);
+    persistBufferedAgentEvent(session, {
+        cursor: event.seqId,
+        eventType: event.eventType,
+        eventData: event.eventData,
+        createdAt: Date.now(),
+    });
+    streamProjector.sendEvent(res, eventType, payload, event.seqId);
+    return event.seqId;
+}
+function resolveSessionContextForReview(sessionId) {
+    const activeSession = assistantAppService.getSession(sessionId);
+    if (activeSession) {
+        const activeContext = enhancedSessionContext_1.sessionContextManager.get(sessionId, activeSession.traceId) ||
+            enhancedSessionContext_1.sessionContextManager.get(sessionId);
+        if (activeContext) {
+            return {
+                context: activeContext,
+                source: 'memory',
+                traceId: activeSession.traceId,
+                query: activeSession.query,
+                createdAt: activeSession.createdAt,
+                tenantId: activeSession.tenantId,
+                workspaceId: activeSession.workspaceId,
+                userId: activeSession.userId,
+            };
+        }
+    }
+    const memoryContext = enhancedSessionContext_1.sessionContextManager.get(sessionId);
+    if (memoryContext) {
+        return {
+            context: memoryContext,
+            source: 'memory',
+            traceId: memoryContext.getTraceId(),
+            query: activeSession?.query,
+            createdAt: activeSession?.createdAt,
+            tenantId: activeSession?.tenantId,
+            workspaceId: activeSession?.workspaceId,
+            userId: activeSession?.userId,
+        };
+    }
+    const persistenceService = sessionPersistenceService_1.SessionPersistenceService.getInstance();
+    const persistedSession = persistenceService.getSession(sessionId);
+    if (!persistedSession) {
+        return null;
+    }
+    const persistedContext = persistenceService.loadSessionContext(sessionId);
+    if (!persistedContext) {
+        return null;
+    }
+    return {
+        context: persistedContext,
+        source: 'persistence',
+        traceId: persistedSession.traceId,
+        query: persistedSession.question,
+        createdAt: persistedSession.createdAt,
+        tenantId: persistedSession.metadata?.tenantId,
+        workspaceId: persistedSession.metadata?.workspaceId,
+        userId: persistedSession.metadata?.userId,
+        ownerUserId: persistedSession.metadata?.ownerUserId,
+    };
+}
+function assignSessionOwner(session, context) {
+    Object.assign(session, (0, resourceOwnership_1.ownerFieldsFromContext)(context));
+}
+function getAuthorizedSession(req, res, sessionId) {
+    const context = (0, auth_1.requireRequestContext)(req);
+    const session = assistantAppService.getSession(sessionId);
+    if (!session || !(0, resourceOwnership_1.isOwnedByContext)(session, context)) {
+        (0, resourceOwnership_1.sendResourceNotFound)(res, 'Session not found');
+        return null;
+    }
+    return session;
+}
+function getAuthorizedSessionByRunId(req, res, runId) {
+    const context = (0, auth_1.requireRequestContext)(req);
+    for (const [, session] of assistantAppService.entries()) {
+        const isRequestedRun = session.activeRun?.runId === runId || session.lastRun?.runId === runId;
+        if (isRequestedRun && (0, resourceOwnership_1.isOwnedByContext)(session, context)) {
+            return session;
+        }
+    }
+    (0, resourceOwnership_1.sendResourceNotFound)(res, 'Run not found');
+    return null;
+}
+function isResolvedSessionAccessible(req, resolved) {
+    return (0, resourceOwnership_1.isOwnedByContext)(resolved, (0, auth_1.requireRequestContext)(req));
+}
+async function ensureTraceAccessible(req, res, traceId) {
+    const context = (0, auth_1.requireRequestContext)(req);
+    const metadata = await (0, traceMetadataStore_1.readTraceMetadataForContext)(traceId, context);
+    if (!metadata) {
+        (0, resourceOwnership_1.sendResourceNotFound)(res, 'Trace not found in backend');
+        return false;
+    }
+    return true;
+}
+function requestedSessionIsVisible(sessionId, context) {
+    const activeSession = assistantAppService.getSession(sessionId);
+    if (activeSession) {
+        return (0, resourceOwnership_1.isOwnedByContext)(activeSession, context);
+    }
+    const persistedSession = sessionPersistenceService_1.SessionPersistenceService.getInstance().getSession(sessionId);
+    return !persistedSession || (0, resourceOwnership_1.isOwnedByContext)(persistedSession.metadata, context);
+}
+function buildTurnSeverityCounts(turn) {
+    const counts = {
+        critical: 0,
+        high: 0,
+        warning: 0,
+        medium: 0,
+        low: 0,
+        info: 0,
+    };
+    for (const finding of turn.findings || []) {
+        const severity = String(finding?.severity || '').toLowerCase();
+        if (severity in counts) {
+            counts[severity] += 1;
+        }
+        else {
+            counts.info += 1;
+        }
+    }
+    return counts;
+}
+function toJsonSafe(value) {
+    return JSON.parse(JSON.stringify(value, (_key, v) => (typeof v === 'bigint' ? v.toString() : v)));
+}
+function buildTurnSummary(turn) {
+    const confidence = typeof turn.result?.confidence === 'number'
+        ? turn.result.confidence
+        : undefined;
+    const sanitizedConclusion = typeof turn.result?.message === 'string'
+        ? normalizeNarrativeForClient(turn.result.message)
+        : '';
+    const conclusionPreview = sanitizedConclusion
+        ? sanitizedConclusion.replace(/\s+/g, ' ').slice(0, 240)
+        : undefined;
+    return {
+        turnId: turn.id,
+        turnIndex: turn.turnIndex,
+        timestamp: turn.timestamp,
+        query: turn.query,
+        intent: {
+            primaryGoal: turn.intent?.primaryGoal || '',
+            followUpType: turn.intent?.followUpType || 'initial',
+            aspects: Array.isArray(turn.intent?.aspects) ? turn.intent.aspects : [],
+        },
+        completed: !!turn.completed,
+        success: typeof turn.result?.success === 'boolean' ? turn.result.success : null,
+        confidence,
+        findingCount: Array.isArray(turn.findings) ? turn.findings.length : 0,
+        severityCounts: buildTurnSeverityCounts(turn),
+        conclusionPreview,
+    };
+}
+function buildTurnDetail(turn) {
+    const summary = buildTurnSummary(turn);
+    return {
+        ...summary,
+        intent: toJsonSafe(turn.intent),
+        result: turn.result
+            ? toJsonSafe({
+                ...turn.result,
+                message: typeof turn.result.message === 'string'
+                    ? normalizeNarrativeForClient(turn.result.message)
+                    : turn.result.message,
+            })
+            : null,
+        findings: toJsonSafe(turn.findings || []),
+    };
+}
+function getLastCompletedTurn(context) {
+    const turns = context.getAllTurns();
+    for (let i = turns.length - 1; i >= 0; i--) {
+        const turn = turns[i];
+        if (turn.completed && turn.result) {
+            return turn;
+        }
+    }
+    return null;
+}
+function buildRecoveredResultFromContext(sessionId, context) {
+    const turn = getLastCompletedTurn(context);
+    if (!turn || !turn.result) {
+        return null;
+    }
+    const conclusion = typeof turn.result.message === 'string' && turn.result.message.trim().length > 0
+        ? turn.result.message
+        : `已恢复会话历史。可通过 /api/agent/v1/${sessionId}/turns 查看历史轮次。`;
+    const confidence = typeof turn.result.confidence === 'number'
+        ? turn.result.confidence
+        : 0.5;
+    return {
+        sessionId,
+        success: turn.result.success !== false,
+        findings: Array.isArray(turn.findings) ? turn.findings : [],
+        hypotheses: [],
+        conclusion,
+        confidence,
+        rounds: 1,
+        totalDurationMs: 0,
+        partial: turn.result.partial,
+        terminationReason: turn.result.terminationReason,
+        terminationMessage: turn.result.terminationMessage,
+    };
+}
+function recoverResultForSessionIfNeeded(sessionId, session) {
+    if (session.result) {
+        return session.result;
+    }
+    const resolved = resolveSessionContextForReview(sessionId);
+    if (!resolved) {
+        return null;
+    }
+    const recovered = buildRecoveredResultFromContext(sessionId, resolved.context);
+    if (!recovered) {
+        return null;
+    }
+    session.result = recovered;
+    const turns = resolved.context.getAllTurns();
+    const latestTurn = turns.length > 0 ? turns[turns.length - 1] : null;
+    if (latestTurn?.query) {
+        session.query = latestTurn.query;
+    }
+    return recovered;
+}
+function buildFallbackIntentFromQuery(query) {
+    const primaryGoal = String(query || '').trim();
+    if (!primaryGoal)
+        return null;
+    return {
+        primaryGoal,
+        aspects: [],
+        expectedOutputType: 'summary',
+        complexity: 'simple',
+        followUpType: 'initial',
+    };
+}
+function resolveConclusionSceneIdHint(params) {
+    const findings = Array.isArray(params.findings) ? params.findings : [];
+    let intent = params.intent;
+    if (!intent) {
+        const resolved = resolveSessionContextForReview(params.sessionId);
+        const turn = resolved ? getLastCompletedTurn(resolved.context) : null;
+        if (turn?.intent) {
+            intent = turn.intent;
+        }
+    }
+    if (!intent) {
+        intent = buildFallbackIntentFromQuery(params.query) || undefined;
+    }
+    if (!intent)
+        return undefined;
+    try {
+        return (0, conclusionSceneTemplates_1.resolveConclusionScene)({
+            intent,
+            findings,
+            deepReasonLabel: analysisNarrative_1.DEEP_REASON_LABEL,
+        }).selectedTemplate.id;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Initialize Agent tools once
+let toolsRegistered = false;
+const SCENE_STRATEGY_IDS = ['scene_reconstruction', 'scene_reconstruction_quick'];
+const MAX_SESSION_DATA_ENVELOPES = 1200;
+const MAX_SESSION_AGENT_DIALOGUE = 800;
+const MAX_SESSION_AGENT_RESPONSES = 400;
+const TERMINAL_SESSION_MAX_IDLE_MS = 30 * 60 * 1000;
+const NON_TERMINAL_SESSION_MAX_IDLE_MS = 2 * 60 * 60 * 1000;
+const AGENT_RUN_HEARTBEAT_INTERVAL_MS = 30 * 1000;
+const AGENT_RUN_HEARTBEAT_MAX_STALE_MS = NON_TERMINAL_SESSION_MAX_IDLE_MS;
+function trimSessionArray(items, maxEntries) {
+    if (items.length > maxEntries) {
+        items.splice(0, items.length - maxEntries);
+    }
+}
+function pushWithSessionCap(items, value, maxEntries) {
+    items.push(value);
+    trimSessionArray(items, maxEntries);
+}
+function ensureToolsRegistered() {
+    if (!toolsRegistered) {
+        (0, agent_1.registerCoreTools)();
+        toolsRegistered = true;
+        console.log('[AgentRoutes] Core tools registered');
+    }
+}
+function isDedicatedSceneReplayRequest(query) {
+    const q = String(query || '').trim().toLowerCase();
+    if (!q)
+        return false;
+    return (q === '/scene' ||
+        q.includes('场景还原') ||
+        q.includes('scene reconstruction') ||
+        q.includes('scene replay'));
+}
+// ============================================================================
+// Main Analysis Endpoints
+// ============================================================================
+/**
+ * POST /api/agent/v1/analyze
+ *
+ * Start analysis using AgentRuntime
+ *
+ * Features:
+ * - Agent-driven task graph planning
+ * - Domain agent evidence collection
+ * - Multi-round analysis with strategy planning
+ * - DataEnvelope streaming
+ *
+ * Body:
+ * {
+ *   "traceId": "uuid-of-trace",
+ *   "query": "分析这个 trace 的滑动性能",
+ *   "options": {
+ *     "maxRounds": 5,
+ *     "confidenceThreshold": 0.7,
+ *     "maxNoProgressRounds": 2,
+ *     "maxFailureRounds": 2,
+ *     "maxConcurrentTasks": 3
+ *   }
+ * }
+ */
+async function handleAnalyzeRequest(req, res, requestedSessionIdOverride) {
+    try {
+        const requestId = getRequestId(req);
+        const requestContext = (0, auth_1.requireRequestContext)(req);
+        const { traceId, query, sessionId: bodyRequestedSessionId, options = {}, selectionContext: rawSelectionContext, referenceTraceId, traceContext: rawTraceContext, providerId, } = req.body;
+        const requestedSessionId = requestedSessionIdOverride || bodyRequestedSessionId;
+        if (!(0, rbac_1.hasRbacPermission)(requestContext, 'agent:run')) {
+            (0, rbac_1.sendForbidden)(res, 'Starting analysis requires agent:run permission');
+            return;
+        }
+        const tenantDecision = (0, enterpriseTenantLifecycleService_1.evaluateTenantMutationPolicy)(requestContext);
+        if (!tenantDecision.allowed) {
+            res.status(tenantDecision.httpStatus).json((0, enterpriseTenantLifecycleService_1.sendTenantMutationDeniedPayload)(tenantDecision));
+            return;
+        }
+        if (!traceId) {
+            res.status(400).json({
+                success: false,
+                error: 'traceId is required',
+            });
+            return;
+        }
+        if (!query) {
+            res.status(400).json({
+                success: false,
+                error: 'query is required',
+            });
+            return;
+        }
+        if (isDedicatedSceneReplayRequest(query)) {
+            res.status(400).json({
+                success: false,
+                code: 'SCENE_REPLAY_SEPARATED',
+                error: '场景还原已独立为专用功能',
+                hint: '请使用 /scene 命令（前端）或 POST /api/agent/v1/scene-reconstruct（后端）',
+            });
+            return;
+        }
+        if (requestedSessionId && !requestedSessionIsVisible(requestedSessionId, requestContext)) {
+            (0, resourceOwnership_1.sendResourceNotFound)(res, 'Session not found');
+            return;
+        }
+        // Validate selectionContext — strip invalid payloads silently instead of rejecting
+        let selectionContext;
+        if (rawSelectionContext && typeof rawSelectionContext === 'object') {
+            const sc = rawSelectionContext;
+            if (sc.kind === 'area' && typeof sc.startNs === 'number' && typeof sc.endNs === 'number') {
+                selectionContext = sc;
+            }
+            else if (sc.kind === 'track_event' && typeof sc.eventId === 'number' && typeof sc.ts === 'number') {
+                selectionContext = sc;
+            }
+            // Otherwise: invalid kind or missing required fields — selectionContext stays undefined
+        }
+        // Verify trace exists
+        const traceProcessorService = (0, traceProcessorService_1.getTraceProcessorService)();
+        if (!await ensureTraceAccessible(req, res, traceId)) {
+            return;
+        }
+        const trace = await traceProcessorService.getOrLoadTrace(traceId);
+        if (!trace) {
+            res.status(404).json({
+                success: false,
+                error: 'Trace not found in backend',
+                hint: 'Please upload the trace to the backend first',
+                code: 'TRACE_NOT_UPLOADED',
+            });
+            return;
+        }
+        const validateReferenceTraceForRun = async (candidateReferenceTraceId) => {
+            if (candidateReferenceTraceId === traceId) {
+                res.status(400).json({
+                    success: false,
+                    error: 'referenceTraceId must be different from traceId',
+                    code: 'SAME_TRACE_COMPARISON',
+                });
+                return null;
+            }
+            if (!await ensureTraceAccessible(req, res, candidateReferenceTraceId)) {
+                return null;
+            }
+            const refTrace = await traceProcessorService.getOrLoadTrace(candidateReferenceTraceId);
+            if (!refTrace) {
+                res.status(404).json({
+                    success: false,
+                    error: 'Reference trace not found in backend',
+                    hint: 'Please upload the reference trace to the backend first',
+                    code: 'REFERENCE_TRACE_NOT_UPLOADED',
+                });
+                return null;
+            }
+            return refTrace;
+        };
+        // Comparison mode: validate reference trace if provided
+        let requestedReferenceTrace = null;
+        if (referenceTraceId) {
+            requestedReferenceTrace = await validateReferenceTraceForRun(referenceTraceId);
+            if (!requestedReferenceTrace)
+                return;
+            console.log(`[AgentRoutes] Comparison mode: current=${traceId}, reference=${referenceTraceId}`);
+        }
+        const quotaDecision = (0, enterpriseQuotaPolicyService_1.evaluateAnalysisRunQuota)(requestContext);
+        if (!quotaDecision.allowed) {
+            sendAgentQuotaDenied(res, quotaDecision);
+            return;
+        }
+        // Initialize tools
+        ensureToolsRegistered();
+        const analyzeSessionService = new agentAnalyzeSessionService_1.AgentAnalyzeSessionService({
+            assistantAppService,
+            createSessionLogger: sessionLogger_1.createSessionLogger,
+            sessionPersistenceService: sessionPersistenceService_1.SessionPersistenceService.getInstance(),
+            buildRecoveredResultFromContext,
+        });
+        let sessionId;
+        let preparedSession;
+        let isNewSession = true;
+        try {
+            const prepared = analyzeSessionService.prepareSession({
+                traceId,
+                query,
+                requestedSessionId,
+                referenceTraceId,
+                providerId,
+                providerScope: {
+                    tenantId: requestContext.tenantId,
+                    workspaceId: requestContext.workspaceId,
+                    userId: requestContext.userId,
+                },
+                options,
+            });
+            sessionId = prepared.sessionId;
+            preparedSession = prepared.session;
+            isNewSession = prepared.isNewSession;
+            if (isNewSession) {
+                assignSessionOwner(preparedSession, requestContext);
+            }
+            else if (!(0, resourceOwnership_1.isOwnedByContext)(preparedSession, requestContext)) {
+                (0, resourceOwnership_1.sendResourceNotFound)(res, 'Session not found');
+                return;
+            }
+        }
+        catch (error) {
+            if (error instanceof agentAnalyzeSessionService_1.AnalyzeSessionPreparationError) {
+                res.status(error.httpStatus).json({
+                    success: false,
+                    error: error.message,
+                    code: error.code,
+                    ...(error.hint ? { hint: error.hint } : {}),
+                });
+                return;
+            }
+            throw error;
+        }
+        const blockedStrategyIds = Array.from(new Set([
+            ...SCENE_STRATEGY_IDS,
+            ...(Array.isArray(options.blockedStrategyIds) ? options.blockedStrategyIds : []),
+        ]));
+        const sessionForRun = preparedSession || assistantAppService.getSession(sessionId);
+        if (!sessionForRun) {
+            throw new Error(`Session ${sessionId} not found after preparation`);
+        }
+        const effectiveReferenceTraceId = referenceTraceId || sessionForRun.referenceTraceId;
+        let effectiveReferenceTrace = requestedReferenceTrace;
+        if (effectiveReferenceTraceId) {
+            if (!effectiveReferenceTrace || effectiveReferenceTraceId !== referenceTraceId) {
+                effectiveReferenceTrace = await validateReferenceTraceForRun(effectiveReferenceTraceId);
+                if (!effectiveReferenceTrace)
+                    return;
+            }
+            sessionForRun.referenceTraceId = effectiveReferenceTraceId;
+            sessionForRun.comparisonSource = 'raw_trace_pair';
+        }
+        const runContext = startSessionRun(sessionForRun, query, requestId);
+        sessionForRun.logger.setMetadata({
+            requestId: runContext.requestId,
+            runId: runContext.runId,
+            runSequence: runContext.sequence,
+        });
+        let agentRunLease = null;
+        let referenceAgentRunLease = null;
+        let agentRunLeaseDecision = null;
+        let referenceAgentRunLeaseDecision = null;
+        if (enterpriseLeasesEnabled()) {
+            try {
+                const scope = leaseScopeFromRequestContext(requestContext);
+                agentRunLeaseDecision = buildLeaseModeDecisionForTrace(scope, traceId, 'agent_run', {
+                    analysisMode: options.analysisMode,
+                    traceSizeBytes: trace.size,
+                });
+                agentRunLease = (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)().acquireHolder(scope, traceId, {
+                    holderType: 'agent_run',
+                    holderRef: runContext.runId,
+                    runId: runContext.runId,
+                    sessionId,
+                    metadata: {
+                        requestId: runContext.requestId,
+                        runSequence: runContext.sequence,
+                        leaseModeReason: agentRunLeaseDecision.reason,
+                        leaseModeSignals: agentRunLeaseDecision.signals,
+                    },
+                }, { mode: agentRunLeaseDecision.mode });
+                agentRunLease = markLeaseReadyIfNew(agentRunLease, scope);
+                await traceProcessorService.ensureProcessorForLease(traceId, agentRunLease.id, agentRunLease.mode, scope);
+            }
+            catch (leaseError) {
+                if (agentRunLease) {
+                    try {
+                        (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)().markFailed(leaseScopeFromRequestContext(requestContext), agentRunLease.id);
+                    }
+                    catch (markFailedError) {
+                        console.warn(`[AgentRoutes] Failed to mark agent_run lease ${agentRunLease.id} failed: ${markFailedError.message}`);
+                    }
+                }
+                sessionForRun.status = 'failed';
+                sessionForRun.error = leaseError.message;
+                markSessionRunStatus(sessionForRun, 'failed', leaseError.message);
+                res.status(409).json({
+                    success: false,
+                    code: 'TRACE_PROCESSOR_LEASE_UNAVAILABLE',
+                    error: leaseError.message,
+                });
+                return;
+            }
+            if (effectiveReferenceTraceId) {
+                try {
+                    const scope = leaseScopeFromRequestContext(requestContext);
+                    referenceAgentRunLeaseDecision = buildLeaseModeDecisionForTrace(scope, effectiveReferenceTraceId, 'agent_run', {
+                        analysisMode: options.analysisMode,
+                        traceSizeBytes: effectiveReferenceTrace?.size,
+                    });
+                    referenceAgentRunLease = (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)().acquireHolder(scope, effectiveReferenceTraceId, {
+                        holderType: 'agent_run',
+                        holderRef: `${runContext.runId}:reference`,
+                        runId: runContext.runId,
+                        sessionId,
+                        metadata: {
+                            requestId: runContext.requestId,
+                            runSequence: runContext.sequence,
+                            traceSide: 'reference',
+                            leaseModeReason: referenceAgentRunLeaseDecision.reason,
+                            leaseModeSignals: referenceAgentRunLeaseDecision.signals,
+                        },
+                    }, { mode: referenceAgentRunLeaseDecision.mode });
+                    referenceAgentRunLease = markLeaseReadyIfNew(referenceAgentRunLease, scope);
+                    await traceProcessorService.ensureProcessorForLease(effectiveReferenceTraceId, referenceAgentRunLease.id, referenceAgentRunLease.mode, scope);
+                }
+                catch (leaseError) {
+                    if (referenceAgentRunLease) {
+                        try {
+                            (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)().markFailed(leaseScopeFromRequestContext(requestContext), referenceAgentRunLease.id);
+                        }
+                        catch (markFailedError) {
+                            console.warn(`[AgentRoutes] Failed to mark reference agent_run lease ${referenceAgentRunLease.id} failed: ${markFailedError.message}`);
+                        }
+                    }
+                    if (agentRunLease) {
+                        try {
+                            (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)().releaseHolder(leaseScopeFromRequestContext(requestContext), agentRunLease.id, 'agent_run', runContext.runId);
+                        }
+                        catch (releaseError) {
+                            console.warn(`[AgentRoutes] Failed to release current agent_run lease after reference lease failure ${agentRunLease.id}: ${releaseError.message}`);
+                        }
+                    }
+                    sessionForRun.status = 'failed';
+                    sessionForRun.error = leaseError.message;
+                    markSessionRunStatus(sessionForRun, 'failed', leaseError.message);
+                    res.status(409).json({
+                        success: false,
+                        code: 'REFERENCE_TRACE_PROCESSOR_LEASE_UNAVAILABLE',
+                        error: leaseError.message,
+                    });
+                    return;
+                }
+            }
+        }
+        // Validate traceContext — must be array of objects with columns/rows
+        const traceContext = Array.isArray(rawTraceContext)
+            ? rawTraceContext.filter((d) => d && typeof d === 'object' && Array.isArray(d.columns) && Array.isArray(d.rows))
+            : undefined;
+        runAgentDrivenAnalysis(sessionId, query, traceId, {
+            ...options,
+            selectionContext,
+            blockedStrategyIds,
+            traceProcessorService,
+            runContext,
+            referenceTraceId: effectiveReferenceTraceId,
+            traceContext: traceContext && traceContext.length > 0 ? traceContext : undefined,
+            providerId: sessionForRun.providerId !== undefined ? sessionForRun.providerId : providerId,
+            traceProcessorLease: agentRunLease
+                ? {
+                    traceId,
+                    leaseId: agentRunLease.id,
+                    mode: agentRunLease.mode,
+                    leaseScope: leaseScopeFromRequestContext(requestContext),
+                }
+                : undefined,
+            referenceTraceProcessorLease: referenceAgentRunLease && effectiveReferenceTraceId
+                ? {
+                    traceId: effectiveReferenceTraceId,
+                    leaseId: referenceAgentRunLease.id,
+                    mode: referenceAgentRunLease.mode,
+                    leaseScope: leaseScopeFromRequestContext(requestContext),
+                }
+                : undefined,
+        }).catch((error) => {
+            const session = assistantAppService.getSession(sessionId);
+            if (session) {
+                session.logger.error('AgentRoutes', 'Agent-driven analysis failed', error);
+                session.status = 'failed';
+                session.error = error.message;
+                markSessionRunStatus(session, 'failed', error.message);
+                broadcastToAgentDrivenClients(sessionId, {
+                    type: 'error',
+                    content: { message: error.message, error: error.message },
+                    timestamp: Date.now(),
+                });
+            }
+        }).finally(() => {
+            if (agentRunLease) {
+                try {
+                    (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)().releaseHolder(leaseScopeFromRequestContext(requestContext), agentRunLease.id, 'agent_run', runContext.runId);
+                }
+                catch (releaseError) {
+                    console.warn(`[AgentRoutes] Failed to release agent_run lease ${agentRunLease.id}: ${releaseError.message}`);
+                }
+            }
+            if (referenceAgentRunLease) {
+                try {
+                    (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)().releaseHolder(leaseScopeFromRequestContext(requestContext), referenceAgentRunLease.id, 'agent_run', `${runContext.runId}:reference`);
+                }
+                catch (releaseError) {
+                    console.warn(`[AgentRoutes] Failed to release reference agent_run lease ${referenceAgentRunLease.id}: ${releaseError.message}`);
+                }
+            }
+        });
+        res.json({
+            success: true,
+            sessionId,
+            message: preparedSession?.providerSnapshotChanged
+                ? 'Provider configuration changed; continuing with a fresh SDK session'
+                : isNewSession
+                    ? 'Analysis started'
+                    : 'Continuing analysis (multi-turn)',
+            isNewSession,
+            providerSnapshotChanged: preparedSession?.providerSnapshotChanged || undefined,
+            architecture: 'agent-driven',
+            runId: runContext.runId,
+            leaseId: agentRunLease?.id,
+            leaseState: agentRunLease?.state,
+            leaseMode: agentRunLease?.mode,
+            leaseModeReason: agentRunLeaseDecision?.reason,
+            leaseQueueLength: agentRunLeaseDecision?.signals.sharedQueueLength,
+            referenceLeaseId: referenceAgentRunLease?.id,
+            referenceLeaseState: referenceAgentRunLease?.state,
+            referenceLeaseMode: referenceAgentRunLease?.mode,
+            referenceLeaseModeReason: referenceAgentRunLeaseDecision?.reason,
+            requestId: runContext.requestId,
+            runSequence: runContext.sequence,
+            observability: {
+                runId: runContext.runId,
+                requestId: runContext.requestId,
+                runSequence: runContext.sequence,
+            },
+        });
+    }
+    catch (error) {
+        console.error('[AgentRoutes] Analyze error:', error);
+        res.status(500).json({
+            success: false,
+            error: error.message || 'Agent analysis failed',
+        });
+    }
+}
+router.post('/analyze', async (req, res) => {
+    await handleAnalyzeRequest(req, res);
+});
+router.post('/sessions/:sessionId/runs', async (req, res) => {
+    await handleAnalyzeRequest(req, res, req.params.sessionId);
+});
+/**
+ * GET /api/agent/v1/:sessionId/stream
+ *
+ * SSE endpoint for real-time analysis updates
+ *
+ * Events:
+ * - connected: SSE connection established
+ * - conversation_step: Ordered conversational timeline step
+ * - progress: Progress updates (task graph, rounds, strategy)
+ * - data: DataEnvelope(s) from skill execution
+ * - agent_task_dispatched: Task sent to domain agent
+ * - agent_response: Agent completed task
+ * - synthesis_complete: Feedback synthesis complete
+ * - strategy_decision: Next iteration strategy decided
+ * - analysis_completed: Final analysis result
+ * - error: Error occurred
+ * - end: Stream ended
+ */
+function handleSessionStream(req, res, sessionId) {
+    const session = getAuthorizedSession(req, res, sessionId);
+    if (!session)
+        return;
+    // Check for Last-Event-ID (reconnect replay support). The header is the
+    // canonical fetch-stream path; the query param is kept for older clients.
+    const lastEventId = (0, sessionSseReplay_1.parseLastEventId)(req.headers['last-event-id'], req.query.lastEventId);
+    streamProjector.setSseHeaders(res);
+    streamProjector.sendConnected(res, {
+        sessionId,
+        status: session.status,
+        traceId: session.traceId,
+        query: session.query,
+        architecture: 'agent-driven',
+        timestamp: Date.now(),
+        ...buildStreamObservability(session),
+    });
+    let ringReplayAfter = lastEventId;
+    if (lastEventId !== null) {
+        const persistedReplay = replayPersistedAgentEvents(session, res, lastEventId);
+        ringReplayAfter = persistedReplay.lastCursor;
+        if (persistedReplay.replayed > 0) {
+            console.log(`[AgentRoutes] Replayed ${persistedReplay.replayed} persisted SSE events for ${sessionId} ` +
+                `(after seqId ${lastEventId})`);
+        }
+        if (persistedReplay.includesTerminal) {
+            res.end();
+            return;
+        }
+    }
+    // Replay missed events from the ring buffer if reconnecting.
+    if (ringReplayAfter !== null && session.sseEventBuffer.length > 0) {
+        const replayIncludesTerminal = (0, sessionSseReplay_1.hasTerminalReplayAfter)(session, ringReplayAfter);
+        const replayed = streamProjector.replayBufferedEvents(res, session.sseEventBuffer, ringReplayAfter);
+        if (replayed > 0) {
+            console.log(`[AgentRoutes] Replayed ${replayed} missed SSE events for ${sessionId} (after seqId ${ringReplayAfter})`);
+        }
+        if (replayIncludesTerminal) {
+            res.end();
+            return;
+        }
+    }
+    // Add client to session
+    assistantAppService.addSseClient(sessionId, res);
+    console.log(`[AgentRoutes] SSE client connected for ${sessionId}`);
+    // If analysis is already completed, send the result.
+    // Resumed sessions may not have session.result in memory; recover from persisted turn context.
+    if (session.status === 'completed' || session.status === 'quota_exceeded') {
+        recoverResultForSessionIfNeeded(sessionId, session);
+        if (session.result) {
+            sendAgentDrivenResult(res, session);
+            sendReplayableSessionEvent(session, res, 'end', {
+                timestamp: Date.now(),
+                ...buildStreamObservability(session),
+            });
+            res.end();
+            return;
+        }
+    }
+    // If analysis failed, send error
+    if (session.status === 'failed') {
+        sendReplayableSessionEvent(session, res, 'error', {
+            error: session.error,
+            message: session.error,
+            timestamp: Date.now(),
+            ...buildStreamObservability(session),
+        });
+        sendReplayableSessionEvent(session, res, 'end', {
+            timestamp: Date.now(),
+            ...buildStreamObservability(session),
+        });
+        res.end();
+        return;
+    }
+    // Handle client disconnect
+    req.on('close', () => {
+        console.log(`[AgentRoutes] SSE client disconnected for ${sessionId}`);
+        assistantAppService.removeSseClient(sessionId, res);
+    });
+    // Handle write errors (EPIPE when client disconnects mid-write).
+    // Without this handler, EPIPE propagates as uncaughtException and can crash
+    // the SDK subprocess (which inherits the process's pipe state).
+    res.on('error', (err) => {
+        if (err.code === 'EPIPE' || err.code === 'ERR_STREAM_DESTROYED') {
+            // Expected when SSE client disconnects (e.g., curl timeout, browser navigation)
+            assistantAppService.removeSseClient(sessionId, res);
+            return;
+        }
+        console.error(`[AgentRoutes] SSE response error for ${sessionId}:`, err.message);
+    });
+    streamProjector.bindKeepAlive(req, res);
+}
+router.get('/:sessionId/stream', (req, res) => {
+    handleSessionStream(req, res, req.params.sessionId);
+});
+router.get('/runs/:runId/stream', (req, res) => {
+    const session = getAuthorizedSessionByRunId(req, res, req.params.runId);
+    if (!session)
+        return;
+    handleSessionStream(req, res, session.sessionId);
+});
+/**
+ * GET /api/agent/v1/:sessionId/status
+ *
+ * Get analysis status (for polling)
+ */
+router.get('/:sessionId/status', (req, res) => {
+    const { sessionId } = req.params;
+    const session = getAuthorizedSession(req, res, sessionId);
+    if (!session)
+        return;
+    const response = {
+        success: true,
+        sessionId,
+        status: session.status,
+        traceId: session.traceId,
+        query: session.query,
+        createdAt: session.createdAt,
+        observability: buildSessionObservability(session),
+    };
+    if (session.status === 'completed' || session.status === 'quota_exceeded') {
+        const recoveredResult = recoverResultForSessionIfNeeded(sessionId, session);
+        if (recoveredResult) {
+            const conclusion = normalizeNarrativeForClient(recoveredResult.conclusion);
+            const clientFindings = buildClientFindings(recoveredResult.findings, session.scenes || []);
+            const resultContract = buildSessionResultContract(session, clientFindings);
+            const sceneIdHint = resolveConclusionSceneIdHint({
+                sessionId,
+                query: session.query,
+                findings: recoveredResult.findings,
+            });
+            const conclusionContract = recoveredResult.conclusionContract ||
+                (0, agentResultNormalizer_1.deriveConclusionContractForNarrative)(recoveredResult.conclusion, {
+                    mode: recoveredResult.rounds > 1 ? 'focused_answer' : 'initial_report',
+                    sceneId: sceneIdHint,
+                }) ||
+                undefined;
+            response.result = {
+                answer: conclusion,
+                conclusion,
+                conclusionContract,
+                confidence: recoveredResult.confidence,
+                totalDurationMs: recoveredResult.totalDurationMs,
+                rounds: recoveredResult.rounds,
+                partial: recoveredResult.partial,
+                terminationReason: recoveredResult.terminationReason,
+                terminationMessage: recoveredResult.terminationMessage,
+                findings: recoveredResult.findings,
+                findingsCount: recoveredResult.findings.length,
+                resultContract,
+            };
+        }
+    }
+    if (session.status === 'failed') {
+        response.error = session.error;
+    }
+    res.json(response);
+});
+/**
+ * GET /api/agent/v1/:sessionId/turns
+ *
+ * List persisted turns for a session.
+ * Supports in-memory sessions and persisted (recoverable) sessions.
+ *
+ * Query params:
+ * - limit: default 20, max 200
+ * - offset: default 0
+ * - order: asc | desc (default desc)
+ */
+router.get('/:sessionId/turns', (req, res) => {
+    const { sessionId } = req.params;
+    const rawLimit = parseInt(String(req.query.limit || '20'), 10);
+    const rawOffset = parseInt(String(req.query.offset || '0'), 10);
+    const order = String(req.query.order || 'desc').toLowerCase() === 'asc' ? 'asc' : 'desc';
+    const limit = Number.isFinite(rawLimit) ? Math.max(1, Math.min(200, rawLimit)) : 20;
+    const offset = Number.isFinite(rawOffset) ? Math.max(0, rawOffset) : 0;
+    const resolved = resolveSessionContextForReview(sessionId);
+    if (!resolved) {
+        return res.status(404).json({
+            success: false,
+            error: 'Session context not found',
+            hint: 'Session may not exist or was not persisted with context snapshots',
+        });
+    }
+    if (!isResolvedSessionAccessible(req, resolved)) {
+        return (0, resourceOwnership_1.sendResourceNotFound)(res, 'Session context not found');
+    }
+    const allTurns = resolved.context.getAllTurns();
+    const ordered = order === 'desc' ? [...allTurns].reverse() : [...allTurns];
+    const paged = ordered.slice(offset, offset + limit);
+    const latestTurn = allTurns.length > 0 ? allTurns[allTurns.length - 1] : null;
+    return res.json({
+        success: true,
+        sessionId,
+        traceId: resolved.traceId,
+        source: resolved.source,
+        query: resolved.query,
+        createdAt: resolved.createdAt,
+        totalTurns: allTurns.length,
+        turns: paged.map(buildTurnSummary),
+        latestTurn: latestTurn ? buildTurnSummary(latestTurn) : null,
+        pagination: {
+            limit,
+            offset,
+            order,
+            hasMore: offset + limit < ordered.length,
+        },
+    });
+});
+/**
+ * GET /api/agent/v1/:sessionId/turns/:turnId
+ *
+ * Get details for a specific turn.
+ * `turnId` supports:
+ * - UUID turn ID
+ * - numeric turn index (0-based or 1-based)
+ * - literal `latest`
+ */
+router.get('/:sessionId/turns/:turnId', (req, res) => {
+    const { sessionId, turnId } = req.params;
+    const resolved = resolveSessionContextForReview(sessionId);
+    if (!resolved) {
+        return res.status(404).json({
+            success: false,
+            error: 'Session context not found',
+            hint: 'Session may not exist or was not persisted with context snapshots',
+        });
+    }
+    if (!isResolvedSessionAccessible(req, resolved)) {
+        return (0, resourceOwnership_1.sendResourceNotFound)(res, 'Session context not found');
+    }
+    const turns = resolved.context.getAllTurns();
+    if (turns.length === 0) {
+        return res.status(404).json({
+            success: false,
+            error: 'No turns recorded for this session',
+        });
+    }
+    let turn;
+    if (turnId === 'latest') {
+        turn = turns[turns.length - 1];
+    }
+    else {
+        turn = turns.find(t => t.id === turnId);
+        if (!turn && /^\d+$/.test(turnId)) {
+            const parsed = parseInt(turnId, 10);
+            turn = turns.find(t => t.turnIndex === parsed) || turns.find(t => t.turnIndex === parsed - 1);
+        }
+    }
+    if (!turn) {
+        return res.status(404).json({
+            success: false,
+            error: `Turn not found: ${turnId}`,
+            hint: 'Use /api/agent/v1/:sessionId/turns to inspect available turn IDs',
+        });
+    }
+    const previousTurn = turns.find(t => t.turnIndex === turn.turnIndex - 1) || null;
+    const nextTurn = turns.find(t => t.turnIndex === turn.turnIndex + 1) || null;
+    return res.json({
+        success: true,
+        sessionId,
+        traceId: resolved.traceId,
+        source: resolved.source,
+        turn: buildTurnDetail(turn),
+        navigation: {
+            previousTurnId: previousTurn?.id || null,
+            nextTurnId: nextTurn?.id || null,
+            previousTurnIndex: previousTurn?.turnIndex ?? null,
+            nextTurnIndex: nextTurn?.turnIndex ?? null,
+        },
+    });
+});
+/**
+ * DELETE /api/agent/v1/:sessionId
+ *
+ * Clean up an analysis session
+ */
+router.delete('/:sessionId', (req, res) => {
+    const { sessionId } = req.params;
+    const session = getAuthorizedSession(req, res, sessionId);
+    if (!session)
+        return;
+    // Close all SSE connections
+    session.sseClients.forEach((client) => {
+        try {
+            client.end();
+        }
+        catch { }
+    });
+    // Clean up session-scoped state only — do NOT call reset() which clears
+    // global caches (architectureCache) shared across all active sessions.
+    if (typeof session.orchestrator.cleanupSession === 'function') {
+        session.orchestrator.cleanupSession(sessionId);
+    }
+    // Also clean up the EnhancedSessionContext (EntityStore, turns, working memory)
+    enhancedSessionContext_1.sessionContextManager.remove(sessionId);
+    assistantAppService.deleteSession(sessionId);
+    res.json({ success: true });
+});
+const FEEDBACK_DIR = (0, runtimePaths_1.backendLogPath)('feedback');
+const FEEDBACK_FILE = path.join(FEEDBACK_DIR, 'feedback.jsonl');
+/**
+ * POST /api/agent/v1/:sessionId/feedback
+ *
+ * Submit user feedback on analysis quality (thumbs up/down + optional comment).
+ * Stored as append-only JSONL in logs/feedback/ with versioned schema
+ * (see backend/src/agentv3/selfImprove/feedbackEnricher.ts).
+ */
+router.post('/:sessionId/feedback', async (req, res) => {
+    const { sessionId } = req.params;
+    const validated = (0, feedbackEnricher_1.validateFeedbackInput)(req.body);
+    if (!validated.ok) {
+        return res.status(400).json({ success: false, error: validated.error });
+    }
+    const session = getAuthorizedSession(req, res, sessionId);
+    if (!session)
+        return;
+    const lookup = session
+        ? { traceId: session.traceId, referenceTraceId: session.referenceTraceId }
+        : null;
+    const entry = (0, feedbackEnricher_1.enrichFeedbackEntry)(sessionId, validated.value, lookup);
+    try {
+        fs.mkdirSync(FEEDBACK_DIR, { recursive: true });
+        fs.appendFileSync(FEEDBACK_FILE, JSON.stringify(entry) + '\n');
+    }
+    catch (err) {
+        console.error('[Feedback] Failed to save feedback:', err.message);
+        return res.status(500).json({ success: false, error: 'Failed to save feedback' });
+    }
+    // Feed the rating into the pattern state machine when the client
+    // identified the pattern. Best-effort: log and continue if it fails so
+    // the JSONL audit trail is the canonical record either way.
+    let patternStatusAfter = null;
+    if (validated.value.patternId) {
+        try {
+            patternStatusAfter = await (0, analysisPatternMemory_1.applyFeedbackToPattern)(validated.value.patternId, validated.value.rating);
+        }
+        catch (err) {
+            console.warn('[Feedback] Pattern state update failed:', err.message);
+        }
+    }
+    res.json({
+        success: true,
+        schemaVersion: entry.schemaVersion,
+        patternStatus: patternStatusAfter,
+    });
+});
+/**
+ * POST /api/agent/v1/:sessionId/respond
+ *
+ * Respond to an interactive session (e.g. continue/abort).
+ *
+ * Note: AgentRuntime currently does not pause for user input in v2;
+ * this endpoint mainly exists for API compatibility and future multi-turn UX.
+ */
+function handleSessionRespond(req, res, sessionId) {
+    const session = getAuthorizedSession(req, res, sessionId);
+    if (!session)
+        return;
+    const action = req.body?.action;
+    const allowedActions = new Set(['continue', 'abort']);
+    if (!action || typeof action !== 'string' || !allowedActions.has(action)) {
+        res.status(400).json({
+            success: false,
+            error: `Invalid action: ${String(action)}. Allowed: continue, abort`,
+        });
+        return;
+    }
+    if (action === 'abort') {
+        session.status = 'failed';
+        session.error = 'Aborted by user';
+        res.json({ success: true, sessionId, status: session.status });
+        return;
+    }
+    // continue
+    if (session.status !== 'awaiting_user') {
+        res.status(400).json({
+            success: false,
+            error: `Session is not awaiting user input (current status: ${session.status})`,
+        });
+        return;
+    }
+    session.status = 'running';
+    res.json({ success: true, sessionId, status: session.status });
+}
+router.post('/:sessionId/respond', (req, res) => {
+    handleSessionRespond(req, res, req.params.sessionId);
+});
+router.post('/sessions/:sessionId/respond', (req, res) => {
+    handleSessionRespond(req, res, req.params.sessionId);
+});
+// =============================================================================
+// Agent-Driven Architecture v2.0 - Intervention & Focus Endpoints
+// =============================================================================
+/**
+ * POST /api/agent/v1/:sessionId/intervene
+ *
+ * Handle user intervention response during analysis.
+ * Called when the frontend receives an 'intervention_required' event and
+ * the user selects an option.
+ *
+ * Request body:
+ * {
+ *   interventionId: string,    // ID from intervention_required event
+ *   action: 'continue' | 'focus' | 'abort' | 'custom' | 'select_option',
+ *   selectedOptionId?: string, // ID of selected option
+ *   customInput?: string,      // User's custom input (for action='custom')
+ *   params?: Record<string, any> // Additional parameters
+ * }
+ *
+ * Response:
+ * {
+ *   success: boolean,
+ *   sessionId: string,
+ *   directive?: AnalysisDirective  // How analysis should proceed
+ * }
+ */
+router.post('/:sessionId/intervene', async (req, res) => {
+    const { sessionId } = req.params;
+    const session = getAuthorizedSession(req, res, sessionId);
+    if (!session)
+        return;
+    const { interventionId, action, selectedOptionId, customInput, params } = req.body;
+    // Validate required fields
+    if (!interventionId || typeof interventionId !== 'string') {
+        return res.status(400).json({
+            success: false,
+            error: 'interventionId is required',
+        });
+    }
+    const allowedActions = new Set(['continue', 'focus', 'abort', 'custom', 'select_option']);
+    if (!action || !allowedActions.has(action)) {
+        return res.status(400).json({
+            success: false,
+            error: `Invalid action: ${String(action)}. Allowed: ${Array.from(allowedActions).join(', ')}`,
+        });
+    }
+    try {
+        // ClaudeRuntime (agentv3) doesn't implement getInterventionController — reject gracefully.
+        if (typeof session.orchestrator.getInterventionController !== 'function') {
+            return res.status(400).json({ success: false, error: 'Intervention not supported in this runtime mode' });
+        }
+        const interventionController = session.orchestrator.getInterventionController();
+        // Check if there's a pending intervention
+        if (!interventionController.hasPendingIntervention(sessionId)) {
+            return res.status(400).json({
+                success: false,
+                error: 'No pending intervention for this session',
+            });
+        }
+        // Build user decision
+        const decision = {
+            interventionId,
+            action,
+            selectedOptionId,
+            customInput,
+            params,
+        };
+        // Process the decision (interventionId is used internally to find the session)
+        const directive = interventionController.handleUserDecision(decision);
+        // Update session status if needed
+        if (directive.action === 'abort') {
+            session.status = 'failed';
+            session.error = 'Aborted by user intervention';
+        }
+        else if (session.status === 'awaiting_user') {
+            session.status = 'running';
+        }
+        return res.json({
+            success: true,
+            sessionId,
+            directive,
+        });
+    }
+    catch (error) {
+        console.error(`[Intervene] Error processing intervention for session ${sessionId}:`, error);
+        return res.status(500).json({
+            success: false,
+            error: error.message || 'Failed to process intervention',
+        });
+    }
+});
+/**
+ * POST /api/agent/v1/:sessionId/interaction
+ *
+ * Record user interaction from the frontend.
+ * Used to update the FocusStore for incremental analysis support.
+ *
+ * Request body:
+ * {
+ *   type: 'click' | 'query' | 'drill_down' | 'compare' | 'extend' | 'explicit',
+ *   target: {
+ *     entityType?: 'frame' | 'process' | 'thread' | 'session',
+ *     entityId?: string,
+ *     timeRange?: { start: string, end: string },  // ns as string
+ *     metricName?: string,
+ *     question?: string
+ *   },
+ *   context?: Record<string, any>  // Additional context
+ * }
+ *
+ * Response:
+ * {
+ *   success: boolean,
+ *   sessionId: string,
+ *   focusCount: number  // Current number of tracked focuses
+ * }
+ */
+// P1-4: Cancel endpoint — allows frontend to signal the backend to stop analysis
+router.post('/:sessionId/cancel', (req, res) => {
+    const { sessionId } = req.params;
+    const session = getAuthorizedSession(req, res, sessionId);
+    if (!session)
+        return;
+    // Mark session as failed/cancelled
+    if (session.status === 'running' || session.status === 'pending') {
+        session.status = 'failed';
+        session.error = 'Cancelled by user';
+        markSessionRunStatus(session, 'failed', 'Cancelled by user');
+        // Close SSE connections to signal the frontend
+        for (const client of session.sseClients) {
+            try {
+                sendReplayableSessionEvent(session, client, 'error', {
+                    error: 'Analysis cancelled by user',
+                    message: 'Analysis cancelled by user',
+                    timestamp: Date.now(),
+                    ...buildStreamObservability(session),
+                });
+                client.end();
+            }
+            catch { /* client may already be closed */ }
+        }
+        session.sseClients = [];
+        session.logger.info('AgentRoutes', 'Session cancelled by user', { sessionId });
+    }
+    return res.json({ success: true, sessionId, status: session.status });
+});
+router.post('/:sessionId/interaction', async (req, res) => {
+    const { sessionId } = req.params;
+    const session = getAuthorizedSession(req, res, sessionId);
+    if (!session)
+        return;
+    const { type, target, context } = req.body;
+    // Validate type
+    const allowedTypes = new Set(['click', 'query', 'drill_down', 'compare', 'extend', 'explicit']);
+    if (!type || !allowedTypes.has(type)) {
+        return res.status(400).json({
+            success: false,
+            error: `Invalid interaction type: ${String(type)}. Allowed: ${Array.from(allowedTypes).join(', ')}`,
+        });
+    }
+    // Validate target
+    if (!target || typeof target !== 'object') {
+        return res.status(400).json({
+            success: false,
+            error: 'target is required and must be an object',
+        });
+    }
+    try {
+        // Convert timeRange strings to BigInt if present
+        const processedTarget = { ...target };
+        if (target.timeRange) {
+            processedTarget.timeRange = {
+                start: BigInt(target.timeRange.start),
+                end: BigInt(target.timeRange.end),
+            };
+        }
+        // Build interaction
+        const interaction = {
+            type,
+            target: processedTarget,
+            source: 'ui',
+            timestamp: Date.now(),
+            context,
+        };
+        // Record the interaction — ClaudeRuntime (agentv3) doesn't implement these methods.
+        if (typeof session.orchestrator.recordUserInteraction === 'function') {
+            session.orchestrator.recordUserInteraction(interaction);
+            const focusStore = typeof session.orchestrator.getFocusStore === 'function'
+                ? session.orchestrator.getFocusStore()
+                : null;
+            const focusCount = focusStore ? focusStore.getTopFocuses(100).length : 0;
+            return res.json({ success: true, sessionId, focusCount });
+        }
+        return res.json({ success: true, sessionId, focusCount: 0 });
+    }
+    catch (error) {
+        console.error(`[Interaction] Error recording interaction for session ${sessionId}:`, error);
+        return res.status(500).json({
+            success: false,
+            error: error.message || 'Failed to record interaction',
+        });
+    }
+});
+/**
+ * GET /api/agent/v1/:sessionId/focus
+ *
+ * Get current user focus state for a session.
+ * Useful for debugging and displaying focus indicators in the UI.
+ *
+ * Query params:
+ * - limit: Max number of focuses to return (default: 10)
+ *
+ * Response:
+ * {
+ *   success: boolean,
+ *   sessionId: string,
+ *   focuses: UserFocus[],
+ *   context: string  // LLM-ready focus context summary
+ * }
+ */
+router.get('/:sessionId/focus', (req, res) => {
+    const { sessionId } = req.params;
+    const session = getAuthorizedSession(req, res, sessionId);
+    if (!session)
+        return;
+    try {
+        // ClaudeRuntime (agentv3) doesn't implement getFocusStore — return empty.
+        if (typeof session.orchestrator.getFocusStore !== 'function') {
+            return res.json({ success: true, sessionId, focuses: [], context: '' });
+        }
+        const limit = req.query.limit ? parseInt(req.query.limit, 10) : 10;
+        const focusStore = session.orchestrator.getFocusStore();
+        // Get top focuses
+        const focuses = focusStore.getTopFocuses(limit).map((f) => ({
+            id: f.id,
+            type: f.type,
+            target: {
+                ...f.target,
+                // Convert BigInt to string for JSON serialization
+                ...(f.target.timeRange && {
+                    timeRange: {
+                        start: String(f.target.timeRange.start),
+                        end: String(f.target.timeRange.end),
+                    },
+                }),
+            },
+            weight: f.weight,
+            lastInteractionTime: f.lastInteractionTime,
+            interactionCount: f.interactionHistory.length,
+        }));
+        // Get LLM-ready context
+        const context = focusStore.buildFocusContext();
+        return res.json({
+            success: true,
+            sessionId,
+            focuses,
+            context,
+        });
+    }
+    catch (error) {
+        console.error(`[Focus] Error getting focus for session ${sessionId}:`, error);
+        return res.status(500).json({
+            success: false,
+            error: error.message || 'Failed to get focus state',
+        });
+    }
+});
+(0, agentSessionCatalogRoutes_1.registerAgentSessionCatalogRoutes)(router, {
+    sessionStore: assistantAppService,
+    buildSessionObservability,
+});
+(0, agentResumeRoutes_1.registerAgentResumeRoutes)(router, {
+    sessionStore: assistantAppService,
+    buildSessionObservability,
+    buildRecoveredResultFromContext,
+    buildTurnSummary,
+});
+// ============================================================================
+// Scene Reconstruction Endpoints
+// ============================================================================
+// Scene-report cache layer singletons. The disk store backs file-backed
+// traces with a 7-day TTL; the memory LRU is the fallback for external RPC
+// traces (no content hash, so they live for the lifetime of the backend).
+const sceneReportStore = new sceneReportStore_1.FileSystemSceneReportStore(config_1.sceneStoryConfig.reportDir);
+const sceneReportMemoryCache = new sceneReportMemoryCache_1.SceneReportMemoryCache(config_1.sceneStoryConfig.memoryCacheMaxSize);
+// Singleton — sceneStoryService holds per-session JobRunner state for cancel
+// lookup, so it must outlive a single request. SkillExecutor is still created
+// per-request inside the route handler.
+const sceneStoryService = new sceneStoryService_1.SceneStoryService({
+    broadcast: broadcastToAgentDrivenClients,
+    getSession: (id) => assistantAppService.getSession(id),
+    reportStore: sceneReportStore,
+    memoryCache: sceneReportMemoryCache,
+    computeHash: (traceId) => (0, traceHash_1.computeTraceContentHash)((0, traceProcessorService_1.getTraceProcessorService)(), traceId),
+    probeDuration: (traceId) => (0, sceneTraceDurationProbe_1.probeTraceDuration)((0, traceProcessorService_1.getTraceProcessorService)(), traceId),
+});
+(0, agentSceneReconstructRoutes_1.registerSceneReconstructRoutes)(router, {
+    assistantAppService,
+    streamProjector,
+    ensureToolsRegistered,
+    runAgentDrivenAnalysis,
+    broadcastToAgentDrivenClients,
+    sendAgentDrivenResult,
+    isSceneReplayOnlyQuery,
+    buildSceneReplayNarrative,
+    normalizeNarrativeForClient,
+    sceneStoryService,
+});
+(0, agentQuickSceneRoutes_1.registerAgentQuickSceneRoutes)(router, {
+    detectScenesQuick,
+});
+// ============================================================================
+// Scene Detection Cache + Parallel Helpers
+// ============================================================================
+const sceneCache = new Map();
+const SCENE_CACHE_TTL = 10 * 60 * 1000; // 10 minutes
+const SCENE_EXTRACTION_STEP_IDS = new Set([
+    'screen_state_changes',
+    'app_launches',
+    'user_gestures',
+    'scroll_initiation',
+    'inertial_scrolls',
+    'idle_periods',
+    'top_app_changes',
+    'system_events',
+    'jank_events',
+    'clean_timeline',
+]);
+function objectRowsToEnvelopePayload(rows) {
+    if (!Array.isArray(rows) || rows.length === 0) {
+        return { columns: [], rows: [] };
+    }
+    const columns = [];
+    const seen = new Set();
+    for (const row of rows) {
+        if (!row || typeof row !== 'object')
+            continue;
+        for (const key of Object.keys(row)) {
+            if (!seen.has(key)) {
+                seen.add(key);
+                columns.push(key);
+            }
+        }
+    }
+    return {
+        columns,
+        rows: rows.map((row) => columns.map((col) => (row ? row[col] : null))),
+    };
+}
+function buildSceneExtractionEnvelopesFromRawResults(rawResults) {
+    const envelopes = [];
+    if (!rawResults || typeof rawResults !== 'object')
+        return envelopes;
+    for (const [stepId, stepResult] of Object.entries(rawResults)) {
+        if (!SCENE_EXTRACTION_STEP_IDS.has(stepId))
+            continue;
+        const rows = Array.isArray(stepResult?.data)
+            ? stepResult.data
+            : [];
+        if (rows.length === 0)
+            continue;
+        const payload = objectRowsToEnvelopePayload(rows);
+        if (payload.columns.length === 0)
+            continue;
+        envelopes.push((0, dataContract_1.createDataEnvelope)(payload, {
+            type: 'skill_result',
+            source: `scene_reconstruction.${stepId}`,
+            skillId: 'scene_reconstruction',
+            stepId,
+            title: stepId,
+            layer: 'list',
+            format: 'table',
+        }));
+    }
+    return envelopes;
+}
+/**
+ * Execute the state_timeline skill directly (bypasses Agent decision-making).
+ * Returns DataEnvelopes suitable for SSE broadcast and track overlay rendering.
+ * agentv3's ClaudeRuntime doesn't auto-execute strategy tasks, so this must be
+ * called explicitly from the scene reconstruction flow.
+ */
+async function executeStateTimelineSkill(traceProcessorService, traceId) {
+    await (0, skillLoader_1.ensureSkillRegistryInitialized)();
+    const skillExecutor = new skillExecutor_1.SkillExecutor(traceProcessorService);
+    skillExecutor.registerSkills(skillLoader_1.skillRegistry.getAllSkills());
+    const skillResult = await skillExecutor.execute('state_timeline', traceId, {
+        trace_id: traceId,
+    });
+    if (!skillResult.success) {
+        console.warn('[StateTimeline] state_timeline skill failed:', skillResult.error);
+        return [];
+    }
+    // Convert rawResults to DataEnvelopes (same pattern as scene_reconstruction)
+    const envelopes = [];
+    if (!skillResult.rawResults || typeof skillResult.rawResults !== 'object')
+        return envelopes;
+    for (const [stepId, stepResult] of Object.entries(skillResult.rawResults)) {
+        const rows = Array.isArray(stepResult?.data)
+            ? stepResult.data
+            : [];
+        if (rows.length === 0)
+            continue;
+        const payload = objectRowsToEnvelopePayload(rows);
+        if (payload.columns.length === 0)
+            continue;
+        envelopes.push((0, dataContract_1.createDataEnvelope)(payload, {
+            type: 'skill_result',
+            source: `state_timeline:${stepId}`,
+            skillId: 'state_timeline',
+            stepId,
+            title: stepId,
+            layer: 'list',
+            format: 'table',
+        }));
+    }
+    return envelopes;
+}
+async function detectScenesQuickViaSkill(traceProcessorService, traceId) {
+    await (0, skillLoader_1.ensureSkillRegistryInitialized)();
+    const skillExecutor = new skillExecutor_1.SkillExecutor(traceProcessorService);
+    skillExecutor.registerSkills(skillLoader_1.skillRegistry.getAllSkills());
+    const skillResult = await skillExecutor.execute('scene_reconstruction', traceId, {
+        trace_id: traceId,
+    });
+    if (!skillResult.success) {
+        throw new Error(skillResult.error || 'scene_reconstruction execution failed');
+    }
+    const envelopes = buildSceneExtractionEnvelopesFromRawResults(skillResult.rawResults);
+    return extractDetectedScenesFromEnvelopes(envelopes);
+}
+/** Detect app startups from android_startups stdlib view */
+async function detectStartups(tps, traceId) {
+    // Reclassify startup_type: platform may report 'warm' even when
+    // bindApplication exists (process killed + ActivityRecord survives).
+    const result = await tps.query(traceId, `
+    SELECT
+      s.ts,
+      s.dur,
+      s.package,
+      CASE
+        WHEN EXISTS (
+          SELECT 1 FROM android_startup_threads st
+          JOIN thread_track tt ON tt.utid = st.utid
+          JOIN slice sl ON sl.track_id = tt.id
+          WHERE st.startup_id = s.startup_id
+            AND st.is_main_thread = 1
+            AND sl.name = 'bindApplication'
+            AND sl.ts + sl.dur > st.ts AND sl.ts < st.ts + st.dur
+        ) THEN 'cold'
+        ELSE s.startup_type
+      END AS startup_type,
+      CAST(s.dur / 1000000 AS INT) AS dur_ms
+    FROM android_startups s
+    WHERE s.dur > 0
+    ORDER BY s.ts
+  `);
+    const scenes = [];
+    if (result.rows) {
+        for (const row of result.rows) {
+            const [ts, dur, pkg, startupType, durMs] = row;
+            let sceneType = 'cold_start';
+            if (startupType === 'warm')
+                sceneType = 'warm_start';
+            else if (startupType === 'hot')
+                sceneType = 'hot_start';
+            scenes.push({
+                type: sceneType,
+                startTs: String(ts),
+                endTs: String(BigInt(ts) + BigInt(dur)),
+                durationMs: Number(durMs),
+                confidence: 0.95,
+                appPackage: pkg,
+                metadata: { startupType },
+            });
+        }
+    }
+    return scenes;
+}
+/** Detect scroll sessions from input events + frame timeline */
+async function detectScrollSessions(tps, traceId) {
+    const scrollResult = await tps.query(traceId, `
+    WITH
+    input_exists AS (
+      SELECT 1 AS ok WHERE EXISTS (
+        SELECT 1 FROM sqlite_master WHERE type IN ('table','view') AND name = 'android_input_events'
+      )
+    ),
+    motion_events AS (
+      SELECT
+        read_time AS ts,
+        event_action
+      FROM android_input_events
+      WHERE event_type = 'MOTION'
+        AND EXISTS (SELECT ok FROM input_exists)
+    ),
+    gesture_markers AS (
+      SELECT
+        ts,
+        event_action,
+        SUM(CASE WHEN event_action = 'DOWN' THEN 1 ELSE 0 END) OVER (ORDER BY ts) AS gesture_id
+      FROM motion_events
+    ),
+    gestures AS (
+      SELECT
+        gesture_id,
+        MIN(ts) AS down_ts,
+        MAX(CASE WHEN event_action = 'UP' THEN ts ELSE NULL END) AS up_ts,
+        COUNT(*) AS event_count
+      FROM gesture_markers
+      WHERE gesture_id > 0
+      GROUP BY gesture_id
+      HAVING COUNT(*) >= 4
+    ),
+    frame_with_stats AS (
+      SELECT
+        ts,
+        dur,
+        ts + dur AS frame_end,
+        jank_type,
+        COALESCE(LEAD(ts) OVER (ORDER BY ts) - (ts + dur), 999999999) AS gap_to_next
+      FROM actual_frame_timeline_slice
+      WHERE surface_frame_token IS NOT NULL AND dur > 0
+    ),
+    scroll_sessions AS (
+      SELECT
+        g.gesture_id,
+        g.down_ts AS start_ts,
+        COALESCE(
+          (SELECT MIN(f.frame_end)
+           FROM frame_with_stats f
+           WHERE f.ts >= g.up_ts AND f.gap_to_next > 100000000),
+          g.up_ts + 500000000
+        ) AS end_ts
+      FROM gestures g
+      WHERE g.up_ts IS NOT NULL
+    )
+    SELECT
+      s.start_ts,
+      s.end_ts,
+      CAST((s.end_ts - s.start_ts) / 1000000 AS INT) AS dur_ms,
+      (SELECT COUNT(*) FROM frame_with_stats f WHERE f.ts >= s.start_ts AND f.frame_end <= s.end_ts) AS frame_count
+    FROM scroll_sessions s
+    WHERE s.end_ts > s.start_ts + 100000000
+    ORDER BY s.start_ts
+  `);
+    const scenes = [];
+    if (scrollResult.rows) {
+        for (const row of scrollResult.rows) {
+            const [startTs, endTs, durMs, frameCount] = row;
+            if (Number(frameCount) >= 3) {
+                const fps = (Number(frameCount) * 1000) / Math.max(Number(durMs), 1);
+                scenes.push({
+                    type: 'scroll',
+                    startTs: String(startTs),
+                    endTs: String(endTs),
+                    durationMs: Number(durMs),
+                    confidence: 0.85,
+                    metadata: {
+                        frameCount: Number(frameCount),
+                        averageFps: Math.round(fps * 10) / 10,
+                    },
+                });
+            }
+        }
+    }
+    return scenes;
+}
+/** Detect tap/click events from input events */
+async function detectTapEvents(tps, traceId) {
+    const tapResult = await tps.query(traceId, `
+    WITH
+    input_exists AS (
+      SELECT 1 AS ok WHERE EXISTS (
+        SELECT 1 FROM sqlite_master WHERE type IN ('table','view') AND name = 'android_input_events'
+      )
+    ),
+    motion_events AS (
+      SELECT
+        read_time AS ts,
+        event_action
+      FROM android_input_events
+      WHERE event_type = 'MOTION'
+        AND EXISTS (SELECT ok FROM input_exists)
+    ),
+    tap_events AS (
+      SELECT
+        ts AS down_ts,
+        LEAD(ts) OVER (ORDER BY ts) AS up_ts,
+        event_action
+      FROM motion_events
+      WHERE event_action IN ('DOWN', 'UP')
+    )
+    SELECT
+      down_ts AS start_ts,
+      up_ts AS end_ts,
+      CAST((up_ts - down_ts) / 1000000 AS INT) AS dur_ms
+    FROM tap_events
+    WHERE event_action = 'DOWN'
+      AND up_ts IS NOT NULL
+      AND (up_ts - down_ts) < 300000000
+    ORDER BY down_ts
+    LIMIT 50
+  `);
+    const scenes = [];
+    if (tapResult.rows) {
+        for (const row of tapResult.rows) {
+            const [startTs, endTs, durMs] = row;
+            scenes.push({
+                type: 'tap',
+                startTs: String(startTs),
+                endTs: String(endTs),
+                durationMs: Number(durMs),
+                confidence: 0.75,
+            });
+        }
+    }
+    return scenes;
+}
+/**
+ * Legacy quick scene detection path.
+ * Kept as fallback when skill-based extraction is unavailable.
+ */
+async function detectScenesQuickLegacy(traceProcessorService, traceId) {
+    // =========================================================================
+    // Pre-load Perfetto stdlib modules (parallel)
+    // =========================================================================
+    // `android_input_events` and `android_startups` are stdlib VIEWS, not
+    // intrinsic tables. They only exist after loading the corresponding modules.
+    const REQUIRED_MODULES = [
+        'android.input', // Creates android_input_events, android_key_events
+        'android.startup.startups', // Creates android_startups
+    ];
+    await Promise.all(REQUIRED_MODULES.map(module => traceProcessorService.query(traceId, `INCLUDE PERFETTO MODULE ${module};`)
+        .catch(e => console.warn(`[QuickSceneDetect] Module not available: ${module}`, e))));
+    // =========================================================================
+    // Run all 3 detection queries in parallel
+    // =========================================================================
+    const [startupResult, scrollResult, tapResult] = await Promise.allSettled([
+        detectStartups(traceProcessorService, traceId),
+        detectScrollSessions(traceProcessorService, traceId),
+        detectTapEvents(traceProcessorService, traceId),
+    ]);
+    // Merge results from fulfilled promises
+    const scenes = [];
+    if (startupResult.status === 'fulfilled') {
+        scenes.push(...startupResult.value);
+    }
+    else {
+        console.warn('[QuickSceneDetect] Startup detection failed:', startupResult.reason);
+    }
+    if (scrollResult.status === 'fulfilled') {
+        scenes.push(...scrollResult.value);
+    }
+    else {
+        console.warn('[QuickSceneDetect] Scroll detection failed:', scrollResult.reason);
+    }
+    if (tapResult.status === 'fulfilled') {
+        scenes.push(...tapResult.value);
+    }
+    else {
+        console.warn('[QuickSceneDetect] Tap detection failed:', tapResult.reason);
+    }
+    // Sort scenes by start timestamp
+    scenes.sort((a, b) => {
+        const aTs = BigInt(a.startTs);
+        const bTs = BigInt(b.startTs);
+        return aTs < bTs ? -1 : aTs > bTs ? 1 : 0;
+    });
+    return scenes;
+}
+async function detectScenesQuick(traceProcessorService, traceId) {
+    const cached = sceneCache.get(traceId);
+    if (cached && Date.now() - cached.timestamp < SCENE_CACHE_TTL) {
+        console.log('[QuickSceneDetect] Cache hit for traceId:', traceId);
+        return cached.scenes;
+    }
+    const t0 = Date.now();
+    let scenes = [];
+    try {
+        scenes = await detectScenesQuickViaSkill(traceProcessorService, traceId);
+        console.log(`[QuickSceneDetect] Skill extraction path returned ${scenes.length} scenes`);
+        if (scenes.length === 0) {
+            const legacyScenes = await detectScenesQuickLegacy(traceProcessorService, traceId);
+            if (legacyScenes.length > 0) {
+                console.log(`[QuickSceneDetect] Legacy fallback provided ${legacyScenes.length} scenes after empty skill extraction`);
+                scenes = legacyScenes;
+            }
+        }
+    }
+    catch (error) {
+        console.warn('[QuickSceneDetect] Skill extraction failed, falling back to legacy SQL path:', error?.message || error);
+        scenes = await detectScenesQuickLegacy(traceProcessorService, traceId);
+    }
+    scenes.sort((a, b) => {
+        const aTs = BigInt(a.startTs);
+        const bTs = BigInt(b.startTs);
+        return aTs < bTs ? -1 : aTs > bTs ? 1 : 0;
+    });
+    console.log(`[QuickSceneDetect] Completed in ${Date.now() - t0}ms, ${scenes.length} scenes`);
+    sceneCache.set(traceId, { scenes, timestamp: Date.now() });
+    return scenes;
+}
+// ============================================================================
+// Teaching Pipeline Endpoints
+// ============================================================================
+(0, agentTeachingRoutes_1.registerTeachingRoutes)(router);
+(0, agentReportRoutes_1.registerAgentReportRoutes)(router, {
+    getSession: (sessionId) => assistantAppService.getSession(sessionId),
+    recoverResultForSessionIfNeeded,
+    normalizeNarrativeForClient,
+    buildClientFindings,
+    buildSessionResultContract,
+});
+// ============================================================================
+// Agent-Driven Analysis Helper Functions (Phase 2-4)
+// ============================================================================
+async function runAgentDrivenAnalysis(sessionId, query, traceId, options = {}) {
+    const session = assistantAppService.getSession(sessionId);
+    if (!session)
+        return;
+    const inputRun = options.runContext;
+    if (inputRun) {
+        session.activeRun = {
+            ...inputRun,
+            query,
+            status: 'running',
+            startedAt: inputRun.startedAt || Date.now(),
+        };
+        session.lastRun = { ...session.activeRun };
+        session.runSequence = Math.max(normalizeRunSequence(session.runSequence), normalizeRunSequence(inputRun.sequence));
+    }
+    else if (!session.activeRun) {
+        const fallback = startSessionRun(session, query, generateRequestId());
+        session.activeRun = {
+            ...fallback,
+            status: 'running',
+        };
+        session.lastRun = { ...session.activeRun };
+    }
+    else {
+        session.activeRun.query = query;
+        session.activeRun.status = 'running';
+        if (!session.activeRun.startedAt) {
+            session.activeRun.startedAt = Date.now();
+        }
+        session.lastRun = { ...session.activeRun };
+    }
+    const { logger } = session;
+    session.status = 'running';
+    session.lastActivityAt = Date.now();
+    persistSessionRunState(session, 'running');
+    const runHeartbeatInterval = startSessionRunHeartbeat(session);
+    logger.info('AgentDrivenAnalysis', 'Starting agent-driven analysis', {
+        query,
+        traceId,
+        runId: session.activeRun?.runId,
+        requestId: session.activeRun?.requestId,
+        runSequence: session.activeRun?.sequence,
+    });
+    // Track generation is a lightweight derivation step from DataEnvelopes.
+    // Enable by default (unless explicitly disabled) so `/api/agent/v1/analyze` can
+    // also produce TrackEvent(s) when the scene reconstruction skill runs.
+    const shouldGenerateTracks = options.generateTracks !== false;
+    // Capture LLM call telemetry into session logs (privacy-safe: hashes + params only)
+    const modelRouter = (0, modelRouterSingleton_1.getSharedModelRouter)();
+    const onLlmTelemetry = (event) => {
+        if (!event || event.sessionId !== sessionId)
+            return;
+        logger.debug('LLM', 'llmTelemetry', event);
+    };
+    modelRouter.on('llmTelemetry', onLlmTelemetry);
+    const runWithTraceProcessorLease = (fn) => {
+        const leaseContexts = [
+            options.traceProcessorLease,
+            options.referenceTraceProcessorLease,
+        ].filter(Boolean);
+        if (leaseContexts.length > 1 && options.traceProcessorService?.runWithLeases) {
+            return options.traceProcessorService.runWithLeases(leaseContexts, fn);
+        }
+        if (leaseContexts.length === 1 && options.traceProcessorService?.runWithLease) {
+            return options.traceProcessorService.runWithLease(leaseContexts[0], fn);
+        }
+        return fn();
+    };
+    // Set up streaming via event listener on orchestrator
+    const handleUpdate = (update) => {
+        session.lastActivityAt = Date.now();
+        console.log(`[AgentRoutes.AgentDriven] Received event: ${update.type}`, update.content?.phase);
+        logger.debug('Stream', `Update: ${update.type}`, update.content);
+        const normalizedUpdate = augmentConclusionUpdateWithEvidenceIndex(session, normalizeAgentDrivenUpdate(update));
+        // Broadcast the original event so the frontend receives raw events
+        // (answer_token, thought, agent_response, conclusion, etc.) for rendering.
+        broadcastToAgentDrivenClients(sessionId, normalizedUpdate);
+        // Also derive a conversation_step for the timeline/observability layer.
+        const conversationStep = buildConversationStepUpdate(session, normalizedUpdate);
+        if (conversationStep) {
+            appendConversationStep(session, conversationStep);
+            broadcastToAgentDrivenClients(sessionId, conversationStep);
+        }
+        // Derive TrackEvent(s) for scene reconstruction sessions from emitted DataEnvelopes.
+        // This keeps the TrackEvent feature while unifying on the agent-driven architecture.
+        if (shouldGenerateTracks && normalizedUpdate.type === 'data') {
+            const envelopes = (Array.isArray(normalizedUpdate.content) ? normalizedUpdate.content : [normalizedUpdate.content])
+                .filter((e) => !!e && typeof e === 'object');
+            const changed = updateSceneReconstructionArtifactsFromEnvelopes(session, envelopes);
+            if (changed) {
+                broadcastToAgentDrivenClients(sessionId, {
+                    type: 'track_data',
+                    content: {
+                        tracks: session.trackEvents || [],
+                        scenes: session.scenes || [],
+                    },
+                    timestamp: update.timestamp,
+                    id: (0, dataContract_1.generateEventId)('track_data', sessionId),
+                });
+            }
+        }
+        // Track agent dialogue events
+        if (normalizedUpdate.content?.phase === 'task_dispatched' || normalizedUpdate.content?.phase === 'task_completed') {
+            pushWithSessionCap(session.agentDialogue, {
+                agentId: normalizedUpdate.content.agentId || 'master',
+                type: normalizedUpdate.content.phase === 'task_dispatched' ? 'task' : 'response',
+                content: normalizedUpdate.content,
+                timestamp: normalizedUpdate.timestamp,
+            }, MAX_SESSION_AGENT_DIALOGUE);
+            // Collect full agent responses for HTML report enrichment
+            if (normalizedUpdate.content.phase === 'task_completed') {
+                pushWithSessionCap(session.agentResponses, {
+                    taskId: normalizedUpdate.content.taskId || '',
+                    agentId: normalizedUpdate.content.agentId || 'unknown',
+                    response: normalizedUpdate.content.response || normalizedUpdate.content,
+                    timestamp: normalizedUpdate.timestamp,
+                }, MAX_SESSION_AGENT_RESPONSES);
+            }
+        }
+        // Broadcast specialized events for frontend visualization.
+        // Skip if the mapped type is the same as the original — agentv3 events
+        // (answer_token, thought, conclusion, etc.) are already broadcast above
+        // and remapping would cause duplicate delivery to the frontend.
+        const eventType = mapToAgentDrivenEventType(normalizedUpdate);
+        if (eventType !== normalizedUpdate.type) {
+            broadcastToAgentDrivenClients(sessionId, {
+                type: eventType,
+                content: normalizedUpdate.content,
+                timestamp: normalizedUpdate.timestamp,
+                id: normalizedUpdate.id,
+            });
+        }
+    };
+    // Listen to orchestrator events
+    if (session.orchestratorUpdateHandler) {
+        session.orchestrator.off('update', session.orchestratorUpdateHandler);
+    }
+    session.orchestratorUpdateHandler = handleUpdate;
+    session.orchestrator.on('update', handleUpdate);
+    // Run state_timeline skill in parallel with Agent analysis (fire-and-forget).
+    // Only execute when explicitly requested (e.g. scene reconstruction flow),
+    // NOT on every analyze call — raw state lane data needs LLM reasoning before display.
+    if (options.executeStateTimeline && options.traceProcessorService) {
+        runWithTraceProcessorLease(() => executeStateTimelineSkill(options.traceProcessorService, traceId))
+            .then((envelopes) => {
+            if (envelopes.length === 0)
+                return;
+            // Process envelopes through the same pipeline as Agent-produced data
+            const changed = updateSceneReconstructionArtifactsFromEnvelopes(session, envelopes);
+            // Broadcast each envelope as a 'data' event so frontend track_overlay picks it up
+            for (const env of envelopes) {
+                broadcastToAgentDrivenClients(sessionId, {
+                    type: 'data',
+                    content: env,
+                    timestamp: Date.now(),
+                    id: (0, dataContract_1.generateEventId)('data', sessionId),
+                });
+            }
+            if (changed) {
+                broadcastToAgentDrivenClients(sessionId, {
+                    type: 'track_data',
+                    content: { tracks: session.trackEvents || [], scenes: session.scenes || [] },
+                    timestamp: Date.now(),
+                    id: (0, dataContract_1.generateEventId)('track_data', sessionId),
+                });
+            }
+            logger.info('StateTimeline', 'State timeline lanes broadcast', {
+                laneCount: Object.keys(session.stateTimeline || {}).length,
+                envelopeCount: envelopes.length,
+            });
+        })
+            .catch((err) => {
+            logger.warn('StateTimeline', 'state_timeline skill failed (non-fatal)', {
+                error: String(err?.message || err),
+            });
+        });
+    }
+    try {
+        console.log('[AgentRoutes.AgentDriven] Starting orchestrator.analyze...');
+        const result = await logger.timed('AgentDrivenAnalysis', 'analyze', async () => {
+            const analyze = () => session.orchestrator.analyze(query, sessionId, traceId, {
+                traceProcessorService: options.traceProcessorService,
+                packageName: options.packageName,
+                timeRange: options.timeRange,
+                taskTimeoutMs: options.taskTimeoutMs,
+                blockedStrategyIds: options.blockedStrategyIds,
+                adb: options.adb,
+                selectionContext: options.selectionContext,
+                analysisMode: options.analysisMode,
+                traceContext: options.traceContext,
+                referenceTraceId: options.referenceTraceId,
+                providerId: options.providerId,
+                tenantId: session.tenantId,
+                workspaceId: session.workspaceId,
+                userId: session.userId,
+                runId: session.activeRun?.runId,
+            });
+            return runWithTraceProcessorLease(analyze);
+        });
+        console.log('[AgentRoutes.AgentDriven] analyze completed, success:', result.success);
+        session.result = result;
+        // Accumulate hypotheses across turns (deduplicate by id)
+        const existingIds = new Set(session.hypotheses.map(h => h.id));
+        for (const h of result.hypotheses) {
+            if (!existingIds.has(h.id)) {
+                session.hypotheses.push(h);
+            }
+            else {
+                // Update existing hypothesis with latest status
+                const idx = session.hypotheses.findIndex(eh => eh.id === h.id);
+                if (idx >= 0)
+                    session.hypotheses[idx] = h;
+            }
+        }
+        const terminalRunStatus = terminalRunStatusForResult(result);
+        session.status = terminalRunStatus === 'quota_exceeded'
+            ? 'quota_exceeded'
+            : result.success ? 'completed' : 'failed';
+        markSessionRunStatus(session, terminalRunStatus);
+        // Record conclusion in cross-turn history
+        if (!session.conclusionHistory)
+            session.conclusionHistory = [];
+        if (result.conclusion) {
+            session.conclusionHistory.push({
+                turn: session.runSequence || 1,
+                conclusion: result.conclusion,
+                confidence: result.confidence ?? 0,
+                timestamp: Date.now(),
+            });
+        }
+        // Ensure trackEvents/scenes are computed for completed sessions (even without SSE clients)
+        if (shouldGenerateTracks) {
+            updateSceneReconstructionArtifactsFromEnvelopes(session, session.dataEnvelopes);
+        }
+        if (session.referenceTraceId && options.traceProcessorService) {
+            session.comparisonSource = 'raw_trace_pair';
+            try {
+                session.comparisonReportSection = await runWithTraceProcessorLease(() => (0, comparisonAppendixService_1.buildRawTraceComparisonReportSection)(options.traceProcessorService, {
+                    currentTraceId: traceId,
+                    referenceTraceId: session.referenceTraceId,
+                }));
+            }
+            catch (comparisonSectionError) {
+                session.comparisonReportSection = {
+                    source: 'raw_trace_pair',
+                    title: 'SmartPerfetto 确定性对比附录',
+                    markdown: [
+                        '## SmartPerfetto 确定性对比附录',
+                        '',
+                        `- 固定 SQL 附录生成失败：${comparisonSectionError?.message || String(comparisonSectionError)}`,
+                        '',
+                    ].join('\n'),
+                    html: `<section class="smartperfetto-comparison-appendix"><h2>SmartPerfetto 确定性对比附录</h2><p>固定 SQL 附录生成失败：${escapeHtmlForInlineHtml(comparisonSectionError?.message || String(comparisonSectionError))}</p></section>`,
+                    limitations: [`固定 SQL 附录生成失败：${comparisonSectionError?.message || String(comparisonSectionError)}`],
+                };
+            }
+        }
+        // Log completion details
+        logger.info('AgentDrivenAnalysis', 'Agent-driven analysis completed', {
+            confidence: result.confidence,
+            rounds: result.rounds,
+            findingsCount: result.findings.length,
+            hypothesesCount: result.hypotheses.length,
+            partial: result.partial,
+            terminationReason: result.terminationReason,
+            runId: session.activeRun?.runId,
+            requestId: session.activeRun?.requestId,
+            runSequence: session.activeRun?.sequence,
+        });
+        // Persist session state via shared helper — see services/persistAgentSession.ts.
+        // CLI's cliAnalyzeService routes through the same function.
+        (0, persistAgentSession_1.persistAgentTurn)({
+            session,
+            sessionId,
+            traceId,
+            query,
+            result: { conclusion: result.conclusion, totalDurationMs: result.totalDurationMs },
+            logger,
+            // Preserve the legacy component label so any log filters / alerts keyed
+            // on 'AgentDrivenAnalysis' keep matching persist-related events.
+            logComponent: 'AgentDrivenAnalysis',
+        });
+        // Send final result
+        const clientCount = session.sseClients.length;
+        logger.info('AgentRoutes', 'Sending agent-driven result', { clientCount });
+        session.sseClients.forEach((client, index) => {
+            try {
+                logger.info('AgentRoutes', `Sending agent-driven result to client ${index + 1}/${clientCount}`);
+                sendAgentDrivenResult(client, session);
+                sendReplayableSessionEvent(session, client, 'end', {
+                    timestamp: Date.now(),
+                    ...buildStreamObservability(session),
+                });
+            }
+            catch (e) {
+                logger.error('AgentRoutes', `Error sending agent-driven result to client ${index + 1}`, e);
+            }
+        });
+        logger.close();
+    }
+    catch (error) {
+        session.status = 'failed';
+        session.error = error.message;
+        markSessionRunStatus(session, 'failed', error.message);
+        logger.error('AgentDrivenAnalysis', 'Agent-driven analysis failed', error);
+        broadcastToAgentDrivenClients(sessionId, {
+            type: 'error',
+            content: { message: error.message, error: error.message },
+            timestamp: Date.now(),
+        });
+        logger.close();
+        throw error;
+    }
+    finally {
+        if (runHeartbeatInterval) {
+            clearInterval(runHeartbeatInterval);
+        }
+        // Prevent listener accumulation across multi-turn requests in the same session.
+        if (session.orchestratorUpdateHandler) {
+            session.orchestrator.off('update', session.orchestratorUpdateHandler);
+            if (session.orchestratorUpdateHandler === handleUpdate) {
+                session.orchestratorUpdateHandler = undefined;
+            }
+        }
+        modelRouter.off('llmTelemetry', onLlmTelemetry);
+    }
+}
+function sanitizeConversationText(value, maxLen = 240) {
+    return String(value ?? '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, maxLen);
+}
+function escapeHtmlForInlineHtml(value) {
+    return String(value ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+function appendConversationStep(session, update) {
+    if (update.type !== 'conversation_step')
+        return;
+    const payload = update.content && typeof update.content === 'object' && !Array.isArray(update.content)
+        ? update.content
+        : {};
+    const contentRecord = payload.content && typeof payload.content === 'object' && !Array.isArray(payload.content)
+        ? payload.content
+        : {};
+    const text = sanitizeConversationText(contentRecord.text);
+    const ordinal = Number(payload.ordinal);
+    if (!text || !Number.isFinite(ordinal) || ordinal <= 0)
+        return;
+    const phaseRaw = sanitizeConversationText(payload.phase, 24);
+    const phase = ((phaseRaw === 'thinking' ||
+        phaseRaw === 'tool' ||
+        phaseRaw === 'result' ||
+        phaseRaw === 'error') ? phaseRaw : 'progress');
+    const roleRaw = sanitizeConversationText(payload.role, 16);
+    const role = roleRaw === 'system' ? 'system' : 'agent';
+    const eventId = sanitizeConversationText(payload.eventId, 128) ||
+        sanitizeConversationText(update.id, 128) ||
+        `conversation-step-${session.sessionId}-${ordinal}`;
+    if (session.conversationSteps.some((step) => step.eventId === eventId || step.ordinal === ordinal)) {
+        return;
+    }
+    session.conversationSteps.push({
+        eventId,
+        ordinal,
+        phase,
+        role,
+        text,
+        timestamp: typeof update.timestamp === 'number' && Number.isFinite(update.timestamp)
+            ? update.timestamp
+            : Date.now(),
+        sourceEventType: sanitizeConversationText(payload?.source?.eventType, 48) || undefined,
+    });
+    session.conversationSteps.sort((a, b) => a.ordinal - b.ordinal);
+    if (session.conversationSteps.length > 400) {
+        session.conversationSteps.splice(0, session.conversationSteps.length - 400);
+    }
+}
+function summarizeTimelineToolCall(content) {
+    const toolName = typeof content.toolName === 'string' ? content.toolName : '';
+    if (!toolName)
+        return '';
+    const generated = (0, toolNarration_1.formatToolCallNarration)(toolName, content.args);
+    const message = sanitizeConversationText(content.message);
+    if (!message || (0, toolNarration_1.looksLikeGenericToolMessage)(message)) {
+        return generated;
+    }
+    return message;
+}
+function summarizeTimelineResult(content) {
+    const candidates = [
+        content.summary,
+        content.message,
+        content.result,
+        content.output,
+    ];
+    for (const candidate of candidates) {
+        const text = sanitizeConversationText(candidate);
+        if (text)
+            return text;
+    }
+    return '';
+}
+function summarizeDataEnvelopeForTimeline(update) {
+    const envelopes = (Array.isArray(update.content) ? update.content : [update.content])
+        .filter((entry) => entry && typeof entry === 'object');
+    if (envelopes.length === 0)
+        return '';
+    const allTitles = envelopes
+        .map((env) => sanitizeConversationText(env?.display?.title || env?.meta?.stepId || env?.meta?.source))
+        .filter(Boolean);
+    const titles = allTitles.slice(0, 4);
+    const omittedTitleCount = Math.max(0, allTitles.length - titles.length);
+    const rows = envelopes
+        .map((env) => {
+        const data = env?.data;
+        return Array.isArray(data?.rows) ? data.rows.length : undefined;
+    })
+        .filter((rowCount) => typeof rowCount === 'number');
+    const rowText = rows.length > 0
+        ? `，共 ${rows.reduce((sum, rowCount) => sum + rowCount, 0)} 行`
+        : '';
+    const traceSides = [...new Set(envelopes
+            .map((env) => env?.meta?.traceSide || env?.traceSide || env?.traceProvenance?.traceSide)
+            .filter((side) => side === 'current' || side === 'reference'))];
+    const traceText = traceSides.length > 0
+        ? `，Trace: ${traceSides.map(side => side === 'reference' ? '参考' : '当前').join('/')}`
+        : '';
+    const evidenceRefs = envelopes
+        .map((env) => sanitizeConversationText(env?.meta?.evidenceRefId))
+        .filter(Boolean);
+    const evidenceText = evidenceRefs.length > 0
+        ? `，已登记 ${evidenceRefs.length} 个证据 ID`
+        : '';
+    const formats = [...new Set(envelopes
+            .map((env) => sanitizeConversationText(env?.display?.format, 24))
+            .filter(Boolean))];
+    const kindText = formats.length === 1
+        ? {
+            table: '数据表',
+            summary: '摘要数据',
+            metric: '指标数据',
+            chart: '图表数据',
+            text: '文本数据',
+            timeline: '时间线数据',
+        }[formats[0]] || '数据输出'
+        : '数据输出';
+    const planPhases = [...new Set(envelopes
+            .map((env) => sanitizeConversationText(env?.meta?.planPhaseTitle || env?.meta?.planPhaseId, 80))
+            .filter(Boolean))];
+    const phaseText = planPhases.length > 0
+        ? `，阶段: ${planPhases.slice(0, 2).join('/')}`
+        : '';
+    const phaseWarnings = [...new Set(envelopes
+            .map((env) => sanitizeConversationText(env?.meta?.planPhaseWarning, 120))
+            .filter(Boolean))];
+    const phaseWarningText = phaseWarnings.length > 0
+        ? `，阶段归因需核对: ${phaseWarnings.slice(0, 2).join('；')}`
+        : '';
+    const reasons = envelopes
+        .map((env) => sanitizeConversationText(env?.meta?.producerReason || env?.meta?.toolNarration, 180))
+        .filter(Boolean);
+    const uniqueReasons = [...new Set(reasons)].slice(0, 3);
+    const omittedReasonCount = Math.max(0, reasons.length - uniqueReasons.length);
+    const reasonText = uniqueReasons.length > 0
+        ? `：${uniqueReasons.join('；')}${omittedReasonCount > 0 ? `；另有 ${omittedReasonCount} 条原因` : ''}`
+        : '';
+    const titleText = titles.length > 0
+        ? `：${titles.join(' / ')}${omittedTitleCount > 0 ? ` / 另有 ${omittedTitleCount} 份` : ''}`
+        : '';
+    return `收到 ${envelopes.length} 份${kindText}${titleText}${rowText}${traceText}${phaseText}${phaseWarningText}${evidenceText}${reasonText || '，用于支撑后续诊断'}`;
+}
+function buildConversationStepUpdate(session, update) {
+    if (update.type === 'conversation_step')
+        return null;
+    const contentRecord = update.content && typeof update.content === 'object' && !Array.isArray(update.content)
+        ? update.content
+        : {};
+    let phase = 'progress';
+    let role = 'agent';
+    let text = '';
+    switch (update.type) {
+        case 'progress':
+        case 'degraded':
+        case 'stage_transition':
+        case 'round_start':
+        case 'strategy_decision':
+        case 'synthesis_complete':
+        case 'hypothesis_generated':
+            phase = 'progress';
+            role = 'system';
+            text =
+                sanitizeConversationText(contentRecord.message) ||
+                    sanitizeConversationText(contentRecord.fallback && `降级处理: ${contentRecord.fallback}`) ||
+                    sanitizeConversationText(contentRecord.reasoning) ||
+                    sanitizeConversationText(contentRecord.phase && `阶段: ${contentRecord.phase}`);
+            if (!text && update.type === 'hypothesis_generated' && Array.isArray(contentRecord.hypotheses)) {
+                text = `形成 ${contentRecord.hypotheses.length} 个待验证假设`;
+            }
+            break;
+        case 'thought':
+        case 'worker_thought':
+            phase = 'thinking';
+            role = update.type === 'worker_thought' ? 'system' : 'agent';
+            text =
+                sanitizeConversationText(contentRecord.thought) ||
+                    sanitizeConversationText(contentRecord.content) ||
+                    sanitizeConversationText(contentRecord.message);
+            break;
+        case 'tool_call':
+        case 'agent_task_dispatched':
+        case 'agent_dialogue':
+            phase = 'tool';
+            role = 'agent';
+            text =
+                summarizeTimelineToolCall(contentRecord) ||
+                    sanitizeConversationText(contentRecord.message) ||
+                    sanitizeConversationText(contentRecord.summary) ||
+                    sanitizeConversationText(contentRecord.taskTitle) ||
+                    sanitizeConversationText(contentRecord.toolName);
+            break;
+        case 'agent_response':
+        case 'finding':
+            phase = 'result';
+            role = 'agent';
+            if (update.type === 'finding' && Array.isArray(contentRecord.findings)) {
+                const firstFinding = contentRecord.findings.find((entry) => entry && typeof entry === 'object');
+                const firstTitle = sanitizeConversationText(firstFinding?.title || firstFinding?.description);
+                text = firstTitle
+                    ? `新增发现 ${contentRecord.findings.length} 条: ${firstTitle}`
+                    : `新增发现 ${contentRecord.findings.length} 条`;
+            }
+            else {
+                text =
+                    summarizeTimelineResult(contentRecord) ||
+                        (contentRecord.taskId ? `工具调用完成 (#${String(contentRecord.taskId).slice(-6)})` : '');
+            }
+            break;
+        case 'data': {
+            phase = 'result';
+            role = 'system';
+            text = summarizeDataEnvelopeForTimeline(update);
+            break;
+        }
+        case 'conclusion':
+            phase = 'result';
+            role = 'agent';
+            text =
+                sanitizeConversationText(contentRecord.summary) ||
+                    sanitizeConversationText(contentRecord.message) ||
+                    '最终结论已生成';
+            break;
+        case 'answer_token':
+            if (contentRecord.done === true) {
+                phase = 'result';
+                role = 'agent';
+                text = '最终回答生成完成';
+            }
+            break;
+        case 'error':
+            phase = 'error';
+            role = 'system';
+            text =
+                sanitizeConversationText(contentRecord.message) ||
+                    sanitizeConversationText(contentRecord.error) ||
+                    '分析过程中发生错误';
+            break;
+        default:
+            return null;
+    }
+    if (!text)
+        return null;
+    session.conversationOrdinal = (Number.isFinite(session.conversationOrdinal) ? session.conversationOrdinal : 0) + 1;
+    const ordinal = session.conversationOrdinal;
+    const eventId = (0, dataContract_1.generateEventId)('conversation_step', session.sessionId);
+    const metadata = {};
+    if (typeof contentRecord.round === 'number' && Number.isFinite(contentRecord.round)) {
+        metadata.round = contentRecord.round;
+    }
+    if (typeof contentRecord.strategyId === 'string' && contentRecord.strategyId.trim()) {
+        metadata.strategyId = contentRecord.strategyId.trim();
+    }
+    if (contentRecord.partial === true) {
+        metadata.partial = true;
+    }
+    if (typeof contentRecord.terminationReason === 'string' && contentRecord.terminationReason.trim()) {
+        metadata.terminationReason = contentRecord.terminationReason.trim();
+    }
+    if (session.activeRun?.runId) {
+        metadata.runId = session.activeRun.runId;
+    }
+    if (session.activeRun?.requestId) {
+        metadata.requestId = session.activeRun.requestId;
+    }
+    if (typeof session.activeRun?.sequence === 'number' && Number.isFinite(session.activeRun.sequence)) {
+        metadata.runSequence = session.activeRun.sequence;
+    }
+    return {
+        type: 'conversation_step',
+        id: eventId,
+        timestamp: update.timestamp || Date.now(),
+        content: {
+            eventId,
+            sessionId: session.sessionId,
+            traceId: session.traceId,
+            phase,
+            role,
+            ordinal,
+            content: {
+                text,
+            },
+            metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+            source: {
+                eventType: update.type,
+                phase: typeof contentRecord.phase === 'string' ? contentRecord.phase : undefined,
+            },
+        },
+    };
+}
+/**
+ * Normalize orchestrator updates before mapping/broadcasting
+ */
+function normalizeAgentDrivenUpdate(update) {
+    const rawContent = update.content;
+    if (!rawContent || typeof rawContent !== 'object' || Array.isArray(rawContent)) {
+        return update;
+    }
+    const content = { ...rawContent };
+    if (update.type === 'stage_transition') {
+        const stageName = typeof content.stageName === 'string' ? content.stageName : 'unknown';
+        const hasStageIndex = typeof content.stageIndex === 'number' && Number.isFinite(content.stageIndex);
+        const hasTotalStages = typeof content.totalStages === 'number' && Number.isFinite(content.totalStages) && content.totalStages > 0;
+        const skipped = content.skipped === true;
+        const skipReason = typeof content.skipReason === 'string' ? content.skipReason.trim() : '';
+        const stageSeq = hasStageIndex && hasTotalStages
+            ? ` (${content.stageIndex + 1}/${content.totalStages})`
+            : '';
+        if (typeof content.phase !== 'string' || !content.phase.trim()) {
+            content.phase = 'stage_transition';
+        }
+        if (typeof content.message !== 'string' || !content.message.trim()) {
+            const prefix = skipped ? '跳过阶段' : '进入阶段';
+            const reason = skipped && skipReason ? `: ${skipReason}` : '';
+            content.message = `${prefix} ${stageName}${stageSeq}${reason}`;
+        }
+    }
+    if (update.type === 'tool_call') {
+        const phase = typeof content.phase === 'string' ? content.phase : '';
+        const phaseLower = phase.toLowerCase();
+        const isDone = phaseLower.includes('completed') || phaseLower.includes('done') || phaseLower.includes('finished');
+        if (typeof content.phase !== 'string' || !content.phase.trim()) {
+            content.phase = isDone ? 'task_completed' : 'task_dispatched';
+        }
+        if (typeof content.message !== 'string' || !content.message.trim()) {
+            const taskTitle = typeof content.taskTitle === 'string' ? content.taskTitle : '';
+            const toolName = typeof content.toolName === 'string' ? content.toolName : '';
+            const displayName = taskTitle || toolName || '工具任务';
+            content.message = isDone ? `完成 ${displayName}` : `调用 ${displayName}`;
+        }
+    }
+    return {
+        ...update,
+        content,
+    };
+}
+function mapToAgentDrivenEventType(update) {
+    const phase = update.content?.phase;
+    if (update.type === 'conversation_step') {
+        return 'conversation_step';
+    }
+    if (update.type === 'stage_transition') {
+        return 'progress';
+    }
+    if (update.type === 'tool_call') {
+        const phaseText = typeof phase === 'string' ? phase.toLowerCase() : '';
+        const isComplete = phaseText.includes('completed') || phaseText.includes('done') || phaseText.includes('finished');
+        return isComplete ? 'agent_response' : 'agent_dialogue';
+    }
+    switch (phase) {
+        case 'starting':
+        case 'understanding':
+            return 'progress';
+        case 'hypotheses_generated':
+            return 'hypothesis_generated';
+        case 'round_start':
+            return 'round_start';
+        case 'tasks_dispatched':
+            return 'agent_task_dispatched';
+        case 'task_dispatched':
+            return 'agent_dialogue';
+        case 'task_completed':
+            return 'agent_response';
+        case 'synthesis_complete':
+            return 'synthesis_complete';
+        case 'strategy_decision':
+            return 'strategy_decision';
+        case 'concluding':
+            return 'progress';
+        default:
+            return update.type;
+    }
+}
+/**
+ * Broadcast update to all SSE clients for an agent-driven session
+ */
+function broadcastToAgentDrivenClients(sessionId, update) {
+    const session = assistantAppService.getSession(sessionId);
+    if (!session)
+        return;
+    session.lastActivityAt = Date.now();
+    // F3: Assign monotonic sequence ID for replay on reconnect
+    const seqId = ++session.sseEventSeq;
+    streamProjector.broadcastStreamingUpdate(sessionId, session.sseClients, update, {
+        observability: buildStreamObservability(session),
+        seqId,
+        onBufferedEvent: (event) => {
+            session.sseEventBuffer.push(event);
+            persistBufferedAgentEvent(session, {
+                cursor: event.seqId,
+                eventType: event.eventType,
+                eventData: event.eventData,
+                createdAt: Date.now(),
+            });
+            // Trim ring buffer to cap
+            if (session.sseEventBuffer.length > streamProjector_1.SSE_RING_BUFFER_SIZE) {
+                session.sseEventBuffer.splice(0, session.sseEventBuffer.length - streamProjector_1.SSE_RING_BUFFER_SIZE);
+            }
+        },
+        onDataEnvelopeValidationWarning: (payload) => {
+            console.warn(`[AgentRoutes.broadcastToAgentDrivenClients] DataEnvelope validation warning (envelope ${payload.envelopeIndex}):`, {
+                sessionId: payload.sessionId,
+                errors: payload.errors.slice(0, 5),
+                totalErrors: payload.errors.length,
+                envelope: payload.envelope,
+            });
+        },
+        onValidDataEnvelopes: (validEnvelopes) => {
+            if (validEnvelopes.length > 0) {
+                console.log(`[AgentRoutes.broadcastToAgentDrivenClients] Sending ${validEnvelopes.length} DataEnvelope(s) for session ${sessionId}`);
+                // P2-4: Tag envelopes with current turn number for multi-turn attribution
+                const turnNumber = session.runSequence || 1;
+                for (const env of validEnvelopes) {
+                    if (env.meta)
+                        env.meta.turn = turnNumber;
+                }
+                session.dataEnvelopes.push(...validEnvelopes);
+                trimSessionArray(session.dataEnvelopes, MAX_SESSION_DATA_ENVELOPES);
+            }
+        },
+    });
+}
+// =============================================================================
+// Scene Reconstruction: Derive scenes + TrackEvent(s) from DataEnvelopes
+// =============================================================================
+const SCENE_DISPLAY_NAMES = {
+    cold_start: '冷启动',
+    warm_start: '温启动',
+    hot_start: '热启动',
+    scroll_start: '滑动启动',
+    scroll: '滑动',
+    inertial_scroll: '惯性滑动',
+    navigation: '跳转',
+    app_switch: '应用切换',
+    home_screen: '桌面',
+    app_foreground: '应用内',
+    screen_on: '屏幕点亮',
+    screen_off: '屏幕熄灭',
+    screen_sleep: '屏幕休眠',
+    screen_unlock: '解锁屏幕',
+    notification: '通知操作',
+    split_screen: '分屏操作',
+    tap: '点击',
+    long_press: '长按',
+    idle: '空闲',
+    jank_region: '性能问题区间',
+    back_key: '返回键',
+    home_key: 'Home键',
+    recents_key: '最近任务键',
+    anr: 'ANR',
+    ime_show: '键盘弹出',
+    ime_hide: '键盘收起',
+    window_transition: '窗口转场',
+};
+const SCENE_COLOR_SCHEMES = {
+    cold_start: 'launch',
+    warm_start: 'launch',
+    hot_start: 'launch',
+    scroll_start: 'scroll',
+    scroll: 'scroll',
+    inertial_scroll: 'scroll',
+    navigation: 'navigation',
+    app_switch: 'system',
+    home_screen: 'system',
+    app_foreground: 'system',
+    screen_on: 'system',
+    screen_off: 'system',
+    screen_sleep: 'system',
+    screen_unlock: 'system',
+    notification: 'system',
+    split_screen: 'system',
+    tap: 'tap',
+    long_press: 'tap',
+    idle: 'system',
+    jank_region: 'jank', // Use jank color to highlight performance issues
+    back_key: 'system',
+    home_key: 'system',
+    recents_key: 'system',
+    anr: 'jank',
+    ime_show: 'system',
+    ime_hide: 'system',
+    window_transition: 'navigation',
+};
+/** Lane step IDs from state_timeline skill */
+const STATE_LANE_STEP_IDS = new Set([
+    'device_state_lane',
+    'device_state_lane_fallback',
+    'input_state_lane_frames',
+    'input_state_lane_fallback',
+    'app_state_lane',
+    'app_state_lane_fallback',
+    'system_state_lane',
+]);
+/** Map stepId → lane name */
+const STEP_TO_LANE = {
+    device_state_lane: 'device',
+    device_state_lane_fallback: 'device',
+    input_state_lane_frames: 'input',
+    input_state_lane_fallback: 'input',
+    app_state_lane: 'app',
+    app_state_lane_fallback: 'app',
+    system_state_lane: 'system',
+};
+const VALID_LANE_STATUSES = new Set(['available', 'available_frame_based', 'available_heuristic', 'table_missing', 'no_data']);
+/** Statuses indicating data is expected (table exists, may have rows). */
+const DATA_PRESENT_STATUSES = new Set(['available', 'available_frame_based', 'available_heuristic']);
+/**
+ * Single-pass extraction of state timeline lanes + lane availability from DataEnvelopes.
+ * Combines what would otherwise be two separate iterations over the same envelope array.
+ */
+function extractStateTimelineData(envelopes) {
+    const timeline = {};
+    const availability = {};
+    for (const env of envelopes) {
+        if (!env || env.meta?.skillId !== 'state_timeline')
+            continue;
+        const stepId = env.meta.stepId || '';
+        // Lane summary → extract availability
+        if (stepId === 'lane_summary') {
+            const rows = payloadToObjectRowsLocal(env.data);
+            for (const row of rows) {
+                const lane = String(row.lane || '');
+                const status = String(row.source_status || 'available');
+                if (lane) {
+                    availability[lane] = VALID_LANE_STATUSES.has(status) ? status : 'available';
+                }
+            }
+            continue;
+        }
+        // Lane data steps → extract segments
+        if (!STATE_LANE_STEP_IDS.has(stepId))
+            continue;
+        const laneName = STEP_TO_LANE[stepId] || stepId;
+        // Real data over fallback: conditions are mutually exclusive, but be safe.
+        const isFallbackStep = stepId.endsWith('_fallback');
+        if (isFallbackStep && timeline[laneName]?.length > 0) {
+            continue;
+        }
+        const rows = payloadToObjectRowsLocal(env.data);
+        if (rows.length === 0)
+            continue;
+        const segments = [];
+        for (const row of rows) {
+            const startTs = String(row.start_ts || '');
+            const endTs = String(row.end_ts || '');
+            const durMs = Number(row.dur_ms || 0);
+            if (!startTs || !endTs || durMs <= 0)
+                continue;
+            segments.push({
+                lane: laneName,
+                state: String(row.state || 'UNKNOWN'),
+                stateLabel: String(row.state_label || ''),
+                startTs,
+                endTs,
+                durMs,
+                sourceStatus: String(row.source_status || 'available'),
+                confidence: row.confidence ? String(row.confidence) : undefined,
+            });
+        }
+        if (segments.length > 0) {
+            timeline[laneName] = segments;
+        }
+    }
+    // Reconcile: if a lane has segments, it's available; if lane_summary said
+    // 'available' but we got no segments, it's really 'no_data'.
+    for (const lane of [...new Set(Object.values(STEP_TO_LANE))]) {
+        if (timeline[lane] && timeline[lane].length > 0) {
+            // Has real data — check if it's all UNKNOWN (empty-source fallback)
+            const allUnknown = timeline[lane].every(s => s.state === 'UNKNOWN' || s.state === 'IDLE');
+            if (!availability[lane]) {
+                availability[lane] = allUnknown ? 'no_data' : 'available';
+            }
+        }
+        else if (DATA_PRESENT_STATUSES.has(availability[lane])) {
+            // lane_summary said available, but no segments arrived → no_data
+            availability[lane] = 'no_data';
+        }
+    }
+    return { timeline, availability };
+}
+function updateSceneReconstructionArtifactsFromEnvelopes(session, envelopes) {
+    if (!Array.isArray(envelopes) || envelopes.length === 0)
+        return false;
+    // Extract scene events (from scene_reconstruction skill)
+    const extractedScenes = extractDetectedScenesFromEnvelopes(envelopes);
+    // Extract state timeline + lane availability in a single pass
+    const { timeline, availability } = extractStateTimelineData(envelopes);
+    let hasTimelineUpdate = false;
+    if (Object.keys(timeline).length > 0) {
+        session.stateTimeline = Object.assign(session.stateTimeline || {}, timeline);
+        hasTimelineUpdate = true;
+    }
+    if (Object.keys(availability).length > 0) {
+        session.laneAvailability = Object.assign(session.laneAvailability || {}, availability);
+    }
+    if (extractedScenes.length === 0)
+        return hasTimelineUpdate;
+    const mergedScenes = mergeDetectedScenes(session.scenes || [], extractedScenes);
+    const mergedTracks = buildTrackEventsFromScenes(mergedScenes);
+    const prevFingerprint = fingerprintTrackEvents(session.trackEvents || []);
+    const nextFingerprint = fingerprintTrackEvents(mergedTracks);
+    session.scenes = mergedScenes;
+    session.trackEvents = mergedTracks;
+    return prevFingerprint !== nextFingerprint;
+}
+function extractDetectedScenesFromEnvelopes(envelopes) {
+    const scenes = [];
+    const jankRowsForFallback = [];
+    for (const env of envelopes) {
+        if (!env || env.meta?.skillId !== 'scene_reconstruction')
+            continue;
+        const stepId = env.meta.stepId || '';
+        const rows = payloadToObjectRowsLocal(env.data);
+        if (rows.length === 0)
+            continue;
+        // Step: screen_state_changes (screen on/off/sleep)
+        if (stepId === 'screen_state_changes') {
+            for (const row of rows) {
+                const startTs = normalizeNs(row.ts);
+                const durNs = toBigInt(row.dur);
+                if (!startTs || durNs === null)
+                    continue;
+                const eventText = String(row.event || '');
+                const type = mapScreenStateEventToSceneType(eventText);
+                if (!type)
+                    continue;
+                const startNs = BigInt(startTs);
+                const endNs = startNs + durNs;
+                const durationMs = Number(durNs / 1000000n);
+                scenes.push({
+                    type,
+                    startTs,
+                    endTs: endNs.toString(),
+                    durationMs,
+                    confidence: 0.9,
+                    metadata: {
+                        source: 'scene_reconstruction:screen_state_changes',
+                        event: eventText,
+                    },
+                });
+            }
+            continue;
+        }
+        // Step: app_launches (startup events)
+        if (stepId === 'app_launches') {
+            for (const row of rows) {
+                const startTs = normalizeNs(row.ts);
+                const durNs = toBigInt(row.dur);
+                if (!startTs || durNs === null)
+                    continue;
+                const startupType = String(row.startup_type || '').toLowerCase();
+                const type = startupType === 'warm' ? 'warm_start'
+                    : startupType === 'hot' ? 'hot_start'
+                        : 'cold_start';
+                const startNs = BigInt(startTs);
+                const endNs = startNs + durNs;
+                const durationMs = Number(durNs / 1000000n);
+                scenes.push({
+                    type,
+                    startTs: startTs,
+                    endTs: endNs.toString(),
+                    durationMs,
+                    confidence: 0.95,
+                    appPackage: extractRowAppPackage(row, ['package']),
+                    metadata: {
+                        source: 'scene_reconstruction:app_launches',
+                        startupType: startupType || undefined,
+                        event: row.event,
+                    },
+                });
+            }
+            continue;
+        }
+        // Step: user_gestures (tap/scroll/long_press)
+        if (stepId === 'user_gestures') {
+            for (const row of rows) {
+                const startTs = normalizeNs(row.ts);
+                const durNs = toBigInt(row.dur);
+                if (!startTs || durNs === null)
+                    continue;
+                const gestureType = String(row.gesture_type || '').toLowerCase();
+                const type = gestureType === 'scroll' ? 'scroll'
+                    : gestureType === 'long_press' ? 'long_press'
+                        : 'tap';
+                const startNs = BigInt(startTs);
+                const endNs = startNs + durNs;
+                const durationMs = Number(durNs / 1000000n);
+                scenes.push({
+                    type,
+                    startTs: startTs,
+                    endTs: endNs.toString(),
+                    durationMs,
+                    confidence: confidenceToScore(row.confidence),
+                    appPackage: extractRowAppPackage(row),
+                    metadata: {
+                        source: 'scene_reconstruction:user_gestures',
+                        moveCount: row.move_count,
+                        event: row.event,
+                    },
+                });
+            }
+            continue;
+        }
+        // Step: scroll_initiation (precise scroll start marker)
+        if (stepId === 'scroll_initiation') {
+            for (const row of rows) {
+                const startTs = normalizeNs(row.ts);
+                const durNs = toBigInt(row.dur);
+                if (!startTs || durNs === null)
+                    continue;
+                const startNs = BigInt(startTs);
+                const endNs = startNs + durNs;
+                const durationMs = Number(durNs / 1000000n);
+                scenes.push({
+                    type: 'scroll_start',
+                    startTs,
+                    endTs: endNs.toString(),
+                    durationMs,
+                    confidence: 0.9,
+                    appPackage: extractRowAppPackage(row, ['app']),
+                    metadata: {
+                        source: 'scene_reconstruction:scroll_initiation',
+                        gestureId: row.gesture_id,
+                        event: row.event,
+                        explanation: row.explanation,
+                    },
+                });
+            }
+            continue;
+        }
+        // Step: inertial_scrolls (fling inertia region after finger up)
+        if (stepId === 'inertial_scrolls') {
+            for (const row of rows) {
+                const startTs = normalizeNs(row.ts);
+                const durNs = toBigInt(row.dur);
+                if (!startTs || durNs === null)
+                    continue;
+                const startNs = BigInt(startTs);
+                const endNs = startNs + durNs;
+                const durationMs = Number(durNs / 1000000n);
+                const frameCount = Number(row.frame_count || 0);
+                scenes.push({
+                    type: 'inertial_scroll',
+                    startTs: startTs,
+                    endTs: endNs.toString(),
+                    durationMs,
+                    confidence: frameCount >= 12 ? 0.9 : frameCount >= 8 ? 0.8 : 0.7,
+                    appPackage: extractRowAppPackage(row),
+                    metadata: {
+                        source: 'scene_reconstruction:inertial_scrolls',
+                        frameCount,
+                        jankFrames: Number(row.jank_frames || 0),
+                        event: row.event,
+                    },
+                });
+            }
+            continue;
+        }
+        // Step: idle_periods (no obvious operation gap)
+        if (stepId === 'idle_periods') {
+            for (const row of rows) {
+                const startTs = normalizeNs(row.ts);
+                const durNs = toBigInt(row.dur);
+                if (!startTs || durNs === null)
+                    continue;
+                const startNs = BigInt(startTs);
+                const endNs = startNs + durNs;
+                const durationMs = Number(durNs / 1000000n);
+                scenes.push({
+                    type: 'idle',
+                    startTs: startTs,
+                    endTs: endNs.toString(),
+                    durationMs,
+                    confidence: confidenceToScore(row.confidence),
+                    metadata: {
+                        source: 'scene_reconstruction:idle_periods',
+                        event: row.event,
+                    },
+                });
+            }
+            continue;
+        }
+        // Step: top_app_changes (app switches)
+        if (stepId === 'top_app_changes') {
+            for (const row of rows) {
+                const startTs = normalizeNs(row.ts);
+                const durNs = toBigInt(row.dur);
+                if (!startTs || durNs === null)
+                    continue;
+                const startNs = BigInt(startTs);
+                const endNs = startNs + durNs;
+                const durationMs = Number(durNs / 1000000n);
+                scenes.push({
+                    type: 'app_switch',
+                    startTs: startTs,
+                    endTs: endNs.toString(),
+                    durationMs,
+                    confidence: 0.9,
+                    appPackage: extractRowAppPackage(row),
+                    metadata: {
+                        source: 'scene_reconstruction:top_app_changes',
+                        event: row.event,
+                    },
+                });
+            }
+            continue;
+        }
+        // Step: system_events (unlock/notification/split screen)
+        if (stepId === 'system_events') {
+            for (const row of rows) {
+                const startTs = normalizeNs(row.ts);
+                const durNs = toBigInt(row.dur);
+                if (!startTs || durNs === null)
+                    continue;
+                const eventText = String(row.event || '');
+                const type = mapSystemEventToSceneType(eventText);
+                if (!type)
+                    continue;
+                // Guardrail: ignore very short unlock slices (usually render/mutex noise).
+                if (type === 'screen_unlock' && durNs < 100000000n)
+                    continue;
+                const startNs = BigInt(startTs);
+                const endNs = startNs + durNs;
+                const durationMs = Number(durNs / 1000000n);
+                scenes.push({
+                    type,
+                    startTs: startTs,
+                    endTs: endNs.toString(),
+                    durationMs,
+                    confidence: 0.85,
+                    metadata: {
+                        source: 'scene_reconstruction:system_events',
+                        event: eventText,
+                    },
+                });
+            }
+            continue;
+        }
+        // Step: clean_timeline (quality-gated unified timeline)
+        if (stepId === 'clean_timeline') {
+            const cleanTimelineTypeMapping = {
+                'cold_start': 'cold_start',
+                'warm_start': 'warm_start',
+                'hot_start': 'hot_start',
+                'scroll': 'scroll',
+                'tap': 'tap',
+                'long_press': 'long_press',
+                'screen_on': 'screen_on',
+                'screen_off': 'screen_off',
+                'screen_sleep': 'screen_sleep',
+                'screen_unlock': 'screen_unlock',
+                'notification': 'notification',
+                'split_screen': 'split_screen',
+                'pip': 'navigation',
+                'app_switch': 'app_switch',
+                'home_screen': 'home_screen',
+                'app_foreground': 'app_foreground',
+                'back_key': 'back_key',
+                'home_key': 'home_key',
+                'recents_key': 'recents_key',
+                'anr': 'anr',
+                'ime_show': 'ime_show',
+                'ime_hide': 'ime_hide',
+                'window_transition': 'window_transition',
+                'idle': 'idle',
+            };
+            for (const row of rows) {
+                const eventType = String(row.event_type || '');
+                const sceneType = cleanTimelineTypeMapping[eventType];
+                if (!sceneType)
+                    continue;
+                const startTs = normalizeNs(row.ts);
+                const durNs = toBigInt(row.dur);
+                if (!startTs || durNs === null)
+                    continue;
+                const startNs = BigInt(startTs);
+                const endNs = startNs + durNs;
+                const durationMs = Number(durNs / 1000000n);
+                scenes.push({
+                    type: sceneType,
+                    startTs,
+                    endTs: endNs.toString(),
+                    durationMs,
+                    confidence: 0.9,
+                    appPackage: extractRowAppPackage(row),
+                    metadata: {
+                        source: 'scene_reconstruction:clean_timeline',
+                        eventId: row.event_id,
+                        timeOffset: row.time_offset,
+                        rating: row.rating,
+                        event: row.event,
+                    },
+                });
+            }
+            continue;
+        }
+        // Step: jank_events (performance issue regions) - FALLBACK
+        // Collected first; only used if no gesture-like scenes are found.
+        if (stepId === 'jank_events') {
+            jankRowsForFallback.push(...rows);
+            continue;
+        }
+    }
+    const hasGestureLikeScene = scenes.some((scene) => (scene.type === 'tap' ||
+        scene.type === 'scroll' ||
+        scene.type === 'long_press' ||
+        scene.type === 'inertial_scroll'));
+    if (!hasGestureLikeScene && jankRowsForFallback.length > 0) {
+        const jankIntervals = aggregateJankFramesToIntervals(jankRowsForFallback);
+        for (const interval of jankIntervals) {
+            if (interval.jankCount < 3)
+                continue;
+            scenes.push({
+                type: 'jank_region',
+                startTs: interval.startTs,
+                endTs: interval.endTs,
+                durationMs: interval.durationMs,
+                confidence: 0.8,
+                metadata: {
+                    source: 'scene_reconstruction:jank_events',
+                    jankCount: interval.jankCount,
+                    severity: interval.severity,
+                },
+            });
+        }
+    }
+    scenes.sort((a, b) => (BigInt(a.startTs) > BigInt(b.startTs) ? 1 : -1));
+    return scenes;
+}
+/**
+ * Aggregates consecutive jank frames into intervals.
+ * Adjacent jank frames within 500ms gap are merged into one interval.
+ * This creates meaningful analysis targets from scattered jank events.
+ */
+function aggregateJankFramesToIntervals(rows) {
+    if (!rows.length)
+        return [];
+    const MERGE_GAP_NS = 500000000n; // 500ms
+    const intervals = [];
+    // Sort by timestamp first
+    const sortedRows = [...rows].sort((a, b) => {
+        const aTs = toBigInt(a.ts);
+        const bTs = toBigInt(b.ts);
+        if (aTs === null || bTs === null)
+            return 0;
+        return aTs < bTs ? -1 : aTs > bTs ? 1 : 0;
+    });
+    let currentStart = toBigInt(sortedRows[0].ts);
+    let currentEnd = currentStart !== null
+        ? currentStart + (toBigInt(sortedRows[0].dur) || 0n)
+        : null;
+    let jankCount = 1;
+    let severities = [String(sortedRows[0].jank_severity_type || '')];
+    if (currentStart === null || currentEnd === null) {
+        return []; // Invalid first row
+    }
+    for (let i = 1; i < sortedRows.length; i++) {
+        const rowTs = toBigInt(sortedRows[i].ts);
+        const rowDur = toBigInt(sortedRows[i].dur) || 0n;
+        if (rowTs === null)
+            continue;
+        if (rowTs - currentEnd < MERGE_GAP_NS) {
+            // Merge into current interval
+            const rowEnd = rowTs + rowDur;
+            if (rowEnd > currentEnd) {
+                currentEnd = rowEnd;
+            }
+            jankCount++;
+            severities.push(String(sortedRows[i].jank_severity_type || ''));
+        }
+        else {
+            // Save current interval and start a new one
+            intervals.push({
+                startTs: currentStart.toString(),
+                endTs: currentEnd.toString(),
+                durationMs: Number((currentEnd - currentStart) / 1000000n),
+                jankCount,
+                severity: severities.includes('Full') ? 'severe' : 'mild',
+            });
+            currentStart = rowTs;
+            currentEnd = rowTs + rowDur;
+            jankCount = 1;
+            severities = [String(sortedRows[i].jank_severity_type || '')];
+        }
+    }
+    // Save the last interval
+    intervals.push({
+        startTs: currentStart.toString(),
+        endTs: currentEnd.toString(),
+        durationMs: Number((currentEnd - currentStart) / 1000000n),
+        jankCount,
+        severity: severities.includes('Full') ? 'severe' : 'mild',
+    });
+    return intervals;
+}
+function mergeDetectedScenes(existing, incoming) {
+    const merged = new Map();
+    for (const s of existing)
+        merged.set(sceneKey(s), s);
+    for (const s of incoming)
+        merged.set(sceneKey(s), s);
+    const out = Array.from(merged.values());
+    out.sort((a, b) => (BigInt(a.startTs) > BigInt(b.startTs) ? 1 : -1));
+    return out;
+}
+function sceneKey(scene) {
+    return `${scene.type}:${scene.startTs}:${scene.endTs}:${scene.appPackage || ''}`;
+}
+function buildTrackEventsFromScenes(scenes) {
+    return scenes.map((scene) => {
+        const displayName = SCENE_DISPLAY_NAMES[scene.type] || scene.type;
+        const colorScheme = SCENE_COLOR_SCHEMES[scene.type] || 'system';
+        const appName = scene.appPackage
+            ? scene.appPackage.replace('com.', '').replace('android.', '')
+            : '';
+        let name = displayName;
+        if (appName)
+            name += ` [${appName}]`;
+        if (Number.isFinite(scene.durationMs) && scene.durationMs > 0)
+            name += ` ${scene.durationMs}ms`;
+        let dur = '0';
+        try {
+            dur = (BigInt(scene.endTs) - BigInt(scene.startTs)).toString();
+        }
+        catch { }
+        return {
+            ts: scene.startTs,
+            dur,
+            name,
+            category: 'scene',
+            colorScheme,
+            details: {
+                sceneType: scene.type,
+                appPackage: scene.appPackage,
+                durationMs: scene.durationMs,
+                confidence: scene.confidence,
+                ...scene.metadata,
+            },
+        };
+    });
+}
+function fingerprintTrackEvents(events) {
+    return events.map(e => `${e.ts}:${e.dur}:${e.name}:${e.colorScheme}`).join('|');
+}
+function payloadToObjectRowsLocal(payload) {
+    if (!payload || typeof payload !== 'object')
+        return [];
+    const cols = payload.columns;
+    const rows = payload.rows;
+    if (!Array.isArray(cols) || !Array.isArray(rows))
+        return [];
+    const out = [];
+    for (const row of rows) {
+        if (!Array.isArray(row))
+            continue;
+        const obj = {};
+        for (let i = 0; i < cols.length; i++) {
+            obj[String(cols[i])] = row[i];
+        }
+        out.push(obj);
+    }
+    return out;
+}
+function normalizeNs(value) {
+    const n = toBigInt(value);
+    return n === null ? null : n.toString();
+}
+function toBigInt(value) {
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        try {
+            return BigInt(Math.trunc(value));
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof value === 'string') {
+        const s = value.trim();
+        if (!s)
+            return null;
+        if (!/^-?\d+$/.test(s))
+            return null;
+        try {
+            return BigInt(s);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function confidenceToScore(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return Math.max(0, Math.min(1, value));
+    const s = String(value || '').trim();
+    if (!s)
+        return 0.85;
+    if (s === '高')
+        return 0.9;
+    if (s === '中')
+        return 0.7;
+    if (s === '低')
+        return 0.5;
+    return 0.8;
+}
+function extractRowAppPackage(row, extraFields = []) {
+    const candidateFields = ['app_package', 'appPackage', ...extraFields];
+    for (const field of candidateFields) {
+        const value = row[field];
+        if (typeof value === 'string' && value.trim()) {
+            return value.trim();
+        }
+    }
+    const eventApp = extractBracketContent(String(row.event || ''));
+    if (eventApp)
+        return eventApp;
+    return undefined;
+}
+function extractBracketContent(text) {
+    const m = text.match(/\[([^\]]+)\]\s*$/);
+    return m ? m[1] : null;
+}
+function mapSystemEventToSceneType(eventText) {
+    const e = eventText.trim();
+    if (!e)
+        return null;
+    // Keep unlock mapping strict; broad substring matching causes false positives.
+    if (e === '解锁屏幕' || e.includes('锁屏解锁'))
+        return 'screen_unlock';
+    if (e.includes('画中画'))
+        return 'navigation';
+    if (e.includes('通知栏') || e.includes('通知'))
+        return 'notification';
+    if (e.includes('分屏'))
+        return 'split_screen';
+    if (e.includes('Activity'))
+        return 'navigation';
+    return null;
+}
+function mapScreenStateEventToSceneType(eventText) {
+    const e = eventText.trim();
+    if (!e)
+        return null;
+    if (e.includes('点亮'))
+        return 'screen_on';
+    if (e.includes('熄灭'))
+        return 'screen_off';
+    if (e.includes('休眠'))
+        return 'screen_sleep';
+    return null;
+}
+function buildClientFindings(findings, scenes) {
+    const base = (findings || []).map((f) => ({
+        id: String(f?.id || `finding_${Date.now()}`),
+        category: f?.category,
+        severity: f?.severity,
+        title: f?.title,
+        description: f?.description,
+        timestampsNs: f?.timestampsNs,
+        evidence: f?.evidence,
+        details: f?.details,
+        recommendations: f?.recommendations,
+        confidence: f?.confidence,
+    }));
+    const hasIssueLikeFinding = base.some((f) => {
+        const severity = String(f.severity || '').toLowerCase();
+        if (severity === 'critical' || severity === 'high' || severity === 'warning')
+            return true;
+        return hasIssueSignalText(`${f.title || ''} ${f.description || ''}`);
+    });
+    const filtered = hasIssueLikeFinding
+        ? base.filter((f) => !isNoIssueText(`${f.title || ''} ${f.description || ''}`))
+        : base;
+    const derived = deriveSceneIssueFindings(scenes);
+    const merged = [...filtered, ...derived];
+    const dedup = new Map();
+    for (const f of merged) {
+        const key = `${String(f.title || '').trim()}::${String(f.description || '').trim()}`;
+        if (!key || key === '::') {
+            dedup.set(f.id, f);
+            continue;
+        }
+        if (!dedup.has(key))
+            dedup.set(key, f);
+    }
+    return Array.from(dedup.values());
+}
+function buildSessionResultContract(session, findings) {
+    return (0, assistantResultContract_1.buildAssistantResultContract)({
+        dataEnvelopes: session.dataEnvelopes,
+        findings,
+    });
+}
+function deriveSceneIssueFindings(scenes) {
+    if (!Array.isArray(scenes) || scenes.length === 0)
+        return [];
+    const scrollScenes = scenes.filter((s) => s.type === 'scroll');
+    const inertialCandidates = scenes
+        .filter((s) => s.type === 'inertial_scroll')
+        .map((s) => ({
+        scene: s,
+        jankFrames: Number(s.metadata?.jankFrames || 0),
+    }))
+        .filter((item) => item.jankFrames > 0)
+        .sort((a, b) => b.jankFrames - a.jankFrames)
+        .slice(0, 3);
+    const derived = [];
+    for (const item of inertialCandidates) {
+        const s = item.scene;
+        const severity = item.jankFrames >= 100 ? 'critical'
+            : item.jankFrames >= 40 ? 'warning'
+                : 'info';
+        const app = s.appPackage || 'unknown';
+        const inertialStartNs = toBigInt(s.startTs);
+        const inertialEndNs = toBigInt(s.endTs);
+        let totalScrollDurationMs = s.durationMs;
+        if (inertialStartNs !== null && inertialEndNs !== null) {
+            let parentScroll = null;
+            let parentStartNs = null;
+            for (const scroll of scrollScenes) {
+                const startNs = toBigInt(scroll.startTs);
+                const endNs = toBigInt(scroll.endTs);
+                if (startNs === null || endNs === null)
+                    continue;
+                if (startNs <= inertialStartNs && endNs >= inertialStartNs) {
+                    if (!parentScroll || (parentStartNs !== null && startNs > parentStartNs)) {
+                        parentScroll = scroll;
+                        parentStartNs = startNs;
+                    }
+                }
+            }
+            if (parentStartNs !== null && inertialEndNs > parentStartNs) {
+                totalScrollDurationMs = Number((inertialEndNs - parentStartNs) / 1000000n);
+            }
+        }
+        derived.push({
+            id: `scene_inertial_${s.startTs}`,
+            category: 'scroll',
+            severity,
+            title: `惯性滑动卡顿：${item.jankFrames} 帧异常`,
+            description: `惯性 ${s.durationMs}ms，总滑动约 ${totalScrollDurationMs}ms，应用 ${app}，建议重点排查滑动后渲染路径`,
+            details: {
+                sceneType: s.type,
+                startTs: s.startTs,
+                endTs: s.endTs,
+                durationMs: s.durationMs,
+                totalScrollDurationMs,
+                jankFrames: item.jankFrames,
+                source: 'scene_reconstruction:derived',
+            },
+            confidence: 0.85,
+        });
+    }
+    return derived;
+}
+function isNoIssueText(text) {
+    const t = String(text || '').toLowerCase();
+    return (t.includes('未发现明显性能问题') ||
+        t.includes('整体流畅度良好') ||
+        t.includes('分析未发现明显问题'));
+}
+function hasIssueSignalText(text) {
+    const t = String(text || '').toLowerCase();
+    return (t.includes('卡顿') ||
+        t.includes('掉帧') ||
+        t.includes('缓冲区积压') ||
+        t.includes('jank') ||
+        t.includes('stutter') ||
+        t.includes('deadline missed') ||
+        t.includes('renderthread') ||
+        t.includes('主线程阻塞'));
+}
+function isSceneReplayOnlyQuery(query) {
+    const q = String(query || '').toLowerCase();
+    const isSceneQuery = q.includes('场景还原') || q.includes('scene reconstruction');
+    if (!isSceneQuery)
+        return false;
+    // Scene reconstruction in this product is replay-first; quick/replay variants are explicit.
+    return q.includes('仅检测') || q.includes('只检测') || q.includes('quick') || q.includes('replay');
+}
+const SCENE_RESPONSE_THRESHOLDS = {
+    cold_start: { good: 500, acceptable: 1000 },
+    warm_start: { good: 300, acceptable: 600 },
+    hot_start: { good: 100, acceptable: 200 },
+    inertial_scroll: { good: 500, acceptable: 1000 },
+    tap: { good: 100, acceptable: 200 },
+    navigation: { good: 300, acceptable: 500 },
+    app_switch: { good: 500, acceptable: 1000 },
+};
+function classifySceneResponse(scene) {
+    const metadata = scene.metadata;
+    if ((scene.type === 'scroll' || scene.type === 'inertial_scroll') && Number.isFinite(Number(metadata?.averageFps))) {
+        const fps = Number(metadata?.averageFps);
+        if (fps >= 55)
+            return '流畅';
+        if (fps >= 45)
+            return '轻微波动';
+        return '明显波动';
+    }
+    const thresholds = SCENE_RESPONSE_THRESHOLDS[scene.type];
+    if (!thresholds)
+        return '未知';
+    if (scene.durationMs <= thresholds.good)
+        return '流畅';
+    if (scene.durationMs <= thresholds.acceptable)
+        return '轻微波动';
+    return '明显波动';
+}
+function formatSceneDurationMs(durationMs) {
+    if (!Number.isFinite(durationMs) || durationMs <= 0)
+        return '-';
+    if (durationMs >= 1000)
+        return `${(durationMs / 1000).toFixed(2)}s`;
+    return `${Math.round(durationMs)}ms`;
+}
+function formatSceneStartTsForNarrative(tsNs) {
+    const ns = toBigInt(tsNs);
+    if (ns === null)
+        return tsNs;
+    const totalMs = Number(ns / 1000000n);
+    const seconds = totalMs / 1000;
+    if (!Number.isFinite(seconds))
+        return tsNs;
+    if (seconds < 60)
+        return `${seconds.toFixed(3)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m ${remainingSeconds.toFixed(3)}s`;
+}
+function buildSceneReplayNarrative(scenes) {
+    if (!Array.isArray(scenes) || scenes.length === 0) {
+        return '未检测到可回放的用户操作场景。';
+    }
+    const sorted = [...scenes].sort((a, b) => {
+        const aTs = toBigInt(a.startTs);
+        const bTs = toBigInt(b.startTs);
+        if (aTs === null || bTs === null)
+            return 0;
+        if (aTs > bTs)
+            return 1;
+        if (aTs < bTs)
+            return -1;
+        return 0;
+    });
+    const maxItems = 12;
+    const sequenceLines = sorted.slice(0, maxItems).map((scene, idx) => {
+        const displayName = SCENE_DISPLAY_NAMES[scene.type] || scene.type;
+        const startTs = formatSceneStartTsForNarrative(scene.startTs);
+        const duration = formatSceneDurationMs(scene.durationMs);
+        const response = classifySceneResponse(scene);
+        const appText = scene.appPackage ? `，应用 ${scene.appPackage}` : '';
+        return `${idx + 1}. [${startTs}] ${displayName}，持续 ${duration}${appText}，响应状态：${response}`;
+    });
+    const extraLine = sorted.length > maxItems
+        ? `- 其余 ${sorted.length - maxItems} 个场景可在表格中继续查看。`
+        : '';
+    return [
+        `共还原 ${sorted.length} 个操作场景。以下为操作与设备响应事实回放（不含根因推断）：`,
+        '',
+        ...sequenceLines.map((line) => `- ${line}`),
+        extraLine,
+    ].filter(Boolean).join('\n');
+}
+// Delegates to the shared normalizer so CLI's buildReportHtml gets identical
+// conclusion text for the same run. The HTTP-specific pieces (scene replay,
+// sceneIdHint) stay inline in sendAgentDrivenResult.
+function normalizeNarrativeForClient(narrative) {
+    return (0, agentResultNormalizer_1.normalizeNarrativeForClient)(narrative);
+}
+function conclusionHasEvidenceIndex(conclusion) {
+    const text = conclusion || '';
+    return /(^|\n)\s*##\s*证据表索引\b/.test(text);
+}
+function markdownCell(value, maxLen = 80) {
+    return String(value ?? '')
+        .replace(/\s+/g, ' ')
+        .replace(/\|/g, '/')
+        .trim()
+        .slice(0, maxLen) || '-';
+}
+function envelopeRowCount(env) {
+    const rows = env?.data?.rows;
+    if (Array.isArray(rows))
+        return String(rows.length);
+    const summaryContent = env?.data?.summary?.content;
+    if (typeof summaryContent === 'string') {
+        const matched = summaryContent.match(/Total rows:\s*(\d+)/i);
+        if (matched)
+            return matched[1];
+    }
+    return '-';
+}
+function buildConclusionEvidenceIndex(envelopes, maxItems = 8) {
+    if (!Array.isArray(envelopes) || envelopes.length === 0)
+        return '';
+    const seen = new Set();
+    const candidates = [];
+    for (const env of envelopes) {
+        const meta = env?.meta || {};
+        const display = env?.display || {};
+        if (display.level === 'hidden')
+            continue;
+        const title = markdownCell(display.title || meta.stepId || meta.source);
+        if (title === '-')
+            continue;
+        const key = String(meta.evidenceRefId || `${meta.source || ''}:${meta.stepId || ''}:${title}`);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const phase = markdownCell(meta.planPhaseTitle || meta.planPhaseId || '-');
+        const source = markdownCell(meta.source || meta.skillId || 'execute_sql');
+        const evidence = markdownCell(meta.evidenceRefId || meta.sourceToolCallId || '-', 48);
+        candidates.push(`| ${phase} | ${title} | ${source} | ${envelopeRowCount(env)} | ${evidence} |`);
+    }
+    if (candidates.length === 0)
+        return '';
+    const rows = candidates.slice(0, maxItems);
+    const omitted = Math.max(0, candidates.length - rows.length);
+    return [
+        '## 证据表索引',
+        '',
+        '| 阶段 | 表/摘要 | 来源 | 行数 | 证据 ID |',
+        '|---|---|---|---:|---|',
+        ...rows,
+        omitted > 0 ? `| - | 其余 ${omitted} 份证据 | - | - | - |` : '',
+    ].filter(Boolean).join('\n');
+}
+function appendEvidenceIndexIfMissing(conclusion, envelopes) {
+    const normalized = conclusion || '';
+    if (conclusionHasEvidenceIndex(normalized))
+        return normalized;
+    const evidenceIndex = buildConclusionEvidenceIndex(envelopes);
+    if (!evidenceIndex)
+        return normalized;
+    return `${normalized.trim()}\n\n${evidenceIndex}`;
+}
+function augmentConclusionUpdateWithEvidenceIndex(session, update) {
+    if (update.type !== 'conclusion')
+        return update;
+    const content = update.content;
+    if (!content || typeof content !== 'object' || Array.isArray(content))
+        return update;
+    const conclusion = content.conclusion;
+    if (typeof conclusion !== 'string')
+        return update;
+    const augmented = appendEvidenceIndexIfMissing(conclusion, session.dataEnvelopes || []);
+    if (augmented === conclusion)
+        return update;
+    return {
+        ...update,
+        content: {
+            ...content,
+            conclusion: augmented,
+        },
+    };
+}
+/**
+ * Send agent-driven analysis result to SSE client
+ */
+function sendAgentDrivenResult(res, session) {
+    const result = session.result;
+    if (!result)
+        return;
+    const observability = buildStreamObservability(session);
+    const replayOnlyScene = isSceneReplayOnlyQuery(session.query);
+    const hasEvidenceBackedConclusion = result.success || result.partial === true;
+    const normalizedConclusion = replayOnlyScene
+        ? buildSceneReplayNarrative(session.scenes || [])
+        : hasEvidenceBackedConclusion ? appendEvidenceIndexIfMissing(normalizeNarrativeForClient(result.conclusion), session.dataEnvelopes || []) : normalizeNarrativeForClient(result.conclusion);
+    const sceneIdHint = replayOnlyScene
+        ? undefined
+        : resolveConclusionSceneIdHint({
+            sessionId: session.sessionId,
+            query: session.query,
+            findings: result.findings,
+        });
+    // Fallback: re-derive contract if the orchestrator didn't populate it.
+    // Note: mode heuristic uses rounds (available here) as proxy for turnCount
+    // (which only the orchestrator knows). Both signal "multi-interaction" analysis.
+    const normalizedConclusionContract = replayOnlyScene
+        ? undefined
+        : hasEvidenceBackedConclusion ? (result.conclusionContract ||
+            (0, agentResultNormalizer_1.deriveConclusionContractForNarrative)(result.conclusion, {
+                mode: result.rounds > 1 ? 'focused_answer' : 'initial_report',
+                sceneId: sceneIdHint,
+            }) ||
+            undefined) : undefined;
+    const resultForClient = normalizedConclusion === result.conclusion && normalizedConclusionContract === result.conclusionContract
+        ? result
+        : { ...result, conclusion: normalizedConclusion, conclusionContract: normalizedConclusionContract };
+    const clientFindings = replayOnlyScene ? [] : buildClientFindings(result.findings, session.scenes || []);
+    const resultContract = buildSessionResultContract(session, clientFindings);
+    // Generate HTML report
+    let reportUrl;
+    let reportError;
+    const reportId = `agent-report-${session.sessionId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    let resultSnapshotId;
+    let resultSnapshotEventData;
+    let reportLease = null;
+    if (!hasEvidenceBackedConclusion) {
+        reportError = `analysis did not complete successfully (${result.terminationReason || 'failed'})`;
+    }
+    else {
+        try {
+            if (enterpriseLeasesEnabled()) {
+                const scope = leaseScopeFromSession(session);
+                if (scope) {
+                    const traceInfo = (0, traceProcessorService_1.getTraceProcessorService)().getTrace(session.traceId);
+                    const reportLeaseDecision = buildLeaseModeDecisionForTrace(scope, session.traceId, 'report_generation', {
+                        traceSizeBytes: traceInfo?.size,
+                    });
+                    reportLease = (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)().acquireHolder(scope, session.traceId, {
+                        holderType: 'report_generation',
+                        holderRef: reportId,
+                        reportId,
+                        sessionId: session.sessionId,
+                        runId: session.lastRun?.runId || session.activeRun?.runId,
+                        metadata: {
+                            leaseModeReason: reportLeaseDecision.reason,
+                            leaseModeSignals: reportLeaseDecision.signals,
+                        },
+                    }, { mode: reportLeaseDecision.mode });
+                    reportLease = markLeaseReadyIfNew(reportLease, scope);
+                }
+            }
+            const generator = (0, htmlReportGenerator_1.getHTMLReportGenerator)();
+            // Report assembly (cumulative findings dedup, empty-conclusion fallback,
+            // snapshot-first analysisNotes/Plan/Flags) lives in the shared builder so
+            // the CLI path produces identical output.
+            const reportData = (0, agentReportData_1.buildAgentDrivenReportData)({
+                session,
+                result: resultForClient,
+            });
+            console.log(`[AgentRoutes] Generating HTML report, data keys:`, {
+                hasResult: !!result,
+                conclusionLength: normalizedConclusion?.length || 0,
+                conclusionPreview: (normalizedConclusion || '').substring(0, 100),
+                hasConclusionContract: !!normalizedConclusionContract,
+                findingsCount: result.findings?.length || 0,
+                hypothesesCount: session.hypotheses?.length || 0,
+                dialogueCount: session.agentDialogue?.length || 0,
+                conversationStepCount: session.conversationSteps?.length || 0,
+                dataEnvelopesCount: session.dataEnvelopes?.length || 0,
+                agentResponsesCount: session.agentResponses?.length || 0,
+                conclusionHistoryCount: session.conclusionHistory?.length || 0,
+                hasSnapshot: !!session._lastSnapshot,
+                snapshotNotes: session._lastSnapshot?.analysisNotes?.length ?? 'n/a',
+                snapshotPlan: !!session._lastSnapshot?.analysisPlan,
+                snapshotFlags: session._lastSnapshot?.uncertaintyFlags?.length ?? 'n/a',
+            });
+            const html = generator.generateAgentDrivenHTML(reportData);
+            // Store report
+            (0, reportRoutes_1.persistReport)(reportId, {
+                html,
+                generatedAt: Date.now(),
+                sessionId: session.sessionId,
+                runId: session.lastRun?.runId || session.activeRun?.runId,
+                traceId: session.traceId,
+                tenantId: session.tenantId,
+                workspaceId: session.workspaceId,
+                userId: session.userId,
+                visibility: 'private',
+            });
+            reportUrl = `/api/reports/${reportId}`;
+            console.log(`[AgentRoutes] Generated agent-driven HTML report: ${reportId} (${html.length} bytes)`);
+        }
+        catch (error) {
+            reportError = error.message || 'Unknown error';
+            console.error('[AgentRoutes] Failed to generate agent-driven HTML report:', {
+                error: reportError,
+                stack: error.stack?.split('\n').slice(0, 5).join('\n'),
+                resultConclusion: result?.conclusion ? `${result.conclusion.length} chars` : 'EMPTY/NULL',
+                resultConfidence: result?.confidence,
+                resultRounds: result?.rounds,
+            });
+        }
+        finally {
+            if (reportLease) {
+                const scope = leaseScopeFromSession(session);
+                if (scope) {
+                    try {
+                        (0, traceProcessorLeaseStore_1.getTraceProcessorLeaseStore)().releaseHolder(scope, reportLease.id, 'report_generation', reportId);
+                    }
+                    catch (releaseError) {
+                        console.warn(`[AgentRoutes] Failed to release report_generation lease ${reportLease.id}: ${releaseError.message}`);
+                    }
+                }
+            }
+        }
+    }
+    if (hasEvidenceBackedConclusion) {
+        try {
+            const resultSnapshot = (0, analysisResultSnapshotPipeline_1.persistCompletedAnalysisResultSnapshot)({
+                tenantId: session.tenantId,
+                workspaceId: session.workspaceId,
+                userId: session.userId,
+                traceId: session.traceId,
+                sessionId: session.sessionId,
+                runId: session.lastRun?.runId || session.activeRun?.runId,
+                reportId: reportUrl ? reportId : undefined,
+                query: session.query,
+                traceLabel: session.traceId,
+                conclusion: normalizedConclusion,
+                conclusionContract: normalizedConclusionContract,
+                confidence: result.confidence,
+                partial: result.partial,
+                terminationReason: result.terminationReason,
+                terminationMessage: result.terminationMessage,
+                dataEnvelopes: session.dataEnvelopes,
+            });
+            resultSnapshotId = resultSnapshot?.id;
+            if (resultSnapshot) {
+                resultSnapshotEventData = {
+                    snapshotId: resultSnapshot.id,
+                    status: resultSnapshot.status,
+                    sceneType: resultSnapshot.sceneType,
+                    metricCount: resultSnapshot.metrics.length,
+                    evidenceRefCount: resultSnapshot.evidenceRefs.length,
+                    traceId: resultSnapshot.traceId,
+                    sessionId: resultSnapshot.sessionId,
+                    runId: resultSnapshot.runId,
+                    reportId: resultSnapshot.reportId,
+                    visibility: resultSnapshot.visibility,
+                    createdAt: resultSnapshot.createdAt,
+                };
+            }
+        }
+        catch (snapshotError) {
+            console.warn('[AgentRoutes] Failed to persist analysis result snapshot:', {
+                sessionId: session.sessionId,
+                runId: session.lastRun?.runId || session.activeRun?.runId,
+                error: snapshotError?.message || String(snapshotError),
+            });
+        }
+    }
+    if (resultSnapshotEventData) {
+        sendReplayableSessionEvent(session, res, 'snapshot_created', {
+            type: 'snapshot_created',
+            architecture: 'agent-driven',
+            ...observability,
+            data: resultSnapshotEventData,
+            timestamp: Date.now(),
+        });
+    }
+    // Send analysis_completed event with full result. Keep it replayable so a
+    // reconnect between conclusion and report generation can recover reportUrl.
+    sendReplayableSessionEvent(session, res, 'analysis_completed', {
+        type: 'analysis_completed',
+        architecture: 'agent-driven',
+        ...observability,
+        data: {
+            conclusion: normalizedConclusion,
+            conclusionContract: normalizedConclusionContract,
+            confidence: result.confidence,
+            rounds: result.rounds,
+            totalDurationMs: result.totalDurationMs,
+            partial: result.partial,
+            terminationReason: result.terminationReason,
+            terminationMessage: result.terminationMessage,
+            findings: clientFindings,
+            resultContract,
+            hypotheses: result.hypotheses.map((h) => ({
+                id: h.id,
+                description: h.description,
+                status: h.status,
+                confidence: h.confidence,
+                supportingEvidence: h.supportingEvidence,
+                contradictingEvidence: h.contradictingEvidence,
+            })),
+            agentDialogueCount: session.agentDialogue.length,
+            conversationTimelineCount: session.conversationSteps.length,
+            conversationTimeline: session.conversationSteps,
+            reportUrl,
+            reportError,
+            comparisonReportSection: session.comparisonReportSection
+                ? {
+                    source: session.comparisonReportSection.source,
+                    title: session.comparisonReportSection.title,
+                    markdown: session.comparisonReportSection.markdown,
+                    limitations: session.comparisonReportSection.limitations,
+                    evidencePack: session.comparisonReportSection.evidencePack,
+                }
+                : undefined,
+            resultSnapshotId,
+            observability,
+        },
+        timestamp: Date.now(),
+    });
+    // Backward-compatible scene reconstruction payload (used by the legacy /scene-reconstruct clients).
+    if ((session.scenes?.length || 0) > 0 || (session.trackEvents?.length || 0) > 0) {
+        sendReplayableSessionEvent(session, res, 'scene_reconstruction_completed', {
+            type: 'scene_reconstruction_completed',
+            ...observability,
+            data: {
+                narrative: normalizedConclusion,
+                confidence: result.confidence,
+                executionTimeMs: result.totalDurationMs,
+                scenes: (session.scenes || []).map((s) => ({
+                    type: s.type,
+                    startTs: s.startTs,
+                    endTs: s.endTs,
+                    durationMs: s.durationMs,
+                    confidence: s.confidence,
+                    appPackage: s.appPackage,
+                })),
+                trackEvents: session.trackEvents || [],
+                findings: clientFindings.map((f) => ({
+                    id: f.id,
+                    category: f.category,
+                    severity: f.severity,
+                    title: f.title,
+                    description: f.description,
+                    timestampsNs: f.timestampsNs,
+                })),
+                suggestions: [],
+                observability,
+            },
+            timestamp: Date.now(),
+        });
+    }
+}
+(0, agentLogsRoutes_1.registerAgentLogsRoutes)(router);
+// ============================================================================
+// Cleanup
+// ============================================================================
+// Cleanup old sessions every 30 minutes
+const sessionCleanupInterval = setInterval(() => {
+    assistantAppService.cleanupIdleSessions({
+        terminalMaxIdleMs: TERMINAL_SESSION_MAX_IDLE_MS,
+        nonTerminalMaxIdleMs: NON_TERMINAL_SESSION_MAX_IDLE_MS,
+        shouldCleanup: (_sessionId, session, context) => {
+            if (!(0, config_1.resolveFeatureConfig)().enterprise || !context.isAbandonedNonTerminal) {
+                return true;
+            }
+            if (isPersistedSessionRunFresh(session, context.now)) {
+                session.lastActivityAt = context.now;
+                return false;
+            }
+            return true;
+        },
+        onCleanup: (sessionId, session) => {
+            console.log(`[AgentRoutes] Cleaning up stale session: ${sessionId}`);
+            session.sseClients.forEach((client) => {
+                try {
+                    client.end();
+                }
+                catch {
+                    // Ignore closed sockets during cleanup.
+                }
+            });
+            // Clean up session-scoped state only — do NOT call reset() which clears
+            // global caches (architectureCache) shared across all active sessions.
+            if (typeof session.orchestrator.cleanupSession === 'function') {
+                session.orchestrator.cleanupSession(sessionId);
+            }
+            // Also clean up the EnhancedSessionContext (EntityStore, turns, working memory)
+            enhancedSessionContext_1.sessionContextManager.remove(sessionId);
+        },
+    });
+    // Piggyback the Scene Story disk cache cleanup on the same 30-min cadence.
+    // It's idempotent and self-contained, so a failed sweep here only delays
+    // expired-report removal by another 30 minutes — never blocks session
+    // cleanup or throws into the interval.
+    void sceneReportStore
+        .cleanupExpired(Date.now())
+        .then((removed) => {
+        if (removed > 0) {
+            console.log(`[AgentRoutes] SceneReportStore expired ${removed} report(s)`);
+        }
+    })
+        .catch((err) => {
+        console.warn('[AgentRoutes] SceneReportStore cleanupExpired failed:', err?.message ?? err);
+    });
+}, 30 * 60 * 1000);
+sessionCleanupInterval.unref?.();
+exports.default = router;
+//# sourceMappingURL=agentRoutes.js.map