@syntax-syllogism/sfd 0.2.0 → 0.4.0

package/src/commands.mjs

@@ -0,0 +1,132 @@
+export const COMMANDS = [
+  {
+    "name": "query",
+    "args": "<soql>",
+    "summary": "Run SOQL (all pages). --tooling, --all (include deleted), --limit <n>, --csv",
+    "agentTip": "\"<soql>\" --csv --limit 200: SOQL; --tooling, --all"
+  },
+  {
+    "name": "apex",
+    "args": "[file]",
+    "summary": "Run anonymous Apex from a file, -f <file>, or stdin. --log for the full debug log",
+    "agentTip": "-f <file> (or stdin): anonymous Apex; debug and fatal lines"
+  },
+  {
+    "name": "rest",
+    "args": "<path>",
+    "summary": "Call a REST path, e.g. /services/data/v67.0/limits. -X <method>, --body <json|@file>",
+    "agentTip": "<path>: REST; -X <method>, --body <json|@file>"
+  },
+  {
+    "name": "describe",
+    "args": "<sobject>",
+    "summary": "Compact describe. --tooling, --raw for the full describe",
+    "agentTip": "<sobject>: compact describe; --tooling, --raw",
+    "agentGroup": "describe"
+  },
+  {
+    "name": "list-metadata-types",
+    "args": "",
+    "summary": "List supported metadata types (cached per org and API version)",
+    "agentTip": ": supported metadata types (cached)",
+    "agentGroup": "describe"
+  },
+  {
+    "name": "list-metadata",
+    "args": "-m <Type>[,<Type>…]",
+    "summary": "List metadata names. -m repeatable, --folder <name>, --details for audit fields",
+    "agentTip": "-m <Type>: metadata names; --folder <name>, --details",
+    "agentGroup": "describe"
+  },
+  {
+    "name": "deploy",
+    "args": "",
+    "summary": "Deploy source. -d <path> (repeatable), -m <Type[:Name]> (repeatable),\n--check-only, -l <test level>, -t <test> (repeatable), -w <minutes>",
+    "agentTip": "-d <path> | -m <Type:Name>: deploy source",
+    "agentGroup": "source"
+  },
+  {
+    "name": "retrieve",
+    "args": "",
+    "summary": "Retrieve source. -d <path>, -m <Type[:Name]> or -x <package.xml>,\n-w <minutes>, --ignore-conflicts. No selector pulls tracked remote changes",
+    "agentTip": "[-d <path> | -m <Type:Name> | -x <manifest>]: retrieve source",
+    "agentGroup": "source"
+  },
+  {
+    "name": "tracking",
+    "args": "",
+    "summary": "Show source-tracked changes. --local | --remote, --conflicts (conflicts only)",
+    "agentTip": "[--local | --remote] [--conflicts]: source changes"
+  },
+  {
+    "name": "test",
+    "args": "",
+    "summary": "Run Apex tests. -n <class> (repeatable), -t <Class.method> (repeatable),\n-s <suite> (repeatable), -l <test level>, -c (coverage), -w <minutes>, --logs, --no-trace",
+    "agentTip": "-n <class> | -t <Class.method>: Apex tests; --logs, -c"
+  },
+  {
+    "name": "logs",
+    "args": "",
+    "summary": "List recent debug logs. --count/--limit <10>, --user <username>, --no-trace",
+    "agentTip": "[--count 10]: recent debug logs",
+    "agentGroup": "logs"
+  },
+  {
+    "name": "logs get",
+    "args": "<id|latest>",
+    "summary": "Print a filtered log. --full for raw text, --no-trace",
+    "agentTip": "latest: filtered debug log; --full for raw text",
+    "agentGroup": "logs"
+  },
+  {
+    "name": "org",
+    "args": "",
+    "summary": "Show the resolved org (username, id, instance, API version)",
+    "agentTip": ": resolved org details",
+    "agentGroup": "orgs"
+  },
+  {
+    "name": "org list",
+    "args": "[--all] [--status]",
+    "summary": "List authenticated orgs (local; --status pings)",
+    "agentTip": "[--all] [--status]: list local orgs; optional live checks",
+    "agentGroup": "orgs"
+  },
+  {
+    "name": "hook",
+    "args": "<agent|check|install|uninstall>",
+    "summary": "Integrate with Claude Code, Codex CLI or Gemini CLI",
+    "agentTip": "install --agent <claude|codex|gemini>: install rewrite hook",
+    "agentGroup": "agents"
+  },
+  {
+    "name": "agents-snippet",
+    "args": "[--write [file]]",
+    "summary": "Print agent instructions, or update AGENTS.md / CLAUDE.md",
+    "agentTip": "[--write [file]]: print or update agent instructions",
+    "agentGroup": "agents"
+  },
+  {
+    "name": "discover",
+    "args": "[--since 30d]",
+    "summary": "Report missed sfd opportunities in local agent transcripts",
+    "agentTip": "[--since 30d]: local transcript adoption report",
+    "agentGroup": "agents"
+  },
+  {
+    "name": "start | stop | status | reload",
+    "args": "",
+    "summary": "Manage the daemon. reload drops cached orgs and auth state",
+    "agentTip": ": daemon lifecycle"
+  }
+];
+
+export function commandHelp() {
+  return COMMANDS.map(({ name, args, summary }) => {
+    const syntax = [name, args].filter(Boolean).join(" ");
+    const description = summary.replaceAll("\n", "\n                        ");
+    return syntax.length >= 22
+      ? `  ${syntax}\n                        ${description}`
+      : `  ${syntax.padEnd(22)}${description}`;
+  }).join("\n");
+}

