@sylphx/flow 3.19.1 → 3.21.0

package/src/core/cleanup-handler.ts

@@ -1,16 +1,17 @@
 /**
  * Cleanup Handler
  * Manages graceful cleanup on exit and crash recovery
- * Handles process signals and ensures backup restoration
  *
  * Centralized cleanup for all exit paths:
- * - Signal (SIGINT/SIGTERM) → onSignal() → restore + cleanup
- * - Manual (FlowExecutor.cleanup) → cleanup() → restore + cleanup
- * - Crash recovery (next startup) → recoverOnStartup() → restore + prune
+ * - Signal (SIGTERM) → onSignal() → release + restore + finalize
+ * - Manual (FlowExecutor.cleanup) → cleanup() → release + restore + finalize
+ * - Crash recovery (next startup) → recoverOnStartup() → restore + finalize
  *
- * IMPORTANT: Node.js 'exit' event handlers MUST be synchronous.
- * We use SIGINT/SIGTERM handlers to perform async cleanup before exiting.
- * The 'exit' handler is only a last-resort sync cleanup.
+ * SIGINT is NOT handled — the child process (claude-code) handles its own Ctrl+C.
+ * Suppression is done in execute-v2.ts around the child spawn.
+ *
+ * CRITICAL: backup.json is deleted AFTER restore succeeds (via finalizeSessionCleanup),
+ * ensuring orphan detection always works even if the process dies mid-cleanup.
  */
 
 import { existsSync } from 'node:fs';
