@winspan/claude-forge 8.18.0 → 8.25.0

package/dist/web/server.js

@@ -13,21 +13,45 @@ import { Recommender } from '../engine/recommender.js';
 import { logger } from '../core/utils/logger.js';
 import { ErrorHandler } from '../core/utils/error-handler.js';
 import { ConfigManager } from '../core/config.js';
+import { ClaudeProvider } from '../core/ai/provider.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export class WebServer {
     options;
     app;
     server = null;
     agents;
+    router;
     constructor(options) {
         this.options = options;
         this.app = express();
         this.app.use(express.json());
         this.agents = options.agents;
+        this.router = options.router;
         this.setupRoutes();
     }
     setupRoutes() {
         const { storage, ruleEngine } = this.options;
+        const resolvePatchTarget = (targetType, targetName) => {
+            if (targetType === 'agent') {
+                return {
+                    filePath: path.join(homedir(), '.claude', 'agents', `${targetName}.md`),
+                    backupDir: path.join(homedir(), '.claude-forge', 'backups', 'agents'),
+                };
+            }
+            if (targetType === 'skill') {
+                return {
+                    filePath: path.join(homedir(), '.claude', 'skills', `${targetName}.md`),
+                    backupDir: path.join(homedir(), '.claude-forge', 'backups', 'skills'),
+                };
+            }
+            if (targetType === 'routing_rule') {
+                return {
+                    filePath: path.join(homedir(), '.claude-forge', 'routing.yaml'),
+                    backupDir: path.join(homedir(), '.claude-forge', 'backups', 'routing'),
+                };
+            }
+            throw new Error(`Unsupported targetType: ${targetType}`);
+        };
         // Serve static files (support both dist/ and src/ layouts)
         const candidates = [
             path.join(__dirname, 'static'), // dist/web/static
@@ -436,6 +460,161 @@ export class WebServer {
                 byVersion,
             });
         });
