atris 3.58.8 → 3.60.0

package/lib/member-engine.js

@@ -0,0 +1,253 @@
+'use strict';
+
+// Which engine a team member runs on. Every member in atris/team/*/MEMBER.md
+// gets a job on its own: navigators, researchers, and scouts search;
+// validators, reviewers, judges, critics, and verifiers review; everyone else
+// builds. A line under "## team" in ROSTER.md overrides that, either with a
+// job ("researcher: search", "fixer: small build") or with engine or model
+// words ("judge: opus 5.5"). The job's pick then comes from the roster.
+
+const fs = require('fs');
+const path = require('path');
+const {
+  ENGINE_JOBS,
+  ENGINE_ROLES,
+  inferJobKind,
+  mainCheckoutRoot,
+  readEngineRegistry,
+  readRosterState,
+  resolveEngineForRoleRanked,
+  rosterChoiceForPick,
+  rosterDecided,
+  ROSTER_LAYERS,
+  rosterJobKey,
+  rosterJobLabel,
+  rosterJobRole,
+  rosterModelLabel,
+  rosterPickFromValue,
+} = require('./engine-registry');
+
+const SEARCH_WORDS = Object.freeze(['navigator', 'researcher', 'research', 'search', 'scout']);
+const REVIEW_WORDS = Object.freeze(['validator', 'reviewer', 'review', 'judge', 'critic', 'verifier']);
+
+function memberCardFile(root, name) {
+  return path.join(root, 'atris', 'team', name, 'MEMBER.md');
+}
+
+// This folder's card, else the main checkout's when this is a git worktree:
+// the same fallback the roster file uses, so a card not yet committed still
+// counts from a worktree. '' when neither has one.
+function findMemberCard(root, name) {
+  const own = memberCardFile(root, name);
+  if (fs.existsSync(own)) return own;
+  const main = mainCheckoutRoot(root);
+  const shared = main ? memberCardFile(main, name) : '';
+  return shared && fs.existsSync(shared) ? shared : '';
+}
+
+// name and role from the MEMBER.md frontmatter; found is false when there is
+// no card for this name.
+function readMemberCard(root, name) {
+  let text = '';
+  try {
+    text = fs.readFileSync(findMemberCard(root, name), 'utf8');
+  } catch {
+    return { name, role: '', found: false };
+  }
+  const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  const field = (key) => {
+    const match = block ? new RegExp(`^${key}:\\s*(.*)$`, 'm').exec(block[1]) : null;
+    return match ? match[1].trim().replace(/^["']|["']$/g, '') : '';
+  };
+  return { name: field('name') || name, role: field('role'), found: true };
+}
+
+function listTeamMembers(root = process.cwd()) {
+  const dir = path.join(root, 'atris', 'team');
+  let names = [];
+  try {
+    names = fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.') && !entry.name.startsWith('_'))
+      .map((entry) => entry.name)
+      .filter((name) => fs.existsSync(memberCardFile(root, name)));
+  } catch {
+    return [];
+  }
+  return names.sort();
+}
+
+function words(text) {
+  return String(text || '').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+
+function kindFromWords(list) {
+  if (list.some((word) => SEARCH_WORDS.includes(word))) return 'search';
+  if (list.some((word) => REVIEW_WORDS.includes(word))) return 'review';
+  return '';
+}
+
+// The job a member gets with no team line: its name decides first, then its
+// role title, else build.
+function autoJobForMember(name, role = '') {
+  return kindFromWords(words(name)) || kindFromWords(words(role)) || 'build';
+}
+
+// This session's team line wins, then this project's, then the
+// all-projects one.
+function teamLineFor(state, member) {
+  const key = String(member || '').trim().toLowerCase();
+  const find = (layer) => (layer && Array.isArray(layer.team) ? layer.team.filter((line) => line.member === key)[0] : null);
+  for (const scope of ROSTER_LAYERS) {
+    const line = find(state[scope]);
+    if (line) return { ...line, scope };
+  }
+  return null;
+}
+
+// What a team line value means: a job (built-in name, a job the roster
+// already has, or a name that says its kind) or a direct engine pick for the
+// member's own kind of work. error is a plain sentence for a line that means
+// neither.
+function interpretTeamValue(value, state, memberKind, options = {}) {
+  const text = String(value || '').trim();
+  if (!text) return { error: 'names no job or engine' };
+  const key = rosterJobKey(text);
+  if (key && ENGINE_ROLES.includes(key)) return { type: 'job', key };
+  const saved = (layer) => Boolean(key && layer && layer.picks && layer.picks[key]);
+  if (saved(state.session) || saved(state.project) || saved(state.machine)) return { type: 'job', key };
+  try {
+    return { type: 'pick', pick: rosterPickFromValue(text, ENGINE_JOBS[memberKind], options) };
+  } catch (error) {
+    if (key && inferJobKind(text)) return { type: 'job', key };
+    return { error: error.message };
+  }
+}
+
+function engineText(engine) {
+  if (!engine) return 'no ready engine';
+  return `${engine.id}${engine.roster_model ? ` ${rosterModelLabel(engine.roster_model)}` : ''}`;
+}
+
+// The engine one member runs on, with a plain reason ("researcher does
+// search: claude haiku"). roster_backed is true when a roster line decided
+// (a job pick or a team line); when false the router decided, and callers
+// keep whatever they did before the roster existed.
+function resolveEngineForMember(memberName, root = process.cwd(), options = {}) {
+  const name = String(memberName || '').trim();
+  const card = readMemberCard(root, name);
+  const state = options.rosterState || readRosterState(root, options);
+  const autoKind = autoJobForMember(name, card.role);
+  const line = teamLineFor(state, name);
+  const read = line ? interpretTeamValue(line.value, state, autoKind, options) : null;
+  const override = read && !read.error ? read : null;
+  const yearless = override && override.type === 'pick' && override.pick.until_needs_year;
+  const pickOptions = {
+    ...options,
+    sessionRosterPicks: state.session ? state.session.picks : {},
+    projectRosterPicks: state.project.picks,
+    machineRosterPicks: state.machine.picks,
+  };
+  const base = {
+    member: name,
+    title: card.role || '',
+    found: card.found || Boolean(line),
+    source: override ? 'file' : 'auto',
+    file: override ? line.file : null,
+    line: override ? line.line : null,
+    ...(read && read.error ? { warning: read.error } : {}),
+    ...(yearless ? { until_warning: `has no year in its until date, so it counts as expired; write until ${yearless}` } : {}),
+  };
+
+  if (override && override.type === 'pick') {
+    const role = ENGINE_JOBS[autoKind];
+    const registry = readEngineRegistry(root, { persist: false });
+    const choice = rosterChoiceForPick(override.pick, role, registry, { label: autoKind, source: line.scope, now: options.now });
+    if (choice) {
+      return {
+        ...base,
+        job: autoKind,
+        job_key: role,
+        role,
+        engine: choice.engine,
+        model: choice.engine.roster_model || '',
+        pick_source: 'team',
+        roster_backed: true,
+        reason: `${name} does ${autoKind}: ${engineText(choice.engine)}`,
+      };
+    }
+  }
+
+  const jobKey = override && override.type === 'job' ? override.key : ENGINE_JOBS[autoKind];
+  const role = rosterJobRole(jobKey, root, pickOptions) || ENGINE_JOBS[autoKind];
+  const custom = !ENGINE_ROLES.includes(jobKey);
+  const resolved = resolveEngineForRoleRanked(role, root, { ...pickOptions, ...(custom ? { job: jobKey } : {}) });
+  const job = rosterJobLabel(jobKey);
+  const fromRoster = rosterDecided(resolved.source);
+  return {
+    ...base,
+    job,
+    job_key: jobKey,
+    role,
+    engine: resolved.engine || null,
+    model: resolved.engine && resolved.engine.roster_model ? resolved.engine.roster_model : '',
+    pick_source: resolved.source,
+    roster_backed: fromRoster || Boolean(override),
+    reason: `${name} does ${job}: ${engineText(resolved.engine)}`,
+  };
+}
+
+// The member's engine only when the roster decided it and the member is on
+// the team (a MEMBER.md or a team line). null means keep the old routing.
+// Never throws: a broken roster must not stop a run.
+function memberRosterEngine(memberName, root = process.cwd(), options = {}) {
+  const name = String(memberName || '').trim();
+  if (!name || name.includes('/') || name.includes('\\')) return null;
+  try {
+    const picked = resolveEngineForMember(name, root, options);
+    if (!picked.found && options.requireMember !== false) return null;
+    return picked.roster_backed && picked.engine ? picked : null;
+  } catch {
+    return null;
+  }
+}
+
+// One row per member for `atris engine roster`, plus a warning for every
+// team line that could not be used.
+function teamRosterView(root = process.cwd(), options = {}) {
+  const state = options.rosterState || readRosterState(root, options);
+  const names = new Set(listTeamMembers(root));
+  const warnings = [];
+  for (const layer of [state.session, state.project, state.machine]) {
+    for (const line of (layer && layer.team) || []) {
+      if (findMemberCard(root, line.member)) names.add(line.member);
+      else if (layer.scope === 'project') warnings.push({ file: line.file, line: line.line, text: line.text, message: `there is no team member named ${line.member}, so the line does nothing` });
+    }
+  }
+  const rows = [...names].sort().map((name) => {
+    const picked = resolveEngineForMember(name, root, { ...options, rosterState: state });
+    const line = teamLineFor(state, name);
+    if (picked.warning && line) {
+      warnings.push({ file: line.file, line: line.line, text: line.text, message: `${picked.warning}, so ${name} picks automatically` });
+    }
+    if (picked.until_warning && line) warnings.push({ file: line.file, line: line.line, text: line.text, message: picked.until_warning });
+    return {
+      member: name,
+      job: picked.job,
+      engine: picked.engine ? picked.engine.id : null,
+      model: picked.model || null,
+      effort: picked.engine && picked.engine.roster_effort ? picked.engine.roster_effort : null,
+      max_seconds: picked.engine && picked.engine.roster_max_seconds ? picked.engine.roster_max_seconds : null,
+      source: picked.source,
+      file: picked.file,
+      reason: picked.reason,
+    };
+  });
+  return { rows, warnings };
+}
+
+module.exports = {
+  autoJobForMember,
+  resolveEngineForMember,
+  memberRosterEngine,
+  teamRosterView,
+};

package/lib/roster-markdown.js

@@ -0,0 +1,206 @@
+'use strict';
+
+// ROSTER.md as text: which lines are job lines, worker lines, and team
+// lines, and edits that touch one job while keeping everything else the
+// person wrote (comments, order, blank lines, notes). What a line means
+// (which engine, which job) lives in engine-registry; this file only knows
+// the shape.
+//
+// Two shapes read side by side. The sectioned shape, which assign writes:
+//   ## build
+//   - claude code, model: opus 5.5
+//   - codex, effort: medium
+// and the older one-line shape, still read as before:
+//   build: claude opus 5.5, backup codex
+
+const OLD_ROSTER_NOTE = '> edit any time. each line is job: engine and model, an optional effort (low, medium, high, xhigh, max), then optional "backup <engine and model>", "max 20 min", and "until 2026-10-24" (the year is required).';
+const ROSTER_NOTE = '> edit any time. each "## job" lists its workers in order, one per line: "- tool, model: name", then optional "effort: medium", "max: 20 min", and "until 2026-10-24" (the year is required). the first ready worker leads and the rest back it up.';
+
+const ROSTER_MARKDOWN_TEMPLATE = [
+  '# roster',
+  '',
+  ROSTER_NOTE,
+  '',
+];
+
+function stripInlineComments(text) {
+  return String(text || '').replace(/<!--.*?-->/g, '').trim();
+}
+
+// Sections: anything under a top heading, "## jobs", or "## roster" holds
+// one-line job lines; "## team" holds member lines; any other heading is a
+// job whose "- " lines are its workers. Other lines under a job heading are
+// free notes that are never read as picks.
+function sectionForHeading(level, title) {
+  const name = String(title || '').trim().toLowerCase();
+  if (level === 1) return 'jobs';
+  if (name === 'team') return 'team';
+  if (name === 'jobs' || name === 'roster') return 'jobs';
+  return 'job';
+}
+
+function scanRosterMarkdown(text) {
+  const source = String(text || '');
+  const newline = source.includes('\r\n') ? '\r\n' : '\n';
+  const lines = source.split(/\r?\n/);
+  const entries = [];
+  const headings = [];
+  let section = 'jobs';
+  let heading = null;
+  let inComment = false;
+  lines.forEach((raw, index) => {
+    const line = raw.trim();
+    if (inComment) {
+      if (line.includes('-->')) inComment = false;
+      return;
+    }
+    if (!line) return;
+    if (line.startsWith('<!--')) {
+      if (!line.includes('-->')) inComment = true;
+      return;
+    }
+    if (line.startsWith('>') || line.startsWith('```')) return;
+    const headingMatch = /^(#{1,6})\s*(.*)$/.exec(line);
+    if (headingMatch) {
+      section = sectionForHeading(headingMatch[1].length, headingMatch[2]);
+      heading = { index, lineNumber: index + 1, level: headingMatch[1].length, title: stripInlineComments(headingMatch[2]), raw: line, section };
+      headings.push(heading);
+      return;
+    }
+    const dashed = /^-\s+/.test(line);
+    if (line.startsWith('-') && !dashed) return;
+    const body = stripInlineComments(dashed ? line.replace(/^-\s+/, '') : line);
+    if (!body) return;
+    if (section === 'job') {
+      // Only "- " lines under a job heading are workers.
+      if (!dashed) return;
+      entries.push({ index, lineNumber: index + 1, section, raw: line, name: '', value: body, heading: heading.title, headingIndex: heading.index, dashed, malformed: false });
+      return;
+    }
+    // A "- " bullet under the jobs heading is a note; under team it is a
+    // member line.
+    if (dashed && section !== 'team') return;
+    const colon = body.indexOf(':');
+    if (dashed && colon <= 0) return;
+    entries.push({
+      index,
+      lineNumber: index + 1,
+      section,
+      raw: line,
+      name: colon > 0 ? body.slice(0, colon).trim() : '',
+      value: colon > 0 ? body.slice(colon + 1).trim() : '',
+      dashed,
+      malformed: colon <= 0,
+    });
+  });
+  return { lines, entries, headings, newline };
+}
+
+function joinLines(lines, newline) {
+  const text = lines.join(newline);
+  return text.endsWith(newline) ? text : `${text}${newline}`;
+}
+
+function trimTrailingBlank(lines) {
+  const out = [...lines];
+  while (out.length && !out[out.length - 1].trim()) out.pop();
+  return out;
+}
+
+function isBlank(line) {
+  return !String(line || '').trim();
+}
+
+// One job's section: its heading, the index where it ends (the next heading
+// or the end of the file), and its worker lines in order.
+function jobSections(scan) {
+  return scan.headings
+    .map((heading, i) => ({ heading, next: scan.headings[i + 1] }))
+    .filter(({ heading }) => heading.section === 'job')
+    .map(({ heading, next }) => ({
+      heading,
+      end: next ? next.index : scan.lines.length,
+      workers: scan.entries.filter((entry) => entry.section === 'job' && entry.headingIndex === heading.index),
+    }));
+}
+
+// Two headings say the same thing when they differ only in case or spacing.
+function sameHeading(a, b) {
+  const plain = (text) => stripInlineComments(String(text || '').replace(/^#+\s*/, '')).replace(/\s+/g, ' ').toLowerCase();
+  return plain(a) === plain(b);
+}
+
+// Replace one job's worker lines with lines (in order), add the section when
+// it is missing, or remove every section for the job when lines is null. matches(title)
+// names the section by its heading; heading is the text for a new one, and
+// when given it also replaces an existing heading that says something else
+// (a note at the end of the old heading stays). Every other line outside that
+// job's workers stays as written.
+function replaceJobSection(text, { matches, heading, lines: workerLines }) {
+  const base = String(text || '').trim() ? String(text) : ROSTER_MARKDOWN_TEMPLATE.join('\n');
+  const scan = scanRosterMarkdown(base);
+  const lines = [...scan.lines];
+  const sections = jobSections(scan).filter((entry) => matches(entry.heading.title));
+  const section = sections[0];
+  if (section && workerLines === null) {
+    // Every section for the job goes, last first so earlier indexes hold; a
+    // second section that was ignored must not become the job.
+    for (const entry of [...sections].reverse()) {
+      let start = entry.heading.index;
+      let end = Math.min(entry.end, lines.length);
+      // Take the blank lines after the section with it, so no double gap stays.
+      while (end > start && isBlank(lines[end - 1])) end -= 1;
+      while (end < lines.length && isBlank(lines[end])) end += 1;
+      if (end >= lines.length) while (start > 0 && isBlank(lines[start - 1])) start -= 1;
+      lines.splice(start, end - start);
+    }
+    return joinLines(trimTrailingBlank(lines), scan.newline);
+  }
+  if (section) {
+    const at = section.workers.length ? section.workers[0].index : section.heading.index + 1;
+    for (const worker of [...section.workers].reverse()) lines.splice(worker.index, 1);
+    lines.splice(at, 0, ...workerLines);
+    if (heading && !sameHeading(section.heading.raw, heading)) {
+      const note = /\s*(<!--.*?-->)\s*$/.exec(section.heading.raw);
+      lines[section.heading.index] = note ? `${heading} ${note[1]}` : heading;
+    }
+    return joinLines(trimTrailingBlank(lines), scan.newline);
+  }
+  if (workerLines === null) return joinLines(trimTrailingBlank(lines), scan.newline);
+  // A new job goes right before the team, else at the end.
+  const team = scan.headings.find((entry) => entry.section === 'team');
+  const block = [heading, ...workerLines];
+  if (team) {
+    let at = team.index;
+    while (at > 0 && isBlank(lines[at - 1])) at -= 1;
+    lines.splice(at, 0, ...(at > 0 ? [''] : []), ...block);
+    return joinLines(trimTrailingBlank(lines), scan.newline);
+  }
+  const trimmed = trimTrailingBlank(lines);
+  return joinLines([...trimmed, ...(trimmed.length ? [''] : []), ...block], scan.newline);
+}
+
+// Replace every line for which rewrite(entry) returns a string, leaving the
+// rest of the file byte for byte.
+function rewriteRosterValues(text, rewrite) {
+  const scan = scanRosterMarkdown(text);
+  const lines = [...scan.lines];
+  for (const entry of scan.entries) {
+    const next = rewrite(entry);
+    if (typeof next !== 'string') continue;
+    const indent = /^\s*/.exec(lines[entry.index])[0];
+    lines[entry.index] = `${indent}${next}`;
+  }
+  return joinLines(trimTrailingBlank(lines), scan.newline);
+}
+
+module.exports = {
+  OLD_ROSTER_NOTE,
+  ROSTER_NOTE,
+  ROSTER_MARKDOWN_TEMPLATE,
+  scanRosterMarkdown,
+  jobSections,
+  replaceJobSection,
+  rewriteRosterValues,
+  joinLines,
+};

package/lib/roster-models.js

@@ -0,0 +1,179 @@
+'use strict';
+
+// What model and effort each roster line really runs, and where each came
+// from, so the roster view never shows an engine with a blank model. A pin
+// on the line wins; with no pin, codex reads the top of its own settings
+// file, claude-family engines run the atris default, and every other engine
+// rides its own default. Nothing here spawns an engine or goes online.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  RUNNER_PROFILE_DEFS,
+  RUNNER_PROFILE_ALIASES,
+  DEFAULT_CLAUDE_RUNNER_MODEL,
+} = require('./runner-command');
+
+const CLAUDE_FAMILY = Object.freeze(['claude', 'fable', 'haiku']);
+const ATRIS_PINNED = Object.freeze(['atris-fast', 'composer']);
+
+// ~/.codex/config.toml unless a path is given. Test runs never read the real
+// file unless they point at one on purpose.
+function codexConfigFile(options = {}) {
+  if (options.codexConfigPath) return options.codexConfigPath;
+  if (process.env.ATRIS_CODEX_CONFIG_PATH) return process.env.ATRIS_CODEX_CONFIG_PATH;
+  if (process.env.NODE_TEST_CONTEXT) return '';
+  return path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'config.toml');
+}
+
+// The top-level model and model_reasoning_effort, the lines before the first
+// [section]. A tiny line reader, not a toml parser: anything else is ignored.
+function readCodexSettings(options = {}) {
+  const file = codexConfigFile(options);
+  if (!file) return {};
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return {};
+  }
+  const settings = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith('[')) break;
+    const match = /^(model|model_reasoning_effort)\s*=\s*(?:"([^"]*)"|'([^']*)')\s*(?:#.*)?$/.exec(line);
+    if (match) settings[match[1]] = (match[2] !== undefined ? match[2] : match[3]).trim();
+  }
+  return settings;
+}
+
+// claude-opus-5-5 reads as "opus 5.5"; anything else as written.
+function modelLabel(model) {
+  const text = String(model || '').trim();
+  const grok = /^grok-(\d+(?:\.\d+)?)(-build-fast)?$/.exec(text);
+  if (grok) return `grok ${grok[1]}${grok[2] ? ' fast' : ''}`;
+  const match = /^claude-(opus|sonnet|haiku|fable)-(\d+)(?:-(\d{1,2}))?(?:-\d{8})?$/.exec(text);
+  if (!match) return text;
+  return `${match[1]} ${match[2]}${match[3] ? `.${match[3]}` : ''}`;
+}
+
+const SOURCE_TAIL = Object.freeze({ 'codex settings': 'from codex settings', 'atris default': 'atris default' });
+const SOURCE_INLINE = Object.freeze({ 'codex settings': 'from codex settings', 'atris default': 'by atris default' });
+
+// One engine's real model and effort. Sources: roster (pinned on the line),
+// codex settings, atris default, or own default (the engine decides).
+function engineRunsView(engineId, { model = '', effort = '' } = {}, options = {}) {
+  const id = RUNNER_PROFILE_ALIASES[engineId] || engineId;
+  const def = RUNNER_PROFILE_DEFS[id] || {};
+  const view = { engine: id, model: '', model_source: 'own default', effort: '', effort_source: '' };
+  if (model) {
+    view.model = model;
+    view.model_source = 'roster';
+  } else if (id === 'codex') {
+    const settings = readCodexSettings(options);
+    if (settings.model) {
+      view.model = settings.model;
+      view.model_source = 'codex settings';
+    }
+  } else if (CLAUDE_FAMILY.includes(id)) {
+    view.model = String(process.env.ATRIS_RUNNER_MODEL || '').trim() || def.model || DEFAULT_CLAUDE_RUNNER_MODEL;
+    view.model_source = 'atris default';
+  } else if (ATRIS_PINNED.includes(id) && def.model) {
+    view.model = def.model;
+    view.model_source = 'atris default';
+  }
+  if (effort) {
+    view.effort = effort;
+    view.effort_source = 'roster';
+  } else if (id === 'codex') {
+    const settings = readCodexSettings(options);
+    if (settings.model_reasoning_effort) {
+      view.effort = settings.model_reasoning_effort;
+      view.effort_source = 'codex settings';
+    }
+  }
+  view.text = `${id} (${runsDetail(view)})`;
+  return view;
+}
+
+function runsDetail(view) {
+  const items = [{ text: view.model ? modelLabel(view.model) : 'its own default', source: view.model ? view.model_source : 'roster' }];
+  if (view.effort) items.push({ text: view.effort, source: view.effort_source });
+  const sourced = [...new Set(items.map((item) => item.source).filter((source) => SOURCE_TAIL[source]))];
+  // Every item shares one source: say it once at the end.
+  if (sourced.length === 1 && items.every((item) => item.source === sourced[0])) {
+    return [...items.map((item) => item.text), SOURCE_TAIL[sourced[0]]].join(', ');
+  }
+  return items.map((item) => (SOURCE_INLINE[item.source] ? `${item.text} ${SOURCE_INLINE[item.source]}` : item.text)).join(', ');
+}
+
+// --- what this machine offers --------------------------------------------
+//
+// Cheap local sources only: never the network, never the tool itself. Codex
+// keeps a cache of the models it can run; claude takes the names atris knows;
+// every other engine lists its seed models.
+
+const KNOWN_CLAUDE_MODELS = Object.freeze(['opus 5.5', 'opus 5', 'sonnet 5', 'haiku 4.5', 'fable 5.1']);
+
+// ~/.codex/models_cache.json unless a path is given. Test runs never read the
+// real file unless they point at one on purpose.
+function codexModelsCacheFile(options = {}) {
+  if (options.codexModelsCachePath) return options.codexModelsCachePath;
+  if (process.env.ATRIS_CODEX_MODELS_CACHE_PATH) return process.env.ATRIS_CODEX_MODELS_CACHE_PATH;
+  if (process.env.NODE_TEST_CONTEXT) return '';
+  return path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'models_cache.json');
+}
+
+// Every "slug" in the cache, in order, once each. [] when there is no cache
+// or it does not parse.
+function readCodexModelSlugs(options = {}) {
+  const file = codexModelsCacheFile(options);
+  if (!file) return [];
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return [];
+  }
+  const slugs = [];
+  const walk = (value, depth) => {
+    if (depth > 6 || !value || typeof value !== 'object') return;
+    if (Array.isArray(value)) {
+      value.forEach((item) => walk(item, depth + 1));
+      return;
+    }
+    if (typeof value.slug === 'string' && value.slug.trim() && !slugs.includes(value.slug.trim())) slugs.push(value.slug.trim());
+    for (const child of Object.values(value)) if (child && typeof child === 'object') walk(child, depth + 1);
+  };
+  walk(data, 0);
+  return slugs;
+}
+
+function homeLabel(file) {
+  const home = os.homedir();
+  const rel = path.relative(home, file);
+  return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? `~/${rel}` : file;
+}
+
+// One row per installed engine: the models it offers and where that list
+// came from ("from <file>" or "known names").
+function availableModels(engines, options = {}) {
+  return (engines || []).map((engine) => {
+    const id = engine.id;
+    if (id === 'codex') {
+      const slugs = readCodexModelSlugs(options);
+      if (slugs.length) return { engine: id, models: slugs, source: `from ${homeLabel(codexModelsCacheFile(options))}` };
+    }
+    if (id === 'claude') return { engine: id, models: [...KNOWN_CLAUDE_MODELS], source: 'known names' };
+    const models = Array.isArray(engine.models) ? engine.models.filter(Boolean) : [];
+    return { engine: id, models, source: 'known names' };
+  });
+}
+
+module.exports = {
+  modelLabel,
+  readCodexSettings,
+  engineRunsView,
+  availableModels,
+};