package/src/daemon.mjs

@@ -4,13 +4,16 @@ import { PROTOCOL, VERSION } from "./version.mjs";
 import { AlreadyRunning, startServer } from "./server.mjs";
 import { paths } from "./paths.mjs";
 import { findSfRoot, sfInfo } from "./sf-root.mjs";
+import { pathToFileURL } from "node:url";
 
 const log = (...args) => console.error(new Date().toISOString(), ...args);
 const p = paths();
 const sf = sfInfo(findSfRoot());
 
 // SFD_HANDLERS_MODULE swaps in stub handlers for tests that must not touch an org.
-const { createHandlers } = await import(process.env.SFD_HANDLERS_MODULE ?? "./handlers.mjs");
+// import() needs a file URL for absolute Windows paths such as C:\\...
+const handlersModule = process.env.SFD_HANDLERS_MODULE ? pathToFileURL(process.env.SFD_HANDLERS_MODULE).href : "./handlers.mjs";
+const { createHandlers } = await import(handlersModule);
 const handlers = createHandlers(sf.root);
 
 // An sf upgrade rewrites its package.json; finish in-flight work and let the next call start fresh.

package/src/discover/claude.mjs

@@ -0,0 +1,25 @@
+import { join } from "node:path";
+import { files, lines, matches, complete, candidate, count } from "./shared.mjs";
+
+export async function* read(options) {
+  const { home, since = new Date(0), stats } = options;
+  for await (const file of files(join(home, ".claude/projects"), ".jsonl", since, stats)) {
+    const pending = new Map();
+    for await (const entry of lines(file, stats)) {
+      const content = entry?.message?.content;
+      if (!Array.isArray(content)) { count(stats, "ignoredEntries"); continue; }
+      for (const item of content) {
+        if (item?.type === "tool_use" && item.name === "Bash") {
+          const command = item.input?.command;
+          if (!candidate(command)) continue;
+          const record = { agent: "claude", ts: new Date(entry.timestamp ?? NaN), command, cwd: entry.cwd, session: file };
+          if (matches(record, options)) pending.set(item.id, record);
+        } else if (item?.type === "tool_result" && pending.has(item.tool_use_id)) {
+          yield complete(pending.get(item.tool_use_id), entry.timestamp, item.content);
+          pending.delete(item.tool_use_id);
+        } else count(stats, "ignoredEntries");
+      }
+    }
+    yield* pending.values();
+  }
+}

