@synergenius/flow-weaver-pack-weaver 0.9.0 → 0.9.3

package/src/bot/bot-manager.ts

@@ -0,0 +1,293 @@
+/**
+ * Bot Manager — spawns and manages multiple weaver bot sessions
+ * as separate processes. Each bot has its own queue, steering file,
+ * and output log under ~/.weaver/bots/{name}/.
+ */
+
+import { spawn, execFileSync, type ChildProcess } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { TaskQueue } from './task-queue.js';
+import { SteeringController } from './steering.js';
+
+export interface ManagedBot {
+  name: string;
+  pid: number;
+  projectDir: string;
+  botDir: string;
+  startedAt: number;
+  status: 'running' | 'paused' | 'stopped';
+}
+
+export interface SpawnOpts {
+  projectDir: string;
+  parallel?: number;
+  deadline?: string;
+  autoApprove?: boolean;
+  /** Git branch for commits (creates if needed). Keeps main clean for overnight runs. */
+  branch?: string;
+}
+
+const BOTS_DIR = path.join(os.homedir(), '.weaver', 'bots');
+
+export class BotManager {
+  private bots = new Map<string, { meta: ManagedBot; process: ChildProcess }>();
+
+  constructor() {
+    // Ensure base dir exists
+    fs.mkdirSync(BOTS_DIR, { recursive: true });
+
+    // Clean up on process exit
+    const cleanup = () => this.cleanup();
+    process.on('exit', cleanup);
+    process.on('SIGTERM', cleanup);
+  }
+
+  spawn(name: string, opts: SpawnOpts): ManagedBot {
+    if (this.bots.has(name)) {
+      throw new Error(`Bot "${name}" already exists. Stop it first or use a different name.`);
+    }
+
+    const botDir = path.join(BOTS_DIR, name);
+    fs.mkdirSync(botDir, { recursive: true });
+
+    // Create git branch if specified (keeps main clean for overnight runs)
+    if (opts.branch) {
+      try {
+        execFileSync('git', ['checkout', '-B', opts.branch], { cwd: opts.projectDir, encoding: 'utf-8', stdio: 'pipe' });
+      } catch { /* branch may already exist */ }
+    }
+
+    const logPath = path.join(botDir, 'output.log');
+    // Touch the file synchronously so it exists immediately after spawn() returns
+    fs.writeFileSync(logPath, '', { flag: 'a' });
+    const logStream = fs.createWriteStream(logPath, { flags: 'a' });
+
+    const sessionArgs = [
+      'flow-weaver', 'weaver', 'session',
+      '--continuous',
+      '--project-dir', opts.projectDir,
+    ];
+    if (opts.autoApprove !== false) sessionArgs.push('--auto-approve');
+    if (opts.parallel && opts.parallel > 1) sessionArgs.push('--parallel', String(opts.parallel));
+    if (opts.deadline) sessionArgs.push('--until', opts.deadline);
+
+    // Prevent system sleep during long runs (cross-platform)
+    const { cmd, args } = wrapWithSleepInhibitor('npx', sessionArgs);
+
+    // Set queue/steering to bot-specific paths
+    const env = {
+      ...process.env,
+      WEAVER_QUEUE_DIR: botDir,
+      WEAVER_STEERING_DIR: botDir,
+    };
+
+    const child = spawn(cmd, args, {
+      cwd: opts.projectDir,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: false,
+    });
+
+    // Capture output to log file
+    child.stdout?.pipe(logStream);
+    child.stderr?.pipe(logStream);
+
+    const meta: ManagedBot = {
+      name,
+      pid: child.pid ?? 0,
+      projectDir: opts.projectDir,
+      botDir,
+      startedAt: Date.now(),
+      status: 'running',
+    };
+
+    // Write metadata for persistence
+    fs.writeFileSync(path.join(botDir, 'meta.json'), JSON.stringify(meta, null, 2));
+
+    child.on('exit', (code) => {
+      const bot = this.bots.get(name);
+      if (bot) {
+        bot.meta.status = 'stopped';
+        fs.writeFileSync(path.join(botDir, 'meta.json'), JSON.stringify(bot.meta, null, 2));
+      }
+      logStream.write(`\n[bot-manager] Process exited with code ${code}\n`);
+      logStream.end();
+    });
+
+    this.bots.set(name, { meta, process: child });
+    return meta;
+  }
+
+  list(): ManagedBot[] {
+    this.discoverExistingBots();
+    // Health check: update status of bots that died
+    for (const [, bot] of this.bots) {
+      if (bot.meta.status === 'running' && !this.isAlive(bot.meta)) {
+        bot.meta.status = 'stopped';
+        try {
+          fs.writeFileSync(path.join(bot.meta.botDir, 'meta.json'), JSON.stringify(bot.meta, null, 2));
+        } catch { /* non-fatal */ }
+      }
+    }
+    return [...this.bots.values()].map(b => b.meta);
+  }
+
+  get(name: string): ManagedBot | null {
+    const bot = this.bots.get(name);
+    if (!bot) return null;
+    // Health check on access
+    if (bot.meta.status === 'running' && !this.isAlive(bot.meta)) {
+      bot.meta.status = 'stopped';
+      try {
+        fs.writeFileSync(path.join(bot.meta.botDir, 'meta.json'), JSON.stringify(bot.meta, null, 2));
+      } catch { /* non-fatal */ }
+    }
+    return bot.meta;
+  }
+
+  /** Check if a bot process is still alive. */
+  private isAlive(bot: ManagedBot): boolean {
+    if (!bot.pid || bot.pid === 0) return false;
+    try { process.kill(bot.pid, 0); return true; } catch { return false; }
+  }
+
+  getQueue(name: string): TaskQueue {
+    const bot = this.bots.get(name);
+    if (!bot) throw new Error(`Bot "${name}" not found.`);
+    return new TaskQueue(bot.meta.botDir);
+  }
+
+  getSteering(name: string): SteeringController {
+    const bot = this.bots.get(name);
+    if (!bot) throw new Error(`Bot "${name}" not found.`);
+    return new SteeringController(bot.meta.botDir);
+  }
+
+  async steer(name: string, command: 'pause' | 'resume' | 'cancel'): Promise<void> {
+    const steering = this.getSteering(name);
+    await steering.write({ command, timestamp: Date.now() });
+    if (command === 'pause') {
+      const bot = this.bots.get(name);
+      if (bot) bot.meta.status = 'paused';
+    } else if (command === 'resume') {
+      const bot = this.bots.get(name);
+      if (bot) bot.meta.status = 'running';
+    }
+  }
+
+  stop(name: string): void {
+    const bot = this.bots.get(name);
+    if (!bot) throw new Error(`Bot "${name}" not found.`);
+    // Send SIGTERM for graceful shutdown
+    if (bot.process.pid && !bot.process.killed) {
+      bot.process.kill('SIGTERM');
+    }
+    bot.meta.status = 'stopped';
+  }
+
+  kill(name: string): void {
+    const bot = this.bots.get(name);
+    if (!bot) throw new Error(`Bot "${name}" not found.`);
+    if (bot.process.pid && !bot.process.killed) {
+      bot.process.kill('SIGKILL');
+    }
+    bot.meta.status = 'stopped';
+  }
+
+  logs(name: string, lines = 50): string {
+    const bot = this.bots.get(name);
+    if (!bot) throw new Error(`Bot "${name}" not found.`);
+    const logPath = path.join(bot.meta.botDir, 'output.log');
+    if (!fs.existsSync(logPath)) return '(no logs yet)';
+    const content = fs.readFileSync(logPath, 'utf-8');
+    const allLines = content.split('\n');
+    return allLines.slice(-lines).join('\n');
+  }
+
+  cleanup(): void {
+    for (const [, bot] of this.bots) {
+      if (bot.process.pid && !bot.process.killed) {
+        try { bot.process.kill('SIGTERM'); } catch (err) {
+          if (process.env.WEAVER_VERBOSE) process.stderr.write(`[weaver] SIGTERM failed for bot: ${err}\n`);
+        }
+      }
+    }
+  }
+
+  /** Discover bots from disk that were spawned by a previous assistant session. */
+  private discoverExistingBots(): void {
+    if (!fs.existsSync(BOTS_DIR)) return;
+    for (const name of fs.readdirSync(BOTS_DIR)) {
+      if (this.bots.has(name)) continue;
+      const metaPath = path.join(BOTS_DIR, name, 'meta.json');
+      if (!fs.existsSync(metaPath)) continue;
+      try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8')) as ManagedBot;
+        // Check if process is still running
+        if (meta.pid > 0) {
+          try {
+            process.kill(meta.pid, 0); // test if process exists
+            meta.status = 'running';
+          } catch {
+            meta.status = 'stopped';
+          }
+        }
+        // Store without a process handle (can only steer via file, not kill directly)
+        this.bots.set(name, { meta, process: null as unknown as ChildProcess });
+      } catch { /* corrupt meta */ }
+    }
+  }
+}
+
+/**
+ * Cross-platform sleep inhibitor. Wraps a command to prevent the OS from sleeping.
+ * - macOS: caffeinate -i -s
+ * - Linux: systemd-inhibit (if available)
+ * - Windows/other: no wrapper (runs command directly)
+ */
+function wrapWithSleepInhibitor(command: string, args: string[]): { cmd: string; args: string[] } {
+  switch (process.platform) {
+    case 'darwin':
+      return { cmd: 'caffeinate', args: ['-i', '-s', command, ...args] };
+    case 'linux': {
+      // Check if systemd-inhibit is available
+      try {
+        execFileSync('which', ['systemd-inhibit'], { stdio: 'pipe' });
+        return {
+          cmd: 'systemd-inhibit',
+          args: ['--what=idle:sleep', '--who=weaver', '--why=Bot session running', command, ...args],
+        };
+      } catch {
+        return { cmd: command, args };
+      }
+    }
+    default:
+      return { cmd: command, args };
+  }
+}
+
+/**
+ * Cross-platform desktop notification.
+ * - macOS: osascript
+ * - Linux: notify-send (if available)
+ * - Windows: PowerShell toast (if available)
+ */
+export function sendDesktopNotification(title: string, message: string): void {
+  try {
+    switch (process.platform) {
+      case 'darwin':
+        execFileSync('osascript', ['-e', `display notification "${message}" with title "${title}"`], { stdio: 'ignore' });
+        break;
+      case 'linux':
+        execFileSync('notify-send', [title, message], { stdio: 'ignore' });
+        break;
+      case 'win32':
+        execFileSync('powershell', ['-Command', `[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('${message}','${title}')`], { stdio: 'ignore' });
+        break;
+    }
+  } catch {
+    // Non-fatal — notification is best-effort
+  }
+}

