@winspan/claude-forge 8.41.0 → 8.50.6

package/src/daemon/handlers/stop.ts

@@ -0,0 +1,215 @@
+/**
+ * StopHandler — handles Stop hook
+ *
+ * Responsibilities:
+ * 1. Mark current task complete
+ * 2. Save resume info
+ * 3. Export session history
+ * 4. Clear skill invocation guard
+ */
+
+import type { StopEvent, HookResult } from '../../core/types.js';
+import type { HistoryExporter } from './history-exporter.js';
+import type { ResumeManager } from '../../claudemd/resume-manager.js';
+import type { TaskSegmenter } from '../services/task-segmenter.js';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import type { InvocationGuard } from '../../skills/invocation-guard.js';
+import type { UserPromptHandler } from './user-prompt.js';
+import { logger } from '../../core/utils/logger.js';
+import { execFileSync } from 'node:child_process';
+import { formatError, truncateString } from '../../core/utils/format.js';
+import { truncateSessionId } from '../../core/utils/session.js';
+
+export class StopHandler {
+  constructor(
+    private exporter: HistoryExporter,
+    private resume: ResumeManager | null = null,
+    private taskSegmenter: TaskSegmenter | null = null,
+    private storage: SQLiteStorage | null = null,
+    private invocationGuard: InvocationGuard | null = null,
+    private userPromptHandler: UserPromptHandler | null = null,
+  ) {}
+
+  async handle(event: StopEvent): Promise<HookResult> {
+    try {
+      // 1. Mark current task complete
+      if (this.taskSegmenter) {
+        try {
+          this.taskSegmenter.completeCurrentTask(event.session_id, event.timestamp);
+        } catch (err) {
+          logger.debug(`[Stop] task completion failed: ${formatError(err)}`);
+        }
+      }
+
+      // 2. Save resume info with behavior summary
+      if (this.resume) {
+        let resumeContent = this.resume.generate(event.session_id, event.project_path);
+        if (resumeContent) {
+          // Append behavior summary before saving
+          const behaviorSummary = this.generateBehaviorSummary(event.session_id);
+          if (behaviorSummary) {
+            resumeContent = this.appendBehaviorSummary(resumeContent, behaviorSummary);
+          }
+          this.resume.save(event.project_path, resumeContent);
+          logger.info(`[Stop] Resume saved for ${event.project_path}`);
+        }
+      }
+
+      // 3. Export history
+      logger.info(`[Stop] Exporting history for session ${event.session_id}`);
+      await this.exporter.export(event);
+
+      // 4. Clear skill invocation guard for this session
+      if (this.invocationGuard) {
+        try {
+          this.invocationGuard.clear(event.session_id);
+          logger.debug(`[Stop] InvocationGuard cleared for session ${truncateSessionId(event.session_id)}`);
+        } catch (err) {
+          logger.debug(`[Stop] InvocationGuard clear failed: ${formatError(err)}`);
+        }
+      }
+
+      // 5. Clear UserPromptHandler injection tracking for this session
+      if (this.userPromptHandler) {
+        try {
+          const sessionKey = `${event.session_id}:${event.project_path}`;
+          this.userPromptHandler.clearSession(sessionKey);
+          logger.debug(`[Stop] UserPromptHandler session cleared for ${truncateSessionId(event.session_id)}`);
+        } catch (err) {
+          logger.debug(`[Stop] UserPromptHandler clear failed: ${formatError(err)}`);
+        }
+      }
+
+      // 6. Write session_id to git note on HEAD commit
+      this.writeGitNote(event);
+
+      return { allow: true };
+    } catch (err) {
+      logger.warn(`[Stop] Handler failed: ${formatError(err)}`);
+      return { allow: true };
+    }
+  }
+
+  // ── Private: Git Note ──────────────────────────────────────────────────
+
+  /**
+   * Write session_id into a git note on the current HEAD commit.
+   * Uses `git notes append` so multiple sessions can be associated with one commit.
+   * Silently ignores failures (no git repo, no commits, etc.).
+   */
+  private writeGitNote(event: StopEvent): void {
+    const projectPath = event.project_path;
+    if (!projectPath) return;
+
+    try {
+      // Check if inside a git work tree
+      execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+        cwd: projectPath,
+        stdio: 'pipe',
+        timeout: 5000,
+      });
+
+      // Get HEAD commit hash
+      const head = execFileSync('git', ['rev-parse', 'HEAD'], {
+        cwd: projectPath,
+        stdio: 'pipe',
+        timeout: 5000,
+      }).toString().trim();
+
+      if (!head) return;
+
+      // Append session_id to git note on HEAD
+      execFileSync('git', ['notes', 'append', '-m', `forge-session: ${event.session_id}`, head], {
+        cwd: projectPath,
+        stdio: 'pipe',
+        timeout: 5000,
+      });
+
+      logger.debug(`[Stop] Git note appended: forge-session: ${truncateSessionId(event.session_id)} on ${truncateString(head, 8)}`);
+    } catch (err) {
+      logger.debug(`[Stop] Git note write skipped: ${formatError(err)}`);
+    }
+  }
+
+  // ── Private: Behavior Summary ──────────────────────────────────────────
+
+  /**
+   * Generate a brief behavior summary for the session by querying event stats.
+   */
+  private generateBehaviorSummary(sessionId: string): string | null {
+    if (!this.storage) return null;
+
+    try {
+      const db = this.storage.getDatabase();
+
+      // 1. Tool usage stats
+      const toolStats = db.prepare(`
+        SELECT tool_name, COUNT(*) as count FROM events
+        WHERE session_id = ? AND tool_name IS NOT NULL
+        GROUP BY tool_name ORDER BY count DESC
+      `).all(sessionId) as Array<{ tool_name: string; count: number }>;
+
+      const totalToolCalls = toolStats.reduce((sum, row) => sum + row.count, 0);
+
+      // 2. Agent/Task delegation stats
+      const agentStats = db.prepare(`
+        SELECT json_extract(tool_input, '$.subagent_type') as agent_type, COUNT(*) as count
+        FROM events
+        WHERE session_id = ? AND tool_name IN ('Agent', 'Task') AND tool_input IS NOT NULL
+        GROUP BY agent_type
+      `).all(sessionId) as Array<{ agent_type: string | null; count: number }>;
+
+      const totalAgentCalls = agentStats.reduce((sum, row) => sum + row.count, 0);
+      const agentNames = agentStats
+        .filter(row => row.agent_type)
+        .map(row => row.agent_type as string);
+
+      // 3. Skill invocation count
+      const skillRow = db.prepare(`
+        SELECT COUNT(*) as count FROM skill_invocations WHERE session_id = ?
+      `).get(sessionId) as { count: number } | undefined;
+
+      const skillCount = skillRow?.count ?? 0;
+
+      // Build summary
+      if (totalToolCalls === 0) return null;
+
+      const parts: string[] = [];
+      parts.push(`工具调用 ${totalToolCalls} 次`);
+
+      if (totalAgentCalls > 0) {
+        const agentDetail = agentNames.length > 0
+          ? ` (${agentNames.slice(0, 3).join(', ')})`
+          : '';
+        parts.push(`Agent 委托 ${totalAgentCalls} 次${agentDetail}`);
+      } else {
+        parts.push('Agent 委托 0 次');
+      }
+
+      parts.push(`Skill 调用 ${skillCount} 次`);
+
+      return `**会话行为**: ${parts.join(' | ')}`;
+    } catch (err) {
+      logger.debug(`[Stop] Behavior summary generation failed: ${formatError(err)}`);
+      return null;
+    }
+  }
+
+  /**
+   * Append behavior summary to resume content, inserting before the timestamp line.
+   */
+  private appendBehaviorSummary(resumeContent: string, summary: string): string {
+    // Insert before the final "_生成时间:" line
+    const timestampPattern = /\n_生成时间:/;
+    const match = resumeContent.match(timestampPattern);
+    if (match && match.index !== undefined) {
+      return (
+        resumeContent.slice(0, match.index) +
+        '\n' + summary + '\n' +
+        resumeContent.slice(match.index)
+      );
+    }
+    // Fallback: append at end
+    return resumeContent + '\n' + summary;
+  }
+}

