total-recall-brain 3.43.3 → 3.44.0

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

@@ -0,0 +1,249 @@
+/** Admission for the operator's included-usage policy. No provider generation happens here. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+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';
+
+export const INCLUDED_AGENTS = ['claude', 'codex'];
+const VERSION = 1;
+const DEFAULT = { version: VERSION, enabled: false, claude: null };
+const sha256 = key => createHash('sha256').update(key).digest('hex');
+const validKeyName = name => typeof name === 'string' && /^[A-Z][A-Z0-9_]{1,100}$/.test(name);
+const validModel = model => typeof model === 'string' && /^[\w.-]+\/[\w./:-]+$/.test(model) && model.length <= 180;
+const validOpenRouterBinding = (agent, binding) => OPENROUTER_AGENTS.includes(agent) &&
+  validKeyName(binding?.keyName) && validModel(binding?.model);
+
+async function policyStore() {
+  const { PluginStateStore } = await import('./ssss-store.mjs');
+  return new PluginStateStore(path.join(configDir(), 'included-usage.json'), 'meta-harness');
+}
+
+export async function readIncludedPolicy(store) {
+  store ??= await policyStore();
+  const state = store.read(DEFAULT);
+  if (state?.version !== VERSION || typeof state.enabled !== 'boolean' ||
+      (state.claude !== null && (!/^[a-f0-9]{64}$/.test(state.claude?.fingerprint || '') ||
+        typeof state.claude.keyName !== 'string' || typeof state.claude.organization !== 'string' ||
+        !Number.isFinite(Date.parse(state.claude.expiresAt)))) ||
+      (state.claudePlan !== undefined && (!/^[\w-]{1,100}$/.test(state.claudePlan?.organization || '') ||
+        state.claudePlan.usageCreditsEnabled !== false || !Number.isFinite(Date.parse(state.claudePlan.verifiedAt)))) ||
+      (state.openRouter !== undefined && (!state.openRouter || typeof state.openRouter !== 'object' ||
+        Array.isArray(state.openRouter) || !Object.entries(state.openRouter).every(([agent, binding]) => validOpenRouterBinding(agent, binding))))) {
+    throw new Error('Included usage policy is invalid; dispatch stopped.');
+  }
+  return state;
+}
+
+function requireOperator() {
+  if (process.env.TR_META_HARNESS_RUN) throw new Error('Only the operator may change the included usage policy.');
+}
+
+export async function enforceIncludedUsage() {
+  requireOperator();
+  const store = await policyStore();
+  const state = await readIncludedPolicy(store);
+  if (!state.enabled) store.write({ ...state, enabled: true });
+  return includedUsageStatus();
+}
+
+async function authRuntime() {
+  const root = process.env.TR_PACKAGE_ROOT;
+  if (!root || !path.isAbsolute(root) ||
+      JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name !== 'total-recall-brain') {
+    throw new Error('Verified Total Recall Auth runtime required.');
+  }
+  const { loadPluginModule } = await import(pathToFileURL(path.join(root, 'src/core/plugin-runtime.mjs')).href);
+  const { hostSecretsBrainDir } = await loadPluginModule('auth', 'host-secrets-store', { activeRequired: true });
+  return { brain: hostSecretsBrainDir(), load: module => loadPluginModule('auth', module, { activeRequired: true }) };
+}
+
+async function authValue(keyName) {
+  const { brain, load } = await authRuntime();
+  const { getSecret } = await load('secrets-store');
+  const result = await getSecret(brain, keyName, { action: 'use', actor: 'meta-harness' });
+  return result.found && typeof result.value === 'string' ? result.value : '';
+}
+
+async function authKey(keyName) {
+  const value = await authValue(keyName);
+  if (!/^sk-ant-api[0-9]+-[\w-]+$/.test(value)) {
+    throw new Error('The selected Anthropic API key is missing or invalid in Total Recall Auth.');
+  }
+  return value;
+}
+
+async function verifyOpenRouterKey(keyName) {
+  const { brain, load } = await authRuntime();
+  const { syncSecretAccount } = await load('provider-account-sync');
+  const result = await syncSecretAccount(brain, keyName);
+  return result.provider === 'openrouter' && result.key_valid === true && result.tracking_status === 'ok';
+}
+
+/** OpenRouter opt-in is per harness and per destination, with no subscription fallback. */
+export async function bindOpenRouter(agent, keyName, model, { verify = verifyOpenRouterKey } = {}) {
+  requireOperator();
+  const binding = { keyName, model };
+  if (!validOpenRouterBinding(agent, binding)) throw new Error('Select a supported OpenRouter harness, an Auth key name and a catalog model ID.');
+  if (!(await verify(keyName))) throw new Error('Total Recall Auth could not verify this OpenRouter key.');
+  const store = await policyStore();
+  const state = await readIncludedPolicy(store);
+  store.write({ ...state, enabled: true, openRouter: { ...state.openRouter, [agent]: binding } });
+  return { ok: true, agent, ...binding };
+}
+
+export async function openRouterAdmission(agent, policy, { readKey = authValue } = {}) {
+  const binding = policy.openRouter?.[agent];
+  if (!validOpenRouterBinding(agent, binding)) return { ok: false, failureKind: 'billing-policy', error: 'No approved OpenRouter binding for this harness.' };
+  const key = await readKey(binding.keyName);
+  if (!/^sk-or-v1-[\w-]+$/.test(key)) return { ok: false, failureKind: 'auth', error: 'The approved OpenRouter key is unavailable in Total Recall Auth.' };
+  return { ok: true, openRouter: { key, keyName: binding.keyName, model: binding.model } };
+}
+
+/** Bind the operator's Console observation to the actual secret without recording its value or hint. */
+export async function bindClaudeIncludedKey(evidence, { readKey = authKey, now = Date.now() } = {}) {
+  requireOperator();
+  const { keyName, organization, keyHint, expiresAt, creditSource, autoReload, paymentMethod, invoiced, paidBalanceCents } = evidence || {};
+  const expiry = Date.parse(expiresAt);
+  const hint = typeof keyHint === 'string' && /^(sk-ant-api[0-9]+-[\w-]{2,20})(?:\.{3}|…)([\w-]{4,12})$/.exec(keyHint);
+  if (!/^[A-Z][A-Z0-9_]{1,100}$/.test(keyName || '') || !/^[\w-]{1,100}$/.test(organization || '') ||
+      !hint || !Number.isFinite(expiry) || expiry <= now || expiry > now + 35 * 86400000 ||
+      creditSource !== 'claude-max' || autoReload !== false || paymentMethod !== false || invoiced !== false || paidBalanceCents !== 0) {
+    throw new Error('Binding requires verified Max credit expiry, Console key hint, and a prepaid organization with no paid balance, auto-reload, or payment method.');
+  }
+  const key = await readKey(keyName);
+  if (!key.startsWith(hint[1]) || !key.endsWith(hint[2])) throw new Error('The Console key hint does not match the selected Total Recall Auth key.');
+  const store = await policyStore();
+  const state = await readIncludedPolicy(store);
+  store.write({ ...state, enabled: true, claude: { keyName, organization, expiresAt: new Date(expiry).toISOString(),
+    verifiedAt: new Date(now).toISOString(), fingerprint: sha256(key) } });
+  return includedUsageStatus();
+}
+
+export const claudeProofCurrent = (policy, now = Date.now()) => Date.parse(policy.claude?.expiresAt) > now;
+
+/** Bind the observed account setting to this host's native Claude Max login. */
+export async function bindClaudeMaxPlan(evidence, { readOrganization = readClaudeMaxOrganization } = {}) {
+  requireOperator();
+  const { organization, usageCreditsEnabled } = evidence || {};
+  if (!/^[\w-]{1,100}$/.test(organization || '') || usageCreditsEnabled !== false) {
+    throw new Error('Confirm Usage credits are off in the signed-in Max account before binding it.');
+  }
+  if (organization !== await readOrganization(process.cwd())) {
+    throw new Error('The native Claude Max login does not match the verified organization.');
+  }
+  const store = await policyStore();
+  const state = await readIncludedPolicy(store);
+  store.write({ ...state, enabled: true, claudePlan: { organization, usageCreditsEnabled, verifiedAt: new Date().toISOString() } });
+  return includedUsageStatus();
+}
+
+export async function includedUsageStatus({ probe = false } = {}) {
+  const policy = await readIncludedPolicy();
+  const claude = policy.claude ? { organization: policy.claude.organization, verifiedAt: policy.claude.verifiedAt,
+    expiresAt: policy.claude.expiresAt, current: claudeProofCurrent(policy) } : null;
+  return { ok: true, policyVersion: VERSION, enabled: policy.enabled, claude, claudePlan: policy.claudePlan ?? null,
+    openRouter: policy.openRouter ?? {},
+    ...(probe ? { codex: await readCodexAllowance(process.cwd()) } : {}) };
+}
+
+/** Use only the documented account reads on stdio. No turn/start is sent. */
+export function queryCodexAccount(cwd, { env = process.env, timeoutMs = 10000 } = {}) {
+  const binary = findBinary('codex', env);
+  if (!binary) throw new Error('Codex CLI is unavailable.');
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, [...CODEX_PLAN_ARGS, 'app-server', '--listen', 'stdio://'], {
+      cwd, env: agentEnvironment(env), stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    let account, limits, size = 0, outcome;
+    const send = message => child.stdin.write(JSON.stringify(message) + '\n');
+    const fail = error => {
+      outcome ||= { error };
+      child.kill('SIGTERM');
+    };
+    const timer = setTimeout(() => { outcome ||= { error: 'Codex account read timed out.' }; child.kill('SIGKILL'); }, timeoutMs);
+    const closed = () => {
+      clearTimeout(timer);
+      lines.close();
+      if (outcome?.result) resolve(outcome.result);
+      else reject(new Error(outcome?.error || 'Codex account read ended without a complete result.'));
+    };
+    child.once('error', () => { outcome = { error: 'Could not start Codex account read.' }; });
+    child.once('close', closed);
+    child.stdin.on('error', () => fail('Codex account read input closed.'));
+    child.stdout.on('data', chunk => { size += chunk.length; if (size > 256 * 1024) fail('Codex account response exceeded its bound.'); });
+    lines.on('line', line => {
+      if (outcome) return;
+      let frame;
+      try { frame = JSON.parse(line); } catch { fail('Codex returned invalid account data.'); return; }
+      if (![1, 2, 3].includes(frame?.id)) return;
+      if (!frame.result || frame.error) { fail('Codex could not read the signed-in account or its limits.'); return; }
+      if (frame.id === 1) {
+        send({ method: 'initialized', params: {} });
+        send({ id: 2, method: 'account/read', params: { refreshToken: false } });
+        send({ id: 3, method: 'account/rateLimits/read' });
+      } else if (frame.id === 2) account = frame.result;
+      else limits = frame.result;
+      if (account && limits) {
+        outcome = { result: { account, limits } };
+        child.stdin.end();
+        child.kill('SIGTERM');
+      }
+    });
+    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'meta_harness', title: 'Meta Harness', version: '1' } } });
+  });
+}
+
+export function evaluateCodexAllowance({ account, limits }, now = Date.now()) {
+  const plan = account?.account?.planType;
+  if (account?.account?.type !== 'chatgpt' || !/^(plus|pro|prolite|go|free)(?:[_-]\w+)?$/i.test(plan || '')) {
+    return { ok: false, failureKind: 'auth', error: 'Codex requires a verified personal ChatGPT plan with included limits.' };
+  }
+  const rate = limits?.rateLimits;
+  const buckets = [rate, ...Object.values(limits?.rateLimitsByLimitId || {})].filter(Boolean);
+  const windows = [rate?.primary, rate?.secondary].filter(Boolean);
+  if (!windows.length || windows.some(window => typeof window.usedPercent !== 'number')) {
+    return { ok: false, plan, failureKind: 'billing-policy', error: 'Codex did not report current included usage.' };
+  }
+  const credits = buckets.map(bucket => bucket.credits).filter(Boolean);
+  if (!credits.length || credits.some(c => c.hasCredits !== false || c.unlimited !== false ||
+      (c.balance != null && !/^0(?:\.0+)?$/.test(String(c.balance))))) {
+    return { ok: false, plan, failureKind: 'billing-policy', error: 'Codex did not confirm that paid credits are unavailable.' };
+  }
+  const full = windows.filter(window => window.usedPercent >= 100);
+  if (full.length) {
+    const resets = full.map(window => window.resetsAt * 1000);
+    return { ok: false, plan, failureKind: 'quota', error: 'Codex has reached an included usage limit.',
+      resetsAt: resets.every(reset => Number.isFinite(reset) && reset > now) ? new Date(Math.max(...resets)).toISOString() : null };
+  }
+  return { ok: true, plan, usagePercent: Math.max(...windows.map(window => window.usedPercent)) };
+}
+
+export async function readCodexAllowance(cwd, { query = queryCodexAccount } = {}) {
+  try { return evaluateCodexAllowance(await query(cwd)); }
+  catch (error) { return { ok: false, failureKind: 'billing-policy', error: error.message }; }
+}
+
+export async function includedAdmission(agent, cwd, policy, { readKey = authKey, codex = readCodexAllowance,
+  receipts = readReceipts } = {}) {
+  if (!INCLUDED_AGENTS.includes(agent)) return { ok: false, failureKind: 'billing-policy', error: 'This harness is outside the included usage policy.' };
+  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];
+  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 };
+  try {
+    const key = await readKey(policy.claude.keyName);
+    if (sha256(key) !== policy.claude.fingerprint) throw new Error('The Claude key changed; verify the new key against the Max grant.');
+    return { ok: true, key };
+  } catch (error) {
+    return { ok: false, failureKind: 'auth', error: error.message };
+  }
+}

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

