@sylphx/flow 3.20.0 → 3.21.1

package/src/core/__tests__/session-cleanup.test.ts

@@ -1,12 +1,13 @@
 /**
- * Tests for SessionManager cleanup functionality
- * Covers: cleanupSessionHistory, multi-session lifecycle
+ * Tests for SessionManager — PID-based session management
+ * Covers: acquireSession, releaseSession, detectOrphanedSessions,
+ * finalizeSessionCleanup, cleanupSessionHistory
  */
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { ProjectManager } from '../project-manager.js';
 import { SessionManager } from '../session-manager.js';
 
@@ -39,6 +40,331 @@ describe('SessionManager', () => {
     }
   });
 
+  // --- acquireSession ---
+
+  describe('acquireSession()', () => {
+    it('should detect first session via atomic mkdir', async () => {
+      const projectPath = path.join(tempDir, 'project');
+      fs.mkdirSync(projectPath, { recursive: true });
+      const hash = projectManager.getProjectHash(projectPath);
+
+      const result = await sessionManager.acquireSession(hash, projectPath, 'claude-code', {
+        sessionId: 'session-1',
+        backupPath: '/tmp/backup',
+      });
+
+      expect(result.isFirstSession).toBe(true);
+      expect(result.backupRef).not.toBeNull();
+      expect(result.backupRef?.sessionId).toBe('session-1');
+      expect(result.backupRef?.createdByPid).toBe(process.pid);
+
+      // Verify PID file was written
+      const paths = projectManager.getProjectPaths(hash);
+      const pidFile = path.join(paths.pidsDir, `${process.pid}.json`);
+      expect(fs.existsSync(pidFile)).toBe(true);
+
+      // Verify backup.json was written
+      expect(fs.existsSync(paths.backupRefFile)).toBe(true);
+    });
+
+    it('should detect join when pids/ already exists', async () => {
+      const projectPath = path.join(tempDir, 'project');
+      fs.mkdirSync(projectPath, { recursive: true });
+      const hash = projectManager.getProjectHash(projectPath);
+      const paths = projectManager.getProjectPaths(hash);
+
+      // Pre-create pids/ directory and backup.json (simulating first session)
+      fs.mkdirSync(paths.pidsDir, { recursive: true });
+      const backupRef = {
+        sessionId: 'session-existing',
+        backupPath: '/tmp/backup',
+        projectPath,
+        target: 'claude-code',
+        createdAt: new Date().toISOString(),
+        createdByPid: 99999,
+      };
+      fs.writeFileSync(paths.backupRefFile, JSON.stringify(backupRef));
+
+      // Second process joins
+      const result = await sessionManager.acquireSession(hash, projectPath, 'claude-code');
+
+      expect(result.isFirstSession).toBe(false);
+      expect(result.backupRef?.sessionId).toBe('session-existing');
+
+      // Verify our PID file was written
+      const pidFile = path.join(paths.pidsDir, `${process.pid}.json`);
+      expect(fs.existsSync(pidFile)).toBe(true);
+    });
+
+    it('should handle race condition (mkdir EEXIST)', async () => {
+      const projectPath = path.join(tempDir, 'project');
+      fs.mkdirSync(projectPath, { recursive: true });
+      const hash = projectManager.getProjectHash(projectPath);
+      const paths = projectManager.getProjectPaths(hash);
+
+      // Pre-create the session dir but NOT pids/
+      fs.mkdirSync(paths.sessionDir, { recursive: true });
+
+      // First call creates pids/
+      const result1 = await sessionManager.acquireSession(hash, projectPath, 'claude-code', {
+        sessionId: 'session-race',
+        backupPath: '/tmp/backup',
+      });
+      expect(result1.isFirstSession).toBe(true);
+
+      // Second call should get EEXIST and join
+      const result2 = await sessionManager.acquireSession(hash, projectPath, 'claude-code');
+      expect(result2.isFirstSession).toBe(false);
+    });
+  });
+
+  // --- releaseSession ---
+
+  describe('releaseSession()', () => {
+    it('should return shouldRestore=true when last PID', async () => {
+      const projectPath = path.join(tempDir, 'project');
+      fs.mkdirSync(projectPath, { recursive: true });
+      const hash = projectManager.getProjectHash(projectPath);
+
+      // Acquire session
+      await sessionManager.acquireSession(hash, projectPath, 'claude-code', {
+        sessionId: 'session-1',
+        backupPath: '/tmp/backup',
+      });
+
+      // Release — we're the only PID
+      const result = await sessionManager.releaseSession(hash);
+
+      expect(result.shouldRestore).toBe(true);
+      expect(result.backupRef?.sessionId).toBe('session-1');
+    });
+
+    it('should return shouldRestore=false when other alive PIDs exist', async () => {
+      const projectPath = path.join(tempDir, 'project');
+      fs.mkdirSync(projectPath, { recursive: true });
+      const hash = projectManager.getProjectHash(projectPath);
+      const paths = projectManager.getProjectPaths(hash);
+
+      // Acquire session
+      await sessionManager.acquireSession(hash, projectPath, 'claude-code', {
+        sessionId: 'session-1',
+        backupPath: '/tmp/backup',
+      });
+
+      // Simulate another alive process (PID 1 is always alive on Unix)
+      fs.writeFileSync(
+        path.join(paths.pidsDir, '1.json'),
+        JSON.stringify({ pid: 1, startTime: new Date().toISOString() })
+      );
+
+      // Release — PID 1 is still alive
+      const result = await sessionManager.releaseSession(hash);
+
+      expect(result.shouldRestore).toBe(false);
+    });
+
+    it('should clean dead PID files during release', async () => {
+      const projectPath = path.join(tempDir, 'project');
+      fs.mkdirSync(projectPath, { recursive: true });
+      const hash = projectManager.getProjectHash(projectPath);
+      const paths = projectManager.getProjectPaths(hash);
+
+      // Acquire session
+      await sessionManager.acquireSession(hash, projectPath, 'claude-code', {
+        sessionId: 'session-1',
+        backupPath: '/tmp/backup',
+      });
+
+      // Simulate a dead process (PID that doesn't exist)
+      fs.writeFileSync(
+        path.join(paths.pidsDir, '999999.json'),
+        JSON.stringify({ pid: 999999, startTime: new Date().toISOString() })
+      );
+
+      // Release — should clean dead PID file
+      const result = await sessionManager.releaseSession(hash);
+
+      // Dead PID file should be cleaned
+      expect(fs.existsSync(path.join(paths.pidsDir, '999999.json'))).toBe(false);
+      // Only our PID was alive, and we removed it — shouldRestore
+      expect(result.shouldRestore).toBe(true);
+    });
+  });
+
+  // --- detectOrphanedSessions ---
+
+  describe('detectOrphanedSessions()', () => {
+    it('should detect orphaned sessions (backup.json + no alive PIDs)', async () => {
+      const hash = 'orphanedproject1';
+      const paths = projectManager.getProjectPaths(hash);
+
+      // Create session dir with backup.json and dead PID
+      fs.mkdirSync(paths.pidsDir, { recursive: true });
+      const backupRef = {
+        sessionId: 'session-orphan',
+        backupPath: '/tmp/backup',
+        projectPath: '/tmp/project',
+        target: 'claude-code',
+        createdAt: new Date().toISOString(),
+        createdByPid: 999999,
+      };
+      fs.writeFileSync(paths.backupRefFile, JSON.stringify(backupRef));
+      fs.writeFileSync(
+        path.join(paths.pidsDir, '999999.json'),
+        JSON.stringify({ pid: 999999 })
+      );
+
+      const orphaned = await sessionManager.detectOrphanedSessions();
+
+      expect(orphaned.size).toBe(1);
+      expect(orphaned.has(hash)).toBe(true);
+      expect(orphaned.get(hash)?.sessionId).toBe('session-orphan');
+    });
+
+    it('should NOT detect sessions with alive PIDs as orphaned', async () => {
+      const hash = 'activeproject1';
+      const paths = projectManager.getProjectPaths(hash);
+
+      // Create session dir with backup.json and alive PID (PID 1)
+      fs.mkdirSync(paths.pidsDir, { recursive: true });
+      fs.writeFileSync(
+        paths.backupRefFile,
+        JSON.stringify({
+          sessionId: 'session-active',
+          backupPath: '/tmp/backup',
+          projectPath: '/tmp/project',
+          target: 'claude-code',
+          createdAt: new Date().toISOString(),
+          createdByPid: 1,
+        })
+      );
+      fs.writeFileSync(
+        path.join(paths.pidsDir, '1.json'),
+        JSON.stringify({ pid: 1 })
+      );
+
+      const orphaned = await sessionManager.detectOrphanedSessions();
+
+      expect(orphaned.size).toBe(0);
+    });
+
+    it('should clean stale session dirs without backup.json', async () => {
+      const hash = 'staleproject1';
+      const paths = projectManager.getProjectPaths(hash);
+
+      // Create session dir without backup.json
+      fs.mkdirSync(paths.pidsDir, { recursive: true });
+
+      const orphaned = await sessionManager.detectOrphanedSessions();
+
+      expect(orphaned.size).toBe(0);
+      // Stale directory should be cleaned up
+      expect(fs.existsSync(paths.sessionDir)).toBe(false);
+    });
+  });
+
+  // --- finalizeSessionCleanup ---
+
+  describe('finalizeSessionCleanup()', () => {
+    it('should remove session directory and archive to history', async () => {
+      const hash = 'finalize1';
+      const paths = projectManager.getProjectPaths(hash);
+
+      // Create session with backup.json
+      fs.mkdirSync(paths.pidsDir, { recursive: true });
+      fs.writeFileSync(
+        paths.backupRefFile,
+        JSON.stringify({
+          sessionId: 'session-finalize',
+          backupPath: '/tmp/backup',
+          projectPath: '/tmp/project',
+          target: 'claude-code',
+          createdAt: new Date().toISOString(),
+          createdByPid: process.pid,
+        })
+      );
+
+      await sessionManager.finalizeSessionCleanup(hash);
+
+      // Session dir should be gone
+      expect(fs.existsSync(paths.sessionDir)).toBe(false);
+
+      // History file should exist
+      const historyPath = path.join(flowHome, 'sessions', 'history', 'session-finalize.json');
+      expect(fs.existsSync(historyPath)).toBe(true);
+      const archived = JSON.parse(fs.readFileSync(historyPath, 'utf-8'));
+      expect(archived.status).toBe('completed');
+      expect(archived.sessionId).toBe('session-finalize');
+    });
+  });
+
+  // --- getBackupRef ---
+
+  describe('getBackupRef()', () => {
+    it('should return null for non-existent session', async () => {
+      const ref = await sessionManager.getBackupRef('nonexistent');
+      expect(ref).toBeNull();
+    });
+
+    it('should return backup ref when exists', async () => {
+      const hash = 'reftest1';
+      const paths = projectManager.getProjectPaths(hash);
+
+      fs.mkdirSync(paths.sessionDir, { recursive: true });
+      fs.writeFileSync(
+        paths.backupRefFile,
+        JSON.stringify({
+          sessionId: 'session-ref',
+          backupPath: '/tmp/backup',
+          projectPath: '/tmp/project',
+          target: 'claude-code',
+          createdAt: new Date().toISOString(),
+          createdByPid: 1234,
+        })
+      );
+
+      const ref = await sessionManager.getBackupRef(hash);
+      expect(ref?.sessionId).toBe('session-ref');
+    });
+  });
+
+  // --- isSessionActive ---
+
+  describe('isSessionActive()', () => {
+    it('should return false when no backup.json', async () => {
+      const active = await sessionManager.isSessionActive('nonexistent');
+      expect(active).toBe(false);
+    });
+
+    it('should return true when backup.json exists and alive PIDs', async () => {
+      const hash = 'active1';
+      const paths = projectManager.getProjectPaths(hash);
+
+      fs.mkdirSync(paths.pidsDir, { recursive: true });
+      fs.writeFileSync(paths.backupRefFile, JSON.stringify({ sessionId: 'test' }));
+      // PID 1 is always alive
+      fs.writeFileSync(path.join(paths.pidsDir, '1.json'), JSON.stringify({ pid: 1 }));
+
+      const active = await sessionManager.isSessionActive(hash);
+      expect(active).toBe(true);
+    });
+
+    it('should return false when backup.json exists but no alive PIDs', async () => {
+      const hash = 'dead1';
+      const paths = projectManager.getProjectPaths(hash);
+
+      fs.mkdirSync(paths.pidsDir, { recursive: true });
+      fs.writeFileSync(paths.backupRefFile, JSON.stringify({ sessionId: 'test' }));
+      // Dead PID
+      fs.writeFileSync(path.join(paths.pidsDir, '999999.json'), JSON.stringify({ pid: 999999 }));
+
+      const active = await sessionManager.isSessionActive(hash);
+      expect(active).toBe(false);
+    });
+  });
+
+  // --- cleanupSessionHistory (unchanged) ---
+
   describe('cleanupSessionHistory()', () => {
     it('should keep only last N session history files', async () => {
       const historyDir = path.join(flowHome, 'sessions', 'history');
@@ -112,36 +438,4 @@ describe('SessionManager', () => {
       expect(remaining).toContain('notes.txt');
     });
   });
-
-  describe('Session lifecycle', () => {
-    it('should create and end a session', async () => {
-      const projectPath = path.join(tempDir, 'project');
-      fs.mkdirSync(projectPath, { recursive: true });
-
-      const hash = projectManager.getProjectHash(projectPath);
-
-      const { session, isFirstSession } = await sessionManager.startSession(
-        projectPath,
-        hash,
-        'claude-code',
-        '/tmp/backup',
-        'session-test-1'
-      );
-
-      expect(isFirstSession).toBe(true);
-      expect(session.projectPath).toBe(projectPath);
-      expect(session.sessionId).toBe('session-test-1');
-      expect(session.refCount).toBe(1);
-
-      // Verify active session exists
-      const active = await sessionManager.getActiveSession(hash);
-      expect(active).not.toBeNull();
-      expect(active?.sessionId).toBe('session-test-1');
-    });
-
-    it('should return null for non-existent session', async () => {
-      const active = await sessionManager.getActiveSession('nonexistent');
-      expect(active).toBeNull();
-    });
-  });
 });

