create-walle 0.9.25 → 0.9.26

package/template/wall-e/bin/train-gemma-e4b-tooluse.js

@@ -0,0 +1,1981 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  buildDatasetManifest,
+  checkHoldoutLeakage,
+  splitExamplesBySource,
+  stableStringify,
+  writeDatasetFiles,
+} = require('../training/tool-sft-dataset');
+const {
+  applyRunShellCommandSelection,
+  scoreRunShellCommandCandidates,
+} = require('../training/run-shell-command-selector');
+const {
+  applyTrajectoryActionSelection,
+  defaultActionMemoryFilesForEval,
+  loadTrajectoryActionMemory,
+  scoreTrajectoryActionCandidates,
+} = require('../training/trajectory-action-selector');
+const {
+  ActionMemoryStore,
+  defaultActionMemoryArtifactsDir,
+  defaultActionMemoryDbPath,
+} = require('../coding/action-memory-store');
+const {
+  summarizeActionMemoryReplayEval,
+} = require('../training/replay-eval-analysis');
+const { renderExample, writeRenderedSplit } = require('../training/tool-sft-renderers');
+const { buildSyntheticToolUseExamples, harvestToolTracesFromSessions } = require('../training/tool-trace-harvester');
+const {
+  auditDecisionPoints,
+  auditDecisiveActionExamples,
+  auditTrajectories,
+  buildDecisiveActionExamples,
+  buildPersonalReplayEvalCases,
+  buildPersonalReplayExamples,
+  decisionPointsFromTrajectories,
+  mineRealTrajectories,
+  targetToolCallFromExample,
+  trajectoryToCanonicalExamples,
+  writeWorkflowCatalog,
+  writeDecisionPointAudit,
+  writeTrajectoryAudit,
+} = require('../training/real-trajectory-miner');
+const { createMLXProvider } = require('../llm/mlx');
+const {
+  buildMlxLoraCommand,
+  buildMlxLoraConfig,
+  buildTrainingManifest,
+  runMlxLoraTraining,
+  validateDatasetFiles,
+  writeCandidateMetadata,
+  writeMlxLoraConfig,
+  writeModelCard,
+} = require('../training/gemma-e4b-qlora');
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const out = { command: argv[0] || 'help' };
+  for (let i = 1; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const key = arg.slice(2);
+    if (['dry-run', 'help'].includes(key)) {
+      out[key] = true;
+    } else {
+      out[key] = argv[i + 1];
+      i += 1;
+    }
+  }
+  return out;
+}
+
+function defaultOutputDir() {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(os.homedir(), '.walle', 'training', 'gemma-e4b-tooluse', stamp);
+}
+
+function parseList(value) {
+  if (!value) return [];
+  return String(value).split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+function parseBool(value, defaultValue = false) {
+  if (value === undefined || value === null) return defaultValue;
+  if (typeof value === 'boolean') return value;
+  return !/^(false|0|no|off)$/i.test(String(value).trim());
+}
+
+function normalizeToolCallFormat(value) {
+  return value === 'bare-json' ? 'bare-json' : 'fenced';
+}
+
+function parseRoots(args) {
+  return [
+    ...parseList(args.root),
+    ...parseList(args.roots),
+  ];
+}
+
+function parsePerSourceLimit(value) {
+  if (!value) return null;
+  const text = String(value).trim();
+  if (!text) return null;
+  if (/^\d+$/.test(text)) return { all: Number(text) };
+  const out = {};
+  for (const part of text.split(',')) {
+    const [rawKey, rawValue] = part.split('=');
+    const key = String(rawKey || '').trim();
+    const n = Number(String(rawValue || '').trim());
+    if (key && Number.isFinite(n) && n >= 0) out[key] = n;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+function parsePerToolLimit(value) {
+  return parsePerSourceLimit(value);
+}
+
+function applyPerToolLimit(examples = [], perToolLimit = null) {
+  const limits = parsePerToolLimit(perToolLimit);
+  if (!limits) return examples;
+  const counts = new Map();
+  const out = [];
+  for (const example of examples) {
+    const toolName = example.labels?.tool_name || 'unknown';
+    const cap = limits[toolName] ?? limits.all ?? limits.default ?? null;
+    const count = counts.get(toolName) || 0;
+    if (cap != null && count >= cap) continue;
+    counts.set(toolName, count + 1);
+    out.push(example);
+  }
+  return out;
+}
+
+function applyMaxRenderedChars(examples = [], { format = 'mlx-tools', maxChars = 0 } = {}) {
+  const limit = Number(maxChars || 0);
+  if (!Number.isFinite(limit) || limit <= 0) {
+    return { examples, dropped: 0, maxChars: limit, maxSeenChars: 0 };
+  }
+  const kept = [];
+  let dropped = 0;
+  let maxSeenChars = 0;
+  for (const example of examples) {
+    const rendered = renderExample(example, format, { compactTools: true });
+    const chars = JSON.stringify(rendered).length;
+    maxSeenChars = Math.max(maxSeenChars, chars);
+    if (chars <= limit) {
+      kept.push(example);
+    } else {
+      dropped += 1;
+    }
+  }
+  return { examples: kept, dropped, maxChars: limit, maxSeenChars };
+}
+
+function buildRenderedLengthGate({ filter = null, args = {} } = {}) {
+  if (!filter || !filter.maxChars) return null;
+  const minRows = parseNumber(args['min-rendered-length-kept-rows'], 0);
+  const checks = [{
+    name: 'renderedLengthKeptRows',
+    actual: filter.examples?.length || 0,
+    required: minRows,
+  }];
+  const failed = checks.filter((check) => check.actual < check.required);
+  return {
+    ok: failed.length === 0,
+    checks,
+    failed,
+  };
+}
+
+function parseNumber(value, defaultValue = 0) {
+  if (value === undefined || value === null || value === '') return defaultValue;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : defaultValue;
+}
+
+function buildRealDatasetQualityGate({ audit = null, examples = [], args = {} } = {}) {
+  if (!audit) return null;
+  const checks = [
+    {
+      name: 'goldTrajectories',
+      actual: audit.tierCounts?.gold || 0,
+      required: parseNumber(args['min-gold-trajectories'], 0),
+    },
+    {
+      name: 'silverTrajectories',
+      actual: audit.tierCounts?.silver || 0,
+      required: parseNumber(args['min-silver-trajectories'], 0),
+    },
+    {
+      name: 'goldOrSilverTrajectories',
+      actual: audit.datasetCandidateCounts?.goldOrSilverTrajectories || 0,
+      required: parseNumber(args['min-gold-or-silver-trajectories'], 0),
+    },
+    {
+      name: 'passingVerificationTrajectories',
+      actual: audit.signalCounts?.hasPassingVerification || 0,
+      required: parseNumber(args['min-passing-verification'], 0),
+    },
+    {
+      name: 'realSftExamples',
+      actual: examples.filter((example) => example.labels?.real_trajectory).length,
+      required: parseNumber(args['min-real-examples'], 0),
+    },
+  ];
+  const failed = checks.filter((check) => check.actual < check.required);
+  return {
+    ok: failed.length === 0,
+    checks,
+    failed,
+  };
+}
+
+function buildDecisionPointQualityGate({ audit = null, args = {} } = {}) {
+  if (!audit) return null;
+  const checks = [
+    {
+      name: 'decisionPoints',
+      actual: audit.totalDecisionPoints || 0,
+      required: parseNumber(args['min-decision-points'], 0),
+    },
+    {
+      name: 'guardRecoveryDecisionPoints',
+      actual: audit.guardRecoveryCount || 0,
+      required: parseNumber(args['min-guard-recovery'], 0),
+    },
+    {
+      name: 'sameInspectionAfterGuard',
+      actual: audit.sameInspectionAfterGuardCount || 0,
+      maximum: parseNumber(args['max-same-inspection-after-guard'], 0),
+    },
+  ];
+  const failed = checks.filter((check) => {
+    if (check.required !== undefined) return check.actual < check.required;
+    if (check.maximum !== undefined) return check.actual > check.maximum;
+    return false;
+  });
+  return {
+    ok: failed.length === 0,
+    checks,
+    failed,
+  };
+}
+
+function buildPersonalReplayDataGate({ workflowAudit = null, examples = [], args = {} } = {}) {
+  if (!workflowAudit) return null;
+  const personalRows = examples.filter((example) => example.labels?.personal_replay);
+  const editVerificationRows = personalRows.filter((example) => (
+    /^(edit_file|write_file|apply_patch|run_shell)$/.test(example.labels?.tool_name || '') &&
+    (example.labels?.latest_decisive_verification_status === 'passed' || example.labels?.verification_commands?.length)
+  ));
+  const firstActionRows = personalRows.filter((example) => {
+    const messages = example.messages || [];
+    return messages.filter((message) => message.role === 'assistant' && message.tool_calls?.length).length === 1 &&
+      !messages.some((message) => message.role === 'tool');
+  });
+  const variantRows = personalRows.filter((example) => /variant/.test(example.labels?.replay_lane || ''));
+  const checks = [
+    {
+      name: 'seenWorkflowFamilies',
+      actual: workflowAudit.totalFamilies || 0,
+      required: parseNumber(args['min-seen-workflow-families'], 0),
+    },
+    {
+      name: 'repeatedWorkflowFamilies',
+      actual: workflowAudit.repeatedFamilies || 0,
+      required: parseNumber(args['min-repeated-workflow-families'], 0),
+    },
+    {
+      name: 'seenReplayRows',
+      actual: personalRows.length,
+      required: parseNumber(args['min-seen-replay-rows'], 0),
+    },
+    {
+      name: 'seenVariantRows',
+      actual: variantRows.length,
+      required: parseNumber(args['min-seen-variant-rows'], 0),
+    },
+    {
+      name: 'editVerificationRows',
+      actual: editVerificationRows.length,
+      required: parseNumber(args['min-edit-verification-rows'], 0),
+    },
+    {
+      name: 'firstActionRows',
+      actual: firstActionRows.length,
+      required: parseNumber(args['min-first-action-rows'], 0),
+    },
+  ];
+  const failed = checks.filter((check) => check.actual < check.required);
+  return {
+    ok: failed.length === 0,
+    checks,
+    failed,
+  };
+}
+
+function buildDecisiveActionDataGate({ audit = null, args = {} } = {}) {
+  if (!audit) return null;
+  const checks = [
+    {
+      name: 'decisiveActionRows',
+      actual: audit.totalRows || 0,
+      required: parseNumber(args['min-decisive-action-rows'], 0),
+    },
+    {
+      name: 'decisiveExactRows',
+      actual: audit.exactRows || 0,
+      required: parseNumber(args['min-decisive-exact-rows'], 0),
+    },
+    {
+      name: 'decisiveEditRows',
+      actual: audit.editRows || 0,
+      required: parseNumber(args['min-decisive-edit-rows'], 0),
+    },
+    {
+      name: 'decisiveVerificationRows',
+      actual: audit.verificationRows || 0,
+      required: parseNumber(args['min-decisive-verification-rows'], 0),
+    },
+    {
+      name: 'decisiveRealToolResultRows',
+      actual: audit.realToolResultHistoryRows || 0,
+      required: parseNumber(args['min-decisive-real-result-rows'], 0),
+    },
+    {
+      name: 'jsonOnlyContractRows',
+      actual: audit.jsonOnlyContractRows || 0,
+      required: parseNumber(args['min-json-only-contract-rows'], 0),
+    },
+    {
+      name: 'stateSummaryRows',
+      actual: audit.stateSummaryRows || 0,
+      required: parseNumber(args['min-state-summary-rows'], 0),
+    },
+  ];
+  const failed = checks.filter((check) => check.actual < check.required);
+  return {
+    ok: failed.length === 0,
+    checks,
+    failed,
+  };
+}
+
+async function exportDataset(args) {
+  const outputDir = path.resolve(args['output-dir'] || defaultOutputDir());
+  const datasetDir = path.join(outputDir, 'dataset');
+  const format = args.format || 'mlx-tools';
+  const stateSummaryMode = parseBool(args['state-summary'], format === 'mlx-provider-state-bare');
+  const maxExamples = args['max-examples'] ? Number(args['max-examples']) : 0;
+  const qualityThreshold = args['quality-threshold'] ? Number(args['quality-threshold']) : 0.8;
+  const source = args.source || 'synthetic';
+  const useDecisiveActions = source === 'decisive-actions' || parseBool(args['decisive-actions'], false);
+  const excludeHoldoutIds = parseList(args['exclude-holdout-ids']);
+  const traceFiles = parseList(args['trace-files']);
+  const datasetVersion = args['dataset-version'] || 'gemma-e4b-tooluse-v1';
+  const targetedRepeats = args['targeted-repeats'] ? Number(args['targeted-repeats']) : 1;
+  const useRealTrajectories = source === 'real-sessions' || useDecisiveActions || parseBool(args['real-trajectories'], false);
+  const usePersonalReplay = source === 'personal-replay';
+  let realAudit = null;
+  let decisionAudit = null;
+  let decisionQualityGate = null;
+  let workflowAudit = null;
+  let workflowFamilies = [];
+  let personalReplayDataGate = null;
+  let decisiveActionAudit = null;
+  let decisiveActionDataGate = null;
+  let renderedLengthFilter = null;
+  let renderedLengthGate = null;
+  let personalReplayEvalCases = null;
+  let minedRealTrajectories = [];
+
+  let examples = [];
+  if (traceFiles.length) {
+    examples.push(...await harvestToolTracesFromSessions({
+      traceFiles,
+      excludeHoldoutIds,
+      qualityThreshold,
+      datasetVersion,
+    }));
+  }
+  if (useRealTrajectories || usePersonalReplay) {
+    const roots = parseRoots(args);
+    const includeCtm = parseBool(args['include-ctm'], true);
+    const mined = mineRealTrajectories({
+      roots: roots.length ? roots.map((root) => path.resolve(root)) : null,
+      repoPath: args.repo ? path.resolve(args.repo) : null,
+      source: args['transcript-source'] || 'all',
+      sinceDays: args['since-days'] === undefined ? 14 : Number(args['since-days']),
+      limit: args['scan-limit'] ? Number(args['scan-limit']) : (maxExamples > 0 ? maxExamples : 500),
+      includeCtm,
+      includeFilesystem: parseBool(args['include-filesystem'], roots.length > 0 || !includeCtm),
+      ctmDbPath: args['ctm-db'] ? path.resolve(args['ctm-db']) : undefined,
+      requireCodingIntent: parseBool(args['require-coding-intent'], true),
+      maxResultChars: args['max-result-chars'] ? Number(args['max-result-chars']) : undefined,
+      maxFileBytes: args['max-file-mb'] ? Number(args['max-file-mb']) * 1024 * 1024 : undefined,
+      perSourceLimit: parsePerSourceLimit(args['per-source-limit']),
+      recoverGit: parseBool(args['recover-git'], false),
+      gitRecoveryWindowMs: args['git-recovery-window-minutes']
+        ? Number(args['git-recovery-window-minutes']) * 60 * 1000
+        : undefined,
+      gitRecoveryRequireOverlap: !parseBool(args['allow-weak-git-recovery'], false),
+    });
+    minedRealTrajectories = mined.trajectories;
+    if (usePersonalReplay || useDecisiveActions || args['workflow-audit-dir']) {
+      const workflowWritten = writeWorkflowCatalog({
+        trajectories: minedRealTrajectories,
+        outputDir: path.resolve(args['workflow-audit-dir'] || path.join(outputDir, 'workflow-audit')),
+        includeTiers: parseList(args['include-tiers']).length ? parseList(args['include-tiers']) : ['gold', 'silver'],
+      });
+      workflowAudit = workflowWritten.audit;
+      workflowFamilies = workflowWritten.families;
+    }
+    if (args['audit-dir']) {
+      const writtenAudit = writeTrajectoryAudit({
+        trajectories: minedRealTrajectories,
+        outputDir: path.resolve(args['audit-dir']),
+        includePaths: parseBool(args['include-paths'], false),
+        skipped: mined.skipped,
+        diagnostics: mined.diagnostics,
+      });
+      realAudit = writtenAudit.audit;
+    } else {
+      realAudit = auditTrajectories(minedRealTrajectories);
+    }
+    const decisionPoints = decisionPointsFromTrajectories(minedRealTrajectories, {
+      includeMessages: parseBool(args['include-messages'], false),
+    });
+    if (args['decision-audit-dir']) {
+      const writtenDecisionAudit = writeDecisionPointAudit({
+        trajectories: minedRealTrajectories,
+        decisionPoints,
+        outputDir: path.resolve(args['decision-audit-dir']),
+        includeMessages: parseBool(args['include-messages'], false),
+        gate: {
+          minDecisionPoints: parseNumber(args['min-decision-points'], 0),
+          minGuardRecovery: parseNumber(args['min-guard-recovery'], 0),
+          maxSameInspectionAfterGuard: parseNumber(args['max-same-inspection-after-guard'], 0),
+        },
+      });
+      decisionAudit = writtenDecisionAudit.audit;
+    } else {
+      decisionAudit = auditDecisionPoints(decisionPoints, {
+        minDecisionPoints: parseNumber(args['min-decision-points'], 0),
+        minGuardRecovery: parseNumber(args['min-guard-recovery'], 0),
+        maxSameInspectionAfterGuard: parseNumber(args['max-same-inspection-after-guard'], 0),
+      });
+    }
+    decisionQualityGate = buildDecisionPointQualityGate({ audit: decisionAudit, args });
+    if (usePersonalReplay || useDecisiveActions) {
+      const personalExamples = useDecisiveActions ? buildDecisiveActionExamples({
+        trajectories: minedRealTrajectories,
+        families: workflowFamilies,
+        datasetVersion,
+        maxExamplesPerTrajectory: args['max-tool-examples-per-session']
+          ? Number(args['max-tool-examples-per-session'])
+          : 12,
+        includeTiers: parseList(args['include-tiers']).length ? parseList(args['include-tiers']) : ['gold', 'silver'],
+        includeTrainVariants: parseBool(args['include-train-variants'], true),
+        variantRepeats: args['personal-variant-repeats'] ? Number(args['personal-variant-repeats']) : 1,
+        exactRepeats: args['decisive-exact-repeats'] ? Number(args['decisive-exact-repeats']) : 1,
+        requireToolResultHistory: parseBool(args['require-decisive-tool-result-history'], true),
+        stateSummary: stateSummaryMode,
+      }) : buildPersonalReplayExamples({
+        trajectories: minedRealTrajectories,
+        families: workflowFamilies,
+        datasetVersion,
+        maxExamplesPerTrajectory: args['max-tool-examples-per-session']
+          ? Number(args['max-tool-examples-per-session'])
+          : 10,
+        includeTiers: parseList(args['include-tiers']).length ? parseList(args['include-tiers']) : ['gold', 'silver'],
+        includeTrainVariants: parseBool(args['include-train-variants'], true),
+        variantRepeats: args['personal-variant-repeats'] ? Number(args['personal-variant-repeats']) : 1,
+        stateSummary: stateSummaryMode,
+      });
+      examples.push(...personalExamples);
+      if (useDecisiveActions) decisiveActionAudit = auditDecisiveActionExamples(personalExamples);
+      personalReplayEvalCases = buildPersonalReplayEvalCases({
+        examples: personalExamples,
+        families: workflowFamilies,
+        maxExact: args['max-seen-exact-eval'] ? Number(args['max-seen-exact-eval']) : 120,
+        maxVariant: args['max-seen-variant-eval'] ? Number(args['max-seen-variant-eval']) : 120,
+      });
+    } else {
+      examples.push(...minedRealTrajectories.flatMap((trajectory) => trajectoryToCanonicalExamples(trajectory, {
+        datasetVersion,
+        maxExamplesPerTrajectory: args['max-tool-examples-per-session']
+          ? Number(args['max-tool-examples-per-session'])
+          : 12,
+        includeTiers: parseList(args['include-tiers']).length ? parseList(args['include-tiers']) : ['gold', 'silver'],
+        stateSummary: stateSummaryMode,
+      })));
+    }
+  }
+  if (source === 'synthetic' || source === 'all') {
+    examples.push(...buildSyntheticToolUseExamples({ excludeHoldoutIds, datasetVersion, targetedRepeats }));
+  }
+  if (source === 'sessions' || source === 'all') {
+    const roots = parseRoots(args);
+    examples.push(...await harvestToolTracesFromSessions({
+      roots: roots.length ? roots.map((root) => path.resolve(root)) : null,
+      repoPath: args.repo ? path.resolve(args.repo) : null,
+      includeTranscripts: true,
+      transcriptSource: args['transcript-source'] || 'all',
+      sinceDays: args['since-days'] === undefined ? 14 : Number(args['since-days']),
+      limit: args['scan-limit'] ? Number(args['scan-limit']) : (maxExamples > 0 ? maxExamples : 500),
+      excludeHoldoutIds,
+      qualityThreshold,
+      datasetVersion,
+      requireEdits: parseBool(args['require-edits'], true),
+      requireCodingIntent: parseBool(args['require-coding-intent'], true),
+      maxToolExamplesPerSession: args['max-tool-examples-per-session']
+        ? Number(args['max-tool-examples-per-session'])
+        : 12,
+    }));
+  }
+  examples = examples.filter((example) => example.quality >= qualityThreshold);
+  examples = applyPerToolLimit(examples, args['per-tool-limit']);
+  renderedLengthFilter = applyMaxRenderedChars(examples, {
+    format,
+    maxChars: args['max-rendered-chars'] ? Number(args['max-rendered-chars']) : 0,
+  });
+  examples = renderedLengthFilter.examples;
+  if (maxExamples > 0) examples = examples.slice(0, maxExamples);
+  if (useDecisiveActions) decisiveActionAudit = auditDecisiveActionExamples(examples);
+  if ((usePersonalReplay || useDecisiveActions) && personalReplayEvalCases) {
+    personalReplayEvalCases = buildPersonalReplayEvalCases({
+      examples,
+      families: workflowFamilies,
+      maxExact: args['max-seen-exact-eval'] ? Number(args['max-seen-exact-eval']) : 120,
+      maxVariant: args['max-seen-variant-eval'] ? Number(args['max-seen-variant-eval']) : 120,
+    });
+  }
+  const realQualityGate = buildRealDatasetQualityGate({ audit: realAudit, examples, args });
+  personalReplayDataGate = buildPersonalReplayDataGate({ workflowAudit, examples, args });
+  decisiveActionDataGate = buildDecisiveActionDataGate({ audit: decisiveActionAudit, args });
+  renderedLengthGate = buildRenderedLengthGate({ filter: renderedLengthFilter, args });
+  if (parseBool(args['fail-on-quality-gate'], false)) {
+    const failedGroups = [];
+    if (realQualityGate && !realQualityGate.ok) {
+      failedGroups.push(`real: ${formatGateFailures(realQualityGate.failed)}`);
+    }
+    if (decisionQualityGate && !decisionQualityGate.ok) {
+      failedGroups.push(`decision: ${formatGateFailures(decisionQualityGate.failed)}`);
+    }
+    if (personalReplayDataGate && !personalReplayDataGate.ok) {
+      failedGroups.push(`personalReplay: ${formatGateFailures(personalReplayDataGate.failed)}`);
+    }
+    if (decisiveActionDataGate && !decisiveActionDataGate.ok) {
+      failedGroups.push(`decisiveAction: ${formatGateFailures(decisiveActionDataGate.failed)}`);
+    }
+    if (renderedLengthGate && !renderedLengthGate.ok) {
+      failedGroups.push(`renderedLength: ${formatGateFailures(renderedLengthGate.failed)}`);
+    }
+    if (failedGroups.length) {
+      throw new Error(`Dataset quality gate failed: ${failedGroups.join('; ')}`);
+    }
+  }
+
+  const splits = splitExamplesBySource(examples, {
+    train: Number(args['train-ratio'] || 0.8),
+    valid: Number(args['valid-ratio'] || 0.1),
+    calibration: Number(args['calibration-ratio'] || 0.1),
+  }, args.seed || 'gemma-e4b-tooluse-v1');
+
+  let holdout = [];
+  if (args['holdout-manifest']) {
+    const parsed = JSON.parse(fs.readFileSync(path.resolve(args['holdout-manifest']), 'utf8'));
+    holdout = Array.isArray(parsed) ? parsed : (parsed.examples || parsed.holdout || []);
+  }
+  const leakage = checkHoldoutLeakage({ ...splits, holdout });
+  if (!leakage.ok) throw new Error(`Holdout leakage detected: ${leakage.leaked.map((x) => x.id || x.hash).join(', ')}`);
+
+  const manifest = buildDatasetManifest({
+    splits,
+    config: {
+      datasetVersion,
+      format,
+      stateSummaryMode,
+      source,
+      transcriptSource: args['transcript-source'] || null,
+      qualityThreshold,
+      targetedRepeats,
+      perToolLimit: args['per-tool-limit'] || null,
+      leakageCheck: { ok: leakage.ok, leaked: leakage.leaked.length },
+      realQualityGate,
+      decisionQualityGate,
+      personalReplayDataGate,
+      decisiveActionDataGate,
+      decisiveActionAudit,
+      renderedLengthGate,
+      renderedLengthFilter: renderedLengthFilter ? {
+        maxChars: renderedLengthFilter.maxChars,
+        dropped: renderedLengthFilter.dropped,
+        maxSeenChars: renderedLengthFilter.maxSeenChars,
+        kept: examples.length,
+      } : null,
+      workflowAudit: workflowAudit ? {
+        totalFamilies: workflowAudit.totalFamilies,
+        repeatedFamilies: workflowAudit.repeatedFamilies,
+        editVerificationTrajectories: workflowAudit.editVerificationTrajectories,
+        coveredTrajectories: workflowAudit.coveredTrajectories,
+      } : null,
+      replayEvalCases: personalReplayEvalCases ? {
+        seenExact: personalReplayEvalCases.seenExact.length,
+        seenVariant: personalReplayEvalCases.seenVariant.length,
+      } : null,
+      decisionAudit: decisionAudit ? {
+        totalDecisionPoints: decisionAudit.totalDecisionPoints,
+        guardRecoveryCount: decisionAudit.guardRecoveryCount,
+        sameInspectionAfterGuardCount: decisionAudit.sameInspectionAfterGuardCount,
+        targetToolCounts: decisionAudit.targetToolCounts,
+        labelCounts: decisionAudit.labelCounts,
+      } : null,
+    },
+  });
+  manifest.leakageCheck = { ok: leakage.ok, leaked: leakage.leaked.length };
+  const written = writeDatasetFiles({ outputDir: datasetDir, splits, manifest });
+  for (const [split, rows] of Object.entries({ train: splits.train, valid: splits.valid, test: splits.calibration })) {
+    writeRenderedSplit({ examples: rows, outputDir: datasetDir, splitName: split, format });
+  }
+  let replayEval = null;
+  if (personalReplayEvalCases) {
+    replayEval = writeReplayEvalCases({
+      outputDir: path.join(outputDir, 'replay-eval'),
+      cases: personalReplayEvalCases,
+      format,
+    });
+  }
+  fs.writeFileSync(path.join(outputDir, 'training-summary.json'), JSON.stringify({
+    outputDir,
+    datasetDir,
+    manifest: written.manifest,
+    replayEval,
+  }, null, 2) + '\n');
+  return { outputDir, datasetDir, manifest: written.manifest, replayEval };
+}
+
+function formatGateFailures(failed = []) {
+  return failed.map((check) => {
+    if (check.required !== undefined) return `${check.name} ${check.actual}/${check.required}`;
+    if (check.maximum !== undefined) return `${check.name} ${check.actual}>${check.maximum}`;
+    return `${check.name} actual=${check.actual}`;
+  }).join(', ');
+}
+
+function writeJsonl(filePath, rows = []) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, rows.map((row) => JSON.stringify(row)).join('\n') + (rows.length ? '\n' : ''), 'utf8');
+}
+
+function writeReplayEvalCases({ outputDir, cases, format = 'mlx-tools' } = {}) {
+  if (!outputDir) throw new Error('outputDir is required');
+  fs.mkdirSync(outputDir, { recursive: true });
+  const seenExactPath = path.join(outputDir, 'seen-exact.jsonl');
+  const seenVariantPath = path.join(outputDir, 'seen-variant.jsonl');
+  writeJsonl(seenExactPath, cases.seenExact || []);
+  writeJsonl(seenVariantPath, cases.seenVariant || []);
+  const manifest = {
+    generatedAt: new Date().toISOString(),
+    evaluationPolicy: 'personal_seen_replay',
+    leakageAllowed: true,
+    purpose: 'verify repeatability of known local workflows and light parameter variation',
+    format,
+    counts: {
+      seenExact: cases.seenExact?.length || 0,
+      seenVariant: cases.seenVariant?.length || 0,
+    },
+    files: {
+      seenExact: path.basename(seenExactPath),
+      seenVariant: path.basename(seenVariantPath),
+    },
+  };
+  const manifestPath = path.join(outputDir, 'manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+  return { outputDir, seenExactPath, seenVariantPath, manifestPath, manifest };
+}
+
+function exportReplaySliceDataset(args) {
+  const outputDir = path.resolve(args['output-dir'] || defaultOutputDir());
+  const datasetDir = path.join(outputDir, 'dataset');
+  const format = args.format || 'mlx-provider-state-bare';
+  const evalFile = args['eval-file'] ? path.resolve(args['eval-file']) : null;
+  if (!evalFile || !fs.existsSync(evalFile)) throw new Error(`Missing eval file: ${evalFile}`);
+  const resultsFile = args['results-file'] ? path.resolve(args['results-file']) : null;
+  if (resultsFile && !fs.existsSync(resultsFile)) throw new Error(`Missing results file: ${resultsFile}`);
+  const limit = args.limit ? Number(args.limit) : 12;
+  const repeats = args.repeats ? Number(args.repeats) : 8;
+  const targetMode = args['target-mode'] || 'full';
+  const includeTools = new Set(parseList(args['include-tools']));
+  const datasetVersion = args['dataset-version'] || 'gemma-e4b-tooluse-replay-slice';
+  const sliceMode = args['slice-mode'] || (resultsFile ? 'failures' : 'all');
+  const normalizedRows = readJsonl(evalFile)
+    .map((row) => normalizeReplayEvalExample(row))
+    .filter(Boolean);
+  const filteredRows = includeTools.size
+    ? normalizedRows.filter((row) => includeTools.has(targetToolCallFromExample(row)?.name))
+    : normalizedRows;
+  const resultFilteredRows = selectReplaySliceRows(filteredRows, { resultsFile, sliceMode });
+  const baseRows = resultFilteredRows.rows.slice(0, limit);
+  if (!baseRows.length) {
+    const toolSuffix = includeTools.size ? ` for tools: ${[...includeTools].join(',')}` : '';
+    const resultSuffix = resultsFile ? ` with slice mode: ${sliceMode}` : '';
+    throw new Error(`No replay rows selected${toolSuffix}${resultSuffix}`);
+  }
+  const examples = [];
+  for (let repeat = 0; repeat < Math.max(1, repeats); repeat += 1) {
+    for (const row of baseRows) {
+      const clone = JSON.parse(JSON.stringify(row));
+      clone.id = `${row.id}-replay-slice-${repeat}`;
+      clone.dataset_version = datasetVersion;
+      clone.source = `${row.source || 'replay-eval'}-replay-slice`;
+      clone.quality = Math.min(0.995, Math.max(0.8, Number(row.quality || 0.9)));
+      if (targetMode === 'tool-choice') eraseTargetArguments(clone);
+      clone.labels = {
+        ...(row.labels || {}),
+        replay_slice_training: true,
+        replay_slice_repeat: repeat,
+        replay_slice_target_mode: targetMode,
+      };
+      clone.leakage = {
+        ...(row.leakage || {}),
+        holdout: false,
+        source_session_id: `${row.leakage?.source_session_id || row.id}:replay-slice:${repeat}`,
+        source_task_id: `${row.leakage?.source_task_id || row.id}:replay-slice:${repeat}`,
+      };
+      examples.push(clone);
+    }
+  }
+  const renderedLengthFilter = applyMaxRenderedChars(examples, {
+    format,
+    maxChars: args['max-rendered-chars'] ? Number(args['max-rendered-chars']) : 0,
+  });
+  const keptExamples = renderedLengthFilter.examples;
+  const splits = ensureNonEmptyMlxTrainingSplits(splitExamplesBySource(keptExamples, {
+    train: Number(args['train-ratio'] || 0.96),
+    valid: Number(args['valid-ratio'] || 0.02),
+    calibration: Number(args['calibration-ratio'] || 0.02),
+  }, args.seed || 'gemma-e4b-tooluse-replay-slice'));
+  const manifest = buildDatasetManifest({
+    splits,
+    config: {
+      datasetVersion,
+      format,
+      source: 'replay-slice',
+      evalFile,
+      resultsFile,
+      limit,
+      repeats,
+      targetMode,
+      sliceMode,
+      includeTools: [...includeTools],
+      rowSelection: {
+        normalized: normalizedRows.length,
+        afterToolFilter: filteredRows.length,
+        ...(resultsFile ? { afterResultFilter: resultFilteredRows.rows.length } : {}),
+        selected: baseRows.length,
+      },
+      resultSelection: resultsFile ? resultFilteredRows.summary : null,
+      renderedLengthFilter: {
+        maxChars: renderedLengthFilter.maxChars,
+        dropped: renderedLengthFilter.dropped,
+        maxSeenChars: renderedLengthFilter.maxSeenChars,
+        kept: keptExamples.length,
+      },
+      splitRepair: splits.__repair || null,
+    },
+  });
+  manifest.leakageCheck = { ok: true, leaked: 0, replaySlice: true };
+  const written = writeDatasetFiles({ outputDir: datasetDir, splits, manifest });
+  for (const [split, rows] of Object.entries({ train: splits.train, valid: splits.valid, test: splits.calibration })) {
+    writeRenderedSplit({ examples: rows, outputDir: datasetDir, splitName: split, format });
+  }
+  const replayEval = writeReplayEvalCases({
+    outputDir: path.join(outputDir, 'replay-eval'),
+    cases: { seenExact: baseRows, seenVariant: [] },
+    format,
+  });
+  fs.writeFileSync(path.join(outputDir, 'training-summary.json'), JSON.stringify({
+    outputDir,
+    datasetDir,
+    manifest: written.manifest,
+    replayEval,
+  }, null, 2) + '\n');
+  return { outputDir, datasetDir, manifest: written.manifest, replayEval };
+}
+
+function ensureNonEmptyMlxTrainingSplits(inputSplits = {}) {
+  const splits = {
+    train: [...(inputSplits.train || [])],
+    valid: [...(inputSplits.valid || [])],
+    calibration: [...(inputSplits.calibration || [])],
+    ab_holdout: [...(inputSplits.ab_holdout || [])],
+  };
+  const allRows = [...splits.train, ...splits.valid, ...splits.calibration, ...splits.ab_holdout];
+  if (!allRows.length) return splits;
+  const repair = { train: 0, valid: 0, calibration: 0, reason: 'mlx_lora_requires_non_empty_local_subsets' };
+  if (!splits.train.length) {
+    splits.train.push(cloneReplaySplitBackfillRow(allRows[0], 'train', 0));
+    repair.train += 1;
+  }
+  for (const split of ['valid', 'calibration']) {
+    if (splits[split].length) continue;
+    const source = splits.train[(repair[split] || 0) % splits.train.length] || allRows[0];
+    splits[split].push(cloneReplaySplitBackfillRow(source, split, repair[split] || 0));
+    repair[split] += 1;
+  }
+  if (repair.train || repair.valid || repair.calibration) {
+    Object.defineProperty(splits, '__repair', {
+      value: repair,
+      enumerable: false,
+    });
+  }
+  return splits;
+}
+
+function cloneReplaySplitBackfillRow(row = {}, split = 'valid', idx = 0) {
+  const clone = JSON.parse(JSON.stringify(row));
+  clone.id = `${row.id || 'replay-row'}-mlx-${split}-backfill-${idx}`;
+  clone.split = split;
+  clone.labels = {
+    ...(clone.labels || {}),
+    replay_slice_split_backfill: true,
+    replay_slice_split_backfill_split: split,
+    replay_slice_split_backfill_source_id: row.id || null,
+  };
+  clone.leakage = {
+    ...(clone.leakage || {}),
+    holdout: split === 'ab_holdout',
+  };
+  return clone;
+}
+
+function selectReplaySliceRows(rows = [], { resultsFile = null, sliceMode = 'all' } = {}) {
+  const mode = sliceMode || 'all';
+  if (!resultsFile || mode === 'all') {
+    return { rows, summary: { mode, resultsFile: resultsFile || null, available: rows.length, selected: rows.length } };
+  }
+  const resultsById = new Map(readJsonl(resultsFile).map((row) => [row.id, row]));
+  const selected = [];
+  const summary = {
+    mode,
+    resultsFile,
+    available: rows.length,
+    resultRows: resultsById.size,
+    matched: 0,
+    parserFailures: 0,
+    wrongTool: 0,
+    failures: 0,
+    selected: 0,
+  };
+  for (const row of rows) {
+    const result = resultsById.get(row.id);
+    if (!result) continue;
+    summary.matched += 1;
+    const parserFailure = replayResultParserFailure(result);
+    const wrongTool = replayResultWrongTool(result, row);
+    const failed = !result.score?.pass;
+    if (parserFailure) summary.parserFailures += 1;
+    if (wrongTool) summary.wrongTool += 1;
+    if (failed) summary.failures += 1;
+    if (replaySliceResultMatchesMode({ mode, parserFailure, wrongTool, failed })) selected.push(row);
+  }
+  summary.selected = selected.length;
+  return { rows: selected, summary };
+}
+
+function replaySliceResultMatchesMode({ mode, parserFailure, wrongTool, failed }) {
+  if (mode === 'failures') return failed;
+  if (mode === 'parser-failures') return parserFailure;
+  if (mode === 'wrong-tool') return wrongTool;
+  if (mode === 'parser-or-wrong-tool') return parserFailure || wrongTool;
+  throw new Error(`Unsupported replay slice mode: ${mode}`);
+}
+
+function replayResultParserFailure(result = {}) {
+  if (!result.prediction) return true;
+  if (result.parsedToolCallCount !== undefined && Number(result.parsedToolCallCount) <= 0) return true;
+  return false;
+}
+
+function replayResultWrongTool(result = {}, example = {}) {
+  if (!result.prediction) return false;
+  if (result.score?.toolNameMatch === false) return true;
+  const predictedTool = result.prediction.tool || result.prediction.name;
+  const expectedTool = result.expected?.tool || targetToolCallFromExample(example)?.name;
+  return !!predictedTool && !!expectedTool && predictedTool !== expectedTool;
+}
+
+function eraseTargetArguments(example = {}) {
+  for (let i = (example.messages || []).length - 1; i >= 0; i -= 1) {
+    const message = example.messages[i];
+    if (message.role !== 'assistant' || !Array.isArray(message.tool_calls) || !message.tool_calls.length) continue;
+    for (const call of message.tool_calls) {
+      if (call.function) call.function.arguments = '{}';
+      else call.arguments = '{}';
+    }
+    return example;
+  }
+  return example;
+}
+
+function auditRealTrajectories(args) {
+  const outputDir = path.resolve(args['output-dir'] || path.join(defaultOutputDir(), 'real-trajectory-audit'));
+  const roots = parseRoots(args);
+  const includeCtm = parseBool(args['include-ctm'], true);
+  const mined = mineRealTrajectories({
+    roots: roots.length ? roots.map((root) => path.resolve(root)) : null,
+    repoPath: args.repo ? path.resolve(args.repo) : null,
+    source: args['transcript-source'] || args.source || 'all',
+    sinceDays: args['since-days'] === undefined ? 14 : Number(args['since-days']),
+    limit: args['scan-limit'] ? Number(args['scan-limit']) : 500,
+    includeCtm,
+    includeFilesystem: parseBool(args['include-filesystem'], roots.length > 0 || !includeCtm),
+    ctmDbPath: args['ctm-db'] ? path.resolve(args['ctm-db']) : undefined,
+    requireCodingIntent: parseBool(args['require-coding-intent'], true),
+    maxResultChars: args['max-result-chars'] ? Number(args['max-result-chars']) : undefined,
+    maxFileBytes: args['max-file-mb'] ? Number(args['max-file-mb']) * 1024 * 1024 : undefined,
+    perSourceLimit: parsePerSourceLimit(args['per-source-limit']),
+    recoverGit: parseBool(args['recover-git'], false),
+    gitRecoveryWindowMs: args['git-recovery-window-minutes']
+      ? Number(args['git-recovery-window-minutes']) * 60 * 1000
+      : undefined,
+    gitRecoveryRequireOverlap: !parseBool(args['allow-weak-git-recovery'], false),
+  });
+  const written = writeTrajectoryAudit({
+    trajectories: mined.trajectories,
+    outputDir,
+    includePaths: parseBool(args['include-paths'], false),
+    skipped: mined.skipped,
+    diagnostics: mined.diagnostics,
+  });
+  return {
+    outputDir,
+    scanned: mined.scanned,
+    trajectories: mined.trajectories.length,
+    skipped: mined.skipped,
+    auditPath: written.auditPath,
+    manifestPath: written.manifestPath,
+    tierCounts: written.audit.tierCounts,
+    sourceCounts: written.audit.sourceCounts,
+    signalCounts: written.audit.signalCounts,
+    datasetCandidateCounts: written.audit.datasetCandidateCounts,
+    resultCoverage: written.audit.resultCoverage,
+  };
+}
+
+function auditDecisionPointsCommand(args) {
+  const outputDir = path.resolve(args['output-dir'] || path.join(defaultOutputDir(), 'decision-point-audit'));
+  const roots = parseRoots(args);
+  const includeCtm = parseBool(args['include-ctm'], true);
+  const mined = mineRealTrajectories({
+    roots: roots.length ? roots.map((root) => path.resolve(root)) : null,
+    repoPath: args.repo ? path.resolve(args.repo) : null,
+    source: args['transcript-source'] || args.source || 'all',
+    sinceDays: args['since-days'] === undefined ? 14 : Number(args['since-days']),
+    limit: args['scan-limit'] ? Number(args['scan-limit']) : 500,
+    includeCtm,
+    includeFilesystem: parseBool(args['include-filesystem'], roots.length > 0 || !includeCtm),
+    ctmDbPath: args['ctm-db'] ? path.resolve(args['ctm-db']) : undefined,
+    requireCodingIntent: parseBool(args['require-coding-intent'], true),
+    maxResultChars: args['max-result-chars'] ? Number(args['max-result-chars']) : undefined,
+    maxFileBytes: args['max-file-mb'] ? Number(args['max-file-mb']) * 1024 * 1024 : undefined,
+    perSourceLimit: parsePerSourceLimit(args['per-source-limit']),
+    recoverGit: parseBool(args['recover-git'], false),
+    gitRecoveryWindowMs: args['git-recovery-window-minutes']
+      ? Number(args['git-recovery-window-minutes']) * 60 * 1000
+      : undefined,
+    gitRecoveryRequireOverlap: !parseBool(args['allow-weak-git-recovery'], false),
+  });
+  const decisionPoints = decisionPointsFromTrajectories(mined.trajectories, {
+    includeMessages: parseBool(args['include-messages'], false),
+  });
+  const written = writeDecisionPointAudit({
+    trajectories: mined.trajectories,
+    decisionPoints,
+    outputDir,
+    includeMessages: parseBool(args['include-messages'], false),
+    gate: {
+      minDecisionPoints: parseNumber(args['min-decision-points'], 0),
+      minGuardRecovery: parseNumber(args['min-guard-recovery'], 0),
+      maxSameInspectionAfterGuard: parseNumber(args['max-same-inspection-after-guard'], 0),
+    },
+  });
+  if (!written.audit.gate.ok && parseBool(args['fail-on-quality-gate'], false)) {
+    const detail = written.audit.gate.failed
+      .map((check) => `${check.name} actual=${check.actual} ${check.required !== undefined ? `required=${check.required}` : `maximum=${check.maximum}`}`)
+      .join(', ');
+    throw new Error(`Decision-point quality gate failed: ${detail}`);
+  }
+  return {
+    outputDir,
+    scanned: mined.scanned,
+    trajectories: mined.trajectories.length,
+    decisionPoints: decisionPoints.length,
+    skipped: mined.skipped,
+    decisionPath: written.decisionPath,
+    auditPath: written.auditPath,
+    manifestPath: written.manifestPath,
+    targetToolCounts: written.audit.targetToolCounts,
+    labelCounts: written.audit.labelCounts,
+    gate: written.audit.gate,
+  };
+}
+
+function auditWorkflowsCommand(args) {
+  const outputDir = path.resolve(args['output-dir'] || path.join(defaultOutputDir(), 'workflow-audit'));
+  const roots = parseRoots(args);
+  const includeCtm = parseBool(args['include-ctm'], true);
+  const mined = mineRealTrajectories({
+    roots: roots.length ? roots.map((root) => path.resolve(root)) : null,
+    repoPath: args.repo ? path.resolve(args.repo) : null,
+    source: args['transcript-source'] || args.source || 'all',
+    sinceDays: args['since-days'] === undefined ? 90 : Number(args['since-days']),
+    limit: args['scan-limit'] ? Number(args['scan-limit']) : 1000,
+    includeCtm,
+    includeFilesystem: parseBool(args['include-filesystem'], roots.length > 0 || !includeCtm),
+    ctmDbPath: args['ctm-db'] ? path.resolve(args['ctm-db']) : undefined,
+    requireCodingIntent: parseBool(args['require-coding-intent'], true),
+    maxResultChars: args['max-result-chars'] ? Number(args['max-result-chars']) : undefined,
+    maxFileBytes: args['max-file-mb'] ? Number(args['max-file-mb']) * 1024 * 1024 : undefined,
+    perSourceLimit: parsePerSourceLimit(args['per-source-limit']),
+    recoverGit: parseBool(args['recover-git'], false),
+    gitRecoveryWindowMs: args['git-recovery-window-minutes']
+      ? Number(args['git-recovery-window-minutes']) * 60 * 1000
+      : undefined,
+    gitRecoveryRequireOverlap: !parseBool(args['allow-weak-git-recovery'], false),
+  });
+  const written = writeWorkflowCatalog({
+    trajectories: mined.trajectories,
+    outputDir,
+    includeTiers: parseList(args['include-tiers']).length ? parseList(args['include-tiers']) : ['gold', 'silver'],
+  });
+  return {
+    outputDir,
+    scanned: mined.scanned,
+    trajectories: mined.trajectories.length,
+    skipped: mined.skipped,
+    catalogPath: written.catalogPath,
+    auditPath: written.auditPath,
+    totalFamilies: written.audit.totalFamilies,
+    repeatedFamilies: written.audit.repeatedFamilies,
+    editVerificationTrajectories: written.audit.editVerificationTrajectories,
+    gates: written.audit.gates,
+    topFamilies: written.audit.topFamilies.slice(0, 10),
+  };
+}
+
+async function evalReplayDataset(args) {
+  const outputDir = path.resolve(args['output-dir'] || path.join(defaultOutputDir(), 'replay-eval-results'));
+  const datasetOutputDir = args['dataset-output-dir'] ? path.resolve(args['dataset-output-dir']) : null;
+  const evalFile = args['eval-file']
+    ? path.resolve(args['eval-file'])
+    : path.join(datasetOutputDir || path.resolve(args['dataset-dir'] || ''), 'replay-eval', `${args.lane || 'seen-exact'}.jsonl`);
+  if (!evalFile || !fs.existsSync(evalFile)) throw new Error(`Missing eval file: ${evalFile}`);
+  const model = args.model || 'gemma4:e4b-it-qat';
+  const toolCallFormat = normalizeToolCallFormat(args['tool-call-format']);
+  const provider = createMLXProvider({
+    adapterPath: args['adapter-path'] ? path.resolve(args['adapter-path']) : undefined,
+    inferenceTimeoutMs: args['inference-timeout-ms'] ? Number(args['inference-timeout-ms']) : undefined,
+    toolCallFormat,
+    forceToolJsonPrefix: parseBool(args['force-tool-json-prefix'], false),
+  });
+  const rows = readJsonl(evalFile)
+    .map((row) => normalizeReplayEvalExample(row))
+    .filter(Boolean);
+  const limit = args.limit ? Number(args.limit) : rows.length;
+  const maxTokens = args['max-tokens'] ? Number(args['max-tokens']) : 256;
+  const actionMemorySelector = args['action-memory-selector'] || 'off';
+  const runShellCommandSelector = args['run-shell-command-selector'] || (actionMemorySelector === 'store' ? 'store' : 'off');
+  const runShellMaxCandidates = args['run-shell-max-candidates'] ? Number(args['run-shell-max-candidates']) : 12;
+  const actionMemoryMaxCandidates = args['action-memory-max-candidates'] ? Number(args['action-memory-max-candidates']) : 24;
+  const actionMemoryMinScore = args['action-memory-min-score'] ? Number(args['action-memory-min-score']) : 100;
+  const actionMemorySelectionUsesStore = ['store', 'sidecar', 'action-memory'].includes(actionMemorySelector);
+  const runShellSelectionUsesStore = ['store', 'sidecar', 'action-memory'].includes(runShellCommandSelector);
+  const useActionMemoryStore = actionMemorySelectionUsesStore || runShellSelectionUsesStore;
+  const actionMemoryFiles = (actionMemorySelector === 'heuristic' || useActionMemoryStore)
+    ? actionMemoryFilePaths(args, evalFile)
+    : [];
+  const actionMemory = actionMemorySelector === 'heuristic'
+    ? loadTrajectoryActionMemory(actionMemoryFiles)
+    : [];
+  let actionMemoryStore = null;
+  let actionMemoryStoreInfo = null;
+  if (useActionMemoryStore) {
+    const storePaths = actionMemoryStorePaths(args, outputDir);
+    actionMemoryStore = new ActionMemoryStore(storePaths).init();
+    if (parseBool(args['action-memory-build-from-files'], true)) {
+      actionMemoryStoreInfo = recordTrajectoryRowsToActionMemoryStore(actionMemoryFiles, {
+        store: actionMemoryStore,
+        excludeIds: parseBool(args['action-memory-allow-eval-rows'], false)
+          ? new Set()
+          : new Set(rows.map((row) => row.id).filter(Boolean)),
+        excludeFamilyIds: parseBool(args['action-memory-exclude-eval-families'], false)
+          ? new Set(rows.map((row) => row.labels?.workflow_family_id).filter(Boolean))
+          : new Set(),
+        sourceKind: 'trajectory-jsonl',
+        model: {
+          provider: args['source-provider'] || '',
+          modelId: args['source-model'] || '',
+          toolFormat: args['source-tool-format'] || '',
+        },
+      });
+    } else {
+      actionMemoryStoreInfo = { dbPath: storePaths.dbPath, artifactsDir: storePaths.artifactsDir, recorded: 0, skipped: 0 };
+    }
+  }
+  const results = [];
+  for (const example of rows.slice(0, limit)) {
+    const target = targetToolCallFromExample(example);
+    if (!target) continue;
+    const promptMessages = example.messages.slice(0, target.messageIndex);
+    const startedAt = Date.now();
+    let prediction = null;
+    let error = null;
+    let raw = null;
+    try {
+      raw = await provider.chat({
+        model,
+        messages: promptMessages,
+        tools: example.tools,
+        maxTokens,
+        temperature: 0,
+      });
+      prediction = raw.toolCalls?.[0] || null;
+      if (runShellCommandSelector !== 'off') {
+        const selected = applyRunShellCommandSelection(example, prediction, {
+          maxCandidates: runShellMaxCandidates,
+          actionMemoryStore: runShellSelectionUsesStore ? actionMemoryStore : null,
+        });
+        prediction = selected.prediction;
+        raw.runShellCommandSelection = selected.selection;
+        raw.runShellCommandCandidates = selected.candidates;
+        raw.runShellCommandOracle = target.name === 'run_shell'
+          ? scoreRunShellCommandCandidates(target.args?.command || '', selected.candidates, selected.selection)
+          : null;
+      }
+      if (actionMemorySelector === 'heuristic' || actionMemorySelectionUsesStore) {
+        const selected = applyTrajectoryActionSelection(example, prediction, {
+          memory: actionMemory,
+          actionMemoryStore: actionMemorySelectionUsesStore ? actionMemoryStore : null,
+          rawText: raw?.rawText || raw?.content || '',
+          maxCandidates: actionMemoryMaxCandidates,
+          minScore: actionMemoryMinScore,
+        });
+        prediction = selected.prediction;
+        raw.actionMemorySelection = selected.selection;
+        raw.actionMemoryCandidates = selected.candidates;
+        raw.actionMemoryOracle = scoreTrajectoryActionCandidates(target, selected.candidates, selected.selection);
+      }
+    } catch (err) {
+      error = err.message;
+    }
+    const score = scoreReplayPrediction({ expected: target, prediction });
+    const rawText = raw?.rawText || raw?.content || '';
+    results.push({
+      id: example.id,
+      lane: example.labels?.replay_eval_lane || example.labels?.replay_lane || args.lane || null,
+      workflowFamilyId: example.labels?.workflow_family_id || null,
+      expected: {
+        tool: target.name,
+        argKeys: Object.keys(target.args || {}).sort(),
+        argsHash: stableStringify(target.args || {}),
+      },
+      prediction: prediction ? {
+        tool: prediction.name,
+        input: prediction.input || {},
+      } : null,
+      runShellCommandSelection: raw?.runShellCommandSelection || null,
+      runShellCommandOracle: raw?.runShellCommandOracle || null,
+      runShellCommandCandidateCount: raw?.runShellCommandCandidates?.length || 0,
+      actionMemorySelection: raw?.actionMemorySelection || null,
+      actionMemoryOracle: raw?.actionMemoryOracle || null,
+      actionMemoryCandidateCount: raw?.actionMemoryCandidates?.length || 0,
+      rawText: rawText ? String(rawText).slice(0, 1200) : '',
+      rawDiagnostics: summarizeRawGeneration(rawText),
+      parsedToolCallCount: raw?.toolCalls?.length || 0,
+      score,
+      error,
+      latencyMs: raw?.latencyMs || Date.now() - startedAt,
+      usage: raw?.usage || null,
+    });
+  }
+  const summary = summarizeReplayEval(results);
+  const actionMemoryReport = useActionMemoryStore
+    ? summarizeActionMemoryReplayEval(results, {
+        allowSameRowCopies: parseBool(args['action-memory-allow-eval-rows'], false),
+      })
+    : null;
+  fs.mkdirSync(outputDir, { recursive: true });
+  const resultPath = path.join(outputDir, 'replay-eval-results.jsonl');
+  const summaryPath = path.join(outputDir, 'replay-eval-summary.json');
+  writeJsonl(resultPath, results);
+  fs.writeFileSync(summaryPath, JSON.stringify({
+    generatedAt: new Date().toISOString(),
+    model,
+    adapterPath: args['adapter-path'] || null,
+    toolCallFormat,
+    forceToolJsonPrefix: parseBool(args['force-tool-json-prefix'], false),
+    runShellCommandSelector,
+    runShellMaxCandidates,
+    actionMemorySelector,
+    actionMemoryFiles,
+    actionMemoryCandidateCount: actionMemory.length,
+    actionMemoryStore: actionMemoryStoreInfo,
+    actionMemoryMaxCandidates,
+    actionMemoryMinScore,
+    evalFile,
+    limit,
+    summary,
+    actionMemoryReport,
+  }, null, 2) + '\n', 'utf8');
+  if (actionMemoryStore) actionMemoryStore.close();
+  return { outputDir, evalFile, resultPath, summaryPath, summary, actionMemoryStore: actionMemoryStoreInfo };
+}
+
+function evalReplayResults(args) {
+  const outputDir = path.resolve(args['output-dir'] || path.join(defaultOutputDir(), 'replay-result-eval'));
+  const evalFile = args['eval-file'] ? path.resolve(args['eval-file']) : null;
+  const resultsFile = args['results-file'] ? path.resolve(args['results-file']) : null;
+  if (!evalFile || !fs.existsSync(evalFile)) throw new Error(`Missing eval file: ${evalFile}`);
+  if (!resultsFile || !fs.existsSync(resultsFile)) throw new Error(`Missing results file: ${resultsFile}`);
+
+  const examples = new Map(readJsonl(evalFile)
+    .map((row) => normalizeReplayEvalExample(row))
+    .filter(Boolean)
+    .map((row) => [row.id, row]));
+  const baselineRows = readJsonl(resultsFile);
+  const limit = args.limit ? Number(args.limit) : baselineRows.length;
+  const runShellCommandSelector = args['run-shell-command-selector'] || 'off';
+  const runShellMaxCandidates = args['run-shell-max-candidates'] ? Number(args['run-shell-max-candidates']) : 12;
+  const actionMemorySelector = args['action-memory-selector'] || 'off';
+  const actionMemoryMaxCandidates = args['action-memory-max-candidates'] ? Number(args['action-memory-max-candidates']) : 24;
+  const actionMemoryMinScore = args['action-memory-min-score'] ? Number(args['action-memory-min-score']) : 100;
+  const actionMemorySelectionUsesStore = ['store', 'sidecar', 'action-memory'].includes(actionMemorySelector);
+  const runShellSelectionUsesStore = ['store', 'sidecar', 'action-memory'].includes(runShellCommandSelector);
+  const useActionMemoryStore = actionMemorySelectionUsesStore || runShellSelectionUsesStore;
+  const actionMemoryFiles = (actionMemorySelector === 'heuristic' || useActionMemoryStore)
+    ? actionMemoryFilePaths(args, evalFile)
+    : [];
+  const actionMemory = actionMemorySelector === 'heuristic'
+    ? loadTrajectoryActionMemory(actionMemoryFiles)
+    : [];
+  let actionMemoryStore = null;
+  let actionMemoryStoreInfo = null;
+  try {
+    if (useActionMemoryStore) {
+      const storePaths = actionMemoryStorePaths(args, outputDir);
+      actionMemoryStore = new ActionMemoryStore(storePaths).init();
+      if (parseBool(args['action-memory-build-from-files'], true)) {
+        actionMemoryStoreInfo = recordTrajectoryRowsToActionMemoryStore(actionMemoryFiles, {
+          store: actionMemoryStore,
+          excludeIds: parseBool(args['action-memory-allow-eval-rows'], false)
+            ? new Set()
+            : new Set(examples.keys()),
+          excludeFamilyIds: parseBool(args['action-memory-exclude-eval-families'], false)
+            ? new Set([...examples.values()].map((row) => row.labels?.workflow_family_id).filter(Boolean))
+            : new Set(),
+          sourceKind: 'trajectory-jsonl',
+          model: {
+            provider: args['source-provider'] || '',
+            modelId: args['source-model'] || '',
+            toolFormat: args['source-tool-format'] || '',
+          },
+        });
+      } else {
+        actionMemoryStoreInfo = { dbPath: storePaths.dbPath, artifactsDir: storePaths.artifactsDir, recorded: 0, skipped: 0 };
+      }
+    }
+
+    const results = [];
+    for (const baseline of baselineRows.slice(0, limit)) {
+      const example = examples.get(baseline.id);
+      if (!example) continue;
+      const target = targetToolCallFromExample(example);
+      if (!target) continue;
+      let prediction = baseline.prediction
+        ? { name: baseline.prediction.tool || baseline.prediction.name, input: baseline.prediction.input || {} }
+        : null;
+      const raw = {
+        rawText: baseline.rawText || '',
+        content: baseline.rawText || '',
+        toolCalls: prediction ? [prediction] : [],
+      };
+      if (runShellCommandSelector !== 'off') {
+        const selected = applyRunShellCommandSelection(example, prediction, {
+          maxCandidates: runShellMaxCandidates,
+          actionMemoryStore: runShellSelectionUsesStore ? actionMemoryStore : null,
+        });
+        prediction = selected.prediction;
+        raw.runShellCommandSelection = selected.selection;
+        raw.runShellCommandCandidates = selected.candidates;
+        raw.runShellCommandOracle = target.name === 'run_shell'
+          ? scoreRunShellCommandCandidates(target.args?.command || '', selected.candidates, selected.selection)
+          : null;
+      }
+      if (actionMemorySelector === 'heuristic' || actionMemorySelectionUsesStore) {
+        const selected = applyTrajectoryActionSelection(example, prediction, {
+          memory: actionMemory,
+          actionMemoryStore: actionMemorySelectionUsesStore ? actionMemoryStore : null,
+          rawText: raw.rawText,
+          maxCandidates: actionMemoryMaxCandidates,
+          minScore: actionMemoryMinScore,
+        });
+        prediction = selected.prediction;
+        raw.actionMemorySelection = selected.selection;
+        raw.actionMemoryCandidates = selected.candidates;
+        raw.actionMemoryOracle = scoreTrajectoryActionCandidates(target, selected.candidates, selected.selection);
+      }
+      const score = scoreReplayPrediction({ expected: target, prediction });
+      results.push({
+        id: example.id,
+        lane: example.labels?.replay_eval_lane || example.labels?.replay_lane || baseline.lane || null,
+        workflowFamilyId: example.labels?.workflow_family_id || null,
+        expected: baseline.expected || {
+          tool: target.name,
+          argKeys: Object.keys(target.args || {}).sort(),
+          argsHash: stableStringify(target.args || {}),
+        },
+        baselinePrediction: baseline.prediction || null,
+        prediction: prediction ? { tool: prediction.name, input: prediction.input || {} } : null,
+        runShellCommandSelection: raw.runShellCommandSelection || null,
+        runShellCommandOracle: raw.runShellCommandOracle || null,
+        runShellCommandCandidateCount: raw.runShellCommandCandidates?.length || 0,
+        actionMemorySelection: raw.actionMemorySelection || null,
+        actionMemoryOracle: raw.actionMemoryOracle || null,
+        actionMemoryCandidateCount: raw.actionMemoryCandidates?.length || 0,
+        rawText: raw.rawText ? String(raw.rawText).slice(0, 1200) : '',
+        rawDiagnostics: summarizeRawGeneration(raw.rawText || ''),
+        parsedToolCallCount: prediction ? 1 : 0,
+        score,
+        baselineScore: baseline.score || null,
+        error: null,
+        baselineError: baseline.error || null,
+        latencyMs: 0,
+        usage: null,
+      });
+    }
+    const summary = summarizeReplayEval(results);
+    const actionMemoryReport = useActionMemoryStore
+      ? summarizeActionMemoryReplayEval(results, {
+          allowSameRowCopies: parseBool(args['action-memory-allow-eval-rows'], false),
+        })
+      : null;
+    fs.mkdirSync(outputDir, { recursive: true });
+    const resultPath = path.join(outputDir, 'replay-eval-results.jsonl');
+    const summaryPath = path.join(outputDir, 'replay-eval-summary.json');
+    writeJsonl(resultPath, results);
+    fs.writeFileSync(summaryPath, JSON.stringify({
+      generatedAt: new Date().toISOString(),
+      mode: 'offline-result-replay',
+      evalFile,
+      resultsFile,
+      runShellCommandSelector,
+      runShellMaxCandidates,
+      actionMemorySelector,
+      actionMemoryFiles,
+      actionMemoryCandidateCount: actionMemory.length,
+      actionMemoryStore: actionMemoryStoreInfo,
+      actionMemoryMaxCandidates,
+      actionMemoryMinScore,
+      limit,
+      baselineSummary: summarizeReplayEval(baselineRows.map((row) => ({ ...row, score: row.score || {} }))),
+      summary,
+      actionMemoryReport,
+    }, null, 2) + '\n', 'utf8');
+    return { outputDir, evalFile, resultsFile, resultPath, summaryPath, summary, actionMemoryStore: actionMemoryStoreInfo };
+  } finally {
+    if (actionMemoryStore) actionMemoryStore.close();
+  }
+}
+
+function actionMemoryFilePaths(args = {}, evalFile = '') {
+  const explicit = [
+    ...parseList(args['action-memory-file']),
+    ...parseList(args['action-memory-files']),
+  ].map((file) => path.resolve(file));
+  if (explicit.length) return explicit;
+  return defaultActionMemoryFilesForEval(evalFile);
+}
+
+function actionMemoryStorePaths(args = {}, outputDir = '') {
+  const dbPath = args['action-memory-db']
+    ? path.resolve(args['action-memory-db'])
+    : (outputDir
+        ? path.join(path.resolve(outputDir), 'action-memory', 'action-memory.db')
+        : defaultActionMemoryDbPath());
+  return {
+    dbPath,
+    artifactsDir: args['action-memory-artifacts-dir']
+      ? path.resolve(args['action-memory-artifacts-dir'])
+      : path.join(path.dirname(dbPath), 'artifacts'),
+  };
+}
+
+function recordTrajectoryRowsToActionMemoryStore(filePaths = [], {
+  store,
+  excludeIds = new Set(),
+  excludeFamilyIds = new Set(),
+  sourceKind = 'trajectory-jsonl',
+  model = {},
+  maxRows = 20000,
+} = {}) {
+  if (!store) throw new Error('recordTrajectoryRowsToActionMemoryStore requires store');
+  const files = Array.isArray(filePaths) ? filePaths : [filePaths];
+  let scanned = 0;
+  let recorded = 0;
+  let skipped = 0;
+  const byTool = {};
+  for (const filePath of files.map((file) => String(file || '')).filter(Boolean)) {
+    if (!fs.existsSync(filePath)) {
+      skipped += 1;
+      continue;
+    }
+    for (const line of fs.readFileSync(filePath, 'utf8').split('\n')) {
+      if (scanned >= maxRows) break;
+      if (!line.trim()) continue;
+      scanned += 1;
+      let row = null;
+      try { row = normalizeReplayEvalExample(JSON.parse(line)); } catch {}
+      if (!row || excludeIds.has(row.id) || excludeFamilyIds.has(row.labels?.workflow_family_id)) {
+        skipped += 1;
+        continue;
+      }
+      const target = targetToolCallFromExample(row);
+      if (!target?.name) {
+        skipped += 1;
+        continue;
+      }
+      store.recordActionMemoryEntry({
+        context: actionMemoryContextFromReplayExample(row, target),
+        action: { toolName: target.name, input: target.args || {} },
+        outcome: {
+          status: actionMemoryOutcomeStatus(row),
+          confidence: actionMemoryConfidence(row),
+          verified: true,
+        },
+        source: {
+          kind: sourceKind,
+          rowId: row.id,
+          sessionId: row.leakage?.source_session_id || row.labels?.source_session_id || '',
+          toolCallId: targetToolCallIdFromExample(row, target.messageIndex),
+          timestamp: row.timestamp || row.created_at || '',
+          metadata: { sourceFile: path.resolve(filePath), source: row.source || '' },
+        },
+        model,
+        metadata: {
+          datasetVersion: row.dataset_version || '',
+          split: row.split || '',
+          replayLane: row.labels?.replay_eval_lane || row.labels?.replay_lane || '',
+          quality: row.quality ?? null,
+        },
+      });
+      recorded += 1;
+      byTool[target.name] = (byTool[target.name] || 0) + 1;
+    }
+  }
+  return {
+    dbPath: store.dbPath,
+    artifactsDir: store.artifactsDir,
+    files: files.map((file) => path.resolve(file)),
+    scanned,
+    recorded,
+    skipped,
+    byTool,
+    excludeIds: excludeIds.size,
+    excludeFamilyIds: excludeFamilyIds.size,
+  };
+}
+
+function actionMemoryContextFromReplayExample(example = {}, target = {}) {
+  const userContent = (example.messages || [])
+    .filter((message) => message.role === 'user')
+    .map((message) => message.content || '')
+    .join('\n');
+  return {
+    familyId: example.labels?.workflow_family_id || null,
+    repo: example.labels?.workflow_repo || null,
+    intent: example.labels?.workflow_intent || null,
+    intendedTool: target.name || example.labels?.tool_name || null,
+    taskText: userContent.split(/\nCurrent Wall-E state:/)[0].replace(/^Task:\s*/i, '').trim(),
+    sequence: firstLineValue(userContent, 'tool sequence') || null,
+    lastTool: firstLineValue(userContent, 'last tool')?.split(/\s+/)[0] || null,
+    toolCatalogId: example.tool_catalog || null,
+    metadata: {
+      replayLane: example.labels?.replay_eval_lane || example.labels?.replay_lane || '',
+    },
+  };
+}
+
+function targetToolCallIdFromExample(example = {}, messageIndex = -1) {
+  const message = example.messages?.[messageIndex];
+  const call = message?.tool_calls?.[0] || null;
+  return call?.id || call?.call_id || '';
+}
+
+function actionMemoryOutcomeStatus(example = {}) {
+  if (example.labels?.verification_passed || example.labels?.has_passing_verification) return 'verified_passed';
+  return 'succeeded';
+}
+
+function actionMemoryConfidence(example = {}) {
+  const quality = Number(example.quality);
+  if (Number.isFinite(quality)) return Math.max(0.1, Math.min(0.99, quality));
+  return 0.85;
+}
+
+function firstLineValue(text = '', label = '') {
+  const re = new RegExp(`^\\s*-\\s*${String(label).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:\\s*(.+)$`, 'im');
+  const match = String(text || '').match(re);
+  return match ? match[1].trim() : null;
+}
+
+function readJsonl(filePath) {
+  return fs.readFileSync(filePath, 'utf8')
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => JSON.parse(line));
+}
+
+function normalizeReplayEvalExample(row) {
+  try {
+    const normalized = require('../training/tool-sft-dataset').normalizeCanonicalExample(row);
+    return targetToolCallFromExample(normalized) ? normalized : null;
+  } catch {
+    return null;
+  }
+}
+
+function scoreReplayPrediction({ expected, prediction }) {
+  if (!prediction) {
+    return {
+      pass: false,
+      toolNameMatch: false,
+      requiredArgsPresent: false,
+      targetMatch: false,
+      exactArgsMatch: false,
+      argShapeScore: 0,
+    };
+  }
+  const expectedArgs = expected.args || {};
+  const predictedArgs = prediction.input || {};
+  const toolNameMatch = prediction.name === expected.name;
+  const requiredKeys = requiredArgKeysForTool(expected.name);
+  const requiredArgsPresent = requiredKeys.every((key) => predictedArgs[key] !== undefined && predictedArgs[key] !== '');
+  const targetMatch = targetArgMatches(expected.name, expectedArgs, predictedArgs);
+  const exactArgsMatch = stableStringify(expectedArgs) === stableStringify(predictedArgs);
+  const presentKeys = requiredKeys.filter((key) => predictedArgs[key] !== undefined && predictedArgs[key] !== '').length;
+  const argShapeScore = requiredKeys.length ? presentKeys / requiredKeys.length : 1;
+  return {
+    pass: toolNameMatch && requiredArgsPresent && targetMatch,
+    toolNameMatch,
+    requiredArgsPresent,
+    targetMatch,
+    exactArgsMatch,
+    argShapeScore: Number(argShapeScore.toFixed(4)),
+  };
+}
+
+function requiredArgKeysForTool(toolName) {
+  if (toolName === 'read_file') return ['file_path'];
+  if (toolName === 'list_directory') return ['directory'];
+  if (toolName === 'glob') return ['pattern'];
+  if (toolName === 'grep_files') return ['pattern'];
+  if (toolName === 'edit_file') return ['file_path', 'old_string', 'new_string'];
+  if (toolName === 'write_file') return ['file_path', 'content'];
+  if (toolName === 'apply_patch') return ['patch_text'];
+  if (toolName === 'run_shell') return ['command'];
+  return [];
+}
+
+function targetArgMatches(toolName, expectedArgs = {}, predictedArgs = {}) {
+  if (toolName === 'read_file' || toolName === 'edit_file' || toolName === 'write_file') {
+    if (!samePathish(expectedArgs.file_path, predictedArgs.file_path)) return false;
+    if (toolName === 'edit_file') {
+      return Boolean(predictedArgs.old_string && predictedArgs.new_string && predictedArgs.old_string !== predictedArgs.new_string);
+    }
+    return true;
+  }
+  if (toolName === 'list_directory') return samePathish(expectedArgs.directory, predictedArgs.directory);
+  if (toolName === 'run_shell') return commandsEquivalentForMatch(expectedArgs.command, predictedArgs.command);
+  if (toolName === 'glob') return String(expectedArgs.pattern || '') === String(predictedArgs.pattern || '');
+  if (toolName === 'grep_files') return String(expectedArgs.pattern || '') === String(predictedArgs.pattern || '');
+  if (toolName === 'apply_patch') return Boolean(predictedArgs.patch_text);
+  return true;
+}
+
+function samePathish(a, b) {
+  const left = normalizePathish(a);
+  const right = normalizePathish(b);
+  return Boolean(left && right && (left === right || left.endsWith(`/${right}`) || right.endsWith(`/${left}`)));
+}
+
+function normalizePathish(value) {
+  return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '') || '.';
+}
+
+function normalizeCommandForMatch(value) {
+  return String(value || '').replace(/\s+/g, ' ').trim();
+}
+
+function commandsEquivalentForMatch(expected, predicted) {
+  const left = normalizeCommandForMatch(expected);
+  const right = normalizeCommandForMatch(predicted);
+  if (!left || !right) return false;
+  if (left === right) return true;
+  const leftClass = commandIntentClass(left);
+  const rightClass = commandIntentClass(right);
+  return Boolean(leftClass && rightClass && leftClass === rightClass);
+}
+
+function commandIntentClass(command) {
+  const value = normalizeCommandForMatch(command).toLowerCase();
+  if (!value) return null;
+  if (/^npm (run )?test\b/.test(value)) return 'npm-test';
+  if (/^pnpm (run )?test\b/.test(value)) return 'pnpm-test';
+  if (/^yarn (run )?test\b/.test(value)) return 'yarn-test';
+  if (/^node --test\b/.test(value)) return 'node-test';
+  if (/^node --check\b/.test(value)) return 'node-check';
+  if (/^(python|python3) -m pytest\b|^pytest\b/.test(value)) return 'pytest';
+  if (/playwright.*test|test.*playwright/.test(value)) return 'playwright-test';
+  if (/^git diff --check\b/.test(value)) return 'git-diff-check';
+  if (/^git status\b/.test(value)) return 'git-status';
+  return null;
+}
+
+function summarizeRawGeneration(text = '') {
+  const raw = String(text || '');
+  const trimmedStart = raw.trimStart();
+  const firstNonWhitespace = trimmedStart[0] || '';
+  const firstJsonIndex = raw.indexOf('{');
+  return {
+    firstNonWhitespace,
+    jsonPrefixOk: firstNonWhitespace === '{',
+    thoughtPrefix: /^<\|channel\>thought|^<\|start\|>thought/i.test(trimmedStart),
+    containsJsonObjectStart: firstJsonIndex >= 0,
+    nonWhitespaceBeforeJson: firstJsonIndex > 0 && raw.slice(0, firstJsonIndex).trim().length > 0,
+  };
+}
+
+function summarizeReplayEval(results = []) {
+  const total = results.length;
+  const count = (fn) => results.filter(fn).length;
+  const decisive = results.filter((row) => isDecisiveExpectedTool(row.expected?.tool));
+  const rate = (n) => total ? Number((n / total).toFixed(4)) : 0;
+  const jsonPrefixCount = count((row) => row.rawDiagnostics?.jsonPrefixOk);
+  const thoughtPrefixCount = count((row) => row.rawDiagnostics?.thoughtPrefix);
+  const nonWhitespaceBeforeJsonCount = count((row) => row.rawDiagnostics?.nonWhitespaceBeforeJson);
+  return {
+    total,
+    pass: count((row) => row.score.pass),
+    passRate: rate(count((row) => row.score.pass)),
+    toolNameMatchRate: rate(count((row) => row.score.toolNameMatch)),
+    requiredArgsPresentRate: rate(count((row) => row.score.requiredArgsPresent)),
+    targetMatchRate: rate(count((row) => row.score.targetMatch)),
+    exactArgsMatchRate: rate(count((row) => row.score.exactArgsMatch)),
+    errorCount: count((row) => row.error),
+    invalidOrProseOnlyCount: count((row) => !row.prediction),
+    invalidOrProseOnlyRate: rate(count((row) => !row.prediction)),
+    thoughtChannelCount: count((row) => /<\|channel\>thought|<\|start\|>thought/i.test(row.rawText || '')),
+    jsonPrefixCount,
+    jsonPrefixRate: rate(jsonPrefixCount),
+    thoughtPrefixCount,
+    thoughtPrefixRate: rate(thoughtPrefixCount),
+    nonWhitespaceBeforeJsonCount,
+    nonWhitespaceBeforeJsonRate: rate(nonWhitespaceBeforeJsonCount),
+    decisiveAction: summarizeReplaySubset(decisive),
+    byTool: summarizeReplayBy(results, (row) => row.expected.tool),
+    byActionClass: summarizeReplayBy(results, (row) => expectedActionClass(row.expected)),
+    byLane: summarizeReplayBy(results, (row) => row.lane || 'unknown'),
+  };
+}
+
+function summarizeReplaySubset(rows = []) {
+  const total = rows.length;
+  const pass = rows.filter((row) => row.score.pass).length;
+  return {
+    total,
+    pass,
+    passRate: total ? Number((pass / total).toFixed(4)) : 0,
+    toolNameMatchRate: total ? Number((rows.filter((row) => row.score.toolNameMatch).length / total).toFixed(4)) : 0,
+    invalidOrProseOnlyRate: total ? Number((rows.filter((row) => !row.prediction).length / total).toFixed(4)) : 0,
+  };
+}
+
+function isDecisiveExpectedTool(toolName) {
+  return /^(edit_file|write_file|apply_patch|run_shell)$/.test(toolName || '');
+}
+
+function expectedActionClass(expected = {}) {
+  if (expected.tool === 'apply_patch') return 'patch';
+  if (expected.tool === 'edit_file' || expected.tool === 'write_file') return 'edit';
+  if (expected.tool === 'run_shell') return 'verification';
+  if (/^(read_file|list_directory|glob|grep_files|lsp_)/.test(expected.tool || '')) return 'inspect';
+  return expected.tool || 'unknown';
+}
+
+function summarizeReplayBy(results, keyFn) {
+  const grouped = new Map();
+  for (const row of results) {
+    const key = keyFn(row) || 'unknown';
+    if (!grouped.has(key)) grouped.set(key, []);
+    grouped.get(key).push(row);
+  }
+  const out = {};
+  for (const [key, rows] of grouped.entries()) {
+    out[key] = {
+      total: rows.length,
+      pass: rows.filter((row) => row.score.pass).length,
+      toolNameMatch: rows.filter((row) => row.score.toolNameMatch).length,
+    };
+  }
+  return out;
+}
+
+function validateDataset(args) {
+  const outputDir = path.resolve(args['output-dir']);
+  const datasetDir = path.join(outputDir, 'dataset');
+  const manifestPath = path.join(datasetDir, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) throw new Error(`Missing manifest: ${manifestPath}`);
+  validateDatasetFiles(datasetDir);
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  return { outputDir, datasetDir, manifest };
+}
+
+function trainingPaths(args) {
+  const outputDir = path.resolve(args['output-dir']);
+  const datasetDir = path.join(outputDir, 'dataset');
+  const adapterPath = path.resolve(args['adapter-path'] || path.join(outputDir, 'adapters', args.alias || 'gemma-e4b-tooluse-v1'));
+  return { outputDir, datasetDir, adapterPath };
+}
+
+function buildTrainingOpts(args) {
+  const { outputDir, datasetDir, adapterPath } = trainingPaths(args);
+  if (!args['base-model']) throw new Error('--base-model is required');
+  const hyperparams = {};
+  if (args.iters) hyperparams.iters = Number(args.iters);
+  if (args.rank) hyperparams.rank = Number(args.rank);
+  if (args.alpha) hyperparams.alpha = Number(args.alpha);
+  if (args['batch-size']) hyperparams.batchSize = Number(args['batch-size']);
+  if (args['grad-accumulation-steps']) hyperparams.gradAccumulationSteps = Number(args['grad-accumulation-steps']);
+  if (args['num-layers']) hyperparams.numLayers = Number(args['num-layers']);
+  if (args['max-seq-length']) hyperparams.maxSeqLength = Number(args['max-seq-length']);
+  if (args['learning-rate']) hyperparams.learningRate = Number(args['learning-rate']);
+  if (args['val-batches']) hyperparams.valBatches = Number(args['val-batches']);
+  if (args['steps-per-report']) hyperparams.stepsPerReport = Number(args['steps-per-report']);
+  if (args['steps-per-eval']) hyperparams.stepsPerEval = Number(args['steps-per-eval']);
+  if (args['save-every']) hyperparams.saveEvery = Number(args['save-every']);
+  if (args.optimizer) hyperparams.optimizer = args.optimizer;
+  if (args['grad-checkpoint']) hyperparams.gradCheckpoint = parseBool(args['grad-checkpoint'], true);
+  return {
+    outputDir,
+    dataDir: datasetDir,
+    baseModel: path.resolve(args['base-model']),
+    adapterPath,
+    resumeAdapterFile: args['resume-adapter-file'] ? path.resolve(args['resume-adapter-file']) : null,
+    hyperparams,
+  };
+}
+
+async function dryRunTrain(args) {
+  const opts = buildTrainingOpts(args);
+  validateDatasetFiles(opts.dataDir);
+  const { config, outputPath } = writeMlxLoraConfig({ ...opts, outputPath: path.join(opts.outputDir, 'configs', 'mlx-lora-config.json') });
+  const command = buildMlxLoraCommand({ config });
+  return { outputDir: opts.outputDir, configPath: outputPath, command };
+}
+
+async function train(args) {
+  const opts = buildTrainingOpts(args);
+  validateDatasetFiles(opts.dataDir);
+  const { config, outputPath } = writeMlxLoraConfig({ ...opts, outputPath: path.join(opts.outputDir, 'configs', 'mlx-lora-config.json') });
+  const result = await runMlxLoraTraining({ config });
+  const manifest = buildTrainingManifest({ config });
+  fs.writeFileSync(path.join(opts.outputDir, 'training-manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+  writeModelCard({ outputDir: opts.outputDir, manifest });
+  return { outputDir: opts.outputDir, configPath: outputPath, result, manifest };
+}
+
+function registerCandidate(args) {
+  const outputDir = path.resolve(args['output-dir']);
+  const manifestPath = path.join(outputDir, 'training-manifest.json');
+  const manifest = fs.existsSync(manifestPath)
+    ? JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+    : buildTrainingManifest(buildTrainingOpts(args));
+  return writeCandidateMetadata({
+    outputDir,
+    alias: args.alias || 'gemma-e4b-tooluse-v1',
+    provider: args.provider || 'mlx',
+    manifest,
+  });
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.command === 'help' || args.help) {
+    printHelp();
+    return null;
+  }
+  let result;
+  if (args.command === 'export-dataset') result = await exportDataset(args);
+  else if (args.command === 'export-replay-slice-dataset') result = exportReplaySliceDataset(args);
+  else if (args.command === 'audit-real-trajectories') result = auditRealTrajectories(args);
+  else if (args.command === 'audit-decision-points') result = auditDecisionPointsCommand(args);
+  else if (args.command === 'audit-workflows') result = auditWorkflowsCommand(args);
+  else if (args.command === 'eval-replay-dataset') result = await evalReplayDataset(args);
+  else if (args.command === 'eval-replay-results') result = evalReplayResults(args);
+  else if (args.command === 'validate-dataset') result = validateDataset(args);
+  else if (args.command === 'dry-run-train') result = await dryRunTrain(args);
+  else if (args.command === 'train') result = await train(args);
+  else if (args.command === 'register-candidate') result = registerCandidate(args);
+  else throw new Error(`Unknown command: ${args.command}`);
+  console.log(JSON.stringify(result, null, 2));
+  return result;
+}
+
+function printHelp() {
+  console.log(`Usage:
+  node wall-e/bin/train-gemma-e4b-tooluse.js export-dataset --source synthetic --output-dir /tmp/run
+  node wall-e/bin/train-gemma-e4b-tooluse.js export-dataset --source sessions --root /path/to/transcripts --repo /path/to/repo --since-days 14 --scan-limit 500 --output-dir /tmp/run
+  node wall-e/bin/train-gemma-e4b-tooluse.js audit-real-trajectories --repo /path/to/repo --since-days 120 --scan-limit 500 --output-dir /tmp/audit
+  node wall-e/bin/train-gemma-e4b-tooluse.js audit-decision-points --repo /path/to/repo --since-days 120 --scan-limit 500 --output-dir /tmp/decision-audit
+  node wall-e/bin/train-gemma-e4b-tooluse.js audit-workflows --repo /path/to/repo --since-days 180 --scan-limit 1000 --output-dir /tmp/workflows
+  node wall-e/bin/train-gemma-e4b-tooluse.js export-dataset --source real-sessions --repo /path/to/repo --audit-dir /tmp/audit --output-dir /tmp/run
+  node wall-e/bin/train-gemma-e4b-tooluse.js export-dataset --source personal-replay --since-days 180 --scan-limit 1000 --output-dir /tmp/run
+	  node wall-e/bin/train-gemma-e4b-tooluse.js export-dataset --source decisive-actions --since-days 180 --scan-limit 1000 --format mlx-provider --output-dir /tmp/run
+	  node wall-e/bin/train-gemma-e4b-tooluse.js export-replay-slice-dataset --eval-file /tmp/run/replay-eval/seen-exact.jsonl --results-file /tmp/baseline/replay-eval-results.jsonl --slice-mode parser-or-wrong-tool --repeats 8 --output-dir /tmp/replay-slice
+  node wall-e/bin/train-gemma-e4b-tooluse.js eval-replay-dataset --dataset-output-dir /tmp/run --lane seen-exact --model gemma4:e4b-it-qat
+  node wall-e/bin/train-gemma-e4b-tooluse.js validate-dataset --output-dir /tmp/run
+  node wall-e/bin/train-gemma-e4b-tooluse.js dry-run-train --output-dir /tmp/run --base-model /path/to/base
+  node wall-e/bin/train-gemma-e4b-tooluse.js train --output-dir /tmp/run --base-model /path/to/base --iters 600 --max-seq-length 8192
+  node wall-e/bin/train-gemma-e4b-tooluse.js register-candidate --output-dir /tmp/run --alias gemma-e4b-tooluse-v1
+
+Dataset export options:
+	  --source synthetic|sessions|real-sessions|personal-replay|decisive-actions|all
+  --trace-files file.jsonl[,file.json]
+  --root path or --roots path1,path2
+  --repo path
+  --transcript-source all|claude|codex|walle
+  --since-days n
+  --scan-limit n
+  --max-examples n
+  --real-trajectories true|false
+  --include-ctm true|false
+  --include-filesystem true|false
+  --per-source-limit claude=200,codex=200,walle=200
+  --per-tool-limit read_file=400,grep_files=200,edit_file=500,apply_patch=160,run_shell=220
+  --recover-git true|false
+  --git-recovery-window-minutes n
+  --allow-weak-git-recovery true|false
+  --min-gold-trajectories n
+  --min-silver-trajectories n
+  --min-gold-or-silver-trajectories n
+  --min-passing-verification n
+  --min-real-examples n
+  --fail-on-quality-gate true|false
+  --ctm-db path
+  --audit-dir path
+  --decision-audit-dir path
+  --workflow-audit-dir path
+  --include-paths true|false
+  --include-messages true|false
+  --min-decision-points n
+  --min-guard-recovery n
+  --max-same-inspection-after-guard n
+	  --include-train-variants true|false
+	  --personal-variant-repeats n
+	  --decisive-actions true|false
+	  --decisive-exact-repeats n
+	  --require-decisive-tool-result-history true|false
+	  --max-seen-exact-eval n
+	  --max-seen-variant-eval n
+  --min-seen-workflow-families n
+  --min-repeated-workflow-families n
+  --min-seen-replay-rows n
+  --min-seen-variant-rows n
+	  --min-edit-verification-rows n
+	  --min-first-action-rows n
+	  --min-decisive-action-rows n
+	  --min-decisive-exact-rows n
+	  --min-decisive-edit-rows n
+	  --min-decisive-verification-rows n
+	  --min-decisive-real-result-rows n
+	  --min-json-only-contract-rows n
+	  --min-state-summary-rows n
+	  --include-tiers gold,silver
+	  --include-tools tool1,tool2
+	  --max-result-chars n
+	  --max-file-mb n
+	  --max-rendered-chars n
+	  --min-rendered-length-kept-rows n
+	  --quality-threshold n
+  --targeted-repeats n
+  --format mlx-tools|mlx-provider|mlx-provider-bare|mlx-provider-state-bare|trl-tools|text
+  --state-summary true|false
+  --target-mode full|tool-choice
+  --results-file /tmp/baseline/replay-eval-results.jsonl
+  --slice-mode all|failures|parser-failures|wrong-tool|parser-or-wrong-tool
+  --require-edits true|false
+  --require-coding-intent true|false
+
+Training options:
+  --iters n
+  --rank n
+  --alpha n
+  --batch-size n
+  --grad-accumulation-steps n
+  --num-layers n
+  --max-seq-length n
+  --learning-rate n
+  --val-batches n
+  --steps-per-report n
+  --steps-per-eval n
+  --save-every n
+  --optimizer adam|adamw|muon|sgd|adafactor
+  --grad-checkpoint true|false
+  --resume-adapter-file path
+
+Replay eval options:
+  --dataset-output-dir path
+  --eval-file path
+  --lane seen-exact|seen-variant
+  --model name
+  --adapter-path path
+  --tool-call-format fenced|bare-json
+  --force-tool-json-prefix true|false
+  --run-shell-command-selector off|heuristic|store
+  --run-shell-max-candidates n
+  --action-memory-selector off|heuristic|store
+  --action-memory-db path
+  --action-memory-build-from-files true|false
+  --action-memory-allow-eval-rows true|false
+  --action-memory-exclude-eval-families true|false
+  --limit n
+  --max-tokens n
+  --inference-timeout-ms n
+`);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err.stack || err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  parseArgs,
+  exportDataset,
+  exportReplaySliceDataset,
+  validateDataset,
+  dryRunTrain,
+  train,
+  registerCandidate,
+  auditRealTrajectories,
+  auditDecisionPointsCommand,
+  auditWorkflowsCommand,
+  evalReplayDataset,
+  buildRealDatasetQualityGate,
+  buildDecisionPointQualityGate,
+  buildDecisiveActionDataGate,
+  buildRenderedLengthGate,
+  buildPersonalReplayDataGate,
+  applyPerToolLimit,
+  applyMaxRenderedChars,
+  actionMemoryContextFromReplayExample,
+  actionMemoryStorePaths,
+  recordTrajectoryRowsToActionMemoryStore,
+  scoreReplayPrediction,
+  parseBool,
+  parsePerSourceLimit,
+  parsePerToolLimit,
+  stableStringify,
+  main,
+};