+        // Performance analysis for the Agent Routing page
+        this.app.get('/api/routing/performance', (req, res) => {
+            const windowHours = parseInt(req.query.window || '168');
+            const minAttempts = Math.max(1, parseInt(req.query.minAttempts || '10'));
+            const since = Date.now() - windowHours * 3600 * 1000;
+            const events = storage.queryRoutingEvents({ since_ts: since, limit: 5000 });
+            const relevant = events.filter(e => e.routed_to_name);
+            const judged = relevant.filter(e => e.obeyed === 0 || e.obeyed === 1);
+            const obeyedCount = judged.filter(e => e.obeyed === 1).length;
+            const refusedCount = judged.filter(e => e.obeyed === 0).length;
+            const unknownCount = relevant.length - judged.length;
+            const latencies = relevant
+                .map(e => e.classification_ms)
+                .filter((ms) => typeof ms === 'number');
+            const executionLatencies = relevant
+                .map(e => e.total_execution_ms ?? ((typeof e.completed_ts === 'number') ? e.completed_ts - e.ts : null))
+                .filter((ms) => typeof ms === 'number');
+            const avgClassificationMs = latencies.length === 0
+                ? null
+                : Math.round(latencies.reduce((sum, n) => sum + n, 0) / latencies.length);
+            const avgExecutionMs = executionLatencies.length === 0
+                ? null
+                : Math.round(executionLatencies.reduce((sum, n) => sum + n, 0) / executionLatencies.length);
+            const sortedExecution = [...executionLatencies].sort((a, b) => a - b);
+            const p95ExecutionMs = sortedExecution.length === 0
+                ? null
+                : sortedExecution[Math.min(sortedExecution.length - 1, Math.floor(sortedExecution.length * 0.95))];
+            const byAgentMap = new Map();
+            const dailyMap = new Map();
+            for (const e of relevant) {
+                const agent = e.routed_to_name ?? '—';
+                const agentBucket = byAgentMap.get(agent) ?? {
+                    agent,
+                    total: 0,
+                    judged: 0,
+                    obeyed: 0,
+                    refused: 0,
+                    unknown: 0,
+                    latencySum: 0,
+                    latencyCount: 0,
+                    executionSum: 0,
+                    executionCount: 0,
+                };
+                agentBucket.total++;
+                if (e.obeyed === 1) {
+                    agentBucket.judged++;
+                    agentBucket.obeyed++;
+                }
+                else if (e.obeyed === 0) {
+                    agentBucket.judged++;
+                    agentBucket.refused++;
+                }
+                else {
+                    agentBucket.unknown++;
+                }
+                if (typeof e.classification_ms === 'number') {
+                    agentBucket.latencySum += e.classification_ms;
+                    agentBucket.latencyCount++;
+                }
+                const executionMs = e.total_execution_ms ?? ((typeof e.completed_ts === 'number') ? e.completed_ts - e.ts : null);
+                if (typeof executionMs === 'number') {
+                    agentBucket.executionSum += executionMs;
+                    agentBucket.executionCount++;
+                }
+                byAgentMap.set(agent, agentBucket);
+                const date = new Date(e.ts).toISOString().slice(0, 10);
+                const dayBucket = dailyMap.get(date) ?? {
+                    date,
+                    total: 0,
+                    obeyed: 0,
+                    refused: 0,
+                    unknown: 0,
+                    latencySum: 0,
+                    latencyCount: 0,
+                    executionSum: 0,
+                    executionCount: 0,
+                };
+                dayBucket.total++;
+                if (e.obeyed === 1)
+                    dayBucket.obeyed++;
+                else if (e.obeyed === 0)
+                    dayBucket.refused++;
+                else
+                    dayBucket.unknown++;
+                if (typeof e.classification_ms === 'number') {
+                    dayBucket.latencySum += e.classification_ms;
+                    dayBucket.latencyCount++;
+                }
+                if (typeof executionMs === 'number') {
+                    dayBucket.executionSum += executionMs;
+                    dayBucket.executionCount++;
+                }
+                dailyMap.set(date, dayBucket);
+            }
+            const byAgent = Array.from(byAgentMap.values())
+                .map(a => ({
+                agent: a.agent,
+                total: a.total,
+                judged: a.judged,
+                obeyed: a.obeyed,
+                refused: a.refused,
+                unknown: a.unknown,
+                obedienceRate: a.judged === 0 ? null : a.obeyed / a.judged,
+                refusalRate: a.judged === 0 ? null : a.refused / a.judged,
+                avgClassificationMs: a.latencyCount === 0 ? null : Math.round(a.latencySum / a.latencyCount),
+                avgExecutionMs: a.executionCount === 0 ? null : Math.round(a.executionSum / a.executionCount),
+            }))
+                .sort((a, b) => b.total - a.total);
+            const dailyTrend = Array.from(dailyMap.values())
+                .map(d => ({
+                date: d.date,
+                total: d.total,
+                obeyed: d.obeyed,
+                refused: d.refused,
+                unknown: d.unknown,
+                avgClassificationMs: d.latencyCount === 0 ? null : Math.round(d.latencySum / d.latencyCount),
+                avgExecutionMs: d.executionCount === 0 ? null : Math.round(d.executionSum / d.executionCount),
+            }))
+                .sort((a, b) => a.date.localeCompare(b.date));
+            const highRefusalAgents = byAgent
+                .filter(a => a.judged >= minAttempts && (a.refusalRate ?? 0) > 0)
+                .sort((a, b) => {
+                const rateDiff = (b.refusalRate ?? 0) - (a.refusalRate ?? 0);
+                return rateDiff !== 0 ? rateDiff : b.judged - a.judged;
+            })
+                .slice(0, 10)
+                .map(a => ({
+                agent: a.agent,
+                totalAttempts: a.judged,
+                obeyed: a.obeyed,
+                refused: a.refused,
+                refusalRate: a.refusalRate,
+                avgClassificationMs: a.avgClassificationMs,
+                avgExecutionMs: a.avgExecutionMs,
+            }));
+            res.json({
+                windowHours,
+                minAttempts,
+                summary: {
+                    totalRouted: relevant.length,
+                    totalJudged: judged.length,
+                    obeyed: obeyedCount,
+                    refused: refusedCount,
+                    unknown: unknownCount,
+                    obedienceRate: judged.length === 0 ? null : obeyedCount / judged.length,
+                    refusalRate: judged.length === 0 ? null : refusedCount / judged.length,
+                    avgClassificationMs,
+                    avgExecutionMs,
+                    p95ExecutionMs,
+                },
+                byAgent,
+                dailyTrend,
+                highRefusalAgents,
+            });
+        });
         // Recent routing events (timeline / detail)
         this.app.get('/api/routing/events', (req, res) => {
             const limit = parseInt(req.query.limit || '50');
@@ -841,6 +1020,236 @@ export class WebServer {
                 res.status(500).json({ error: String(err) });
             }
         });