@@ -49,6 +49,9 @@ export async function recordRunReceipt(receipt = {}) {
     success: receipt.success === true,
     durationMs: receipt.durationMs || 0,
     failureKind: receipt.failureKind || null,
+    ...(receipt.billingMode ? { billingMode: receipt.billingMode } : {}),
+    ...(Array.isArray(receipt.tools) && receipt.tools.length ? { tools: receipt.tools.map(({ tool, status, exitCode }) =>
+      ({ tool, status, ...(Number.isInteger(exitCode) ? { exitCode } : {}) })) } : {}),
     error: receipt.error ? String(receipt.error).slice(0, 500) : null,
     resetsAt: receipt.resetsAt || null,
     gate: receipt.gate || null,

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

@@ -3,6 +3,7 @@ import { ADAPTER_CATALOG } from '../capability/index.mjs';
 import { inspectAgents, getActiveAdapters } from './worker.mjs';
 import { readReceipts, activeQuotaWalls, activeCredentialBlocks } from './learner.mjs';
 import { measuredWalls } from './telemetry.mjs';
+import { claudeProofCurrent, INCLUDED_AGENTS, readIncludedPolicy } from './included-usage.mjs';
 import os from 'node:os';
 
 const describe = (id, extra = {}) => {
@@ -23,16 +24,23 @@ export function exclusionReason(agent, wall, credentialBlock, { allowUnknownAuth
 }
 
 /** An explicit list is the caller's decision and is not filtered. */
-export async function resolvePool({ availableHarnesses, inspect = inspectAgents, receipts = readReceipts, allowUnknownAuth = false } = {}) {
-  if (Array.isArray(availableHarnesses) && availableHarnesses.length) return { ready: availableHarnesses.map(id => describe(id)), excluded: [], walls: {} };
-  const [{ agents = [] }, entries] = await Promise.all([inspect({ env: process.env }), receipts()]);
-  const walls = { ...activeQuotaWalls(entries), ...measuredWalls() };
-  const blocks = activeCredentialBlocks(entries);
+export async function resolvePool({ availableHarnesses, inspect = inspectAgents, receipts = readReceipts, allowUnknownAuth = false, policy } = {}) {
+  policy ??= await readIncludedPolicy();
+  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 walls = { ...activeQuotaWalls(billingEntries), ...(!policy.enabled ? measuredWalls() : {}) };
+  const blocks = activeCredentialBlocks(billingEntries);
   const ready = [], excluded = [];
-  for (const agent of agents) {
-    const reason = exclusionReason(agent, walls[agent.id], blocks[agent.id], { allowUnknownAuth });
+  for (const installed of agents) {
+    const agent = policy.enabled && installed.id === 'claude' && !claudePlan ? { ...installed, authenticated: claudeProofCurrent(policy) } : installed;
+    const policyBlocked = policy.enabled && (!INCLUDED_AGENTS.includes(agent.id) || (Array.isArray(availableHarnesses) && !availableHarnesses.includes(agent.id)));
+    const reason = policyBlocked ? 'outside the included usage route' : exclusionReason(agent, walls[agent.id], blocks[agent.id], { allowUnknownAuth: !policy.enabled && allowUnknownAuth });
     if (!reason) ready.push(describe(agent.id, { authVerified: agent.authenticated === true }));
-    else if (agent.installed) excluded.push({ harness: agent.id, reason });
+    else if (agent.installed) excluded.push({ harness: agent.id, reason,
+      ...(policy.enabled && !policyBlocked && agent.authenticated === true && agent.versionVerified && !agent.blockedBy && walls[agent.id]
+        ? { failureKind: 'quota', resetsAt: walls[agent.id].resetReported ? walls[agent.id].until : null } : {}) });
   }
   return { ready, excluded, walls };
 }

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

@@ -170,6 +170,7 @@ export async function executeProcessTask(job, dependencies = {}) {
     if (branch && !commit) { (dependencies.deleteBranch || deleteBranch)(job.cwd, branch); branch = null; }
   } catch (error) { result = { ...result, ok: false, error: `${result.error ? result.error + '; ' : ''}Isolation cleanup failed: ${error.message}` }; }
   return updateAgentRecord(job.id, { status: result.ok ? 'completed' : 'failed', exitCode: result.exitCode ?? (result.ok ? 0 : 1), error: result.ok ? null : result.error,
+    ...(result.queueId ? { queueId: result.queueId } : {}),
     result: result.response || null, branch, commit, worktreePath: worktree, endedAt: new Date().toISOString() });
 }
 

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

@@ -81,6 +81,11 @@ export async function callLocalRuntime(prompt, system, config, dependencies = {}
       model: agent.model || undefined, write: false, role: 'Reasoning', allowUnknownAuth: config.allowUnknownAuth === true,
     });
     if (result.ok === true || result.success === true) return result.response || '';
+    if (result.queued || result.queueError || result.failureKind === 'billing-policy') {
+      const error = new Error(result.queued ? `Included usage exhausted. Queued as ${result.queueId}.` : result.queueError || result.error);
+      error.queueId = result.queueId;
+      throw error;
+    }
     failures.push(`${agent.name}: ${result.error || 'dispatch failed'}`);
   }
   throw new Error(`All CLI agents failed (${failures.join('; ')})`);

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

@@ -60,7 +60,7 @@ export async function forwardRemoteOperation(operation, task, options = {}) {
       error: transport.error || 'Remote operation returned no valid structured result' };
   }
   const result = { ...payload, ok: transport.ok === true && payload.ok === true, execution, transportExitCode: transport.exitCode ?? null,
-    ...(!transport.ok ? { failureKind: 'transport' } : {}) };
+    ...(!transport.ok && !payload.failureKind ? { failureKind: 'transport' } : {}) };
   if (!result.ok && !result.error) result.error = transport.error || `Remote ${operation} failed`;
   if (result.ok && payload.branch) result.deliverable = { node: options.node, workspace: options.cwd, branch: payload.branch, commit: payload.commit ?? null };
   const threadId = payload.threadId || options.threadId;

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

