create-byan-agent 2.39.0 → 2.41.0

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

@@ -73,3 +73,25 @@ export function dispatch({ task, complexity, parallelizable, nature } = {}) {
     reasoning: `${strategyReason}. ${tierReason}.`,
   };
 }
+
+// Batch tiering — the authoring aid for workflow scripts. The author passes the
+// planned leaves BEFORE writing the script and gets the opts.model value per
+// leaf from the same source of truth (native-tiers). No strategy axis here:
+// the leaves all run inside one Workflow invocation, so WHERE they run is the
+// script's concern, only WHICH model each deserves is answered. An explicit
+// valid nature wins; otherwise the label classifies; a miss stays protected
+// (implementation -> deep -> null), same conservative path as dispatch().
+export function dispatchBatch(leaves) {
+  if (!Array.isArray(leaves)) return [];
+  return leaves.map((leaf) => {
+    const { label, nature } = leaf && typeof leaf === 'object' ? leaf : {};
+    const leafType = VALID_NATURES.has(nature) ? nature : classifyLeaf({ label: label || '' });
+    const tier = tierFor(leafType);
+    return {
+      label: label || '',
+      nature: leafType,
+      tier,
+      model: TIER_MODEL[tier],
+    };
+  });
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/native-tiers.js

@@ -28,7 +28,8 @@ export const TIERS = Object.freeze({ CHEAP: 'cheap', BALANCED: 'balanced', DEEP:
 // session runs (Opus by default, but Sonnet if the user chose Sonnet). We never
 // PIN UP — pinning a leaf to a fixed high tier would override the user's session
 // choice and could silently DOWNGRADE a Sonnet/Opus session's heavy leaf. Only
-// cheap/balanced carry a value, and only exploration leaves ever get one.
+// cheap/balanced carry a value: exploration leaves get cheap, explicit mech-
+// leaves get balanced, nothing else ever gets one.
 //
 // Values are the harness model-selection aliases (same set as the Agent tool:
 // 'haiku' | 'sonnet' | 'opus'). They are version-independent. If a future
@@ -36,15 +37,26 @@ export const TIERS = Object.freeze({ CHEAP: 'cheap', BALANCED: 'balanced', DEEP:
 // flags every script literal that drifts from it, so the fan-out stays bounded.
 export const TIER_MODEL = Object.freeze({ cheap: 'haiku', balanced: 'sonnet', deep: null });
 
-// Leaf task-type taxonomy. EXPLORATION is the only downgrade-safe class; the
-// other three are protected (never downgraded).
+// Leaf task-type taxonomy. EXPLORATION and MECHANICAL are the two
+// downgrade-safe classes; the other three are protected (never downgraded).
+// MECHANICAL is verification whose outcome is binary and judgment-free (JSON
+// parses, schema matches, lint passes, a test suite exits 0) — it earns the
+// balanced tier. Semantic/adversarial verification stays VERIFICATION (deep).
 export const LEAF_TYPES = Object.freeze({
   EXPLORATION: 'exploration',
+  MECHANICAL: 'mechanical',
   IMPLEMENTATION: 'implementation',
   VERIFICATION: 'verification',
   ANALYSIS: 'analysis',
 });
 
+// MECHANICAL is opt-in ONLY, through this label prefix ('mech-validate-json').
+// No keyword fuzziness: 'validate-json' without the prefix stays VERIFICATION
+// (protected). The prefix is an explicit authoring act — the author asserts
+// "this check is binary and judgment-free", and the linter can then hold the
+// script to it (a mech- leaf must carry model: 'sonnet', nothing else).
+export const MECHANICAL_PREFIX = 'mech-';
+
 // Label keyword sets, matched as substrings on the leaf LABEL (not the prompt —
 // see classifyLeaf). Protected sets are checked first so any protected signal
 // beats an exploration signal (conservative: when in doubt, do not downgrade).
@@ -73,6 +85,9 @@ function matchesAny(text, keywords) {
 export function classifyLeaf(leaf) {
   const label = String((leaf && leaf.label) || '').toLowerCase();
   if (!label) return LEAF_TYPES.IMPLEMENTATION;
+  // Explicit opt-in beats every keyword class: 'mech-validate-json' contains a
+  // verification keyword, but the author's declared intent is the signal.
+  if (label.startsWith(MECHANICAL_PREFIX)) return LEAF_TYPES.MECHANICAL;
   if (matchesAny(label, VERIFICATION_KEYWORDS)) return LEAF_TYPES.VERIFICATION;
   if (matchesAny(label, ANALYSIS_KEYWORDS)) return LEAF_TYPES.ANALYSIS;
   if (matchesAny(label, IMPLEMENTATION_KEYWORDS)) return LEAF_TYPES.IMPLEMENTATION;
@@ -80,13 +95,15 @@ export function classifyLeaf(leaf) {
   return LEAF_TYPES.IMPLEMENTATION;
 }
 
-// tierFor(taskType) -> a TIERS value. Conservative auto-routing: only EXPLORATION
-// is downgraded (cheap); every other type stays deep. BALANCED is part of the
-// vocabulary but is never auto-assigned — it exists for an explicit, manual
-// opt-in on a leaf an author judges mid-weight. Automation only ever picks
-// cheap or deep.
+// tierFor(taskType) -> a TIERS value. Conservative auto-routing: EXPLORATION
+// downgrades to cheap, MECHANICAL to balanced, every other type stays deep.
+// BALANCED is reachable ONLY through the explicit mech- label opt-in (see
+// MECHANICAL_PREFIX) — never through keyword classification — so automation
+// still cannot land it on judgment-bearing work.
 export function tierFor(taskType) {
-  return taskType === LEAF_TYPES.EXPLORATION ? TIERS.CHEAP : TIERS.DEEP;
+  if (taskType === LEAF_TYPES.EXPLORATION) return TIERS.CHEAP;
+  if (taskType === LEAF_TYPES.MECHANICAL) return TIERS.BALANCED;
+  return TIERS.DEEP;
 }
 
 // modelForLeaf({ label }) -> the opts.model value to write (a string) or null

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": "a0d73cf82fcf228965de722e7d01c785ae79a6382975e3045b4eeb902633062a"
     },
     "byan-byan-v2": {
       "name": "byan-byan-v2",
@@ -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/docs/native-workflows-contract.md

@@ -96,20 +96,29 @@ tier vocabulary, the leaf classifier, and the model map.
 | Tier | `opts.model` | Used for |
 |------|--------------|----------|
 | `deep` | **omitted** (inherit the session model) | implement, verify, analysis — the default |
-| `balanced` | `sonnet` | mid-weight leaf, explicit manual opt-in only |
+| `balanced` | `sonnet` | MECHANICAL verification, opt-in only via the `mech-` label prefix |
 | `cheap` | `haiku` | a pure exploration leaf: read / load / parse / detect |
 
-Two hard rules:
+Three hard rules:
 
 - **No pin-up.** `deep` is an omission, not `model: 'opus'`. Omitting lets a
   leaf inherit whatever the session runs — Opus by default, Sonnet if the user
   chose Sonnet. Pinning a fixed high tier would override that and could silently
   downgrade a Sonnet/Opus session's heavy leaf.
-- **Only exploration downgrades.** A leaf is pinned to `cheap` only when it is
-  unambiguous read/extract work. `classifyLeaf` keys off the LABEL (the prompt
-  is too noisy — an exploration leaf often says "report what you found").
-  Protected types (implementation / verification / analysis) and any unknown
-  label default to `deep`.
+- **Only exploration and mech- downgrade.** A leaf is pinned to `cheap` only
+  when it is unambiguous read/extract work. `classifyLeaf` keys off the LABEL
+  (the prompt is too noisy — an exploration leaf often says "report what you
+  found"). Protected types (implementation / verification / analysis) and any
+  unknown label default to `deep`.
+- **`mech-` is a held declaration.** The `balanced` tier is reachable ONLY
+  through the explicit `mech-` label prefix (`mech-validate-json`): a binary,
+  judgment-free check — JSON parses, schema matches, lint passes — whose FIXING
+  (if any) happens in a different leaf. The prefix wins over keyword
+  classification (that is the point of the opt-in), and the linter holds the
+  script to it: a `mech-` leaf with no model (`mechanical-without-model`) or
+  with `haiku` (`mechanical-below-tier`) is a hard violation. Verification that
+  reads MEANING (content vs requirements, coverage adequacy, adversarial
+  review) is not mechanical and stays deep.
 
 The classifier is permissive (it labels by keyword), so it is a FLOOR, not a
 ceiling: the linter forbids downgrading a protected leaf, but it does not force
@@ -146,13 +155,15 @@ verbatim/gate sink, making the re-read net-negative or marginal.
 Enforcement (because the in-session hooks do not fire inside a script):
 
 - `workflows-lint.js` -> `modelRoutingViolations` rejects (a) a `model:` value
-  that is not a known downgrade tier, (b) a downgrade on a non-exploration leaf
-  (`protected-leaf-downgraded`), (c) a downgrade with no in-object label.
-  It is part of `validateContract`, so `byan-lint-workflows` and the pre-commit
-  gate enforce it.
+  that is not a known downgrade tier, (b) a downgrade on a protected leaf
+  (`protected-leaf-downgraded`), (c) a downgrade with no in-object label,
+  (d) `haiku` on a `mech-` leaf (`mechanical-below-tier`); and
+  `mechanicalLabelViolations` rejects a `mech-` leaf with no model at all
+  (`mechanical-without-model`). Both are part of `validateContract`, so
+  `byan-lint-workflows` and the pre-commit gate enforce them.
 - `test/native-routing-integration.test.js` pins the invariant on the SHIPPED
   scripts: every script passes the contract, and every downgrade sits on an
-  exploration leaf.
+  exploration or `mech-` leaf.
 - `workflows-lint.js` -> `untieredExplorationViolations` is the SYMMETRIC
   advisory: it surfaces an exploration-labelled leaf that runs deep (a possible
   saving). It is DELIBERATELY OUT of `validateContract` — forcing those leaves to
@@ -162,6 +173,38 @@ Enforcement (because the in-session hooks do not fire inside a script):
   knob (the native `agent()` / Agent API exposes only `model`), so model tier is
   the sole token lever and effort-by-complexity reduces to model-by-complexity.
 
+## Ad-hoc scripts — the tier gate at the Workflow chokepoint
+
+The repo linter only sees committed `.claude/workflows/*.js`. A script authored
+inline for one run (the "adversarial review" pattern) is invisible to it and
+used to run every leaf on the session model. It crosses exactly one enforceable
+chokepoint before executing — the Workflow tool invocation — and that is where
+the gate now sits:
+
+| Piece | File | Role |
+|-------|------|------|
+| Engine | `lib/tier-script.js` | per-leaf report (`analyzeScript`) + pure gate decision (`decideTierGate`) against native-tiers; parsing stays in `workflows-lint.js` (`extractLabelledLeaves`) |
+| Hook | `.claude/hooks/tier-script-guard.js` | PreToolUse (matcher `Workflow`), CJS shell around the engine |
+| CLI | `bin/byan-tier-script.js` | standalone report on any script file; exit 0 clean/acknowledged, 1 gaps, 2 violations |
+| Batch aid | `byan_dispatch { leaves: [...] }` | per-leaf `opts.model` BEFORE the script is written |
+| Ledger | `_byan-output/tier-ledger.jsonl` | every gate decision + per-model histogram — the measurement basis for token gains |
+
+Gate behaviour, deliberately narrow:
+
+- **Deny once, with the exact fix.** Undecided exploration/`mech-` leaves deny
+  the invocation ONE time, listing each leaf and the value to write. An
+  identical resubmission passes — the gate forces a decision, it does not trap
+  the turn (same one-regen shape as the autobench Stop hook).
+- **It rewrites nothing.** An auto-stamped model on a misclassified leaf would
+  be the STRICT-2 No Downgrade regression; the author keeps the pen.
+- **Acknowledgment marker.** `// BYAN-TIER: reviewed` in the script asserts the
+  deep choices are deliberate; the gate then passes and logs `acknowledged`.
+- **Registry passes.** A name-only invocation resolves to a committed script the
+  pre-commit linter already owns.
+- **Escape hatch.** `touch .byan-tier/off` disables gating; the ledger still
+  records `escape-hatch` so misses stay auditable. Deny-once memory lives in the
+  gitignored `.byan-tier/` sidecar, keyed by script hash.
+
 If a future runtime needs full model ids instead of the `haiku`/`sonnet`
 aliases, `TIER_MODEL` in `native-tiers.js` is the only edit; the linter then
 flags every script literal that drifts from it, so the fan-out stays bounded.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.39.0",
+  "version": "2.41.0",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {

package/src/loadbalancer/capability-matrix.js

@@ -35,6 +35,20 @@ const DEFAULT_CAPABILITIES = {
     tool_use: true,
     image_input: true,
   },
+  codex: {
+    file_edit: true,
+    file_read: true,
+    bash: true,
+    web_search: false,
+    mcp_tools: true,
+    subagents: false,
+    git: true,
+    streaming: false, // codex exec is request/response (JSONL events, not token stream)
+    multi_turn: true, // thread id enables continuation
+    max_context_tokens: 256000,
+    tool_use: true,
+    image_input: false,
+  },
   byan_api: {
     file_edit: false,
     file_read: false,