feat: P1/P2 — cost HUD, routing tooling, health TTL cache, commodity tags

Completes the P1/P2 items from the feature/improvement review (some
groundwork was scaffolded in a prior session; this finishes + verifies it).

Unit A — routing config tooling (validation + explainability):
- decide() returns nearMisses[] + a confidence rating (high/medium/low);
  route.mjs --explain surfaces them.
- validateRoster() gains two checks: unknown when.type tokens (warning, when
  the caller passes the tags.txt label set) and invalid agent tier (error);
  existing behavior and return shape preserved (knownTypes is optional).
- new score.mjs knownTypes(tagsPath) exports the tags.txt label set;
  route.mjs --validate now passes it so unknown-type routes are flagged.

Unit B — cost/token accounting in the HUD:
- per-backend cost_per_1k_chars in roster.json; run.mjs computes costMicros
  on success and state.mjs accumulates approx_cost_micros (flat one-field-
  per-line contract preserved); statusline renders a ~$ figure.
- new test/cost-hud.test.mjs proves it end-to-end: two calls (40k+360k
  micros) accumulate to 400000 and the statusline renders "$0.40".

Unit C — health-check TTL cache + new commodity task types:
- backends.mjs health() is now TTL-memoized (60s) per backend with
  invalidateHealth() + _clearHealthCache(); removes the per-fallback-hop
  re-probe cost. The uncached probe is preserved as _healthUncached().
- three new tags.txt types route to the agy standard-coding lane instead of
  wasting Sonnet: docs-write, i18n, deps-bump. Wired into the standard-coding
  route in roster.json. Verified: 5 true-positives route to agy, no false
  positives ("read the docs", "update the business logic" stay clear).

Verified by execution (Opus verifier pass): new-tag routing cases pass,
validator new-checks fire, health cache memoizes, full suite 88/88 green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: WatchAndyTW

config/roster.json

@@ -51,6 +51,8 @@
         "$HOME/AppData/Local/agy/bin/agy.exe"
       ],
       "hard_timeout": "6m",
