@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/scripts/session-cleanup.js

@@ -4,7 +4,6 @@
  * SessionEnd cleanup hook.
  *
  * Removes stale planning artifacts that shouldn't persist across sessions:
- *   - .planning/.auto-next (prevents confusion on next session start)
  *   - .planning/.active-operation (stale operation lock)
  *   - .planning/.active-skill (stale skill tracking)
  *
@@ -20,8 +19,13 @@
 
 const fs = require('fs');
 const path = require('path');
-const { logHook } = require('./hook-logger');
-const { tailLines } = require('./pbr-tools');
+const { execSync } = require('child_process');
+const { logHook, getLogFilename: getHooksFilename, cleanOldHookLogs } = require('./hook-logger');
+const { getLogFilename: getEventsFilename, cleanOldEventLogs } = require('./event-logger');
+const { tailLines, configLoad } = require('./pbr-tools');
+const { removeSessionDir, releaseSessionClaims } = require('./lib/core');
+const { readSessionMetrics, summarizeMetrics, formatSessionSummary } = require('./lib/local-llm/metrics');
+const { writeSnapshot } = require('./lib/snapshot-manager');
 
 function readStdin() {
   try {
@@ -46,7 +50,6 @@ function tryRemove(filePath) {
 }
 
 const STALE_CHECKPOINT_MS = 24 * 60 * 60 * 1000; // 24 hours
-const MAX_HOOKS_LOG_BYTES = 200 * 1024; // 200KB
 
 function cleanStaleCheckpoints(planningDir) {
   const removed = [];
@@ -72,22 +75,9 @@ function cleanStaleCheckpoints(planningDir) {
   return removed;
 }
 
-function rotateHooksLog(planningDir) {
-  try {
-    const logsDir = path.join(planningDir, 'logs');
-    const hooksLog = path.join(logsDir, 'hooks.jsonl');
-    if (!fs.existsSync(hooksLog)) return false;
-
-    const stat = fs.statSync(hooksLog);
-    if (stat.size <= MAX_HOOKS_LOG_BYTES) return false;
-
-    const rotatedPath = hooksLog + '.1';
-    // Overwrite any existing .1 file
-    fs.renameSync(hooksLog, rotatedPath);
-    return true;
-  } catch (_e) {
-    return false;
-  }
+/** @deprecated Daily dated log files no longer need size-based rotation. */
+function rotateHooksLog(_planningDir) {
+  return false;
 }
 
 function findOrphanedProgressFiles(planningDir) {
@@ -112,7 +102,85 @@ function findOrphanedProgressFiles(planningDir) {
   return orphans;
 }
 
+/**
+ * formatSessionMetrics — Format session stats into a human-readable report.
+ * @param {Object} stats - Session statistics
+ * @returns {string} Formatted multi-line string
+ */
+function formatSessionMetrics(stats) {
+  const duration = stats.duration_min || 0;
+  const agents = stats.agents_spawned || 0;
+  const commits = stats.commits_created || 0;
+  const plansExec = stats.plans_executed || 0;
+  const plansVerified = stats.plans_verified || 0;
+  const feedback = stats.feedback_loops || 0;
+  const compliance = Math.round((plansVerified / Math.max(plansExec, 1)) * 100);
+
+  return [
+    'Session Metrics:',
+    `  Duration:    ${duration}m`,
+    `  Agents:      ${agents}`,
+    `  Commits:     ${commits}`,
+    `  Plans:       ${plansExec} executed, ${plansVerified} verified`,
+    `  Compliance:  ${compliance}%`,
+    `  Feedback:    ${feedback} loops triggered`
+  ].join('\n');
+}
+
 const MAX_SESSION_ENTRIES = 100;
+const MAX_SESSION_METRIC_FILES = 50;
+
+/**
+ * Write a per-session metrics JSON file to logs/sessions/ directory.
+ * Each session gets its own file for easy browsing and archival.
+ * Directory is capped at MAX_SESSION_METRIC_FILES (oldest deleted first).
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {object} sessionData - Session summary object from writeSessionHistory
+ */
+function writeSessionMetricsFile(planningDir, sessionData) {
+  try {
+    const sessionsDir = path.join(planningDir, 'logs', 'sessions');
+    fs.mkdirSync(sessionsDir, { recursive: true });
+
+    // Generate Windows-safe filename from timestamp (replace colons with dashes)
+    const ts = (sessionData.end || new Date().toISOString()).replace(/:/g, '-');
+    const filename = `${ts}-metrics.json`;
+
+    const metricsData = {
+      session_id: sessionData.session_id || null,
+      start: sessionData.start || null,
+      end: sessionData.end || null,
+      duration_minutes: sessionData.duration_minutes || null,
+      agents_spawned: sessionData.agents_spawned || 0,
+      commits_created: sessionData.commits_created || 0,
+      commands_run: sessionData.commands_run || [],
+      plans_executed: sessionData.plans_executed || 0,
+      plans_verified: sessionData.plans_verified || 0,
+      compliance_pct: sessionData.compliance_pct || 0,
+      feedback_loops_triggered: sessionData.feedback_loops_triggered || 0
+    };
+
+    fs.writeFileSync(
+      path.join(sessionsDir, filename),
+      JSON.stringify(metricsData, null, 2) + '\n',
+      'utf8'
+    );
+
+    // Cap directory to MAX_SESSION_METRIC_FILES (delete oldest by name sort)
+    const files = fs.readdirSync(sessionsDir)
+      .filter(f => f.endsWith('-metrics.json'))
+      .sort();
+    if (files.length > MAX_SESSION_METRIC_FILES) {
+      const toRemove = files.slice(0, files.length - MAX_SESSION_METRIC_FILES);
+      for (const f of toRemove) {
+        try { fs.unlinkSync(path.join(sessionsDir, f)); } catch (_e) { /* best-effort */ }
+      }
+    }
+  } catch (_e) {
+    // Best-effort — don't fail the hook
+  }
+}
 
 function writeSessionHistory(planningDir, data) {
   try {
@@ -123,9 +191,9 @@ function writeSessionHistory(planningDir, data) {
 
     const sessionsFile = path.join(logsDir, 'sessions.jsonl');
 
-    // Mine existing logs for session stats
-    const hooksLog = path.join(logsDir, 'hooks.jsonl');
-    const eventsLog = path.join(logsDir, 'events.jsonl');
+    // Mine existing logs for session stats (today's dated log files)
+    const hooksLog = path.join(logsDir, getHooksFilename());
+    const eventsLog = path.join(logsDir, getEventsFilename());
 
     let agentsSpawned = 0;
     let commitsCreated = 0;
@@ -148,8 +216,9 @@ function writeSessionHistory(planningDir, data) {
       } catch (_e) { /* skip malformed lines */ }
     }
 
-    // Count commits and commands from events log
+    // Count commits, commands, and feedback loops from events log
     // Read last 200 entries — sufficient for a single session's events
+    let feedbackLoopsTriggered = 0;
     const eventLines = tailLines(eventsLog, 200);
     for (const line of eventLines) {
       try {
@@ -157,6 +226,9 @@ function writeSessionHistory(planningDir, data) {
         if (entry.event === 'commit-validated' && entry.status === 'allow') {
           commitsCreated++;
         }
+        if (entry.event === 'feedback-injected') {
+          feedbackLoopsTriggered++;
+        }
         if (entry.cat === 'workflow' && entry.event) {
           if (!commandsRun.includes(entry.event)) {
             commandsRun.push(entry.event);
@@ -168,12 +240,34 @@ function writeSessionHistory(planningDir, data) {
       } catch (_e) { /* skip malformed lines */ }
     }
 
+    // Count plans executed (SUMMARY-*.md files in phase dirs) and verified (VERIFICATION-*.md)
+    let plansExecuted = 0;
+    let plansVerified = 0;
+    try {
+      const phasesDir = path.join(planningDir, 'phases');
+      if (fs.existsSync(phasesDir)) {
+        const pDirs = fs.readdirSync(phasesDir);
+        for (const pd of pDirs) {
+          const pdPath = path.join(phasesDir, pd);
+          try {
+            const files = fs.readdirSync(pdPath);
+            for (const f of files) {
+              if (/^SUMMARY-.*\.md$/i.test(f)) plansExecuted++;
+              if (/^VERIFICATION-.*\.md$/i.test(f)) plansVerified++;
+            }
+          } catch (_e) { /* skip unreadable dirs */ }
+        }
+      }
+    } catch (_e) { /* best-effort */ }
+
     const sessionEnd = new Date().toISOString();
     let durationMinutes = null;
     if (sessionStart) {
       durationMinutes = Math.round((new Date(sessionEnd) - new Date(sessionStart)) / 60000);
     }
 
+    const compliancePct = Math.round((plansVerified / Math.max(plansExecuted, 1)) * 100);
+
     const summary = {
       start: sessionStart || sessionEnd,
       end: sessionEnd,
@@ -181,7 +275,10 @@ function writeSessionHistory(planningDir, data) {
       reason: data.reason || null,
       agents_spawned: agentsSpawned,
       commits_created: commitsCreated,
-      commands_run: commandsRun
+      commands_run: commandsRun,
+      plans_executed: plansExecuted,
+      compliance_pct: compliancePct,
+      feedback_loops_triggered: feedbackLoopsTriggered
     };
 
     // Append to sessions.jsonl, cap at MAX_SESSION_ENTRIES
@@ -197,13 +294,93 @@ function writeSessionHistory(planningDir, data) {
       lines = lines.slice(lines.length - MAX_SESSION_ENTRIES);
     }
     fs.writeFileSync(sessionsFile, lines.join('\n') + '\n', 'utf8');
+
+    // Write per-session metrics JSON file
+    writeSessionMetricsFile(planningDir, summary);
   } catch (_e) {
     // Best-effort — don't fail the hook
   }
 }
 
+/**
+ * Gather session context for mental model snapshot.
+ * Reads recent git changes, STATE.md sections, and recent commits.
+ * All operations are best-effort — returns partial data on failure.
+ *
+ * @param {string} cwd - Project working directory
+ * @param {string} planningDir - Path to .planning directory
+ * @param {string|null} sessionId - Session ID
+ * @returns {object} Context object for writeSnapshot
+ */
+function gatherSessionContext(cwd, planningDir, sessionId) {
+  const context = {
+    session_id: sessionId || 'unknown',
+    files_working_on: [],
+    pending_decisions: [],
+    current_approach: '',
+    open_questions: [],
+    recent_commits: []
+  };
+
+  // Gather recent git changes
+  try {
+    const diff = execSync('git diff --name-only HEAD~5 HEAD 2>/dev/null || echo ""', {
+      cwd, encoding: 'utf8', timeout: 5000
+    });
+    context.files_working_on = diff.split('\n').map(l => l.trim()).filter(Boolean);
+  } catch (_e) { /* best-effort */ }
+
+  // Gather recent commits
+  try {
+    const log = execSync('git log --oneline -5 2>/dev/null || echo ""', {
+      cwd, encoding: 'utf8', timeout: 5000
+    });
+    context.recent_commits = log.split('\n').map(l => l.trim()).filter(Boolean);
+  } catch (_e) { /* best-effort */ }
+
+  // Read STATE.md for approach, decisions, and open questions
+  const stateFile = path.join(planningDir, 'STATE.md');
+  try {
+    if (fs.existsSync(stateFile)) {
+      const stateContent = fs.readFileSync(stateFile, 'utf8');
+
+      // Extract Current Position section
+      const posMatch = stateContent.match(/## Current Position\s*\n([\s\S]*?)(?=\n##\s|$)/);
+      if (posMatch) {
+        context.current_approach = posMatch[1].trim().split('\n').slice(0, 5).join('\n');
+      }
+
+      // Extract Decisions section
+      const decMatch = stateContent.match(/### Decisions\s*\n([\s\S]*?)(?=\n###\s|\n##\s|$)/);
+      if (decMatch) {
+        context.pending_decisions = decMatch[1].trim().split('\n')
+          .filter(l => l.startsWith('- '))
+          .map(l => l.slice(2).trim());
+      }
+
+      // Extract Blockers/Concerns section
+      const blockMatch = stateContent.match(/### Blockers\/Concerns\s*\n([\s\S]*?)(?=\n###\s|\n##\s|$)/);
+      if (blockMatch) {
+        context.open_questions = blockMatch[1].trim().split('\n')
+          .filter(l => l.startsWith('- '))
+          .map(l => l.slice(2).trim());
+      }
+    }
+  } catch (_e) { /* best-effort */ }
+
+  return context;
+}
+
 function main() {
+  // Safety timeout: prevent hang if stdin never closes or cleanup stalls
+  const safetyTimeout = setTimeout(() => { process.exit(0); }, 3000);
+
+  // Log invocation evidence before any I/O
+  logHook('session-cleanup', 'SessionEnd', 'hook-invoked', { pid: process.pid });
+
   const data = readStdin();
+  clearTimeout(safetyTimeout);
+
   const cwd = process.cwd();
   const planningDir = path.join(cwd, '.planning');
 
@@ -211,11 +388,51 @@ function main() {
     process.exit(0);
   }
 
+  const sessionId = data.session_id || null;
   const cleaned = [];
 
-  if (tryRemove(path.join(planningDir, '.auto-next'))) {
-    cleaned.push('.auto-next');
+  // NOTE: .auto-next is intentionally NOT cleaned here — it is a one-shot
+  // signal consumed by auto-continue.js (Stop hook). SessionEnd cleanup
+  // races with the Stop hook and would delete the signal before it is read.
+
+  // Clean up stale workflow._auto_chain_active config flag.
+  // If the Stop hook didn't consume it (e.g., auto_continue disabled), clear it.
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    if (fs.existsSync(configPath)) {
+      const rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (rawConfig.workflow && rawConfig.workflow._auto_chain_active) {
+        delete rawConfig.workflow._auto_chain_active;
+        fs.writeFileSync(configPath, JSON.stringify(rawConfig, null, 2), 'utf8');
+        cleaned.push('workflow._auto_chain_active');
+      }
+    }
+  } catch (_e) {
+    // best-effort — don't fail the hook
+  }
+
+  // Session-scoped cleanup: remove the entire session directory if session_id is available
+  if (sessionId) {
+    try {
+      removeSessionDir(planningDir, sessionId);
+      cleaned.push(`.sessions/${sessionId}`);
+    } catch (_e) { /* best-effort */ }
+
+    // Release any phase claims held by this session
+    try {
+      const releasedClaims = releaseSessionClaims(planningDir, sessionId);
+      if (releasedClaims.released.length > 0) {
+        logHook('session-cleanup', 'SessionEnd', 'claims-released', { released: releasedClaims.released });
+        cleaned.push(...releasedClaims.released.map(p => `phases/${p}/.claim`));
+      }
+    } catch (_e) { /* best-effort */ }
+  }
+
+  // Primary: remove .session.json (consolidated session state)
+  if (tryRemove(path.join(planningDir, '.session.json'))) {
+    cleaned.push('.session.json');
   }
+  // Legacy fallback: also clean individual signal files during transition period
   if (tryRemove(path.join(planningDir, '.active-operation'))) {
     cleaned.push('.active-operation');
   }
@@ -225,20 +442,109 @@ function main() {
   if (tryRemove(path.join(planningDir, '.active-plan'))) {
     cleaned.push('.active-plan');
   }
+  if (tryRemove(path.join(planningDir, '.context-tracker'))) {
+    cleaned.push('.context-tracker');
+  }
 
   // Clean stale checkpoint manifests (>24h old)
   const staleCheckpoints = cleanStaleCheckpoints(planningDir);
   cleaned.push(...staleCheckpoints);
 
-  // Rotate hooks.jsonl if >200KB
+  // Rotate hooks.jsonl if >200KB (no-op now that we use daily dated files)
   const rotated = rotateHooksLog(planningDir);
 
+  // Clean up daily log files older than 30 days
+  const logsDir = path.join(planningDir, 'logs');
+  if (fs.existsSync(logsDir)) {
+    cleanOldHookLogs(logsDir);
+    cleanOldEventLogs(logsDir);
+  }
+
   // Detect orphaned .PROGRESS-* files (executor crash artifacts)
   const orphans = findOrphanedProgressFiles(planningDir);
 
   // Write session history log
   writeSessionHistory(planningDir, data);
 
+  // Session productivity metrics display (controlled by features.session_metrics)
+  let metricsContext = null;
+  try {
+    const rawConfig = configLoad(planningDir) || {};
+    if (rawConfig.features && rawConfig.features.session_metrics !== false) {
+      // Build stats from the same data writeSessionHistory computed
+      // Re-read the last session entry to get the computed values
+      const sessionsFile = path.join(planningDir, 'logs', 'sessions.jsonl');
+      if (fs.existsSync(sessionsFile)) {
+        const lastLine = fs.readFileSync(sessionsFile, 'utf8').trim().split('\n').pop();
+        if (lastLine) {
+          const lastEntry = JSON.parse(lastLine);
+          metricsContext = formatSessionMetrics({
+            duration_min: lastEntry.duration_minutes || 0,
+            agents_spawned: lastEntry.agents_spawned || 0,
+            commits_created: lastEntry.commits_created || 0,
+            plans_executed: lastEntry.plans_executed || 0,
+            plans_verified: Math.round((lastEntry.compliance_pct || 0) * Math.max(lastEntry.plans_executed || 0, 1) / 100),
+            feedback_loops: lastEntry.feedback_loops_triggered || 0,
+            commands_run: (lastEntry.commands_run || []).length
+          });
+        }
+      }
+    }
+  } catch (_e) { /* metrics display is best-effort */ }
+
+  // Local LLM metrics summary (SessionEnd — sync reads only, never throws)
+  let llmAdditionalContext = null;
+  try {
+    const sessionStartFile = path.join(planningDir, '.session-start');
+    if (fs.existsSync(sessionStartFile)) {
+      const sessionStartTime = fs.readFileSync(sessionStartFile, 'utf8').trim();
+      const entries = readSessionMetrics(planningDir, sessionStartTime);
+      if (entries.length > 0) {
+        const summary = summarizeMetrics(entries);
+        logHook('session-cleanup', 'SessionEnd', 'llm-metrics', {
+          total_calls: summary.total_calls,
+          fallback_count: summary.fallback_count,
+          avg_latency_ms: summary.avg_latency_ms,
+          tokens_saved: summary.tokens_saved,
+          cost_saved_usd: summary.cost_saved_usd
+        });
+        if (summary.total_calls > 0) {
+          let modelName = null;
+          try {
+            const rawConfig = configLoad(planningDir) || {};
+            modelName = (rawConfig.local_llm && rawConfig.local_llm.model) || null;
+          } catch (_e) { /* config read failure is non-fatal */ }
+          llmAdditionalContext = formatSessionSummary(summary, modelName);
+        }
+      }
+      // Clean up session-start file
+      try { fs.unlinkSync(sessionStartFile); } catch (_e) { /* non-fatal */ }
+    }
+  } catch (_e) { /* metrics never crash the hook */ }
+
+  // Surface compliance violations from this session
+  let complianceContext = null;
+  try {
+    const complianceFile = path.join(planningDir, 'logs', 'compliance.jsonl');
+    if (fs.existsSync(complianceFile)) {
+      const lines = fs.readFileSync(complianceFile, 'utf8').trim().split('\n').filter(Boolean);
+      if (lines.length > 0) {
+        const violations = lines.map(l => { try { return JSON.parse(l); } catch (_e) { return null; } }).filter(Boolean);
+        const required = violations.filter(v => v.severity === 'required');
+        if (required.length > 0) {
+          complianceContext = `\n\n⚠ COMPLIANCE: ${required.length} required artifact(s) missing this session:\n` +
+            required.map(v => `  - ${v.agent}: ${v.violation}`).join('\n') +
+            '\nThese artifacts should be created before the milestone is complete.';
+        }
+        // Clear compliance log after surfacing (fresh for next session)
+        fs.unlinkSync(complianceFile);
+        cleaned.push('logs/compliance.jsonl');
+      }
+    }
+  } catch (_e) {
+    // Best-effort
+  }
+
   const decision = cleaned.length > 0 ? 'cleaned' : 'nothing';
   logHook('session-cleanup', 'SessionEnd', decision, {
     reason: data.reason || null,
@@ -247,8 +553,131 @@ function main() {
     orphaned_progress_files: orphans.length > 0 ? orphans : undefined
   });
 
+  // Write mental model snapshot (gated by config toggle)
+  try {
+    const config = configLoad(planningDir) || {};
+    const snapshotsEnabled = config.features && config.features.mental_model_snapshots !== false;
+    if (snapshotsEnabled) {
+      const snapContext = gatherSessionContext(cwd, planningDir, sessionId);
+      writeSnapshot(planningDir, snapContext);
+      logHook('session-cleanup', 'SessionEnd', 'snapshot-written', {
+        files_count: snapContext.files_working_on.length
+      });
+    }
+  } catch (_e) {
+    // Snapshot failure must never crash SessionEnd
+  }
+
+  const combinedContext = [metricsContext, llmAdditionalContext, complianceContext].filter(Boolean).join('\n');
+  if (combinedContext) {
+    process.stdout.write(JSON.stringify({ additionalContext: combinedContext }) + '\n');
+  }
+
   process.exit(0);
 }
 
-module.exports = { writeSessionHistory, tryRemove, cleanStaleCheckpoints, rotateHooksLog, findOrphanedProgressFiles };
+/**
+ * handleHttp — hook-server.js interface.
+ * reqBody = { event, tool, data, planningDir, cache }
+ * Returns null. Never calls process.exit().
+ */
+function handleHttp(reqBody) {
+  logHook('session-cleanup', 'SessionEnd', 'hook-invoked', { pid: process.pid, mode: 'http' });
+
+  const data = (reqBody && reqBody.data) || {};
+  const planningDir = reqBody && reqBody.planningDir;
+  if (!planningDir || !fs.existsSync(planningDir)) return null;
+
+  const cleaned = [];
+  if (tryRemove(path.join(planningDir, '.session.json'))) cleaned.push('.session.json');
+  if (tryRemove(path.join(planningDir, '.active-operation'))) cleaned.push('.active-operation');
+  if (tryRemove(path.join(planningDir, '.active-skill'))) cleaned.push('.active-skill');
+  if (tryRemove(path.join(planningDir, '.active-plan'))) cleaned.push('.active-plan');
+  if (tryRemove(path.join(planningDir, '.context-tracker'))) cleaned.push('.context-tracker');
+
+  const staleCheckpoints = cleanStaleCheckpoints(planningDir);
+  cleaned.push(...staleCheckpoints);
+
+  const rotated = rotateHooksLog(planningDir);
+  const orphans = findOrphanedProgressFiles(planningDir);
+
+  writeSessionHistory(planningDir, data);
+
+  const decision = cleaned.length > 0 ? 'cleaned' : 'nothing';
+  logHook('session-cleanup', 'SessionEnd', decision, {
+    reason: data.reason || null,
+    removed: cleaned,
+    log_rotated: rotated,
+    orphaned_progress_files: orphans.length > 0 ? orphans : undefined
+  });
+
+  return null;
+}
+
+/**
+ * Extract learnings from a session's hook logs and event logs.
+ * Writes to planningDir/logs/session-learnings.jsonl only if interesting events found.
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {string} sessionId - Session identifier
+ */
+function extractSessionLearnings(planningDir, sessionId) {
+  const logsDir = path.join(planningDir, 'logs');
+  // Use today's dated log files (built from planningDir, not from resolved project root).
+  const hooksLog = path.join(logsDir, getHooksFilename());
+  const eventsLog = path.join(logsDir, getEventsFilename());
+
+  const gatesTriggered = [];
+  const agentFailures = [];
+  let phasesCompleted = 0;
+  const contextEvents = [];
+
+  // Parse hooks.jsonl for blocks and warnings
+  if (fs.existsSync(hooksLog)) {
+    const lines = fs.readFileSync(hooksLog, 'utf8').split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.decision === 'block') {
+          gatesTriggered.push({ hook: entry.hook, reason: entry.reason });
+        }
+        if (entry.decision === 'warning' && entry.hook === 'check-subagent-output' && entry.agent_type) {
+          agentFailures.push({ agent_type: entry.agent_type, expected: entry.expected });
+        }
+      } catch (_e) { /* skip malformed */ }
+    }
+  }
+
+  // Parse events.jsonl for phase completions and compactions
+  if (fs.existsSync(eventsLog)) {
+    const lines = fs.readFileSync(eventsLog, 'utf8').split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.cat === 'workflow' && entry.event === 'phase-complete') {
+          phasesCompleted++;
+        }
+        if (entry.cat === 'system' && entry.event === 'compaction') {
+          contextEvents.push('compaction');
+        }
+      } catch (_e) { /* skip malformed */ }
+    }
+  }
+
+  const hasInteresting = gatesTriggered.length > 0 || agentFailures.length > 0 || phasesCompleted > 0 || contextEvents.length > 0;
+  if (!hasInteresting) return;
+
+  if (!fs.existsSync(logsDir)) fs.mkdirSync(logsDir, { recursive: true });
+  const learningsFile = path.join(logsDir, 'session-learnings.jsonl');
+  const entry = JSON.stringify({
+    session_id: sessionId,
+    ts: new Date().toISOString(),
+    gates_triggered: gatesTriggered,
+    agent_failures: agentFailures,
+    phases_completed: phasesCompleted,
+    context_events: contextEvents
+  });
+  fs.appendFileSync(learningsFile, entry + '\n');
+}
+
+module.exports = { writeSessionHistory, writeSessionMetricsFile, tryRemove, cleanStaleCheckpoints, rotateHooksLog, findOrphanedProgressFiles, gatherSessionContext, handleHttp, formatSessionMetrics, extractSessionLearnings };
 if (require.main === module || process.argv[1] === __filename) { main(); }