package/src/discover/codex.mjs

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+import { files, lines, matches, complete, candidate, count, shellCommand } from "./shared.mjs";
+
+export async function* read(options) {
+  const { home, since = new Date(0), stats } = options;
+  for await (const file of files(join(home, ".codex/sessions"), ".jsonl", since, stats)) {
+    const pending = new Map();
+    let cwd;
+    for await (const entry of lines(file, stats)) {
+      const payload = entry?.payload;
+      if (["session_meta", "turn_context"].includes(entry?.type)) { cwd = payload?.cwd ?? cwd; continue; }
+      if (entry?.type !== "response_item" || !payload) { count(stats, "ignoredEntries"); continue; }
+      if (payload.type === "function_call" && ["shell", "shell_command", "exec_command"].includes(payload.name)) {
+        let args;
+        try { args = JSON.parse(payload.arguments); }
+        catch { count(stats, "malformedEntries"); continue; }
+        const command = shellCommand(args);
+        if (!candidate(command)) continue;
+        const record = { agent: "codex", ts: new Date(entry.timestamp ?? NaN), command, cwd: args.workdir ?? cwd, session: file };
+        if (matches(record, options)) pending.set(payload.call_id, record);
+      } else if (payload.type === "function_call_output" && pending.has(payload.call_id)) {
+        yield complete(pending.get(payload.call_id), entry.timestamp, payload.output);
+        pending.delete(payload.call_id);
+      } else count(stats, "ignoredEntries");
+    }
+    yield* pending.values();
+  }
+}

package/src/discover/gemini.mjs

@@ -0,0 +1,32 @@
+import { readFile } from "node:fs/promises";
+import { join, basename, dirname } from "node:path";
+import { files, matches, candidate, count, outputChars } from "./shared.mjs";
+
+export async function* read(options) {
+  const { home, since = new Date(0), stats } = options;
+  for await (const file of files(join(home, ".gemini/tmp"), ".json", since, stats)) {
+    if (basename(dirname(file)) !== "chats" && basename(file) !== "logs.json") continue;
+    let document;
+    // Gemini persists a JSON document, rather than a JSONL stream.
+    try { document = JSON.parse(await readFile(file, "utf8")); }
+    catch (error) { count(stats, error instanceof SyntaxError ? "malformedEntries" : "unreadableFiles"); continue; }
+    const messages = Array.isArray(document) ? document : document?.messages;
+    if (!Array.isArray(messages)) { count(stats, "ignoredEntries"); continue; }
+    for (const message of messages) {
+      if (!Array.isArray(message?.toolCalls)) { count(stats, "ignoredEntries"); continue; }
+      for (const tool of message.toolCalls) {
+        if (tool?.name !== "run_shell_command") { count(stats, "ignoredEntries"); continue; }
+        const command = tool.args?.command;
+        if (!candidate(command)) continue;
+        const record = {
+          agent: "gemini", ts: new Date(tool.timestamp ?? message.timestamp ?? NaN), command,
+          cwd: tool.args?.directory ?? message.cwd ?? document.cwd,
+          session: file
+        };
+        const chars = outputChars(tool.result);
+        if (chars !== undefined) record.outputChars = chars;
+        if (matches(record, options)) yield record;
+      }
+    }
+  }
+}

package/src/discover/index.mjs

