atris 3.37.1 → 3.40.0

package/commands/recover.js

@@ -0,0 +1,340 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { reasonClass, HUMAN_BLOCKING_REASONS } = require('../lib/self-drive');
+const { missionLockRecords } = require('../lib/loop-doctor');
+const {
+  loadMissionMap,
+  acquireMissionLock,
+  releaseMissionLock,
+} = require('./mission');
+
+const RECOVERY_CATALOG = [
+  {
+    id: 'max-ticks-reached',
+    matches: (reason) => reason === 'max-ticks-reached',
+    happened: 'the run used its tick allowance before the mission finished',
+    apply: 'resume',
+  },
+  {
+    id: 'verifier-failed',
+    matches: (reason) => reason === 'verifier-failed' || reason === 'verifier_failed',
+    happened: 'the mission verifier failed',
+    apply: 'verifier',
+  },
+  {
+    id: 'repeated-error:claude-error',
+    matches: (reason) => reason === 'repeated-error:claude-error' || reason.startsWith('repeated-error:'),
+    happened: 'the worker returned the same error twice',
+    apply: null,
+  },
+  {
+    id: 'aborted-during-claude',
+    matches: (reason) => reason === 'aborted-during-claude',
+    happened: 'the worker was interrupted during its tick',
+    apply: 'resume',
+  },
+  {
+    id: 'aborted',
+    matches: (reason) => reason === 'aborted',
+    happened: 'the mission run was interrupted',
+    apply: 'resume',
+  },
+  {
+    id: 'stuck-repeating',
+    matches: (reason) => ['stuck-repeating', 'repeated-pause-reason', 'repeated_pause_reason'].includes(reason),
+    happened: 'the worker kept returning the same pause or summary',
+    apply: 'resume',
+  },
+  {
+    id: 'lock-busy',
+    matches: (reason) => ['lock-busy', 'stale-mission-lock', 'stale_mission_lock'].includes(reason),
+    happened: 'a mission tick lock prevented another tick from starting',
+    apply: null,
+  },
+  {
+    id: 'auth-required',
+    matches: (reason) => reason === 'auth-required',
+    happened: 'the runner needs an operator login',
+    apply: null,
+  },
+  {
+    id: 'model-unavailable',
+    matches: (reason) => reason === 'model-unavailable',
+    happened: 'the configured model is unavailable',
+    apply: null,
+  },
+  {
+    id: 'rate-limit-exceeded-wall',
+    matches: (reason) => reason === 'rate-limit-exceeded-wall',
+    happened: 'the rate-limit reset falls outside this run window',
+    apply: null,
+  },
+];
+
+function classifyRecovery(value) {
+  const reason = reasonClass(value);
+  const entry = RECOVERY_CATALOG.find((candidate) => candidate.matches(reason));
+  if (entry) {
+    return {
+      catalog_entry: entry.id,
+      reason,
+      happened: entry.happened,
+      apply: entry.apply,
+      human_blocking: HUMAN_BLOCKING_REASONS.has(reason),
+    };
+  }
+  return {
+    catalog_entry: 'unknown',
+    reason,
+    happened: `the mission stopped for "${reason}"`,
+    apply: null,
+    human_blocking: HUMAN_BLOCKING_REASONS.has(reason),
+  };
+}
+
+function missionStopReason(mission) {
+  if (mission.stop_reason) return mission.stop_reason;
+  if (mission.pause_reason) return mission.pause_reason;
+  if (mission.status === 'blocked' && mission.verifier_result?.passed === false) return 'verifier-failed';
+  return mission.last_tick_reason || mission.status || 'blocked';
+}
+
+function manualRecoveryCommand(row) {
+  const id = row.mission_id;
+  switch (row.catalog_entry) {
+    case 'auth-required':
+      return 'atris login';
+    case 'model-unavailable':
+      return `atris mission set-runner ${id} auto`;
+    case 'rate-limit-exceeded-wall':
+      return `atris mission run ${id}`;
+    case 'repeated-error:claude-error':
+      return `atris mission run ${id}`;
+    case 'lock-busy':
+      return `atris mission status ${id} --json`;
+    default:
+      return `atris mission status ${id} --json`;
+  }
+}
+
+function recoveryCommand(row) {
+  if (row.apply === 'stale-lock') return `atris recover ${row.mission_id} --apply`;
+  if (row.human_blocking || !row.apply) return manualRecoveryCommand(row);
+  return `atris recover ${row.mission_id} --apply`;
+}
+
+function missionRows(root) {
+  return [...loadMissionMap(root).values()]
+    .filter((mission) => ['blocked', 'paused'].includes(String(mission.status || '').toLowerCase()))
+    .map((mission) => {
+      const classified = classifyRecovery(missionStopReason(mission));
+      const verifier = String(mission.verifier || mission.effective_verifier || '').trim();
+      const missingVerifier = classified.apply === 'verifier' && !verifier;
+      const hasHumanAsk = Array.isArray(mission.human_asks) && mission.human_asks.length > 0;
+      const operatorRequired = missingVerifier || hasHumanAsk;
+      return {
+        mission_id: mission.id,
+        mission: mission.objective || mission.id,
+        status: mission.status,
+        receipt_path: mission.receipt_path || null,
+        next_action: mission.next_action || null,
+        verifier: verifier || null,
+        ...classified,
+        ...(operatorRequired ? {
+          apply: null,
+          operator_required: true,
+          happened: hasHumanAsk
+            ? `${classified.happened}, and the mission has a human ask`
+            : `${classified.happened}, but no verifier command is configured`,
+        } : {}),
+      };
+    });
+}
+
+function lockRows(root) {
+  return missionLockRecords(root).map((lock) => {
+    const match = String(lock.lock || '').match(/^mission-(.+)[.]lock$/);
+    const missionId = match ? match[1] : String(lock.lock || '').replace(/[.]lock$/, '');
+    const classified = classifyRecovery('stale_mission_lock');
+    const stale = lock.stale === true;
+    return {
+      mission_id: missionId,
+      mission: missionId,
+      status: 'lock busy',
+      receipt_path: null,
+      next_action: null,
+      ...classified,
+      happened: stale
+        ? classified.happened
+        : `the mission tick lock is held by live pid ${lock.pid}`,
+      apply: stale ? 'stale-lock' : null,
+      operator_required: !stale,
+      stale_lock: {
+        file: lock.lock,
+        pid: lock.pid,
+        reason: lock.reason,
+      },
+    };
+  });
+}
+
+function selectRows(root, ref = '') {
+  const selected = [...lockRows(root), ...missionRows(root)];
+  if (!ref) return selected;
+  const needle = String(ref).trim();
+  return selected.filter((row) => row.mission_id === needle || row.mission_id.includes(needle));
+}
+
+function runMissionTick(root, row, verify) {
+  const cli = path.join(__dirname, '..', 'bin', 'atris.js');
+  const args = [
+    cli,
+    'mission',
+    'tick',
+    row.mission_id,
+    ...(verify ? ['--verify'] : []),
+    '--summary',
+    verify ? 'recovery reran the mission verifier' : 'recovery resumed the paused mission',
+    '--json',
+  ];
+  return spawnSync(process.execPath, args, {
+    cwd: root,
+    encoding: 'utf8',
+    timeout: 120000,
+    env: { ...process.env, ATRIS_SKIP_UPDATE_CHECK: '1' },
+  });
+}
+
+function applyStaleLock(root, row) {
+  const lock = acquireMissionLock(row.mission_id, root);
+  if (!lock.ok) {
+    return {
+      outcome: 'needs operator',
+      detail: `lock is still held by pid ${lock.holder?.pid || '?'}`,
+    };
+  }
+  releaseMissionLock(lock);
+  const lockPath = path.join(root, '.atris', 'state', row.stale_lock.file);
+  return fs.existsSync(lockPath)
+    ? { outcome: 'failed', detail: 'stale lock still exists' }
+    : { outcome: 'recovered', detail: 'cleared the stale mission tick lock' };
+}
+
+function applyMissionRow(root, row) {
+  if (row.human_blocking || row.operator_required) {
+    return { outcome: 'needs operator', detail: row.happened };
+  }
+  if (row.apply === 'stale-lock') return applyStaleLock(root, row);
+  if (!row.apply) {
+    return { outcome: 'not applied', detail: 'the cause must be inspected before another run' };
+  }
+  if (row.apply === 'resume' && row.status !== 'paused') {
+    return { outcome: 'not applied', detail: 'only paused missions are resumed automatically' };
+  }
+  const run = runMissionTick(root, row, row.apply === 'verifier');
+  if (run.error || run.status !== 0) {
+    return {
+      outcome: 'failed',
+      detail: String(run.error?.message || run.stderr || run.stdout || 'mission tick failed').trim(),
+    };
+  }
+  const mission = loadMissionMap(root).get(row.mission_id) || null;
+  if (row.apply === 'verifier' && mission?.verifier_result?.passed !== true) {
+    return {
+      outcome: 'still blocked',
+      detail: 'the verifier still fails',
+      end_state: mission,
+    };
+  }
+  return {
+    outcome: 'recovered',
+    detail: row.apply === 'verifier' ? 'the verifier passed' : 'the mission resumed',
+    end_state: mission,
+  };
+}
+
+function writeRecoveryReceipt(root, results) {
+  const runs = path.join(root, 'atris', 'runs');
+  fs.mkdirSync(runs, { recursive: true });
+  const at = new Date().toISOString();
+  const name = `recover-${at.replace(/[:.]/g, '-')}-${process.pid}.json`;
+  const relative = path.join('atris', 'runs', name);
+  fs.writeFileSync(path.join(root, relative), `${JSON.stringify({
+    schema: 'atris.recovery_receipt.v1',
+    at,
+    applied: true,
+    results: results.map((row) => ({
+      mission_id: row.mission_id,
+      catalog_entry: row.catalog_entry,
+      previous_status: row.status,
+      outcome: row.outcome,
+      detail: row.detail,
+      end_status: row.end_state?.status || row.status,
+      mission_receipt: row.end_state?.receipt_path || row.receipt_path || null,
+      next_action: row.end_state?.next_action || row.next_action || recoveryCommand(row),
+    })),
+  }, null, 2)}\n`);
+  return relative;
+}
+
+function textLines(rows, receiptPath, applying) {
+  if (!rows.length) return ['recovery report', 'no blocked or paused missions found'];
+  const lines = ['recovery report'];
+  for (const row of rows) {
+    const state = row.human_blocking || row.operator_required
+      ? 'needs operator'
+      : (applying ? `${row.outcome}: ${row.detail}` : (row.apply ? 'safe to apply' : 'report only'));
+    lines.push(
+      `${row.mission_id}: ${row.happened}`,
+      `  ${state}; next: ${recoveryCommand(row)}`,
+      `  receipt: ${row.end_state?.receipt_path || row.receipt_path || 'none today'}`,
+    );
+  }
+  if (receiptPath) lines.push(`recovery receipt: ${receiptPath}`);
+  return lines;
+}
+
+function parseArgs(args) {
+  const apply = args.includes('--apply');
+  const json = args.includes('--json');
+  const help = args.includes('--help') || args.includes('-h') || args[0] === 'help';
+  const ref = args.find((arg) => !String(arg).startsWith('-') && arg !== 'help') || '';
+  return { apply, json, help, ref };
+}
+
+function recoverCommand(args = [], options = {}) {
+  const parsed = parseArgs(args);
+  if (parsed.help) {
+    console.log('Usage: atris recover [mission-id] [--apply] [--json]');
+    console.log('Reports blocked and paused missions. --apply clears dead locks, resumes safe pauses, and reruns failed verifiers.');
+    return 0;
+  }
+  const root = path.resolve(options.root || process.cwd());
+  const rows = selectRows(root, parsed.ref);
+  const results = parsed.apply
+    ? rows.map((row) => ({ ...row, ...applyMissionRow(root, row) }))
+    : rows;
+  const receiptPath = parsed.apply ? writeRecoveryReceipt(root, results) : null;
+  const payload = {
+    ok: true,
+    action: parsed.apply ? 'recovery_applied' : 'recovery_report',
+    report_only: !parsed.apply,
+    results: results.map((row) => ({
+      ...row,
+      recovery_command: recoveryCommand(row),
+      disposition: row.human_blocking || row.operator_required ? 'needs operator' : (row.apply ? 'safe' : 'report only'),
+    })),
+    receipt_path: receiptPath,
+  };
+  if (parsed.json) console.log(JSON.stringify(payload, null, 2));
+  else console.log(textLines(results, receiptPath, parsed.apply).join('\n'));
+  return 0;
+}
+
+module.exports = {
+  classifyRecovery,
+  recoverCommand,
+};

