dont-hallucinate 0.1.3

package/src/parser.js

@@ -0,0 +1,123 @@
+// parser.js — error classification (port of parser.py)
+
+const FLAG_RE = /(?<![\w-])(--[a-zA-Z0-9][\w-]*|-[a-zA-Z0-9])(?![\w-])/g;
+
+export class ParsedFailure {
+  constructor({ errorType, hallucinatedFlag = null, missingCommand = null, rawError = '' }) {
+    this.errorType = errorType;
+    this.hallucinatedFlag = hallucinatedFlag;
+    this.missingCommand = missingCommand;
+    this.rawError = rawError;
+  }
+}
+
+export function commandName(command) {
+  const parts = command.trim().split(/\s+/);
+  return parts[0] || '';
+}
+
+export function extractCmdName(commandText) {
+  const known = ['git', 'npm', 'npx', 'pnpm', 'yarn', 'pip', 'pip3', 'rm', 'docker', 'kubectl', 'python', 'python3'];
+  for (const tool of known) {
+    if (new RegExp(`\\b${tool}\\b`).test(commandText)) return tool;
+  }
+  const skip = new Set(['bash', 'sh', 'zsh', 'fish', 'hallucinate', 'exec', '-c', '-lc', '--']);
+  for (const word of commandText.split(/\s+/)) {
+    if (!skip.has(word) && !word.startsWith('-')) return word;
+  }
+  return '';
+}
+
+export function extractHallucinatedFlag(stderrText) {
+  const patterns = [
+    /(?:unrecognized|unknown|unsupported|illegal)\s+(?:option|flag)\s+['"]?(--?[A-Za-z0-9][\w-]*)/i,
+    /no such option:\s*(--?[A-Za-z0-9][\w-]*)/i,
+    /invalid option\s*--\s*['"]?([A-Za-z0-9])/i,
+  ];
+  for (const pattern of patterns) {
+    const match = stderrText.match(pattern);
+    if (match) {
+      const token = match[1];
+      if (token && token.length === 1) return `-${token}`;
+      return token;
+    }
+  }
+  const allFlags = [...stderrText.matchAll(FLAG_RE)].map(m => m[1]);
+  return allFlags[0] ?? null;
+}
+
+export function extractMissingCommand(stderrText, commandText) {
+  const match = stderrText.match(/^\s*([^\s:]+):\s+command not found\b/im);
+  if (match) return match[1];
+  const first = commandName(commandText);
+  return first || null;
+}
+
+export function classifyFailure(command, stderrText, exitCode) {
+  const stderr = stderrText || '';
+  const stderrLow = stderr.toLowerCase();
+
+  if (exitCode === 0) return new ParsedFailure({ errorType: 'ok', rawError: stderr });
+
+  if (stderrLow.includes('permission denied'))
+    return new ParsedFailure({ errorType: 'permission_denied', rawError: stderr });
+
+  if (stderrLow.includes('no space left on device'))
+    return new ParsedFailure({ errorType: 'no_space', rawError: stderr });
+
+  if (stderrLow.includes('eaddrinuse') || stderrLow.includes('address already in use'))
+    return new ParsedFailure({ errorType: 'port_in_use', rawError: stderr });
+
+  const networkPatterns = [
+    'could not resolve host', 'connection refused', 'econnrefused',
+    'network is unreachable', 'no route to host', 'ssl error',
+    'certificate verify failed', 'name or service not known',
+  ];
+  if (networkPatterns.some(p => stderrLow.includes(p)))
+    return new ParsedFailure({ errorType: 'network_error', rawError: stderr });
+
+  const dirtyPatterns = [
+    'please commit your changes', 'you have unstaged changes',
+    'your local changes to the following', 'cannot pull with rebase',
+    'would be overwritten by merge',
+  ];
+  if (dirtyPatterns.some(p => stderrLow.includes(p)))
+    return new ParsedFailure({ errorType: 'git_dirty', rawError: stderr });
+
+  if (stderrLow.includes('conflict') && ['automatic merge failed', 'merge conflict', 'fix conflicts'].some(p => stderrLow.includes(p)))
+    return new ParsedFailure({ errorType: 'git_conflict', rawError: stderr });
+
+  // Hallucinated flag — must come before git_branch_missing
+  const hallucinatedFlag = extractHallucinatedFlag(stderr);
+  const flagTokens = ['unrecognized option', 'unknown option', 'unknown flag', 'invalid option', 'no such option', 'illegal option', 'unsupported option', 'unsupported flag'];
+  if (hallucinatedFlag && flagTokens.some(t => stderrLow.includes(t)))
+    return new ParsedFailure({ errorType: 'invalid_flag', hallucinatedFlag, rawError: stderr });
+
+  const branchPatterns = ['not something we can merge', 'did not match any file', 'unknown revision or path', 'no such branch', 'pathspec', 'not a valid object name'];
+  if (branchPatterns.some(p => stderrLow.includes(p)))
+    return new ParsedFailure({ errorType: 'git_branch_missing', rawError: stderr });
+
+  if (stderrLow.includes('missing script:') || stderrLow.includes('npm error missing script'))
+    return new ParsedFailure({ errorType: 'npm_missing_script', rawError: stderr });
+
+  const notFoundPatterns = [
+    'command not found',
+    'not recognized as an internal or external command',
+    '\u4e0d\u662f\u5185\u90e8\u6216\u5916\u90e8\u547d\u4ee4',
+    '\u4e0d\u662f\u5916\u90e8\u6216\u5185\u90e8\u547d\u4ee4',
+    '\ucc3e\uc744 \uc218 \uc5c6\uc2b5\ub2c8\ub2e4',
+    "n'est pas reconnu",
+    'no se reconoce',
+  ];
+  if (exitCode === 127 || notFoundPatterns.some(p => stderrLow.includes(p)))
+    return new ParsedFailure({ errorType: 'missing_package', missingCommand: extractMissingCommand(stderr, command), rawError: stderr });
+
+  if (stderrLow.includes('no such file or directory'))
+    return new ParsedFailure({ errorType: 'file_not_found', rawError: stderr });
+
+  const syntaxPatterns = ['syntax error near unexpected', 'unexpected token', 'syntax error:', 'parse error'];
+  if (syntaxPatterns.some(p => stderrLow.includes(p)))
+    return new ParsedFailure({ errorType: 'syntax_error', rawError: stderr });
+
+  return new ParsedFailure({ errorType: 'generic_error', rawError: stderr });
+}

package/src/runtime.js

@@ -0,0 +1,47 @@
+// runtime.js — workspace paths and JSONL utilities (port of runtime.py)
+
+import { mkdirSync, appendFileSync } from 'fs';
+import { resolve, join, sep, dirname } from 'path';
+
+export const RUNTIME_DIRNAME = '.hallucinate';
+export const STREAM_FILENAME = 'stream.jsonl';
+
+export function workspaceRoot(path = null) {
+  return resolve(path ?? process.cwd());
+}
+
+export function runtimeDir(path = null) {
+  return join(workspaceRoot(path), RUNTIME_DIRNAME);
+}
+
+export function defaultStreamFile(path = null) {
+  return join(runtimeDir(path), STREAM_FILENAME);
+}
+
+export function ensureRuntimeDir(path = null) {
+  const dir = runtimeDir(path);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function isWithinWorkspace(candidate, root) {
+  if (root == null) return true;
+  if (!candidate) return false;
+  try {
+    const candidatePath = resolve(candidate);
+    const workspace = workspaceRoot(root);
+    return candidatePath === workspace || candidatePath.startsWith(workspace + sep);
+  } catch {
+    return false;
+  }
+}
+
+export function appendJsonl(filePath, payload) {
+  const dir = dirname(filePath);
+  if (dir) mkdirSync(dir, { recursive: true });
+  appendFileSync(filePath, JSON.stringify(payload) + '\n', 'utf8');
+}
+
+export function utcTimestamp() {
+  return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+}

package/src/ui.js

@@ -0,0 +1,240 @@
+// ui.js — terminal UI (port of ui.py, using chalk instead of Rich)
+
+import chalk from 'chalk';
+import { isWithinWorkspace } from './runtime.js';
+import { detectAgent, loadSnarkMap, pickRoast } from './burn.js';
+import { tailJsonl, toFailureReport } from './watcher.js';
+
+const ACCENT = chalk.hex('#FF8C00');       // orange
+const ACCENT_DIM = chalk.hex('#FF6600');
+const MUTED = chalk.gray;
+const BOLD_WHITE = chalk.bold.white;
+
+const LABELS = {
+  invalid_flag:       'hallucinated flag',
+  missing_package:    'phantom package',
+  permission_denied:  'permission denied',
+  git_branch_missing: 'ghost branch',
+  git_dirty:          'dirty working tree',
+  git_conflict:       'merge conflict',
+  npm_missing_script: 'missing npm script',
+  file_not_found:     'file not found',
+  port_in_use:        'port in use',
+  syntax_error:       'syntax error',
+  network_error:      'network failure',
+  no_space:           'disk full',
+  generic_error:      'shell failure',
+};
+
+const DONT_ART = [
+  '██████╗  ██████╗ ███╗  ██╗████████╗',
+  '██╔══██╗██╔═══██╗████╗ ██║╚══██╔══╝',
+  '██║  ██║██║   ██║██╔██╗██║   ██║   ',
+  '██║  ██║██║   ██║██║╚████║   ██║   ',
+  '██████╔╝╚██████╔╝██║ ╚███║   ██║   ',
+  '╚═════╝  ╚═════╝ ╚═╝  ╚══╝   ╚═╝   ',
+];
+const HALL_ART = [
+  '██╗  ██╗ █████╗ ██╗     ██╗     ██╗   ██╗ ██████╗██╗███╗  ██╗ █████╗ ████████╗███████╗',
+  '██║  ██║██╔══██╗██║     ██║     ██║   ██║██╔════╝██║████╗ ██║██╔══██╗╚══██╔══╝██╔════╝',
+  '███████║███████║██║     ██║     ██║   ██║██║     ██║██╔██╗██║███████║   ██║   █████╗  ',
+  '██╔══██║██╔══██║██║     ██║     ██║   ██║██║     ██║██║╚████║██╔══██║   ██║   ██╔══╝  ',
+  '██║  ██║██║  ██║███████╗███████╗╚██████╔╝╚██████╗██║██║ ╚███║██║  ██║   ██║   ███████╗',
+  '╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚══════╝ ╚═════╝  ╚═════╝╚═╝╚═╝  ╚══╝╚═╝  ╚═╝   ╚═╝   ╚══════╝',
+];
+
+function banner() {
+  return [
+    ...DONT_ART.map(l => ACCENT.bold(l)),
+    ...HALL_ART.map(l => chalk.bold.white(l)),
+  ].join('\n');
+}
+
+function box(title, content, { borderColor = MUTED, width = null } = {}) {
+  const lines = content.split('\n');
+  const innerWidth = width ?? Math.max(...lines.map(l => stripAnsi(l).length), title ? stripAnsi(title).length + 2 : 0, 40);
+  const top = borderColor('┌─ ' + (title ? title + ' ' : '') + '─'.repeat(Math.max(0, innerWidth - (title ? stripAnsi(title).length + 3 : 1))) + '┐');
+  const mid = lines.map(l => borderColor('│') + ' ' + l + ' '.repeat(Math.max(0, innerWidth - stripAnsi(l).length - 1)) + borderColor('│'));
+  const bot = borderColor('└' + '─'.repeat(innerWidth + 1) + '┘');
+  return [top, ...mid, bot].join('\n');
+}
+
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1B\[[0-9;]*m/g, '');
+}
+
+function rule(char = '─', color = MUTED) {
+  const width = Math.min(process.stdout.columns || 80, 90);
+  return color(char.repeat(width));
+}
+
+function padRight(str, len) {
+  const visible = stripAnsi(str).length;
+  return str + ' '.repeat(Math.max(0, len - visible));
+}
+
+function stripWrapper(command) {
+  let m = command.match(/bash\s+-[lc]+\s+'(.*)'$/s);
+  if (m) return m[1];
+  m = command.match(/bash\s+-[lc]+\s+"(.*)"$/s);
+  if (m) return m[1];
+  return command;
+}
+
+function renderIdleScreen(agent) {
+  return [
+    '',
+    banner(),
+    '',
+    rule(),
+    '',
+    MUTED('  watching for shell failures'),
+    MUTED(`  agent: ${agent}`),
+    '',
+  ].join('\n');
+}
+
+function renderMainScreen(state) {
+  const { latestReport, latestRoast, totalCaught, logs } = state;
+  const { event, parsed, verification } = latestReport;
+  const cmd = stripWrapper(event.command);
+  const label = LABELS[parsed.errorType] || parsed.errorType;
+
+  const titleBar = [
+    ACCENT.bold(`  dont-hallucinate`),
+    MUTED(`  ${totalCaught} caught`),
+  ].join('');
+
+  const header = [
+    ACCENT.bold(`  ${label.toUpperCase()}`),
+    MUTED(`  exit ${event.exitCode}`),
+    MUTED(`  ${event.actor || 'unknown'}`),
+  ].join('');
+
+  const cmdBox = box(MUTED('command'), cmd, { borderColor: MUTED });
+
+  const fixLines = [];
+  if (parsed.hallucinatedFlag) {
+    fixLines.push(MUTED('  bad flag  ') + BOLD_WHITE(parsed.hallucinatedFlag));
+  }
+  if (verification.correctedCommand) {
+    fixLines.push(MUTED('  try       ') + BOLD_WHITE(verification.correctedCommand));
+  } else if (verification.suggestedFlag) {
+    fixLines.push(MUTED('  try flag  ') + BOLD_WHITE(verification.suggestedFlag));
+  }
+
+  const roastBox = box('', ACCENT.italic(`"${latestRoast}"`), { borderColor: ACCENT_DIM });
+
+  // History table
+  const tblHeader = [
+    MUTED(padRight('time', 10)),
+    MUTED(padRight('type', 22)),
+    MUTED(padRight('command', 40)),
+    MUTED('exit'),
+  ].join('  ');
+
+  const tblRows = logs.map(r => {
+    const ts = r.event.ts.length > 18 ? r.event.ts.slice(11, 19) : r.event.ts;
+    const c = stripWrapper(r.event.command).slice(0, 38);
+    const errLabel = LABELS[r.parsed.errorType] || r.parsed.errorType;
+    const isLatest = r === latestReport;
+    const style = isLatest ? ACCENT.bold : MUTED;
+    return [
+      MUTED(padRight(ts, 10)),
+      style(padRight(errLabel, 22)),
+      style(padRight(c, 40)),
+      style(String(r.event.exitCode)),
+    ].join('  ');
+  });
+
+  return [
+    '',
+    rule('═', ACCENT),
+    titleBar,
+    rule('═', ACCENT),
+    '',
+    header,
+    '',
+    cmdBox,
+    ...(fixLines.length ? ['', ...fixLines] : []),
+    '',
+    roastBox,
+    '',
+    rule(),
+    '',
+    tblHeader,
+    rule('─'),
+    ...tblRows,
+    '',
+  ].join('\n');
+}
+
+async function bootSplash(agent) {
+  const steps = [
+    ['initialising runtime', 300],
+    ['loading snark database', 400],
+    ['detecting agent', 300],
+    [`agent identified: ${agent}`, 500],
+    ['arming interceptors', 400],
+    ['watching', 300],
+  ];
+
+  process.stdout.write('\n');
+  process.stdout.write(banner() + '\n\n');
+
+  for (const [label, delay] of steps) {
+    process.stdout.write(`  ${ACCENT_DIM('>')} ${ACCENT(label)}\n`);
+    await sleep(delay);
+  }
+
+  process.stdout.write('\n');
+  process.stdout.write(MUTED('  ready — intercepting shell failures') + '\n');
+  await sleep(500);
+  process.stdout.write('\n');
+}
+
+export async function runUi({ streamFile, pollInterval = 200, fromStart = false, workspace = null } = {}) {
+  const agent = detectAgent();
+  const snark = loadSnarkMap();
+
+  await bootSplash(agent);
+
+  const state = {
+    logs: [],
+    latestReport: null,
+    latestRoast: '',
+    totalCaught: 0,
+    agent,
+  };
+
+  function render() {
+    // Clear terminal and redraw
+    process.stdout.write('\x1B[2J\x1B[H');
+    if (state.latestReport === null) {
+      process.stdout.write(renderIdleScreen(agent));
+    } else {
+      process.stdout.write(renderMainScreen(state));
+    }
+  }
+
+  render();
+
+  for await (const event of tailJsonl(streamFile, { pollInterval, fromStart })) {
+    if (event.exitCode === 0) continue;
+    if (workspace && !isWithinWorkspace(event.cwd, workspace)) continue;
+
+    const report = toFailureReport(event);
+    state.latestReport = report;
+    state.totalCaught += 1;
+    state.latestRoast = pickRoast(snark, report.parsed.errorType, { agent });
+    state.logs.push(report);
+    if (state.logs.length > 8) state.logs.shift();
+
+    render();
+  }
+}
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}

package/src/verifier.js

@@ -0,0 +1,156 @@
+// verifier.js — flag verification and fuzzy suggestion (port of verifier.py)
+
+import { spawnSync } from 'child_process';
+
+const FLAG_RE = /(?<![\w-])(--[a-zA-Z0-9][a-zA-Z0-9-]*|-[a-zA-Z0-9])(?![\w-])/g;
+
+export class VerificationResult {
+  constructor({ availableFlags, suggestedFlag, correctedCommand, source }) {
+    this.availableFlags = availableFlags;
+    this.suggestedFlag = suggestedFlag;
+    this.correctedCommand = correctedCommand;
+    this.source = source;
+  }
+}
+
+export function parseFlagsFromText(text) {
+  const flags = new Set([...text.matchAll(FLAG_RE)].map(m => m[1]));
+  return [...flags].sort();
+}
+
+function runHelpCommand(commandName) {
+  const candidates = [
+    { args: [commandName, '--help'], source: 'help' },
+    { args: [commandName, '-h'], source: 'help' },
+  ];
+  for (const { args, source } of candidates) {
+    try {
+      const result = spawnSync(args[0], args.slice(1), {
+        encoding: 'utf8',
+        timeout: 2000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      const output = [result.stdout, result.stderr].filter(Boolean).join('\n');
+      if (output.trim()) return { output, source };
+    } catch {
+      // continue
+    }
+  }
+  return { output: '', source: 'none' };
+}
+
+// Approximate Python's fuzz.ratio (LCS-based similarity ratio, 0–100)
+function fuzzyRatio(a, b) {
+  if (!a && !b) return 100;
+  if (!a || !b) return 0;
+  const la = a.length, lb = b.length;
+  const dp = Array.from({ length: la + 1 }, () => new Array(lb + 1).fill(0));
+  for (let i = 1; i <= la; i++) {
+    for (let j = 1; j <= lb; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1] + 1
+        : Math.max(dp[i - 1][j], dp[i][j - 1]);
+    }
+  }
+  return Math.round(200 * dp[la][lb] / (la + lb));
+}
+
+export function suggestFlag(hallucinatedFlag, availableFlags) {
+  if (!hallucinatedFlag || !availableFlags.length) return null;
+
+  const isLong = hallucinatedFlag.startsWith('--');
+  const candidates = isLong
+    ? availableFlags.filter(f => f.startsWith('--'))
+    : availableFlags.filter(f => f.startsWith('-') && !f.startsWith('--'));
+
+  if (!candidates.length) return null;
+
+  const normalizedBad = hallucinatedFlag.replace(/^-+/, '');
+
+  function scoreCandidate(candidate) {
+    const nc = candidate.replace(/^-+/, '');
+    let score = fuzzyRatio(normalizedBad, nc);
+    if (isLong) {
+      if (!nc || nc[0] !== normalizedBad[0]) return -1;
+      if (normalizedBad.length > 2 && nc.length > 2 && nc.slice(0, 2) === normalizedBad.slice(0, 2)) {
+        score += 10;
+      }
+    }
+    return score;
+  }
+
+  let best = null, bestScore = -1;
+  for (const candidate of candidates) {
+    const s = scoreCandidate(candidate);
+    if (s > bestScore) { bestScore = s; best = candidate; }
+  }
+
+  const threshold = isLong ? 85 : 70;
+  return bestScore >= threshold ? best : null;
+}
+
+export function correctedCommand(command, badFlag, goodFlag) {
+  if (!badFlag || !goodFlag) return null;
+  const parts = shellSplit(command);
+  if (parts === null) {
+    return command.includes(badFlag) ? command.replace(badFlag, goodFlag) : null;
+  }
+  const idx = parts.indexOf(badFlag);
+  if (idx === -1) return null;
+  parts[idx] = goodFlag;
+  return parts.map(shellQuote).join(' ');
+}
+
+export function verifyCommand(command, badFlag) {
+  const cmdName = command.trim().split(/\s+/)[0] || '';
+  if (!cmdName || cmdName === '.' || cmdName === 'source') {
+    return new VerificationResult({ availableFlags: [], suggestedFlag: null, correctedCommand: null, source: 'none' });
+  }
+
+  const { output, source } = runHelpCommand(cmdName);
+  const flags = parseFlagsFromText(output);
+  if (!badFlag) {
+    return new VerificationResult({ availableFlags: flags, suggestedFlag: null, correctedCommand: null, source });
+  }
+
+  const suggestion = suggestFlag(badFlag, flags);
+  const fixed = suggestion ? correctedCommand(command, badFlag, suggestion) : null;
+  return new VerificationResult({ availableFlags: flags, suggestedFlag: suggestion, correctedCommand: fixed, source });
+}
+
+// ── Shell tokenizer/quoter helpers ──────────────────────────────────────────
+
+function shellSplit(cmd) {
+  const tokens = [];
+  let current = '';
+  let inSingle = false, inDouble = false;
+  for (let i = 0; i < cmd.length; i++) {
+    const c = cmd[i];
+    if (inSingle) {
+      if (c === "'") inSingle = false;
+      else current += c;
+    } else if (inDouble) {
+      if (c === '"') inDouble = false;
+      else if (c === '\\' && i + 1 < cmd.length) current += cmd[++i];
+      else current += c;
+    } else if (c === "'") {
+      inSingle = true;
+    } else if (c === '"') {
+      inDouble = true;
+    } else if (c === '\\' && i + 1 < cmd.length) {
+      current += cmd[++i];
+    } else if (/\s/.test(c)) {
+      if (current) { tokens.push(current); current = ''; }
+    } else {
+      current += c;
+    }
+  }
+  if (inSingle || inDouble) return null; // unbalanced quotes
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function shellQuote(s) {
+  if (/^[a-zA-Z0-9._\-/=:@%+,]+$/.test(s)) return s;
+  return "'" + s.replace(/'/g, "'\"'\"'") + "'";
+}

package/src/watcher.js

@@ -0,0 +1,123 @@
+// watcher.js — JSONL stream tail + failure report builder (port of watcher.py)
+
+import { openSync, readSync, statSync, closeSync, mkdirSync, writeFileSync, existsSync } from 'fs';
+import { dirname } from 'path';
+import { classifyFailure } from './parser.js';
+import { verifyCommand, VerificationResult } from './verifier.js';
+
+export class StreamEvent {
+  constructor({ ts, exitCode, command, stderr, shell = '', actor = '', cwd = '', workspaceRoot = '', session = null, pid = null }) {
+    this.ts = ts;
+    this.exitCode = exitCode;
+    this.command = command;
+    this.stderr = stderr;
+    this.shell = shell;
+    this.actor = actor;
+    this.cwd = cwd;
+    this.workspaceRoot = workspaceRoot;
+    this.session = session;
+    this.pid = pid;
+  }
+}
+
+export class FailureReport {
+  constructor({ event, parsed, verification }) {
+    this.event = event;
+    this.parsed = parsed;
+    this.verification = verification;
+  }
+}
+
+export function parseLine(line) {
+  line = line.replace(/^\uFEFF/, ''); // strip UTF-8 BOM
+  try {
+    const payload = JSON.parse(line);
+    return new StreamEvent({
+      ts: String(payload.ts ?? ''),
+      exitCode: Number(payload.exit_code ?? 0),
+      command: String(payload.command ?? ''),
+      stderr: String(payload.stderr ?? ''),
+      shell: String(payload.shell ?? ''),
+      actor: String(payload.actor ?? ''),
+      cwd: String(payload.cwd ?? ''),
+      workspaceRoot: String(payload.workspace_root ?? ''),
+      session: payload.session ?? null,
+      pid: payload.pid ?? null,
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function toFailureReport(event) {
+  const parsed = classifyFailure(event.command, event.stderr, event.exitCode);
+  let verification;
+  if (parsed.errorType === 'invalid_flag') {
+    verification = verifyCommand(event.command, parsed.hallucinatedFlag);
+  } else {
+    verification = new VerificationResult({
+      availableFlags: [],
+      suggestedFlag: null,
+      correctedCommand: null,
+      source: 'none',
+    });
+  }
+  return new FailureReport({ event, parsed, verification });
+}
+
+// Async generator that tails a JSONL file and yields StreamEvent objects.
+// Resolves as soon as the file is created and emits new lines as they appear.
+export async function* tailJsonl(filePath, { pollInterval = 200, fromStart = false } = {}) {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  if (!existsSync(filePath)) writeFileSync(filePath, '', 'utf8');
+
+  const CHUNK = 65536;
+  const buf = Buffer.alloc(CHUNK);
+  let fd = openSync(filePath, 'r');
+  let pos = fromStart ? 0 : statSync(filePath).size;
+  let leftover = '';
+
+  try {
+    while (true) {
+      let bytesRead = readSync(fd, buf, 0, CHUNK, pos);
+      if (bytesRead > 0) {
+        pos += bytesRead;
+        leftover += buf.subarray(0, bytesRead).toString('utf8');
+        const lines = leftover.split('\n');
+        leftover = lines.pop(); // last potentially incomplete line
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          const event = parseLine(trimmed);
+          if (event) yield event;
+        }
+      } else {
+        // Check for truncation (log rotation)
+        try {
+          const size = statSync(filePath).size;
+          if (size < pos) {
+            closeSync(fd);
+            fd = openSync(filePath, 'r');
+            pos = 0;
+            leftover = '';
+          }
+        } catch {
+          // file disappeared, reopen
+          try { closeSync(fd); } catch { /* ignore */ }
+          if (!existsSync(filePath)) writeFileSync(filePath, '', 'utf8');
+          fd = openSync(filePath, 'r');
+          pos = 0;
+          leftover = '';
+        }
+        await sleep(pollInterval);
+      }
+    }
+  } finally {
+    try { closeSync(fd); } catch { /* ignore */ }
+  }
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}