@@ -0,0 +1,181 @@
+import { homedir } from "node:os";
+import { basename } from "node:path";
+import { rewrite, lex } from "../rewrite.mjs";
+import { read as claude } from "./claude.mjs";
+import { read as codex } from "./codex.mjs";
+import { read as gemini } from "./gemini.mjs";
+import { UsageError } from "../usage-error.mjs";
+import { Worker } from "node:worker_threads";
+import { COMMANDS } from "../commands.mjs";
+
+const readers = { claude, codex, gemini };
+// Only known command paths may enter the report; trailing words can be private values.
+const sfPaths = [
+  "org list metadata-types", "org list metadata", "org list", "org display",
+  "org create scratch", "org create sandbox", "org login web", "org login jwt",
+  "apex list log", "apex get log", "apex run test", "apex run", "data query",
+  "project retrieve start", "project deploy start", "sobject describe", "api request rest",
+  "plugins"
+];
+const commandPaths = {
+  sf: sfPaths,
+  sfdx: [...sfPaths, "force:org:list", "force:org:display", "force:data:soql:query",
+    "force:apex:execute", "force:apex:test:run", "force:source:deploy", "force:source:retrieve"],
+  sfd: COMMANDS.flatMap(({ name }) => name.split(" | "))
+};
+
+function subcommandName([executable, ...args]) {
+  if (!args.length || args[0].startsWith("-")) return "(no subcommand)";
+  const matches = commandPaths[executable].filter(path =>
+    path.split(" ").every((word, index) => args[index] === word));
+  return matches.sort((a, b) => b.split(" ").length - a.split(" ").length)[0]
+    ?? "(unrecognized subcommand)";
+}
+
+export function discoverOptions(values, now = Date.now()) {
+  const window = values.since ?? "30d";
+  if (!/^\d+[dh]$/.test(window)) throw new UsageError("--since must be a duration such as 30d or 12h.");
+  const since = new Date(now - Number(window.slice(0, -1)) * (window.endsWith("d") ? 86400000 : 3600000));
+  if (!Number.isFinite(+since)) throw new UsageError("--since is too large.");
+  const agents = [...new Set(values.agent ?? Object.keys(readers))];
+  if (agents.some(agent => !Object.hasOwn(readers, agent))) throw new UsageError("--agent must be claude, codex or gemini.");
+  const top = Number(values.top ?? 10);
+  if (!Number.isSafeInteger(top) || top <= 0) throw new UsageError("--top must be a positive integer.");
+  return { since, window, agents, top, project: values.project };
+}
+
+function invocation(command) {
+  let tokens;
+  try { tokens = lex(command); }
+  catch {
+    // The rewriter will retain its exact syntax/expansion skip reason.
+    const match = /^(?:\s*cd\s+\S+\s*&&)?\s*((?:\w+=\S+\s+)*)(sf|sfd|sfdx)\b(.*)/s.exec(command);
+    return match ? [match[2], ...match[3].trim().split(/\s+/)] : undefined;
+  }
+  const found = [];
+  let start = true;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.op) { start = ["&&", "||", ";", "|", "\n", "&"].includes(token.op); continue; }
+    if (!start) continue;
+    if (/^\w+=/.test(token.value) || ["env", "rtk", "proxy", "command"].includes(token.value)) continue;
+    start = false;
+    if (["sf", "sfd", "sfdx"].includes(basename(token.value))) {
+      const words = [basename(token.value)];
+      for (let j = i + 1; j < tokens.length && !tokens[j].op; j++) words.push(tokens[j].value);
+      found.push(words);
+    }
+  }
+  return found.find(words => words[0] !== "sfd") ?? found[0];
+}
+
+function reportReason(reason) {
+  if (reason.startsWith("unsupported result format ")) return "unsupported result format";
+  const flagReason = /^(unsupported flag|duplicate flag|missing value for|unsupported value for|unsupported boolean value) (.*)$/s.exec(reason);
+  if (!flagReason) return reason;
+  const flag = flagReason[2].split("=")[0];
+  return `${flagReason[1]}${/^(?:--[A-Za-z][A-Za-z0-9-]*|-[A-Za-z])$/.test(flag) ? ` ${flag}` : ""}`;
+}
+
+export function classify(command) {
+  const words = invocation(command);
+  if (!words) return;
+  const subcommand = subcommandName(words);
+  if (words[0] === "sfd") return { classification: "adopted", subcommand };
+  if (words[0] === "sfdx" && words[1]?.startsWith("force:")) return { classification: "legacy", subcommand };
+  const result = rewrite(command);
+  if (result.command) return { classification: "rewritable", subcommand };
+  if (result.skip === "unsupported sf command") return { classification: "unsupported", subcommand };
+  return { classification: "skipped", subcommand, reason: reportReason(result.skip) };
+}
+
+const median = values => {
+  if (!values.length) return null;
+  values.sort((a, b) => a - b);
+  const mid = Math.floor(values.length / 2);
+  return values.length % 2 ? values[mid] : (values[mid - 1] + values[mid]) / 2;
+};
+const ranked = map => [...map].map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+
+function scanAgent(agent, options) {
+  // Independent JSON parsers keep large agent histories off one CPU core.
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(new URL("./worker.mjs", import.meta.url), { workerData: { agent, ...options } });
+    let result;
+    worker.on("message", message => { result = message; });
+    worker.on("error", reject);
+    worker.on("exit", code => {
+      if (code !== 0 || !result) reject(new Error(`Discover ${agent} reader exited with code ${code}`));
+      else resolve(result);
+    });
+  });
+}
+
+export async function discover({ home = homedir(), agents = Object.keys(readers), since = new Date(0), window = "all history", project, top = 10 } = {}) {
+  const report = {
+    since: since.toISOString(), window, agents, project: project ?? null, top,
+    sfCalls: 0, sessions: 0,
+    counts: { rewritable: 0, skipped: 0, unsupported: 0, legacy: 0, adopted: 0 },
+    estimates: { timeSavedMs: 0, durationSamples: 0, outputChars: 0, outputSamples: 0, outputTokens: 0 },
+    diagnostics: { malformedEntries: 0, ignoredEntries: 0, unreadableFiles: 0 }
+  };
+  const sessions = new Set(), groups = new Map(), reasons = new Map(), unsupported = new Map(), rewritable = new Map();
+  const scans = await Promise.all(agents.map(agent => scanAgent(agent, { home, since, project })));
+  for (const { observations, stats } of scans) {
+    for (const [key, value] of Object.entries(stats)) report.diagnostics[key] += value;
+    for (const record of observations) {
+      const classification = record.classification;
+      const { classification: kind, subcommand, reason } = classification;
+      report.counts[kind]++;
+      if (kind !== "adopted") report.sfCalls++;
+      sessions.add(`${record.agent}:${record.session}`);
+      const key = JSON.stringify([kind, subcommand, reason]);
+      if (!groups.has(key)) groups.set(key, { ...classification, count: 0, durations: [], sizes: [] });
+      const group = groups.get(key);
+      group.count++;
+      if (record.durationMs !== undefined) group.durations.push(record.durationMs);
+      if (record.outputChars !== undefined) group.sizes.push(record.outputChars);
+      if (kind === "rewritable") {
+        rewritable.set(subcommand, (rewritable.get(subcommand) ?? 0) + 1);
+        if (record.durationMs !== undefined) {
+          report.estimates.durationSamples++;
+          report.estimates.timeSavedMs += Math.max(0, record.durationMs - 300);
+        }
+        if (record.outputChars !== undefined) {
+          report.estimates.outputSamples++;
+          report.estimates.outputChars += record.outputChars;
+        }
+      } else if (kind === "skipped") reasons.set(reason, (reasons.get(reason) ?? 0) + 1);
+      else if (["unsupported", "legacy"].includes(kind)) unsupported.set(subcommand, (unsupported.get(subcommand) ?? 0) + 1);
+    }
+  }
+  report.sessions = sessions.size;
+  report.estimates.outputTokens = report.estimates.outputChars / 4;
+  report.commands = [...groups.values()].map(({ durations, sizes, ...group }) => ({
+    ...group, medianDurationMs: median(durations), durationSamples: durations.length,
+    medianOutputChars: median(sizes), medianOutputTokens: sizes.length ? median(sizes) / 4 : null, outputSamples: sizes.length
+  })).sort((a, b) => b.count - a.count || a.subcommand.localeCompare(b.subcommand));
+  report.skipReasons = ranked(reasons);
+  report.unsupported = ranked(unsupported);
+  report.rewritable = ranked(rewritable);
+  return report;
+}
+
+export function formatReport(report) {
+  const list = items => items.slice(0, report.top).map(item => `${item.name} ${item.count}`).join(" · ") || "(none)";
+  const { counts: c, estimates: e, diagnostics: d } = report;
+  const time = e.durationSamples ? `~${(e.timeSavedMs / 60000).toFixed(1)} min saved (${e.durationSamples} samples)` : "time unknown";
+  const output = e.outputSamples ? `~${Math.round(e.outputTokens)} output tokens (${e.outputSamples} samples)` : "output unknown";
+  return [
+    `sfd discover: ${report.window}, ${report.agents.length} agents, ${report.sfCalls} sf/sfdx calls in ${report.sessions} sessions`,
+    `  rewritable now  ${c.rewritable}  (${time}; ${output})`,
+    `  skipped         ${c.skipped}  ${list(report.skipReasons)}`,
+    `  not in sfd      ${c.unsupported + c.legacy}  ${list(report.unsupported)} (legacy ${c.legacy})`,
+    `  already sfd     ${c.adopted}`,
+    `Top rewritable: ${list(report.rewritable)}`,
+    `Scan: ${d.malformedEntries} malformed, ${d.ignoredEntries} ignored entries, ${d.unreadableFiles} unreadable files.`,
+    "Durations include permission wait; savings assume 0.3 s/call. Tokens are chars/4.",
+    "Output tokens are potential savings before sfd output, which is not measured. Missing samples are not extrapolated.",
+    "Counts classify shell tool calls once; compound calls use the first sf/sfdx invocation."
+  ].join("\n");
+}