package/commands/release.js

@@ -7,7 +7,7 @@ const { execFileSync } = require('child_process');
  *
  * - Reads git log since last tag
  * - Determines bump type (minor if any scorecard has reward>=5, else patch)
- * - Bumps package.json version
+ * - Bumps package.json and package-lock.json together
  * - Commits, tags, pushes
  * - Creates GitHub release via `gh`
  * - Drafts a /launch post (3 emoji bullets)
@@ -79,16 +79,17 @@ async function releaseAtris({ dryRun = false } = {}) {
     return;
   }
 
-  // 7. Bump package.json
-  const updatedPkgRaw = pkgRaw.replace(
-    `"version": "${currentVersion}"`,
-    `"version": "${nextVersion}"`
-  );
-  fs.writeFileSync(pkgPath, updatedPkgRaw);
-  console.log(`bumped package.json to ${nextVersion}`);
+  // 7. Let npm keep package.json and package-lock.json aligned.
+  execFileSync('npm', [
+    'version',
+    nextVersion,
+    '--no-git-tag-version',
+    '--ignore-scripts',
+  ], { cwd, stdio: 'ignore' });
+  console.log(`bumped package.json and package-lock.json to ${nextVersion}`);
 
   // 8. Commit
-  execFileSync('git', ['add', 'package.json'], { cwd });
+  execFileSync('git', ['add', 'package.json', 'package-lock.json'], { cwd });
   execFileSync('git', ['commit', '-m', `v${nextVersion}`], { cwd });
   console.log('committed');
 

