claude-code-pilot 2.0.0 → 3.1.0

package/{ecc/scripts → src}/lib/session-manager.js

@@ -2,7 +2,8 @@
  * Session Manager Library for Claude Code
  * Provides core session CRUD operations for listing, loading, and managing sessions
  *
- * Sessions are stored as markdown files in ~/.claude/sessions/ with format:
+ * Sessions are stored as markdown files in ~/.claude/session-data/ with
+ * legacy read compatibility for ~/.claude/sessions/:
  * - YYYY-MM-DD-session.tmp (old format)
  * - YYYY-MM-DD-<short-id>-session.tmp (new format)
  */
@@ -12,16 +13,18 @@ const path = require('path');
 
 const {
   getSessionsDir,
+  getSessionSearchDirs,
   readFile,
   log
 } = require('./utils');
 
 // Session filename pattern: YYYY-MM-DD-[session-id]-session.tmp
-// The session-id is optional (old format) and can include lowercase
-// alphanumeric characters and hyphens, with a minimum length of 8.
+// The session-id is optional (old format) and can include letters, digits,
+// underscores, and hyphens, but must not start with a hyphen.
 // Matches: "2026-02-01-session.tmp", "2026-02-01-a1b2c3d4-session.tmp",
-// and "2026-02-01-frontend-worktree-1-session.tmp"
-const SESSION_FILENAME_REGEX = /^(\d{4}-\d{2}-\d{2})(?:-([a-z0-9-]{8,}))?-session\.tmp$/;
+// "2026-02-01-frontend-worktree-1-session.tmp", and
+// "2026-02-01-ChezMoi_2-session.tmp"
+const SESSION_FILENAME_REGEX = /^(\d{4}-\d{2}-\d{2})(?:-([a-zA-Z0-9_][a-zA-Z0-9_-]*))?-session\.tmp$/;
 
 /**
  * Parse session filename to extract metadata
@@ -29,6 +32,7 @@ const SESSION_FILENAME_REGEX = /^(\d{4}-\d{2}-\d{2})(?:-([a-z0-9-]{8,}))?-sessio
  * @returns {object|null} Parsed metadata or null if invalid
  */
 function parseSessionFilename(filename) {
+  if (!filename || typeof filename !== 'string') return null;
   const match = filename.match(SESSION_FILENAME_REGEX);
   if (!match) return null;
 
@@ -74,6 +78,166 @@ function getSessionContent(sessionPath) {
   return readFile(sessionPath);
 }
 
+/**
+ * Gather session candidates from all search directories, deduplicated by filename.
+ * session-data/ entries take priority over sessions/ entries.
+ * @param {object} options - Filter options { date, search }
+ * @returns {object[]} Deduplicated, sorted session candidates
+ */
+function getSessionCandidates(options = {}) {
+  const {
+    date = null,
+    search = null
+  } = options;
+
+  const candidates = [];
+
+  for (const sessionsDir of getSessionSearchDirs()) {
+    if (!fs.existsSync(sessionsDir)) {
+      continue;
+    }
+
+    let entries;
+    try {
+      entries = fs.readdirSync(sessionsDir, { withFileTypes: true });
+    } catch (error) {
+      log(`[SessionManager] Error reading sessions directory ${sessionsDir}: ${error.message}`);
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.tmp')) continue;
+
+      const filename = entry.name;
+      const metadata = parseSessionFilename(filename);
+
+      if (!metadata) continue;
+      if (date && metadata.date !== date) continue;
+      if (search && !metadata.shortId.includes(search)) continue;
+
+      const sessionPath = path.join(sessionsDir, filename);
+
+      let stats;
+      try {
+        stats = fs.statSync(sessionPath);
+      } catch {
+        continue;
+      }
+
+      candidates.push({
+        ...metadata,
+        sessionPath,
+        hasContent: stats.size > 0,
+        size: stats.size,
+        modifiedTime: stats.mtime,
+        createdTime: stats.birthtime || stats.ctime
+      });
+    }
+  }
+
+  const deduped = [];
+  const seenFilenames = new Set();
+
+  for (const session of candidates) {
+    if (seenFilenames.has(session.filename)) {
+      continue;
+    }
+    seenFilenames.add(session.filename);
+    deduped.push(session);
+  }
+
+  deduped.sort((a, b) => b.modifiedTime - a.modifiedTime);
+  return deduped;
+}
+
+/**
+ * Build a session record from a path and metadata
+ * @param {string} sessionPath - Full path to session file
+ * @param {object} metadata - Parsed filename metadata
+ * @returns {object|null} Session record or null if stat fails
+ */
+function buildSessionRecord(sessionPath, metadata) {
+  let stats;
+  try {
+    stats = fs.statSync(sessionPath);
+  } catch {
+    return null;
+  }
+
+  return {
+    ...metadata,
+    sessionPath,
+    hasContent: stats.size > 0,
+    size: stats.size,
+    modifiedTime: stats.mtime,
+    createdTime: stats.birthtime || stats.ctime
+  };
+}
+
+/**
+ * Check if a session's metadata matches a given session ID
+ * @param {object} metadata - Parsed filename metadata
+ * @param {string} normalizedSessionId - Trimmed session ID to match against
+ * @returns {boolean} True if the session matches
+ */
+function sessionMatchesId(metadata, normalizedSessionId) {
+  const filename = metadata.filename;
+  const shortIdMatch = metadata.shortId !== 'no-id' && metadata.shortId.startsWith(normalizedSessionId);
+  const filenameMatch = filename === normalizedSessionId || filename === `${normalizedSessionId}.tmp`;
+  const noIdMatch = metadata.shortId === 'no-id' && filename === `${normalizedSessionId}-session.tmp`;
+
+  return shortIdMatch || filenameMatch || noIdMatch;
+}
+
+/**
+ * Find matching session candidates across all search directories
+ * @param {string} normalizedSessionId - Trimmed session ID to match
+ * @returns {object[]} Matching session records, sorted by modification time
+ */
+function getMatchingSessionCandidates(normalizedSessionId) {
+  const matches = [];
+  const seenFilenames = new Set();
+
+  for (const sessionsDir of getSessionSearchDirs()) {
+    if (!fs.existsSync(sessionsDir)) {
+      continue;
+    }
+
+    let entries;
+    try {
+      entries = fs.readdirSync(sessionsDir, { withFileTypes: true });
+    } catch (error) {
+      log(`[SessionManager] Error reading sessions directory ${sessionsDir}: ${error.message}`);
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.tmp')) continue;
+
+      const metadata = parseSessionFilename(entry.name);
+      if (!metadata || !sessionMatchesId(metadata, normalizedSessionId)) {
+        continue;
+      }
+
+      if (seenFilenames.has(metadata.filename)) {
+        continue;
+      }
+
+      const sessionPath = path.join(sessionsDir, metadata.filename);
+      const sessionRecord = buildSessionRecord(sessionPath, metadata);
+      if (!sessionRecord) {
+        continue;
+      }
+
+      seenFilenames.add(metadata.filename);
+      matches.push(sessionRecord);
+    }
+  }
+
+  matches.sort((a, b) => b.modifiedTime - a.modifiedTime);
+  return matches;
+}
+
 /**
  * Parse session metadata from markdown content
  * @param {string} content - Session markdown content
@@ -85,6 +249,9 @@ function parseSessionMetadata(content) {
     date: null,
     started: null,
     lastUpdated: null,
+    project: null,
+    branch: null,
+    worktree: null,
     completed: [],
     inProgress: [],
     notes: '',
@@ -117,6 +284,22 @@ function parseSessionMetadata(content) {
     metadata.lastUpdated = updatedMatch[1];
   }
 
+  // Extract control-plane metadata
+  const projectMatch = content.match(/\*\*Project:\*\*\s*(.+)$/m);
+  if (projectMatch) {
+    metadata.project = projectMatch[1].trim();
+  }
+
+  const branchMatch = content.match(/\*\*Branch:\*\*\s*(.+)$/m);
+  if (branchMatch) {
+    metadata.branch = branchMatch[1].trim();
+  }
+
+  const worktreeMatch = content.match(/\*\*Worktree:\*\*\s*(.+)$/m);
+  if (worktreeMatch) {
+    metadata.worktree = worktreeMatch[1].trim();
+  }
+
   // Extract completed items
   const completedSection = content.match(/### Completed\s*\n([\s\S]*?)(?=###|\n\n|$)/);
   if (completedSection) {
@@ -208,58 +391,12 @@ function getAllSessions(options = {}) {
   const limitNum = Number(rawLimit);
   const limit = Number.isNaN(limitNum) ? 50 : Math.max(1, Math.floor(limitNum));
 
-  const sessionsDir = getSessionsDir();
+  const sessions = getSessionCandidates({ date, search });
 
-  if (!fs.existsSync(sessionsDir)) {
+  if (sessions.length === 0) {
     return { sessions: [], total: 0, offset, limit, hasMore: false };
   }
 
-  const entries = fs.readdirSync(sessionsDir, { withFileTypes: true });
-  const sessions = [];
-
-  for (const entry of entries) {
-    // Skip non-files (only process .tmp files)
-    if (!entry.isFile() || !entry.name.endsWith('.tmp')) continue;
-
-    const filename = entry.name;
-    const metadata = parseSessionFilename(filename);
-
-    if (!metadata) continue;
-
-    // Apply date filter
-    if (date && metadata.date !== date) {
-      continue;
-    }
-
-    // Apply search filter (search in short ID)
-    if (search && !metadata.shortId.includes(search)) {
-      continue;
-    }
-
-    const sessionPath = path.join(sessionsDir, filename);
-
-    // Get file stats (wrapped in try-catch to handle TOCTOU race where
-    // file is deleted between readdirSync and statSync)
-    let stats;
-    try {
-      stats = fs.statSync(sessionPath);
-    } catch {
-      continue; // File was deleted between readdir and stat
-    }
-
-    sessions.push({
-      ...metadata,
-      sessionPath,
-      hasContent: stats.size > 0,
-      size: stats.size,
-      modifiedTime: stats.mtime,
-      createdTime: stats.birthtime || stats.ctime
-    });
-  }
-
-  // Sort by modified time (newest first)
-  sessions.sort((a, b) => b.modifiedTime - a.modifiedTime);
-
   // Apply pagination
   const paginatedSessions = sessions.slice(offset, offset + limit);
 
@@ -279,55 +416,28 @@ function getAllSessions(options = {}) {
  * @returns {object|null} Session object or null if not found
  */
 function getSessionById(sessionId, includeContent = false) {
-  const sessionsDir = getSessionsDir();
-
-  if (!fs.existsSync(sessionsDir)) {
+  if (typeof sessionId !== 'string') {
     return null;
   }
 
-  const entries = fs.readdirSync(sessionsDir, { withFileTypes: true });
-
-  for (const entry of entries) {
-    if (!entry.isFile() || !entry.name.endsWith('.tmp')) continue;
-
-    const filename = entry.name;
-    const metadata = parseSessionFilename(filename);
-
-    if (!metadata) continue;
-
-    // Check if session ID matches (short ID or full filename without .tmp)
-    const shortIdMatch = sessionId.length > 0 && metadata.shortId !== 'no-id' && metadata.shortId.startsWith(sessionId);
-    const filenameMatch = filename === sessionId || filename === `${sessionId}.tmp`;
-    const noIdMatch = metadata.shortId === 'no-id' && filename === `${sessionId}-session.tmp`;
-
-    if (!shortIdMatch && !filenameMatch && !noIdMatch) {
-      continue;
-    }
+  const normalizedSessionId = sessionId.trim();
+  if (!normalizedSessionId) {
+    return null;
+  }
 
-    const sessionPath = path.join(sessionsDir, filename);
-    let stats;
-    try {
-      stats = fs.statSync(sessionPath);
-    } catch {
-      return null; // File was deleted between readdir and stat
-    }
+  const sessions = getMatchingSessionCandidates(normalizedSessionId);
 
-    const session = {
-      ...metadata,
-      sessionPath,
-      size: stats.size,
-      modifiedTime: stats.mtime,
-      createdTime: stats.birthtime || stats.ctime
-    };
+  for (const session of sessions) {
+    const sessionRecord = { ...session };
 
     if (includeContent) {
-      session.content = getSessionContent(sessionPath);
-      session.metadata = parseSessionMetadata(session.content);
+      sessionRecord.content = getSessionContent(sessionRecord.sessionPath);
+      sessionRecord.metadata = parseSessionMetadata(sessionRecord.content);
       // Pass pre-read content to avoid a redundant disk read
-      session.stats = getSessionStats(session.content || '');
+      sessionRecord.stats = getSessionStats(sessionRecord.content || '');
     }
 
-    return session;
+    return sessionRecord;
   }
 
   return null;

package/{ecc/scripts → src}/lib/utils.d.ts

@@ -18,9 +18,15 @@ export function getHomeDir(): string;
 /** Get the Claude config directory (~/.claude) */
 export function getClaudeDir(): string;
 
-/** Get the sessions directory (~/.claude/sessions) */
+/** Get the sessions directory (~/.claude/session-data) */
 export function getSessionsDir(): string;
 
+/** Get the legacy sessions directory (~/.claude/sessions) used by older installs */
+export function getLegacySessionsDir(): string;
+
+/** Get all session directories to search, in canonical-first order */
+export function getSessionSearchDirs(): string[];
+
 /** Get the learned skills directory (~/.claude/skills/learned) */
 export function getLearnedSkillsDir(): string;
 
@@ -47,6 +53,14 @@ export function getDateTimeString(): string;
 
 // --- Session/Project ---
 
+/**
+ * Sanitize a string for use as a session filename segment.
+ * Replaces invalid characters, handles non-ASCII via hashing,
+ * and guards against Windows reserved names.
+ * @returns Sanitized string, or null if input is empty/meaningless
+ */
+export function sanitizeSessionId(raw: string): string | null;
+
 /**
  * Get short session ID from CLAUDE_SESSION_ID environment variable.
  * Returns last 8 characters, falls back to project name then the provided fallback.
@@ -123,6 +137,14 @@ export interface GrepMatch {
 /** Search for a pattern in a file and return matching lines with line numbers */
 export function grepFile(filePath: string, pattern: string | RegExp): GrepMatch[];
 
+// --- String sanitisation ---
+
+/**
+ * Strip all ANSI escape sequences from a string.
+ * Handles CSI, OSC, charset selection, and bare ESC sequences.
+ */
+export function stripAnsi(str: string): string;
+
 // --- Hook I/O ---
 
 export interface ReadStdinJsonOptions {

package/{ecc/scripts → src}/lib/utils.js

@@ -6,12 +6,20 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
 const { execSync, spawnSync } = require('child_process');
 
 // Platform detection
 const isWindows = process.platform === 'win32';
 const isMacOS = process.platform === 'darwin';
 const isLinux = process.platform === 'linux';
+const SESSION_DATA_DIR_NAME = 'session-data';
+const LEGACY_SESSIONS_DIR_NAME = 'sessions';
+const WINDOWS_RESERVED_SESSION_IDS = new Set([
+  'CON', 'PRN', 'AUX', 'NUL',
+  'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+  'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9'
+]);
 
 /**
  * Get the user's home directory (cross-platform)
@@ -21,17 +29,38 @@ function getHomeDir() {
 }
 
 /**
- * Get the Claude config directory
+ * Get the Claude config directory.
+ * Self-detects local CCP installs by checking for .claude/pilot/VERSION
+ * in the current working directory. Falls back to CLAUDE_CONFIG_DIR env
+ * var or the global ~/.claude/ directory.
  */
 function getClaudeDir() {
-  return path.join(getHomeDir(), '.claude');
+  const localDir = path.join(process.cwd(), '.claude');
+  if (fs.existsSync(path.join(localDir, 'pilot', 'VERSION'))) {
+    return localDir;
+  }
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 }
 
 /**
  * Get the sessions directory
  */
 function getSessionsDir() {
-  return path.join(getClaudeDir(), 'sessions');
+  return path.join(getClaudeDir(), SESSION_DATA_DIR_NAME);
+}
+
+/**
+ * Get the legacy sessions directory used by older ECC installs
+ */
+function getLegacySessionsDir() {
+  return path.join(getClaudeDir(), LEGACY_SESSIONS_DIR_NAME);
+}
+
+/**
+ * Get all session directories to search, in canonical-first order
+ */
+function getSessionSearchDirs() {
+  return Array.from(new Set([getSessionsDir(), getLegacySessionsDir()]));
 }
 
 /**
@@ -107,6 +136,41 @@ function getProjectName() {
   return path.basename(process.cwd()) || null;
 }
 
+/**
+ * Sanitize a string for use as a session filename segment.
+ * Replaces invalid characters with hyphens, collapses runs, strips
+ * leading/trailing hyphens, and removes leading dots so hidden-dir names
+ * like ".claude" map cleanly to "claude".
+ *
+ * Pure non-ASCII inputs get a stable 8-char hash so distinct names do not
+ * collapse to the same fallback session id. Mixed-script inputs retain their
+ * ASCII part and gain a short hash suffix for disambiguation.
+ */
+function sanitizeSessionId(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+
+  const hasNonAscii = Array.from(raw).some(char => char.codePointAt(0) > 0x7f);
+  const normalized = raw.replace(/^\.+/, '');
+  const sanitized = normalized
+    .replace(/[^a-zA-Z0-9_-]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  if (sanitized.length > 0) {
+    const suffix = crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 6);
+    if (WINDOWS_RESERVED_SESSION_IDS.has(sanitized.toUpperCase())) {
+      return `${sanitized}-${suffix}`;
+    }
+    if (!hasNonAscii) return sanitized;
+    return `${sanitized}-${suffix}`;
+  }
+
+  const meaningful = normalized.replace(/[\s\p{P}]/gu, '');
+  if (meaningful.length === 0) return null;
+
+  return crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 8);
+}
+
 /**
  * Get short session ID from CLAUDE_SESSION_ID environment variable
  * Returns last 8 characters, falls back to project name then 'default'
@@ -464,6 +528,24 @@ function countInFile(filePath, pattern) {
   return matches ? matches.length : 0;
 }
 
+/**
+ * Strip all ANSI escape sequences from a string.
+ *
+ * Handles:
+ * - CSI sequences: \x1b[ ... <letter>  (colors, cursor movement, erase, etc.)
+ * - OSC sequences: \x1b] ... BEL/ST    (window titles, hyperlinks)
+ * - Charset selection: \x1b(B
+ * - Bare ESC + single letter: \x1b <letter>  (e.g. \x1bM for reverse index)
+ *
+ * @param {string} str - Input string possibly containing ANSI codes
+ * @returns {string} Cleaned string with all escape sequences removed
+ */
+function stripAnsi(str) {
+  if (typeof str !== 'string') return '';
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b(?:\[[0-9;?]*[A-Za-z]|\][^\x07\x1b]*(?:\x07|\x1b\\)|\([A-Z]|[A-Z])/g, '');
+}
+
 /**
  * Search for pattern in file and return matching lines with line numbers
  */
@@ -507,6 +589,8 @@ module.exports = {
   getHomeDir,
   getClaudeDir,
   getSessionsDir,
+  getLegacySessionsDir,
+  getSessionSearchDirs,
   getLearnedSkillsDir,
   getTempDir,
   ensureDir,
@@ -517,6 +601,7 @@ module.exports = {
   getDateTimeString,
 
   // Session/Project
+  sanitizeSessionId,
   getSessionIdShort,
   getGitRepoName,
   getProjectName,
@@ -530,6 +615,9 @@ module.exports = {
   countInFile,
   grepFile,
 
+  // String sanitisation
+  stripAnsi,
+
   // Hook I/O
   readStdinJson,
   log,