create-byan-agent 2.39.0 → 2.41.0

package/CHANGELOG.md

@@ -9,7 +9,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.39.0] - 2026-07-02
+### Added - Codex auto-delegation (opt-in, native)
+- **BYAN now proposes handing delegable work to Codex on your ChatGPT
+  subscription (no API credit) when Claude nears its 5h limit.** A
+  `UserPromptSubmit` hook estimates the rolling-5h Claude consumption from the
+  local transcripts (live) + session-meta (fallback), and nudges delegation on
+  three triggers: pressure (>= 80% estimated, configurable), task nature
+  (delegable coding work), and an opt-in perf forces table. The red line holds:
+  only delegable natures are proposed; judgment / soul / verification stay on
+  Claude. Disarmed by default — the yanstaller arms it on opt-in (device-flow
+  `codex login --device-auth`, entitled model gpt-5.4) by writing
+  `_byan/_config/autodelegate.json`. The 5h gauge is an honest ESTIMATE (no
+  provider exposes a machine-readable quota; `pct` is null without a configured
+  budget), and perf routing ships neutral (below the L2 perf floor, tagged
+  heuristic). New: `.claude/hooks/codex-autodelegate.js` +
+  `.claude/hooks/lib/{usage-estimator,autodelegate-decision,perf-routing}.js`,
+  `install/lib/codex-autodelegate-setup.js`. 47 unit tests. See
+  `docs/codex-auto-delegation.md`.
+
+### Fixed
+- **lb: Codex pool targeted a non-entitled model on ChatGPT subscription.** The
+  provider defaulted to `gpt-5-codex`; the OpenAI backend rejects every
+  `-codex`-suffixed model on a subscription account (API-key only). Default is
+  now the entitled `gpt-5.4`, and a new pure `resolveCodexModel({ requested,
+  authPool })` remaps a `-codex` request to `gpt-5.4` under subscription auth
+  only (passthrough on api-key or an already-plain id). `loadbalancer.default.yaml`
+  codex models set to `gpt-5.4`. Covered by 7 new unit tests (mock runner, no
+  real CLI/network). See `docs/loadbalancer-multipool.md`.
+
+## [2.41.0] - 2026-07-03
+
+### Added - multi-pool subscription arbitrage: Codex as a second pool + the 5h-window ladder
+
+The load-balancer had claude + copilot + byan_api but no OpenAI pool, and its
+pressure-score modelled API-burst (429) pressure, not the rolling 5h subscription
+window that users actually hit. This release adds the second pool and the window
+tracking that switches before the wall, without denaturing BYAN.
+
+- **CodexProvider** (`src/loadbalancer/providers/codex-provider.js`) - wraps the
+  `codex exec --json` SYSTEM CLI (not an npm SDK); degrades to disabled if the
+  binary is absent; two auth pools (CODEX_API_KEY per-token, else the
+  ChatGPT-subscription session). Rate-limit exhaustion read from stderr (no
+  machine-readable quota, OpenAI issue #10233). Registered in the yaml +
+  capability-matrix; provider factory (`providers/factory.js`).
+- **subscription-window tracker** (`subscription-window.js`) - per-pool rolling-5h
+  + weekly token burn, a `window-proximity` signal (distinct from 429-pressure) +
+  ETA. Honest estimate: `null` proximity without a configured budget, no
+  fabricated percentage.
+- **Execution stubs unblocked** (`mcp-server.js`) - `lb_send` / `lb_switch` /
+  `lb_get_context` now really route / transfer context / read state; the
+  SessionBridge and GracefulDegradation (previously orphaned) are wired; all
+  seams injectable so tests avoid spawning codex or hitting the OpenAI quota.
+- **switch-tolerance** (`switch-tolerance.js`) - the red line: only delegable
+  natures (exploration / mechanical / implementation) may cross to Codex;
+  verification / analysis / soul / identity / review / gate stay on Claude and
+  queue rather than denature.
+- **4-rung degradation ladder** (`degradation-ladder.js`) - HEALTHY ->
+  PRIMARY_HOT -> PRIMARY_EXHAUSTED -> ALL_EXHAUSTED, driven by the window
+  proximity, obeying the red line at every rung. `planRoute(nature)` on the live
+  shell.
+- **lb_budget** MCP tool + `getBudget()` - the anti-"5h limit reached" dashboard:
+  per-pool 5h/weekly burn, proximity, ETA, rung, with the honest estimate/
+  doubles-the-ceiling note.
+- **Docs** - `docs/loadbalancer-multipool.md` (architecture, the red line, the two
+  hard truths, honest shipping status).
+
+### Added - native workflow model tiering: the sonnet tier lives, ad-hoc scripts are gated
+
+Claude Code's Workflow tool runs every `agent()` leaf on the session model
+unless the script pins `opts.model`, and the tiering contract only reached
+committed `.claude/workflows/*.js` through the repo linter. Two consequences,
+both observed live: ad-hoc scripts (written inline for one run) executed
+all-deep (14 agents on Opus for one review), and the `balanced` tier was
+unreachable (0/131 committed leaves on sonnet). This release closes both.
+
+- **`mech-` opt-in class (native-tiers)** - a `mech-` label prefix
+  (`mech-validate-json`) declares a MECHANICAL verification: a binary,
+  judgment-free check (JSON parses, schema matches, lint passes) that tiers to
+  `balanced` (sonnet). Explicit opt-in only, no keyword fuzziness:
+  `validate-json` without the prefix stays protected (deep). The linter holds
+  the script to the declaration: `mechanical-without-model` and
+  `mechanical-below-tier` are hard contract violations.
+- **tier-script engine + CLI** - `lib/tier-script.js` analyzes any workflow
+  script TEXT (committed, ad-hoc or draft): one verdict per labelled leaf
+  against native-tiers, plus the deny-once gate decision. Parsing stays in
+  `workflows-lint.js` (`extractLabelledLeaves`). `bin/byan-tier-script.js`
+  prints the report (exit 0 clean/acknowledged, 1 gaps, 2 violations).
+- **tier gate hook** - `.claude/hooks/tier-script-guard.js` (PreToolUse,
+  matcher `Workflow`) gates EVERY Workflow invocation at the one chokepoint an
+  ad-hoc script crosses. Undecided exploration/`mech-` leaves deny ONCE with
+  the exact leaf list; `// BYAN-TIER: reviewed` acknowledges deliberate deep
+  choices; an identical resubmission passes (deny-once by design); registry
+  invocations pass. It rewrites nothing (STRICT-2 No Downgrade). Every
+  decision lands in `_byan-output/tier-ledger.jsonl` with a per-model
+  histogram - the measurement basis for token gains. Escape hatch:
+  `.byan-tier/off`.
+- **`byan_dispatch` batch mode** - `{ leaves: [{ label, nature? }] }` returns
+  the `opts.model` per planned leaf BEFORE the script is written; the nature
+  enum gains `mechanical` on both axes.
+- **Docs** - `native-workflows.md` rule + `docs/native-workflows-contract.md`
+  describe the three live tiers, the two nets (repo linter floor + tier gate
+  hook) and the authoring flow; byan-byan and hermes-dispatch skills carry the
+  same doctrine.
 
 ### Added - shippable soul stays in sync with the active soul (byan-sync-soul)
 

package/install/bin/create-byan-agent-v2.js

@@ -20,6 +20,7 @@ const { setupRtkIntegration, shouldOfferRtk } = require('../lib/rtk-integration'
 const { setupGdocPublish, shouldOfferGdoc } = require('../lib/gdoc-setup');
 const { setupClaudeNative } = require('../lib/claude-native-setup');
 const { setupCodexNative } = require('../lib/codex-native-setup');
+const { setupCodexAutodelegate, DEVICE_FLOW_INSTRUCTION } = require('../lib/codex-autodelegate-setup');
 const { setupMcpExtensions } = require('../lib/mcp-extensions');
 const { setupStagingConsent } = require('../lib/staging-consent');
 const { getLatestVersion, compareVersions } = require('../lib/utils/version-compare');
@@ -1334,6 +1335,45 @@ async function install(options = {}) {
         )
       );
     }
