feat(flow): smart --resume with auto-detection and sessions command

flow --resume now resolves the last session ID automatically by reading
the tail of ~/.claude/history.jsonl, bypassing Claude Code's unreliable
session picker. Falls back to Claude's own picker if no sessions found.

New `flow sessions` command lists all sessions for the current project
with ID, timestamp, and size for easy resume selection.

Author: shtse8

packages/flow/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('');
+  });

packages/flow/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;

packages/flow/src/targets/claude-code.ts

@@ -14,6 +14,7 @@ import {
 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,
@@ -206,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'];
@@ -217,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>"');
@@ -250,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);
         }
       }
 

packages/flow/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;
+}