package/src/daemon/handlers/user-prompt.ts

@@ -0,0 +1,188 @@
+/**
+ * UserPromptHandler — handles UserPromptSubmit hook
+ *
+ * Pipeline:
+ *   1. Inject one-shot context (resume, convention — first prompt of session)
+ *   2. Skill fallback (inject skill guidance if matched)
+ */
+
+import type { UserPromptSubmitEvent, HookResult } from '../../core/types.js';
+import type { ResumeManager } from '../../claudemd/resume-manager.js';
+import type { ConventionExtractor } from '../../claudemd/convention-extractor.js';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import type { SkillRegistry } from '../../skills/registry.js';
+import { logger } from '../../core/utils/logger.js';
+import { randomUUID } from 'node:crypto';
+import { truncateString } from '../../core/utils/format.js';
+
+export class UserPromptHandler {
+  private resumeInjected = new Map<string, number>();
+  private conventionInjected = new Map<string, number>();
+  private static readonly MAX_INJECTION_KEYS = 1000;
+
+  constructor(
+    private resume: ResumeManager | null = null,
+    private conventionExtractor: ConventionExtractor | null = null,
+    private storage: SQLiteStorage | null = null,
+    private skillRegistry: SkillRegistry | null = null,
+  ) {}
+
+  async handle(event: UserPromptSubmitEvent): Promise<HookResult> {
+    // UserPromptSubmitEvent.user_prompt is guaranteed by isUserPromptSubmit guard.
+    const prompt = event.user_prompt;
+    if (!prompt) {
+      return { allow: true };
+    }
+
+    try {
+      const sessionKey = `${event.session_id}:${event.project_path}`;
+      const contextParts: string[] = [];
+      const systemParts: string[] = [];
+
+      // 1. Resume (once per session)
+      if (this.resume && !this.hasInjected(this.resumeInjected, sessionKey)) {
+        this.markInjected(this.resumeInjected, sessionKey);
+        const resumeContent = this.resume.load(event.project_path);
+        if (resumeContent) {
+          contextParts.push(
+            `━━━ Forge Context (Read First) ━━━\n${resumeContent}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+          );
+          logger.info('[UserPrompt] Injected resume context');
+          this.resume.clear(event.project_path);
+        }
+      }
+
+      // 2. Convention (once per session)
+      if (this.conventionExtractor && !this.hasInjected(this.conventionInjected, sessionKey)) {
+        this.markInjected(this.conventionInjected, sessionKey);
+        const convention = this.conventionExtractor.extract(event.project_path);
+        if (convention) {
+          contextParts.push(
+            `━━━ Project Guidance (Read First) ━━━\n${convention}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+          );
+          logger.info('[UserPrompt] Injected project conventions');
+        }
+      }
+
+      // 3. Skill fallback: try skill matching
+      if (this.skillRegistry) {
+        try {
+          const skillMatchResult = await this.skillRegistry.matchWithConfidence(prompt, []);
+          if (skillMatchResult) {
+            const { skill, source } = skillMatchResult;
+            systemParts.push(formatSkillDirective(skill.name, skill.content));
+            logger.info(`[UserPrompt] Skill matched: ${skill.id} (${source})`);
+
+            // Record skill invocation to database
+            if (this.storage) {
+              try {
+                this.storage.writeSkillInvocation({
+                  id: randomUUID(),
+                  route_request_id: null,
+                  session_id: event.session_id,
+                  agent_id: null,
+                  skill_id: skill.id,
+                  invocation_type: 'dynamic',
+                  reason: `Auto-matched by ${source} matching`,
+                  workflow: null,
+                  phase: null,
+                  feature_slug: null,
+                  artifact_path: null,
+                  depth: 0,
+                  success: 1,
+                  error: null,
+                  timestamp: Date.now(),
+                });
+                logger.debug(`[UserPrompt] Recorded skill invocation: ${skill.id}`);
+              } catch (err) {
+                logger.warn(`[UserPrompt] Failed to record skill invocation: ${err}`);
+              }
+            }
+          } else {
+            logger.debug(`[UserPrompt] No skill matched for prompt: "${truncateString(prompt, 80)}"`);
+          }
+        } catch (err) {
+          logger.warn(`[UserPrompt] Skill matching failed: ${err}`);
+        }
+      }
+
+      const result: HookResult = { allow: true };
+      if (contextParts.length > 0) result.additionalContext = contextParts.join('\n\n');
+      if (systemParts.length > 0) result.systemMessage = systemParts.join('\n\n');
+
+      // Write routing_event for observation (Agent spawn tracking)
+      if (this.storage) {
+        try {
+          this.storage.writeRoutingEvent({
+            session_id: event.session_id,
+            project_path: event.project_path,
+            ts: Date.now(),
+            prompt: prompt.substring(0, 500),
+            intent_json: JSON.stringify({ type: 'user_prompt' }),
+            routed_to_type: null,
+            routed_to_name: null,
+            is_forced: 0,
+            obeyed: null,
+          });
+        } catch (err) {
+          logger.debug(`[UserPrompt] Failed to write routing_event: ${err}`);
+        }
+      }
+
+      return result;
+    } catch (err) {
+      logger.warn(`[UserPrompt] Handler failed: ${err}`);
+      return { allow: true };
+    }
+  }
+  // ── Private: Injection tracking helpers ────────────────────────────────
+
+  /** Check if a sessionKey has been injected in the given map. */
+  private hasInjected(map: Map<string, number>, key: string): boolean {
+    return map.has(key);
+  }
+
+  /**
+   * Mark a sessionKey as injected, recording the current timestamp.
+   * If map size reaches MAX_INJECTION_KEYS, evict the oldest entry (LRU cap).
+   */
+  private markInjected(map: Map<string, number>, key: string): void {
+    if (map.size >= UserPromptHandler.MAX_INJECTION_KEYS) {
+      // Evict the entry with the smallest timestamp (oldest)
+      let oldestKey: string | undefined;
+      let oldestTs = Infinity;
+      for (const [k, ts] of map) {
+        if (ts < oldestTs) {
+          oldestTs = ts;
+          oldestKey = k;
+        }
+      }
+      if (oldestKey !== undefined) {
+        map.delete(oldestKey);
+      }
+    }
+    map.set(key, Date.now());
+  }
+
+  // ── Public: Session cleanup ──────────────────────────────────────────────
+
+  /**
+   * Remove injection tracking entries for a given sessionKey.
+   * Called by StopHandler to clean up after a session ends.
+   */
+  public clearSession(sessionKey: string): void {
+    this.resumeInjected.delete(sessionKey);
+    this.conventionInjected.delete(sessionKey);
+  }
+}
+
+/**
+ * Format skill injection directive.
+ */
+function formatSkillDirective(skillName: string, skillContent: string): string {
+  return [
+    `[SKILL: ${skillName}] [AUTO_MATCHED]`,
+    '',
+    skillContent,
+  ].join('\n');
+}