package/src/bot/child-process-tracker.ts

@@ -0,0 +1,40 @@
+import type { ChildProcess } from 'node:child_process';
+
+/**
+ * Tracks spawned child processes and kills them on SIGINT/SIGTERM.
+ * Prevents zombie `claude` processes when user hits Ctrl+C.
+ */
+
+const activeChildren = new Set<ChildProcess>();
+let signalHandlersInstalled = false;
+
+function installSignalHandlers(): void {
+  if (signalHandlersInstalled) return;
+  signalHandlersInstalled = true;
+
+  const cleanup = () => {
+    for (const child of activeChildren) {
+      try {
+        child.kill('SIGTERM');
+      } catch { /* already dead */ }
+    }
+    activeChildren.clear();
+  };
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+  process.on('exit', cleanup);
+}
+
+/** Register a child process for cleanup on signal. */
+export function trackChild(child: ChildProcess): void {
+  installSignalHandlers();
+  activeChildren.add(child);
+  child.on('exit', () => activeChildren.delete(child));
+  child.on('error', () => activeChildren.delete(child));
+}
+
+/** Get the count of active tracked children. */
+export function activeChildCount(): number {
+  return activeChildren.size;
+}

package/src/bot/cli-provider.ts

@@ -2,6 +2,7 @@ import { execSync, spawn } from 'node:child_process';
 import type { BotAgentProvider, OnUsageCallback, StreamChunk, ToolDefinition, ToolUseResult } from './types.js';
 import { buildSystemPrompt } from './system-prompt.js';
 import { parseStreamLine, extractTextFromChunks } from './cli-stream-parser.js';
