total-recall-brain 3.43.3 → 3.45.0

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

@@ -1,38 +1,93 @@
 /** 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, cancellationResult } from './worker.mjs';
 import { recordRunReceipt } from './learner.mjs';
-import { isGitRepo, createWorktree, removeWorktree } from './worktree.mjs';
+import { isGitRepo, createWorktree, removeWorktree, commitAll, deleteBranch } from './worktree.mjs';
+import { randomUUID } from 'node:crypto';
+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, manageWrites = false, usagePolicy = readIncludedPolicy, admit = includedAdmission, admitOpenRouter = openRouterAdmission } = {}) {
   const started = Date.now();
+  if (cancellationResult()) return cancellationResult();
   // 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;
+  const ownWrites = manageWrites && node === 'local' && request.permissions?.write === true && isGitRepo(request.cwd);
+  let scratch = null, branch = 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 } };
+    }
+    result = cancellationResult() || result;
+    if (!result) {
+      if (contain || ownWrites) {
+        branch = ownWrites ? `meta-harness/dispatch-${randomUUID()}` : null;
+        scratch = createWorktree(request.cwd, { ...(branch ? { branch } : {}), prefix: ownWrites ? 'meta-harness-dispatch-' : 'meta-harness-readonly-' });
+        effective = { ...effective, ...(branch ? { branch } : {}), cwd: scratch, contextCwd: request.contextCwd || request.cwd, isolated: true };
+      }
+      result = dispatchFn ? await dispatchFn(effective) : await executeOnNode(node, { ...effective, operation: 'dispatch' });
+      if (cancellationResult()) result = { ...result, ...cancellationResult() };
+      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)) };
   } finally {
-    if (scratch) removeWorktree(request.cwd, scratch);
+    if (scratch) {
+      try {
+        if (branch) {
+          const commit = commitAll(scratch, result?.cancelled ? 'meta-harness: unfinished cancelled dispatch' : 'meta-harness: dispatch changes');
+          if (commit) result = { ...result, branch, ...(result?.ok ? { commit } : { wip: commit }) };
+          else if (result?.sessionId) result = { ...result, branch };
+          else deleteBranch(request.cwd, branch);
+        }
+      } finally { removeWorktree(request.cwd, scratch); }
+      if (branch && !result?.branch) deleteBranch(request.cwd, branch);
+    }
   }
   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) {
+    // A launch refused for quota is a quota wall too (A-124): record it, so routing sees the harness as
+    // 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 */ }
+    }
+    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 } : {}) };
 }

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

