create-byan-agent 2.39.0 → 2.42.0

package/install/templates/_byan/mcp/byan-mcp-server/lib/tier-script.js

@@ -0,0 +1,104 @@
+// Per-script tiering report + gate decision (the engine under the tier hook
+// and the byan-tier-script bin).
+//
+// The Workflow tool runs every agent() leaf on the session model unless the
+// script pins opts.model, and the sandbox forbids importing native-tiers at
+// runtime — so the ONLY moment the tiering doctrine can reach an AD-HOC script
+// is when the script text crosses the Workflow tool boundary. This module
+// analyzes that text: one verdict per statically-labelled leaf, against the
+// same source of truth the repo linter enforces (native-tiers.js).
+//
+// The gate is deny-ONCE and never rewrites the script (STRICT-2 No Downgrade:
+// a wrong auto-stamp would be the exact regression the doctrine forbids). The
+// author fixes the listed leaves, or asserts the deep choices are deliberate
+// with the acknowledgment marker. An identical resubmission after a deny
+// passes — the gate forces a decision, it does not trap the turn.
+
+import crypto from 'node:crypto';
+import { classifyLeaf, tierFor, TIER_MODEL, TIERS, LEAF_TYPES } from './native-tiers.js';
+import { stripComments, extractLabelledLeaves } from './workflows-lint.js';
+
+// Acknowledgment marker, raw-text (comment form survives comment-stripping
+// concerns by design — mirrors the BYAN-BENCH marker family). Writing it is an
+// explicit authoring act: "I reviewed the tiering; the deep leaves are
+// deliberate."
+export const ACK_RE = /BYAN-TIER:\s*reviewed\b/;
+
+function verdictFor(cls, model) {
+  const expected = TIER_MODEL[tierFor(cls)]; // 'haiku' | 'sonnet' | null (inherit)
+  if (expected === null) {
+    // Protected class: any pinned model is a downgrade or a pin-up — both wrong.
+    return model === null ? 'ok' : 'violation';
+  }
+  if (model === null) return 'missing-tier';
+  if (model === expected) return 'ok';
+  // Exploration may ride ABOVE its floor (sonnet on a cheap leaf wastes a
+  // little, breaks nothing). Anything else — haiku on mech-, opus anywhere —
+  // is below a declared tier or an unknown pin.
+  if (cls === LEAF_TYPES.EXPLORATION && model === TIER_MODEL[TIERS.BALANCED]) return 'ok';
+  return 'violation';
+}
+
+// analyzeScript(src) -> { acknowledged, agentCalls, leaves, gaps, violations }
+// leaves: [{ label, model, class, expectedModel, verdict }] for every
+// statically-labelled opts object. Unlabelled agent() calls classify to the
+// deep default and cannot gap, so they are only counted (agentCalls).
+export function analyzeScript(src) {
+  const leaves = extractLabelledLeaves(src).map(({ label, model }) => {
+    const cls = classifyLeaf({ label });
+    return {
+      label,
+      model,
+      class: cls,
+      expectedModel: TIER_MODEL[tierFor(cls)],
+      verdict: verdictFor(cls, model),
+    };
+  });
+  return {
+    acknowledged: ACK_RE.test(String(src)),
+    agentCalls: (stripComments(src).match(/\bagent\s*\(/g) || []).length,
+    leaves,
+    gaps: leaves.filter((l) => l.verdict === 'missing-tier'),
+    violations: leaves.filter((l) => l.verdict === 'violation'),
+  };
+}
+
+// One line per offending leaf, then the two exits (fix or acknowledge). The
+// reason is the whole teaching surface of the gate — it must carry the exact
+// label and the exact value to write.
+export function formatGateReason(analysis) {
+  const lines = ['BYAN tier gate: this workflow script has undecided or invalid model tiers.'];
+  for (const g of analysis.gaps) {
+    lines.push(`- leaf '${g.label}' (${g.class}) has no model: add model: '${g.expectedModel}'`);
+  }
+  for (const v of analysis.violations) {
+    const fix = v.expectedModel === null ? 'omit model: (deep leaves inherit the session model)' : `use model: '${v.expectedModel}'`;
+    lines.push(`- leaf '${v.label}' (${v.class}) carries model: '${v.model}': ${fix}`);
+  }
+  lines.push(
+    "Fix the listed leaves, or add the comment '// BYAN-TIER: reviewed' to assert the current tiers are deliberate. This gate denies once: an identical resubmission passes."
+  );
+  return lines.join('\n');
+}
+
+// Pure gate decision (the hook is only the I/O shell around this).
+// Precedence: escape hatch > acknowledgment > clean > deny-once memory > deny.
+export function decideTierGate({ analysis, escaped = false, scriptHash = null, priorDenyHash = null } = {}) {
+  if (escaped) return { decision: 'allow', code: 'escape-hatch' };
+  if (analysis.acknowledged) return { decision: 'allow', code: 'acknowledged' };
+  if (analysis.gaps.length === 0 && analysis.violations.length === 0) {
+    return { decision: 'allow', code: 'clean' };
+  }
+  if (scriptHash && priorDenyHash && scriptHash === priorDenyHash) {
+    return { decision: 'allow', code: 'unchanged-after-deny' };
+  }
+  return {
+    decision: 'deny',
+    code: analysis.violations.length ? 'violations' : 'gaps',
+    reason: formatGateReason(analysis),
+  };
+}
+
+export function hashScript(src) {
+  return crypto.createHash('sha1').update(String(src)).digest('hex');
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/workflows-lint.js

@@ -12,7 +12,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { isKnownTierModel, isDowngradeModel, classifyLeaf, LEAF_TYPES } from './native-tiers.js';
+import { isKnownTierModel, isDowngradeModel, classifyLeaf, LEAF_TYPES, TIER_MODEL } from './native-tiers.js';
 
 // Strip /* block */ and // line comments. Preserve "://" inside strings (URLs)
 // by only treating // as a comment when not preceded by a colon.
@@ -104,6 +104,30 @@ export function metaLiteralViolations(src) {
 const MODEL_RE = /\bmodel:\s*(['"`])([^'"`]*)\1/g;
 const LABEL_RE = /\blabel:\s*(['"`])([^'"`]*)\1/g;
 
+// Remove the `export const meta = { ... }` literal before scanning model
+// tokens. The harness meta spec allows `model` on a phases entry (a per-phase
+// display/override declaration) — it carries no label by design and must not
+// read as a leaf downgrade. Balanced-brace walk; no-op when unbalanced.
+// String-unaware by choice: a brace inside a meta string unbalances the walk,
+// which then no-ops and the meta model token stays visible to the scan — the
+// failure mode OVER-reports (fails closed), never hides a real violation.
+// Exported: the routing integration test scans sources with its own regexes
+// (an independent double-check) but must share THIS meta-handling.
+export function stripMetaLiteral(code) {
+  const start = code.search(/export const meta\s*=\s*\{/);
+  if (start === -1) return code;
+  const open = code.indexOf('{', start);
+  let depth = 0;
+  for (let i = open; i < code.length; i++) {
+    if (code[i] === '{') depth += 1;
+    else if (code[i] === '}') {
+      depth -= 1;
+      if (depth === 0) return code.slice(0, open + 1) + code.slice(i);
+    }
+  }
+  return code;
+}
+
 function nearestLabelBefore(code, modelIndex) {
   const before = code.slice(0, modelIndex);
   let last = null;
@@ -120,7 +144,7 @@ function nearestLabelBefore(code, modelIndex) {
 }
 
 export function modelRoutingViolations(src) {
-  const code = stripComments(src);
+  const code = stripMetaLiteral(stripComments(src));
   const out = [];
   let m;
   MODEL_RE.lastIndex = 0;
@@ -137,14 +161,56 @@ export function modelRoutingViolations(src) {
     if (!label) {
       out.push({
         id: 'downgrade-without-label',
-        msg: `a model downgrade ('${model}') must sit on a labelled exploration leaf; no label found in this opts object`,
+        msg: `a model downgrade ('${model}') must sit on a labelled exploration/mech- leaf; no label found in this opts object`,
       });
       continue;
     }
-    if (isDowngradeModel(model) && classifyLeaf({ label }) !== LEAF_TYPES.EXPLORATION) {
+    if (!isDowngradeModel(model)) continue;
+    // Per-class floor: exploration accepts any downgrade tier (haiku or sonnet,
+    // both at-or-above its cheap floor); a mech- leaf accepts exactly the
+    // balanced tier (haiku would sit BELOW the tier its label declares); every
+    // protected class refuses both (STRICT-2 No Downgrade).
+    const cls = classifyLeaf({ label });
+    if (cls === LEAF_TYPES.EXPLORATION) continue;
+    if (cls === LEAF_TYPES.MECHANICAL) {
+      if (model !== TIER_MODEL.balanced) {
+        out.push({
+          id: 'mechanical-below-tier',
+          msg: `mech- leaf '${label}' carries '${model}' but the mechanical tier is '${TIER_MODEL.balanced}'; a declared-mechanical check must not drop further`,
+        });
+      }
+      continue;
+    }
+    out.push({
+      id: 'protected-leaf-downgraded',
+      msg: `leaf '${label}' is protected (${cls}) but carries downgrade model '${model}'; only exploration (read/load/parse/detect) and explicit mech- leaves may downgrade (STRICT-2 No Downgrade)`,
+    });
+  }
+  return out;
+}
+
+// MECHANICAL opt-in consistency (HARD rule, part of validateContract).
+//
+// A mech- label is an explicit authoring declaration: "this check is binary and
+// judgment-free, run it on the balanced tier". Declaring it and then omitting
+// opts.model half-applies the opt-in — the leaf silently runs deep, which is
+// exactly the waste the label promised to avoid. Since the prefix exists only
+// as this convention (no legacy labels carry it), enforcing it hard cannot trip
+// legitimate work. Order-independent via sameOptsObjectText, comment-stripped.
+export function mechanicalLabelViolations(src) {
+  const code = stripComments(src);
+  const out = [];
+  let m;
+  LABEL_RE.lastIndex = 0;
+  while ((m = LABEL_RE.exec(code))) {
+    const label = m[2];
+    if (classifyLeaf({ label }) !== LEAF_TYPES.MECHANICAL) continue;
+    const objText = sameOptsObjectText(code, m.index, m.index + m[0].length);
+    MODEL_RE.lastIndex = 0;
+    if (!MODEL_RE.exec(objText)) {
       out.push({
-        id: 'protected-leaf-downgraded',
-        msg: `leaf '${label}' is not exploration but carries downgrade model '${model}'; only read/load/parse/detect leaves may downgrade (STRICT-2 No Downgrade)`,
+        id: 'mechanical-without-model',
+        msg: `mech- leaf '${label}' declares a mechanical check but omits opts.model; add model: '${TIER_MODEL.balanced}' (or drop the mech- prefix if the check bears judgment)`,
       });
     }
   }
@@ -208,6 +274,25 @@ export function untieredExplorationViolations(src) {
   return out;
 }
 
+// Shared parsing primitive — every statically-labelled opts object with its
+// order-independent model (or null). This is the ONE place that knows how to
+// read agent() opts out of a script source; tier-script.js (the per-leaf
+// report + hook gate) consumes it instead of re-owning the regexes. Fresh
+// regex instances per call: no shared lastIndex across modules.
+export function extractLabelledLeaves(src) {
+  const code = stripComments(src);
+  const out = [];
+  const labelRe = new RegExp(LABEL_RE.source, 'g');
+  let m;
+  while ((m = labelRe.exec(code))) {
+    const objText = sameOptsObjectText(code, m.index, m.index + m[0].length);
+    const modelRe = new RegExp(MODEL_RE.source, 'g');
+    const mm = modelRe.exec(objText);
+    out.push({ label: m[2], model: mm ? mm[2] : null });
+  }
+  return out;
+}
+
 // Full native-workflow contract: state-coupling (comment-stripped) + clock/RNG
 // (raw) + meta-literal-first + model-routing anti-downgrade. Returns the
 // combined [{ id, msg }] violations.
@@ -226,6 +311,7 @@ export function validateContract(src) {
     ...clockRngViolations(src),
     ...metaLiteralViolations(src),
     ...modelRoutingViolations(src),
+    ...mechanicalLabelViolations(src),
   ];
 }
 

package/install/templates/_byan/mcp/byan-mcp-server/server.js

@@ -8,7 +8,7 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import { dispatch } from './lib/dispatch.js';
+import { dispatch, dispatchBatch } from './lib/dispatch.js';
 import { resolveConfig } from './lib/resolve-config.js';
 import { harvest as harvestInsights, renderDigest as renderInsightDigest } from './lib/insight-harvest.js';
 import { appendOutcome } from './lib/outcome-buffer.js';
@@ -333,11 +333,11 @@ const tools = [
   {
     name: 'byan_dispatch',
     description:
-      'BYAN Dispatcher: routes a unit of work along two independent axes. STRATEGY (where it runs: main-thread / agent-subagent-worktree / mcp-worker) from the scalar score + parallelizable. TIER (which model) from the task NATURE via native-tiers (the single source of truth): only exploration downgrades to haiku; implementation/verification/analysis stay deep (inherit the session model); never pins up to opus. Rule-based, no API call. Returns { score, strategy, nature, tier, model, reasoning }.',
+      'BYAN Dispatcher: routes a unit of work along two independent axes. STRATEGY (where it runs: main-thread / agent-subagent-worktree / mcp-worker) from the scalar score + parallelizable. TIER (which model) from the task NATURE via native-tiers (the single source of truth): exploration downgrades to haiku, explicit mechanical checks to sonnet; implementation/verification/analysis stay deep (inherit the session model); never pins up to opus. Rule-based, no API call. Returns { score, strategy, nature, tier, model, reasoning }. BATCH mode: pass `leaves` (array of { label, nature? }) to tier every agent() leaf of a workflow script BEFORE writing it — returns one { label, nature, tier, model } per leaf, no strategy axis.',
     inputSchema: {
       type: 'object',
       properties: {
-        task: { type: 'string', description: 'Short task description.' },
+        task: { type: 'string', description: 'Short task description. Required unless `leaves` is passed (batch mode).' },
         complexity: {
           type: 'number',
           description: 'Complexity score 0-100 (optional, will estimate from task length if absent).',
@@ -348,11 +348,26 @@ const tools = [
         },
         nature: {
           type: 'string',
-          enum: ['exploration', 'implementation', 'verification', 'analysis'],
-          description: 'Optional task nature. A valid value sets the model tier directly; otherwise the nature is classified from the task text. Only exploration is downgrade-safe.',
+          enum: ['exploration', 'mechanical', 'implementation', 'verification', 'analysis'],
+          description: 'Optional task nature. A valid value sets the model tier directly; otherwise the nature is classified from the task text. Exploration (haiku) and mechanical (sonnet) are the only downgrade-safe natures.',
+        },
+        leaves: {
+          type: 'array',
+          description: 'Batch mode: the planned agent() leaves of a workflow script, each { label, nature? }. Returns the opts.model value per leaf; write model: only where it is non-null.',
+          items: {
+            type: 'object',
+            properties: {
+              label: { type: 'string', description: 'The leaf label (the curated signal classifyLeaf keys on).' },
+              nature: {
+                type: 'string',
+                enum: ['exploration', 'mechanical', 'implementation', 'verification', 'analysis'],
+                description: 'Optional explicit nature; wins over label classification.',
+              },
+            },
+            additionalProperties: false,
+          },
         },
       },
-      required: ['task'],
       additionalProperties: false,
     },
   },
@@ -1561,7 +1576,7 @@ export function createByanServer({ token, remoteOnly = false } = {}) {
     }
 
     if (name === 'byan_dispatch') {
-      const result = dispatch(args);
+      const result = Array.isArray(args.leaves) ? dispatchBatch(args.leaves) : dispatch(args);
       return {
         content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
       };

package/install/templates/_byan/mcp/byan-mcp-server/skill-bundles-manifest.json

@@ -94,7 +94,7 @@
       "name": "byan-byan",
       "module": "core",
       "tier": "connector-bound",
-      "sourceHash": "88403d60531d9fb3e7cdb566429643f1f47baf9918593e8082ecc98eedebb878"
+      "sourceHash": "6798beb68df9831e0b9bf3ca17100174316c51b2671d96b2ef5bff6def4eabc7"
     },
     "byan-byan-v2": {
       "name": "byan-byan-v2",
@@ -154,7 +154,7 @@
       "name": "byan-codex",
       "module": "core",
       "tier": "standalone",
-      "sourceHash": "0f0d7a1108a43a0c0c8093cc5600bc2649d6766c6ae94c2a2a9dafa315180627"
+      "sourceHash": "32f2ae4a9bfe7a0f90f2ca9787e472c57b847bc36ac9bc6fa0050af70c0af27c"
     },
     "byan-drawio": {
       "name": "byan-drawio",
@@ -184,7 +184,7 @@
       "name": "byan-hermes-dispatch",
       "module": "core",
       "tier": "connector-bound",
-      "sourceHash": "45003e8a525a792d1a5dbe34ecb8e1443061fa5036a81a38a841598ce5aaf5ff"
+      "sourceHash": "e890a80916fedcf888170f550fc4d7ce289f6dc15243d00675e72e80c8579fdb"
     },
     "byan-insight": {
       "name": "byan-insight",

package/install/templates/_byan/workflow/simple/byan/project-handoff-workflow.md

@@ -0,0 +1,90 @@
+---
+name: project-handoff
+description: "Export/import portable Markdown project state between Claude Code and Codex"
+version: "1.0.0"
+module: byan
+phases: 4
+---
+
+# BYAN Project Handoff Workflow
+
+## Purpose
+
+Use this workflow when a BYAN session must move between Claude Code and Codex,
+usually because one assistant is close to a usage limit. The handoff artifact is
+a Markdown file under `_byan-output/handoffs/`; it is portable repo state, not
+native assistant memory.
+
+## Contract
+
+- Source of truth: repository files plus `_byan/` and `_byan-output/`.
+- Artifact: `_byan-output/handoffs/<timestamp>-<from>-to-<to>-<task>.md`.
+- Format: human-readable Markdown with a parseable `json byan-handoff` block.
+- Direction: Claude -> Codex and Codex -> Claude use the same format.
+- Native memories (`~/.claude`, `~/.codex`) may help locally but are not needed
+  to resume.
+
+## Commands
+
+Export from the current assistant:
+
+```bash
+byan-handoff export --from claude --to codex \
+  --task "current feature" \
+  --summary "what happened so far" \
+  --next "first action for the next assistant"
+```
+
+Import on the next assistant:
+
+```bash
+byan-handoff latest --from claude --prompt
+```
+
+Or import a specific file:
+
+```bash
+byan-handoff import _byan-output/handoffs/<file>.md --prompt
+```
+
+## Phase 1: Export
+
+1. Re-read the active request and any locked BYAN strict scope.
+2. Run `byan-handoff export` with explicit `--from`, `--to`, `--task`,
+   `--summary`, and at least one `--next`.
+3. Add useful optional details:
+   - `--decision "..."` for architectural or product decisions.
+   - `--command "..."` for tests or checks already run.
+   - `--blocker "..."` for gaps, failures, or risks.
+   - `--note "..."` for context the next assistant should not rediscover.
+4. Report the generated file path to the user.
+
+## Phase 2: Transfer
+
+The user opens the same repository with the other assistant. No hidden copy step
+is required when both assistants share the same working tree. If the handoff is
+moving to another machine, copy the Markdown file with the repo or paste its
+`Resume Prompt` section.
+
+## Phase 3: Import
+
+1. Run `byan-handoff latest --from <source> --prompt` or
+   `byan-handoff import <file> --prompt`.
+2. Treat the printed prompt as the starting context.
+3. Inspect the listed files before editing.
+4. Check `_byan-output/fd-state.json` and strict status if the handoff names an
+   active FD.
+
+## Phase 4: Continue
+
+1. Continue from the `Next Actions` section.
+2. Update the same FD rather than starting a parallel one unless the handoff says
+   the old FD is complete or aborted.
+3. Before switching back, create a new handoff in the opposite direction.
+
+## Validation Checklist
+
+- [ ] Handoff file exists under `_byan-output/handoffs/`.
+- [ ] `byan-handoff latest --from <source> --prompt` prints a usable resume prompt.
+- [ ] The next assistant inspected files listed in `Files Touched`.
+- [ ] Any strict-mode gaps are surfaced, not hidden.

package/install/templates/docs/codex-auto-delegation.md

@@ -0,0 +1,140 @@
+# Codex Auto-Delegation
+
+Hand delegable work to Codex on your **ChatGPT subscription** (no API credit)
+when Claude nears its 5h limit — automatically, from inside Claude Code.
+
+This is the native, opt-in layer on top of the Codex load-balancer pool
+(`docs/loadbalancer-multipool.md`). It does not replace judgment: only delegable
+work crosses the line.
+
+## What it does
+
+Every turn, a `UserPromptSubmit` hook estimates how much of the Claude 5h window
+you have burned and looks at the task you just asked for. If the task is
+delegable (code / mechanical) — or if you are over the pressure threshold — BYAN
+injects a one-line advisory nudge proposing you hand it to Codex via
+`codex:codex-rescue --model gpt-5.4`. You still decide, and you still verify
+Codex's output before commit.
+
+Three triggers, in priority order:
+
+1. **Pressure** — estimated Claude 5h usage `>= threshold` (default **80%**) ->
+   propose offloading **everything** delegable this session.
+2. **Nature** — the request looks like delegable coding work -> propose handing
+   **that** task over. Works with no gauge at all.
+3. **Perf** (opt-in, off by default) — a configurable forces table says Codex is
+   reputed stronger for this kind of task. See "Perf routing" below.
+
+**The red line** (held): only delegable natures are proposed. Judgment,
+analysis, soul and verification stay on Claude.
+
+## Enable it
+
+At install (`npx create-byan-agent`), the Codex step asks:
+
+> Add Codex as a backup pool?
+
+Before that optional backup-pool prompt, the yanstaller performs the native Codex
+setup whenever Codex is selected (Codex-only or Claude+Codex):
+
+1. it writes the BYAN MCP entry into `~/.codex/config.toml`;
+2. it installs BYAN's native Codex skills into `~/.codex/skills`, including the
+   `byan` entrypoint skill used by `$byan`;
+3. it keeps the project-local `.codex/prompts/` stubs for backward
+   compatibility.
+
+If `~/.codex` does not exist yet, the yanstaller creates it because Codex was
+explicitly selected.
+
+Those are separate from auto-delegation. Without the native skills, Codex may
+have the MCP server wired but still fail to expose `$byan` / BYAN skill
+invocations on a fresh machine.
+
+Answer yes to the backup-pool prompt and it links your local Codex (the
+`codex login` session — your ChatGPT subscription, **not** an API key) and writes
+`_byan/_config/autodelegate.json`, which **arms** the hook. Without that file the
+hook is a silent no-op (disarmed by default).
+
+Non-interactive install: set `BYAN_CODEX_AUTODELEGATE=1`.
+
+If Codex is not linked yet, the installer prints the device-flow to run on the
+machine (needed on a headless server, where the default localhost browser
+redirect fails):
+
+```
+codex login --device-auth
+```
+
+then re-run the installer.
+
+### The entitled model (why gpt-5.4)
+
+On a ChatGPT subscription the OpenAI backend rejects every `-codex`-suffixed
+model (`gpt-5-codex`, `gpt-5.x-codex`) — those ids are API-key only. The plain
+`gpt-5.x` family (e.g. `gpt-5.4`) is the entitled one. That is why the invocation
+pins `--model gpt-5.4`. See `src/loadbalancer/providers/codex-provider.js`
+(`resolveCodexModel`).
+
+## Configure it
+
+`_byan/_config/autodelegate.json`:
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `enabled` | `true` (once written) | Master switch. Delete the file or set `false` to disarm. |
+| `threshold` | `80` | Pressure percentage that flips to "offload everything delegable". |
+| `budget` | `null` | Your plan's rough token ceiling for the 5h window. Without it, `pct` is null and only the nature trigger fires (see caveat). |
+| `invocation` | `codex:codex-rescue --model gpt-5.4` | What the nudge tells BYAN to run. |
+| `perfRouting` | `false` | Enable the perf trigger. |
+| `perfForces` | `[]` | The forces table (see below). |
+
+Session escape hatch: `touch .byan-codex-autodelegate/off` silences the nudge
+without editing the config; remove it to re-enable.
+
+## The honest caveats
+
+- **The 5h gauge is an ESTIMATE, not Anthropic's number.** No provider exposes a
+  machine-readable 5h quota; `/usage` fetches the authoritative figure live and
+  does not persist it. The estimator sums the real per-message token counts from
+  your local transcripts (`~/.claude/projects/*/*.jsonl`) over the rolling 5h
+  window, weighting cache reads at 0.1 (they are billed roughly a tenth and
+  repeat every turn). It is proportional, not exact — and `pct` is only computed
+  when you set a `budget`. Without a budget, delegation runs on the nature
+  trigger alone.
+- **`~/.claude` is a native accelerator, not a source of truth** (PORTABLE-3).
+  If it is absent the estimator degrades to `pct: null` and the feature falls
+  back to nature-based delegation. The feature keeps working.
+- **Perf routing is a heuristic below the L2 floor.** "Model X is better at task
+  Y" is a performance claim; BYAN's fact-check floor for performance is L2 (a
+  reproducible benchmark). A community arena such as designarena.ai is weaker
+  than that. So the forces table ships empty — it asserts nothing until you
+  populate it, and every match is tagged `heuristic`, not presented as measured.
+
+## Perf routing (opt-in)
+
+Set `perfRouting: true` and fill `perfForces` with entries:
+
+```json
+{
+  "perfRouting": true,
+  "perfForces": [
+    { "category": "bulk-refactor", "pattern": "rename across|codemod", "favors": "codex" }
+  ]
+}
+```
+
+`pattern` is a case-insensitive regex matched against your request. `favors:
+"codex"` pushes a delegation nudge even below the pressure threshold. Populate it
+from your own benchmarks, or from an arena taken as a weak signal — BYAN tags it
+heuristic either way.
+
+## Files
+
+| Piece | File |
+|-------|------|
+| Usage estimator | `.claude/hooks/lib/usage-estimator.js` |
+| Decision core + nudge | `.claude/hooks/lib/autodelegate-decision.js` |
+| Perf routing | `.claude/hooks/lib/perf-routing.js` |
+| Hook | `.claude/hooks/codex-autodelegate.js` |
+| Installer opt-in | `install/lib/codex-autodelegate-setup.js` |
+| Native Codex MCP + skills setup | `install/lib/codex-native-setup.js` |