package/src/daemon/index.ts

@@ -0,0 +1,278 @@
+/**
+ * Daemon entry point — starts the Forge daemon process
+ *
+ * Responsibilities:
+ * 1. Load config and initialize logging
+ * 2. Manage lifecycle (PID, socket, auth token)
+ * 3. Initialize storage, AI provider, and core services
+ * 4. Create event handlers and start socket server
+ * 5. Handle graceful shutdown
+ */
+
+import { SocketServer } from './server.js';
+import {
+  writePidFile,
+  removePidFile,
+  cleanSocket,
+  getSocketPath,
+  writeAuthToken,
+  syncMcpToken,
+  removeAuthToken,
+} from './lifecycle.js';
+import { routeEvent, type Handlers } from './router.js';
+import { logger, setLogLevel, LogLevel } from '../core/utils/logger.js';
+import { ConfigManager } from '../core/config.js';
+import { SQLiteStorage } from '../core/storage/sqlite.js';
+import { expandPath } from '../core/utils/path.js';
+import { ClaudeProvider } from '../core/ai/provider.js';
+import { TaskSegmenter } from './services/task-segmenter.js';
+import { SkillRegistry } from '../skills/registry.js';
+import { InvocationGuard } from '../skills/invocation-guard.js';
+import { HistoryExporter } from './handlers/history-exporter.js';
+import { ResumeManager } from '../claudemd/resume-manager.js';
+import { ConventionExtractor } from '../claudemd/convention-extractor.js';
+import { UserPromptHandler } from './handlers/user-prompt.js';
+import { PostToolUseHandler } from './handlers/post-tool-use.js';
+import { StopHandler } from './handlers/stop.js';
+import { replayQueue } from '../core/queue/index.js';
+import type { ForgeEvent } from '../core/types.js';
+import type { HookResponse } from './server.js';
+
+export interface DaemonOptions {
+  /** Whether to enable the web server (default: use config value) */
+  web?: boolean;
+}
+
+export async function startDaemon(foreground: boolean = false, options: DaemonOptions = {}): Promise<void> {
+  // ── 0. Global Exception Handlers ───────────────────────────────────────────
+  process.on('uncaughtException', (err) => {
+    logger.error(`[Daemon] Uncaught exception: ${err.message}`);
+    logger.error(err.stack || '');
+    // Don't exit — let daemon continue running
+  });
+
+  process.on('unhandledRejection', (reason, promise) => {
+    logger.error(`[Daemon] Unhandled rejection at ${promise}: ${reason}`);
+  });
+
+  // ── 1. Config & Logging ────────────────────────────────────────────────────
+  const config = new ConfigManager().get();
+
+  const envLevel = (process.env.LOG_LEVEL ?? '').toLowerCase();
+  const levelMap: Record<string, LogLevel> = {
+    debug: LogLevel.DEBUG, info: LogLevel.INFO, warn: LogLevel.WARN, error: LogLevel.ERROR,
+  };
+  setLogLevel(levelMap[envLevel] ?? LogLevel.INFO);
+  logger.info('Claude Forge daemon starting...');
+
+  // ── 2. Lifecycle (PID, socket, auth token) ─────────────────────────────────
+  cleanSocket();
+  writePidFile();
+  const authToken = writeAuthToken();
+  logger.info('[Security] Auth token generated');
+  syncMcpToken(authToken, config.web?.port ?? 3721);
+
+  // ── 3. Storage ─────────────────────────────────────────────────────────────
+  const dbPath = expandPath(config.storage.path);
+  const storage = new SQLiteStorage(dbPath);
+  logger.info(`Storage initialized: ${dbPath}`);
+
+  // ── 4. AI Provider ─────────────────────────────────────────────────────────
+  const apiKey = config.ai.api_key || process.env.ANTHROPIC_API_KEY || '';
+  if (!apiKey) {
+    logger.warn('No API key configured — AI features disabled');
+  }
+
+  const ai = apiKey
+    ? new ClaudeProvider(apiKey, config.ai.model, config.ai.base_url)
+    : null;
+
+  // ── 5. Initialize services ─────────────────────────────────────────────────
+  const skillApiKey = config.skill_matching?.api_key || apiKey;
+  const skillRegistry = new SkillRegistry(skillApiKey);
+  const invocationGuard = new InvocationGuard();
+  if (skillApiKey) {
+    logger.info('[Skills] Registry loaded with semantic matching support');
+  } else {
+    logger.info('[Skills] Registry loaded (keyword matching)');
+  }
+  logger.info('[Skills] InvocationGuard ready (idempotent + depth/total limits)');
+
+  const exporter = new HistoryExporter(storage);
+  const resume = new ResumeManager(storage);
+  const conventionExtractor = new ConventionExtractor();
+  const taskSegmenter = new TaskSegmenter(storage);
+
+  logger.info('[Services] Initialized: ResumeManager, TaskSegmenter, SkillRegistry');
+
+  // ── 5.5. Schedule daily maintenance ────────────────────────────────────────
+  // Clean old events every 24 hours
+  const MAINTENANCE_INTERVAL = 24 * 60 * 60 * 1000; // 24 hours
+  setInterval(() => {
+    logger.info('[Daemon] Running daily maintenance: cleaning old events');
+    try {
+      storage.cleanOldEvents(30);
+    } catch (err) {
+      logger.error(`[Daemon] Maintenance failed: ${err}`);
+    }
+  }, MAINTENANCE_INTERVAL);
+  logger.info('[Daemon] Scheduled daily maintenance (clean events older than 30 days)');
+
+  // ── 6. Create handlers ─────────────────────────────────────────────────────
+  const userPromptHandler = new UserPromptHandler(
+    resume,
+    conventionExtractor,
+    storage,
+    skillRegistry,
+  );
+
+  const handlers: Handlers = {
+    UserPromptSubmit: userPromptHandler,
+    PostToolUse: new PostToolUseHandler(storage),
+    Stop: new StopHandler(
+      exporter,
+      resume,
+      taskSegmenter,
+      storage,
+      invocationGuard,
+      userPromptHandler,
+    ),
+  };
+
+  // ── 7. Event handler ───────────────────────────────────────────────────────
+  const handleEvent = async (event: ForgeEvent): Promise<HookResponse | void> => {
+    try {
+      try {
+        storage.writeEvent(event);
+      } catch (writeErr) {
+        const writeMsg = writeErr instanceof Error ? writeErr.message : String(writeErr);
+        if (writeMsg.includes('UNIQUE constraint failed')) {
+          // Duplicate event_id — already in DB (e.g. replayed from queue then re-sent).
+          // Log at debug level and continue processing the event normally.
+          logger.debug(`[Event] Duplicate event_id ignored: ${event.event_id}`);
+        } else {
+          throw writeErr;
+        }
+      }
+      logger.debug(`[Event] ${event.hook_type} | tool=${event.tool_name ?? 'N/A'}`);
+
+      // Task segmentation: UserPromptSubmit starts/continues tasks
+      const prompt = event.user_prompt || (event.tool_input as any)?.user_prompt;
+      if (event.hook_type === 'UserPromptSubmit' && prompt) {
+        taskSegmenter.processPrompt(event.session_id, prompt, event.timestamp, event.event_id);
+      } else if (event.event_id) {
+        taskSegmenter.linkEvent(event.session_id, event.event_id);
+      }
+
+      // PreToolUse: always allow (governance removed)
+      if (event.hook_type === 'PreToolUse') {
+        return { allow: true };
+      }
+
+      const result = await routeEvent(event, handlers);
+
+      if (result) {
+        const handlerName = event.hook_type + 'Handler';
+        if (result.systemMessage) {
+          storage.writeInjection({
+            event_id: event.event_id,
+            session_id: event.session_id,
+            timestamp: event.timestamp,
+            source_handler: handlerName,
+            injection_type: 'systemMessage',
+            content: result.systemMessage,
+          });
+          const preview = result.systemMessage.slice(0, 200).replace(/\n/g, ' ');
+          console.error(`\x1b[36m[${handlerName}] systemMessage (${result.systemMessage.length} chars): ${preview}\x1b[0m`);
+        }
+        if (result.additionalContext) {
+          storage.writeInjection({
+            event_id: event.event_id,
+            session_id: event.session_id,
+            timestamp: event.timestamp,
+            source_handler: handlerName,
+            injection_type: 'additionalContext',
+            content: result.additionalContext,
+          });
+          const preview = result.additionalContext.slice(0, 200).replace(/\n/g, ' ');
+          console.error(`\x1b[36m[${handlerName}] additionalContext: ${preview}\x1b[0m`);
+        }
+      }
+
+      return result;
+    } catch (err) {
+      logger.error(`Event handling failed: ${err}`);
+      throw err;
+    }
+  };
+
+  // ── 8. Start socket server ─────────────────────────────────────────────────
+  const socketPath = getSocketPath();
+  const server = new SocketServer(socketPath, handleEvent, authToken);
+
+  // ── 8.1. Replay queued events (hook failures during daemon downtime) ────────
+  // Run after the socket is created so the daemon is ready to receive events.
+  // setImmediate ensures the event loop has had a chance to process the listen
+  // callback before we touch storage (not strictly required, but defensive).
+  setImmediate(() => {
+    replayQueue(storage).then(({ replayed, skipped, dead }) => {
+      if (replayed > 0 || skipped > 0 || dead > 0) {
+        logger.info(`[Queue] Replay: ${replayed} replayed, ${skipped} skipped (dup), ${dead} dead-lettered`);
+      }
+    }).catch((err) => {
+      logger.error(`[Queue] replayQueue failed: ${err}`);
+    });
+  });
+
+  // ── 8.5. Start web server (optional) ───────────────────────────────────────
+  // Priority: CLI option > env var > config file
+  const webEnabled = options.web ?? (process.env.FORGE_DAEMON_NO_WEB === '1' ? false : config.web.enabled);
+  let webServer: any = null;
+  if (webEnabled) {
+    const { WebServer } = await import('../web/server.js');
+    webServer = new WebServer({
+      port: config.web.port,
+      storage,
+      skillRegistry,
+      invocationGuard,
+    });
+    await webServer.start();
+  } else {
+    logger.info('[Web] Server disabled (--no-web or config.web.enabled=false)');
+  }
+
+  // ── 9. Graceful shutdown ───────────────────────────────────────────────────
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    logger.info('Shutting down...');
+
+    if (ai) logger.info(`[AI Stats] ${ai.formatStats()}`);
+
+    if (webServer) await webServer.stop();
+    await server.close();
+    storage.close();
+    removePidFile();
+    cleanSocket();
+    removeAuthToken();
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  logger.info(`Daemon started (PID: ${process.pid})`);
+  if (foreground) {
+    process.stdout.write(`Claude Forge daemon running (PID: ${process.pid})\n`);
+    process.stdout.write('Press Ctrl+C to stop\n');
+  }
+}
+
+// Allow running as standalone script (spawned by `cf daemon start`)
+if (process.env.FORGE_DAEMON_FOREGROUND === '1') {
+  startDaemon(true).catch((err) => {
+    console.error('Daemon failed to start:', err);
+    process.exit(1);
+  });
+}