total-recall-brain 3.43.2 → 3.44.0

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

@@ -1,17 +1,17 @@
 {
   "name": "tr-plugin-meta-harness",
-  "version": "0.3.4",
+  "version": "0.3.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-meta-harness",
-      "version": "0.3.4",
+      "version": "0.3.9",
       "dependencies": {
-        "@gregiteen/ssss-cli": "0.14.4"
+        "@gregiteen/ssss-cli": "0.14.5"
       },
       "devDependencies": {
-        "total-recall-brain": "3.42.1"
+        "total-recall-brain": "3.43.3"
       }
     },
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -714,9 +714,9 @@
       "license": "MIT"
     },
     "node_modules/@gregiteen/ssss-cli": {
-      "version": "0.14.4",
-      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.14.4.tgz",
-      "integrity": "sha512-R6JIgPRvS9xXp0xb6BYO3rauv+72r35GIiDrJcvbjPdTSHFZXr8/jRxFOgoF8yTed/5xyGFF3ey3DI9bOjmHVA==",
+      "version": "0.14.5",
+      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.14.5.tgz",
+      "integrity": "sha512-qVEYOocnwn97uJ0eDzmuwN06CYsYWr2t3+iKylpisBHX4wlLWk7P8EmFFdBlx7NyKVIZDDeYT164Gd7/T8UGgw==",
       "license": "ISC",
       "bin": {
         "ssss": "scripts/ssss.mjs"
@@ -1589,9 +1589,9 @@
     },
     "node_modules/@ssss/cli": {
       "name": "@gregiteen/ssss-cli",
-      "version": "0.14.4",
-      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.14.4.tgz",
-      "integrity": "sha512-R6JIgPRvS9xXp0xb6BYO3rauv+72r35GIiDrJcvbjPdTSHFZXr8/jRxFOgoF8yTed/5xyGFF3ey3DI9bOjmHVA==",
+      "version": "0.14.5",
+      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.14.5.tgz",
+      "integrity": "sha512-qVEYOocnwn97uJ0eDzmuwN06CYsYWr2t3+iKylpisBHX4wlLWk7P8EmFFdBlx7NyKVIZDDeYT164Gd7/T8UGgw==",
       "dev": true,
       "license": "ISC",
       "bin": {
@@ -5546,9 +5546,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.42.1",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.42.1.tgz",
-      "integrity": "sha512-woH7mdkGwPFYlKPZurhE8L3BPe+cSeIruNGaPOjGZJm/O8C92Bbr1gsdOY0tTLg5QHlgPHcXG1GMtsm9lPDz8w==",
+      "version": "3.43.3",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.43.3.tgz",
+      "integrity": "sha512-yjfPN/BQxEEa+iodyFXQov/6fRt1pZg/7RcmgsbpALwBt6Ki3JJjT3tzArBC7NxHQmXgGYyKnCYId6xe/W2rPg==",
       "dev": true,
       "license": "MIT",
       "workspaces": [
@@ -5579,6 +5579,7 @@
         "antigravity": "bin/antigravity.mjs",
         "total-recall": "bin/total-recall.mjs",
         "total-recall-memory": "bin/total-recall-memory.mjs",
+        "total-recall-server-release": "bin/total-recall-server-release.mjs",
         "vibebrain": "bin/total-recall.mjs"
       },
       "optionalDependencies": {

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

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-meta-harness",
-  "version": "0.3.4",
+  "version": "0.3.9",
   "description": "Total Recall Meta Harness plugin",
   "type": "module",
   "scripts": {
@@ -22,9 +22,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@gregiteen/ssss-cli": "0.14.4"
+    "@gregiteen/ssss-cli": "0.14.5"
   },
   "overrides": {
-    "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.4"
+    "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.5"
   }
 }

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

@@ -1,7 +1,7 @@
 {
   "id": "meta-harness",
   "name": "Meta Harness",
-  "version": "0.3.4",
+  "version": "0.3.9",
   "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"],
@@ -67,6 +67,27 @@
         ],
         "timeout_ms": 120000
       },
+      {
+        "name": "adoption",
+        "description": "Check installed agents, native gate activity and managed run receipts on this node or the mesh",
+        "effect": "read",
+        "output": "json",
+        "args": [
+          {
+            "name": "node",
+            "flag": "--node",
+            "type": "string",
+            "label": "Mesh node"
+          },
+          {
+            "name": "all",
+            "flag": "--all",
+            "type": "boolean",
+            "label": "Check the recorded fleet"
+          }
+        ],
+        "timeout_ms": 120000
+      },
       {
         "name": "run-command",
         "description": "Run an explicit plugin command through the selected agent and node using a JSON request on stdin",
@@ -77,7 +98,7 @@
       },
       {
         "name": "runtime",
-        "description": "Manage any agent runtime; includes Hermes gateway/auth/skills/plugins and DSH observations",
+        "description": "Inspect a runtime or run supported maintenance; agent tasks use dispatch",
         "effect": "write",
         "output": "json",
         "args": [
@@ -91,7 +112,7 @@
           {
             "name": "operation",
             "type": "string",
-            "label": "Native operation",
+            "label": "Maintenance operation",
             "required": true,
             "positional": true
           }
@@ -106,6 +127,67 @@
         "args": [],
         "timeout_ms": 600000
       },
+      {
+        "name": "included-status",
+        "description": "Read included usage policy and optionally check Codex allowance without a turn",
+        "effect": "read",
+        "output": "json",
+        "args": [{ "name": "probe", "flag": "--probe", "type": "boolean", "label": "Read live Codex allowance" }]
+      },
+      {
+        "name": "included-enforce",
+        "description": "Require included usage for managed agent dispatch on this node",
+        "effect": "write",
+        "output": "json",
+        "args": []
+      },
+      {
+        "name": "included-bind-claude",
+        "description": "Bind verified Max credit evidence on stdin to an existing Auth key",
+        "effect": "write",
+        "output": "json",
+        "args": []
+      },
+      {
+        "name": "included-bind-claude-plan",
+        "description": "Bind the signed-in Claude Max account after verifying Usage credits are off",
+        "effect": "write",
+        "output": "json",
+        "args": []
+      },
+      {
+        "name": "openrouter-bind",
+        "description": "Authorize an explicit OpenRouter harness with a verified Total Recall Auth key and catalog model",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          { "name": "agent", "type": "string", "label": "Harness", "required": true, "positional": true },
+          { "name": "key", "type": "string", "label": "Auth key name", "required": true, "positional": true },
+          { "name": "model", "flag": "--model", "type": "string", "label": "OpenRouter model ID", "required": true }
+        ]
+      },
+      {
+        "name": "usage-queue",
+        "description": "List jobs waiting for included usage and their reset evidence",
+        "effect": "read",
+        "output": "json",
+        "args": []
+      },
+      {
+        "name": "usage-retry",
+        "description": "Retry a waiting job after checking included usage",
+        "effect": "write",
+        "output": "json",
+        "args": [{ "name": "job", "type": "string", "label": "Queued job ID", "required": true, "positional": true }],
+        "timeout_ms": 600000
+      },
+      {
+        "name": "usage-cancel",
+        "description": "Cancel a waiting included usage job",
+        "effect": "write",
+        "output": "json",
+        "args": [{ "name": "job", "type": "string", "label": "Queued job ID", "required": true, "positional": true }]
+      },
       {
         "name": "docs-status",
         "description": "Verify cached official documentation coverage freshness and hashes",

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

@@ -25,7 +25,8 @@ Coordinates coding agent harnesses across mesh nodes. `cli-agents` is an alias o
 - `review [<git-range>] [--staged] [--author <id>] [--reviewer <id>] [--thread <id>]`: review by another model family. `NO_DIFF` means there was nothing to review.
 - `dispatch --stdin` with JSON `{agent, cwd, prompt, permissions, node, allowUnknownAuth}`: one bootstrapped run with a receipt.
 - `threads list|show|create|close|delete`, `learn [--emit]`, `alerts check|test [--dry-run]`, `adapter list|add|remove`.
-- `docs-status`, `docs-refresh`, `docs-search --query <q>`, `docs-read`, `maintenance`, `setup`, `runtime <agent> <args>`.
+- `adoption [--node <id> | --all]`: inspect native gate activity and real managed run receipts separately from installation and login.
+- `docs-status`, `docs-refresh`, `docs-search --query <q>`, `docs-read`, `maintenance`, `setup`, `runtime <agent> <maintenance-command>`. Use dispatch for agent tasks and the service owner for gateway changes.
 
 ## When something fails
 Read `failureKind` on the result. `quota` carries `resetsAt`, and routing avoids that harness until then. `auth` and `not-ready` mean the operator must sign in or install something. These do not count against a harness's pass rate; `agent` and `gate` failures do.

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

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import { executeOnNode, listTargets } from './executor.mjs';
+import { readReceipts } from './learner.mjs';
+import { agentEnvironment, findBinary, inspectAgents, runProcess } from './worker.mjs';
+
+const { version } = JSON.parse(fs.readFileSync(new URL('../plugin.json', import.meta.url), 'utf8'));
+
+async function readPreflight(args) {
+  const binary = findBinary('total-recall');
+  if (!binary) throw new Error('Total Recall CLI is unavailable');
+  const result = await runProcess(binary, ['preflight', ...args, '--json'], {
+    cwd: os.homedir(), env: agentEnvironment(), timeoutMs: 25000,
+  });
+  if (result.reason || result.exitCode !== 0) throw new Error(`Preflight query failed: ${result.reason || `exit ${result.exitCode}`}`);
+  return JSON.parse(result.stdout);
+}
+
+const describeRun = run => run ? {
+  id: run.id, at: run.timestamp, success: run.success === true, exitCode: run.exitCode ?? null,
+  failureKind: run.failureKind ?? null,
+  ...(run.billingMode ? { billingMode: run.billingMode } : {}),
+  ...(run.tools?.length ? { tools: run.tools } : {}),
+} : null;
+
+function latestRuns(receipts) {
+  const runs = new Map();
+  for (const row of receipts) {
+    const time = Date.parse(row.timestamp);
+    if (row.node !== 'local' || !Number.isFinite(time)) continue;
+    const state = runs.get(row.harness) || {};
+    if (!state.attempt || time >= Date.parse(state.attempt.timestamp)) state.attempt = row;
+    if (row.success === true && row.exitCode === 0 && (!state.completed || time >= Date.parse(state.completed.timestamp))) state.completed = row;
+    runs.set(row.harness, state);
+  }
+  return runs;
+}
+
+/** This query never launches an agent or treats a synthetic hook test as live activity. */
+export async function inspectLocalAdoption({ inspect = inspectAgents, receipts = readReceipts, preflight = readPreflight } = {}) {
+  const [inventory, history, gates, mode] = await Promise.allSettled([
+    inspect(), receipts(), preflight(['report']), preflight(['mode', '--router']),
+  ]);
+  const issues = [];
+  const inventoryRows = Array.isArray(inventory.value?.agents) ? inventory.value.agents : null;
+  const receiptRows = Array.isArray(history.value) ? history.value : null;
+  const adapterRows = Array.isArray(gates.value?.adapters) ? gates.value.adapters : null;
+  const decisions = gates.value?.compliance?.byHarness;
+  const routerMode = mode.value?.router?.mode;
+  if (!inventoryRows) issues.push('Agent inventory unavailable');
+  if (!receiptRows) issues.push('Managed run receipts unavailable');
+  if (!adapterRows || !decisions) issues.push('Native preflight evidence unavailable');
+  if (!['off', 'warn', 'enforce'].includes(routerMode)) issues.push('Native router policy unavailable');
+  const runs = latestRuns(receiptRows || []);
+  const adapters = new Map((adapterRows || []).map(row => [row.id, row.verification]));
+  const agents = (inventoryRows || []).map(({ id, name, installed, authenticated, version, blockedBy }) => {
+    const gate = adapters.get(id);
+    const decisionCount = decisions ? (Object.hasOwn(decisions, id) ? decisions[id]?.total ?? 0 : 0) : null;
+    const hookStatus = !adapterRows ? 'unknown' : !gate || gate.level === 'not wired' ? 'unsupported' : gate.installed ? 'configured' : 'missing';
+    const { attempt, completed } = runs.get(id) || {};
+    return {
+      id, name, installed, authenticated, version: version ?? null, ...(blockedBy ? { blockedBy } : {}),
+      nativeGate: { status: hookStatus, recentDecisions: decisionCount },
+      managedRun: { lastAttempt: describeRun(attempt), lastCompleted: describeRun(completed) },
+    };
+  });
+  const installed = agents.filter(agent => agent.installed);
+  const managedCompletions = installed.filter(agent => agent.managedRun.lastCompleted).length;
+  return {
+    ok: issues.length === 0, pluginVersion: version, routerMode: routerMode ?? null,
+    issues, agents,
+    summary: { installed: installed.length, managedCompletions, liveHookActivity: installed.filter(agent => agent.nativeGate.recentDecisions > 0).length },
+  };
+}
+
+export async function inspectFleetAdoption({ node, inventory = listTargets, readLocal = inspectLocalAdoption, execute = executeOnNode } = {}) {
+  const targets = await inventory();
+  const nodes = node ? targets.nodes.filter(row => row.id === node || row.name === node) : targets.nodes;
+  if (!nodes.length) throw new Error('Select a recorded node from meta-harness nodes');
+  const results = await Promise.all(nodes.map(async target => {
+    const row = { node: target.id, name: target.name };
+    if (!target.self && target.online === false) return { ...row, status: 'offline' };
+    if (!target.self && !target.accessConfigured) return { ...row, status: 'no-cli-access' };
+    try {
+      let report;
+      if (target.self) report = await readLocal();
+      else {
+        const result = await execute(target.id, {
+          operation: 'direct', useHome: true, timeoutMs: 40000,
+          argv: ['total-recall', 'meta-harness', 'adoption', '--json'],
+        });
+        try { report = JSON.parse(result.output); } catch { /* The installed CLI did not supply an adoption report. */ }
+        if (report?.error === 'Unknown operation: adoption') return { ...row, status: 'update-required', error: 'The installed Meta Harness does not support adoption reports.' };
+        if (!report || !Array.isArray(report.agents) || typeof report.pluginVersion !== 'string' || typeof report.ok !== 'boolean' || (report.ok && !result.ok)) {
+          return { ...row, status: 'adoption-unavailable', error: 'The installed Meta Harness did not return an adoption report. Verify its version and CLI availability.' };
+        }
+      }
+      return { ...row, status: report.ok ? 'inspected' : 'partial', report };
+    } catch (error) {
+      return { ...row, status: 'probe-failed', error: String(error?.message || error).slice(0, 400) };
+    }
+  }));
+  return { ok: !targets.meshError && results.every(row => row.status === 'inspected'), ...(targets.meshError ? { meshError: targets.meshError } : {}), nodes: results };
+}

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

@@ -11,6 +11,7 @@ import { routeTask } from './router.mjs';
 import { runQualityGate } from './gate.mjs';
 import { isGitRepo, createWorktree, removeWorktree, commitAll, linkDependencies, deleteBranch } from './worktree.mjs';
 import { forwardRemoteOperation } from './remote-operation.mjs';
+import { queueIncludedJob } from './usage-queue.mjs';
 
 export async function executeRoutedTask(task, options = {}) {
   const remote = await forwardRemoteOperation('route', task, { ...options, execute: true });
@@ -19,6 +20,13 @@ export async function executeRoutedTask(task, options = {}) {
   const cwd = options.cwd || process.cwd();
   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 };
+  if (!route.selected && route.deferred) {
+    const blocked = { ok: false, failureKind: 'quota', error: 'The included usage allowance is exhausted.', resetsAt: route.deferred.resetsAt };
+    const job = await queueIncludedJob({ agent: route.deferred.harness, cwd, prompt: task }, blocked,
+      { role: 'Routed', replay, launchPrevented: true });
+    return { ...blocked, route, attempts: [], queued: true, queueId: job.id };
+  }
   if (!route.selected) return { ok: false, route, attempts: [], error: 'No harness can take this task right now.' };
   const node = localExecutionNode(options, route.placement);
   const pool = options.pool || (await resolvePool(options)).ready.map(h => h.id);
@@ -35,9 +43,10 @@ export async function executeRoutedTask(task, options = {}) {
     const directory = createWorktree(cwd, { branch });
     const attempt = { harness, branch: null, commit: null, gate: null, escalatedFrom: previous };
     attempts.push(attempt);
+    let stopped;
     try {
       const prompt = `Work only in this checkout. Do not commit; the harness commits your changes.\nTask:\n${task}${diagnostic ? `\n\nA previous attempt by ${previous} failed. Diagnostic:\n${diagnostic}` : ''}`;
-      const result = await dispatchWithReceipt({ agent: harness, node, cwd: directory, contextCwd: cwd, contextTask: task, prompt, permissions: { read: true, write: true }, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Routed', complexityScore: route.complexity?.score, escalatedFrom: previous });
+      const result = await dispatchWithReceipt({ agent: harness, node, cwd: directory, contextCwd: cwd, contextTask: task, prompt, permissions: { read: true, write: true }, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Routed', complexityScore: route.complexity?.score, escalatedFrom: previous, replay, retryId: options.retryId });
       attempt.ok = result.ok === true;
       attempt.durationMs = result.durationMs;
       attempt.output = result.response || null;
@@ -51,6 +60,7 @@ export async function executeRoutedTask(task, options = {}) {
       } else {
         attempt.error = result.error;
         attempt.failureKind = result.failureKind;
+        if (result.queued || result.queueError || (result.failureKind === 'quota' && options.retryId) || result.failureKind === 'billing-policy') stopped = result;
       }
       if (attempt.ok && options.gate) {
         linkDependencies(cwd, directory);
@@ -74,6 +84,7 @@ export async function executeRoutedTask(task, options = {}) {
     }
 
     if (attempt.ok) return { ok: true, route, gateApplied: Boolean(options.gate), branch: attempt.branch, commit: attempt.commit, harness, attempts, alerts };
+    if (stopped) return { ...stopped, route, attempts, alerts };
 
     const remaining = pool.filter(item => !tried.has(item));
     const next = remaining.length ? evaluateGateCascade(harness, { testsPassed: false }, remaining) : null;

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

@@ -8,6 +8,7 @@ import { recordRunReceipt } from './learner.mjs';
 import { classifyTaskComplexity, synthesizeOneWayValve } from '../capability/index.mjs';
 import { notifyAlert } from './alerts.mjs';
 import { dispatchWithReceipt } from './dispatch.mjs';
+import { queueIncludedJob } from './usage-queue.mjs';
 import { resolvePool, localExecutionNode } from './pool.mjs';
 import { createThread, appendThreadTurn, updateThread } from './threads.mjs';
 import { executeCodeReview } from './review.mjs';
@@ -101,9 +102,10 @@ async function runPipeline(task, poolInfo, options) {
   const run = async (stage, harness, prompt, { workdir = cwd, permissions, role = stage.role } = {}) => {
     stage.status = 'running';
     const result = await dispatchWithReceipt({ agent: harness.id, node: 'local', cwd: workdir, contextCwd: cwd, contextTask: task, prompt, permissions: permissions || stage.permissions, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role, complexityScore: complexity.score });
-    stage.status = result.ok ? 'completed' : 'failed';
+    stage.status = result.ok ? 'completed' : result.queued ? 'queued' : 'failed';
     stage.output = result.response || result.error || null;
     stage.failureKind = result.ok ? undefined : result.failureKind;
+    if (result.queueId) stage.queueId = result.queueId;
     appendThreadTurn(thread.id, { role: role.toLowerCase(), agent: harness.id, content: stage.output || '' });
     return result;
   };
@@ -186,7 +188,8 @@ async function runCouncil(task, poolInfo, options) {
   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, 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, ...(result.ok ? parseVote(result.response) : { vote: 'ABSTAIN', reason: null, error: result.error }), feedback: result.response || null };
+    return { harness, ok: result.ok === true, ...(result.ok ? parseVote(result.response) : { vote: 'ABSTAIN', reason: null, error: result.error }),
+      ...(result.queueId ? { queueId: result.queueId } : {}), feedback: result.response || null };
   }));
   const count = vote => votes.filter(item => item.vote === vote).length;
   const majority = votes.length / 2;
@@ -214,7 +217,8 @@ async function runRace(task, poolInfo, options) {
       if (commit && options.gate) linkDependencies(cwd, directory);
       const gate = commit ? await (options.gateFn || runQualityGate)(directory, options.gateOptions) : null;
       keep = Boolean(commit) && gate?.passed === true;
-      return { harness, branch: keep ? branch : null, commit: keep ? commit : null, ok: keep, gate, completedAt: Date.now(), durationMs: Date.now() - started, error: result.ok ? (commit ? (keep ? undefined : 'The quality gate failed') : 'No files changed') : result.error };
+      return { harness, branch: keep ? branch : null, commit: keep ? commit : null, ok: keep, gate, completedAt: Date.now(), durationMs: Date.now() - started, error: result.ok ? (commit ? (keep ? undefined : 'The quality gate failed') : 'No files changed') : result.error,
+        ...(result.queueId ? { queueId: result.queueId } : {}) };
     } catch (error) {
       return { harness, branch: null, commit: null, ok: false, gate: null, durationMs: null, error: String(error.message) };
     } finally {
@@ -235,6 +239,14 @@ export async function coordinateTask(taskDescription, options = {}) {
   if (!['pipeline', 'orchestrate', 'council', 'race'].includes(mode)) throw new Error(`Unsupported coordination mode: ${mode}`);
   localExecutionNode(options);
   const poolInfo = await resolvePool(options);
+  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) {
+    const blocked = { ok: false, failureKind: 'quota', error: 'Coordination is waiting for included usage.', resetsAt: wall.resetsAt };
+    const job = await queueIncludedJob({ agent: wall.harness, cwd: options.cwd || process.cwd(), prompt: task }, blocked,
+      { role: 'Coordinate', launchPrevented: true });
+    return { ...blocked, mode, executedLive: false, queued: true, queueId: job.id, needsReview: job.needsReview };
+  }
   if (mode === 'council') return runCouncil(task, poolInfo, options);
   if (mode === 'race') return runRace(task, poolInfo, options);
   return runPipeline(task, poolInfo, options);

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

@@ -0,0 +1,38 @@
+import path from 'node:path';
+
+const DEFAULT_PERMISSIONS = Object.freeze({ read: true, write: false, send: false, destructive: false });
+export { DEFAULT_PERMISSIONS };
+
+export function commandPermissions(value = DEFAULT_PERMISSIONS) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Command permissions must be boolean values');
+  for (const key of Object.keys(value)) {
+    if (!Object.hasOwn(DEFAULT_PERMISSIONS, key) || typeof value[key] !== 'boolean') throw new Error(`Invalid permission ${key}`);
+  }
+  return { ...DEFAULT_PERMISSIONS, ...value };
+}
+
+const PUBLIC_FIELDS = [
+  'agent', 'cwd', 'prompt', 'permissions', 'node', 'allowUnknownAuth', 'timeoutMs',
+  'model', 'tools', 'settingSources', 'allowedTools',
+];
+
+export function validateDispatchRequest(request) {
+  if (!request || typeof request !== 'object' || Array.isArray(request)) throw new Error('Dispatch requires a JSON object');
+  if (Object.keys(request).some(key => !PUBLIC_FIELDS.includes(key))) throw new Error('Unsupported dispatch field; workspace context and containment are managed by Meta Harness');
+  if (typeof request.agent !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(request.agent) ||
+      typeof request.cwd !== 'string' || !path.isAbsolute(request.cwd) || request.cwd.includes('\0') ||
+      typeof request.prompt !== 'string' || !request.prompt.trim() || Buffer.byteLength(request.prompt) > 65536) {
+    throw new Error('Dispatch requires an explicit agent, absolute workspace, and bounded nonempty prompt');
+  }
+  if (request.node !== undefined && (typeof request.node !== 'string' || !request.node.trim() || /[\0\r\n]/.test(request.node))) throw new Error('Invalid dispatch node');
+  if (request.allowUnknownAuth !== undefined && typeof request.allowUnknownAuth !== 'boolean') throw new Error('allowUnknownAuth must be a boolean');
+  const timeoutMs = request.timeoutMs === undefined ? 300000 : request.timeoutMs;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 540000) throw new Error('Foreground dispatch timeout must be 1..540000 ms');
+  return { ...request, permissions: commandPermissions(request.permissions), timeoutMs };
+}
+
+/** The installed destination starts from its own project context and decides containment itself. */
+export function destinationDispatchRequest(request) {
+  const fields = PUBLIC_FIELDS.filter(key => key !== 'node' && request[key] !== undefined);
+  return validateDispatchRequest(Object.fromEntries(fields.map(key => [key, request[key]])));
+}

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

@@ -1,22 +1,37 @@
 /** One path for every agent run: contain it if needed, dispatch it, classify the outcome, write its receipt. */
 import { executeOnNode } from './executor.mjs';
-import { classifyFailure, READ_ONLY_ADAPTERS } from './worker.mjs';
+import { classifyFailure, INCLUDED_BILLING, READ_ONLY_ADAPTERS } from './worker.mjs';
 import { recordRunReceipt } from './learner.mjs';
 import { isGitRepo, createWorktree, removeWorktree } from './worktree.mjs';
+import { includedAdmission, openRouterAdmission, readIncludedPolicy } from './included-usage.mjs';
+import { queueIncludedJob } from './usage-queue.mjs';
 
-export async function dispatchWithReceipt(request, { dispatchFn, node = request.node || 'local', role, complexityScore, escalatedFrom, record = recordRunReceipt } = {}) {
+export async function dispatchWithReceipt(request, { dispatchFn, node = request.node || 'local', role, complexityScore, escalatedFrom,
+  record = recordRunReceipt, replay, retryId, usagePolicy = readIncludedPolicy, admit = includedAdmission, admitOpenRouter = openRouterAdmission } = {}) {
   const started = Date.now();
   // 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);
-  let scratch = null, result;
+  let scratch = null, result, billingMode = null, launchPrevented = false;
   try {
     let effective = request;
-    if (contain) {
-      scratch = createWorktree(request.cwd, { prefix: 'meta-harness-readonly-' });
-      effective = { ...request, cwd: scratch, contextCwd: request.contextCwd || request.cwd, isolated: true };
+    const policy = await usagePolicy();
+    if (policy.enabled && node === 'local') {
+      const openRouter = Object.hasOwn(policy.openRouter ?? {}, request.agent);
+      billingMode = openRouter ? 'openrouter' : 'included';
+      const admission = openRouter ? await admitOpenRouter(request.agent, policy) : await admit(request.agent, request.cwd, policy);
+      if (!admission.ok) {
+        result = { ...admission, agent: request.agent, exitCode: null };
+        launchPrevented = true;
+      } else effective = { ...request, [INCLUDED_BILLING]: { key: admission.key, claudePlan: admission.claudePlan, openRouter: admission.openRouter } };
+    }
+    if (!result) {
+      if (contain) {
+        scratch = createWorktree(request.cwd, { prefix: 'meta-harness-readonly-' });
+        effective = { ...effective, cwd: scratch, contextCwd: request.contextCwd || request.cwd, isolated: true };
+      }
+      result = dispatchFn ? await dispatchFn(effective) : await executeOnNode(node, { ...effective, operation: 'dispatch' });
+      if (contain) result = { ...result, readOnly: 'disposable-checkout' };
     }
-    result = dispatchFn ? await dispatchFn(effective) : await executeOnNode(node, { ...effective, operation: 'dispatch' });
-    if (contain) result = { ...result, readOnly: 'disposable-checkout' };
   } catch (error) {
     const message = String(error?.message || error);
     result = { ok: false, error: message, agent: request.agent, ...(error?.code === 'NOT_READY' ? { failureKind: 'not-ready' } : classifyFailure(message)) };
@@ -24,15 +39,31 @@ export async function dispatchWithReceipt(request, { dispatchFn, node = request.
     if (scratch) removeWorktree(request.cwd, scratch);
   }
   const durationMs = Date.now() - started;
+  if (result.execution?.receiptOwner === 'destination' && result.receiptId) return { ...result, durationMs };
+  if (result.execution?.remote && (result.queued || result.launchPrevented)) return { ...result, durationMs };
+  if (billingMode === 'included' && result.failureKind === 'quota') {
+    if (retryId) result = { ...result, needsReview: !launchPrevented && request.permissions?.write === true };
+    else {
+      try {
+        const job = await queueIncludedJob(request, result, { role, replay, launchPrevented });
+        result = { ...result, queued: true, queueId: job.id, needsReview: job.needsReview };
+      } catch (error) {
+        result = { ...result, queueError: error.message };
+      }
+    }
+  }
+  if (launchPrevented) return { ...result, launchPrevented, durationMs };
   // A finished run keeps its result: the worktree and any cost are real even when bookkeeping fails.
-  let receiptError;
+  let receipt, receiptError;
   try {
-    await record({
+    receipt = await record({
     harness: request.agent, role, node, task: request.contextTask || request.prompt, complexityScore,
+      billingMode,
     model: result.model ?? null, exitCode: result.exitCode ?? null, finishedReason: result.finishedReason ?? null,
+      tools: result.toolResults,
     success: result.ok === true, durationMs, failureKind: result.ok ? null : result.failureKind || 'agent',
     error: result.ok ? null : result.error, resetsAt: result.resetsAt, escalatedFrom,
     });
   } catch (error) { receiptError = String(error?.message || error); }
-  return { ...result, durationMs, ...(receiptError ? { receiptError } : {}) };
+  return { ...result, durationMs, ...(billingMode ? { billingMode } : {}), ...(receipt?.id ? { receiptId: receipt.id } : {}), ...(receiptError ? { receiptError } : {}) };
 }