+
+    // Optional: opt into a Codex BACKUP pool. When enabled, BYAN auto-proposes
+    // handing delegable work to Codex on the ChatGPT subscription (no API credit)
+    // to spare the Claude 5h budget. Arms the F5 hook by writing
+    // _byan/_config/autodelegate.json. TTY -> prompt; non-TTY -> env opt-in.
+    console.log();
+    console.log(chalk.cyan('Codex backup pool (auto-delegation)'));
+    let wantAutodelegate = false;
+    if (process.stdin.isTTY) {
+      try {
+        const ans = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'enable',
+            message:
+              'Add Codex as a backup pool? BYAN will propose offloading delegable work to Codex (your ChatGPT subscription, no API credit) when Claude is under 5h pressure.',
+            default: true,
+          },
+        ]);
+        wantAutodelegate = ans.enable;
+      } catch {
+        wantAutodelegate = false;
+      }
+    } else {
+      wantAutodelegate = process.env.BYAN_CODEX_AUTODELEGATE === '1';
+      if (!wantAutodelegate) {
+        console.log(
+          chalk.gray('  · non-TTY — skipped (set BYAN_CODEX_AUTODELEGATE=1 to arm)')
+        );
+      }
+    }
+    if (wantAutodelegate) {
+      try {
+        await setupCodexAutodelegate(projectRoot);
+      } catch (error) {
+        console.log(chalk.yellow(`  ! Codex auto-delegation setup skipped: ${error.message}`));
+        console.log(chalk.gray(`    ${DEVICE_FLOW_INSTRUCTION.replace(/\n/g, '\n    ')}`));
+      }
+    }
   }
 
   if (needsClaude) {

package/install/lib/codex-autodelegate-setup.js

@@ -0,0 +1,100 @@
+/**
+ * Codex auto-delegation setup (installer F4) — opts the user into a Codex backup
+ * pool and ARMS the F5 auto-delegation hook by writing
+ * `_byan/_config/autodelegate.json`.
+ *
+ * Linking uses the LOCAL Codex auth — the ChatGPT subscription established by
+ * `codex login` — NOT an API key: delegated turns cost subscription quota, not
+ * per-token API credit. The entitled model is `gpt-5.4` (the `-codex` ids are
+ * API-only on a subscription; see src/loadbalancer/providers/codex-provider.js).
+ *
+ * On a headless server the browser localhost redirect of the default login
+ * fails, so we surface the DEVICE-FLOW instruction (`codex login --device-auth`)
+ * rather than pretend the link worked.
+ *
+ * Companion to codex-native-setup.js (which wires the BYAN MCP into
+ * ~/.codex/config.toml). This module owns only the auto-delegation opt-in. All
+ * fs is injectable so the unit tests write nothing real; the hook it arms is a
+ * no-op until this config exists (disarmed-by-default, see the F5 hook).
+ */
+
+const realFs = require('fs');
+const realPath = require('path');
+const os = require('os');
+let chalk;
+try { chalk = require('chalk'); } catch { chalk = null; }
+
+const paint = (fn, s) => (chalk && chalk[fn] ? chalk[fn](s) : s);
+
+const DEVICE_FLOW_INSTRUCTION = [
+  'Codex is not linked yet. On THIS machine run:',
+  '    codex login --device-auth',
+  'then open the printed URL, enter the code, and re-run the installer.',
+  '(device-auth avoids the localhost browser redirect that fails on a headless server).',
+].join('\n');
+
+// Which local Codex auth backs the CLI: 'api-key' (CODEX_API_KEY, per-token),
+// 'subscription' (~/.codex/auth.json, the 5h window), or null (not linked).
+function codexAuthState({ home = os.homedir(), fs = realFs, path = realPath } = {}) {
+  if (process.env.CODEX_API_KEY) return 'api-key';
+  try {
+    if (fs.existsSync(path.join(home, '.codex', 'auth.json'))) return 'subscription';
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+// The config that ARMS the F5 hook. enabled:true is the whole point — the hook
+// no-ops without this file.
+function autodelegateConfig({ threshold = 80, budget = null, invocation = 'codex:codex-rescue --model gpt-5.4' } = {}) {
+  return {
+    enabled: true,
+    threshold,
+    budget,
+    invocation,
+    model: 'gpt-5.4',
+    note: 'Written by the BYAN installer (F4). Delete or set enabled:false to disarm auto-delegation.',
+  };
+}
+
+function writeAutodelegateConfig({ projectRoot, config, fs = realFs, path = realPath }) {
+  const dir = path.join(projectRoot, '_byan', '_config');
+  fs.mkdirSync(dir, { recursive: true });
+  const p = path.join(dir, 'autodelegate.json');
+  fs.writeFileSync(p, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return p;
+}
+
+// Orchestrate the opt-in step. Called only when the user chose "add a Codex
+// backup" at install. Arms the hook when Codex is linked; otherwise leaves it
+// disarmed and surfaces the device-flow so the link can be completed and the
+// installer re-run. Never throws on a link check — an unlinked Codex is a normal
+// outcome, not an installer failure.
+async function setupCodexAutodelegate(projectRoot, options = {}) {
+  const log = options.quiet ? () => {} : (...a) => console.log(...a);
+  const fs = options.fs || realFs;
+  const path = options.path || realPath;
+
+  const auth = codexAuthState({ fs, path, home: options.home });
+  if (!auth) {
+    log(paint('yellow', '  ! Codex not linked - auto-delegation left DISARMED'));
+    log(paint('gray', `    ${DEVICE_FLOW_INSTRUCTION.replace(/\n/g, '\n    ')}`));
+    return { armed: false, reason: 'codex-not-linked' };
+  }
+
+  const config = autodelegateConfig(options);
+  config.linkedVia = auth;
+  const p = writeAutodelegateConfig({ projectRoot, config, fs, path });
+  log(paint('green', `  + Codex auto-delegation ARMED (${auth}) -> ${p}`));
+  log(paint('gray', '    BYAN will now propose handing delegable work to Codex (no API credit).'));
+  return { armed: true, path: p, authPool: auth, config };
+}
+
+module.exports = {
+  DEVICE_FLOW_INSTRUCTION,
+  codexAuthState,
+  autodelegateConfig,
+  writeAutodelegateConfig,
+  setupCodexAutodelegate,
+};

package/install/templates/.claude/hooks/codex-autodelegate.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit hook — Codex auto-delegation nudge (F5).
+ *
+ * Every turn, estimates Claude's rolling-5h consumption (F1 usage-estimator) and
+ * asks the pure decision core (F5 autodelegate-decision) whether to nudge BYAN to
+ * hand delegable work to Codex — on the ChatGPT subscription, no API credit. The
+ * nudge is ADVISORY context only: it proposes, never forces, and always names the
+ * red line (delegable work only; judgment/soul/verify stay on Claude).
+ *
+ * DISARMED BY DEFAULT. The hook no-ops unless `_byan/_config/autodelegate.json`
+ * exists with `enabled: true` (written by the yanstaller F4 when the user opts
+ * into a Codex backup). No config file -> silence. This keeps it from nagging on
+ * machines where Codex is not set up, and honors "only once the user chose it at
+ * install".
+ *
+ * Escape hatch: a `.byan-codex-autodelegate/off` file in the project root forces
+ * silence even when enabled. Always exits 0; never blocks prompt submission.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readStdin, parseJson } = require('./lib/strict-runtime');
+const { decideAutodelegation, renderNudge } = require('./lib/autodelegate-decision');
+const { estimateClaudeUsage } = require('./lib/usage-estimator');
+
+// Load the opt-in config; absent/invalid -> disarmed ({ enabled: false }).
+function loadConfig(projectRoot) {
+  try {
+    const p = path.join(projectRoot, '_byan', '_config', 'autodelegate.json');
+    if (!fs.existsSync(p)) return { enabled: false };
+    const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return cfg && typeof cfg === 'object' ? cfg : { enabled: false };
+  } catch {
+    return { enabled: false };
+  }
+}
+
+function toggledOff(projectRoot) {
+  try {
+    return fs.existsSync(path.join(projectRoot, '.byan-codex-autodelegate', 'off'));
+  } catch {
+    return false;
+  }
+}
+
+if (require.main === module) {
+  (async () => {
+    let additionalContext = '';
+    try {
+      const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      const config = loadConfig(projectRoot);
+      if (config.enabled === true && !toggledOff(projectRoot)) {
+        const payload = parseJson(await readStdin());
+        const prompt = payload.prompt || payload.user_prompt || payload.userPrompt || '';
+        // Estimate usage only when a budget is configured; else pct stays null and
+        // the decision falls back to nature-based delegation (still useful).
+        const usage = estimateClaudeUsage({ budget: config.budget || null });
+        const decision = decideAutodelegation({ requestText: prompt, usage, config });
+        additionalContext = renderNudge(decision);
+      }
+    } catch {
+      additionalContext = ''; // never block prompt submission
+    }
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext },
+      })
+    );
+    process.exit(0);
+  })();
+}
+
+module.exports = { loadConfig, toggledOff };

