total-recall-brain 3.47.0 → 3.47.2

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/package-lock.json

@@ -1,17 +1,17 @@
 {
   "name": "tr-plugin-meta-harness",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-meta-harness",
-      "version": "0.4.0",
+      "version": "0.4.2",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.14.5"
       },
       "devDependencies": {
-        "total-recall-brain": "3.45.0"
+        "total-recall-brain": "3.47.1"
       }
     },
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -5546,9 +5546,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.45.0",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.45.0.tgz",
-      "integrity": "sha512-HDYfROazZbsLHQsFPnlBcSpe1HL1QEi7JG8x/eNRUI06RxVQsZWl8LwBo2lTWjWRDrKmCy7BUmSXQDuWF3lrEw==",
+      "version": "3.47.1",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.47.1.tgz",
+      "integrity": "sha512-9yDByVZMNxNE10hjPf0vEmvBLGGUpD8sqAN7svuZpJEb2TSTPA1eSSwaZ5H4QScJQTT3DcV8MeQjuyLy8urnEw==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-meta-harness",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Total Recall Metaharness plugin",
   "type": "module",
   "scripts": {

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "meta-harness",
   "name": "Metaharness",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Discover, configure, document, track, and run coding agent harnesses through Total Recall across mesh nodes.",
   "gate": {
     "tasks": ["Run work in another agent harness", "Choose which harness takes a task", "Check harness versions, sign-in and quota", "Read a harness's official documentation"],
@@ -167,7 +167,8 @@
           { "name": "maxTokens", "flag": "--max-tokens", "type": "number", "label": "Job token limit" },
           { "name": "resultSchema", "flag": "--result-schema", "type": "string", "label": "JSON Schema file" },
           { "name": "approvals", "flag": "--approvals", "type": "string", "label": "auto, operator, or rules" },
-          { "name": "questionTimeoutMs", "flag": "--question-timeout-ms", "type": "number", "label": "Question timeout in milliseconds" }
+          { "name": "questionTimeoutMs", "flag": "--question-timeout-ms", "type": "number", "label": "Question timeout in milliseconds" },
+          { "name": "model", "flag": "--model", "type": "string", "label": "Model for this run, validated before launch (agy never runs Opus)" }
         ],
         "timeout_ms": 600000
       },
@@ -570,6 +571,7 @@
           { "name": "node", "flag": "--node", "type": "string", "label": "Selected mesh node" },
           { "name": "allowUnknownAuth", "flag": "--allow-unknown-auth", "type": "boolean", "label": "Explicitly allow a runner without a login probe" },
           { "name": "background", "flag": "--background", "type": "boolean", "label": "Return the owned job and log for a long run" },
+          { "name": "model", "flag": "--model", "type": "string", "label": "Model to run; only harnesses that can run it are chosen (agy never runs Opus)" },
           { "name": "timeoutMs", "flag": "--timeout-ms", "type": "number", "label": "Remote wall-clock limit in milliseconds" }
         ]
       },
@@ -627,6 +629,7 @@
           { "name": "node", "flag": "--node", "type": "string", "label": "Selected mesh node" },
           { "name": "allowUnknownAuth", "flag": "--allow-unknown-auth", "type": "boolean", "label": "Explicitly allow a runner without a login probe" },
           { "name": "background", "flag": "--background", "type": "boolean", "label": "Return the owned job and log for a long run" },
+          { "name": "model", "flag": "--model", "type": "string", "label": "Model for the Implementer, or every council and race seat (agy never runs Opus)" },
           { "name": "timeoutMs", "flag": "--timeout-ms", "type": "number", "label": "Remote wall-clock limit in milliseconds" }
         ],
         "timeout_ms": 600000

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

