feat: implement unified audit system v3.0 with crash-safety and self-healing

## Unified Audit System (v3.0) - Implemented crash-safe, append-only logging to audit-logs/{hostname}_{sessionId}/ - Added session.json with comprehensive metrics (timing, cost, attempts) - Agent execution logs with turn-by-turn detail - Prompt snapshots saved to audit-logs/.../prompts/{agent}.md - SessionMutex prevents race conditions during parallel execution - Self-healing reconciliation before every CLI command ## Session Metadata Standardization - Fixed critical bug: standardized on 'id' field (not 'sessionId') throughout codebase - Updated: shannon.mjs (recon, report), src/phases/pre-recon.js - Added validation in AuditSession to fail fast on incorrect field usage - JavaScript shorthand syntax was causing wrong field names ## Schema Improvements - session.json: Added cost_usd per phase, removed redundant final_cost_usd - Renamed 'percentage' -> 'duration_percentage' for clarity - Simplified agent metrics to single total_cost_usd field - Removed unused validation object from schema ## Legacy System Removal - Removed savePromptSnapshot() - prompts now only saved by audit system - Removed target repo pollution (prompt-snapshots/ no longer created) - Single source of truth: audit-logs/{hostname}_{sessionId}/prompts/ ## Export Script Simplification - Removed JSON export mode (session.json already exists) - CSV-only export with clean columns: agent, phase, status, attempts, duration_ms, cost_usd - Tested on real session data ## Documentation - Updated CLAUDE.md with audit system architecture - Added .gitignore entry for audit-logs/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-22 16:09:08 -07:00
parent a9e00ca19f
commit 27334a4dd6
18 changed files with 1871 additions and 206 deletions
@@ -0,0 +1,313 @@
+/**
+ * Audit Session - Main Facade
+ *
+ * Coordinates logger, metrics tracker, and concurrency control for comprehensive
+ * crash-safe audit logging.
+ */
+
+import { AgentLogger } from './logger.js';
+import { MetricsTracker } from './metrics-tracker.js';
+import { initializeAuditStructure, formatTimestamp } from './utils.js';
+
+/**
+ * SessionMutex for concurrency control
+ * (Identical to session-manager.js implementation)
+ */
+class SessionMutex {
+  constructor() {
+    this.locks = new Map();
+  }
+
+  async lock(sessionId) {
+    if (this.locks.has(sessionId)) {
+      // Wait for existing lock to be released
+      await this.locks.get(sessionId);
+    }
+
+    let resolve;
+    const promise = new Promise(r => resolve = r);
+    this.locks.set(sessionId, promise);
+
+    return () => {
+      this.locks.delete(sessionId);
+      resolve();
+    };
+  }
+}
+
+// Global mutex instance
+const sessionMutex = new SessionMutex();
+
+/**
+ * AuditSession - Main audit system facade
+ */
+export class AuditSession {
+  /**
+   * @param {Object} sessionMetadata - Session metadata from Shannon store
+   * @param {string} sessionMetadata.id - Session UUID
+   * @param {string} sessionMetadata.webUrl - Target web URL
+   * @param {string} [sessionMetadata.repoPath] - Target repository path
+   */
+  constructor(sessionMetadata) {
+    this.sessionMetadata = sessionMetadata;
+    this.sessionId = sessionMetadata.id;
+
+    // Validate required fields
+    if (!this.sessionId) {
+      throw new Error('sessionMetadata.id is required');
+    }
+    if (!this.sessionMetadata.webUrl) {
+      throw new Error('sessionMetadata.webUrl is required');
+    }
+
+    // Components
+    this.metricsTracker = new MetricsTracker(sessionMetadata);
+
+    // Active logger (one at a time per agent attempt)
+    this.currentLogger = null;
+
+    // Initialization flag
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize audit session (creates directories, session.json)
+   * Idempotent and race-safe
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    if (this.initialized) {
+      return; // Already initialized
+    }
+
+    // Create directory structure
+    await initializeAuditStructure(this.sessionMetadata);
+
+    // Initialize metrics tracker (loads or creates session.json)
+    await this.metricsTracker.initialize();
+
+    this.initialized = true;
+  }
+
+  /**
+   * Ensure initialized (helper for lazy initialization)
+   * @private
+   * @returns {Promise<void>}
+   */
+  async ensureInitialized() {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+  }
+
+  /**
+   * Log session-level failure (pre-agent failures)
+   * @param {Error} error - Error object
+   * @param {Object} context - Additional context
+   * @returns {Promise<void>}
+   */
+  async logSessionFailure(error, context = {}) {
+    await this.ensureInitialized();
+
+    // Update session status
+    await this.metricsTracker.updateSessionStatus('failed');
+
+    // Create a special failure logger
+    const failureLogger = new AgentLogger(this.sessionMetadata, 'session-failure', 1);
+    await failureLogger.initialize();
+
+    await failureLogger.logError(error, {
+      ...context,
+      timestamp: formatTimestamp(),
+      sessionId: this.sessionId
+    });
+
+    await failureLogger.close();
+  }
+
+  /**
+   * Start agent execution
+   * @param {string} agentName - Agent name
+   * @param {string} promptContent - Full prompt content
+   * @param {number} [attemptNumber=1] - Attempt number
+   * @returns {Promise<void>}
+   */
+  async startAgent(agentName, promptContent, attemptNumber = 1) {
+    await this.ensureInitialized();
+
+    // Save prompt snapshot (only on first attempt)
+    if (attemptNumber === 1) {
+      await AgentLogger.savePrompt(this.sessionMetadata, agentName, promptContent);
+    }
+
+    // Create and initialize logger for this attempt
+    this.currentLogger = new AgentLogger(this.sessionMetadata, agentName, attemptNumber);
+    await this.currentLogger.initialize();
+
+    // Start metrics tracking
+    this.metricsTracker.startAgent(agentName, attemptNumber);
+
+    // Log start event
+    await this.currentLogger.logEvent('agent_start', {
+      agentName,
+      attemptNumber,
+      timestamp: formatTimestamp()
+    });
+  }
+
+  /**
+   * Log event during agent execution
+   * @param {string} eventType - Event type (tool_start, tool_end, llm_response, etc.)
+   * @param {Object} eventData - Event data
+   * @returns {Promise<void>}
+   */
+  async logEvent(eventType, eventData) {
+    if (!this.currentLogger) {
+      throw new Error('No active logger. Call startAgent() first.');
+    }
+
+    await this.currentLogger.logEvent(eventType, eventData);
+  }
+
+  /**
+   * Log a text message (for compatibility)
+   * @param {string} message - Message to log
+   * @returns {Promise<void>}
+   */
+  async logMessage(message) {
+    if (!this.currentLogger) {
+      throw new Error('No active logger. Call startAgent() first.');
+    }
+
+    await this.currentLogger.logMessage(message);
+  }
+
+  /**
+   * End agent execution (mutex-protected)
+   * @param {string} agentName - Agent name
+   * @param {Object} result - Execution result
+   * @param {number} result.attemptNumber - Attempt number
+   * @param {number} result.duration_ms - Duration in milliseconds
+   * @param {number} result.cost_usd - Cost in USD
+   * @param {boolean} result.success - Whether attempt succeeded
+   * @param {string} [result.error] - Error message (if failed)
+   * @param {string} [result.checkpoint] - Git checkpoint hash (if succeeded)
+   * @param {boolean} [result.isFinalAttempt=false] - Whether this is the final attempt
+   * @returns {Promise<void>}
+   */
+  async endAgent(agentName, result) {
+    // Log end event
+    if (this.currentLogger) {
+      await this.currentLogger.logEvent('agent_end', {
+        agentName,
+        success: result.success,
+        duration_ms: result.duration_ms,
+        cost_usd: result.cost_usd,
+        timestamp: formatTimestamp()
+      });
+
+      // Close logger
+      await this.currentLogger.close();
+      this.currentLogger = null;
+    }
+
+    // Mutex-protected update to session.json
+    const unlock = await sessionMutex.lock(this.sessionId);
+    try {
+      // Reload metrics (in case of parallel updates)
+      await this.metricsTracker.reload();
+
+      // Update metrics
+      await this.metricsTracker.endAgent(agentName, result);
+    } finally {
+      unlock();
+    }
+  }
+
+  /**
+   * Update validation results
+   * @param {string} agentName - Agent name
+   * @param {Object} validationData - Validation data
+   * @returns {Promise<void>}
+   */
+  async updateValidation(agentName, validationData) {
+    await this.ensureInitialized();
+
+    const unlock = await sessionMutex.lock(this.sessionId);
+    try {
+      await this.metricsTracker.reload();
+      await this.metricsTracker.updateValidation(agentName, validationData);
+    } finally {
+      unlock();
+    }
+  }
+
+  /**
+   * Mark agent as rolled back
+   * @param {string} agentName - Agent name
+   * @returns {Promise<void>}
+   */
+  async markRolledBack(agentName) {
+    await this.ensureInitialized();
+
+    const unlock = await sessionMutex.lock(this.sessionId);
+    try {
+      await this.metricsTracker.reload();
+      await this.metricsTracker.markRolledBack(agentName);
+    } finally {
+      unlock();
+    }
+  }
+
+  /**
+   * Mark multiple agents as rolled back
+   * @param {string[]} agentNames - Array of agent names
+   * @returns {Promise<void>}
+   */
+  async markMultipleRolledBack(agentNames) {
+    await this.ensureInitialized();
+
+    const unlock = await sessionMutex.lock(this.sessionId);
+    try {
+      await this.metricsTracker.reload();
+      await this.metricsTracker.markMultipleRolledBack(agentNames);
+    } finally {
+      unlock();
+    }
+  }
+
+  /**
+   * Update session status
+   * @param {string} status - New status (in-progress, completed, failed)
+   * @returns {Promise<void>}
+   */
+  async updateSessionStatus(status) {
+    await this.ensureInitialized();
+
+    const unlock = await sessionMutex.lock(this.sessionId);
+    try {
+      await this.metricsTracker.reload();
+      await this.metricsTracker.updateSessionStatus(status);
+    } finally {
+      unlock();
+    }
+  }
+
+  /**
+   * Get current metrics (read-only)
+   * @returns {Promise<Object>} Current metrics
+   */
+  async getMetrics() {
+    await this.ensureInitialized();
+    return this.metricsTracker.getMetrics();
+  }
+
+  /**
+   * Get validation results (read-only)
+   * @returns {Promise<Object>} Validation results
+   */
+  async getValidation() {
+    await this.ensureInitialized();
+    return this.metricsTracker.getValidation();
+  }
+}