package/install/templates/.claude/hooks/lib/autodelegate-decision.js

@@ -0,0 +1,152 @@
+/**
+ * autodelegate-decision — the pure core that decides whether BYAN should hand a
+ * task to Codex (on the ChatGPT subscription, no API credit), and how hard to
+ * push. Two triggers, honest about their strength:
+ *
+ *   1. NATURE (always available, no gauge needed): the request looks like
+ *      delegable coding work (implement / write / fix / refactor / test) -> mode
+ *      'delegable-only', propose handing THIS task to Codex.
+ *   2. PRESSURE (only when a usage gauge is supplied): the estimated Claude 5h
+ *      consumption is at/above the threshold (default 80%) -> mode 'all', propose
+ *      offloading everything delegable to spare the remaining budget.
+ *   3. PERF (opt-in, off by default): a config-driven forces table says Codex is
+ *      reputed stronger for this kind of task -> mode 'perf-routed'. Honest: this
+ *      is a heuristic below BYAN's L2 perf floor, so it ships neutral (empty
+ *      table) and asserts nothing until the user populates it. See perf-routing.
+ *
+ * The red line is never crossed: only DELEGABLE natures are ever proposed —
+ * judgment / analysis / soul / verification stay on Claude. This module states
+ * that in `redLine` so the hook's nudge always carries it. Pure (no I/O): the
+ * hook is a thin shell that feeds it the request text + the F1 usage estimate.
+ */
+
+const { perfFavors } = require('./perf-routing');
+
+const DEFAULT_THRESHOLD = 80;
+const DEFAULT_INVOCATION = 'codex:codex-rescue --model gpt-5.4';
+const RED_LINE = 'delegable work only (code / mechanical) — judgment, analysis, soul and verification stay on Claude';
+
+// Verbs/nouns that mark a delegable coding task. Heuristic by construction (free
+// text has no nature field); kept deliberately conservative so conversational or
+// judgment requests do not trip it.
+const DELEGABLE_RE = new RegExp(
+  [
+    'code', 'coder', 'impl[ée]mente', 'implement', '[ée]cris', 'write', 'wire',
+    'fix', 'corrige', 'debug', 'd[ée]bogue', 'refactor', 'refactorise',
+    'test', 'tests', 'script', 'module', 'fonction', 'function', 'patch',
+    'ajoute\\s+(le|la|un|une|du)', 'build\\s+(the|a|le|la)', 'port',
+  ].join('|'),
+  'i'
+);
+
+function looksDelegable(text) {
+  return DELEGABLE_RE.test(String(text || ''));
+}
+
+// Decide the auto-delegation posture for one turn.
+// Returns { delegate, mode, pct, reason, redLine, invocation } — a stable shape.
+// mode: 'off' | 'all' | 'delegable-only' | 'none'.
+function decideAutodelegation({ requestText = '', usage = null, config = {} } = {}) {
+  const {
+    enabled = true,
+    threshold = DEFAULT_THRESHOLD,
+    invocation = DEFAULT_INVOCATION,
+  } = config;
+
+  if (!enabled) {
+    return { delegate: false, mode: 'off', pct: null, reason: 'auto-delegation disabled (toggle off)', redLine: RED_LINE, invocation };
+  }
+
+  const pct = usage && typeof usage.pct === 'number' ? usage.pct : null;
+  const delegable = looksDelegable(requestText);
+
+  if (pct != null && pct >= threshold) {
+    return {
+      delegate: true,
+      mode: 'all',
+      pct,
+      reason: `estimated Claude 5h usage ${pct}% >= ${threshold}% — propose offloading everything delegable to Codex`,
+      redLine: RED_LINE,
+      invocation,
+    };
+  }
+
+  if (delegable) {
+    return {
+      delegate: true,
+      mode: 'delegable-only',
+      pct,
+      reason: 'request looks like delegable coding work — propose handing it to Codex to spare the Claude 5h budget',
+      redLine: RED_LINE,
+      invocation,
+    };
+  }
+
+  // PERF (opt-in): the forces table (user-populated) may favor Codex for this
+  // kind of task even at low pressure. Off by default; always heuristic.
+  if (config.perfRouting) {
+    const pf = perfFavors(requestText, config.perfForces || []);
+    if (pf.favors === 'codex') {
+      return {
+        delegate: true,
+        mode: 'perf-routed',
+        pct,
+        reason: `perf heuristic favors Codex for '${pf.category}' (heuristic, NOT a measured benchmark)`,
+        redLine: RED_LINE,
+        invocation,
+      };
+    }
+  }
+
+  return {
+    delegate: false,
+    mode: 'none',
+    pct,
+    reason: pct != null
+      ? `usage ${pct}% below ${threshold}% and task not clearly delegable`
+      : 'task not clearly delegable and no usage gauge available',
+    redLine: RED_LINE,
+    invocation,
+  };
+}
+
+// Defense-in-depth: the invocation string is interpolated into BYAN's injected
+// context. It is config/installer-controlled today (safe), but sanitising before
+// interpolation closes the door on any future path feeding untrusted text in —
+// strip newlines/control chars (no context-structure injection) and cap length.
+function sanitizeForContext(value, max = 120) {
+  return String(value == null ? "" : value)
+    .replace(/[\u0000-\u001F\u007F]+/g, " ") // control chars + newlines -> space
+    .replace(/\s+/g, " ")                       // collapse whitespace runs
+    .trim()
+    .slice(0, max);
+}
+
+// Render a decision into the one-paragraph nudge injected into BYAN's context.
+// Empty string when there is nothing to propose (so the hook injects nothing).
+// The nudge is ADVISORY: it proposes, it never forces — BYAN still owns the call
+// and the red line is spelled out every time.
+function renderNudge(decision) {
+  if (!decision || !decision.delegate) return '';
+  const gauge = decision.pct != null ? ` (estimated Claude 5h usage ~${decision.pct}%)` : '';
+  const invocation = sanitizeForContext(decision.invocation) || DEFAULT_INVOCATION;
+  const scope = decision.mode === 'all'
+    ? 'Consider offloading ALL delegable work this session to Codex'
+    : decision.mode === 'perf-routed'
+      ? 'Codex is heuristically favored for this kind of task (not a measured benchmark) — consider handing it over'
+      : 'This looks like delegable coding work — consider handing it to Codex';
+  return [
+    `[BYAN auto-delegate]${gauge}: ${scope} via \`${invocation}\` `
+      + '(runs on the ChatGPT subscription, no API credit).',
+    `Red line: ${decision.redLine}. This is advisory — you decide, and you still verify Codex's output before commit.`,
+  ].join(' ');
+}
+
+module.exports = {
+  DEFAULT_THRESHOLD,
+  DEFAULT_INVOCATION,
+  RED_LINE,
+  looksDelegable,
+  decideAutodelegation,
+  renderNudge,
+};