@@ -3,7 +3,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
-import { loadCustomAdapters } from './worker.mjs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { agentEnvironment, loadCustomAdapters } from './worker.mjs';
+
+const exec = promisify(execFile);
 
 export const DOC_SOURCES = [
   { id: 'claude', index: 'https://code.claude.com/docs/llms.txt', prefix: 'https://code.claude.com/docs/', catalog:true },
@@ -69,7 +73,7 @@ async function download(url, fetchImpl, declaredOrigin) {
   if (declaredOrigin) allowed.add(declaredOrigin);
   for(let redirects=0;redirects<5;redirects++) {
     if(target.protocol!=='https:' || target.username || target.password || !allowed.has(target.hostname)) throw new Error(`Unapproved official documentation origin: ${target.hostname}`);
-    const response=await fetchImpl(target,{redirect:'manual',signal:AbortSignal.timeout(20000),headers:{'User-Agent':'Total-Recall-Meta-Harness-Docs','Accept':'*/*'}});
+    const response=await fetchImpl(target,{redirect:'manual',signal:AbortSignal.timeout(20000),headers:{'User-Agent':'Total-Recall-Metaharness-Docs','Accept':'*/*'}});
     if(response.status>=300 && response.status<400){target=new URL(response.headers.get('location'),target);continue;}
     // Some entries advertise Markdown exports which no longer exist while the
     // same official HTML document remains available. Fetch that representation.
@@ -91,7 +95,27 @@ function links(text,base,prefix) {
   return [...new Set(values.map(value=>{try{const url=new URL(value);url.hash='';url.search='';url.pathname=url.pathname.replace(/\/{2,}/g,'/').replace(/\/$/,'') || '/';return url.href;}catch{return '';}}))]
     .filter(url=>url.startsWith(prefix) && !/%3[CE]|[<>"'`\s]/i.test(url) && !/\.(png|jpg|jpeg|svg|gif|css|js|woff2?|ico|pdf|json|ya?ml|xml|zip|gz|tgz|lock)$/i.test(url));
 }
-export async function refreshDocumentation({ directory = documentationDirectory(), agent, fetchImpl = fetch, now = () => new Date(), maxPages = 1500 } = {}) {
+async function gitDocumentationPaths(source) {
+  const checkout = fs.mkdtempSync(path.join(os.tmpdir(), 'meta-harness-doc-tree-'));
+  const options = {
+    cwd: checkout, timeout: 30000, maxBuffer: 4 * 1024 * 1024,
+    env: { ...agentEnvironment(), GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: os.devNull },
+  };
+  try {
+    await exec('git', ['-c', 'http.followRedirects=false', 'clone', '--quiet', '--filter=blob:none',
+      '--depth=1', '--single-branch', '--branch', source.branch, '--no-checkout',
+      '--', `https://github.com/${source.repo}.git`, checkout], options);
+    const { stdout } = await exec('git', ['ls-tree', '-r', '-z', 'HEAD', '--', ...source.directories], options);
+    return stdout.split('\0').flatMap(entry => {
+      const match = /^100(?:644|755) blob [a-f0-9]+\t([\s\S]+)$/.exec(entry);
+      return match ? [match[1]] : [];
+    });
+  } catch {
+    throw new Error(`Could not read the official documentation tree through Git for ${source.repo}`);
+  } finally { fs.rmSync(checkout, { recursive: true, force: true }); }
+}
+
+export async function refreshDocumentation({ directory = documentationDirectory(), agent, fetchImpl = fetch, now = () => new Date(), maxPages = 1500, readGitPaths = gitDocumentationPaths } = {}) {
   const sources=sourcesFor(agent);
   if(!sources.length)throw new Error('Unknown documentation adapter');
   const reports=[];
@@ -99,11 +123,27 @@ export async function refreshDocumentation({ directory = documentationDirectory(
     const previous=metadata(directory,source.id), pages=[], queue=[source.index], seen=new Set(), queued=new Set(queue), errors=[], discovered=new Set(), skipped=[];
     // `found` marks a link taken from HTML navigation. The vendor's catalog, the index and the repository tree are authoritative; a link found by scraping is not.
     const enqueue=(url,found=false)=>{if(!queued.has(url)){queued.add(url);queue.push(url);if(found)discovered.add(url);}};
+    let treeSource;
     try {
       if(source.repo) {
-        const tree=JSON.parse(await download(`https://api.github.com/repos/${source.repo}/git/trees/${source.branch}?recursive=1`,fetchImpl));
-        if(tree.truncated)throw new Error('Official repository documentation tree is truncated');
-        for(const entry of tree.tree || [])if(entry.type==='blob' && /\.(md|mdx)$/i.test(entry.path) && source.directories.some(dir=>entry.path.startsWith(dir)))enqueue(`https://raw.githubusercontent.com/${source.repo}/${source.branch}/${entry.path}`);
+        let paths;
+        try {
+          const tree = JSON.parse(await download(`https://api.github.com/repos/${source.repo}/git/trees/${source.branch}?recursive=1`, fetchImpl));
+          if (tree.truncated) throw new Error('Official repository documentation tree is truncated');
+          if (!Array.isArray(tree.tree)) throw new Error('Invalid official repository documentation tree');
+          paths = tree.tree.filter(entry => entry.type === 'blob').map(entry => entry.path);
+          treeSource = 'github-rest';
+        } catch (error) {
+          if (!/^Documentation HTTP (403|429):|^Official repository documentation tree is truncated$/.test(error.message)) throw error;
+          paths = await readGitPaths(source);
+          treeSource = 'github-git';
+        }
+        for (const file of paths) {
+          if (!/\.(md|mdx)$/i.test(file) || !source.directories.some(dir => file.startsWith(dir))) continue;
+          const encoded = file.split('/').map(encodeURIComponent).join('/');
+          enqueue(`https://raw.githubusercontent.com/${source.repo}/${source.branch}/${encoded}`);
+        }
+        if (queue.length === 1) throw new Error('Official repository documentation tree contains no additional pages');
       }
       // Bounded batches; follow the official index/navigation to cover agent features.
       while(queue.length) {
@@ -138,7 +178,7 @@ export async function refreshDocumentation({ directory = documentationDirectory(
         reports.push({id:source.id,ok:false,error,pages:preserved.pages?.length || 0,downloadedPages:pages.length,failedCount:errors.length,failures:errors,...(skipped.length?{skippedCount:skipped.length,skipped}:{})});continue;
       }
       atomic(path.join(directory,source.id,'index.json'),JSON.stringify({id:source.id,complete:true,checkedAt,lastAttempt:checkedAt,pages,...(skipped.length?{skipped}:{})},null,2));
-      reports.push({id:source.id,ok:true,pages:pages.length,...(skipped.length?{skippedCount:skipped.length,skipped}:{})});
+      reports.push({id:source.id,ok:true,pages:pages.length,...(treeSource?{treeSource}:{}),...(skipped.length?{skippedCount:skipped.length,skipped}:{})});
     } catch(error) {
       atomic(path.join(directory,source.id,'index.json'),JSON.stringify({...previous,id:source.id,lastAttempt:now().toISOString(),error:error.message},null,2));
       reports.push({id:source.id,ok:false,error:error.message,pages:previous?.pages?.length || 0});
@@ -156,11 +196,15 @@ export async function ensureDocumentation(options={}) {
 
 export async function maintainDocumentation(options={}) {
   const status=documentationStatus(options);
-  const next=status.agents.filter(row=>!row.fresh).sort((a,b)=>String(a.lastAttempt || '').localeCompare(String(b.lastAttempt || '')))[0];
-  if(!next)return {...status,scope:'all-agent-documentation-current'};
-  const refreshed=await refreshDocumentation({...options,agent:next.id});
+  const pending=status.agents.filter(row=>!row.fresh).sort((a,b)=>String(a.lastAttempt || '').localeCompare(String(b.lastAttempt || '')));
+  const reports=[];
+  // Missing documentation for one harness must not prevent attempts for the others.
+  for(const row of pending) {
+    try { reports.push(...(await refreshDocumentation({...options,agent:row.id})).agents); }
+    catch(error) { reports.push({id:row.id,ok:false,error:error.message}); }
+  }
   const current=documentationStatus(options);
-  return {...refreshed,scope:'one-stale-agent-refreshed',coverage_complete:current.ok,pending:current.agents.filter(row=>!row.fresh).map(row=>row.id)};
+  return {...current,ok:current.ok && reports.every(row=>row.ok),scope:'all-agent-documentation',refresh:reports,coverage_complete:current.ok,pending:current.agents.filter(row=>!row.fresh).map(row=>row.id)};
 }
 
 export function readDocumentation({agent,url,directory=documentationDirectory()}) {

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

@@ -3,6 +3,10 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { runWorker, runProcess, getActiveAdapters, notReady, agentEnvironment } from './worker.mjs';
 import { dispatchWithReceipt } from './dispatch.mjs';
+import { commandPermissions, destinationDispatchRequest } from './dispatch-request.mjs';
+import { readIncludedPolicy } from './included-usage.mjs';
+
+export { DEFAULT_PERMISSIONS, commandPermissions } from './dispatch-request.mjs';
 
 async function hostModule(name) {
   const selected = process.env.TR_PACKAGE_ROOT;
@@ -12,13 +16,6 @@ async function hostModule(name) {
   return import(pathToFileURL(path.join(root, 'src/core', `${name}.mjs`)).href);
 }
 
-export const DEFAULT_PERMISSIONS = Object.freeze({ read: true, write: false, send: false, destructive: false });
-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 };
-}
-
 export async function listTargets() {
   try {
     const mesh = await hostModule('mesh');
@@ -27,32 +24,84 @@ export async function listTargets() {
       nodes: nodes.length > 0 ? nodes : [{ id: 'local', name: 'Local Host', online: true, self: true, accessConfigured: true }],
       adapters: getActiveAdapters().map(({ id, name, docs, custom }) => ({ id, name, docs, custom: Boolean(custom) }))
     };
-  } catch {
+  } catch (error) {
     return {
       nodes: [{ id: 'local', name: 'Local Host', online: true, self: true, accessConfigured: true }],
-      adapters: getActiveAdapters().map(({ id, name, docs, custom }) => ({ id, name, docs, custom: Boolean(custom) }))
+      adapters: getActiveAdapters().map(({ id, name, docs, custom }) => ({ id, name, docs, custom: Boolean(custom) })),
+      meshError: String(error?.message || error).slice(0, 400),
     };
   }
 }
 
 export function workerProgram(request) {
-  const source = fs.readFileSync(new URL('./worker.mjs', import.meta.url), 'utf8');
-  return source + '\nrunWorker(' + JSON.stringify(request) + ').then(result=>console.log(JSON.stringify(result))).catch(error=>{console.error(String(error?.message||"Selected agent worker failed"));process.exitCode=1;});\n';
+  // Materialize a portable module graph. The stdin launcher imports only Node
+  // built-ins. Relative imports resolve inside this owned bundle on the node.
+  const names = ['worker.mjs', 'control.mjs', 'jobs.mjs', 'paths.mjs', 'mcp-server.mjs',
+    ...fs.readdirSync(new URL('./session/', import.meta.url)).filter(name => name.endsWith('.mjs')).map(name => `session/${name}`)];
+  const files = Object.fromEntries(names.map(name => [name, fs.readFileSync(new URL(name, import.meta.url), 'utf8')]));
+  return `import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'metaharness-worker-'));
+try {
+  for (const [name, source] of Object.entries(${JSON.stringify(files)})) {
+    const file = path.join(directory, name);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, source, { mode: 0o600 });
+  }
+  const { runWorker } = await import(pathToFileURL(path.join(directory, 'worker.mjs')).href);
+  console.log(JSON.stringify(await runWorker(${JSON.stringify(request)})));
+} catch (error) { console.error(String(error?.message || 'Selected agent worker failed')); process.exitCode = 1; }
+finally { fs.rmSync(directory, { recursive: true, force: true }); }
+`;
+
+}
+
+function destinationDispatchResult(result, node, request) {
+  let payload;
+  try { payload = JSON.parse(result.output); } catch { /* No structured result from the installed owner. */ }
+  if (!payload || typeof payload.ok !== 'boolean' || (payload.ok && !result.ok)) {
+    throw notReady(`Installed Metaharness on ${node} returned no valid dispatch outcome (exit ${result.exitCode ?? 'unknown'})`);
+  }
+  return { ...payload, execution: { node, workspace: request.cwd, remote: true,
+    ...(typeof payload.receiptId === 'string' ? { receiptOwner: 'destination' } : {}) } };
 }
 
 export async function executeOnNode(node, request, { worker = runWorker, processRunner = runProcess, mesh, access } = {}) {
   if (!node || node === 'local') return worker(request);
-  mesh ||= await hostModule('mesh'); access ||= await hostModule('mesh-access');
+  mesh ||= await hostModule('mesh');
   const target = mesh.findMeshNode(node);
   if (!target) throw new Error('Selected mesh node is not recorded');
-  if (target.self) return worker(request);
+  if (target.self && request.operation !== 'dispatch') return worker(request);
+  // Route simple dispatch through the installed owner, just like a routed, coordinated or managed job.
+  const dispatch = request.operation === 'dispatch';
+  let transport = request;
+  if (dispatch) {
+    const input = JSON.stringify(destinationDispatchRequest(request));
+    if (Buffer.byteLength(input) > 65536) throw new Error('Remote dispatch request is too large');
+    // The transport outlives the attempt it carries by a minute, so the destination reports its own timeout (A-101).
+    transport = { operation: 'direct', cwd: request.cwd, argv: ['total-recall', 'meta-harness', 'dispatch', '--stdin', '--json'], input,
+      timeoutMs: Number.isInteger(request.timeoutMs) && request.timeoutMs > 0 ? request.timeoutMs + 60_000 : 600000 };
+  }
+  const managed = dispatch || (transport.argv?.[1] === 'meta-harness' &&
+    ['route', 'coordinate', 'review', 'process', 'run-command', 'usage-retry'].includes(transport.argv[2]));
+  if (managed && (await readIncludedPolicy()).enabled) transport = { ...transport, requireIncluded: true };
+  if (target.self) {
+    const result = destinationDispatchResult(await worker(transport), 'local', request);
+    result.execution.remote = false;
+    return result;
+  }
   if (target.online === false) throw new Error('Selected mesh node is offline');
+  access ||= await hostModule('mesh-access');
   const resolved = access.resolveNodeAccess(target);
   const args = access.buildSshArgs(resolved, { command: 'export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"; exec node --input-type=module', extraOptions: ['BatchMode=yes', 'ConnectTimeout=10'] });
   if (!args) throw new Error('Selected mesh node has no verified SSH access');
-  const result = await processRunner('ssh', args, { input: workerProgram(request), timeoutMs: request.operation === 'inspect' ? 120000 : (request.timeoutMs || 900000) + 30000, maxBytes: 17 * 1024 * 1024, env: { ...agentEnvironment(), ...(process.env.SSH_AUTH_SOCK ? { SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK } : {}) } });
+  const result = await processRunner('ssh', args, { input: workerProgram(transport), timeoutMs: transport.operation === 'inspect' ? 120000 : (transport.timeoutMs || 900000) + 30000, maxBytes: 17 * 1024 * 1024, env: { ...agentEnvironment(), ...(process.env.SSH_AUTH_SOCK ? { SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK } : {}) } });
   if (result.reason || result.exitCode !== 0) throw notReady(`Worker on ${node} failed: ${String(result.stderr || result.reason || 'verify node access, workspace and agent installation').trim().slice(0, 400)}`);
-  try { return JSON.parse(result.stdout); } catch { throw new Error('Selected mesh worker returned invalid data'); }
+  let payload;
+  try { payload = JSON.parse(result.stdout); } catch { throw new Error('Selected mesh worker returned invalid data'); }
+  return dispatch ? destinationDispatchResult(payload, target.hostname || node, request) : payload;
 }
 
 export async function inspectNode(node = 'local', dependencies) {

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/gate-adapters/hermes.mjs

@@ -27,6 +27,32 @@ function withGate(text) {
   return `${text.replace(/\n*$/, text ? '\n' : '')}\nhooks:\n  pre_tool_call:\n${entry}`;
 }
 
+/**
+ * Remove every hook list item whose command runs the gate. Other tools rewrite config.yaml (the
+ * lesson hooks re-serialize it), so the item is found by indentation, not by its exact text: the
+ * item runs from its `- ` line to the next line indented no deeper than that dash.
+ */
+export function withoutGate(text) {
+  if (!text.includes(GATE)) return text;
+  const exact = text.replace(ENTRY_LINES, '');
+  if (!exact.includes(GATE)) return exact;
+  let lines = text.split('\n');
+  const indent = (line) => line.match(/^ */)[0].length;
+  for (let guard = 0; guard < 50; guard++) {
+    const hit = lines.findIndex((line) => line.includes(GATE));
+    if (hit < 0) break;
+    let start = hit;
+    while (start >= 0 && !/^ *- /.test(lines[start])) start--;
+    if (start < 0 || indent(lines[start]) > indent(lines[hit])) break;
+    const dash = indent(lines[start]);
+    let end = start + 1;
+    while (end < lines.length && (lines[end].trim() === '' || indent(lines[end]) > dash)) end++;
+    while (end > start + 1 && lines[end - 1].trim() === '') end--;
+    lines = [...lines.slice(0, start), ...lines.slice(end)];
+  }
+  return lines.join('\n');
+}
+
 export const hermesAdapter = {
   id: 'hermes',
   level: 'enforced',
@@ -118,7 +144,9 @@ export const hermesAdapter = {
     const present = text.includes(GATE);
     if (remove || off) {
       if (present) {
-        if (!dryRun) fs.writeFileSync(configPath, text.replace(ENTRY_LINES, ''));
+        const next = withoutGate(text);
+        if (next.includes(GATE)) throw new Error(`could not remove the gate from ${configPath}; remove the pre_tool_call entry that runs "${GATE}" by hand`);
+        if (!dryRun) fs.writeFileSync(configPath, next);
         removed.push('managed pre_tool_call gate');
       }
       return { settings: configPath, added, removed };

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/gate-adapters/index.mjs

@@ -1,5 +1,5 @@
 /**
- * Gate Adapters registry for Meta Harness (tr-plugin-cli-agents).
+ * Gate Adapters registry for Metaharness (tr-plugin-cli-agents).
  * Provides harness-specific parsing, emission, installation and verification.
  */
 import { claudeAdapter } from './claude.mjs';

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: 'Metaharness', 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 };
+  }
+}