@sylphx/flow 3.24.1 → 3.25.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @sylphx/flow
 
+## 3.25.0 (2026-02-17)
+
+### ✨ Features
+
+- **flow:** smart --resume with auto-detection and sessions command ([ce6a3f8](https://github.com/SylphxAI/flow/commit/ce6a3f820c99fe47cb5c6701fc219bd599583470))
+
+### 🔧 Chores
+
+- fix biome formatting in settings.json and package.json ([02bd051](https://github.com/SylphxAI/flow/commit/02bd051b88d29b645786c8812610400960adbcfe))
+
+## 3.24.2 (2026-02-17)
+
+### 🐛 Bug Fixes
+
+- **flow:** graceful exit when Claude Code exits with non-zero code ([44892b5](https://github.com/SylphxAI/flow/commit/44892b51beda34b49020ed1d0324cfcc3e4b28f9))
+
 ## 3.24.1 (2026-02-15)
 
 ### 🐛 Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "3.24.1",
+	"version": "3.25.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

@@ -19,7 +19,7 @@ import { TargetInstaller } from '../../services/target-installer.js';
 import type { RunCommandOptions } from '../../types.js';
 import { extractAgentInstructions, loadAgentContent } from '../../utils/agent-enhancer.js';
 import { showAttachSummary, showHeader } from '../../utils/display/banner.js';
-import { CLIError, UserCancelledError } from '../../utils/errors.js';
+import { CLIError, ChildProcessExitError, UserCancelledError } from '../../utils/errors.js';
 import { log, promptConfirm, promptSelect } from '../../utils/prompts/index.js';
 import { ensureTargetInstalled, promptForTargetSelection } from '../../utils/target-selection.js';
 import { resolvePrompt } from './prompt.js';
@@ -340,6 +340,17 @@ export async function executeFlowV2(
       process.exit(0);
     }
 
+    // Child process already displayed its own error via inherited stdio —
+    // cleanup silently and exit with the same code.
+    if (error instanceof ChildProcessExitError) {
+      try {
+        await executor.cleanup(projectPath);
+      } catch (cleanupError) {
+        debug('cleanup after child exit failed:', cleanupError);
+      }
+      process.exit(error.exitCode);
+    }
+
     console.error(chalk.red('\n  Error:'), error);
 
     try {

package/src/commands/sessions-command.ts

@@ -0,0 +1,87 @@
+/**
+ * Sessions Command
+ *
+ * Lists Claude Code sessions for the current project so users can
+ * pick one to resume, instead of relying on Claude Code's unreliable picker.
+ */
+
+import chalk from 'chalk';
+import { Command } from 'commander';
+import { type SessionInfo, listProjectSessions } from '../targets/functional/claude-session.js';
+
+/**
+ * Format bytes into a human-readable size string.
+ */
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(0)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+/**
+ * Format a date into a relative time string.
+ */
+function formatRelativeTime(date: Date): string {
+  const now = Date.now();
+  const diffMs = now - date.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHour = Math.floor(diffMin / 60);
+  const diffDay = Math.floor(diffHour / 24);
+
+  if (diffSec < 60) return 'just now';
+  if (diffMin < 60) return `${diffMin} minute${diffMin === 1 ? '' : 's'} ago`;
+  if (diffHour < 24) return `${diffHour} hour${diffHour === 1 ? '' : 's'} ago`;
+  if (diffDay === 1) return 'yesterday';
+  if (diffDay < 7) return `${diffDay} days ago`;
+  if (diffDay < 30) return `${Math.floor(diffDay / 7)} week${Math.floor(diffDay / 7) === 1 ? '' : 's'} ago`;
+  return date.toLocaleDateString();
+}
+
+/**
+ * Format a session row for the table output.
+ */
+function formatSessionRow(session: SessionInfo, isLatest: boolean): string {
+  const id = chalk.white(session.id);
+  const time = formatRelativeTime(session.modifiedAt).padEnd(18);
+  const size = formatSize(session.sizeBytes).padStart(8);
+  const marker = isLatest ? chalk.green('  \u2190 latest') : '';
+
+  return `  ${id}  ${chalk.dim(time)}  ${chalk.dim(size)}${marker}`;
+}
+
+export const sessionsCommand = new Command('sessions')
+  .description('List Claude Code sessions for the current project')
+  .action(async () => {
+    const cwd = process.cwd();
+    const sessions = await listProjectSessions(cwd);
+
+    if (sessions.length === 0) {
+      console.log(chalk.yellow('\n  No sessions found for this project.\n'));
+      console.log(chalk.dim(`  Project: ${cwd}`));
+      console.log(chalk.dim('  Start a new session with: flow\n'));
+      return;
+    }
+
+    console.log(`\n${chalk.cyan.bold('  Sessions')} ${chalk.dim(`for ${cwd}`)}\n`);
+
+    // Header
+    console.log(
+      `  ${chalk.dim.bold('ID'.padEnd(36))}  ${chalk.dim.bold('Last active'.padEnd(18))}  ${chalk.dim.bold('Size'.padStart(8))}`
+    );
+    console.log(chalk.dim(`  ${'─'.repeat(36)}  ${'─'.repeat(18)}  ${'─'.repeat(8)}`));
+
+    // Rows
+    for (let i = 0; i < sessions.length; i++) {
+      console.log(formatSessionRow(sessions[i], i === 0));
+    }
+
+    // Footer hint
+    const latestId = sessions[0].id;
+    const shortId = latestId.slice(0, 8);
+    console.log('');
+    console.log(chalk.dim(`  Resume latest:  ${chalk.white(`flow --resume`)}`));
+    console.log(chalk.dim(`  Resume by ID:   ${chalk.white(`flow --resume ${shortId}`)}`));
+    console.log('');
+  });

package/src/index.ts

@@ -17,6 +17,7 @@ import {
   upgradeCommand,
 } from './commands/flow-command.js';
 import { hookCommand } from './commands/hook-command.js';
+import { sessionsCommand } from './commands/sessions-command.js';
 import { settingsCommand } from './commands/settings-command.js';
 import { UserCancelledError } from './utils/errors.js';
 
@@ -73,6 +74,7 @@ export function createCLI(): Command {
   program.addCommand(doctorCommand);
   program.addCommand(upgradeCommand);
   program.addCommand(hookCommand);
+  program.addCommand(sessionsCommand);
   program.addCommand(settingsCommand);
 
   return program;

package/src/targets/claude-code.ts

@@ -11,9 +11,10 @@ import {
   pathUtils,
   yamlUtils,
 } from '../utils/config/target-utils.js';
-import { CLIError } from '../utils/errors.js';
+import { CLIError, ChildProcessExitError } from '../utils/errors.js';
 import { sanitize } from '../utils/security/security.js';
 import { DEFAULT_CLAUDE_CODE_ENV } from './functional/claude-code-logic.js';
+import { findLastSessionId } from './functional/claude-session.js';
 import {
   detectTargetConfig,
   stripFrontMatter,
@@ -32,11 +33,6 @@ interface ClaudeCodeAgentMetadata {
   model?: string;
 }
 
-/** Error with exit code from child process */
-interface ProcessExitError extends Error {
-  code: number | null;
-}
-
 /** Type guard for Node.js errors with errno/code properties */
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
   return error instanceof Error && 'code' in error;
@@ -211,6 +207,24 @@ export const claudeCodeTarget: Target = {
 
 Please begin your response with a comprehensive summary of all the instructions and context provided above.`;
 
+    // Resolve session ID for --resume (auto-detect or passthrough)
+    let resolvedResumeId: string | undefined;
+    if (options.resume) {
+      if (typeof options.resume === 'string') {
+        resolvedResumeId = options.resume;
+      } else {
+        // Auto-resolve: find last session for current project
+        const lastSession = await findLastSessionId(process.cwd());
+        if (lastSession) {
+          resolvedResumeId = lastSession;
+          if (options.verbose) {
+            console.log(chalk.dim(`  Resolved session: ${resolvedResumeId}`));
+          }
+        }
+        // If null, fall through to bare --resume (Claude's own picker as fallback)
+      }
+    }
+
     if (options.dryRun) {
       // Build the command for display
       const dryRunArgs = ['claude', '--dangerously-skip-permissions'];
@@ -222,8 +236,8 @@ Please begin your response with a comprehensive summary of all the instructions
       }
       if (options.resume) {
         dryRunArgs.push('--resume');
-        if (typeof options.resume === 'string') {
-          dryRunArgs.push(options.resume);
+        if (resolvedResumeId) {
+          dryRunArgs.push(resolvedResumeId);
         }
       }
       dryRunArgs.push('--system-prompt', '"<agent content>"');
@@ -255,8 +269,8 @@ Please begin your response with a comprehensive summary of all the instructions
       }
       if (options.resume) {
         args.push('--resume');
-        if (typeof options.resume === 'string') {
-          args.push(options.resume);
+        if (resolvedResumeId) {
+          args.push(resolvedResumeId);
         }
       }
 
@@ -299,9 +313,9 @@ Please begin your response with a comprehensive summary of all the instructions
           if (code === 0) {
             resolve();
           } else {
-            const error = new Error(`Claude Code exited with code ${code}`) as ProcessExitError;
-            error.code = code;
-            reject(error);
+            // Child already displayed its error via inherited stdio — use
+            // ChildProcessExitError so upstream handlers exit silently.
+            reject(new ChildProcessExitError(code ?? 1));
           }
         });
 
@@ -313,13 +327,15 @@ Please begin your response with a comprehensive summary of all the instructions
         });
       });
     } catch (error: unknown) {
+      // ChildProcessExitError means the child already printed its own error —
+      // let it propagate unmodified so upstream can exit silently.
+      if (error instanceof ChildProcessExitError) {
+        throw error;
+      }
       if (isNodeError(error)) {
         if (error.code === 'ENOENT') {
           throw new CLIError('Claude Code not found. Please install it first.', 'CLAUDE_NOT_FOUND');
         }
-        if (error.code !== undefined) {
-          throw new CLIError(`Claude Code exited with code ${error.code}`, 'CLAUDE_ERROR');
-        }
         throw new CLIError(`Failed to execute Claude Code: ${error.message}`, 'CLAUDE_ERROR');
       }
       if (error instanceof Error) {

package/src/targets/functional/claude-session.ts

@@ -0,0 +1,155 @@
+/**
+ * Claude Code Session Resolver
+ *
+ * Resolves session IDs from Claude Code's data files, bypassing the
+ * built-in session picker which is unreliable with large project directories.
+ *
+ * Data model:
+ * - ~/.claude/projects/{encoded-path}/ — session .jsonl files (filename = session ID)
+ * - ~/.claude/history.jsonl — global log with {timestamp, project, sessionId} per user message
+ * - Snapshot-only files have type: "file-history-snapshot" and are tiny (<5KB)
+ * - Real sessions have type: "user" messages and are much larger
+ */
+
+import fs from 'node:fs/promises';
+import { open } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Minimum file size in bytes to consider a session file "real" (not just a snapshot) */
+const MIN_SESSION_SIZE_BYTES = 2048;
+
+/** Number of bytes to read from the tail of history.jsonl */
+const HISTORY_TAIL_BYTES = 65_536;
+
+/** Session info returned by listProjectSessions */
+export interface SessionInfo {
+  id: string;
+  modifiedAt: Date;
+  sizeBytes: number;
+}
+
+/**
+ * Encode a project path the same way Claude Code does.
+ * /Users/kyle/flow → -Users-kyle-flow
+ */
+function encodeProjectPath(projectPath: string): string {
+  return projectPath.replace(/\//g, '-');
+}
+
+/**
+ * Get the Claude Code home directory.
+ */
+function getClaudeHome(): string {
+  return path.join(os.homedir(), '.claude');
+}
+
+/**
+ * Find the most recent session ID for a project by reading the tail of history.jsonl.
+ *
+ * Reads only the last ~64KB of the file (not the full 20MB+ file) for performance.
+ * Returns null if no sessions found for the given project path.
+ */
+export async function findLastSessionId(projectPath: string): Promise<string | null> {
+  const historyPath = path.join(getClaudeHome(), 'history.jsonl');
+
+  let fd: Awaited<ReturnType<typeof open>> | null = null;
+  try {
+    fd = await open(historyPath, 'r');
+    const stat = await fd.stat();
+
+    if (stat.size === 0) {
+      return null;
+    }
+
+    // Read the tail of the file
+    const readSize = Math.min(HISTORY_TAIL_BYTES, stat.size);
+    const offset = stat.size - readSize;
+    const buffer = Buffer.alloc(readSize);
+    await fd.read(buffer, 0, readSize, offset);
+
+    const content = buffer.toString('utf-8');
+    const lines = content.split('\n').filter(Boolean);
+
+    // Walk backwards through lines to find the last session for this project
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i];
+
+      // Skip partial lines at the start of the buffer (if we started mid-line)
+      if (i === 0 && offset > 0) {
+        // First line in buffer may be truncated — skip it
+        continue;
+      }
+
+      try {
+        const entry = JSON.parse(line);
+        if (entry.sessionId && entry.project === projectPath) {
+          return entry.sessionId;
+        }
+      } catch {
+        // Skip malformed lines
+        continue;
+      }
+    }
+
+    return null;
+  } catch (error) {
+    // File doesn't exist or can't be read — no sessions
+    if (isNodeError(error) && error.code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  } finally {
+    await fd?.close();
+  }
+}
+
+/**
+ * List all real sessions for a project from the project directory.
+ *
+ * Reads ~/.claude/projects/{encoded-path}/, stats each .jsonl file,
+ * filters out snapshot-only files (< 2KB), returns sorted by mtime descending.
+ */
+export async function listProjectSessions(projectPath: string): Promise<SessionInfo[]> {
+  const encoded = encodeProjectPath(projectPath);
+  const projectDir = path.join(getClaudeHome(), 'projects', encoded);
+
+  let entries: Awaited<ReturnType<typeof fs.readdir>>;
+  try {
+    entries = await fs.readdir(projectDir);
+  } catch (error) {
+    if (isNodeError(error) && error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+
+  const jsonlFiles = entries.filter((f) => f.endsWith('.jsonl'));
+
+  // Stat all files in parallel
+  const statResults = await Promise.all(
+    jsonlFiles.map(async (filename) => {
+      const filePath = path.join(projectDir, filename);
+      try {
+        const stat = await fs.stat(filePath);
+        return {
+          id: filename.replace(/\.jsonl$/, ''),
+          modifiedAt: stat.mtime,
+          sizeBytes: stat.size,
+        };
+      } catch {
+        // File may have been deleted between readdir and stat
+        return null;
+      }
+    })
+  );
+
+  return statResults
+    .filter((s): s is SessionInfo => s !== null && s.sizeBytes >= MIN_SESSION_SIZE_BYTES)
+    .sort((a, b) => b.modifiedAt.getTime() - a.modifiedAt.getTime());
+}
+
+/** Type guard for Node.js errors with errno/code properties */
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error;
+}

package/src/utils/errors.ts

@@ -20,3 +20,15 @@ export class CLIError extends Error {
     this.name = 'CLIError';
   }
 }
+
+/**
+ * Child process exited with non-zero code.
+ * Since stdio is inherited, the child already displayed its own error —
+ * upstream handlers should cleanup and exit silently without printing anything.
+ */
+export class ChildProcessExitError extends Error {
+  constructor(public exitCode: number) {
+    super(`Child process exited with code ${exitCode}`);
+    this.name = 'ChildProcessExitError';
+  }
+}