package/install/templates/.claude/hooks/lib/perf-routing.js

@@ -0,0 +1,47 @@
+/**
+ * perf-routing — the MECHANISM for routing a task to the pool reputed stronger
+ * for it, WITHOUT asserting an unsourced ranking.
+ *
+ * The honest ceiling (BYAN fact-check, performance domain): "model X is better
+ * at task Y" needs L2 evidence (a reproducible benchmark). A community arena such
+ * as designarena.ai is preference-vote data — below that floor. So this module
+ * ships a NEUTRAL default (DEFAULT_FORCES = []): out of the box it claims nothing
+ * and changes no routing. It provides the config-driven forces table + a matcher;
+ * populating the table with rankings (from the user's own benchmarks, or an arena
+ * taken as a weak signal) is an explicit opt-in, and every result it returns is
+ * tagged `confidence: 'heuristic'` so downstream never presents it as measured.
+ *
+ * A forces entry: { category, pattern (regex source, case-insensitive), favors:
+ * 'codex' | 'claude' }. Pure — no I/O.
+ */
+
+// Neutral by default: no unsourced perf claim ships. Populate via config.
+const DEFAULT_FORCES = [];
+
+// Return the first forces entry whose pattern matches the text, or null.
+// Malformed entries (missing pattern/favors, or an invalid regex) are skipped.
+function matchCategory(text, forces = DEFAULT_FORCES) {
+  const s = String(text || '');
+  if (!Array.isArray(forces)) return null;
+  for (const entry of forces) {
+    if (!entry || !entry.pattern || !entry.favors) continue;
+    let re;
+    try {
+      re = new RegExp(entry.pattern, 'i');
+    } catch {
+      continue; // invalid regex in a user-supplied table — skip, never throw
+    }
+    if (re.test(s)) return entry;
+  }
+  return null;
+}
+
+// Resolve the perf preference for a text: which pool the (user-supplied) table
+// favors, always tagged heuristic. { favors: 'codex'|'claude'|null, category, confidence }.
+function perfFavors(text, forces = DEFAULT_FORCES) {
+  const hit = matchCategory(text, forces);
+  if (!hit) return { favors: null, category: null, confidence: 'heuristic' };
+  return { favors: hit.favors, category: hit.category, confidence: 'heuristic' };
+}
+
+module.exports = { DEFAULT_FORCES, matchCategory, perfFavors };