@sylphx/flow 3.19.1 → 3.21.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @sylphx/flow
 
+## 3.21.0 (2026-02-08)
+
+Add SessionStart memory hook and use stdin for notifications
+
+### ✨ Features
+
+- **flow:** replace state-flag session management with PID-based ground truth ([692344d](https://github.com/SylphxAI/flow/commit/692344d7cd2b2b8c3b460347b3111ac5b08e375a))
+
+### 🐛 Bug Fixes
+
+- close three gaps found in challenge round 2 ([52bf789](https://github.com/SylphxAI/flow/commit/52bf789323a30d3a245375bdd4442a2532984823))
+
+### ♻️ Refactoring
+
+- extract restoreAndFinalize helper, improve cleanup safety ([959f255](https://github.com/SylphxAI/flow/commit/959f25507fb9db78191c7ed3e540319948e1288c))
+
+### 💅 Styles
+
+- format package.json with biome (tabs → spaces) ([8560a3f](https://github.com/SylphxAI/flow/commit/8560a3f7c5debf220bf6fd02da19276911e75886))
+
+## 3.20.0 (2026-02-08)
+
+### ✨ Features
+
+- **flow:** add SessionStart memory hook and use stdin for notifications ([6580500](https://github.com/SylphxAI/flow/commit/65805004f164a8f9a05d821e528c7412f7573e2f))
+
 ## 3.19.1 (2026-02-07)
 
 ### 🐛 Bug Fixes

package/assets/agents/builder.md

@@ -101,13 +101,22 @@ State-of-the-art industrial standard. Every time. Would you stake your reputatio
 
 ## Memory
 
+Two-layer durable memory:
+
+- **`MEMORY.md`** — Curated long-term memory. Decisions, preferences, durable facts.
+- **`memory/YYYY-MM-DD.md`** — Daily log (append-only). Running context, day-to-day notes.
+
+**Rules:**
+- If someone says "remember this," write it down immediately (do not keep it in RAM).
+- Decisions and preferences → `MEMORY.md`
+- Day-to-day notes and running context → `memory/YYYY-MM-DD.md`
+- SessionStart hook auto-loads MEMORY.md + today/yesterday daily logs.
+
 **Atomic commits.** Commit continuously. Each commit = one logical change. Semantic commit messages (feat, fix, docs, refactor, test, chore). This is your memory of what was done.
 
 **Todos.** Use TaskCreate/TaskUpdate to track what needs to be done. This is your memory of what to do.
 
-**CLAUDE.md** — Your persistent memory file. Commands, env setup, architecture decisions, patterns, gotchas. Read first. Summarize, don't append. Remove resolved. Consolidate duplicates.
-
-**Recovery:** Lost context? → `git log`. Forgot next steps? → TaskList.
+**Recovery:** Lost context? → `git log`. Forgot next steps? → TaskList. Need old memories? → read `memory/` directory.
 
 ## Issue Ownership
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "3.19.1",
+	"version": "3.21.0",
 	"description": "One CLI to rule them all. Unified orchestration layer for AI coding assistants. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {

package/src/commands/flow/execute-v2.ts

@@ -308,7 +308,25 @@ export async function executeFlowV2(
       continue: options.continue,
     };
 
-    await executeTargetCommand(selectedTargetId, systemPrompt, userPrompt, runOptions);
+    // Suppress SIGINT in parent — child process handles its own Ctrl+C.
+    // Without this, SIGINT propagates to parent and triggers premature cleanup
+    // while the child is still running.
+    const originalSigintListeners = process.listeners('SIGINT') as ((...args: unknown[]) => void)[];
+    process.removeAllListeners('SIGINT');
+    process.on('SIGINT', () => {
+      // Intentionally empty — child handles Ctrl+C
+    });
+
+    try {
+      await executeTargetCommand(selectedTargetId, systemPrompt, userPrompt, runOptions);
+    } finally {
+      // Restore original SIGINT listeners after child exits
+      process.removeAllListeners('SIGINT');
+      for (const listener of originalSigintListeners) {
+        process.on('SIGINT', listener);
+      }
+    }
+
     await executor.cleanup(projectPath);
   } catch (error) {
     if (error instanceof UserCancelledError) {

package/src/commands/hook-command.ts

@@ -1,27 +1,50 @@
 #!/usr/bin/env node
 /**
- * Hook command - OS notification for Claude Code startup
+ * Hook command - Claude Code hook handlers
  *
- * Purpose: Send OS-level notifications when Claude Code starts
+ * Purpose: Handle Claude Code lifecycle hooks:
+ * - notification: OS-level notification when Claude Code starts
+ * - session-start: Load durable memory (MEMORY.md + recent daily logs)
  *
  * DESIGN RATIONALE:
- * - Simple notification: Just notify user when Claude Code is ready
- * - Cross-platform: Supports macOS, Linux, and Windows
- * - Non-intrusive: Fails silently if notification system not available
+ * - Each hook type returns content to stdout (Claude Code injects as context)
+ * - Cross-platform notifications (macOS, Linux, Windows)
+ * - SessionStart hook loads cross-session memory at startup
  */
 
 import { exec } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
 import os from 'node:os';
+import path from 'node:path';
 import { promisify } from 'node:util';
 import { Command } from 'commander';
 import { cli } from '../utils/display/cli-output.js';
 
+/**
+ * Hook input from Claude Code via stdin.
+ * Claude Code sends JSON context about the event — we read what we need.
+ */
+interface HookInput {
+  /** Notification message text */
+  message?: string;
+  /** Notification title */
+  title?: string;
+  /** Notification type (permission_prompt, idle_prompt, etc.) */
+  notification_type?: string;
+  /** How the session started (startup, resume, clear, compact) */
+  source?: string;
+  /** Current working directory */
+  cwd?: string;
+}
+
 const execAsync = promisify(exec);
 
 /**
- * Hook types supported
+ * Hook types supported — single source of truth for both type and runtime validation
  */
-type HookType = 'notification';
+const VALID_HOOK_TYPES = ['notification', 'session-start'] as const;
+type HookType = (typeof VALID_HOOK_TYPES)[number];
+const VALID_HOOK_TYPE_SET = new Set<string>(VALID_HOOK_TYPES);
 
 /**
  * Target platforms supported
@@ -32,18 +55,20 @@ type TargetPlatform = 'claude-code';
  * Create the hook command
  */
 export const hookCommand = new Command('hook')
-  .description('Load dynamic system information for Claude Code hooks')
-  .requiredOption('--type <type>', 'Hook type (notification)')
+  .description('Handle Claude Code lifecycle hooks (notification, memory)')
+  .requiredOption('--type <type>', 'Hook type (notification | session-start)')
   .option('--target <target>', 'Target platform (claude-code)', 'claude-code')
   .option('--verbose', 'Show verbose output', false)
   .action(async (options) => {
     try {
-      const hookType = options.type as HookType;
+      const hookType = options.type as string;
       const target = options.target as TargetPlatform;
 
       // Validate hook type
-      if (hookType !== 'notification') {
-        throw new Error(`Invalid hook type: ${hookType}. Must be 'notification'`);
+      if (!VALID_HOOK_TYPE_SET.has(hookType)) {
+        throw new Error(
+          `Invalid hook type: ${hookType}. Must be one of: ${VALID_HOOK_TYPES.join(', ')}`
+        );
       }
 
       // Validate target
@@ -51,8 +76,11 @@ export const hookCommand = new Command('hook')
         throw new Error(`Invalid target: ${target}. Only 'claude-code' is currently supported`);
       }
 
+      // Read hook input from stdin (Claude Code passes JSON context)
+      const hookInput = await readStdinInput();
+
       // Load and display content based on hook type
-      const content = await loadHookContent(hookType, target, options.verbose);
+      const content = await loadHookContent(hookType as HookType, target, hookInput, options.verbose);
 
       // Output the content (no extra formatting, just the content)
       console.log(content);
@@ -72,27 +100,140 @@ export const hookCommand = new Command('hook')
     }
   });
 
+/**
+ * Read JSON input from stdin (non-blocking, returns empty object if no input)
+ * Claude Code sends event context as JSON on stdin for all hook types.
+ */
+async function readStdinInput(): Promise<HookInput> {
+  // stdin is not a TTY when piped from Claude Code
+  if (process.stdin.isTTY) {
+    return {};
+  }
+
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      if (!data.trim()) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(data) as HookInput);
+      } catch {
+        resolve({});
+      }
+    });
+    // Safety timeout — don't hang if stdin never closes
+    setTimeout(() => resolve({}), 1000);
+  });
+}
+
 /**
  * Load content for a specific hook type and target
  */
 async function loadHookContent(
   hookType: HookType,
   _target: TargetPlatform,
+  input: HookInput,
   verbose: boolean = false
 ): Promise<string> {
-  if (hookType === 'notification') {
-    return await sendNotification(verbose);
+  switch (hookType) {
+    case 'notification':
+      return await sendNotification(input, verbose);
+    case 'session-start':
+      return await loadSessionStartContent(verbose);
+  }
+}
+
+/**
+ * Read a file and return its contents, or empty string if not found
+ */
+async function readFileIfExists(filePath: string): Promise<string> {
+  try {
+    return await readFile(filePath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Format a date as YYYY-MM-DD
+ */
+function formatDate(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Load memory files for session start:
+ * - MEMORY.md (curated long-term memory)
+ * - memory/{today}.md (today's daily log)
+ * - memory/{yesterday}.md (yesterday's daily log)
+ *
+ * Returns concatenated content to stdout for Claude Code context injection
+ */
+async function loadSessionStartContent(verbose: boolean): Promise<string> {
+  const cwd = process.cwd();
+  const sections: string[] = [];
+
+  // Load MEMORY.md
+  const memoryPath = path.join(cwd, 'MEMORY.md');
+  const memoryContent = await readFileIfExists(memoryPath);
+  if (memoryContent.trim()) {
+    sections.push(`## MEMORY.md\n${memoryContent.trim()}`);
+    if (verbose) {
+      cli.info('Loaded MEMORY.md');
+    }
+  }
+
+  // Calculate today and yesterday dates
+  const today = new Date();
+  const yesterday = new Date(today);
+  yesterday.setDate(yesterday.getDate() - 1);
+
+  const todayStr = formatDate(today);
+  const yesterdayStr = formatDate(yesterday);
+
+  // Load today's daily log
+  const todayPath = path.join(cwd, 'memory', `${todayStr}.md`);
+  const todayContent = await readFileIfExists(todayPath);
+  if (todayContent.trim()) {
+    sections.push(`## memory/${todayStr}.md\n${todayContent.trim()}`);
+    if (verbose) {
+      cli.info(`Loaded memory/${todayStr}.md`);
+    }
+  }
+
+  // Load yesterday's daily log
+  const yesterdayPath = path.join(cwd, 'memory', `${yesterdayStr}.md`);
+  const yesterdayContent = await readFileIfExists(yesterdayPath);
+  if (yesterdayContent.trim()) {
+    sections.push(`## memory/${yesterdayStr}.md\n${yesterdayContent.trim()}`);
+    if (verbose) {
+      cli.info(`Loaded memory/${yesterdayStr}.md`);
+    }
+  }
+
+  if (verbose && sections.length === 0) {
+    cli.info('No memory files found');
   }
 
-  return '';
+  return sections.join('\n\n');
 }
 
 /**
- * Send OS-level notification
+ * Send OS-level notification using event data from Claude Code.
+ * Falls back to generic message when stdin input is missing.
  */
-async function sendNotification(verbose: boolean): Promise<string> {
-  const title = '🔮 Sylphx Flow';
-  const message = 'Claude Code is ready';
+async function sendNotification(input: HookInput, verbose: boolean): Promise<string> {
+  const title = input.title || '🔮 Sylphx Flow';
+  const message = input.message || 'Claude Code is ready';
   const platform = os.platform();
 
   if (verbose) {

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

@@ -1,7 +1,8 @@
 /**
  * Tests for CleanupHandler
- * Covers: signal cleanup, crash recovery, orphaned project detection,
- * periodic cleanup gating, and session history pruning coordination
+ * Covers: cleanup flow, crash recovery, orphaned project detection,
+ * periodic cleanup gating, finalize-after-restore ordering,
+ * and legacy migration
  */
 
 import fs from 'node:fs';
@@ -16,21 +17,26 @@ function createMockProjectManager(flowHome: string) {
   return {
     getFlowHomeDir: () => flowHome,
     getProjectPaths: (hash: string) => ({
-      sessionFile: path.join(flowHome, 'sessions', `${hash}.json`),
+      sessionDir: path.join(flowHome, 'sessions', hash),
+      backupRefFile: path.join(flowHome, 'sessions', hash, 'backup.json'),
+      pidsDir: path.join(flowHome, 'sessions', hash, 'pids'),
       backupsDir: path.join(flowHome, 'backups', hash),
       secretsDir: path.join(flowHome, 'secrets', hash),
       latestBackup: path.join(flowHome, 'backups', hash, 'latest'),
     }),
+    getActiveProjects: vi.fn().mockResolvedValue([]),
   };
 }
 
 function createMockSessionManager() {
   return {
     detectOrphanedSessions: vi.fn().mockResolvedValue(new Map()),
-    endSession: vi.fn().mockResolvedValue({ shouldRestore: false, session: null }),
-    recoverSession: vi.fn().mockResolvedValue(undefined),
-    getActiveSession: vi.fn().mockResolvedValue(null),
+    releaseSession: vi.fn().mockResolvedValue({ shouldRestore: false, backupRef: null }),
+    finalizeSessionCleanup: vi.fn().mockResolvedValue(undefined),
+    isSessionActive: vi.fn().mockResolvedValue(false),
     cleanupSessionHistory: vi.fn().mockResolvedValue(undefined),
+    getBackupRef: vi.fn().mockResolvedValue(null),
+    acquireSession: vi.fn().mockResolvedValue({ isFirstSession: false, backupRef: null }),
   };
 }
 
@@ -38,6 +44,7 @@ function createMockBackupManager() {
   return {
     restoreBackup: vi.fn().mockResolvedValue(undefined),
     cleanupOldBackups: vi.fn().mockResolvedValue(undefined),
+    cleanupOrphanedRestores: vi.fn().mockResolvedValue(undefined),
   };
 }
 
@@ -94,24 +101,74 @@ describe('CleanupHandler', () => {
   // --- cleanup() ---
 
   describe('cleanup()', () => {
-    it('should restore backup and clean up when last session ends', async () => {
-      const session = { sessionId: 'session-1', projectPath: '/tmp/project' };
-      mockSessionManager.endSession.mockResolvedValue({ shouldRestore: true, session });
+    it('should restore backup and finalize when last session ends', async () => {
+      const backupRef = {
+        sessionId: 'session-1',
+        projectPath: '/tmp/project',
+        backupPath: '/tmp/backup',
+        target: 'claude-code',
+      };
+      mockSessionManager.releaseSession.mockResolvedValue({ shouldRestore: true, backupRef });
 
       await handler.cleanup('abc123');
 
       expect(mockBackupManager.restoreBackup).toHaveBeenCalledWith('abc123', 'session-1');
+      // CRITICAL: finalize called AFTER restore
+      expect(mockSessionManager.finalizeSessionCleanup).toHaveBeenCalledWith('abc123');
       expect(mockBackupManager.cleanupOldBackups).toHaveBeenCalledWith('abc123', 3);
       expect(mockGitStash.popSettingsChanges).toHaveBeenCalledWith('/tmp/project');
       expect(mockSecrets.clearSecrets).toHaveBeenCalledWith('abc123');
     });
 
+    it('should call finalize AFTER restore (ordering)', async () => {
+      const callOrder: string[] = [];
+      mockSessionManager.releaseSession.mockResolvedValue({
+        shouldRestore: true,
+        backupRef: {
+          sessionId: 's1',
+          projectPath: '/tmp/p',
+          backupPath: '/tmp/b',
+          target: 'claude-code',
+        },
+      });
+      mockBackupManager.restoreBackup.mockImplementation(async () => {
+        callOrder.push('restore');
+      });
+      mockSessionManager.finalizeSessionCleanup.mockImplementation(async () => {
+        callOrder.push('finalize');
+      });
+
+      await handler.cleanup('abc123');
+
+      expect(callOrder).toEqual(['restore', 'finalize']);
+    });
+
+    it('should NOT call finalize if restore fails', async () => {
+      mockSessionManager.releaseSession.mockResolvedValue({
+        shouldRestore: true,
+        backupRef: {
+          sessionId: 's1',
+          projectPath: '/tmp/p',
+          backupPath: '/tmp/b',
+          target: 'claude-code',
+        },
+      });
+      mockBackupManager.restoreBackup.mockRejectedValue(new Error('restore failed'));
+
+      // cleanup() will throw since restoreBackup throws
+      await expect(handler.cleanup('abc123')).rejects.toThrow('restore failed');
+
+      // finalize should NOT have been called
+      expect(mockSessionManager.finalizeSessionCleanup).not.toHaveBeenCalled();
+    });
+
     it('should not restore when other sessions still active', async () => {
-      mockSessionManager.endSession.mockResolvedValue({ shouldRestore: false, session: null });
+      mockSessionManager.releaseSession.mockResolvedValue({ shouldRestore: false, backupRef: null });
 
       await handler.cleanup('abc123');
 
       expect(mockBackupManager.restoreBackup).not.toHaveBeenCalled();
+      expect(mockSessionManager.finalizeSessionCleanup).not.toHaveBeenCalled();
       expect(mockGitStash.popSettingsChanges).not.toHaveBeenCalled();
       expect(mockSecrets.clearSecrets).not.toHaveBeenCalled();
     });
@@ -120,30 +177,31 @@ describe('CleanupHandler', () => {
   // --- recoverOnStartup() ---
 
   describe('recoverOnStartup()', () => {
-    it('should recover orphaned sessions', async () => {
-      const session = {
+    it('should recover orphaned sessions with finalize after restore', async () => {
+      const backupRef = {
         sessionId: 'session-crashed',
         projectPath: '/tmp/crashed-project',
-        projectHash: 'hash1',
+        backupPath: '/tmp/backup',
+        target: 'claude-code',
       };
-      const orphaned = new Map([['hash1', session]]);
+      const orphaned = new Map([['hash1', backupRef]]);
       mockSessionManager.detectOrphanedSessions.mockResolvedValue(orphaned);
 
       await handler.recoverOnStartup();
 
       expect(mockBackupManager.restoreBackup).toHaveBeenCalledWith('hash1', 'session-crashed');
-      expect(mockSessionManager.recoverSession).toHaveBeenCalledWith('hash1', session);
+      expect(mockSessionManager.finalizeSessionCleanup).toHaveBeenCalledWith('hash1');
       expect(mockGitStash.popSettingsChanges).toHaveBeenCalledWith('/tmp/crashed-project');
       expect(mockSecrets.clearSecrets).toHaveBeenCalledWith('hash1');
       expect(mockBackupManager.cleanupOldBackups).toHaveBeenCalledWith('hash1', 3);
     });
 
     it('should handle multiple orphaned sessions independently', async () => {
-      const session1 = { sessionId: 's1', projectPath: '/p1' };
-      const session2 = { sessionId: 's2', projectPath: '/p2' };
+      const ref1 = { sessionId: 's1', projectPath: '/p1', backupPath: '/b1', target: 'claude-code' };
+      const ref2 = { sessionId: 's2', projectPath: '/p2', backupPath: '/b2', target: 'claude-code' };
       const orphaned = new Map([
-        ['h1', session1],
-        ['h2', session2],
+        ['h1', ref1],
+        ['h2', ref2],
       ]);
       mockSessionManager.detectOrphanedSessions.mockResolvedValue(orphaned);
 
@@ -156,7 +214,9 @@ describe('CleanupHandler', () => {
 
       // Second session should still be recovered despite first failure
       expect(mockBackupManager.restoreBackup).toHaveBeenCalledTimes(2);
-      expect(mockSessionManager.recoverSession).toHaveBeenCalledWith('h2', session2);
+      expect(mockSessionManager.finalizeSessionCleanup).toHaveBeenCalledWith('h2');
+      // First session's finalize should NOT have been called (restore failed)
+      expect(mockSessionManager.finalizeSessionCleanup).not.toHaveBeenCalledWith('h1');
     });
 
     it('should skip heavy cleanup when marker is fresh', async () => {
@@ -209,6 +269,76 @@ describe('CleanupHandler', () => {
     });
   });
 
+  // --- Legacy migration ---
+
+  describe('migrateLegacySessions (via recoverOnStartup)', () => {
+    it('should migrate legacy session files with cleanupRequired=true', async () => {
+      // Create a legacy session file
+      const legacySession = {
+        projectHash: 'abc123',
+        projectPath: '/tmp/project',
+        sessionId: 'session-legacy',
+        pid: 999999,
+        startTime: '2026-01-01T00:00:00.000Z',
+        backupPath: '/tmp/backups/session-legacy',
+        status: 'active',
+        target: 'claude-code',
+        cleanupRequired: true,
+        isOriginal: true,
+        sharedBackupId: 'session-legacy',
+        refCount: 1,
+        activePids: [999999],
+      };
+      fs.writeFileSync(
+        path.join(flowHome, 'sessions', 'abc123.json'),
+        JSON.stringify(legacySession)
+      );
+
+      // Fresh cleanup marker to skip heavy cleanup
+      fs.writeFileSync(path.join(flowHome, '.last-cleanup'), new Date().toISOString());
+
+      await handler.recoverOnStartup();
+
+      // Legacy file should be gone
+      expect(fs.existsSync(path.join(flowHome, 'sessions', 'abc123.json'))).toBe(false);
+
+      // New directory structure should exist with backup.json
+      const paths = mockProjectManager.getProjectPaths('abc123');
+      expect(fs.existsSync(paths.backupRefFile)).toBe(true);
+
+      const backupRef = JSON.parse(fs.readFileSync(paths.backupRefFile, 'utf-8'));
+      expect(backupRef.sessionId).toBe('session-legacy');
+      expect(backupRef.projectPath).toBe('/tmp/project');
+    });
+
+    it('should migrate legacy session files with cleanupRequired=false (no backup.json)', async () => {
+      const legacySession = {
+        sessionId: 'session-done',
+        backupPath: '/tmp/backup',
+        projectPath: '/tmp/project',
+        target: 'claude-code',
+        cleanupRequired: false,
+        pid: 999999,
+        startTime: '2026-01-01T00:00:00.000Z',
+      };
+      fs.writeFileSync(
+        path.join(flowHome, 'sessions', 'def456.json'),
+        JSON.stringify(legacySession)
+      );
+
+      fs.writeFileSync(path.join(flowHome, '.last-cleanup'), new Date().toISOString());
+
+      await handler.recoverOnStartup();
+
+      // Legacy file should be gone
+      expect(fs.existsSync(path.join(flowHome, 'sessions', 'def456.json'))).toBe(false);
+
+      // No backup.json should be created (cleanupRequired was false)
+      const paths = mockProjectManager.getProjectPaths('def456');
+      expect(fs.existsSync(paths.backupRefFile)).toBe(false);
+    });
+  });
+
   // --- Orphaned project cleanup ---
 
   describe('cleanupOrphanedProjects (via recoverOnStartup)', () => {
@@ -248,11 +378,8 @@ describe('CleanupHandler', () => {
       );
 
       // Mock: this project has an active session
-      mockSessionManager.getActiveSession.mockImplementation(async (hash: string) => {
-        if (hash === activeHash) {
-          return { projectHash: activeHash };
-        }
-        return null;
+      mockSessionManager.isSessionActive.mockImplementation(async (hash: string) => {
+        return hash === activeHash;
       });
 
       await handler.recoverOnStartup();