@winspan/claude-forge 8.50.6 → 8.51.0

package/src/web/routes/skill-stats.ts

@@ -8,6 +8,8 @@ import type { RouteContext } from './types.js';
  *   - /api/skill-stats/distribution — routing type distribution (agent/skill/none)
  *   - /api/skill-stats/frequency — skill usage frequency
  *   - /api/skill-stats/trend — skill usage rate trend over time
+ *
+ * H1: All endpoints now use storage-layer SQL aggregation (no JS GROUP BY).
  */
 export function registerSkillStatsRoutes(app: Application, ctx: RouteContext): void {
   const { storage } = ctx;
@@ -16,23 +18,14 @@ export function registerSkillStatsRoutes(app: Application, ctx: RouteContext): v
   app.get('/api/skill-stats/distribution', (req, res) => {
     const windowHours = parseInt((req.query.window as string) || '168'); // default 7d
     const since = Date.now() - windowHours * 3600 * 1000;
-    const events = storage.queryRoutingEvents({ since_ts: since, limit: 10000 });
-
-    const distribution: Record<string, number> = {
-      agent: 0,
-      skill: 0,
-      none: 0,
-    };
+    const agg = storage.aggregateRoutingStats({ since_ts: since });
 
-    for (const e of events) {
-      const type = e.routed_to_type || 'none';
-      distribution[type] = (distribution[type] || 0) + 1;
+    // Ensure stable ordering and presence of all three buckets (agent/skill/none)
+    const counts: Record<string, number> = { agent: 0, skill: 0, none: 0 };
+    for (const row of agg.by_type) {
+      counts[row.type] = row.count;
     }
-
-    const result = Object.entries(distribution).map(([type, count]) => ({
-      type,
-      count,
-    }));
+    const result = Object.entries(counts).map(([type, count]) => ({ type, count }));
 
     res.json({ windowHours, distribution: result });
   });
@@ -41,19 +34,9 @@ export function registerSkillStatsRoutes(app: Application, ctx: RouteContext): v
   app.get('/api/skill-stats/frequency', (req, res) => {
     const windowHours = parseInt((req.query.window as string) || '168');
     const since = Date.now() - windowHours * 3600 * 1000;
-    const events = storage.queryRoutingEvents({ since_ts: since, limit: 10000 });
-
-    const frequency = new Map<string, number>();
+    const agg = storage.aggregateRoutingStats({ since_ts: since });
 
-    for (const e of events) {
-      if (e.routed_to_type === 'skill' && e.routed_to_name) {
-        frequency.set(e.routed_to_name, (frequency.get(e.routed_to_name) || 0) + 1);
-      }
-    }
-
-    const result = Array.from(frequency.entries())
-      .map(([name, count]) => ({ name, count }))
-      .sort((a, b) => b.count - a.count);
+    const result = agg.by_skill_routed.map(({ skill, count }) => ({ name: skill, count }));
 
     res.json({ windowHours, frequency: result });
   });
@@ -62,25 +45,12 @@ export function registerSkillStatsRoutes(app: Application, ctx: RouteContext): v
   app.get('/api/skill-stats/trend', (req, res) => {
     const windowHours = parseInt((req.query.window as string) || '168');
     const since = Date.now() - windowHours * 3600 * 1000;
-    const events = storage.queryRoutingEvents({ since_ts: since, limit: 10000 });
-
-    // Group by day
-    const dailyStats = new Map<string, { total: number; skill: number }>();
-
-    for (const e of events) {
-      const day = new Date(e.ts).toISOString().split('T')[0];
-      const stats = dailyStats.get(day) || { total: 0, skill: 0 };
-      stats.total++;
-      if (e.routed_to_type === 'skill') {
-        stats.skill++;
-      }
-      dailyStats.set(day, stats);
-    }
+    const rows = storage.aggregateRoutingTrendByDay({ since_ts: since });
 
-    const result = Array.from(dailyStats.entries())
-      .map(([day, stats]) => ({
-        day,
-        skillRate: stats.total > 0 ? Math.round((stats.skill / stats.total) * 100) : 0,
+    const result = rows
+      .map(r => ({
+        day: r.day,
+        skillRate: r.total > 0 ? Math.round((r.skill / r.total) * 100) : 0,
       }))
       .sort((a, b) => a.day.localeCompare(b.day));
 
@@ -91,41 +61,31 @@ export function registerSkillStatsRoutes(app: Application, ctx: RouteContext): v
   app.get('/api/skill-stats/invocations', (req, res) => {
     const days = parseInt((req.query.days as string) || '7');
     const since = Date.now() - days * 24 * 3600 * 1000;
-    const invocations = storage.querySkillInvocations({ since, limit: 1000 });
-
-    const stats = new Map<string, { skill_id: string; total: number; success: number; failed: number }>();
-    for (const inv of invocations) {
-      const cur = stats.get(inv.skill_id) || { skill_id: inv.skill_id, total: 0, success: 0, failed: 0 };
-      cur.total++;
-      if (inv.success === 1) cur.success++;
-      else cur.failed++;
-      stats.set(inv.skill_id, cur);
-    }
+    const rows = storage.aggregateSkillInvocationsBySkill({ since });
+
+    const total = rows.reduce((sum, r) => sum + r.total, 0);
+    const result = rows.map(r => ({
+      skill_id: r.skill_id,
+      total: r.total,
+      success: r.success,
+      failed: r.failed,
+    }));
 
-    const result = Array.from(stats.values()).sort((a, b) => b.total - a.total);
-    res.json({ days, total: invocations.length, invocations: result });
+    res.json({ days, total, invocations: result });
   });
 
   // Routing/Agent call rate stats
   app.get('/api/routing/stats', (req, res) => {
     const days = parseInt((req.query.days as string) || '7');
     const since = Date.now() - days * 24 * 3600 * 1000;
-    const events = storage.queryRoutingEvents({ since_ts: since, limit: 10000 });
+    const agg = storage.aggregateRoutingStats({ since_ts: since });
 
-    const total = events.length;
-    const agentCalls = events.filter(e => e.obeyed === 1).length;
+    const total = agg.total;
+    const agentCalls = agg.obeyed;
     const noAgent = total - agentCalls;
     const agentRate = total > 0 ? Math.round((agentCalls / total) * 1000) / 10 : 0;
 
-    const byAgentMap = new Map<string, number>();
-    for (const e of events) {
-      if (e.routed_to_name && e.obeyed === 1) {
-        byAgentMap.set(e.routed_to_name, (byAgentMap.get(e.routed_to_name) || 0) + 1);
-      }
-    }
-    const byAgent = Array.from(byAgentMap.entries())
-      .map(([agent, count]) => ({ agent, count }))
-      .sort((a, b) => b.count - a.count);
+    const byAgent = agg.by_agent.map(({ agent, count }) => ({ agent, count }));
 
     res.json({ days, total, agentCalls, noAgent, agentRate, byAgent });
   });

package/src/web/routes/skills.ts

@@ -4,6 +4,7 @@ import path from 'path';
 import { homedir } from 'os';
 import { logger } from '../../core/utils/logger.js';
 import type { RouteContext } from './types.js';
+import { FORGE_PATHS } from '../../core/constants.js';
 
 /**
  * /api/skills/* — list, read, update, version, rollback.
@@ -205,7 +206,7 @@ export function registerSkillsRoutes(app: Application, ctx: RouteContext): void
         return;
       }
 
-      const backupDir = path.join(homedir(), '.claude-forge', 'backups', 'skills');
+      const backupDir = FORGE_PATHS.backups('skills');
       fs.mkdirSync(backupDir, { recursive: true });
       const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
       const backupPath = path.join(backupDir, `${name}-${timestamp}.md`);
@@ -232,7 +233,7 @@ export function registerSkillsRoutes(app: Application, ctx: RouteContext): void
         return;
       }
 
-      const backupDir = path.join(homedir(), '.claude-forge', 'backups', 'skills');
+      const backupDir = FORGE_PATHS.backups('skills');
 
       if (!fs.existsSync(backupDir)) {
         res.json({ versions: [] });
@@ -276,7 +277,7 @@ export function registerSkillsRoutes(app: Application, ctx: RouteContext): void
         return;
       }
 
-      const backupDir = path.join(homedir(), '.claude-forge', 'backups', 'skills');
+      const backupDir = FORGE_PATHS.backups('skills');
       const filename = `${name}-${timestamp}.md`;
       const filePath = path.join(backupDir, filename);
 
@@ -318,7 +319,7 @@ export function registerSkillsRoutes(app: Application, ctx: RouteContext): void
 
       const skillsDir = path.join(homedir(), '.claude', 'skills');
       const currentPath = path.join(skillsDir, `${name}.md`);
-      const backupDir = path.join(homedir(), '.claude-forge', 'backups', 'skills');
+      const backupDir = FORGE_PATHS.backups('skills');
       const versionPath = path.join(backupDir, `${name}-${timestamp}.md`);
 
       if (!fs.existsSync(currentPath)) {

package/src/web/routes/stats.ts

@@ -3,51 +3,41 @@ import type { RouteContext } from './types.js';
 
 /**
  * /api/stats — System-wide statistics for the Dashboard.
+ *
+ * H2 Phase 3: 替换原 db.prepare 直写 SQL 为 SQLiteStorage facade 聚合方法。
+ * 响应 shape 保持不变（前端契约）：totalSessions / totalEvents / toolUsage /
+ * dailyActivity / skillInvocations。
  */
 export function registerStatsRoutes(app: Application, ctx: RouteContext): void {
   const { storage } = ctx;
 
   app.get('/api/stats', (_req, res) => {
-    const db = storage.getDatabase();
+    const totalEvents = storage.countAllEvents();
+    const totalSessions = storage.countAllSessions();
 
-    const totalEvents = (db.prepare('SELECT COUNT(*) as cnt FROM events').get() as any).cnt;
-    const totalSessions = (db.prepare('SELECT COUNT(*) as cnt FROM sessions').get() as any).cnt;
-
-    // Tool usage distribution
-    const toolRows = db.prepare(
-      `SELECT tool_name, COUNT(*) as cnt FROM events
-       WHERE tool_name IS NOT NULL AND tool_name != ''
-       GROUP BY tool_name ORDER BY cnt DESC LIMIT 15`
-    ).all() as Array<{ tool_name: string; cnt: number }>;
+    // Tool usage distribution (top 15)
+    const toolRows = storage.aggregateToolUsage({ limit: 15 });
     const toolUsage: Record<string, number> = {};
     for (const r of toolRows) {
-      toolUsage[r.tool_name] = r.cnt;
+      toolUsage[r.tool_name] = r.count;
     }
 
     // Daily activity (last 7 days)
-    const dailyRows = db.prepare(
-      `SELECT date(timestamp) as d, COUNT(*) as eventCount
-       FROM events
-       WHERE timestamp >= date('now', '-7 days')
-       GROUP BY d ORDER BY d`
-    ).all() as Array<{ d: string; eventCount: number }>;
-
-    const sessionDailyRows = db.prepare(
-      `SELECT date(start_time) as d, COUNT(*) as sessionCount
-       FROM sessions
-       WHERE start_time >= date('now', '-7 days')
-       GROUP BY d ORDER BY d`
-    ).all() as Array<{ d: string; sessionCount: number }>;
+    // 旧 SQL: timestamp >= date('now', '-7 days')
+    // 新口径：调用方计算 ISO 字符串，传给 facade。
+    const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const dailyRows = storage.aggregateDailyEventCounts({ since: sevenDaysAgo });
+    const sessionDailyRows = storage.aggregateDailySessionCounts({ since: sevenDaysAgo });
 
-    const sessionMap = new Map(sessionDailyRows.map(r => [r.d, r.sessionCount]));
+    const sessionMap = new Map(sessionDailyRows.map(r => [r.date, r.count]));
     const dailyActivity = dailyRows.map(r => ({
-      date: r.d,
-      eventCount: r.eventCount,
-      sessionCount: sessionMap.get(r.d) || 0,
+      date: r.date,
+      eventCount: r.count,
+      sessionCount: sessionMap.get(r.date) || 0,
     }));
 
     // Skill invocation count
-    const skillCount = (db.prepare('SELECT COUNT(*) as cnt FROM skill_invocations').get() as any)?.cnt ?? 0;
+    const skillCount = storage.countAllSkillInvocations();
 
     res.json({
       totalSessions,

package/src/web/routes/tasks.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import type { Application } from 'express';
 import type { RouteContext } from './types.js';
+import { truncateField } from './_helpers.js';
+import { getFilePath, getUserPrompt } from '../../core/event-fields.js';
 
 /**
  * /api/tasks — Task execution view.
@@ -59,28 +61,20 @@ export function registerTasksRoutes(app: Application, ctx: RouteContext): void {
   app.get('/api/tasks/:taskId', (req, res) => {
     const taskId = req.params.taskId;
 
-    // Find the task
-    const allTasks = storage.queryTasks({ limit: 5000 });
-    const task = allTasks.find(t => t.id === taskId);
+    // H1: PK direct fetch (was: queryTasks({limit:5000}).find)
+    const task = storage.getTask(taskId);
     if (!task) {
       res.status(404).json({ error: 'Task not found' });
       return;
     }
 
-    // Get event IDs associated with this task
-    const eventIds = new Set(storage.getTaskEventIds(taskId));
-
-    // Fetch all events for the session, then filter to task events
-    const allEvents = storage.queryEvents({ session_id: task.session_id, limit: 5000 });
-    const taskEvents = allEvents.filter(e => e.event_id && eventIds.has(e.event_id));
-
-    // Sort by timestamp ascending (chronological order)
-    taskEvents.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    // H1: JOIN task_events (was: queryEvents({limit:5000}) + Set.has filter)
+    const taskEvents = storage.queryEventsByTaskId(taskId, { limit: 5000 });
 
     // ── Injections ──────────────────────────────────────────────────────
-    const allInjections = storage.queryInjections({ session_id: task.session_id, limit: 500 });
+    // H1: JOIN task_events (was: queryInjections({limit:500}) + Set.has filter)
+    const allInjections = storage.queryInjectionsByTaskId(taskId);
     const injections = allInjections
-      .filter(inj => inj.event_id && eventIds.has(inj.event_id))
       .map(inj => ({
         id: inj.id,
         timestamp: inj.timestamp,
@@ -92,20 +86,6 @@ export function registerTasksRoutes(app: Application, ctx: RouteContext): void {
       }));
 
     // ── Timeline ────────────────────────────────────────────────────────
-    const truncateField = (obj: unknown, maxLen = 300): unknown => {
-      if (!obj) return obj;
-      if (typeof obj === 'string') return obj.length > maxLen ? obj.slice(0, maxLen) + '...' : obj;
-      if (Array.isArray(obj)) return obj.slice(0, 10);
-      if (typeof obj === 'object') {
-        const result: Record<string, unknown> = {};
-        for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
-          result[k] = truncateField(v, maxLen);
-        }
-        return result;
-      }
-      return obj;
-    };
-
     const timeline = taskEvents
       .filter(e => e.tool_name && (e.hook_type === 'PreToolUse' || e.hook_type === 'PostToolUse'))
       .reduce<Array<{
@@ -129,7 +109,7 @@ export function registerTasksRoutes(app: Application, ctx: RouteContext): void {
           return acc;
         }
 
-        const toolInput = e.tool_input as Record<string, unknown> | null;
+        const toolInput = e.tool_input ?? null;
         const isAgentCall = e.tool_name === 'Agent' || e.tool_name === 'Task';
 
         const entry: (typeof acc)[number] = {
@@ -143,8 +123,8 @@ export function registerTasksRoutes(app: Application, ctx: RouteContext): void {
 
         if (isAgentCall && toolInput) {
           entry.agent_detail = {
-            subagent_type: toolInput.subagent_type as string | undefined,
-            name: toolInput.name as string | undefined,
+            subagent_type: typeof toolInput.subagent_type === 'string' ? toolInput.subagent_type : undefined,
+            name: typeof toolInput.name === 'string' ? toolInput.name : undefined,
             prompt: typeof toolInput.prompt === 'string'
               ? toolInput.prompt
               : undefined,
@@ -156,15 +136,10 @@ export function registerTasksRoutes(app: Application, ctx: RouteContext): void {
       }, []);
 
     // ── Skill Invocations ───────────────────────────────────────────────
-    const allSkillInvocations = storage.querySkillInvocations({ session_id: task.session_id, limit: 200 });
-    // Filter by timestamp range of the task
-    const taskStart = task.start_time;
-    const taskEnd = task.end_time || new Date().toISOString();
-    const taskStartMs = new Date(taskStart).getTime();
-    const taskEndMs = new Date(taskEnd).getTime();
+    // H1: SQL window filter (was: querySkillInvocations({limit:200}) + JS time filter)
+    const allSkillInvocations = storage.querySkillInvocationsByTaskWindow(taskId);
 
     const skillInvocations = allSkillInvocations
-      .filter(si => si.timestamp >= taskStartMs && si.timestamp <= taskEndMs)
       .map(si => ({
         id: si.id,
         skill_id: si.skill_id,
@@ -184,17 +159,17 @@ export function registerTasksRoutes(app: Application, ctx: RouteContext): void {
       taskEvents
         .filter(e =>
           (e.tool_name === 'Edit' || e.tool_name === 'Write') &&
-          (e.tool_input as Record<string, unknown> | null)?.file_path,
+          getFilePath(e),
         )
-        .map(e => (e.tool_input as Record<string, unknown>).file_path as string),
+        .map(e => getFilePath(e)!),
     )];
 
     // ── User Prompts ────────────────────────────────────────────────────
     const userPrompts = taskEvents
-      .filter(e => e.hook_type === 'UserPromptSubmit' && (e.user_prompt || (e.tool_input as any)?.user_prompt))
+      .filter(e => e.hook_type === 'UserPromptSubmit' && getUserPrompt(e))
       .map(e => ({
         timestamp: e.timestamp,
-        content: e.user_prompt || (e.tool_input as any)?.user_prompt,
+        content: getUserPrompt(e),
       }));
 
     res.json({

package/src/web/routes/trace.ts

@@ -92,7 +92,7 @@ export function registerTraceRoutes(app: Application, ctx: RouteContext): void {
     }
 
     // 4. Query session details
-    const db = storage.getDatabase();
+    // H2 Phase 3: 改用 facade 聚合方法，消除 db.prepare 直写。
     const allSessions = storage.querySessions({ limit: 5000 });
     const sessionDetails = sessionIds.map(sid => {
       const session = allSessions.find(s => s.session_id === sid || s.session_id.startsWith(sid));
@@ -103,21 +103,9 @@ export function registerTraceRoutes(app: Application, ctx: RouteContext): void {
       const end = new Date(session.end_time);
       const durationMin = Math.round((end.getTime() - start.getTime()) / 60000);
 
-      const eventBreakdown = db.prepare(`
-        SELECT hook_type, COUNT(*) as cnt FROM events
-        WHERE session_id = ? GROUP BY hook_type
-      `).all(fullId) as Array<{ hook_type: string; cnt: number }>;
-
-      const agentRows = db.prepare(`
-        SELECT json_extract(tool_input, '$.subagent_type') as agent_type, COUNT(*) as cnt
-        FROM events
-        WHERE session_id = ? AND tool_name IN ('Agent', 'Task') AND tool_input IS NOT NULL
-        GROUP BY agent_type
-      `).all(fullId) as Array<{ agent_type: string | null; cnt: number }>;
-
-      const skillRows = db.prepare(`
-        SELECT DISTINCT skill_id FROM skill_invocations WHERE session_id = ?
-      `).all(fullId) as Array<{ skill_id: string }>;
+      const eventBreakdown = storage.aggregateHookTypeBySession(fullId);
+      const agentRows = storage.aggregateAgentTypeBySession(fullId);
+      const skillIds = storage.queryDistinctSkillIdsBySession(fullId);
 
       return {
         session_id: fullId,
@@ -127,9 +115,9 @@ export function registerTraceRoutes(app: Application, ctx: RouteContext): void {
         end_time: session.end_time,
         duration_min: durationMin,
         event_count: session.event_count,
-        event_breakdown: Object.fromEntries(eventBreakdown.map(r => [r.hook_type, r.cnt])),
-        agent_calls: agentRows.filter(r => r.agent_type).map(r => ({ type: r.agent_type, count: r.cnt })),
-        skills: skillRows.map(r => r.skill_id),
+        event_breakdown: Object.fromEntries(eventBreakdown.map(r => [r.hook_type, r.count])),
+        agent_calls: agentRows.filter(r => r.agent_type).map(r => ({ type: r.agent_type, count: r.count })),
+        skills: skillIds,
       };
     });
 

package/src/web/routes/types.ts

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'url';
 import { homedir } from 'os';
 import type { SQLiteStorage } from '../../core/storage/sqlite.js';
 import type { SkillRegistry } from '../../skills/registry.js';
+import { FORGE_PATHS } from '../../core/constants.js';
 
 export interface RouteContext {
   storage: SQLiteStorage;
@@ -29,13 +30,13 @@ export function resolvePatchTarget(
   if (targetType === 'skill') {
     return {
       filePath: path.join(homedir(), '.claude', 'skills', `${targetName}.md`),
-      backupDir: path.join(homedir(), '.claude-forge', 'backups', 'skills'),
+      backupDir: FORGE_PATHS.backups('skills'),
     };
   }
   if (targetType === 'routing_rule') {
     return {
-      filePath: path.join(homedir(), '.claude-forge', 'routing.yaml'),
-      backupDir: path.join(homedir(), '.claude-forge', 'backups', 'routing'),
+      filePath: FORGE_PATHS.routingYaml(),
+      backupDir: FORGE_PATHS.backups('routing'),
     };
   }
   throw new Error(`Unsupported targetType: ${targetType}`);

package/tests/integration/claudemd-generator.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Integration test for ClaudeMdGenerator — safety-net for L1 SWARM_PROTOCOL extraction.
+ *
+ * Anchors the SWARM section content (open → projectContent boundary) via SHA256
+ * so that the .md file extraction must produce byte-for-byte identical output.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { ClaudeMdGenerator } from '../../src/claudemd/claudemd-generator.js';
+
+// SWARM section SHA256, captured against the literal-string implementation
+// before extracting to swarm-protocol.md. After extraction, this MUST stay equal.
+const SWARM_SECTION_SHA256 =
+  '260dfe1e48fdecc324419a6330428eaa3597e3fd6e6262cf66cdcf301ca32e18';
+
+/**
+ * Minimal stub for ClaudeProvider — only `complete` is exercised by generate().
+ */
+function makeFailingAi(): any {
+  return {
+    complete: async () => {
+      throw new Error('forced AI failure (safety-net)');
+    },
+  };
+}
+
+describe('ClaudeMdGenerator (safety-net)', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'claudemd-gen-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('generates fallback CLAUDE.md containing all SWARM_PROTOCOL anchors', async () => {
+    const gen = new ClaudeMdGenerator(makeFailingAi());
+    const output = await gen.generate(tmpDir);
+
+    // ── Key field anchors (SWARM section) ──────────────────────────────
+    expect(output).toContain('# claude-forge 工作区规范');
+    expect(output).toContain('## 自检');
+    expect(output).toContain('Two-Phase Workflow');
+    expect(output).toContain('harness-hotfix');
+    expect(output).toContain('refactor-safe');
+    expect(output).toContain('hybrid-feature-with-safety');
+
+    // ── Total line count ≥ 200 (SWARM ~223 lines + fallback) ───────────
+    const lineCount = output.split('\n').length;
+    expect(lineCount).toBeGreaterThanOrEqual(200);
+  });
+
+  it('SWARM section hash is stable across literal/file-loaded implementations', async () => {
+    const gen = new ClaudeMdGenerator(makeFailingAi());
+    const output = await gen.generate(tmpDir);
+
+    // Split SWARM from projectContent: fallback always starts with sectionOverview ("## 项目概述").
+    // SWARM_PROTOCOL ends with "\n" + "\n\n" separator, so the boundary is the first
+    // "\n\n## 项目概述" occurrence — everything before that is the SWARM section.
+    const boundary = output.indexOf('\n\n## 项目概述');
+    expect(boundary).toBeGreaterThan(0);
+
+    // Include the trailing newline of SWARM_PROTOCOL (it ends with `\n`), exclude the `\n\n` separator.
+    const swarmSection = output.slice(0, boundary + 1);
+
+    const hash = createHash('sha256').update(swarmSection, 'utf-8').digest('hex');
+
+    // Print for first-run baseline capture (visible with --reporter=verbose).
+    // eslint-disable-next-line no-console
+    console.log('[safety-net] SWARM_SECTION_SHA256 =', hash);
+    // eslint-disable-next-line no-console
+    console.log('[safety-net] SWARM section length =', swarmSection.length, 'bytes');
+
+    // Sanity: SWARM section must be substantial.
+    expect(swarmSection.length).toBeGreaterThan(4000);
+    expect(swarmSection.startsWith('# claude-forge 工作区规范')).toBe(true);
+    expect(swarmSection.endsWith('（由 daemon 自动更新，记录最近任务上下文）\n\n')).toBe(true);
+
+    // If a known hash is set (non-placeholder), assert equality.
+    // The placeholder below is the all-zero-ish string used on first run; replaced
+    // automatically by the orchestration script once baseline is captured.
+    expect(hash).toBe(SWARM_SECTION_SHA256);
+  });
+});