package/commands/report.js

@@ -409,7 +409,6 @@ function reportCommand(args = []) {
 module.exports = {
   buildWeekReportData,
   renderWeekReport,
-  renderWeekReportHtml,
   reportCommand,
   showReportHelp,
 };

package/commands/router.js

@@ -0,0 +1,320 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { loadOverrides, pickLane } = require('../lib/ax-auto-lane');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const DEFAULT_GOLD_PATH = path.join(REPO_ROOT, 'scripts', 'det', 'data', 'ax-lane-gold.jsonl');
+const LANE_ORDER = ['fast', 'pro', 'max', 'code-fast'];
+const DEPTH = { fast: 0, 'code-fast': 1, pro: 1, max: 2 };
+const QUALITY_MISS_WEIGHT = 3;
+
+// Preserve alias priority and inline-value priority within each alias.
+function readFirstNamedFlag(args, names) {
+  for (const name of names) {
+    const prefix = `${name}=`;
+    const inline = args.find((arg) => String(arg).startsWith(prefix));
+    if (inline) return String(inline).slice(prefix.length);
+    const index = args.indexOf(name);
+    if (index >= 0 && args[index + 1] && !String(args[index + 1]).startsWith('--')) {
+      return String(args[index + 1]);
+    }
+  }
+  return null;
+}
+
+function resolveRouterPaths(args = [], env = process.env) {
+  const home = env.HOME || os.homedir();
+  return {
+    picks: path.resolve(readFirstNamedFlag(args, ['--picks', '--picks-path'])
+      || env.ATRIS_ROUTER_PICKS_PATH
+      || env.ATRIS_AX_AUTO_PICKS_PATH
+      || path.join(home, '.atris', 'ax-auto-picks.jsonl')),
+    overrides: path.resolve(readFirstNamedFlag(args, ['--overrides', '--overrides-path'])
+      || env.ATRIS_ROUTER_OVERRIDES_PATH
+      || path.join(home, '.atris', 'router-overrides.json')),
+    gold: path.resolve(readFirstNamedFlag(args, ['--gold', '--gold-path'])
+      || env.ATRIS_ROUTER_GOLD_PATH
+      || DEFAULT_GOLD_PATH),
+  };
+}
+
+function readJsonl(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8')
+      .split(/\r?\n/)
+      .filter((line) => line.trim())
+      .flatMap((line) => {
+        try {
+          return [JSON.parse(line)];
+        } catch (_) {
+          return [];
+        }
+      });
+  } catch (_) {
+    return [];
+  }
+}
+
+function outcomeKind(row) {
+  if (!row || row.event !== 'outcome') return null;
+  if (row.outcome === 'rephrased') return 'rephrased';
+  if (row.ok === true || row.outcome === 'ok') return 'ok';
+  if (row.ok === false || row.outcome === 'error' || row.error) return 'error';
+  return null;
+}
+
+function routerStatus(records, overrides) {
+  const picks = Object.fromEntries(LANE_ORDER.map((lane) => [lane, 0]));
+  const outcomes = { ok: 0, error: 0, rephrased: 0 };
+  for (const row of records) {
+    if (row && row.event !== 'outcome' && Object.hasOwn(picks, row.lane)) picks[row.lane] += 1;
+    const kind = outcomeKind(row);
+    if (kind) outcomes[kind] += 1;
+  }
+  return {
+    picks,
+    outcomes,
+    active_overrides: Array.isArray(overrides) ? overrides.length : 0,
+  };
+}
+
+function printStatus(status, output = console.log) {
+  for (const lane of LANE_ORDER) output(`${lane} picks: ${status.picks[lane]}`);
+  output(`ok outcomes: ${status.outcomes.ok}`);
+  output(`error outcomes: ${status.outcomes.error}`);
+  output(`rephrased outcomes: ${status.outcomes.rephrased}`);
+  output(`active overrides: ${status.active_overrides}`);
+}
+
+function messageWords(message) {
+  return String(message || '').toLowerCase().match(/[a-z0-9]+/g) || [];
+}
+
+function signatureForPick(pick) {
+  const firstWords = messageWords(pick && pick.message).slice(0, 2);
+  if (!pick || !pick.lane || !firstWords.length) return null;
+  return `${firstWords.join(' ')}|${pick.lane}`;
+}
+
+function nextLane(lane) {
+  if (lane === 'fast') return 'pro';
+  if (lane === 'pro' || lane === 'code-fast') return 'max';
+  return null;
+}
+
+function groupPicksBySignature(records) {
+  const outcomesByPick = new Map();
+  for (const row of records) {
+    const kind = outcomeKind(row);
+    if (!kind || !row.pick_id) continue;
+    if (!outcomesByPick.has(row.pick_id)) outcomesByPick.set(row.pick_id, new Set());
+    outcomesByPick.get(row.pick_id).add(kind);
+  }
+
+  const groups = new Map();
+  for (const pick of records) {
+    if (!pick || pick.event === 'outcome' || !pick.pick_id) continue;
+    const signature = signatureForPick(pick);
+    if (!signature) continue;
+    if (!groups.has(signature)) {
+      groups.set(signature, {
+        signature,
+        lane: pick.lane,
+        words: messageWords(pick.message).slice(0, 2),
+        picks: [],
+        bad_picks: [],
+      });
+    }
+    const group = groups.get(signature);
+    group.picks.push(pick);
+    const kinds = outcomesByPick.get(pick.pick_id) || new Set();
+    if (kinds.has('error') || kinds.has('rephrased')) group.bad_picks.push(pick);
+  }
+  return groups;
+}
+
+function promotionCandidates(records, minimumMisses = 3) {
+  const candidates = [];
+  for (const group of groupPicksBySignature(records).values()) {
+    const promotedLane = nextLane(group.lane);
+    const misses = group.bad_picks.length;
+    if (!promotedLane || misses < minimumMisses) continue;
+    const idHash = crypto.createHash('sha256').update(group.signature).digest('hex').slice(0, 12);
+    candidates.push({
+      signature: group.signature,
+      misses,
+      from_lane: group.lane,
+      override: {
+        id: `learned-${idHash}`,
+        test: { startsWith: group.words.join(' ') },
+        lane: promotedLane,
+        reason: `learned from ${misses} misses`,
+      },
+    });
+  }
+  return candidates.sort((left, right) => left.signature.localeCompare(right.signature));
+}
+
+function evaluateRows(rows, overrides = []) {
+  let correct = 0;
+  let weightedError = 0;
+  for (const row of rows) {
+    const picked = pickLane(row.message, { overrides }).lane;
+    if (picked === row.lane) {
+      correct += 1;
+      continue;
+    }
+    weightedError += DEPTH[picked] < DEPTH[row.lane] ? QUALITY_MISS_WEIGHT : 1;
+  }
+  const total = rows.length;
+  return {
+    total,
+    correct,
+    accuracy: total ? correct / total : 0,
+    weighted_error_rate: total ? weightedError / (total * QUALITY_MISS_WEIGHT) : 0,
+    weighted_accuracy: total ? 1 - (weightedError / (total * QUALITY_MISS_WEIGHT)) : 0,
+  };
+}
+
+function runCandidateHarness(args = [], env = process.env) {
+  const paths = resolveRouterPaths(args, env);
+  const candidate = JSON.parse(env.ATRIS_ROUTER_CANDIDATE_JSON || '{}');
+  const rows = readJsonl(paths.gold);
+  process.stdout.write(`${JSON.stringify(evaluateRows(rows, [candidate]))}\n`);
+  return rows.length ? 0 : 2;
+}
+
+function runSealedEval(goldPath, options = {}) {
+  const spawn = options.spawnSync || spawnSync;
+  const evalScript = path.join(REPO_ROOT, 'scripts', 'det', 'ax-lane-eval.js');
+  const args = [evalScript, '--json'];
+  if (path.resolve(goldPath) !== path.resolve(DEFAULT_GOLD_PATH)) args.push('--data', goldPath);
+  const result = spawn(process.execPath, args, {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+    env: options.env || process.env,
+  });
+  if (result.error || result.status !== 0) {
+    throw new Error(String((result.error && result.error.message) || result.stderr || 'sealed eval failed').trim());
+  }
+  const report = JSON.parse(result.stdout);
+  return {
+    ...report,
+    weighted_accuracy: 1 - Number(report.weighted_error_rate || 0),
+  };
+}
+
+function runOverrideEval(goldPath, override, options = {}) {
+  const spawn = options.spawnSync || spawnSync;
+  const result = spawn(process.execPath, [__filename, '_eval-candidate', '--gold', goldPath], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+    env: {
+      ...(options.env || process.env),
+      ATRIS_ROUTER_CANDIDATE_JSON: JSON.stringify(override),
+    },
+  });
+  if (result.error || result.status !== 0) {
+    throw new Error(String((result.error && result.error.message) || result.stderr || 'override eval failed').trim());
+  }
+  return JSON.parse(result.stdout);
+}
+
+function evaluateCandidateGate(goldPath, override, options = {}) {
+  const baseline = runSealedEval(goldPath, options);
+  const candidate = runOverrideEval(goldPath, override, options);
+  return {
+    keep: candidate.weighted_accuracy >= baseline.weighted_accuracy,
+    baseline,
+    candidate,
+  };
+}
+
+function writeOverrides(filePath, overrides) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(overrides, null, 2)}\n`, 'utf8');
+  fs.renameSync(tempPath, filePath);
+}
+
+function promote(args, paths, options = {}) {
+  const output = options.output || console.log;
+  const records = readJsonl(paths.picks);
+  const candidates = promotionCandidates(records);
+  const existing = loadOverrides(paths.overrides);
+  const accepted = [];
+  if (!candidates.length) {
+    output('no promotion candidates');
+    return { code: 0, candidates, accepted };
+  }
+
+  for (const candidate of candidates) {
+    output(`candidate ${candidate.signature}: ${candidate.from_lane} -> ${candidate.override.lane}, ${candidate.override.reason}`);
+    if (existing.some((override) => override.id === candidate.override.id)) {
+      output(`keep ${candidate.override.id}: already active`);
+      continue;
+    }
+    const gate = evaluateCandidateGate(paths.gold, candidate.override, options);
+    const before = gate.baseline.weighted_accuracy.toFixed(4);
+    const after = gate.candidate.weighted_accuracy.toFixed(4);
+    if (!gate.keep) {
+      output(`revert ${candidate.override.id}: weighted accuracy ${before} -> ${after}, candidate rejected`);
+      continue;
+    }
+    output(`keep ${candidate.override.id}: weighted accuracy ${before} -> ${after}`);
+    accepted.push(candidate.override);
+  }
+
+  if (args.includes('--dry-run')) {
+    output('dry run: no overrides written');
+  } else if (accepted.length) {
+    writeOverrides(paths.overrides, [...existing, ...accepted]);
+    output(`promoted overrides: ${accepted.length}`);
+  } else {
+    output('promoted overrides: 0');
+  }
+  return { code: 0, candidates, accepted };
+}
+
+function printHelp(output = console.log) {
+  output('usage: atris router status [--picks <path>] [--overrides <path>]');
+  output('usage: atris router promote [--dry-run] [--picks <path>] [--overrides <path>] [--gold <path>]');
+}
+
+function routerCommand(args = [], options = {}) {
+  const env = options.env || process.env;
+  const output = options.output || console.log;
+  const paths = resolveRouterPaths(args, env);
+  const subcommand = args[0] || 'status';
+  if (subcommand === 'status') {
+    printStatus(routerStatus(readJsonl(paths.picks), loadOverrides(paths.overrides)), output);
+    return 0;
+  }
+  if (subcommand === 'promote') return promote(args.slice(1), paths, { ...options, env, output }).code;
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+    printHelp(output);
+    return 0;
+  }
+  printHelp(output);
+  return 2;
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  process.exitCode = args[0] === '_eval-candidate'
+    ? runCandidateHarness(args.slice(1))
+    : routerCommand(args);
+}
+
+module.exports = {
+  groupPicksBySignature,
+  nextLane,
+  promotionCandidates,
+  readJsonl,
+  routerCommand,
+};