total-recall-brain 3.41.4 → 3.41.6

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/router.mjs

@@ -7,96 +7,20 @@
  * - Zero hardcoded hostnames, IP addresses, or personal node topologies.
  * - Zero fabricated or simulated quota percentages: a figure is reported only when a real
  *   provider API or local telemetry file supplies it; otherwise `unknown` is reported honestly.
- * - Filters candidates to harnesses actually installed on the target host unless `--include-uninstalled` is requested.
+ * - Candidates are the harnesses that can take work now; `resolvePool` reports why the others cannot.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { execFileSync } from 'node:child_process';
-import { ADAPTER_CATALOG, classifyTaskComplexity, selectOptimalHarness, computeEmpiricalScorecard } from '../capability/index.mjs';
-import { inspectAgents, getActiveAdapters } from './worker.mjs';
-
-// Generic Coding Benchmark Reference Data (SWE-bench Pro, Terminal-Bench 2.0, Artificial Analysis ELO)
-export const BENCHMARK_MATRIX = {
-  agy: {
-    sweBenchPro: 68.4,
-    terminalBench2: 74.2,
-    artificialAnalysisElo: 1380,
-    costPer1kTokens: 0.003,
-    provider: 'Google Antigravity'
-  },
-  claude: {
-    sweBenchPro: 72.8,
-    terminalBench2: 76.5,
-    artificialAnalysisElo: 1410,
-    costPer1kTokens: 0.008,
-    provider: 'Anthropic'
-  },
-  codex: {
-    sweBenchPro: 69.1,
-    terminalBench2: 71.8,
-    artificialAnalysisElo: 1375,
-    costPer1kTokens: 0.006,
-    provider: 'OpenAI'
-  },
-  grok: {
-    sweBenchPro: 61.2,
-    terminalBench2: 66.0,
-    artificialAnalysisElo: 1320,
-    costPer1kTokens: 0.0025,
-    provider: 'xAI'
-  },
-  dsh: {
-    sweBenchPro: 64.7,
-    terminalBench2: 67.9,
-    artificialAnalysisElo: 1335,
-    costPer1kTokens: 0.0006,
-    provider: 'DeepSeek / OpenRouter'
-  },
-  ollama: {
-    sweBenchPro: 44.5,
-    terminalBench2: 52.1,
-    artificialAnalysisElo: 1210,
-    costPer1kTokens: 0.0,
-    provider: 'Local / Ollama'
-  },
-  hermes: {
-    sweBenchPro: 56.8,
-    terminalBench2: 60.4,
-    artificialAnalysisElo: 1285,
-    costPer1kTokens: 0.0002,
-    provider: 'Local / Nous Research'
-  },
-  openhands: {
-    sweBenchPro: 67.3,
-    terminalBench2: 70.1,
-    artificialAnalysisElo: 1360,
-    costPer1kTokens: 0.005,
-    provider: 'OpenHands Community'
-  },
-  aider: {
-    sweBenchPro: 62.4,
-    terminalBench2: 65.8,
-    artificialAnalysisElo: 1310,
-    costPer1kTokens: 0.002,
-    provider: 'Aider AI'
-  },
-  goose: {
-    sweBenchPro: 58.0,
-    terminalBench2: 63.2,
-    artificialAnalysisElo: 1295,
-    costPer1kTokens: 0.002,
-    provider: 'Block Goose'
-  },
-  cline: {
-    sweBenchPro: 63.5,
-    terminalBench2: 66.4,
-    artificialAnalysisElo: 1315,
-    costPer1kTokens: 0.003,
-    provider: 'Cline AI'
-  }
-};
+import { classifyTaskComplexity, selectOptimalHarness, computeEmpiricalScorecard } from '../capability/index.mjs';
+import { inspectAgents } from './worker.mjs';
+import { inspectNode } from './executor.mjs';
+import { getModelCatalog, joinHarnessModels } from './model-catalog.mjs';
+import { readReceipts, activeQuotaWalls, activeCredentialBlocks } from './learner.mjs';
+import { resolvePool, exclusionReason } from './pool.mjs';
+import { readCodexRateLimits, measuredWalls } from './telemetry.mjs';
 
 /**
  * Helper to safely query host Total Recall CLI without assumptions
@@ -106,7 +30,7 @@ function runHostCli(args = []) {
     const totalRecallBin = process.env.TOTAL_RECALL_BIN || 'total-recall';
     const output = execFileSync(totalRecallBin, args, {
       stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: 8000,
+      timeout: 20000,
       encoding: 'utf8'
     });
     return output.trim();
@@ -115,18 +39,17 @@ function runHostCli(args = []) {
   }
 }
 
-/**
- * Read local empirical run ledger safely
- */
-export function readLocalRunLedger() {
-  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
-  const ledgerPath = path.join(home, '.agent', 'skills', 'total-recall', 'meta-harness-runs.json');
-  if (!fs.existsSync(ledgerPath)) return [];
+const gigabytes = bytes => (typeof bytes === 'number' ? +(bytes / 1024 ** 3).toFixed(2) : null);
+function normalizeFleetRow(row) {
+  return { hostname: row.hostname, ip: row.ip, online: row.online !== false, self: Boolean(row.self), telemetry: row.state || null, cpuCores: row.cores ?? null, loadAvg1m: row.loadAvg?.[0] ?? null, freeMemGB: gigabytes(row.memory?.free), totalMemGB: gigabytes(row.memory?.total), memoryUtilizationPercent: row.memory?.usedPercent ?? null };
+}
+function fleetTelemetry(run = runHostCli) {
   try {
-    const parsed = JSON.parse(fs.readFileSync(ledgerPath, 'utf8'));
-    return Array.isArray(parsed) ? parsed : [];
-  } catch {
-    return [];
+    const parsed = JSON.parse(run(['system-monitor', 'fleet', '--json']) || 'null');
+    if (!parsed?.rows) return { ok: false, error: 'Fleet telemetry is unavailable', nodes: [] };
+    return { ok: true, machines: parsed.machines, answered: parsed.answered, nodes: parsed.rows.map(normalizeFleetRow) };
+  } catch (error) {
+    return { ok: false, error: String(error.message), nodes: [] };
   }
 }
 
@@ -137,279 +60,146 @@ export function readLocalRunLedger() {
  */
 export async function inspectQuotas(options = {}) {
   const quotas = {};
-
-  // 1. Dynamic Host Hardware & RAM Telemetry (works on Android, Linux, macOS, Windows, or cloud VMs)
-  let totalMemBytes = os.totalmem();
-  let freeMemBytes = os.freemem();
-  let hostname = os.hostname();
-  let platform = os.platform();
-  let arch = os.arch();
-  let cpuCores = os.cpus()?.length || 1;
-  let loadAvg1m = os.loadavg()?.[0] || 0;
-
-  try {
-    const sysJson = runHostCli(['system-monitor', 'status', '--json']);
-    if (sysJson) {
-      const sysData = JSON.parse(sysJson);
-      if (sysData.memory?.total && sysData.memory?.free) {
-        totalMemBytes = sysData.memory.total;
-        freeMemBytes = sysData.memory.free;
-      }
-      if (sysData.hostname) hostname = sysData.hostname;
-      if (sysData.platform) platform = sysData.platform;
-      if (sysData.cores) cpuCores = sysData.cores;
-    }
-  } catch {}
-
-  const freeMemGB = parseFloat((freeMemBytes / (1024 * 1024 * 1024)).toFixed(2));
-  const totalMemGB = parseFloat((totalMemBytes / (1024 * 1024 * 1024)).toFixed(2));
-  const memoryUtilizationPercent = Math.round(((totalMemBytes - freeMemBytes) / totalMemBytes) * 100);
-
-  quotas.system = {
-    hostname,
-    platform,
-    arch,
-    cpuCores,
-    loadAvg1m: parseFloat(loadAvg1m.toFixed(2)),
-    totalMemGB,
-    freeMemGB,
-    memoryUtilizationPercent,
-    node: options.node || 'local'
-  };
-
-  // 2. Discover actually installed harnesses and their real authentication state
-  let installedState = {};
-  try {
-    const inspected = await inspectAgents({ env: process.env });
-    for (const a of inspected.agents || []) {
-      installedState[a.id] = a;
-    }
-  } catch {}
-
-  // 3. Subscription & Frontier Runners (honest state: never invent percentages)
-  for (const id of ['agy', 'claude', 'codex', 'grok']) {
-    const agent = installedState[id];
-    const installed = Boolean(agent?.installed);
-    let status = installed ? 'ready' : 'not_installed';
-    let quotaSource = 'unintegrated';
-    let rolling5hRemainingPercent = null;
-    let weeklyRemainingPercent = null;
-    let usagePercent = null;
-
-    // Check if local telemetry file provides actual rate-limit snapshots
-    if (id === 'claude') {
-      const telemetryFile = path.join(os.homedir(), '.claude', 'rate_limits.json');
-      if (fs.existsSync(telemetryFile)) {
-        try {
-          const data = JSON.parse(fs.readFileSync(telemetryFile, 'utf8'));
-          if (typeof data.five_hour?.used_percentage === 'number') {
-            rolling5hRemainingPercent = Math.max(0, 100 - Math.round(data.five_hour.used_percentage));
-            usagePercent = Math.round(data.five_hour.used_percentage);
-            quotaSource = 'claude-telemetry';
-          }
-          if (typeof data.seven_day?.used_percentage === 'number') {
-            weeklyRemainingPercent = Math.max(0, 100 - Math.round(data.seven_day.used_percentage));
-          }
-        } catch {}
-      }
-    }
-
-    if (agent?.authenticated === false) {
-      status = 'needs_auth';
-    }
-
-    quotas[id] = {
-      installed,
-      version: agent?.version || null,
-      billingModel: 'subscription',
-      rolling5hRemainingPercent,
-      weeklyRemainingPercent,
-      usagePercent,
-      quotaNote: rolling5hRemainingPercent !== null ? 'measured' : (installed ? 'unknown — provider exposes no public quota endpoint' : 'not installed'),
-      quotaSource,
-      status
+  const remote = options.node && options.node !== 'local';
+  const fleet = (options.fleet || fleetTelemetry)();
+  const rowFor = node => fleet.nodes.find(row => [row.hostname, row.ip].includes(node) || String(row.hostname || '').split('.')[0] === node);
+
+  if (remote) {
+    const row = rowFor(options.node);
+    if (!row || row.freeMemGB === null) throw new Error(`No telemetry from mesh node ${options.node}${fleet.ok ? '' : `: ${fleet.error}`}`);
+    quotas.system = { ...row, node: options.node };
+  } else {
+    // os.freemem() on macOS excludes reclaimable memory, so the monitor's figure wins when it answered.
+    const totalMemBytes = os.totalmem(), freeMemBytes = os.freemem();
+    const self = fleet.nodes.find(row => row.self);
+    quotas.system = {
+      hostname: os.hostname(), platform: os.platform(), arch: os.arch(), cpuCores: os.cpus()?.length || 1,
+      loadAvg1m: parseFloat((os.loadavg()?.[0] || 0).toFixed(2)),
+      totalMemGB: parseFloat((totalMemBytes / 1024 ** 3).toFixed(2)), freeMemGB: parseFloat((freeMemBytes / 1024 ** 3).toFixed(2)),
+      memoryUtilizationPercent: Math.round(((totalMemBytes - freeMemBytes) / totalMemBytes) * 100), node: 'local',
+      ...(typeof self?.freeMemGB === 'number' ? { freeMemGB: self.freeMemGB, totalMemGB: self.totalMemGB, memoryUtilizationPercent: self.memoryUtilizationPercent } : {}),
     };
   }
 
-  // 4. Generic Metered Balances (OpenRouter / API Credits if configured by user)
-  let meteredQuota = {
-    metered: true,
-    billingModel: 'metered',
-    creditRemainingUSD: null,
-    usageUSD: null,
-    usageDailyUSD: null,
-    usageWeeklyUSD: null,
-    usagePercent: null,
-    quotaNote: 'unconfigured — set OPENROUTER_API_KEY in auth secret to track metered credits',
-    status: 'unconfigured'
-  };
+  // Harness state comes from the selected machine. Quota walls are this machine's receipts.
+  const inspected = remote ? await (options.inspectNodeFn || inspectNode)(options.node) : await (options.inspect || inspectAgents)({ env: process.env });
+  const codexLimits = remote ? null : readCodexRateLimits();
+  const walls = remote ? {} : { ...activeQuotaWalls(await readReceipts()), ...measuredWalls(codexLimits) };
+  const metered = new Set(['dsh', 'hermes', 'openclaw', 'pi', 'aider', 'goose', 'openhands', 'cline']);
+
+  const blocks = remote ? {} : activeCredentialBlocks(await readReceipts());
+  for (const agent of inspected.agents || []) {
+    const wall = walls[agent.id];
+    const block = blocks[agent.id];
+    const reason = exclusionReason(agent, wall, block);
+    let status = 'ready';
+    if (!agent.installed) status = 'not_installed';
+    else if (agent.authenticated === false || block) status = 'needs_auth';
+    else if (agent.blockedBy) status = 'blocked';
+    else if (wall) status = 'exhausted';
+    else if (agent.authenticated === 'unknown') status = 'unverified';
+    const quota = {
+      installed: Boolean(agent.installed), version: agent.version || null,
+      billingModel: agent.id === 'ollama' ? 'local' : metered.has(agent.id) ? 'metered' : 'subscription',
+      rolling5hUsedPercent: null, weeklyUsedPercent: null, usagePercent: null,
+      quotaSource: 'none', quotaNote: reason || 'No usage figure is available from this harness', status,
+      ...(wall ? { resetsAt: wall.until, wallMessage: wall.message } : {}),
+    };
+    if (agent.id === 'codex' && codexLimits) {
+      quota.rolling5hUsedPercent = codexLimits.primary?.used_percent ?? null;
+      quota.weeklyUsedPercent = codexLimits.secondary?.used_percent ?? null;
+      if (codexLimits.primary || codexLimits.secondary) quota.usagePercent = Math.max(quota.rolling5hUsedPercent ?? 0, quota.weeklyUsedPercent ?? 0);
+      quota.quotaSource = 'codex-session-log';
+      quota.observedAt = codexLimits.observedAt;
+      if (!reason) quota.quotaNote = `Measured in the Codex session log at ${codexLimits.observedAt}`;
+    }
+    quotas[agent.id] = quota;
+  }
 
+  // Metered balance, from the provider
+  let meteredQuota = { billingModel: 'metered', creditRemainingUSD: null, usageUSD: null, usageDailyUSD: null, usageWeeklyUSD: null, usagePercent: null, quotaNote: 'No OpenRouter key in the auth store', status: 'unconfigured' };
   try {
-    const key = options.openRouterKey !== undefined
-      ? options.openRouterKey
-      : (runHostCli(['auth', 'secret', 'get', 'OPENROUTER_API_KEY']) || process.env.OPENROUTER_API_KEY);
-    if (key && key.startsWith('sk-or-')) {
-      const fetchFn = options.fetchImpl || fetch;
-      const res = await fetchFn('https://openrouter.ai/api/v1/auth/key', {
-        headers: { Authorization: `Bearer ${key}` },
-        signal: AbortSignal.timeout(4000)
-      });
-      if (res.ok) {
-        const json = await res.json();
-        const data = json.data;
-        if (data) {
-          const limit = data.limit;
-          const usage = typeof data.usage === 'number' ? parseFloat(data.usage.toFixed(4)) : 0;
-          const limitRemaining = data.limit_remaining;
-          meteredQuota = {
-            metered: true,
-            billingModel: 'metered',
-            creditRemainingUSD: limitRemaining !== null && limitRemaining !== undefined
-              ? parseFloat(Number(limitRemaining).toFixed(4))
-              : (limit ? parseFloat(Math.max(0, limit - usage).toFixed(4)) : null),
-            usageUSD: usage,
-            usageDailyUSD: typeof data.usage_daily === 'number' ? parseFloat(data.usage_daily.toFixed(4)) : 0,
-            usageWeeklyUSD: typeof data.usage_weekly === 'number' ? parseFloat(data.usage_weekly.toFixed(4)) : 0,
-            usagePercent: limit ? Math.min(100, Math.round((usage / limit) * 100)) : 0,
-            label: data.label || 'configured',
-            quotaNote: limit ? `${Math.round((usage / limit) * 100)}% of limit used` : `Metered active ($${usage} total used, no hard cap)`,
-            status: 'ready'
-          };
-        }
-      }
+    const key = options.openRouterKey !== undefined ? options.openRouterKey : (runHostCli(['auth', 'secret', 'get', 'DEVELOPER_OPENROUTER_API_KEY']) || runHostCli(['auth', 'secret', 'get', 'OPENROUTER_API_KEY']));
+    if (key) {
+      const response = await (options.fetchImpl || fetch)('https://openrouter.ai/api/v1/auth/key', { headers: { Authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(6000) });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      const data = (await response.json()).data || {};
+      const usage = typeof data.usage === 'number' ? +data.usage.toFixed(4) : null;
+      meteredQuota = {
+        billingModel: 'metered', creditRemainingUSD: typeof data.limit_remaining === 'number' ? +data.limit_remaining.toFixed(4) : null,
+        usageUSD: usage, usageDailyUSD: data.usage_daily ?? null, usageWeeklyUSD: data.usage_weekly ?? null,
+        usagePercent: data.limit && usage !== null ? Math.min(100, Math.round((usage / data.limit) * 100)) : null,
+        quotaNote: data.limit ? `Limit $${data.limit}` : 'No spending limit on this key', quotaSource: 'openrouter', status: 'ready',
+      };
     }
-  } catch {
-    meteredQuota.quotaNote = 'offline — unable to reach metered provider endpoint';
+  } catch (error) {
+    meteredQuota.quotaNote = `OpenRouter could not be reached: ${error.message}`;
+    meteredQuota.status = 'unavailable';
   }
   quotas.metered = meteredQuota;
 
-  // 5. Zero-Cost Local Inference (Ollama / Hermes)
-  // Evaluated against actual host RAM and binary installation
-  for (const localId of ['ollama', 'hermes']) {
-    const agent = installedState[localId];
-    const installed = Boolean(agent?.installed);
-    const hasRam = freeMemGB >= 2.0;
-    quotas[localId] = {
-      installed,
-      version: agent?.version || null,
-      metered: false,
-      billingModel: 'local',
-      costUSD: 0,
-      usagePercent: 0,
-      freeMemGB,
-      quotaNote: !installed
-        ? 'not installed'
-        : (hasRam ? `Unlimited local inference (${freeMemGB} GB free RAM)` : `Low host memory (${freeMemGB} GB free RAM)`),
-      status: !installed ? 'not_installed' : (hasRam ? 'ready' : 'low-ram')
-    };
-  }
+  return { ok: true, timestamp: new Date().toISOString(), node: options.node || 'local', fleet: { ok: fleet.ok, error: fleet.error, machines: fleet.machines, answered: fleet.answered, nodes: fleet.nodes }, quotas };
+}
 
+/** Models with sourced figures, the leaderboards they came from, and pass rates measured on this machine. */
+export async function getBenchmarks(options = {}) {
+  const catalog = getModelCatalog();
+  const receipts = options.ledger || await readReceipts();
   return {
-    ok: true,
-    timestamp: new Date().toISOString(),
-    quotas
+    ok: true, updatedAt: catalog.updatedAt, synced: Boolean(catalog.updatedAt),
+    note: catalog.updatedAt ? undefined : 'Run `total-recall meta-harness maintenance --models` to fetch real figures.',
+    sources: catalog.sources, models: joinHarnessModels(catalog), leaderboards: catalog.leaderboards,
+    local: computeEmpiricalScorecard(receipts),
   };
 }
 
-/**
- * Query Benchmarks Matrix and Local Empirical Pass Rates
- */
-export function getBenchmarks(options = {}) {
-  const localLedger = options.ledger || readLocalRunLedger();
-  const empirical = computeEmpiricalScorecard(localLedger);
-  const customAdapters = getActiveAdapters().filter(a => a.custom);
-
-  const combined = {};
-  for (const [id, bm] of Object.entries(BENCHMARK_MATRIX)) {
-    const stats = empirical[id] || { total: 0, passed: 0, passRate: null, avgDurationMs: 0 };
-    combined[id] = {
-      ...bm,
-      localRuns: stats.total,
-      localPassRatePercent: stats.total > 0 ? stats.passRate : null,
-      avgDurationMs: stats.total > 0 ? stats.avgDurationMs : null
-    };
-  }
-
-  // Include any custom user adapters so their empirical pass rates are tracked too
-  for (const custom of customAdapters) {
-    if (!combined[custom.id]) {
-      const stats = empirical[custom.id] || { total: 0, passed: 0, passRate: null, avgDurationMs: 0 };
-      combined[custom.id] = {
-        sweBenchPro: null,
-        terminalBench2: null,
-        artificialAnalysisElo: null,
-        costPer1kTokens: null,
-        provider: `Custom (${custom.name})`,
-        localRuns: stats.total,
-        localPassRatePercent: stats.total > 0 ? stats.passRate : null,
-        avgDurationMs: stats.total > 0 ? stats.avgDurationMs : null
-      };
-    }
-  }
+/** Ask the decision plugin to classify. Its failure is reported; the caller sees which classifier answered. */
+export function classifyWithDecision(task, run = args => runHostCli(args)) {
+  const questions = { complexity: { type: 'choice', prompt: 'How demanding is this software engineering task for a coding agent?', options: ['local', 'budget', 'frontier'] } };
+  const output = run(['decision', 'run', '--state', JSON.stringify({ task: task.slice(0, 2000) }), '--questions', JSON.stringify(questions), '--json']);
+  if (!output) throw new Error('The decision plugin did not answer');
+  const parsed = JSON.parse(output);
+  const answer = parsed.answers?.complexity ?? parsed.decision?.answers?.complexity ?? parsed.result?.complexity;
+  const tier = typeof answer === 'string' ? answer : answer?.choice;
+  if (!['local', 'budget', 'frontier'].includes(tier)) throw new Error('The decision plugin returned no usable tier');
+  return { tier, confidence: answer?.confidence ?? null };
+}
 
-  return {
-    ok: true,
-    updatedAt: new Date().toISOString(),
-    matrix: combined
-  };
+/** Local-tier work goes to the online machine with the most free memory that reported telemetry. */
+export function placeLocalWork(fleet = {}) {
+  const nodes = (fleet.nodes || []).filter(node => node.online !== false && typeof node.freeMemGB === 'number');
+  if (!nodes.length) return null;
+  const best = nodes.reduce((a, b) => (b.freeMemGB > a.freeMemGB ? b : a));
+  return { node: best.hostname, freeMemGB: best.freeMemGB };
 }
 
-/**
- * Route a task dynamically based on complexity, installed harnesses, quotas, and empirical pass rates
- */
 export async function routeTask(taskDescription, options = {}) {
-  const complexity = classifyTaskComplexity(taskDescription, options);
-  const quotaReport = await inspectQuotas(options);
-  const quotas = quotaReport.quotas;
-  const empiricalScorecard = computeEmpiricalScorecard(readLocalRunLedger());
-
-  // Discover actually installed harnesses on the host unless caller passes an explicit pool
-  let available = options.availableHarnesses;
-  let installedOnly = true;
-  if (!Array.isArray(available) || available.length === 0) {
+  let complexity = classifyTaskComplexity(taskDescription, options);
+  let classifier = { source: 'heuristic' };
+  if (options.jev) {
     try {
-      const inspected = await inspectAgents({ env: process.env });
-      const installedIds = (inspected.agents || []).filter(a => a.installed).map(a => a.id);
-      if (installedIds.length > 0 && !options.includeUninstalled) {
-        available = installedIds;
-      } else {
-        available = getActiveAdapters().map(a => a.id);
-        installedOnly = false;
-      }
-    } catch {
-      available = Object.keys(ADAPTER_CATALOG);
-      installedOnly = false;
+      const decided = classifyWithDecision(taskDescription, options.decisionRun);
+      complexity = { ...complexity, tier: decided.tier, isFrontierRecommended: decided.tier === 'frontier', isLocalRecommended: decided.tier === 'local' };
+      classifier = { source: 'decision', confidence: decided.confidence };
+    } catch (error) {
+      classifier = { source: 'heuristic', decisionError: String(error.message).slice(0, 300) };
     }
   }
-
-  const routing = selectOptimalHarness(taskDescription, available, quotas, {
-    ...options,
-    empiricalScorecard
-  });
-
+  const [quotaReport, pool, receipts] = await Promise.all([inspectQuotas(options), resolvePool(options), readReceipts()]);
+  const quotas = quotaReport.quotas;
+  const routing = selectOptimalHarness(taskDescription, pool.ready.map(h => h.id), quotas, { ...options, tierOverride: complexity.tier, empiricalScorecard: computeEmpiricalScorecard(receipts) });
   const selectedQuota = quotas[routing.selected] || {};
-  const usage = selectedQuota.usagePercent ?? null;
   const warnings = [];
-  if (typeof usage === 'number' && usage > 85) {
-    warnings.push(`Selected harness '${routing.selected}' is at ${usage}% measured quota usage.`);
-  }
-  if (selectedQuota.status === 'needs_auth') {
-    warnings.push(`Selected harness '${routing.selected}' is installed but requires authentication.`);
-  }
-
+  if (typeof selectedQuota.usagePercent === 'number' && selectedQuota.usagePercent > 85) warnings.push(`${routing.selected} is at ${selectedQuota.usagePercent}% measured usage.`);
+  if (selectedQuota.status === 'unverified') warnings.push(`${routing.selected} has no login probe; only a completed run proves it works.`);
+  if (selectedQuota.billingModel === 'metered') warnings.push(`${routing.selected} bills per token.`);
+  if (!routing.selected) warnings.push('No harness can take this task right now.');
   return {
-    ok: true,
-    task: taskDescription,
-    complexity,
-    selected: routing.selected,
-    tier: routing.complexity.tier,
-    installedOnlyPool: installedOnly,
-    candidates: routing.candidates,
-    quotaSnapshot: {
-      selectedHarnessStatus: selectedQuota.status || 'unknown',
-      selectedHarnessUsage: usage,
-      freeMemGB: quotas.system.freeMemGB
-    },
-    warnings
+    ok: Boolean(routing.selected), task: taskDescription, classifier, complexity,
+    selected: routing.selected, tier: complexity.tier, candidates: routing.candidates, excluded: pool.excluded,
+    placement: complexity.tier === 'local' ? placeLocalWork(quotaReport.fleet) : null,
+    scoring: 'Adapter quality and cost scores are configured priors, adjusted by pass rates measured on this machine.',
+    quotaSnapshot: { selectedHarnessStatus: selectedQuota.status || null, selectedHarnessUsage: selectedQuota.usagePercent ?? null, freeMemGB: quotas.system.freeMemGB ?? null },
+    warnings,
   };
 }

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/runtime.mjs

@@ -16,7 +16,7 @@ export async function manageRuntime(agent, args = [], { env = process.env, probe
     let result, code;
     try {
       console.log = (...parts) => lines.push(parts.join(' ')); console.error = (...parts) => errors.push(parts.join(' '));
-      result = await run([process.execPath, 'cli-agents', 'dsh', ...args]);
+      result = await run([process.execPath, 'meta-harness', 'dsh', ...args]);
       code = process.exitCode || 0;
     } finally { console.log = log; console.error = error; process.exitCode = previous; }
     return { ok:code === 0, agent, exitCode:code, data:result?.data, output:lines.join('\n'), error:errors.join('\n') || undefined };

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/ssss-store.mjs

@@ -0,0 +1,20 @@
+/** Bind only to the verified native Total Recall storage contract. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+function resolveStateStoreSource() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [process.env.TR_PACKAGE_ROOT, path.resolve(here, '..', '..', 'total-recall'), path.resolve(process.cwd(), '..', 'total-recall'), process.cwd()].filter(Boolean);
+  for (const root of candidates) {
+    try {
+      if (JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name !== 'total-recall-brain') continue;
+      const file = path.join(root, 'src/core/plugin-state-store.mjs');
+      if (fs.existsSync(file)) return file;
+    } catch { /* try the next candidate */ }
+  }
+  return null;
+}
+const source = resolveStateStoreSource();
+if (!source) throw new Error('Cannot bind the native Total Recall storage contract: no total-recall-brain host found. Run inside a Total Recall host or set TR_PACKAGE_ROOT.');
+export const { PluginStateStore } = await import(pathToFileURL(source).href);

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/telemetry.mjs

@@ -0,0 +1,43 @@
+/** Usage figures the harnesses themselves recorded on this machine. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+function recentSessionFiles(dir, depth = 3, limit = 5) {
+  let names;
+  try { names = fs.readdirSync(dir).sort().reverse(); } catch { return []; }
+  const files = [];
+  for (const name of names) {
+    const full = path.join(dir, name);
+    if (depth > 0) files.push(...recentSessionFiles(full, depth - 1, limit));
+    else if (name.endsWith('.jsonl')) files.push(full);
+    if (files.length >= limit) break;
+  }
+  return files;
+}
+
+/** Codex logs its real rate-limit windows. A window whose reset has passed no longer applies. */
+export function readCodexRateLimits({ sessionsDir = path.join(process.env.CODEX_HOME || path.join(process.env.HOME || os.homedir(), '.codex'), 'sessions'), now = Date.now() } = {}) {
+  const live = window => (window && typeof window.used_percent === 'number' && window.resets_at * 1000 > now ? window : null);
+  for (const file of recentSessionFiles(sessionsDir)) {
+    const lines = fs.readFileSync(file, 'utf8').trim().split('\n').reverse();
+    for (const line of lines) {
+      if (!line.includes('"used_percent"')) continue;
+      try {
+        const event = JSON.parse(line);
+        const limits = event.payload?.rate_limits;
+        if (!limits?.primary && !limits?.secondary) continue;
+        return { observedAt: event.timestamp || null, primary: live(limits.primary), secondary: live(limits.secondary) };
+      } catch { /* a partial line */ }
+    }
+  }
+  return null;
+}
+
+/** Quota walls from measured usage: a live window at 100% blocks the harness until it resets. */
+export function measuredWalls(limits = readCodexRateLimits()) {
+  const full = [limits?.primary, limits?.secondary].filter(window => window && window.used_percent >= 100);
+  if (!full.length) return {};
+  const until = Math.max(...full.map(window => window.resets_at)) * 1000;
+  return { codex: { until: new Date(until).toISOString(), resetReported: true, observedAt: limits.observedAt, message: 'Codex session log shows a rate-limit window at 100%.' } };
+}