+      "_cost_note": "tunable estimate, USD per 1000 output chars — for the HUD cost figure only",
+      "cost_per_1k_chars": 0.0001,
       "quota_patterns": [
         "quota", "rate limit", "resource_exhausted", "429",
         "exceeded your current quota", "insufficient", "out of credits",
@@ -72,6 +74,8 @@
       "sandbox_flag": "",
       "use_winpty": false,
       "hard_timeout": "6m",
+      "_cost_note": "tunable estimate, USD per 1000 output chars — for the HUD cost figure only",
+      "cost_per_1k_chars": 0.0004,
       "quota_patterns": ["rate limit", "quota", "429", "usage limit", "insufficient_quota", "too many requests", "exceeded"],
       "quota_exit_codes": [],
       "_note": "Invoked as `codex exec <flags> <prompt>` — non-interactive, prints only the final message to stdout (no winpty). models empty = codex's own config.toml default; set per-tier model IDs here to map cheap/standard. `-s read-only` keeps it from modifying files; drop --skip-git-repo-check only if you require a git repo."
@@ -146,7 +150,7 @@
 
     { "_comment": "Standard, verifiable coding — most everyday code work.",
       "name": "standard-coding",
-      "when": { "type": ["frontend", "react-component", "css", "html", "ui", "svg", "animation", "3d", "asset-gen", "mockup", "boilerplate", "scaffold", "crud", "rest-endpoint", "script", "cli-tool", "glue-code", "data-transform", "sql-query", "regex", "config-file", "dockerfile", "rename", "format", "codegen", "fixture"] },
+      "when": { "type": ["frontend", "react-component", "css", "html", "ui", "svg", "animation", "3d", "asset-gen", "mockup", "boilerplate", "scaffold", "crud", "rest-endpoint", "script", "cli-tool", "glue-code", "data-transform", "sql-query", "regex", "config-file", "dockerfile", "rename", "format", "codegen", "fixture", "docs-write", "i18n", "deps-bump"] },
       "backend": "agy", "tier": "standard" },
 
     { "_comment": "Cheap/fast trivia — tiny, throwaway, zero-judgment.",

config/tags.txt

@@ -86,6 +86,9 @@ format         reformat|prettier|fix (the )?indentation|lint fix|run the formatt
 codegen        code ?gen(eration)?|generate (the )?code
 unit-test      unit test|write tests?|test cases?|\bjest\b|\bpytest\b|test coverage
 fixture        fixture|mock data|test data|seed data|sample data
+docs-write     (writ|updat|add|generat|creat|author).{0,30}(docs?|documentation|readme|jsdoc|docstrings?|changelog)|document (the )?(api|module|function|code)
+i18n           \bi18n\b|internationali(z|s)ation|locali(z|s)ation|translat.{0,15}(strings?|\bui\b|text|copy)|add locale support
+deps-bump      (bump|upgrade|update).{0,20}(the )?(version|dependenc(y|ies)|package)|upgrade .{0,20} to v?\d|bump .{0,20} to v?\d
 
 # ============================ AGY: trivial ============================
 quick-email    \bemail\b|draft (a|an) (email|message|note)|reply to

src/bin/route.mjs

@@ -9,6 +9,8 @@ import { fileURLToPath } from 'url';
 import { dirname, resolve, join } from 'path';
 import { readFileSync } from 'fs';
 import { decide } from '../lib/router.mjs';
+import { validateRoster } from '../lib/validate-config.mjs';
+import { knownTypes } from '../lib/score.mjs';
 import { resolveRosterPath } from '../lib/platform.mjs';
 
 // Resolve project root from this file's location (src/bin/route.mjs -> root).
@@ -19,6 +21,7 @@ const MMT_ROOT = resolve(__dirname, '..', '..');
 const args = process.argv.slice(2);
 let preset = '';
 let explain = false;
+let validate = false;
 let tagsPath = process.env.MMT_TAGS || join(MMT_ROOT, 'config', 'tags.txt');
 // Default via shared resolver: .mmt/roster.json (cwd) > ~/.claude/mmt-roster.json > plugin default.
 // An explicit --roster flag (below) still overrides this.
@@ -30,6 +33,7 @@ for (let i = 0; i < args.length; i++) {
   if (a === '--preset' && i + 1 < args.length) { preset = args[++i]; }
   else if (a.startsWith('--preset=')) { preset = a.slice('--preset='.length); }
   else if (a === '--explain') { explain = true; }
+  else if (a === '--validate') { validate = true; }
   else if (a === '--tags' && i + 1 < args.length) { tagsPath = args[++i]; }
   else if (a.startsWith('--tags=')) { tagsPath = a.slice('--tags='.length); }
   else if (a === '--roster' && i + 1 < args.length) { rosterPath = args[++i]; }
@@ -56,26 +60,30 @@ async function main() {
     task = (await readStdin()).replace(/\r?\n$/, '');
   }
 
-  if (!task) {
-    process.stderr.write('route.mjs: no task text (pass as arg or stdin)\n');
-    process.exit(2);
-  }
-
   // Load roster.
   let roster;
   try {
     roster = JSON.parse(readFileSync(rosterPath, 'utf8'));
   } catch (e) {
     process.stderr.write(`route.mjs: could not load roster: ${e.message}\n`);
-    // Degrade to a safe Sonnet decision.
-    const fallback = {
-      backend: 'native', model: 'native:sonnet', tier: 'sonnet',
-      rule: 'no-roster', native: true,
-      preset: preset || 'balanced',
-      score: { chars: [...task].length, types: [] },
-    };
-    process.stdout.write(JSON.stringify(fallback) + '\n');
-    process.exit(0);
+    process.exit(1);
+  }
+
+  // --validate mode: check roster schema and exit. Pass the tags.txt type labels so the validator
+  // can flag any route that references a type not defined there.
+  if (validate) {
+    let known;
+    try { known = knownTypes(tagsPath); } catch { known = undefined; }
+    const result = validateRoster(roster, known);
+    result.errors.forEach(err => process.stderr.write(`error: ${err}\n`));
+    result.warnings.forEach(warn => process.stderr.write(`warning: ${warn}\n`));
+    process.stdout.write(JSON.stringify(result) + '\n');
+    process.exit(result.ok ? 0 : 1);
+  }
+
+  if (!task) {
+    process.stderr.write('route.mjs: no task text (pass as arg or stdin)\n');
+    process.exit(2);
   }
 
   let decision;
@@ -88,19 +96,26 @@ async function main() {
       rule: 'internal-error', native: true,
       preset: preset || 'balanced',
       score: { chars: [...task].length, types: [] },
+      nearMisses: [],
+      confidence: 'low'
     };
     process.stdout.write(JSON.stringify(fallback) + '\n');
     process.exit(0);
   }
 
   if (explain) {
+    const nearMissLines = decision.nearMisses.length === 0
+      ? ['<none>']
+      : decision.nearMisses.map(nm => `${nm.rule.name} (${nm.backend}/${nm.tier})`);
     process.stderr.write([
       '── route.mjs decision ─────────────────────────────',
-      `task chars : ${decision.score.chars}`,
-      `task types : ${decision.score.types.join(', ') || '<none>'}`,
-      `preset     : ${decision.preset}`,
-      `roster     : ${rosterPath}`,
-      `decision   : ${JSON.stringify(decision)}`,
+      `task chars    : ${decision.score.chars}`,
+      `task types    : ${decision.score.types.join(', ') || '<none>'}`,
+      `preset        : ${decision.preset}`,
+      `confidence    : ${decision.confidence}`,
+      `near misses   : ${nearMissLines.join(', ')}`,
+      `roster        : ${rosterPath}`,
+      `decision      : ${JSON.stringify(decision)}`,
       '───────────────────────────────────────────────────',
     ].join('\n') + '\n');
   }

src/bin/run.mjs

@@ -254,8 +254,11 @@ async function main() {
       fallbackCount++; continue;
     }
 
-    // success.
-    state.end({ id: callId, backend: be, model, rule: D_rule, code: 0, durMs, outChars, fallback: fallbackCount });
+    // success. Approximate cost (USD micros) from the backend's per-1k-char rate × (in+out) chars —
+    // a rough HUD figure only (chars, not tokens). Missing/zero rate -> 0 cost.
+    const rate = Number(beCfg.cost_per_1k_chars) || 0;
+    const costMicros = Math.round(rate * ((inChars + outChars) / 1000) * 1e6);
+    state.end({ id: callId, backend: be, model, rule: D_rule, code: 0, durMs, outChars, fallback: fallbackCount, costMicros });
     process.stdout.write(cleanOut + '\n');
     process.exit(0);
   }

src/lib/backends.mjs

@@ -19,6 +19,15 @@ import Module, { createRequire } from 'node:module';
 import { spawn, execSync } from 'node:child_process';
 import * as platform from './platform.mjs';
 
+// Health-check TTL memoization — health() is called on EVERY fallback-chain hop in run.mjs; without
+// caching that re-spawns `<bin> --version` each time. Cache the boolean per backend for HEALTH_TTL_MS.
+const _healthCache = new Map();
+const HEALTH_TTL_MS = 60_000;
+
+function _healthKey(backendCfg) {
+  return (backendCfg?.kind || '') + ':' + (backendCfg?.cmd || '');
+}
+
 // node-pty resolution: plugin-local install first, then a GLOBAL `npm install -g node-pty` via the
 // NODE_PATH shim (ensureGlobalNodeModules). createRequire is used instead of ESM import() because
 // NODE_PATH only affects CommonJS require() resolution — this is the same trick oh-my-claudecode uses
@@ -350,7 +359,7 @@ export async function invoke(backendCfg, prompt, opts = {}) {
 // --- health ------------------------------------------------------------------
 // `<bin> --version` -> non-empty output, exit 0. WITHOUT any PTY wrapper for BOTH backends:
 // PROBES.md confirms winpty yields empty for agy --version (not TTY-gated), and codex isn't gated.
-export async function health(backendCfg) {
+async function _healthUncached(backendCfg) {
   const kind = backendCfg && backendCfg.kind;
   let bin;
   if (kind === 'gemini') {
@@ -377,6 +386,28 @@ export async function health(backendCfg) {
   return res.code === 0 && out.length > 0;
 }
 
+// TTL-memoized health check. Returns the cached boolean if checked within HEALTH_TTL_MS, else
+// re-probes and caches. Keeps the per-hop fallback-chain cost down to one probe per backend per TTL.
+export async function health(backendCfg) {
+  const key = _healthKey(backendCfg);
+  const cached = _healthCache.get(key);
+  const now = Date.now();
+  if (cached !== undefined && (now - cached.ts) < HEALTH_TTL_MS) return cached.ok;
+  const ok = await _healthUncached(backendCfg);
+  _healthCache.set(key, { ok, ts: now });
+  return ok;
+}
+
+// Drop a backend's cached health (e.g. after it errors mid-run) so the next call re-probes it.
+export function invalidateHealth(backendCfg) {
+  _healthCache.delete(_healthKey(backendCfg));
+}
+
+// Reset the whole health cache — for tests.
+export function _clearHealthCache() {
+  _healthCache.clear();
+}
+
 // --- clean -------------------------------------------------------------------
 // Parity with backends.sh mmt_clean: strip CR, drop winpty teardown assertion lines, strip stray
 // OSC / CSI / charset-select / 2-char ESC sequences, then trim trailing blank lines.

src/lib/router.mjs

@@ -43,14 +43,20 @@ function applyPreset(preset, ruleName, backend, tier) {
 
 /**
  * First-match-wins rule evaluation (parity with match.py match_rule).
+ * Returns the winning rule or null; also collects near-misses for confidence.
  * @param {object[]} routes
  * @param {number} chars
  * @param {string[]} types
- * @returns {object|null}
+ * @returns {{ rule: object|null, nearMisses: object[] }}
  */
 function matchRule(routes, chars, types) {
   const tset = new Set(types.filter(Boolean));
+  const nearMisses = [];
+
   for (const r of routes) {
+    // Skip marker objects (no name key)
+    if (!r.name) continue;
+
     const when = r.when || {};
     let ok = true;
 
@@ -65,16 +71,40 @@ function matchRule(routes, chars, types) {
     if (ok && 'max_chars' in when) {
       if (chars > Number(when.max_chars)) ok = false;
     }
-    if (ok) return r;
+
+    if (ok) return { rule: r, nearMisses };
+
+    // Collect near-misses: rules with type overlap (ignore char constraints)
+    if ('type' in when) {
+      const ruleTypes = when.type;
+      const hasTypeOverlap = ruleTypes.some(t => tset.has(t));
+      if (hasTypeOverlap) {
+        nearMisses.push({ rule: r, backend: r.backend || 'native', tier: r.tier || 'sonnet' });
+      }
+    }
   }
-  return null;
+
+  return { rule: null, nearMisses };
+}
+
+/**
+ * Compute decision confidence.
+ * @param {string[]} types - matched task types
+ * @param {object[]} nearMisses - rules with type overlap but failed on chars/min_chars/max_chars
+ * @returns {"high" | "medium" | "low"}
+ */
+function computeConfidence(types, nearMisses) {
+  if (types.length > 0 && nearMisses.length === 0) return 'high';
+  if (nearMisses.length > 0) return 'medium';
+  return 'low'; // catch-all only
 }
 
 /**
  * Produce a routing decision.
  * @param {{ task: string, roster: object, tagsPath: string, preset?: string }} opts
  * @returns {{ backend: string, model: string, tier: string, rule: string, native: boolean,
- *             preset: string, score: { chars: number, types: string[] } }}
+ *             preset: string, score: { chars: number, types: string[] },
+ *             nearMisses: object[], confidence: string }}
  */
 export function decide({ task, roster, tagsPath, preset: presetArg }) {
   const defs = getRosterDefaults(roster);
@@ -83,15 +113,13 @@ export function decide({ task, roster, tagsPath, preset: presetArg }) {
   const chars = charCount(task);
   const types = classify(task, tagsPath);
 
-  // Filter out _comment marker objects; keep only real rules (those with a `name` key).
   const rawRoutes = getRosterRoutes(roster);
   const score = { chars, types };
 
-  let rule = matchRule(rawRoutes, chars, types);
+  const { rule, nearMisses } = matchRule(rawRoutes, chars, types);
 
   let backend, tier, ruleName;
   if (rule === null) {
-    // Should be impossible given catch-all-safe with when:{}, but stay safe.
     backend = 'native';
     tier = 'sonnet';
     ruleName = 'catch-all-safe';
@@ -103,6 +131,7 @@ export function decide({ task, roster, tagsPath, preset: presetArg }) {
 
   [backend, tier] = applyPreset(preset, ruleName, backend, tier);
   const { model, native } = resolveModel(roster, backend, tier);
+  const confidence = computeConfidence(types, nearMisses);
 
-  return { backend, model, tier, rule: ruleName, native, preset, score };
+  return { backend, model, tier, rule: ruleName, native, preset, score, nearMisses, confidence };
 }

src/lib/score.mjs

@@ -61,3 +61,27 @@ export function classify(task, tagsPath) {
 
   return result;
 }
+
+/**
+ * Collect the set of task-type labels DEFINED in tags.txt (the first token of each non-comment,
+ * non-blank line). Used by `route.mjs --validate` to flag routes that reference an unknown type.
+ * @param {string} tagsPath  absolute path to config/tags.txt
+ * @returns {Set<string>}
+ */
+export function knownTypes(tagsPath) {
+  const out = new Set();
+  let raw;
+  try {
+    raw = readFileSync(tagsPath, 'utf8');
+  } catch {
+    return out;
+  }
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const spaceIdx = trimmed.search(/\s/);
+    if (spaceIdx === -1) continue;
+    out.add(trimmed.slice(0, spaceIdx));
+  }
+  return out;
+}

src/lib/state.mjs

@@ -46,6 +46,7 @@ function loadCounters() {
     errors: getNum(text, 'errors', 0),
     approx_in_chars: getNum(text, 'approx_in_chars', 0),
     approx_out_chars: getNum(text, 'approx_out_chars', 0),
+    approx_cost_micros: getNum(text, 'approx_cost_micros', 0),
   };
 }
 
@@ -137,7 +138,8 @@ function flush(s) {
     `  "last_dur_ms": ${intOr(s.last_dur_ms, 0)},`,
     `  "last_out_chars": ${intOr(s.last_out_chars, 0)},`,
     `  "approx_in_chars": ${intOr(s.approx_in_chars, 0)},`,
-    `  "approx_out_chars": ${intOr(s.approx_out_chars, 0)}`,
+    `  "approx_out_chars": ${intOr(s.approx_out_chars, 0)},`,
+    `  "approx_cost_micros": ${intOr(s.approx_cost_micros, 0)}`,
     '}',
     '',
   ];
@@ -179,8 +181,8 @@ export function start({ id, backend, model, rule, inChars } = {}) {
   }
 }
 
-// end({ id, backend, model, rule, code, durMs, outChars, fallback }) — open--, calls++, set last_*.
-export function end({ id, backend, model, rule, code, durMs, outChars, fallback } = {}) {
+// end({ id, backend, model, rule, code, durMs, outChars, fallback, costMicros }) — open--, calls++, set last_*.
+export function end({ id, backend, model, rule, code, durMs, outChars, fallback, costMicros } = {}) {
   const locked = lock();
   try {
     const s = loadCounters();
@@ -204,6 +206,7 @@ export function end({ id, backend, model, rule, code, durMs, outChars, fallback
     s.last_dur_ms = intOr(durMs, 0);
     s.last_out_chars = intOr(outChars, 0);
     s.approx_out_chars = (s.approx_out_chars || 0) + intOr(outChars, 0);
+    s.approx_cost_micros = (s.approx_cost_micros || 0) + intOr(costMicros, 0);
     flush(s);
   } finally {
     if (locked) unlock();