package/src/core/backup-manager.ts

@@ -149,7 +149,16 @@ export class BackupManager {
   }
 
   /**
-   * Restore backup to project
+   * Restore backup to project (atomic).
+   *
+   * Uses copy-to-temp → rm → rename pattern to ensure atomicity:
+   * 1. Copy backup → temp dir (.claude.flow-restore-<timestamp>)
+   * 2. rm -rf current config dir
+   * 3. fs.rename(temp, configDir) — atomic on same filesystem
+   *
+   * If the process dies after step 2 but before step 3, the temp dir
+   * still exists. cleanupOrphanedRestores() detects this on next startup
+   * and renames it into place as recovery.
    */
   async restoreBackup(projectHash: string, sessionId: string): Promise<void> {
     const paths = this.projectManager.getProjectPaths(projectHash);
@@ -169,19 +178,56 @@ export class BackupManager {
     // Resolve target to get config
     const target = resolveTarget(targetId);
 
-    // Get target config directory
+    // Get target config directory (e.g., /project/.claude)
     const targetConfigDir = this.projectManager.getTargetConfigDir(projectPath, target);
+    const backupTargetDir = path.join(backupPath, target.config.configDir);
 
-    // Remove current target directory
-    if (existsSync(targetConfigDir)) {
-      await fs.rm(targetConfigDir, { recursive: true, force: true });
+    if (!existsSync(backupTargetDir)) {
+      // No backup config to restore — just remove current config
+      if (existsSync(targetConfigDir)) {
+        await fs.rm(targetConfigDir, { recursive: true, force: true });
+      }
+      return;
     }
 
-    // Restore from backup using target config's configDir
-    const backupTargetDir = path.join(backupPath, target.config.configDir);
+    // Atomic restore: copy → rm → rename
+    const tempDir = path.join(
+      path.dirname(targetConfigDir),
+      `${path.basename(targetConfigDir)}.flow-restore-${Date.now()}`
+    );
 
-    if (existsSync(backupTargetDir)) {
-      await this.copyDirectory(backupTargetDir, targetConfigDir);
+    try {
+      // 1. Copy backup to temp dir
+      await this.copyDirectory(backupTargetDir, tempDir);
+
+      // 2. Remove current config dir
+      if (existsSync(targetConfigDir)) {
+        await fs.rm(targetConfigDir, { recursive: true, force: true });
+      }
+
+      // 3. Rename temp → config dir (atomic on same filesystem)
+      try {
+        await fs.rename(tempDir, targetConfigDir);
+      } catch (renameError: unknown) {
+        // EXDEV: cross-device link — source and dest on different filesystems.
+        // Fall back to copy + delete (not atomic, but functional).
+        if (renameError instanceof Error && 'code' in renameError && (renameError as NodeJS.ErrnoException).code === 'EXDEV') {
+          await this.copyDirectory(tempDir, targetConfigDir);
+          await fs.rm(tempDir, { recursive: true, force: true });
+        } else {
+          throw renameError;
+        }
+      }
+    } catch (error) {
+      // Clean up temp dir on failure
+      try {
+        if (existsSync(tempDir)) {
+          await fs.rm(tempDir, { recursive: true, force: true });
+        }
+      } catch {
+        // Ignore cleanup errors
+      }
+      throw error;
     }
   }
 
@@ -214,6 +260,50 @@ export class BackupManager {
     await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
   }
 
+  /**
+   * Clean up orphaned .flow-restore-* temp directories left by interrupted restores.
+   * If the process dies between rm(.claude) and rename(temp, .claude), the temp dir
+   * is stranded. This scans known project paths and removes any orphaned temp dirs.
+   *
+   * If the config dir is also missing (both deleted), the temp dir IS the backup —
+   * rename it into place as recovery.
+   */
+  async cleanupOrphanedRestores(projectPath: string, targetOrId: Target | string): Promise<void> {
+    const target = resolveTargetOrId(targetOrId);
+    const targetConfigDir = this.projectManager.getTargetConfigDir(projectPath, target);
+    const parentDir = path.dirname(targetConfigDir);
+    const configBaseName = path.basename(targetConfigDir);
+
+    if (!existsSync(parentDir)) {
+      return;
+    }
+
+    try {
+      const entries = await fs.readdir(parentDir);
+      const orphanedRestores = entries.filter(
+        (e) => e.startsWith(`${configBaseName}.flow-restore-`)
+      );
+
+      for (const orphan of orphanedRestores) {
+        const orphanPath = path.join(parentDir, orphan);
+        if (!existsSync(targetConfigDir)) {
+          // Config dir is gone — this temp dir IS the recovery. Rename it in.
+          try {
+            await fs.rename(orphanPath, targetConfigDir);
+          } catch {
+            // If rename fails, remove it
+            await fs.rm(orphanPath, { recursive: true, force: true }).catch(() => {});
+          }
+        } else {
+          // Config dir exists — temp dir is a leftover. Remove it.
+          await fs.rm(orphanPath, { recursive: true, force: true }).catch(() => {});
+        }
+      }
+    } catch {
+      // Non-fatal — project dir might not exist
+    }
+  }
+
   /**
    * Cleanup old backups (keep last N)
    */