@@ -45,7 +45,8 @@ export async function executeRoutedTask(task, options = {}) {
   if (remote) return remote;
   if (options.node) localExecutionNode(options);
   const cwd = options.cwd || process.cwd();
-  const controls = sessionOptions({ ...options, cwd });
+  // The requested model travels with the controls, so every attempt and a queued replay run it.
+  const controls = { ...sessionOptions({ ...options, cwd }), ...(options.model !== undefined ? { model: options.model } : {}) };
   if (!isGitRepo(cwd)) throw new Error('Routed execution writes on its own branch, so it must run inside a git repository');
   const route = options.route || await routeTask(task, options);
   const replay = { kind: 'route', gate: options.gate === true, gateOptions: options.gateOptions, controls };
@@ -160,7 +161,8 @@ export async function executeRoutedTask(task, options = {}) {
     }
     if (stopped) return { ...stopped, route, attempts, alerts };
 
-    const remaining = pool.filter(item => !tried.has(item));
+    // Escalation stays with harnesses that can run the requested model.
+    const remaining = pool.filter(item => !tried.has(item) && (!route.modelSelection || route.modelSelection.compatible.includes(item)));
     const next = remaining.length ? evaluateGateCascade(harness, { testsPassed: false }, remaining) : null;
     diagnostic = attempt.gate?.summary || attempt.error || 'The previous attempt failed.';
     previous = harness;

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

@@ -18,6 +18,7 @@ import { runQualityGate } from './gate.mjs';
 import { forwardRemoteOperation } from './remote-operation.mjs';
 import { cancellationResult } from './worker.mjs';
 import { sessionOptions } from './session/run.mjs';
+import { createModelValidator, filterPoolByModel } from './model-selection.mjs';
 
 const OPEN_THREADS = new Set();
 const MAX_BLUEPRINT = 20000;
@@ -42,7 +43,12 @@ export function assignPipelineRoles(pool = [], options = {}) {
   const byCost = [...pool].sort((a, b) => a.costScore - b.costScore);
   const explorer = options.explorer ? findById(options.explorer) : byCost.find(h => h.id !== orchestrator.id) || orchestrator;
   const architect = options.architect ? findById(options.architect) : orchestrator;
-  const implementer = options.implementer ? findById(options.implementer) : sorted.find(h => h.id !== explorer.id && h.id !== architect.id) || sorted.find(h => h.id !== architect.id) || architect;
+  // A requested model is the Implementer's: only a harness that can run it writes the code.
+  const compatible = options.modelCompatible;
+  const writers = compatible ? sorted.filter(h => compatible.includes(h.id)) : sorted;
+  const implementer = options.implementer ? findById(options.implementer) : writers.find(h => h.id !== explorer.id && h.id !== architect.id) || writers.find(h => h.id !== architect.id) || (compatible ? writers[0] || null : architect);
+  if (compatible && implementer && !compatible.includes(implementer.id)) throw new Error(`Selected implementer ${implementer.id} cannot run model ${options.model}`);
+  if (!implementer) return { orchestrator, explorer, architect, implementer: null, verifier: null, heterogeneousFamilies: false };
   const verifier = options.verifier ? findById(options.verifier) : sorted.find(h => h.family !== implementer.family) || null;
   return { orchestrator, explorer, architect, implementer, verifier, heterogeneousFamilies: Boolean(verifier) && verifier.family !== implementer.family };
 }
@@ -81,15 +87,18 @@ async function runPipeline(task, poolInfo, options) {
   const execute = options.execute === true;
   const withSubagents = options.subagents !== false;
   const stages = roles.orchestrator ? buildStages(roles, withSubagents) : [];
-  const base = { mode: 'pipeline', task, orchestrator: roles.orchestrator?.id || null, executedLive: execute, excluded: poolInfo.excluded, heterogeneousFamiliesVerified: roles.heterogeneousFamilies, stages };
+  if (options.model !== undefined) for (const item of stages) if (item.role === 'Implementer') item.model = options.model;
+  const base = { mode: 'pipeline', task, ...modelFields(options), orchestrator: roles.orchestrator?.id || null, executedLive: execute, excluded: poolInfo.excluded, heterogeneousFamiliesVerified: roles.heterogeneousFamilies, stages };
 
   if (!execute) {
     const blockers = [];
     if (!roles.orchestrator) blockers.push('No harness can take work right now.');
+    else if (!roles.implementer) blockers.push(`No harness that can take work can run model ${options.model}.`);
     else if (!roles.heterogeneousFamilies) blockers.push('Only one model family is available, so no independent Verifier exists.');
     return { ...base, ok: blockers.length === 0, threadId: null, blockers };
   }
   if (!roles.orchestrator) throw new Error(`No harness can take work right now: ${poolInfo.excluded.map(e => `${e.harness} (${e.reason})`).join(', ') || 'none installed'}`);
+  if (!roles.implementer) throw new Error(`No harness that can take work can run model ${options.model}`);
   if (!roles.heterogeneousFamilies && options.allowSameFamily !== true) throw new Error('Refusing to run: only one model family is available, so no independent Verifier exists. Pass --allow-same-family to accept self-review.');
   if (!isGitRepo(cwd)) throw new Error('A pipeline writes on its own branch, so it must run inside a git repository');
 
@@ -105,6 +114,7 @@ async function runPipeline(task, poolInfo, options) {
     stage.status = 'running';
     const result = await dispatchWithReceipt({ agent: harness.id, node: 'local', cwd: workdir, contextCwd: cwd, contextTask: task, prompt,
       ...sessionOptions({ ...options, cwd }), goal: stage.role === 'Implementer' ? options.goal || task : prompt.slice(0, 4000),
+      ...(stage.role === 'Implementer' && options.model !== undefined ? { model: options.model } : {}),
       permissions: permissions || stage.permissions, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role, complexityScore: complexity.score });
     stage.status = result.cancelled ? 'cancelled' : result.ok ? 'completed' : result.queued ? 'queued' : 'failed';
     stage.output = result.response || result.error || null;
@@ -193,11 +203,11 @@ async function runCouncil(task, poolInfo, options) {
   // One seat per model family, strongest first, so the seats can actually disagree.
   const families = new Set();
   const seats = options.harnesses || [...poolInfo.ready].sort((a, b) => b.qualityScore - a.qualityScore).filter(h => !families.has(h.family) && families.add(h.family)).slice(0, 3).map(h => h.id);
-  if (options.execute !== true) return { ok: seats.length > 0, mode: 'council', task, executedLive: false, consensus: 'planned', excluded: poolInfo.excluded, votes: seats.map(harness => ({ harness, status: 'planned' })) };
+  if (options.execute !== true) return { ok: seats.length > 0, mode: 'council', task, ...modelFields(options), executedLive: false, consensus: 'planned', excluded: poolInfo.excluded, votes: seats.map(harness => ({ harness, status: 'planned' })) };
   if (!seats.length) throw new Error('No harness can take work right now');
   const cwd = options.cwd || process.cwd();
   const votes = await Promise.all(seats.map(async harness => {
-    const result = await dispatchWithReceipt({ agent: harness, node: 'local', cwd, contextTask: task, ...sessionOptions({ ...options, cwd }), prompt: `[ROLE: COUNCIL MEMBER]\nDo not change any file. Assess this proposal, with its trade-offs and risks:\n${task}\n\nEnd your reply with exactly one JSON object: {"vote":"APPROVE"|"REJECT","reason":"..."}`, permissions: READ, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Council' });
+    const result = await dispatchWithReceipt({ agent: harness, node: 'local', cwd, contextTask: task, ...sessionOptions({ ...options, cwd }), ...(options.model !== undefined ? { model: options.model } : {}), prompt: `[ROLE: COUNCIL MEMBER]\nDo not change any file. Assess this proposal, with its trade-offs and risks:\n${task}\n\nEnd your reply with exactly one JSON object: {"vote":"APPROVE"|"REJECT","reason":"..."}`, permissions: READ, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Council' });
     return { harness, ok: result.ok === true, failureKind: result.failureKind, ...(result.ok ? parseVote(result.response) : { vote: 'ABSTAIN', reason: null, error: result.error }),
       ...(result.queueId ? { queueId: result.queueId } : {}), feedback: result.response || null };
   }));
@@ -205,12 +215,12 @@ async function runCouncil(task, poolInfo, options) {
   const majority = votes.length / 2;
   const consensus = count('APPROVE') > majority ? 'approved' : count('REJECT') > majority ? 'rejected' : 'no-consensus';
   const limited = votes.some(item => item.failureKind === 'limit');
-  return { ok: !limited && votes.some(item => item.ok), ...(limited ? { failureKind: 'limit' } : {}), ...cancellationResult(), mode: 'council', task, executedLive: true, consensus, excluded: poolInfo.excluded, votes };
+  return { ok: !limited && votes.some(item => item.ok), ...(limited ? { failureKind: 'limit' } : {}), ...cancellationResult(), mode: 'council', task, ...modelFields(options), executedLive: true, consensus, excluded: poolInfo.excluded, votes };
 }
 
 async function runRace(task, poolInfo, options) {
   const seats = options.candidates || [...poolInfo.ready].sort((a, b) => b.qualityScore - a.qualityScore).slice(0, 2).map(h => h.id);
-  if (options.execute !== true) return { ok: seats.length > 1, mode: 'race', task, executedLive: false, excluded: poolInfo.excluded, candidates: seats.map(harness => ({ harness, status: 'planned' })) };
+  if (options.execute !== true) return { ok: seats.length > 1, mode: 'race', task, ...modelFields(options), executedLive: false, excluded: poolInfo.excluded, candidates: seats.map(harness => ({ harness, status: 'planned' })) };
   if (seats.length < 2) throw new Error('A race needs at least two harnesses that can take work');
   if (!options.gate) return { ok: false, mode: 'race', task, executedLive: false, verification: 'unverified', gateApplied: false, error: 'A race requires a deterministic quality gate before any candidate can win.' };
   const cwd = options.cwd || process.cwd();
@@ -223,7 +233,7 @@ async function runRace(task, poolInfo, options) {
     try {
       const started = Date.now();
       directory = createWorktree(cwd, { branch });
-      const result = await dispatchWithReceipt({ agent: harness, node: 'local', cwd: directory, contextCwd: cwd, contextTask: task, ...sessionOptions({ ...options, cwd }), goal: options.goal || task, prompt: `[ROLE: IMPLEMENTER]\nWork only in this checkout. Implement the task and its tests. Do not commit.\nTask:\n${task}`, permissions: WRITE, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Race' });
+      const result = await dispatchWithReceipt({ agent: harness, node: 'local', cwd: directory, contextCwd: cwd, contextTask: task, ...sessionOptions({ ...options, cwd }), goal: options.goal || task, ...(options.model !== undefined ? { model: options.model } : {}), prompt: `[ROLE: IMPLEMENTER]\nWork only in this checkout. Implement the task and its tests. Do not commit.\nTask:\n${task}`, permissions: WRITE, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Race' });
       const commit = result.ok || result.cancelled ? commitAll(directory, `meta-harness race: ${task.slice(0, 60)}\n\nAgent: ${harness}`) : null;
       if (result.cancelled) {
         keep = Boolean(commit);
@@ -247,9 +257,11 @@ async function runRace(task, poolInfo, options) {
   }));
   const finishers = entries.filter(entry => entry.ok).sort((a, b) => a.completedAt - b.completedAt);
   const limited = entries.some(item => item.failureKind === 'limit');
-  return { ok: !limited && finishers.length > 0, ...(limited ? { failureKind: 'limit' } : {}), ...cancellationResult(), mode: 'race', task, executedLive: true, gateApplied: true, verification: !limited && finishers.length ? 'passed' : 'failed', winner: limited ? null : finishers[0]?.harness || null, excluded: poolInfo.excluded, candidates: entries };
+  return { ok: !limited && finishers.length > 0, ...(limited ? { failureKind: 'limit' } : {}), ...cancellationResult(), mode: 'race', task, ...modelFields(options), executedLive: true, gateApplied: true, verification: !limited && finishers.length ? 'passed' : 'failed', winner: limited ? null : finishers[0]?.harness || null, excluded: poolInfo.excluded, candidates: entries };
 }
 
+const modelFields = options => options.model !== undefined ? { model: options.model, modelSelection: options.modelSelection } : {};
+
 export async function coordinateTask(taskDescription, options = {}) {
   if (cancellationResult()) return cancellationResult();
   const task = String(taskDescription || '').trim();
@@ -259,7 +271,14 @@ export async function coordinateTask(taskDescription, options = {}) {
   const mode = options.mode || 'pipeline';
   if (!['pipeline', 'orchestrate', 'council', 'race'].includes(mode)) throw new Error(`Unsupported coordination mode: ${mode}`);
   localExecutionNode(options);
-  const poolInfo = await resolvePool(options);
+  let poolInfo = await resolvePool(options);
+  if (options.model !== undefined) {
+    // Council and race seats all run the model, so their pool narrows. A pipeline keeps every harness
+    // for its other roles and gives the Implementer role to one that can run the model.
+    const filtered = filterPoolByModel(poolInfo, options.model, options.modelValidator || createModelValidator());
+    options = { ...options, modelSelection: filtered.selection, modelCompatible: filtered.selection.compatible };
+    if (mode === 'council' || mode === 'race') poolInfo = filtered.pool;
+  }
   const wall = poolInfo.excluded.find(item => item.failureKind === 'quota');
   const minimum = mode === 'race' || ((mode === 'pipeline' || mode === 'orchestrate') && options.allowSameFamily !== true) ? 2 : 1;
   if (options.execute === true && wall && poolInfo.ready.length < minimum) {

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

@@ -6,11 +6,17 @@ import { isGitRepo, createWorktree, removeWorktree, commitAll, deleteBranch } fr
 import { randomUUID } from 'node:crypto';
 import { includedAdmission, openRouterAdmission, readIncludedPolicy } from './included-usage.mjs';
 import { queueIncludedJob } from './usage-queue.mjs';
+import { createModelValidator } from './model-selection.mjs';
 
 export async function dispatchWithReceipt(request, { dispatchFn, node = request.node || 'local', role, complexityScore, escalatedFrom,
-  record = recordRunReceipt, replay, retryId, manageWrites = false, usagePolicy = readIncludedPolicy, admit = includedAdmission, admitOpenRouter = openRouterAdmission } = {}) {
+  record = recordRunReceipt, replay, retryId, manageWrites = false, validateModel, usagePolicy = readIncludedPolicy, admit = includedAdmission, admitOpenRouter = openRouterAdmission } = {}) {
   const started = Date.now();
   if (cancellationResult()) return cancellationResult();
+  // A model this harness must not or cannot run is refused before launch; it says nothing about the harness, so no receipt.
+  if (request.model !== undefined) {
+    const check = (validateModel || createModelValidator({ local: node === 'local' }))(request.agent, request.model);
+    if (!check.ok) return { ok: false, agent: request.agent, failureKind: 'model', error: check.reason, modelCheck: check, launchPrevented: true, exitCode: null, durationMs: Date.now() - started };
+  }
   // A harness that cannot be told not to write does read-only work in a checkout that is thrown away.
   const contain = node === 'local' && request.permissions?.write !== true && !READ_ONLY_ADAPTERS.includes(request.agent) && request.isolated !== true && isGitRepo(request.cwd);
   const ownWrites = manageWrites && node === 'local' && request.permissions?.write === true && isGitRepo(request.cwd);
@@ -73,7 +79,7 @@ export async function dispatchWithReceipt(request, { dispatchFn, node = request.
     // exhausted until its reset and picks another included harness instead of choosing it again.
     if (result.failureKind === 'quota') {
       try { await record({ harness: request.agent, role, task: String(request.contextTask || request.prompt || '').slice(0, 200), success: false,
-        failureKind: 'quota', error: result.error, resetsAt: result.resetsAt || null }); } catch { /* bookkeeping must not hide the refusal */ }
+        failureKind: 'quota', billingMode, error: result.error, resetsAt: result.resetsAt || null }); } catch { /* bookkeeping must not hide the refusal */ }
     }
     return { ...result, launchPrevented, durationMs };
   }

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

@@ -7,7 +7,7 @@ import { createInterface } from 'node:readline';
 import { pathToFileURL } from 'node:url';
 import { configDir } from './paths.mjs';
 import { agentEnvironment, CODEX_PLAN_ARGS, findBinary, OPENROUTER_AGENTS, readClaudeMaxOrganization } from './worker.mjs';
-import { activeQuotaWalls, readReceipts } from './learner.mjs';
+import { activeQuotaWalls, includedBillingReceipts, readReceipts } from './learner.mjs';
 
 export const INCLUDED_AGENTS = ['claude', 'codex'];
 const VERSION = 1;
@@ -235,7 +235,7 @@ export async function includedAdmission(agent, cwd, policy, { readKey = authKey,
   if (agent === 'claude' && !policy.claudePlan && !claudeProofCurrent(policy)) {
     return { ok: false, failureKind: 'billing-policy', error: 'Verify the native Claude Max login with Usage credits off, or bind a verified included grant.' };
   }
-  const wall = activeQuotaWalls((await receipts()).filter(run => run.billingMode === 'included'))[agent];
+  const wall = activeQuotaWalls(includedBillingReceipts(await receipts()))[agent];
   if (wall) return { ok: false, failureKind: 'quota', error: 'This harness is waiting for included usage.', resetsAt: wall.resetReported ? wall.until : null };
   if (agent === 'codex') return codex(cwd);
   if (policy.claudePlan) return { ok: true, claudePlan: policy.claudePlan.organization };

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

@@ -60,6 +60,13 @@ export async function recordRunReceipt(receipt = {}) {
   return entry;
 }
 
+/**
+ * Receipts that count under the included usage policy: included runs, plus quota refusals recorded before
+ * refusals carried a billingMode. Those legacy walls expire at their reset, so nothing stale lingers.
+ */
+export const includedBillingReceipts = (entries = []) =>
+  entries.filter(run => run.billingMode === 'included' || (!run.billingMode && run.failureKind === 'quota'));
+
 /** A harness is walled from its last quota failure until the reported reset, or until a later success proves it clear. */
 export function activeQuotaWalls(entries = [], now = Date.now(), unknownResetMs = 60 * 60 * 1000) {
   const latest = new Map();

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

@@ -0,0 +1,59 @@
+/**
+ * Which harness may run a requested model. Shape, operator policy and harness support come first
+ * (worker.mjs, so a remote destination enforces them too). Then the AI Models plugin, which owns the
+ * shared model catalog, decides when it answers `ai-models validate`. When it cannot answer, this
+ * machine's synced harness model lists decide; a harness without a list is accepted as unverified.
+ */
+import { execFileSync } from 'node:child_process';
+import { modelRefusal } from './worker.mjs';
+import { getModelCatalog, normalizeModelName } from './model-catalog.mjs';
+
+/** Ask the AI Models owner. Null means it gave no verdict (not installed, not implemented, or unreadable). */
+export function queryAiModels(harness, model, { bin = process.env.TOTAL_RECALL_BIN || 'total-recall' } = {}) {
+  let output;
+  try {
+    output = execFileSync(bin, ['ai-models', 'validate', '--harness', harness, '--model', model, '--json'], { encoding: 'utf8', timeout: 20000, stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch (error) {
+    // A refusal may exit nonzero with its verdict on stdout.
+    output = String(error.stdout || '');
+  }
+  const line = output.trim().split('\n').filter(Boolean).at(-1);
+  try {
+    const answer = JSON.parse(line);
+    return answer && typeof answer.ok === 'boolean' ? answer : null;
+  } catch { return null; }
+}
+
+/** One validator per decision: after the owner fails to answer once, it is not asked again. */
+export function createModelValidator({ aiModels = queryAiModels, catalog = getModelCatalog, local = true } = {}) {
+  let ownerAnswers = true, listed;
+  return (harness, model) => {
+    const refusal = modelRefusal(harness, model);
+    if (refusal) return { ok: false, harness, model, source: 'policy', reason: refusal };
+    if (ownerAnswers) {
+      const answer = aiModels(harness, model);
+      if (answer) return { ok: answer.ok, harness, model, source: 'ai-models', ...(answer.ok ? {} : { reason: answer.reason || answer.error || `AI Models does not list ${model} for ${harness}` }) };
+      ownerAnswers = false;
+    }
+    // Another node's catalog is not this one's: its destination validates against its own.
+    if (!local) return { ok: true, harness, model, source: 'unverified', note: 'The destination node validates the model before launch.' };
+    listed ??= catalog().harnessModels || {};
+    const models = listed[harness];
+    if (Array.isArray(models) && models.length) {
+      const key = normalizeModelName(model);
+      if (models.some(row => row.id === model || normalizeModelName(row.id) === key)) return { ok: true, harness, model, source: 'catalog' };
+      return { ok: false, harness, model, source: 'catalog', reason: `${harness} does not list ${model}. Listed: ${models.slice(0, 12).map(row => row.id).join(', ')}` };
+    }
+    return { ok: true, harness, model, source: 'unverified', note: `No model list for ${harness}; only a completed run proves ${model} works there.` };
+  };
+}
+
+/** Split a pool by whether each harness can run the model. */
+export function filterPoolByModel(pool, model, validate) {
+  const checks = pool.ready.map(harness => validate(harness.id, model));
+  return {
+    pool: { ...pool, ready: pool.ready.filter((_, index) => checks[index].ok),
+      excluded: [...pool.excluded, ...checks.filter(check => !check.ok).map(check => ({ harness: check.harness, reason: check.reason, failureKind: 'model' }))] },
+    selection: { model, compatible: checks.filter(check => check.ok).map(check => check.harness), checks },
+  };
+}

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

@@ -1,7 +1,7 @@
 /** The harnesses that can actually take work right now, and why the others cannot. */
 import { ADAPTER_CATALOG } from '../capability/index.mjs';
 import { inspectAgents, getActiveAdapters } from './worker.mjs';
-import { readReceipts, activeQuotaWalls, activeCredentialBlocks } from './learner.mjs';
+import { readReceipts, activeQuotaWalls, activeCredentialBlocks, includedBillingReceipts } from './learner.mjs';
 import { measuredWalls } from './telemetry.mjs';
 import { claudeProofCurrent, INCLUDED_AGENTS, readIncludedPolicy } from './included-usage.mjs';
 import os from 'node:os';
@@ -29,7 +29,7 @@ export async function resolvePool({ availableHarnesses, inspect = inspectAgents,
   if (!policy.enabled && Array.isArray(availableHarnesses) && availableHarnesses.length) return { ready: availableHarnesses.map(id => describe(id)), excluded: [], walls: {} };
   const claudePlan = policy.enabled ? policy.claudePlan?.organization : undefined;
   const [{ agents = [] }, entries] = await Promise.all([inspect({ env: process.env, claudePlan }), receipts()]);
-  const billingEntries = policy.enabled ? entries.filter(run => run.billingMode === 'included') : entries;
+  const billingEntries = policy.enabled ? includedBillingReceipts(entries) : entries;
   const walls = { ...activeQuotaWalls(billingEntries), ...(!policy.enabled ? measuredWalls() : {}) };
   const blocks = activeCredentialBlocks(billingEntries);
   const ready = [], excluded = [];

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

@@ -10,11 +10,11 @@ const BOOLEAN_FLAGS = {
 const VALUE_FLAGS = {
   mode: '--mode', orchestrator: '--orchestrator', explorer: '--explorer', architect: '--architect', implementer: '--implementer',
   goal: '--goal', maxTurns: '--max-turns', maxBudgetUsd: '--max-budget-usd', maxTokens: '--max-tokens', approvalPolicy: '--approvals', questionTimeoutMs: '--question-timeout-ms', resultSchema: '--result-schema',
-  verifier: '--verifier', reviewer: '--reviewer', author: '--author', threadId: '--thread', branch: '--branch',
+  verifier: '--verifier', reviewer: '--reviewer', author: '--author', threadId: '--thread', branch: '--branch', model: '--model',
 };
 const OPERATION_KEYS = {
-  route: ['execute', 'gate', 'jev', 'preferLocal', 'preferFrontier', 'allowUnknownAuth'],
-  coordinate: ['execute', 'gate', 'autoReview', 'allowSameFamily', 'allowUnknownAuth', 'mode', 'orchestrator', 'explorer', 'architect', 'implementer', 'verifier', 'reviewer', 'branch'],
+  route: ['execute', 'gate', 'jev', 'preferLocal', 'preferFrontier', 'allowUnknownAuth', 'model'],
+  coordinate: ['execute', 'gate', 'autoReview', 'allowSameFamily', 'allowUnknownAuth', 'mode', 'orchestrator', 'explorer', 'architect', 'implementer', 'verifier', 'reviewer', 'branch', 'model'],
   review: ['staged', 'allowUnknownAuth', 'reviewer', 'author', 'threadId'],
 };
 

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

@@ -18,11 +18,12 @@ import { classifyTaskComplexity, selectOptimalHarness, computeEmpiricalScorecard
 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 { readReceipts, activeQuotaWalls, activeCredentialBlocks, includedBillingReceipts } from './learner.mjs';
 import { resolvePool, exclusionReason, isLocalExecutionNode } from './pool.mjs';
 import { readCodexRateLimits, measuredWalls } from './telemetry.mjs';
 import { claudeProofCurrent, INCLUDED_AGENTS, readIncludedPolicy } from './included-usage.mjs';
 import { derivedDir } from './paths.mjs';
+import { createModelValidator, filterPoolByModel } from './model-selection.mjs';
 
 /**
  * Helper to safely query host Total Recall CLI without assumptions
@@ -168,7 +169,7 @@ export async function inspectQuotas(options = {}) {
   const inspected = remote ? await (options.inspectNodeFn || inspectNode)(options.node) :
     await (options.inspect || inspectAgents)({ env: process.env, cwd: options.cwd, claudePlan });
   const codexLimits = remote ? null : readCodexRateLimits();
-  const receipts = remote ? [] : (await readReceipts()).filter(run => !policy.enabled || run.billingMode === 'included');
+  const receipts = remote ? [] : (policy.enabled ? includedBillingReceipts : runs => runs)(await (options.receipts || readReceipts)());
   const walls = remote ? {} : { ...activeQuotaWalls(receipts), ...(!policy.enabled ? measuredWalls(codexLimits) : {}) };
   const metered = METERED_HARNESSES;
 
@@ -273,7 +274,10 @@ export async function routeTask(taskDescription, options = {}) {
   // fleet telemetry places local work, and the balance matters only to a metered harness.
   const shared = scoped.inspect ? null : inspectAgents({ env: process.env });
   const lean = shared ? { ...scoped, inspect: () => shared } : scoped;
-  const [pool, receipts] = await Promise.all([resolvePool({ ...lean, policy }), readReceipts()]);
+  const [resolved, receipts] = await Promise.all([resolvePool({ ...lean, policy }), readReceipts()]);
+  // A requested model narrows the pool to the harnesses that can run it, and says why the others cannot.
+  const { pool, selection: modelSelection } = options.model === undefined ? { pool: resolved, selection: null }
+    : filterPoolByModel(resolved, options.model, options.modelValidator || createModelValidator({ local: !remote }));
   const quotaReport = await inspectQuotas({
     ...lean,
     policy,
@@ -289,10 +293,12 @@ export async function routeTask(taskDescription, options = {}) {
   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.');
+  if (!routing.selected) warnings.push(modelSelection ? `No harness that can run ${options.model} can take this task right now.` : 'No harness can take this task right now.');
+  const selectedModel = modelSelection?.checks.find(check => check.harness === routing.selected);
+  if (selectedModel?.source === 'unverified') warnings.push(selectedModel.note);
   return {
     ok: Boolean(routing.selected), task: taskDescription, classifier, complexity,
-    selected: routing.selected, tier: complexity.tier, candidates: routing.candidates, excluded: pool.excluded,
+    selected: routing.selected, tier: complexity.tier, model: options.model ?? null, ...(modelSelection ? { modelSelection } : {}), candidates: routing.candidates, excluded: pool.excluded,
     ...(policy.enabled && !routing.selected ? { deferred: pool.excluded.find(row => row.failureKind === 'quota') || null } : {}),
     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.',

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

@@ -73,6 +73,43 @@ export const ADAPTERS = [
   { id: 'hermes', name: 'Hermes', binary: 'hermes', args: ['chat', '--oneshot', '--format', 'stream-json', '--query-file', '-'], input: 'stdin', docs: 'https://github.com/NousResearch/hermes-agent/blob/main/website/docs/reference/cli-commands.md' }
 ];
 
+/**
+ * How each harness takes a model for one run, from its official CLI reference (read 2026-11-14 through
+ * `meta-harness docs-search`). A flag goes after the subcommand, before the flag that carries the prompt.
+ * DSH has no per-run model flag: its headless profile owns the model (`total-recall dsh model`).
+ */
+export const MODEL_SELECTION = Object.freeze({
+  claude: { flag: '--model' }, codex: { flag: '--model' }, agy: { flag: '--model' }, cursor: { flag: '--model' },
+  grok: { flag: '--model' }, muse: { flag: '--model' }, pi: { flag: '--model' }, hermes: { flag: '--model' },
+  openclaw: { flag: '--model' }, aider: { flag: '--model' }, cline: { flag: '--model' },
+  goose: { env: 'GOOSE_MODEL' },
+  // OpenHands ignores LLM_MODEL unless the run also passes --override-with-envs; the override is not persisted.
+  openhands: { env: 'LLM_MODEL', args: ['--override-with-envs'] },
+  ollama: { positional: true },
+});
+// Operator policy: Antigravity never runs an Opus model, although `agy models` lists them.
+const MODEL_POLICY = [{ harness: 'agy', test: model => /opus/i.test(model), reason: 'Antigravity (agy) must not run Opus models. Choose a Gemini or Sonnet model, or route Opus work to claude.' }];
+
+/** Why this harness cannot run this model, or null. Shape, operator policy and harness support only; catalogs live elsewhere. */
+export function modelRefusal(harness, model) {
+  if (typeof model !== 'string' || !model.trim() || model.length > 200 || /[\0-\x1f\s]/.test(model) || model.startsWith('-')) return 'Invalid requested model';
+  const policy = MODEL_POLICY.find(rule => rule.harness === harness && rule.test(model));
+  if (policy) return policy.reason;
+  if (!Object.hasOwn(MODEL_SELECTION, harness)) {
+    return harness === 'dsh' ? 'DSH selects its model through its headless profile; set it with `total-recall dsh model`.' : `${harness} does not declare how it selects a model`;
+  }
+  return null;
+}
+
+/** Put the model where the harness reads it. Returns the environment the launch adds. */
+export function applyModel(harness, model, args) {
+  const selection = MODEL_SELECTION[harness];
+  const at = args.length && !args[0].startsWith('-') ? 1 : 0;
+  if (selection.flag) args.splice(at, 0, selection.flag, model);
+  if (selection.args) args.splice(at, 0, ...selection.args);
+  return selection.env ? { [selection.env]: model } : {};
+}
+
 export const EXTENDED_ADAPTERS = [
   { id: 'ollama', name: 'Ollama', binary: 'ollama', args: ['run'], input: 'stdin', docs: 'https://ollama.com/library' },
   { id: 'openclaw', name: 'OpenClaw', binary: 'openclaw', args: ['agent', '--message'], input: 'argument', docs: 'https://openclaw.ai/docs' },
@@ -535,7 +572,12 @@ export async function totalRecallBootstrap(request, { probe = runProcess, env =
   if (docs.ok !== true) throw notReady('Official agent documentation is unavailable or stale');
   // Node built-ins only here (this file ships to remote nodes): the result is the pretty-printed JSON after any log lines.
   let found = null;
-  try { const out = await invoke(['help', task, '--json']); const at = out.indexOf('{\n'); found = JSON.parse(at >= 0 ? out.slice(at) : out); }
+  try {
+    const res = await probe(binary, ['help', task, '--json'], { cwd, timeoutMs: 30000, maxBytes: 1024 * 1024, env: agentEnvironment(env) });
+    const out = String(res.stdout || '');
+    const at = out.indexOf('{\n');
+    if (at >= 0 || out.trim().startsWith('{')) found = JSON.parse(at >= 0 ? out.slice(at) : out);
+  }
   catch (error) { if (error.code === 'NOT_READY') throw error; found = null; }
   const matches = Array.isArray(found?.matches) ? found.matches.slice(0, 12) : [];
   const references = `${matches.length ? `Commands that match this task (Total Recall semantic command search):\n${matches.map(m => `- ${m.verb} — ${m.description}`).join('\n')}\n` : ''}For anything else, run total-recall help "<what you need>" to find the command, then total-recall <namespace> --help for its arguments. Do not load whole command inventories.`;
@@ -661,6 +703,7 @@ export async function dispatchAgent(request, { probe = runProcess, env = process
     credentials[name] = value;
   }
   const args = [...adapter.args];
+  let modelEnv = {};
   const openClawSession = openRouter && adapter.id === 'openclaw' ? randomUUID() : null;
   if (openRouter) {
     if (adapter.id === 'pi') args.push('--model', openRouter.model);
@@ -668,9 +711,10 @@ export async function dispatchAgent(request, { probe = runProcess, env = process
     if (openClawSession) args.splice(1, 0, '--agent', 'main', '--session-id', openClawSession,
       '--model', `openrouter/${openRouter.model}`, '--json');
   } else if (request.model !== undefined) {
-    if (typeof request.model !== 'string' || !request.model.trim() || /[\0\r\n]/.test(request.model)) throw new Error('Invalid requested model');
-    if (adapter.id === 'ollama') throw new Error('Select the local chat model through its configured runtime');
-    args.push('--model', request.model);
+    const refusal = modelRefusal(adapter.custom ? `custom adapter ${adapter.id}` : adapter.id, request.model);
+    if (refusal) throw notReady(refusal);
+    if (adapter.id === 'ollama' && !state.chatModels.includes(request.model)) throw notReady(`Ollama has no chat model ${request.model} on this node`);
+    modelEnv = applyModel(adapter.id, request.model, args);
   }
   if (request.tools !== undefined || request.settingSources !== undefined || request.allowedTools !== undefined) {
     if (adapter.id !== 'claude') throw notReady(`${adapter.name} cannot enforce the requested tools/settings restriction`);
@@ -705,7 +749,7 @@ export async function dispatchAgent(request, { probe = runProcess, env = process
   if (adapter.id === 'agy') args[args.indexOf('--mode') + 1] = allowWrites ? 'accept-edits' : 'plan';
   if (adapter.id === 'muse' && !allowWrites) args.push('--disable-write');
   if (adapter.id === 'pi') args[args.indexOf('--tools') + 1] = allowWrites ? 'read,bash,edit,write' : 'read';
-  if (adapter.id === 'ollama') args.push(env.TR_OLLAMA_MODEL || state.chatModels[0]);
+  if (adapter.id === 'ollama') args.push(request.model ?? (env.TR_OLLAMA_MODEL || state.chatModels[0]));
   const progressFile = request.progressFile || path.join(
     env.TR_SECRETS_BRAIN || path.join(env.AGENT_DIR || path.join(env.HOME || os.homedir(), '.agent'), 'skills/total-recall'),
     'config/meta-harness/jobs', `${request.jobId || process.env.TR_METAHARNESS_JOB || `session-${randomUUID()}`}.events.jsonl`);
@@ -737,7 +781,7 @@ export async function dispatchAgent(request, { probe = runProcess, env = process
   };
   try {
     parsed = await (sessionRunner || runSession)({ request, adapter, binary, args,
-      env: { ...agentEnvironment(env), ...credentials, TR_META_HARNESS_RUN: '1' }, prompt, progress: liveProgress, onFrame: captureFrame,
+      env: { ...agentEnvironment(env), ...credentials, ...modelEnv, TR_META_HARNESS_RUN: '1' }, prompt, progress: liveProgress, onFrame: captureFrame,
       register: stop => { const id = Symbol('session'); ACTIVE_GROUPS.set(id, stop); return () => ACTIVE_GROUPS.delete(id); } });
     if (cancellationResult()) parsed = { ...parsed, ...cancellationResult() };
     if (frames.length) Object.assign(parsed, toolEvidence(nativeToolResults(adapter.id, frames)));

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/ui/chunks/session-controls.md

@@ -0,0 +1,16 @@
+---
+type: ui-chunk:chunk
+plugin: meta-harness
+id: session-controls
+title: Session controls and reviews
+description: Fork, resume, cancel, reply, approve, interrupt, set goals, manage MCP servers, watch progress, and inspect independent reviews.
+timestamp: "2026-11-14T08:51:00Z"
+intents: [control harness sessions, approve or interrupt run, watch session, inspect independent reviews, manage mcp]
+surfaces: [page]
+operations: [fork, resume, cancel, reply, approve, interrupt, goal, mcp, watch, reviews]
+---
+
+<section>
+  <h2>Session controls &amp; reviews</h2>
+  <p>Manage active harness runs (fork, resume, reply, approve, interrupt, cancel, goal, watch), configure MCP bindings, and review independent verification runs.</p>
+</section>