+        // AI-assisted optimization recommendations
+        this.app.get('/api/routing/ai-optimization', async (req, res) => {
+            const { router, agents } = this.options;
+            if (!router || !agents) {
+                res.status(400).json({ error: 'router/agents not injected' });
+                return;
+            }
+            const windowHours = Math.max(1, Math.min(720, parseInt(req.query.window || '168')));
+            const minAttempts = Math.max(1, parseInt(req.query.minAttempts || '10'));
+            const since = Date.now() - windowHours * 3600 * 1000;
+            try {
+                const config = new ConfigManager().get();
+                const apiKey = config.distill.api_key || process.env.ANTHROPIC_API_KEY || '';
+                if (!apiKey) {
+                    res.status(400).json({ error: 'AI API key not configured' });
+                    return;
+                }
+                const ai = new ClaudeProvider(apiKey, config.distill.model, config.distill.base_url);
+                const recommender = new Recommender(storage, router, agents, { windowMs: windowHours * 3600 * 1000 });
+                const ruleRecommendations = recommender.analyze();
+                const performanceRes = await (async () => {
+                    const events = storage.queryRoutingEvents({ since_ts: since, limit: 5000 });
+                    const relevant = events.filter(e => e.routed_to_name);
+                    const judged = relevant.filter(e => e.obeyed === 0 || e.obeyed === 1);
+                    const byAgent = new Map();
+                    for (const e of relevant) {
+                        const key = e.routed_to_name ?? '—';
+                        const bucket = byAgent.get(key) ?? { total: 0, judged: 0, obeyed: 0, refused: 0, latencySum: 0, latencyCount: 0 };
+                        bucket.total++;
+                        if (e.obeyed === 1) {
+                            bucket.judged++;
+                            bucket.obeyed++;
+                        }
+                        else if (e.obeyed === 0) {
+                            bucket.judged++;
+                            bucket.refused++;
+                        }
+                        if (typeof e.classification_ms === 'number') {
+                            bucket.latencySum += e.classification_ms;
+                            bucket.latencyCount++;
+                        }
+                        byAgent.set(key, bucket);
+                    }
+                    return {
+                        totalRouted: relevant.length,
+                        totalJudged: judged.length,
+                        byAgent: Array.from(byAgent.entries()).map(([agent, b]) => ({
+                            agent,
+                            total: b.total,
+                            judged: b.judged,
+                            obeyed: b.obeyed,
+                            refused: b.refused,
+                            refusalRate: b.judged === 0 ? null : b.refused / b.judged,
+                            avgClassificationMs: b.latencyCount === 0 ? null : Math.round(b.latencySum / b.latencyCount),
+                        })).sort((a, b) => (b.refusalRate ?? 0) - (a.refusalRate ?? 0)),
+                    };
+                })();
+                const highRefusalAgents = performanceRes.byAgent
+                    .filter(a => a.judged >= minAttempts && (a.refusalRate ?? 0) > 0)
+                    .slice(0, 10);
+                const topViolations = (await (async () => {
+                    const events = storage.queryRoutingEvents({ since_ts: since, obeyed: 0, limit: 1000 });
+                    const patterns = new Map();
+                    for (const e of events) {
+                        let taskType = 'unknown';
+                        try {
+                            const parsed = JSON.parse(e.intent_json ?? '{}');
+                            if (typeof parsed.taskType === 'string')
+                                taskType = parsed.taskType;
+                        }
+                        catch { /* ignore */ }
+                        const key = `${taskType}__${e.routed_to_name ?? '—'}`;
+                        const p = patterns.get(key) ?? { taskType, agent: e.routed_to_name ?? '—', total: 0, refusals: 0, refusalRate: 0, samples: [] };
+                        p.total++;
+                        p.refusals++;
+                        if (p.samples.length < 3)
+                            p.samples.push(e.prompt.slice(0, 180));
+                        patterns.set(key, p);
+                    }
+                    return Array.from(patterns.values()).map(p => ({
+                        ...p,
+                        refusalRate: p.total === 0 ? 0 : p.refusals / p.total,
+                    })).sort((a, b) => b.refusalRate - a.refusalRate).slice(0, 5);
+                })());
+                const prompt = [
+                    'You are reviewing Claude Forge routing performance and should produce practical improvement suggestions.',
+                    'Return ONLY valid JSON with keys: summary, priorities, suggestedChanges.',
+                    '',
+                    'Context:',
+                    `- windowHours: ${windowHours}`,
+                    `- minAttempts: ${minAttempts}`,
+                    `- totalRouted: ${performanceRes.totalRouted}`,
+                    `- totalJudged: ${performanceRes.totalJudged}`,
+                    '',
+                    'Performance by agent:',
+                    JSON.stringify(highRefusalAgents, null, 2),
+                    '',
+                    'Top refusal patterns:',
+                    JSON.stringify(topViolations, null, 2),
+                    '',
+                    'Routing rule recommendations:',
+                    JSON.stringify(ruleRecommendations.slice(0, 8), null, 2),
+                    '',
+                    'Please provide:',
+                    '- summary: 2-3 sentences summarizing the main issues',
+                    '- priorities: array of { area, finding, impact, confidence }',
+                    '- suggestedChanges: array of { targetType: agent|skill|routing_rule, targetName, recommendation, rationale, expectedBenefit }',
+                ].join('\n');
+                const raw = await ai.complete(prompt, { maxTokens: 2500 });
+                const cleaned = raw.replace(/```json\s*/g, '').replace(/```\s*/g, '');
+                const match = cleaned.match(/\{[\s\S]*\}/);
+                if (!match) {
+                    res.status(500).json({ error: 'AI did not return JSON', raw });
+                    return;
+                }
+                const parsed = JSON.parse(match[0]);
+                res.json({
+                    windowHours,
+                    minAttempts,
+                    generatedAt: new Date().toISOString(),
+                    summary: parsed.summary ?? '',
+                    priorities: Array.isArray(parsed.priorities) ? parsed.priorities : [],
+                    suggestedChanges: Array.isArray(parsed.suggestedChanges) ? parsed.suggestedChanges : [],
+                    evidence: {
+                        highRefusalAgents,
+                        topViolations,
+                        ruleRecommendations: ruleRecommendations.slice(0, 8),
+                    },
+                });
+            }
+            catch (err) {
+                logger.warn(`[Web] Failed to generate AI optimization: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // ── Patch APIs ────────────────────────────────────────────────────────
+        // POST /api/patch/preview — generate structured patch preview
+        this.app.post('/api/patch/preview', async (req, res) => {
+            const { targetType, targetName, recommendation, rationale } = req.body ?? {};
+            if (!targetType || !targetName || !recommendation) {
+                res.status(400).json({ error: 'targetType, targetName, and recommendation are required' });
+                return;
+            }
+            try {
+                const config = new ConfigManager().get();
+                const apiKey = config.distill.api_key || process.env.ANTHROPIC_API_KEY || '';
+                if (!apiKey) {
+                    res.status(400).json({ error: 'AI API key not configured' });
+                    return;
+                }
+                const { filePath } = resolvePatchTarget(targetType, targetName);
+                if (!fs.existsSync(filePath)) {
+                    res.status(404).json({ error: `Target file not found: ${filePath}` });
+                    return;
+                }
+                const currentContent = fs.readFileSync(filePath, 'utf-8');
+                const ai = new ClaudeProvider(apiKey, config.distill.model, config.distill.base_url);
+                const prompt = `You are a code/config optimization assistant. Given the current file content and a recommended change, generate the updated content.
+
+Current file (${targetType}/${targetName}):
+\`\`\`
+${currentContent}
+\`\`\`
+
+Recommendation: ${recommendation}
+${rationale ? `Rationale: ${rationale}` : ''}
+
+Return ONLY a JSON object with this exact structure (no markdown, no explanation):
+{
+  "summary": "brief description of what changed",
+  "afterContent": "the complete updated file content",
+  "risk": "low|medium|high"
+}`;
+                const response = await ai.complete(prompt, { maxTokens: 4096 });
+                const parsed = JSON.parse(response.trim());
+                res.json({
+                    targetType,
+                    targetName,
+                    filePath,
+                    before: currentContent,
+                    after: parsed.afterContent,
+                    summary: parsed.summary,
+                    risk: parsed.risk || 'medium',
+                    recommendation,
+                    rationale: rationale || null,
+                });
+            }
+            catch (err) {
+                logger.warn(`[Web] Patch preview failed: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // POST /api/patch/apply — apply patch with backup
+        this.app.post('/api/patch/apply', (req, res) => {
+            const { targetType, targetName, afterContent } = req.body ?? {};
+            if (!targetType || !targetName || typeof afterContent !== 'string') {
+                res.status(400).json({ error: 'targetType, targetName, and afterContent are required' });
+                return;
+            }
+            try {
+                const { filePath, backupDir } = resolvePatchTarget(targetType, targetName);
+                if (!fs.existsSync(filePath)) {
+                    res.status(404).json({ error: `Target file not found: ${filePath}` });
+                    return;
+                }
+                // Create backup
+                if (!fs.existsSync(backupDir)) {
+                    fs.mkdirSync(backupDir, { recursive: true });
+                }
+                const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const backupName = `${targetName}_${timestamp}${path.extname(filePath)}`;
+                const backupPath = path.join(backupDir, backupName);
+                fs.copyFileSync(filePath, backupPath);
+                // Apply patch
+                fs.writeFileSync(filePath, afterContent, 'utf-8');
+                logger.info(`[Web] Patch applied to ${targetType}/${targetName}, backup: ${backupPath}`);
+                res.json({
+                    success: true,
+                    targetType,
+                    targetName,
+                    filePath,
+                    backupPath,
+                    timestamp,
+                });
+            }
+            catch (err) {
+                logger.warn(`[Web] Patch apply failed: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
         // ── AI Configuration APIs ─────────────────────────────────────────────
         // GET /api/config/ai — read current AI config (mask apiKey)
         this.app.get('/api/config/ai', (_req, res) => {
@@ -1178,6 +1587,429 @@ export class WebServer {
                 res.status(500).json({ error: String(err) });
             }
         });
+        // ── Version Management APIs ────────────────────────────────────────────────
+        // GET /api/agents/:name/versions — list backup versions
+        this.app.get('/api/agents/:name/versions', (req, res) => {
+            try {
+                const { name } = req.params;
+                const backupDir = path.join(homedir(), '.claude-forge', 'backups', 'agents');
+                if (!fs.existsSync(backupDir)) {
+                    res.json({ versions: [] });
+                    return;
+                }
+                const files = fs.readdirSync(backupDir)
+                    .filter(f => f.startsWith(`${name}-`) && f.endsWith('.md'))
+                    .map(f => {
+                    const filePath = path.join(backupDir, f);
+                    const stats = fs.statSync(filePath);
+                    const timestampMatch = f.match(/-(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z)\.md$/);
+                    return {
+                        filename: f,
+                        timestamp: timestampMatch ? timestampMatch[1].replace(/-/g, ':').replace(/T(\d{2}):(\d{2}):(\d{2})/, 'T$1:$2:$3') : '',
+                        size: stats.size,
+                        mtime: stats.mtime.toISOString(),
+                    };
+                })
+                    .sort((a, b) => new Date(b.mtime).getTime() - new Date(a.mtime).getTime());
+                res.json({ versions: files });
+            }
+            catch (err) {
+                logger.warn(`[Web] Failed to list agent versions: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // GET /api/agents/:name/versions/:timestamp — get specific version content
+        this.app.get('/api/agents/:name/versions/:timestamp', (req, res) => {
+            try {
+                const { name, timestamp } = req.params;
+                const backupDir = path.join(homedir(), '.claude-forge', 'backups', 'agents');
+                const filename = `${name}-${timestamp}.md`;
+                const filePath = path.join(backupDir, filename);
+                if (!fs.existsSync(filePath)) {
+                    res.status(404).json({ error: 'Version not found' });
+                    return;
+                }
+                const content = fs.readFileSync(filePath, 'utf-8');
+                res.json({ content });
+            }
+            catch (err) {
+                logger.warn(`[Web] Failed to get agent version: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // POST /api/agents/:name/rollback — rollback to a specific version
+        this.app.post('/api/agents/:name/rollback', (req, res) => {
+            try {
+                const { name } = req.params;
+                const { timestamp } = req.body;
+                if (!timestamp) {
+                    res.status(400).json({ error: 'Missing timestamp' });
+                    return;
+                }
+                const agentsDir = path.join(homedir(), '.claude', 'agents');
+                const currentPath = path.join(agentsDir, `${name}.md`);
+                const backupDir = path.join(homedir(), '.claude-forge', 'backups', 'agents');
+                const versionPath = path.join(backupDir, `${name}-${timestamp}.md`);
+                if (!fs.existsSync(currentPath)) {
+                    res.status(404).json({ error: 'Agent not found' });
+                    return;
+                }
+                if (!fs.existsSync(versionPath)) {
+                    res.status(404).json({ error: 'Version not found' });
+                    return;
+                }
+                // Backup current version before rollback
+                fs.mkdirSync(backupDir, { recursive: true });
+                const rollbackTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const rollbackBackupPath = path.join(backupDir, `${name}-${rollbackTimestamp}.md`);
+                fs.copyFileSync(currentPath, rollbackBackupPath);
+                // Restore version
+                const versionContent = fs.readFileSync(versionPath, 'utf-8');
+                fs.writeFileSync(currentPath, versionContent, 'utf-8');
+                logger.info(`[Web] Rolled back agent ${name} to ${timestamp} (backup: ${rollbackBackupPath})`);
+                res.json({ success: true, backup: rollbackBackupPath });
+            }
+            catch (err) {
+                logger.warn(`[Web] Failed to rollback agent: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // GET /api/skills/:name/versions — list backup versions
+        this.app.get('/api/skills/:name/versions', (req, res) => {
+            try {
+                const { name } = req.params;
+                const backupDir = path.join(homedir(), '.claude-forge', 'backups', 'skills');
+                if (!fs.existsSync(backupDir)) {
+                    res.json({ versions: [] });
+                    return;
+                }
+                const files = fs.readdirSync(backupDir)
+                    .filter(f => f.startsWith(`${name}-`) && f.endsWith('.md'))
+                    .map(f => {
+                    const filePath = path.join(backupDir, f);
+                    const stats = fs.statSync(filePath);
+                    const timestampMatch = f.match(/-(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z)\.md$/);
+                    return {
+                        filename: f,
+                        timestamp: timestampMatch ? timestampMatch[1].replace(/-/g, ':').replace(/T(\d{2}):(\d{2}):(\d{2})/, 'T$1:$2:$3') : '',
+                        size: stats.size,
+                        mtime: stats.mtime.toISOString(),
+                    };
+                })
+                    .sort((a, b) => new Date(b.mtime).getTime() - new Date(a.mtime).getTime());
+                res.json({ versions: files });
+            }
+            catch (err) {
+                logger.warn(`[Web] Failed to list skill versions: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // GET /api/skills/:name/versions/:timestamp — get specific version content
+        this.app.get('/api/skills/:name/versions/:timestamp', (req, res) => {
+            try {
+                const { name, timestamp } = req.params;
+                const backupDir = path.join(homedir(), '.claude-forge', 'backups', 'skills');
+                const filename = `${name}-${timestamp}.md`;
+                const filePath = path.join(backupDir, filename);
+                if (!fs.existsSync(filePath)) {
+                    res.status(404).json({ error: 'Version not found' });
+                    return;
+                }
+                const content = fs.readFileSync(filePath, 'utf-8');
+                res.json({ content });
+            }
+            catch (err) {
+                logger.warn(`[Web] Failed to get skill version: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // POST /api/skills/:name/rollback — rollback to a specific version
+        this.app.post('/api/skills/:name/rollback', (req, res) => {
+            try {
+                const { name } = req.params;
+                const { timestamp } = req.body;
+                if (!timestamp) {
+                    res.status(400).json({ error: 'Missing timestamp' });
+                    return;
+                }
+                const skillsDir = path.join(homedir(), '.claude', 'skills');
+                const currentPath = path.join(skillsDir, `${name}.md`);
+                const backupDir = path.join(homedir(), '.claude-forge', 'backups', 'skills');
+                const versionPath = path.join(backupDir, `${name}-${timestamp}.md`);
+                if (!fs.existsSync(currentPath)) {
+                    res.status(404).json({ error: 'Skill not found' });
+                    return;
+                }
+                if (!fs.existsSync(versionPath)) {
+                    res.status(404).json({ error: 'Version not found' });
+                    return;
+                }
+                // Backup current version before rollback
+                fs.mkdirSync(backupDir, { recursive: true });
+                const rollbackTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const rollbackBackupPath = path.join(backupDir, `${name}-${rollbackTimestamp}.md`);
+                fs.copyFileSync(currentPath, rollbackBackupPath);
+                // Restore version
+                const versionContent = fs.readFileSync(versionPath, 'utf-8');
+                fs.writeFileSync(currentPath, versionContent, 'utf-8');
+                logger.info(`[Web] Rolled back skill ${name} to ${timestamp} (backup: ${rollbackBackupPath})`);
+                res.json({ success: true, backup: rollbackBackupPath });
+            }
+            catch (err) {
+                logger.warn(`[Web] Failed to rollback skill: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // ── Execution Trace APIs ──────────────────────────────────────────────────
+        // GET /api/execution-trace — list execution traces with routing info
+        this.app.get('/api/execution-trace', (req, res) => {
+            try {
+                const limit = parseInt(req.query.limit) || 50;
+                const agentFilter = req.query.agent;
+                const obeyedFilter = req.query.obeyed;
+                const db = storage.getDatabase();
+                let sql = `
+          SELECT
+            re.id,
+            re.session_id,
+            re.project_path,
+            re.ts,
+            re.prompt,
+            re.intent_json,
+            re.routed_to_type,
+            re.routed_to_name,
+            re.obeyed,
+            re.classification_ms,
+            re.fallback_used,
+            re.first_tool_name,
+            re.first_tool_ts,
+            re.completed_ts,
+            re.total_execution_ms,
+            re.completion_reason,
+            re.downstream_task_chain,
+            s.status as session_status,
+            s.start_time,
+            s.end_time,
+            s.event_count
+          FROM routing_events re
+          LEFT JOIN sessions s ON re.session_id = s.session_id
+          WHERE 1=1
+        `;
+                const params = [];
+                if (agentFilter) {
+                    sql += ` AND re.routed_to_name = ?`;
+                    params.push(agentFilter);
+                }
+                if (obeyedFilter === 'true') {
+                    sql += ` AND re.obeyed = 1`;
+                }
+                else if (obeyedFilter === 'false') {
+                    sql += ` AND re.obeyed = 0`;
+                }
+                sql += ` ORDER BY re.ts DESC LIMIT ?`;
+                params.push(limit);
+                const rows = db.prepare(sql).all(...params);
+                const traces = rows.map(row => ({
+                    id: row.id,
+                    sessionId: row.session_id,
+                    projectPath: row.project_path,
+                    timestamp: row.ts,
+                    prompt: row.prompt,
+                    intent: JSON.parse(row.intent_json || '{}'),
+                    routedToType: row.routed_to_type,
+                    routedToName: row.routed_to_name,
+                    obeyed: row.obeyed,
+                    classificationMs: row.classification_ms,
+                    fallbackUsed: row.fallback_used === 1,
+                    firstTool: row.first_tool_name,
+                    firstToolTs: row.first_tool_ts,
+                    completedTs: row.completed_ts,
+                    totalExecutionMs: row.total_execution_ms,
+                    completionReason: row.completion_reason,
+                    taskChain: row.downstream_task_chain ? JSON.parse(row.downstream_task_chain) : [],
+                    sessionStatus: row.session_status,
+                    sessionStart: row.start_time,
+                    sessionEnd: row.end_time,
+                    eventCount: row.event_count,
+                }));
+                res.json({ traces });
+            }
+            catch (err) {
+                logger.warn(`[Web] Failed to get execution traces: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // GET /api/execution-trace/:session_id — detailed trace for a session
+        this.app.get('/api/execution-trace/:session_id', (req, res) => {
+            try {
+                const { session_id } = req.params;
+                const db = storage.getDatabase();
+                // Get routing event
+                const routing = db.prepare(`
+          SELECT * FROM routing_events WHERE session_id = ?
+        `).get(session_id);
+                if (!routing) {
+                    res.status(404).json({ error: 'Trace not found' });
+                    return;
+                }
+                // Get all events for this session
+                const events = db.prepare(`
+          SELECT event_id, timestamp, hook_type, tool_name, user_prompt
+          FROM events
+          WHERE session_id = ?
+          ORDER BY timestamp ASC
+        `).all(session_id);
+                // Get injections
+                const injections = db.prepare(`
+          SELECT injection_type, content, timestamp
+          FROM injections
+          WHERE session_id = ?
+          ORDER BY timestamp ASC
+        `).all(session_id);
+                res.json({
+                    routing: {
+                        prompt: routing.prompt,
+                        timestamp: routing.ts,
+                        intent: JSON.parse(routing.intent_json || '{}'),
+                        routedToType: routing.routed_to_type,
+                        routedToName: routing.routed_to_name,
+                        obeyed: routing.obeyed,
+                        classificationMs: routing.classification_ms,
+                        fallbackUsed: routing.fallback_used === 1,
+                        refusalReason: routing.refusal_reason,
+                        firstTool: routing.first_tool_name,
+                        firstToolTs: routing.first_tool_ts,
+                        completedTs: routing.completed_ts,
+                        totalExecutionMs: routing.total_execution_ms,
+                        completionReason: routing.completion_reason,
+                        taskChain: routing.downstream_task_chain ? JSON.parse(routing.downstream_task_chain) : [],
+                    },
+                    events,
+                    injections,
+                });
+            }
+            catch (err) {
+                logger.warn(`[Web] Failed to get trace details for ${req.params.session_id}: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // GET /api/execution-trace/:session_id/status — current status snapshot
+        this.app.get('/api/execution-trace/:session_id/status', (req, res) => {
+            try {
+                const { session_id } = req.params;
+                const db = storage.getDatabase();
+                const routing = db.prepare(`SELECT * FROM routing_events WHERE session_id = ? ORDER BY ts DESC LIMIT 1`).get(session_id);
+                if (!routing) {
+                    res.status(404).json({ error: 'Trace not found' });
+                    return;
+                }
+                const latestToolEvent = db.prepare(`
+          SELECT tool, success, error, timestamp
+          FROM v2_tool_events
+          WHERE session_id = ? AND timestamp >= ?
+          ORDER BY timestamp DESC LIMIT 1
+        `).get(session_id, routing.ts);
+                const latestDecision = db.prepare(`
+          SELECT level, reason, timestamp
+          FROM v2_decisions
+          WHERE session_id = ? AND timestamp >= ?
+          ORDER BY timestamp DESC LIMIT 1
+        `).get(session_id, routing.ts);
+                let status = 'routing';
+                if (latestDecision?.level === 'block' || latestToolEvent?.success === 0)
+                    status = 'failed';
+                else if (routing.completed_ts)
+                    status = 'completed';
+                else if (routing.first_tool_ts || latestToolEvent)
+                    status = 'executing';
+                res.json({
+                    status,
+                    timestamp: routing.ts,
+                    firstTool: routing.first_tool_name ?? latestToolEvent?.tool ?? null,
+                    firstToolTs: routing.first_tool_ts ?? latestToolEvent?.timestamp ?? null,
+                    completedTs: routing.completed_ts ?? null,
+                    totalExecutionMs: routing.total_execution_ms ?? null,
+                    completionReason: routing.completion_reason ?? null,
+                    error: latestToolEvent?.success === 0 ? latestToolEvent.error : (latestDecision?.level === 'block' ? latestDecision.reason : null),
+                });
+            }
+            catch (err) {
+                logger.warn(`[Web] Failed to get trace status for ${req.params.session_id}: ${err}`);
+                res.status(500).json({ error: String(err) });
+            }
+        });
+        // SSE: execution trace live status stream
+        this.app.get('/api/execution-trace/stream', (req, res) => {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                Connection: 'keep-alive',
+            });
+            res.write('data: {"type":"connected"}\n\n');
+            const filterSession = req.query.session;
+            const readOnlyTools = new Set(['Read', 'Grep', 'Glob', 'LS', 'NotebookRead', 'WebFetch', 'WebSearch']);
+            const writeStatus = (payload) => {
+                if (filterSession && payload.sessionId !== filterSession)
+                    return;
+                res.write(`data: ${JSON.stringify(payload)}\n\n`);
+            };
+            const onEvent = (event) => {
+                const hookType = event.hook_type;
+                const toolName = event.tool_name;
+                const sessionId = event.session_id;
+                const timestamp = event.timestamp;
+                if (!sessionId || !hookType)
+                    return;
+                if (hookType === 'UserPromptSubmit') {
+                    writeStatus({ type: 'execution-status', status: 'routing', sessionId, timestamp, prompt: event.user_prompt ?? null });
+                    return;
+                }
+                if (hookType === 'PreToolUse' && toolName && !readOnlyTools.has(toolName)) {
+                    writeStatus({ type: 'execution-status', status: 'executing', sessionId, timestamp, tool: toolName });
+                    return;
+                }
+                if (hookType === 'Stop') {
+                    writeStatus({ type: 'execution-status', status: 'completed', sessionId, timestamp });
+                }
+            };
+            const onToolEvent = (event) => {
+                const sessionId = event.session_id;
+                if (!sessionId)
+                    return;
+                if (event.success === false || event.success === 0) {
+                    writeStatus({
+                        type: 'execution-status',
+                        status: 'failed',
+                        sessionId,
+                        timestamp: event.timestamp ?? Date.now(),
+                        tool: event.tool ?? null,
+                        error: event.error ?? null,
+                    });
+                }
+            };
+            const onDecision = (decision) => {
+                const sessionId = decision.session_id;
+                if (!sessionId)
+                    return;
+                if (decision.level === 'block') {
+                    writeStatus({
+                        type: 'execution-status',
+                        status: 'failed',
+                        sessionId,
+                        timestamp: decision.timestamp ?? Date.now(),
+                        error: decision.reason ?? null,
+                    });
+                }
+            };
+            storage.on('event', onEvent);
+            storage.on('tool-event', onToolEvent);
+            storage.on('decision', onDecision);
+            req.on('close', () => {
+                storage.removeListener('event', onEvent);
+                storage.removeListener('tool-event', onToolEvent);
+                storage.removeListener('decision', onDecision);
+            });
+        });
         // SSE: real-time event stream
         this.app.get('/api/events/stream', (req, res) => {
             res.writeHead(200, {