+import { trackChild } from './child-process-tracker.js';
 
 // Strip CLAUDECODE from child env so nested claude CLI invocations work.
 const childEnv = { ...process.env };
@@ -29,20 +30,20 @@ export class CliAgentProvider implements BotAgentProvider {
         ? request.context
         : JSON.stringify(request.context, null, 2);
 
-    const fullPrompt = `${systemPrompt}\n\nContext:\n${contextStr}\n\nInstructions:\n${request.prompt}`;
+    const userPrompt = `Context:\n${contextStr}\n\nInstructions:\n${request.prompt}`;
 
     if (this.cli === 'claude-cli') {
       const chunks: StreamChunk[] = [];
-      for await (const chunk of this.streamRaw(fullPrompt)) {
+      for await (const chunk of this.streamRaw(userPrompt, systemPrompt)) {
         chunks.push(chunk);
       }
       const raw = extractTextFromChunks(chunks);
       return this.parseJson(raw);
     }
 
-    // copilot-cli: no stream-json support, keep execSync
+    // copilot-cli: no --system-prompt support, keep concatenated
     const raw = execSync('copilot -p --silent --allow-all-tools', {
-      input: fullPrompt,
+      input: systemPrompt + '\n\n' + userPrompt,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
       timeout: 120_000,
@@ -64,10 +65,10 @@ export class CliAgentProvider implements BotAgentProvider {
         ? request.context
         : JSON.stringify(request.context, null, 2);
 
-    const fullPrompt = `${systemPrompt}\n\nContext:\n${contextStr}\n\nInstructions:\n${request.prompt}`;
+    const userPrompt = `Context:\n${contextStr}\n\nInstructions:\n${request.prompt}`;
 
     if (this.cli === 'claude-cli') {
-      yield* this.streamRaw(fullPrompt);
+      yield* this.streamRaw(userPrompt, systemPrompt);
     } else {
       const result = await this.decide(request);
       yield { type: 'text', text: JSON.stringify(result) };
@@ -85,18 +86,22 @@ export class CliAgentProvider implements BotAgentProvider {
     return { result };
   }
 
-  private async *streamRaw(fullPrompt: string): AsyncGenerator<StreamChunk> {
+  private async *streamRaw(userPrompt: string, systemPrompt?: string): AsyncGenerator<StreamChunk> {
     const args = ['-p', '--output-format', 'stream-json', '--include-partial-messages'];
     if (this.model) {
       args.push('--model', this.model);
     }
+    if (systemPrompt) {
+      args.push('--system-prompt', systemPrompt);
+    }
 
     const child = spawn('claude', args, {
       stdio: ['pipe', 'pipe', 'pipe'],
       env: childEnv,
     });
+    trackChild(child);
 
-    child.stdin.write(fullPrompt);
+    child.stdin.write(userPrompt);
     child.stdin.end();
 
     const timeout = setTimeout(() => {

package/src/bot/conversation-store.ts

@@ -0,0 +1,222 @@
+/**
+ * Conversation Store — persistent conversation history for the assistant.
+ * Mirrors the platform's aiConversations/aiChatMessages tables
+ * using file-based storage for CLI use.
+ *
+ * Layout:
+ *   ~/.weaver/conversations/
+ *     index.json                  # ConversationRecord[]
+ *     {id}/messages.ndjson        # StoredMessage[] (append-only)
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+import type { AgentMessage } from '@synergenius/flow-weaver/agent';
+import { withFileLock } from './file-lock.js';
+
+export interface ConversationRecord {
+  id: string;
+  title: string;
+  projectDir: string;
+  messageCount: number;
+  totalTokens: number;
+  createdAt: number;
+  lastMessageAt: number;
+  botIds: string[];
+}
+
+interface StoredMessage {
+  role: 'user' | 'assistant' | 'tool';
+  content: string;
+  toolCalls?: Array<{ id: string; name: string; arguments: Record<string, unknown> }>;
+  toolCallId?: string;
+  timestamp: number;
+  tokens?: number;
+}
+
+const MAX_INDEX_SIZE = 20;
+const CHARS_PER_TOKEN = 4;
+
+export class ConversationStore {
+  private baseDir: string;
+  private indexPath: string;
+
+  constructor(baseDir?: string) {
+    this.baseDir = baseDir ?? path.join(os.homedir(), '.weaver', 'conversations');
+    this.indexPath = path.join(this.baseDir, 'index.json');
+    fs.mkdirSync(this.baseDir, { recursive: true });
+  }
+
+  create(projectDir: string): ConversationRecord {
+    const id = crypto.randomUUID().slice(0, 8);
+    const now = Date.now();
+    const record: ConversationRecord = {
+      id,
+      title: '',
+      projectDir,
+      messageCount: 0,
+      totalTokens: 0,
+      createdAt: now,
+      lastMessageAt: now,
+      botIds: [],
+    };
+
+    // Create conversation directory
+    const convDir = path.join(this.baseDir, id);
+    fs.mkdirSync(convDir, { recursive: true });
+
+    // Add to index (sync write — no lock needed for create, index is new or we're the only writer)
+    const index = this.readIndex();
+    index.unshift(record);
+    this.writeIndexUnsafe(index);
+
+    return record;
+  }
+
+  list(): ConversationRecord[] {
+    return this.readIndex();
+  }
+
+  get(id: string): ConversationRecord | null {
+    const index = this.readIndex();
+    return index.find(c => c.id === id) ?? null;
+  }
+
+  getMostRecent(): ConversationRecord | null {
+    const index = this.readIndex();
+    return index.length > 0 ? index[0] : null;
+  }
+
+  delete(id: string): void {
+    // Remove from index (sync — delete doesn't need lock)
+    const index = this.readIndex();
+    const filtered = index.filter(c => c.id !== id);
+    this.writeIndexUnsafe(filtered);
+
+    // Remove files
+    const convDir = path.join(this.baseDir, id);
+    if (fs.existsSync(convDir)) {
+      fs.rmSync(convDir, { recursive: true, force: true });
+    }
+  }
+
+  loadMessages(id: string): AgentMessage[] {
+    const msgPath = path.join(this.baseDir, id, 'messages.ndjson');
+    if (!fs.existsSync(msgPath)) return [];
+
+    const content = fs.readFileSync(msgPath, 'utf-8');
+    const messages: AgentMessage[] = [];
+
+    for (const line of content.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const stored = JSON.parse(line) as StoredMessage;
+        const msg: AgentMessage = {
+          role: stored.role,
+          content: stored.content,
+        };
+        if (stored.toolCalls) msg.toolCalls = stored.toolCalls;
+        if (stored.toolCallId) msg.toolCallId = stored.toolCallId;
+        messages.push(msg);
+      } catch {
+        // Skip corrupt lines
+      }
+    }
+
+    return messages;
+  }
+
+  appendMessages(id: string, messages: AgentMessage[]): void {
+    if (messages.length === 0) return;
+
+    const convDir = path.join(this.baseDir, id);
+    fs.mkdirSync(convDir, { recursive: true });
+    const msgPath = path.join(convDir, 'messages.ndjson');
+
+    const lines = messages.map(m => {
+      const stored: StoredMessage = {
+        role: m.role,
+        content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+        timestamp: Date.now(),
+        tokens: Math.ceil((typeof m.content === 'string' ? m.content.length : JSON.stringify(m.content).length) / CHARS_PER_TOKEN),
+      };
+      if (m.toolCalls) stored.toolCalls = m.toolCalls;
+      if (m.toolCallId) stored.toolCallId = m.toolCallId;
+      return JSON.stringify(stored);
+    });
+
+    fs.appendFileSync(msgPath, lines.join('\n') + '\n');
+  }
+
+  async updateAfterTurn(id: string, newMessages: AgentMessage[], tokensUsed: number): Promise<void> {
+    await withFileLock(this.indexPath, () => {
+      const index = this.readIndex();
+      const record = index.find(c => c.id === id);
+      if (!record) return;
+
+      record.messageCount += newMessages.length;
+      record.totalTokens += tokensUsed;
+      record.lastMessageAt = Date.now();
+
+      // Move to front (most recent)
+      const idx = index.indexOf(record);
+      if (idx > 0) {
+        index.splice(idx, 1);
+        index.unshift(record);
+      }
+
+      // Cap index size
+      if (index.length > MAX_INDEX_SIZE) {
+        index.splice(MAX_INDEX_SIZE);
+      }
+
+      this.writeIndexUnsafe(index);
+    });
+  }
+
+  async setTitle(id: string, title: string): Promise<void> {
+    await withFileLock(this.indexPath, () => {
+      const index = this.readIndex();
+      const record = index.find(c => c.id === id);
+      if (record) {
+        record.title = title.slice(0, 80).replace(/\n/g, ' ').trim();
+        this.writeIndexUnsafe(index);
+      }
+    });
+  }
+
+  async addBotId(id: string, botId: string): Promise<void> {
+    await withFileLock(this.indexPath, () => {
+      const index = this.readIndex();
+      const record = index.find(c => c.id === id);
+      if (record && !record.botIds.includes(botId)) {
+        record.botIds.push(botId);
+        this.writeIndexUnsafe(index);
+      }
+    });
+  }
+
+  // --- Private ---
+
+  private readIndex(): ConversationRecord[] {
+    if (!fs.existsSync(this.indexPath)) return [];
+    try {
+      return JSON.parse(fs.readFileSync(this.indexPath, 'utf-8'));
+    } catch (err) {
+      if (process.env.WEAVER_VERBOSE) process.stderr.write(`[weaver] conversation index parse failed: ${err}\n`);
+      return [];
+    }
+  }
+
+  private async writeIndex(index: ConversationRecord[]): Promise<void> {
+    await withFileLock(this.indexPath, () => {
+      this.writeIndexUnsafe(index);
+    });
+  }
+
+  private writeIndexUnsafe(index: ConversationRecord[]): void {
+    fs.writeFileSync(this.indexPath, JSON.stringify(index, null, 2));
+  }
+}

package/src/bot/error-guide.ts

@@ -0,0 +1,34 @@
+/**
+ * Actionable error guidance — maps cryptic error messages
+ * to human-readable explanations with fix suggestions.
+ */
+
+const GUIDES: Array<{ pattern: RegExp; guidance: string }> = [
+  { pattern: /ETIMEDOUT/i, guidance: 'Network timeout. Check internet connection or increase timeout with --timeout.' },
+  { pattern: /ECONNRESET/i, guidance: 'Connection reset. The server closed the connection. Retry in a few seconds.' },
+  { pattern: /ECONNREFUSED/i, guidance: 'Connection refused. Is the service running? Check the provider URL.' },
+  { pattern: /401|authentication|invalid.*key/i, guidance: 'Authentication failed. Check ANTHROPIC_API_KEY or run "weaver init" to reconfigure.' },
+  { pattern: /403|forbidden/i, guidance: 'Access denied. Your API key may not have permission for this model.' },
+  { pattern: /429|rate.?limit|too many requests/i, guidance: 'Rate limited. Wait a few minutes or reduce --parallel.' },
+  { pattern: /502|bad gateway/i, guidance: 'Server error (502). The API is temporarily unavailable. Will auto-retry.' },
+  { pattern: /503|service unavailable|overloaded/i, guidance: 'Service overloaded. Will auto-retry with backoff.' },
+  { pattern: /exit code 143/i, guidance: 'Process was killed (SIGTERM). Likely our timeout or Ctrl+C.' },
+  { pattern: /exit code 137/i, guidance: 'Process was killed (OOM or SIGKILL). System may be low on memory.' },
+  { pattern: /ENOMEM/i, guidance: 'Out of memory. Close other applications or increase available RAM.' },
+  { pattern: /ENOSPC/i, guidance: 'Disk full. Free up disk space.' },
+  { pattern: /lock.*retries|failed to acquire.*lock/i, guidance: 'File lock contention. Another weaver process may be running. Check with "ps aux | grep weaver".' },
+  { pattern: /not a workflow|No @flowWeaver/i, guidance: 'File is not a Flow Weaver workflow. Ensure it has @flowWeaver annotations.' },
+  { pattern: /parse.*json|unexpected token/i, guidance: 'JSON parse error. The AI may have returned malformed output. Retry the task.' },
+  { pattern: /Queue full/i, guidance: 'Too many pending tasks (200 max). Process or clear existing tasks first.' },
+];
+
+/**
+ * Get actionable guidance for an error message.
+ * Returns null if no guidance is available.
+ */
+export function getErrorGuidance(msg: string): string | null {
+  for (const { pattern, guidance } of GUIDES) {
+    if (pattern.test(msg)) return guidance;
+  }
+  return null;
+}