clearctx 3.0.0

package/src/diff-engine.js

@@ -0,0 +1,473 @@
+/**
+ * diff-engine.js
+ *
+ * The Diff Engine computes what changed between sessions.
+ * This is Layer 0 of the Session Continuity Engine.
+ *
+ * Primary use case: "What changed since my last session?"
+ * - Compares latest snapshot to current git state
+ * - Detects new commits, file changes, and stale context
+ * - Provides time-aware session continuity
+ *
+ * Uses synchronous git commands and zero external dependencies.
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const SessionSnapshot = require('./session-snapshot');
+
+/**
+ * DiffEngine - Computes differences between snapshots and current state
+ *
+ * This class analyzes what changed between sessions by comparing
+ * git state, file modifications, and working context.
+ */
+class DiffEngine {
+  /**
+   * Create a new DiffEngine
+   * @param {string} projectPath - Absolute path to the project directory
+   */
+  constructor(projectPath) {
+    // Store the project path for git operations
+    this.projectPath = projectPath;
+
+    // Create a SessionSnapshot instance to read snapshots
+    this.snapshot = new SessionSnapshot(projectPath);
+  }
+
+  /**
+   * Compare latest snapshot to current git state
+   *
+   * This is the PRIMARY use case — answers "what changed since my last session?"
+   *
+   * @returns {Object} Diff object with git changes, file changes, and context impact
+   */
+  diffFromLatest() {
+    // Step 1: Get the latest snapshot
+    const snapshot = this.snapshot.getLatest();
+
+    // If no snapshot exists, this is the first session
+    if (!snapshot) {
+      return {
+        noSnapshot: true,
+        message: 'No previous snapshot found. This appears to be the first session.'
+      };
+    }
+
+    // Step 2: Get the snapshot's git commit
+    const snapshotHead = snapshot.git?.headCommit || null;
+
+    // If snapshot has no git state (repo had no commits), return a special diff
+    if (!snapshotHead) {
+      return {
+        noGitState: true,
+        message: 'Previous snapshot had no git state (repository had no commits at that time).',
+        fromSnapshot: snapshot.snapshotId,
+        toState: 'current',
+        timeDelta: Date.now() - new Date(snapshot.capturedAt).getTime(),
+        timeDeltaHuman: this._formatTimeDelta(Date.now() - new Date(snapshot.capturedAt).getTime()),
+        gitChanges: {
+          newCommitCount: 0,
+          commits: [],
+          branchChanged: false,
+          oldBranch: null,
+          newBranch: null,
+          diffFailed: false
+        },
+        fileChanges: {
+          added: [],
+          modified: [],
+          deleted: [],
+          renamed: [],
+          diffFailed: false
+        },
+        contextImpact: {
+          activeFilesModified: [],
+          staleFiles: [],
+          previousTask: snapshot.workingContext?.taskSummary || '',
+          previousQuestions: snapshot.workingContext?.openQuestions || []
+        }
+      };
+    }
+
+    // Step 3: Compute current git state
+    let currentHead, currentBranch;
+    try {
+      // Get current commit hash
+      currentHead = execSync('git rev-parse HEAD', {
+        cwd: this.projectPath,
+        encoding: 'utf8'
+      }).trim();
+
+      // Get current branch name
+      currentBranch = execSync('git branch --show-current', {
+        cwd: this.projectPath,
+        encoding: 'utf8'
+      }).trim();
+    } catch (err) {
+      return {
+        error: true,
+        message: 'Failed to get current git state: ' + err.message
+      };
+    }
+
+    // Step 4: Compute git changes between snapshot and now
+    let commits = [];
+    let commitDiffFailed = false;
+
+    try {
+      // Get new commits since snapshot
+      const logOutput = execSync(`git log --oneline ${snapshotHead}..HEAD`, {
+        cwd: this.projectPath,
+        encoding: 'utf8'
+      }).trim();
+
+      if (logOutput) {
+        commits = this._parseOneline(logOutput);
+      }
+    } catch (err) {
+      // Snapshot commit might not exist (rebased/force-pushed)
+      commitDiffFailed = true;
+      commits = [{
+        hash: 'N/A',
+        message: `Cannot compute commits (snapshot commit ${snapshotHead.slice(0, 7)} no longer exists)`
+      }];
+    }
+
+    // Step 5: Compute file changes
+    let fileChanges = { added: [], modified: [], deleted: [], renamed: [] };
+    let fileDiffFailed = false;
+
+    try {
+      if (!commitDiffFailed && snapshotHead !== currentHead) {
+        // Use git diff to find changes between commits
+        const diffOutput = execSync(`git diff --name-status ${snapshotHead} HEAD`, {
+          cwd: this.projectPath,
+          encoding: 'utf8'
+        }).trim();
+
+        if (diffOutput) {
+          fileChanges = this._parseNameStatus(diffOutput);
+        }
+      } else if (commitDiffFailed) {
+        // Fallback: use git status if snapshot commit doesn't exist
+        const statusOutput = execSync('git status --porcelain', {
+          cwd: this.projectPath,
+          encoding: 'utf8'
+        }).trim();
+
+        if (statusOutput) {
+          fileChanges = this._parseStatusPorcelain(statusOutput);
+        }
+      }
+      // If snapshotHead === currentHead, no file changes (already initialized empty)
+    } catch (err) {
+      fileDiffFailed = true;
+    }
+
+    // Step 6: Compute context impact
+    const activeFiles = snapshot.workingContext?.activeFiles || [];
+    const allChangedFiles = [
+      ...fileChanges.added,
+      ...fileChanges.modified,
+      ...fileChanges.deleted,
+      ...fileChanges.renamed.map(r => r.from),
+      ...fileChanges.renamed.map(r => r.to)
+    ];
+
+    // Find which active files were modified
+    const activeFilesModified = activeFiles.filter(file =>
+      allChangedFiles.includes(file)
+    );
+
+    // Step 7: Compute time delta
+    const timeDeltaMs = Date.now() - new Date(snapshot.capturedAt).getTime();
+
+    // Step 8: Return comprehensive diff object
+    return {
+      fromSnapshot: snapshot.snapshotId,
+      toState: 'current',
+      timeDelta: timeDeltaMs,
+      timeDeltaHuman: this._formatTimeDelta(timeDeltaMs),
+      gitChanges: {
+        newCommitCount: commits.length,
+        commits: commits,
+        branchChanged: snapshot.git?.branch !== currentBranch,
+        oldBranch: snapshot.git?.branch || 'unknown',
+        newBranch: currentBranch,
+        diffFailed: commitDiffFailed
+      },
+      fileChanges: {
+        added: fileChanges.added,
+        modified: fileChanges.modified,
+        deleted: fileChanges.deleted,
+        renamed: fileChanges.renamed,
+        diffFailed: fileDiffFailed
+      },
+      contextImpact: {
+        activeFilesModified: activeFilesModified,
+        staleFiles: activeFilesModified,  // Alias for clarity
+        previousTask: snapshot.workingContext?.taskSummary || '',
+        previousQuestions: snapshot.workingContext?.openQuestions || []
+      }
+    };
+  }
+
+  /**
+   * Compare two specific snapshots
+   *
+   * @param {string} snapshotIdA - First snapshot ID
+   * @param {string} snapshotIdB - Second snapshot ID
+   * @returns {Object} Diff object between the two snapshots
+   */
+  diffBetween(snapshotIdA, snapshotIdB) {
+    // Step 1: Get both snapshots
+    const snapshotA = this.snapshot.get(snapshotIdA);
+    const snapshotB = this.snapshot.get(snapshotIdB);
+
+    if (!snapshotA) {
+      throw new Error(`Snapshot not found: ${snapshotIdA}`);
+    }
+    if (!snapshotB) {
+      throw new Error(`Snapshot not found: ${snapshotIdB}`);
+    }
+
+    // Step 2: Get git commits from both snapshots
+    const commitA = snapshotA.git?.headCommit;
+    const commitB = snapshotB.git?.headCommit;
+
+    if (!commitA || !commitB) {
+      throw new Error('One or both snapshots missing git headCommit');
+    }
+
+    // Step 3: Compute commit list
+    let commits = [];
+    let commitDiffFailed = false;
+
+    try {
+      const logOutput = execSync(`git log --oneline ${commitA}..${commitB}`, {
+        cwd: this.projectPath,
+        encoding: 'utf8'
+      }).trim();
+
+      if (logOutput) {
+        commits = this._parseOneline(logOutput);
+      }
+    } catch (err) {
+      commitDiffFailed = true;
+      commits = [{
+        hash: 'N/A',
+        message: 'Cannot compute commits (one or both commits no longer exist)'
+      }];
+    }
+
+    // Step 4: Compute file changes
+    let fileChanges = { added: [], modified: [], deleted: [], renamed: [] };
+    let fileDiffFailed = false;
+
+    try {
+      if (!commitDiffFailed) {
+        const diffOutput = execSync(`git diff --name-status ${commitA} ${commitB}`, {
+          cwd: this.projectPath,
+          encoding: 'utf8'
+        }).trim();
+
+        if (diffOutput) {
+          fileChanges = this._parseNameStatus(diffOutput);
+        }
+      }
+    } catch (err) {
+      fileDiffFailed = true;
+    }
+
+    // Step 5: Compute time delta
+    const timeDeltaMs = new Date(snapshotB.capturedAt).getTime() -
+                        new Date(snapshotA.capturedAt).getTime();
+
+    // Step 6: Return diff object
+    return {
+      fromSnapshot: snapshotIdA,
+      toSnapshot: snapshotIdB,
+      timeDelta: timeDeltaMs,
+      timeDeltaHuman: this._formatTimeDelta(timeDeltaMs),
+      gitChanges: {
+        newCommitCount: commits.length,
+        commits: commits,
+        branchChanged: snapshotA.git?.branch !== snapshotB.git?.branch,
+        oldBranch: snapshotA.git?.branch || 'unknown',
+        newBranch: snapshotB.git?.branch || 'unknown',
+        diffFailed: commitDiffFailed
+      },
+      fileChanges: {
+        added: fileChanges.added,
+        modified: fileChanges.modified,
+        deleted: fileChanges.deleted,
+        renamed: fileChanges.renamed,
+        diffFailed: fileDiffFailed
+      },
+      contextImpact: {
+        activeFilesModified: [],  // Not computed for snapshot-to-snapshot diff
+        staleFiles: [],
+        previousTask: snapshotA.workingContext?.taskSummary || '',
+        previousQuestions: snapshotA.workingContext?.openQuestions || []
+      }
+    };
+  }
+
+  /**
+   * Parse git diff --name-status output
+   *
+   * Format examples:
+   * A       src/new-file.ts         → added
+   * M       src/modified.ts         → modified
+   * D       src/deleted.ts          → deleted
+   * R100    src/old.ts    src/new.ts → renamed
+   *
+   * @param {string} output - Output from git diff --name-status
+   * @returns {Object} Categorized file changes
+   * @private
+   */
+  _parseNameStatus(output) {
+    const result = {
+      added: [],
+      modified: [],
+      deleted: [],
+      renamed: []
+    };
+
+    if (!output) return result;
+
+    const lines = output.split('\n');
+    for (const line of lines) {
+      if (!line.trim()) continue;
+
+      // Split by tabs or multiple spaces
+      const parts = line.split(/\s+/);
+      const status = parts[0];
+
+      if (status.startsWith('A')) {
+        // Added file
+        result.added.push(parts[1]);
+      } else if (status.startsWith('M')) {
+        // Modified file
+        result.modified.push(parts[1]);
+      } else if (status.startsWith('D')) {
+        // Deleted file
+        result.deleted.push(parts[1]);
+      } else if (status.startsWith('R')) {
+        // Renamed file (R100 means 100% similarity)
+        result.renamed.push({
+          from: parts[1],
+          to: parts[2]
+        });
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Parse git status --porcelain output (fallback when diff fails)
+   *
+   * Format examples:
+   * ?? new-file.ts     → added (untracked)
+   *  M modified.ts     → modified
+   *  D deleted.ts      → deleted
+   *
+   * @param {string} output - Output from git status --porcelain
+   * @returns {Object} Categorized file changes
+   * @private
+   */
+  _parseStatusPorcelain(output) {
+    const result = {
+      added: [],
+      modified: [],
+      deleted: [],
+      renamed: []
+    };
+
+    if (!output) return result;
+
+    const lines = output.split('\n');
+    for (const line of lines) {
+      if (!line.trim()) continue;
+
+      // First two characters are status codes
+      const status = line.substring(0, 2);
+      const file = line.substring(3).trim();
+
+      if (status.includes('?')) {
+        result.added.push(file);
+      } else if (status.includes('M') || status.includes('A')) {
+        result.modified.push(file);
+      } else if (status.includes('D')) {
+        result.deleted.push(file);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Parse git log --oneline output
+   *
+   * Format: "abc123d Some commit message"
+   *
+   * @param {string} output - Output from git log --oneline
+   * @returns {Array<Object>} Array of {hash, message} objects
+   * @private
+   */
+  _parseOneline(output) {
+    const commits = [];
+
+    if (!output) return commits;
+
+    const lines = output.split('\n');
+    for (const line of lines) {
+      if (!line.trim()) continue;
+
+      // First word is the hash, rest is the message
+      const spaceIndex = line.indexOf(' ');
+      if (spaceIndex === -1) continue;
+
+      const hash = line.substring(0, spaceIndex);
+      const message = line.substring(spaceIndex + 1);
+
+      commits.push({ hash, message });
+    }
+
+    return commits;
+  }
+
+  /**
+   * Convert milliseconds to human-readable time string
+   *
+   * @param {number} ms - Milliseconds
+   * @returns {string} Human-readable time (e.g., "5 minutes ago")
+   * @private
+   */
+  _formatTimeDelta(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    const weeks = Math.floor(days / 7);
+
+    if (seconds < 60) {
+      return 'just now';
+    } else if (minutes < 60) {
+      return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+    } else if (hours < 24) {
+      return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+    } else if (days < 7) {
+      return `${days} day${days === 1 ? '' : 's'} ago`;
+    } else {
+      return `${weeks} week${weeks === 1 ? '' : 's'} ago`;
+    }
+  }
+}
+
+// Export the DiffEngine class directly
+module.exports = DiffEngine;

package/src/file-lock.js

@@ -0,0 +1,161 @@
+/**
+ * Cross-process file locking with PID-aware stale lock recovery.
+ *
+ * Uses exclusive file creation (wx flag) for atomic lock acquisition.
+ * Handles stale locks from crashed processes by checking PID liveness.
+ *
+ * Lock stealing rules:
+ * 1. If lock owner PID is dead → steal immediately
+ * 2. If lock owner PID is alive but lock is stale → steal after timeout
+ * 3. If lock owner PID is alive and lock is fresh → retry until timeout
+ *
+ * Configuration via environment variables:
+ * - CMS_LOCK_STALE_MS: Milliseconds before a lock is considered stale (default: 30000)
+ * - CMS_LOCK_MAX_RETRIES: Max retry attempts (default: 200)
+ * - CMS_LOCK_INTERVAL_MS: Wait time between retries (default: 50)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Acquire an exclusive lock using atomic file creation.
+ * Retries with backoff if lock is held. Steals stale locks.
+ *
+ * @param {string} lockDir - Directory for lock files
+ * @param {string} lockName - Name of lock (e.g., 'session-foo')
+ * @param {object} [options={}] - Lock options
+ * @param {number} [options.staleMs] - Lock staleness timeout (default: 30000)
+ * @param {number} [options.maxRetries] - Max acquisition attempts (default: 200)
+ * @param {number} [options.retryIntervalMs] - Wait between retries (default: 50)
+ * @throws {Error} Throws if lock cannot be acquired within timeout
+ */
+function acquireLock(lockDir, lockName, options = {}) {
+  // Configuration with env var overrides
+  const staleMs = options.staleMs || Number(process.env.CMS_LOCK_STALE_MS) || 30000;
+  const maxRetries = options.maxRetries || Number(process.env.CMS_LOCK_MAX_RETRIES) || 200;
+  const retryIntervalMs = options.retryIntervalMs || Number(process.env.CMS_LOCK_INTERVAL_MS) || 50;
+
+  const lockFile = path.join(lockDir, `${lockName}.lock`);
+
+  // Ensure lock directory exists
+  if (!fs.existsSync(lockDir)) {
+    fs.mkdirSync(lockDir, { recursive: true });
+  }
+
+  // Lock payload: PID for ownership verification, timestamp for staleness check
+  const lockData = {
+    pid: process.pid,
+    timestamp: Date.now()
+  };
+
+  // Retry loop with exponential backoff
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      // Try to create lock file exclusively (atomic operation)
+      fs.writeFileSync(lockFile, JSON.stringify(lockData), { flag: 'wx' });
+      return; // Success! Lock acquired
+    } catch (err) {
+      if (err.code !== 'EEXIST') {
+        // Unexpected error (permission denied, disk full, etc.)
+        throw err;
+      }
+
+      // Lock file exists — check if we can steal it
+      try {
+        const existingLock = JSON.parse(fs.readFileSync(lockFile, 'utf-8'));
+        const ownerPid = existingLock.pid;
+        const lockTimestamp = existingLock.timestamp;
+
+        // Check if owner process is still alive
+        let isAlive = false;
+        try {
+          // process.kill(pid, 0) throws if process doesn't exist
+          // Signal 0 = no signal sent, just checks existence
+          process.kill(ownerPid, 0);
+          isAlive = true;
+        } catch (killErr) {
+          // Process is dead (ESRCH = no such process)
+          isAlive = false;
+        }
+
+        if (!isAlive) {
+          // Owner process is dead — steal the lock immediately
+          try {
+            fs.unlinkSync(lockFile);
+          } catch (unlinkErr) {
+            // Lock might have been deleted by another process — retry
+          }
+          continue; // Retry immediately
+        }
+
+        // Owner process is alive — check if lock is stale
+        const lockAge = Date.now() - lockTimestamp;
+        if (lockAge > staleMs) {
+          // Lock is held too long — assume deadlock, steal it
+          try {
+            fs.unlinkSync(lockFile);
+          } catch (unlinkErr) {
+            // Lock might have been deleted by another process — retry
+          }
+          continue; // Retry immediately
+        }
+
+        // Lock is fresh and owner is alive — wait and retry
+      } catch (readErr) {
+        // Lock file is corrupt or deleted — retry immediately
+        continue;
+      }
+    }
+
+    // Wait before retrying (synchronous sleep using Atomics)
+    // Creates a shared buffer and waits on it (will always timeout)
+    const sharedBuffer = new SharedArrayBuffer(4);
+    const sharedArray = new Int32Array(sharedBuffer);
+    Atomics.wait(sharedArray, 0, 0, retryIntervalMs);
+  }
+
+  // Failed to acquire lock within timeout
+  throw new Error(`Lock acquisition timeout for ${lockName} after ${maxRetries} retries`);
+}
+
+/**
+ * Release a lock if owned by current process.
+ * Verifies ownership by checking PID before deletion.
+ *
+ * @param {string} lockDir - Directory for lock files
+ * @param {string} lockName - Name of lock to release
+ */
+function releaseLock(lockDir, lockName) {
+  const lockFile = path.join(lockDir, `${lockName}.lock`);
+
+  // Check if lock file exists
+  if (!fs.existsSync(lockFile)) {
+    // Already released or never acquired — success
+    return;
+  }
+
+  try {
+    // Read lock to verify ownership
+    const lockData = JSON.parse(fs.readFileSync(lockFile, 'utf-8'));
+
+    if (lockData.pid === process.pid) {
+      // We own this lock — safe to delete
+      fs.unlinkSync(lockFile);
+    } else {
+      // Someone else owns this lock (stolen from us?)
+      console.error(
+        `WARNING: Lock ${lockName} is owned by PID ${lockData.pid}, not ${process.pid}. ` +
+        `Not releasing. This may indicate a stolen lock or timing issue.`
+      );
+    }
+  } catch (err) {
+    // Lock file disappeared or is corrupt — consider it released
+    return;
+  }
+}
+
+module.exports = {
+  acquireLock,
+  releaseLock
+};

package/src/index.js

@@ -0,0 +1,61 @@
+/**
+ * clearctx — Main exports
+ *
+ * Programmatic API for managing multiple Claude Code sessions.
+ *
+ * Usage:
+ *   const { SessionManager, Delegate, StreamSession, SafetyNet } = require('clearctx');
+ *
+ *   // High-level: delegate tasks with safety and control
+ *   const mgr = new SessionManager();
+ *   const delegate = new Delegate(mgr);
+ *   const result = await delegate.run('fix-bug', { task: 'Fix the auth bug', maxCost: 0.50 });
+ *
+ *   // Mid-level: manage sessions directly
+ *   const { response } = await mgr.spawn('my-task', { prompt: 'Fix the auth bug' });
+ *
+ *   // Low-level: single streaming session
+ *   const session = new StreamSession({ name: 'direct', model: 'haiku' });
+ *   session.start();
+ *   const r = await session.send('Hello');
+ */
+
+const SessionManager = require('./manager');
+const StreamSession = require('./stream-session');
+const Store = require('./store');
+const Delegate = require('./delegate');
+const SafetyNet = require('./safety-net');
+const TeamHub = require('./team-hub');
+const ArtifactStore = require('./artifact-store');
+const ContractStore = require('./contract-store');
+const DependencyResolver = require('./dependency-resolver');
+const LineageGraph = require('./lineage-graph');
+const PipelineEngine = require('./pipeline-engine');
+const SnapshotEngine = require('./snapshot-engine');
+const SessionSnapshot = require('./session-snapshot');
+const DiffEngine = require('./diff-engine');
+const BriefingGenerator = require('./briefing-generator');
+const DecisionJournal = require('./decision-journal');
+const PatternRegistry = require('./pattern-registry');
+const StaleDetector = require('./stale-detector');
+
+module.exports = {
+  SessionManager,
+  StreamSession,
+  Store,
+  Delegate,
+  SafetyNet,
+  TeamHub,
+  ArtifactStore,
+  ContractStore,
+  DependencyResolver,
+  LineageGraph,
+  PipelineEngine,
+  SnapshotEngine,
+  SessionSnapshot,
+  DiffEngine,
+  BriefingGenerator,
+  DecisionJournal,
+  PatternRegistry,
+  StaleDetector,
+};