package/src/discover/shared.mjs

@@ -0,0 +1,79 @@
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { join, relative, resolve, isAbsolute } from "node:path";
+
+export function count(stats, key) {
+  if (stats) stats[key] = (stats[key] ?? 0) + 1;
+}
+
+export async function* files(root, extension, since, stats) {
+  let entries;
+  try { entries = await readdir(root, { withFileTypes: true }); }
+  catch (error) {
+    if (error.code !== "ENOENT") count(stats, "unreadableFiles");
+    return;
+  }
+  for (const entry of entries) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) yield* files(path, extension, since, stats);
+    else if (entry.isFile() && entry.name.endsWith(extension)) {
+      try {
+        if ((await stat(path)).mtimeMs >= Number(since)) yield path;
+      } catch { count(stats, "unreadableFiles"); }
+    }
+  }
+}
+
+export async function* lines(file, stats) {
+  const stream = createReadStream(file, { encoding: "utf8", highWaterMark: 1024 * 1024 });
+  const reader = createInterface({ input: stream, crlfDelay: Infinity });
+  // Forward stream errors into the iterator, including files removed mid-scan.
+  stream.on("error", error => reader.close());
+  try {
+    for await (const line of reader) {
+      if (!line.trim()) continue;
+      try { yield JSON.parse(line); }
+      catch { count(stats, "malformedEntries"); }
+    }
+    if (stream.errored) count(stats, "unreadableFiles");
+  } catch { count(stats, "unreadableFiles"); }
+  finally { reader.close(); stream.destroy(); }
+}
+
+export function matches(record, { since, project, stats }) {
+  if (record.ts == null || !Number.isFinite(+record.ts)) {
+    count(stats, "malformedEntries");
+    return false;
+  }
+  if (+record.ts < +since) return false;
+  if (!project) return true;
+  if (typeof record.cwd !== "string") return false;
+  const path = relative(resolve(project), resolve(record.cwd));
+  return !isAbsolute(path) && path !== ".." && !path.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`);
+}
+
+export function outputChars(output) {
+  if (output === undefined || output === null) return undefined;
+  return (typeof output === "string" ? output : JSON.stringify(output)).length;
+}
+
+export function complete(record, timestamp, output) {
+  const duration = +new Date(timestamp) - +record.ts;
+  return {
+    ...record,
+    ...(Number.isFinite(duration) && duration >= 0 ? { durationMs: duration } : {}),
+    ...(outputChars(output) !== undefined ? { outputChars: outputChars(output) } : {})
+  };
+}
+
+export function shellCommand(args) {
+  const command = args?.command ?? args?.cmd;
+  if (typeof command === "string") return command;
+  if (!Array.isArray(command) || !command.every(v => typeof v === "string")) return;
+  if (["bash", "sh", "/bin/bash", "/bin/sh"].includes(command[0]) && ["-lc", "-c"].includes(command[1]) && command.length === 3) return command[2];
+  // Preserve argv boundaries for the literal-shell rewriter.
+  return command.map(v => `'${v.replaceAll("'", "'\\''")}'`).join(" ");
+}
+
+export const candidate = command => typeof command === "string" && /\b(?:sf|sfd|sfdx)\b/.test(command);

package/src/discover/worker.mjs

@@ -0,0 +1,17 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { read as claude } from "./claude.mjs";
+import { read as codex } from "./codex.mjs";
+import { read as gemini } from "./gemini.mjs";
+import { classify } from "./index.mjs";
+
+const stats = {};
+const observations = [];
+const { agent, ...options } = workerData;
+for await (const record of ({ claude, codex, gemini })[agent]({ ...options, stats })) {
+  const classification = classify(record.command);
+  if (classification) observations.push({
+    agent, session: record.session, durationMs: record.durationMs,
+    outputChars: record.outputChars, classification
+  });
+}
+parentPort.postMessage({ observations, stats });