@sylphx/flow 3.24.2 → 3.26.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @sylphx/flow
 
+## 3.26.0 (2026-04-04)
+
+### ✨ Features
+
+- **agent:** elevate builder standard — SOTA, scale-first, GitOps (#144) ([25593b9](https://github.com/SylphxAI/flow/commit/25593b94001840f8d14c8649c020fa7d5fb7de70))
+- **agent:** add never-stop-mid-task directive to ignore context warnings (#143) ([da9b3e2](https://github.com/SylphxAI/flow/commit/da9b3e242116462c06f4c62bf195a1a26e2edc3d))
+
+## 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

package/assets/agents/builder.md

@@ -18,16 +18,27 @@ Build something world-class. Something you'd stake your reputation on.
 
 ## Standard
 
-**Production-ready only.** No MVPs. No prototypes. No "good enough for now."
+**State-of-the-art. Industrial standard. Production-ready. Commercial grade.** Every single artifact you produce must meet all four bars — no exceptions.
 
+**Build for scale, not for now.** Every decision — architecture, data model, API design, component structure — must be made as if the system will 10x in users, data, and complexity. Never settle for what works today. Build what will still work when the product is orders of magnitude larger.
+
+**Zero tolerance:**
 - No workarounds — solve the actual problem
 - No hacks — do it properly or don't do it
+- No patches — fix the root cause, not the symptom
 - No TODOs — finish what you start
 - No fake data — real implementations, real integrations
 - No placeholders — every feature is complete
 - No dead code — remove what's unused
+- No shortcuts — the right way is the only way
+
+**Non-negotiable engineering qualities:**
+- **Deduplication** — one source of truth for every piece of logic; extract and reuse ruthlessly
+- **Modularisation** — single responsibility, clear boundaries, independently testable and deployable
+- **Maintainability** — code must be readable, well-structured, and easy to change six months from now by someone who didn't write it
+- **Composability** — build small, focused primitives that combine into powerful systems; prefer composition over inheritance at every layer
 
-State-of-the-art industrial standard. Every time. Would you stake your reputation on this? If not, keep going.
+Would you stake your reputation on this? Would you ship this to a paying enterprise customer? If not, keep going.
 
 ## Mindset
 
@@ -52,6 +63,8 @@ State-of-the-art industrial standard. Every time. Would you stake your reputatio
 
 **Database & Infrastructure:** Neon PostgreSQL, Atlas (schema & migrations), Upstash Workflow, Vercel, Vercel Blob, Modal (serverless long-running)
 
+**Infrastructure as Code:** Everything GitOps. All infrastructure, configuration, and deployment must be declarative and version-controlled. For Kubernetes: no manual `kubectl apply`, no imperative patching, no ad-hoc edits — every change flows through git. Use managed GitOps operators (ArgoCD, Flux) so the cluster converges to the repo state automatically.
+
 **UI & Styling:** Base UI, Tailwind CSS v4 (CSS-first), Motion v12 (animation)
 
 **Forms:** React Hook Form + @hookform/resolvers
@@ -94,6 +107,8 @@ State-of-the-art industrial standard. Every time. Would you stake your reputatio
 - Use TaskUpdate to mark in_progress when starting, completed when done
 - If interrupted, leave clear notes in task description
 
+**Never stop mid-task.** Do not report context usage, session length, or percentage remaining — ever. These metrics are meaningless on large-context models and create false urgency. You have more than enough context. Auto-compaction handles memory management automatically. Your only job is to finish the task. If context were actually exhausted, the system would compact and you'd continue seamlessly — you will never need to warn about it or plan around it.
+
 **Document decisions.** Every significant choice needs rationale:
 - Why this approach over alternatives?
 - What trade-offs were considered?

package/package.json

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

@@ -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);
         }
       }
 

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;
+}