@@ -21,6 +21,7 @@ import { getModelCatalog, joinHarnessModels } from './model-catalog.mjs';
 import { readReceipts, activeQuotaWalls, activeCredentialBlocks } 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';
 
 /**
@@ -97,7 +98,7 @@ async function cachedMeteredQuota(options) {
 async function readMeteredQuota(options) {
   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', 'DEVELOPER_OPENROUTER_API_KEY']) || runHostCli(['auth', 'secret', 'get', 'OPENROUTER_API_KEY']));
+    const key = options.openRouterKey !== undefined ? options.openRouterKey : 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}`);
@@ -139,6 +140,7 @@ async function readMeteredQuota(options) {
  * Never fabricates or hardcodes synthetic subscription percentages.
  */
 export async function inspectQuotas(options = {}) {
+  const policy = options.policy || await readIncludedPolicy();
   const quotas = {};
   const remote = options.node && options.node !== 'local';
   const fleet = (options.fleet || fleetTelemetry)();
@@ -162,27 +164,37 @@ export async function inspectQuotas(options = {}) {
   }
 
   // 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 claudePlan = policy.enabled ? policy.claudePlan?.organization : undefined;
+  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 walls = remote ? {} : { ...activeQuotaWalls(await readReceipts()), ...measuredWalls(codexLimits) };
+  const receipts = remote ? [] : (await readReceipts()).filter(run => !policy.enabled || run.billingMode === 'included');
+  const walls = remote ? {} : { ...activeQuotaWalls(receipts), ...(!policy.enabled ? measuredWalls(codexLimits) : {}) };
   const metered = METERED_HARNESSES;
 
-  const blocks = remote ? {} : activeCredentialBlocks(await readReceipts());
-  for (const agent of inspected.agents || []) {
+  const blocks = activeCredentialBlocks(receipts);
+  for (const installed of inspected.agents || []) {
+    const agent = policy.enabled && !remote && installed.id === 'claude' && !claudePlan ?
+      { ...installed, authenticated: claudeProofCurrent(policy) } : installed;
     const wall = walls[agent.id];
     const block = blocks[agent.id];
-    const reason = exclusionReason(agent, wall, block);
+    const policyBlocked = policy.enabled && !INCLUDED_AGENTS.includes(agent.id);
+    const explicitOpenRouter = !remote && Boolean(policy.openRouter?.[agent.id]);
+    const reason = policyBlocked ? (explicitOpenRouter ? 'available through explicit OpenRouter dispatch' : 'outside the included usage route') : exclusionReason(agent, wall, block);
     let status = 'ready';
     if (!agent.installed) status = 'not_installed';
+    else if (policyBlocked) status = 'blocked';
     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',
+      billingModel: policy.enabled && !remote && !claudePlan && agent.id === 'claude' ? 'included-api-credits' :
+        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,
+      ...(explicitOpenRouter ? { explicitOpenRouter: true } : {}),
       ...(wall ? { resetsAt: wall.until, wallMessage: wall.message } : {}),
     };
     if (agent.id === 'codex' && codexLimits) {
@@ -196,7 +208,7 @@ export async function inspectQuotas(options = {}) {
     quotas[agent.id] = quota;
   }
 
-  const meteredQuota = options.skipMetered
+  const meteredQuota = options.skipMetered || policy.enabled
     ? { billingModel: 'metered', status: 'not-read', quotaNote: 'Not read: no metered harness is in this route pool' }
     : await cachedMeteredQuota(options);
   quotas.metered = meteredQuota;
@@ -241,9 +253,10 @@ export function placeLocalWork(fleet = {}) {
 }
 
 export async function routeTask(taskDescription, options = {}) {
+  const policy = await readIncludedPolicy();
   let complexity = classifyTaskComplexity(taskDescription, options);
   let classifier = { source: 'heuristic' };
-  if (options.jev) {
+  if (options.jev && !policy.enabled) {
     try {
       const decided = classifyWithDecision(taskDescription, options.decisionRun);
       complexity = { ...complexity, tier: decided.tier, isFrontierRecommended: decided.tier === 'frontier', isLocalRecommended: decided.tier === 'local' };
@@ -260,17 +273,19 @@ 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), readReceipts()]);
+  const [pool, receipts] = await Promise.all([resolvePool({ ...lean, policy }), readReceipts()]);
   const quotaReport = await inspectQuotas({
     ...lean,
+    policy,
     meteredTtlMs: METERED_TTL_MS,
-    skipMetered: lean.openRouterKey === undefined && !pool.ready.some(h => METERED_HARNESSES.has(h.id)),
+    skipMetered: policy.enabled || (lean.openRouterKey === undefined && !pool.ready.some(h => METERED_HARNESSES.has(h.id))),
     ...(remote || lean.fleet ? {} : { fleet: complexity.tier === 'local' ? cachedFleet : () => ({ ok: false, error: 'Not read: this route places no local work', nodes: [] }) }),
   });
   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 warnings = [];
+  if (policy.enabled && options.jev) warnings.push('Included usage policy uses the local task classifier.');
   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.`);
@@ -278,6 +293,7 @@ export async function routeTask(taskDescription, options = {}) {
   return {
     ok: Boolean(routing.selected), task: taskDescription, classifier, complexity,
     selected: routing.selected, tier: complexity.tier, 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.',
     quotaSnapshot: { selectedHarnessStatus: selectedQuota.status || null, selectedHarnessUsage: selectedQuota.usagePercent ?? null, freeMemGB: quotas.system.freeMemGB ?? null },

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

@@ -1,15 +1,37 @@
-/** One native runtime-management boundary for every installed agent. */
+/** Runtime observations and explicit maintenance. Agent work belongs to dispatch. */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { getActiveAdapters, findBinary, runProcess, agentEnvironment } from './worker.mjs';
 
+const DSH_OBSERVATIONS = ['status', 'sessions', 'tools', 'models', 'model', 'plugins', 'help'];
+const MAINTENANCE = new Map([
+  ['claude', [['auth', 'status']]],
+  ['codex', [['login', 'status']]],
+  ['cursor', [['status']]],
+  ['dsh', [...DSH_OBSERVATIONS.map(operation => [operation]), ['model', '--cache']]],
+  ['hermes', [['status'], ['status', '--full'], ['gateway', 'status'], ['skills', 'list'], ['plugins', 'list'], ['auth']]],
+  ['ollama', [['list'], ['ps']]],
+  ['openclaw', [['status'], ['health'], ['gateway', 'status'], ['plugins', 'list']]],
+]);
+
+export function validateRuntimeOperation(agent, args = []) {
+  if (typeof agent !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(agent)) throw new Error('Invalid agent adapter');
+  if (!Array.isArray(args) || args.length > 64 || args.some(arg => typeof arg !== 'string' || arg.length > 8192)) throw new Error('Invalid native runtime arguments');
+  if (args.some(arg => /(?:api[-_]?key|password|secret|access[-_]?token|refresh[-_]?token)/i.test(arg))) throw new Error('Credential values and mutations belong to the auth owner, never runtime argv');
+  const command = args.length ? args : [agent === 'dsh' ? 'status' : '--help'];
+  const supported = [['--help'], ['-h'], ['--version'], ...(MAINTENANCE.get(agent) || [])];
+  if (!supported.some(tuple => tuple.length === command.length && tuple.every((word, index) => word === command[index]))) {
+    throw new Error('Runtime accepts only supported maintenance commands. Use meta-harness dispatch or route --execute for agent work, or the owning plugin for service changes.');
+  }
+  return command;
+}
+
 export async function manageRuntime(agent, args = [], { env = process.env, probe = runProcess, cwd = process.cwd() } = {}) {
+  args = validateRuntimeOperation(agent, args);
   const adapter = getActiveAdapters().find(item => item.id === agent);
   if (!adapter) throw new Error('Unknown agent adapter');
-  if (!Array.isArray(args) || args.length > 64 || args.some(arg => typeof arg !== 'string' || arg.length > 8192)) throw new Error('Invalid native runtime arguments');
-  if (args.some(arg => /(?:api[-_]?key|password|secret|access[-_]?token|refresh[-_]?token)/i.test(arg))) throw new Error('Credential values and mutations belong to the auth owner, never runtime argv');
-  if (agent === 'dsh' && ['status','sessions','tools','models','model','plugins','help','--help','-h'].includes(args[0] || 'status')) {
+  if (agent === 'dsh' && DSH_OBSERVATIONS.includes(args[0])) {
     const { run } = await import('./adapters/dsh.mjs');
     const lines = [], errors = [], log = console.log, error = console.error;
     const previous = process.exitCode;
@@ -31,6 +53,6 @@ export async function manageRuntime(agent, args = [], { env = process.env, probe
   }
   const binary = findBinary(adapter.binary, env);
   if (!binary) throw new Error(`${adapter.name} is not installed on the selected node`);
-  const result = await probe(binary, args.length ? args : ['--help'], { cwd, timeoutMs:60000, env:agentEnvironment(env) });
-  return { ok:result.exitCode===0 && !result.reason, agent, exitCode:result.exitCode, output:result.stdout, error:result.reason || (result.exitCode ? result.stderr || 'Runtime command failed' : undefined) };
+  const result = await probe(binary, args, { cwd, timeoutMs:60000, env:agentEnvironment(env) });
+  return { ok:result.exitCode===0 && !result.reason, agent, exitCode:result.exitCode, output:result.stdout || (result.exitCode === 0 ? result.stderr : ''), error:result.reason || (result.exitCode ? result.stderr || 'Runtime command failed' : undefined) };
 }

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

@@ -0,0 +1,110 @@
+/** SSSS-backed queue for work deferred by included usage limits. */
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { configDir } from './paths.mjs';
+import { destinationDispatchRequest } from './dispatch-request.mjs';
+import { readIncludedPolicy } from './included-usage.mjs';
+
+async function queueStore() {
+  const { PluginStateStore } = await import('./ssss-store.mjs');
+  return new PluginStateStore(path.join(configDir(), 'usage-queue.json'), 'meta-harness');
+}
+
+function readRows(store) {
+  const jobs = store.read([]);
+  if (!Array.isArray(jobs) || jobs.some(job => !job?.id || typeof job.task !== 'string' || !path.isAbsolute(job.workspace || '') ||
+      !['waiting', 'running', 'completed', 'cancelled', 'failed'].includes(job.status))) {
+    throw new Error('Invalid included usage queue.');
+  }
+  return jobs;
+}
+
+async function mutateQueue(change) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const store = await queueStore();
+    const jobs = readRows(store);
+    const result = change(jobs);
+    try { store.write(jobs); return result; }
+    catch (error) { if (!error.message.includes('version conflict') || attempt === 7) throw error; }
+  }
+}
+
+function publicJob({ replay, task, ...job }) {
+  return { ...job, task: task.slice(0, 160), canRetry: Boolean(replay) && !job.needsReview };
+}
+
+export async function queueIncludedJob(request, result, { role, replay, launchPrevented = false } = {}) {
+  const workspace = request.contextCwd || request.cwd;
+  const direct = !replay && role === 'Dispatch' && workspace === request.cwd;
+  if (direct) replay = { kind: 'dispatch', request: destinationDispatchRequest(request) };
+  const job = {
+    id: randomUUID(), status: 'waiting', agent: request.agent, workspace, role: role || 'Dispatch',
+    task: String(request.contextTask || request.prompt).slice(0, direct ? 160 : 65536),
+    reason: 'included-usage-exhausted',
+    resetsAt: Number.isFinite(Date.parse(result.resetsAt)) ? result.resetsAt : null,
+    queuedAt: new Date().toISOString(), attempts: 0,
+    needsReview: !replay || (!launchPrevented && request.permissions?.write === true),
+    replay: replay || null,
+  };
+  return mutateQueue(jobs => {
+    if (jobs.filter(item => ['waiting', 'running'].includes(item.status)).length >= 200) throw new Error('Included usage queue is full.');
+    const history = jobs.filter(item => !['waiting', 'running'].includes(item.status)).slice(0, -50);
+    for (const item of history) jobs.splice(jobs.indexOf(item), 1);
+    jobs.push(job);
+    if (Buffer.byteLength(JSON.stringify(jobs)) > 4 * 1024 * 1024) throw new Error('Included usage queue exceeds its storage bound.');
+    return publicJob(job);
+  });
+}
+
+export async function listIncludedJobs() {
+  const jobs = readRows(await queueStore());
+  return jobs.map(publicJob);
+}
+
+function updateJob(jobs, id, change) {
+  const index = jobs.findIndex(job => job.id === id);
+  if (index < 0) throw new Error('Included usage job was not found.');
+  return jobs[index] = change(jobs[index]);
+}
+
+export async function cancelIncludedJob(id) {
+  return mutateQueue(jobs => publicJob(updateJob(jobs, id, job => {
+    if (job.status !== 'waiting') throw new Error('Only a waiting job can be cancelled.');
+    return { ...job, status: 'cancelled', replay: null };
+  })));
+}
+
+/** Claim atomically before retry, so two callers cannot start the same job. */
+export async function retryIncludedJob(id, { dispatch, route, now = Date.now() } = {}) {
+  if (!(await readIncludedPolicy()).enabled) throw new Error('Included usage policy must be enabled to retry.');
+  const claimed = await mutateQueue(jobs => updateJob(jobs, id, job => {
+    if (job.status !== 'waiting') throw new Error('Only a waiting job can be retried.');
+    if (job.needsReview || !job.replay) throw new Error('Review the prior attempt and resubmit this task from its original workspace.');
+    if (Date.parse(job.resetsAt) > now) throw new Error('The provider-reported reset time has not arrived.');
+    return { ...job, status: 'running', attempts: job.attempts + 1, startedAt: new Date(now).toISOString() };
+  }));
+  let result;
+  try {
+    if (claimed.replay.kind === 'dispatch') {
+      dispatch ??= (await import('./dispatch.mjs')).dispatchWithReceipt;
+      result = await dispatch(claimed.replay.request, { role: 'Dispatch', retryId: id });
+    } else if (claimed.replay.kind === 'route') {
+      route ??= (await import('./cascade.mjs')).executeRoutedTask;
+      result = await route(claimed.task, { cwd: claimed.workspace, gate: claimed.replay.gate, gateOptions: claimed.replay.gateOptions,
+        route: { selected: claimed.agent }, pool: [claimed.agent], retryId: id });
+    } else throw new Error('Unknown included usage job operation.');
+  } catch (error) {
+    result = { ok: false, failureKind: 'execution', error: error.message };
+  }
+  const held = ['quota', 'billing-policy', 'auth'].includes(result.failureKind);
+  const updated = await mutateQueue(jobs => updateJob(jobs, id, job => {
+    if (job.status !== 'running') throw new Error('Included usage job lost its claim.');
+    return { ...job, status: result.ok ? 'completed' : held ? 'waiting' : 'failed',
+      resetsAt: held && Number.isFinite(Date.parse(result.resetsAt)) ? result.resetsAt : null,
+      needsReview: job.needsReview || result.needsReview === true ||
+        (held && !result.launchPrevented && (job.replay.kind === 'route' || job.replay.request?.permissions?.write === true)),
+      lastError: result.ok ? null : result.error,
+      replay: held ? job.replay : null, finishedAt: new Date().toISOString() };
+  }));
+  return { ...result, job: publicJob(updated) };
+}