@@ -51,7 +52,8 @@ export class CleanupHandler {
   }
 
   /**
-   * Register cleanup hooks for current project
+   * Register cleanup hooks for current project.
+   * SIGINT is intentionally NOT handled — child handles Ctrl+C.
    */
   registerCleanupHooks(projectHash: string): void {
     if (this.registered) {
@@ -61,43 +63,33 @@ export class CleanupHandler {
     this.currentProjectHash = projectHash;
     this.registered = true;
 
-    // SIGINT (Ctrl+C) - perform async cleanup then exit
-    process.on('SIGINT', () => {
-      this.handleSignal('SIGINT', 0);
-    });
-
-    // SIGTERM - perform async cleanup then exit
+    // SIGTERM — perform async cleanup then exit
     process.on('SIGTERM', () => {
       this.handleSignal('SIGTERM', 0);
     });
 
-    // Uncaught exceptions - perform async cleanup then exit with error
+    // Uncaught exceptions — perform async cleanup then exit with error
     process.on('uncaughtException', (error) => {
       console.error('\nUncaught Exception:', error);
       this.handleSignal('uncaughtException', 1);
     });
 
-    // Unhandled rejections - perform async cleanup then exit with error
+    // Unhandled rejections — perform async cleanup then exit with error
     process.on('unhandledRejection', (reason) => {
       console.error('\nUnhandled Rejection:', reason);
       this.handleSignal('unhandledRejection', 1);
     });
 
-    // 'exit' handler - SYNC ONLY, last resort
-    // This catches cases where process.exit() was called without going through signals
+    // 'exit' handler — SYNC ONLY, last resort safety net
     process.on('exit', () => {
-      // If cleanup wasn't done via signal handlers, log warning
-      // (We can't do async cleanup here - just flag it)
-      if (!this.cleanupCompleted && this.currentProjectHash) {
-        // Recovery will happen on next startup via recoverOnStartup()
-        // This is the intended safety net for abnormal exits
-      }
+      // If cleanup wasn't done via signal handlers, orphan recovery
+      // will happen on next startup via recoverOnStartup()
     });
   }
 
   /**
-   * Handle signal with async cleanup
-   * Ensures cleanup completes before process exit
+   * Handle signal with async cleanup.
+   * Ensures cleanup completes before process exit.
    */
   private handleSignal(signal: string, exitCode: number): void {
     // Prevent double cleanup
@@ -108,7 +100,6 @@ export class CleanupHandler {
 
     this.cleanupInProgress = true;
 
-    // Perform async cleanup, then exit
     this.onSignal(signal).finally(() => {
       this.cleanupCompleted = true;
       process.exit(exitCode);
@@ -116,8 +107,8 @@ export class CleanupHandler {
   }
 
   /**
-   * Async cleanup for signals and manual cleanup
-   * Handles session end and backup restoration
+   * Async cleanup for signals.
+   * Release session → restore if last → finalize AFTER restore.
    */
   private async onSignal(_signal: string): Promise<void> {
     if (!this.currentProjectHash) {
@@ -125,15 +116,12 @@ export class CleanupHandler {
     }
 
     try {
-      const { shouldRestore, session } = await this.sessionManager.endSession(
+      const { shouldRestore, backupRef } = await this.sessionManager.releaseSession(
         this.currentProjectHash
       );
 
-      if (shouldRestore && session) {
-        await this.backupManager.restoreBackup(this.currentProjectHash, session.sessionId);
-        await this.backupManager.cleanupOldBackups(this.currentProjectHash, 3);
-        await this.gitStashManager.popSettingsChanges(session.projectPath);
-        await this.secretsManager.clearSecrets(this.currentProjectHash);
+      if (shouldRestore && backupRef) {
+        await this.restoreAndFinalize(this.currentProjectHash, backupRef);
       }
     } catch (error) {
       debug('signal cleanup failed:', error);
@@ -141,24 +129,42 @@ export class CleanupHandler {
   }
 
   /**
-   * Recover on startup (for all projects)
-   * Comprehensive cleanup: crashed sessions, stale data, history pruning
-   * Silent operation - no console output
+   * Restore backup and finalize session.
+   * Single source of truth for the restore → finalize → cleanup sequence.
    *
-   * Performance: Heavy cleanup scans (history pruning, orphaned project detection)
-   * run at most once per day to avoid slowing down every startup.
+   * CRITICAL ordering: backup.json is deleted (via finalizeSessionCleanup) only
+   * AFTER restoreBackup succeeds. If restore throws, finalize is NOT called,
+   * ensuring orphan detection always works on next startup.
+   */
+  private async restoreAndFinalize(
+    projectHash: string,
+    backupRef: { sessionId: string; projectPath: string; target?: string }
+  ): Promise<void> {
+    await this.backupManager.restoreBackup(projectHash, backupRef.sessionId);
+    await this.sessionManager.finalizeSessionCleanup(projectHash);
+    await this.backupManager.cleanupOldBackups(projectHash, 3);
+    // Clean up any orphaned .flow-restore-* temp dirs from interrupted restores
+    if (backupRef.target) {
+      await this.backupManager.cleanupOrphanedRestores(backupRef.projectPath, backupRef.target).catch(() => {});
+    }
+    await this.gitStashManager.popSettingsChanges(backupRef.projectPath);
+    await this.secretsManager.clearSecrets(projectHash);
+  }
+
+  /**
+   * Recover on startup (for all projects).
+   * Handles: orphaned sessions, legacy migration, periodic heavy cleanup.
    */
   async recoverOnStartup(): Promise<void> {
+    // 0. Migrate legacy session files (old <hash>.json format → new directory format)
+    await this.migrateLegacySessions();
+
     // 1. Always recover orphaned sessions (from crashes) — fast when none exist
     const orphanedSessions = await this.sessionManager.detectOrphanedSessions();
 
-    for (const [projectHash, session] of orphanedSessions) {
+    for (const [projectHash, backupRef] of orphanedSessions) {
       try {
-        await this.backupManager.restoreBackup(projectHash, session.sessionId);
-        await this.sessionManager.recoverSession(projectHash, session);
-        await this.gitStashManager.popSettingsChanges(session.projectPath);
-        await this.secretsManager.clearSecrets(projectHash);
-        await this.backupManager.cleanupOldBackups(projectHash, 3);
+        await this.restoreAndFinalize(projectHash, backupRef);
       } catch (error) {
         debug('startup recovery failed for session:', error);
       }
@@ -178,6 +184,74 @@ export class CleanupHandler {
     }
   }
 
+  /**
+   * Migrate legacy session files (old format: sessions/<hash>.json)
+   * to new directory format (sessions/<hash>/backup.json + pids/)
+   */
+  private async migrateLegacySessions(): Promise<void> {
+    const sessionsDir = path.join(this.projectManager.getFlowHomeDir(), 'sessions');
+
+    if (!existsSync(sessionsDir)) {
+      return;
+    }
+
+    try {
+      const entries = await fs.readdir(sessionsDir, { withFileTypes: true });
+      const legacyFiles = entries.filter(
+        (e) => e.isFile() && e.name.endsWith('.json') && e.name !== '.last-cleanup'
+      );
+
+      for (const file of legacyFiles) {
+        const hash = file.name.replace('.json', '');
+        const legacyPath = path.join(sessionsDir, file.name);
+
+        try {
+          const content = JSON.parse(await fs.readFile(legacyPath, 'utf-8'));
+
+          // Only migrate if it has the old session format fields
+          if (content.sessionId && content.backupPath && content.cleanupRequired !== undefined) {
+            const paths = this.projectManager.getProjectPaths(hash);
+
+            // Create new directory structure
+            await fs.mkdir(paths.pidsDir, { recursive: true });
+
+            // Write backup.json from old session data (only if cleanup was still required)
+            if (content.cleanupRequired) {
+              const backupRef = {
+                sessionId: content.sessionId,
+                backupPath: content.backupPath,
+                projectPath: content.projectPath,
+                target: content.target,
+                createdAt: content.startTime,
+                createdByPid: content.pid,
+              };
+              await fs.writeFile(paths.backupRefFile, JSON.stringify(backupRef, null, 2));
+            }
+
+            // Remove legacy file
+            await fs.unlink(legacyPath);
+            debug('migrated legacy session %s', hash);
+          }
+        } catch (error) {
+          debug('failed to migrate legacy session %s: %O', hash, error);
+          // Move corrupt file aside instead of deleting — preserves data for diagnosis
+          try {
+            await fs.rename(legacyPath, `${legacyPath}.corrupt`);
+          } catch {
+            // If rename fails, remove it to prevent retry loops
+            try {
+              await fs.unlink(legacyPath);
+            } catch {
+              // Ignore
+            }
+          }
+        }
+      }
+    } catch (error) {
+      debug('legacy migration scan failed:', error);
+    }
+  }
+
   /**
    * Check if periodic cleanup should run (at most once per 24 hours)
    */
@@ -205,31 +279,28 @@ export class CleanupHandler {
   }
 
   /**
-   * Manually cleanup a specific project session (with multi-session support)
+   * Manually cleanup a specific project session.
+   * Release → restore if last → finalize AFTER restore.
    */
   async cleanup(projectHash: string): Promise<void> {
-    const { shouldRestore, session } = await this.sessionManager.endSession(projectHash);
-
-    if (shouldRestore && session) {
-      // Last session - full restore and cleanup
-      await this.backupManager.restoreBackup(projectHash, session.sessionId);
-      await this.backupManager.cleanupOldBackups(projectHash, 3);
-      await this.gitStashManager.popSettingsChanges(session.projectPath);
-      await this.secretsManager.clearSecrets(projectHash);
+    const { shouldRestore, backupRef } = await this.sessionManager.releaseSession(projectHash);
+
+    if (shouldRestore && backupRef) {
+      await this.restoreAndFinalize(projectHash, backupRef);
     }
   }
 
   /**
-   * Clean up data for projects whose paths no longer exist
-   * Detects orphaned project hashes by checking if the original project path is accessible
+   * Clean up data for projects whose paths no longer exist.
+   * Uses isSessionActive instead of getActiveSession.
    */
   private async cleanupOrphanedProjects(): Promise<void> {
     const allHashes = await this.getAllProjectHashes();
 
     for (const hash of allHashes) {
       // Skip projects with active sessions
-      const activeSession = await this.sessionManager.getActiveSession(hash);
-      if (activeSession) {
+      const isActive = await this.sessionManager.isSessionActive(hash);
+      if (isActive) {
         continue;
       }
 
@@ -267,7 +338,6 @@ export class CleanupHandler {
       }
     };
 
-    // Scan both directories in parallel
     const [backupHashes, secretHashes] = await Promise.all([
       scanDir(path.join(flowHome, 'backups')),
       scanDir(path.join(flowHome, 'secrets')),
@@ -302,7 +372,7 @@ export class CleanupHandler {
   }
 
   /**
-   * Remove all stored data for a project hash (backups, secrets, session file)
+   * Remove all stored data for a project hash (backups, secrets, session dir)
    */
   private async cleanupProjectData(projectHash: string): Promise<void> {
     const paths = this.projectManager.getProjectPaths(projectHash);
@@ -321,11 +391,11 @@ export class CleanupHandler {
       debug('failed to remove secrets for %s: %O', projectHash, error);
     }
 
-    // Remove session file if exists
+    // Remove session directory (replaces old fs.unlink(sessionFile))
     try {
-      await fs.unlink(paths.sessionFile);
+      await fs.rm(paths.sessionDir, { recursive: true, force: true });
     } catch {
-      // Expected: file may not exist
+      // Expected: directory may not exist
     }
   }
 }

package/src/core/flow-executor.ts

@@ -60,6 +60,7 @@ export class FlowExecutor {
 
   /**
    * Try to join an existing session. Returns summary if joined, null otherwise.
+   * Always re-applies settings for self-healing (fixes corrupted state from partial restores).
    */
   private async tryJoinExistingSession(
     projectPath: string,
@@ -67,31 +68,39 @@ export class FlowExecutor {
     target: string,
     verbose?: boolean
   ): Promise<{ joined: true } | null> {
-    const existingSession = await this.sessionManager.getActiveSession(projectHash);
-    if (!existingSession) {
+    // Check if there's an active session (backup.json exists)
+    const backupRef = await this.sessionManager.getBackupRef(projectHash);
+    if (!backupRef) {
       return null;
     }
 
-    const targetObj = resolveTargetOrId(target);
-    const agentsDir = path.join(projectPath, targetObj.config.agentDir);
-    const filesExist = existsSync(agentsDir) && (await fs.readdir(agentsDir)).length > 0;
-
-    if (filesExist) {
-      await this.sessionManager.startSession(
-        projectPath,
-        projectHash,
-        target,
-        existingSession.backupPath
-      );
-      this.cleanupHandler.registerCleanupHooks(projectHash);
-      return { joined: true };
+    if (verbose) {
+      console.log(chalk.dim('Joining existing session...'));
     }
 
-    if (verbose) {
-      console.log(chalk.dim('Session files missing, re-attaching...'));
+    // Register our PID with the session.
+    // Verify backupRef is still valid after acquiring — handles the TOCTOU race
+    // where cleanup could delete backup.json between getBackupRef() and acquireSession().
+    const result = await this.sessionManager.acquireSession(projectHash, projectPath, target);
+    if (!result.backupRef) {
+      // Session was cleaned up between our check and acquire — undo our PID registration
+      await this.sessionManager.releaseSession(projectHash);
+      return null;
     }
-    await this.sessionManager.endSession(projectHash);
-    return null;
+
+    this.cleanupHandler.registerCleanupHooks(projectHash);
+
+    // Always re-apply settings for self-healing
+    const targetObj = resolveTargetOrId(target);
+    if (targetObj.applySettings) {
+      try {
+        await targetObj.applySettings(projectPath, {});
+      } catch (error) {
+        debug('applySettings failed during join:', error);
+      }
+    }
+
+    return { joined: true };
   }
 
   /**
@@ -128,12 +137,12 @@ export class FlowExecutor {
             }),
     ]);
 
-    const { session } = await this.sessionManager.startSession(
-      projectPath,
+    // Acquire session with backup info — atomic first-session detection
+    const { backupRef } = await this.sessionManager.acquireSession(
       projectHash,
+      projectPath,
       target,
-      backup.backupPath,
-      backup.sessionId
+      { sessionId: backup.sessionId, backupPath: backup.backupPath }
     );
 
     this.cleanupHandler.registerCleanupHooks(projectHash);
@@ -142,8 +151,9 @@ export class FlowExecutor {
       await this.clearUserSettings(projectPath, target);
     }
 
+    const sessionId = backupRef?.sessionId ?? backup.sessionId;
     const templates = await this.templateLoader.loadTemplates(target);
-    const manifest = await this.backupManager.getManifest(projectHash, session.sessionId);
+    const manifest = await this.backupManager.getManifest(projectHash, sessionId);
 
     if (!manifest) {
       throw new Error('Backup manifest not found');
@@ -161,7 +171,7 @@ export class FlowExecutor {
       }
     }
 
-    await this.backupManager.updateManifest(projectHash, session.sessionId, manifest);
+    await this.backupManager.updateManifest(projectHash, sessionId, manifest);
 
     return {
       agents: attachResult.agentsAdded.length,

package/src/core/project-manager.ts

@@ -18,7 +18,9 @@ import { targetManager } from './target-manager.js';
 const execAsync = promisify(exec);
 
 export interface ProjectPaths {
-  sessionFile: string;
+  sessionDir: string; // ~/.sylphx-flow/sessions/<hash>/
+  backupRefFile: string; // ~/.sylphx-flow/sessions/<hash>/backup.json
+  pidsDir: string; // ~/.sylphx-flow/sessions/<hash>/pids/
   backupsDir: string;
   secretsDir: string;
   latestBackup: string;
@@ -45,12 +47,14 @@ export class ProjectManager {
    * Get all paths for a project
    */
   getProjectPaths(projectHash: string): ProjectPaths {
-    const sessionsDir = path.join(this.flowHomeDir, 'sessions');
+    const sessionDir = path.join(this.flowHomeDir, 'sessions', projectHash);
     const backupsDir = path.join(this.flowHomeDir, 'backups', projectHash);
     const secretsDir = path.join(this.flowHomeDir, 'secrets', projectHash);
 
     return {
-      sessionFile: path.join(sessionsDir, `${projectHash}.json`),
+      sessionDir,
+      backupRefFile: path.join(sessionDir, 'backup.json'),
+      pidsDir: path.join(sessionDir, 'pids'),
       backupsDir,
       secretsDir,
       latestBackup: path.join(backupsDir, 'latest'),
@@ -216,19 +220,19 @@ export class ProjectManager {
   /**
    * Get all active projects
    */
-  async getActiveProjects(): Promise<Array<{ hash: string; sessionFile: string }>> {
+  async getActiveProjects(): Promise<Array<{ hash: string; sessionDir: string }>> {
     const sessionsDir = path.join(this.flowHomeDir, 'sessions');
 
     if (!existsSync(sessionsDir)) {
       return [];
     }
 
-    const files = await fs.readdir(sessionsDir);
-    return files
-      .filter((file) => file.endsWith('.json'))
-      .map((file) => ({
-        hash: file.replace('.json', ''),
-        sessionFile: path.join(sessionsDir, file),
+    const entries = await fs.readdir(sessionsDir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory() && entry.name !== 'history')
+      .map((entry) => ({
+        hash: entry.name,
+        sessionDir: path.join(sessionsDir, entry.name),
       }));
   }
 
@@ -243,7 +247,8 @@ export class ProjectManager {
   } | null> {
     const paths = this.getProjectPaths(projectHash);
 
-    const hasActiveSession = existsSync(paths.sessionFile);
+    // Session is active if backup.json exists in the session directory
+    const hasActiveSession = existsSync(paths.backupRefFile);
 
     let backupsCount = 0;
     if (existsSync(paths.backupsDir)) {