total-recall-brain 3.43.3 → 3.45.0

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

@@ -0,0 +1,84 @@
+/** Local job identity and cancellation. A terminal log result is the completion record. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { configDir } from './paths.mjs';
+import { createProgress } from './worker.mjs';
+
+const jobsDir = () => path.join(configDir(), 'jobs');
+export const newJobId = () => `${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+
+export function startJob(operation, { id = newJobId() } = {}) {
+  if (!/^[a-z0-9-]+$/.test(id)) throw new Error('Invalid job ID.');
+  const directory = jobsDir();
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const log = path.join(directory, `${id}.log`);
+  const pidFile = path.join(directory, `${id}.pid`);
+  const record = { job: id, pid: process.pid, operation, startedAt: new Date().toISOString() };
+  fs.appendFileSync(log, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+  fs.writeFileSync(pidFile, `${process.pid}\n`, { mode: 0o600, flag: 'wx' });
+  const progress = createProgress({ file: path.join(directory, `${id}.events.jsonl`), harness: operation });
+  return { ...record, log, finish(result) {
+    progress.close(result);
+    fs.appendFileSync(log, `${JSON.stringify(result)}\n`, { mode: 0o600 });
+    fs.rmSync(pidFile, { force: true });
+  } };
+}
+
+function readJob(log) {
+  const lines = fs.readFileSync(log, 'utf8').trim().split('\n');
+  let record;
+  try { record = JSON.parse(lines[0]); } catch { /* old log without PID */ }
+  let result = null;
+  for (const line of lines.slice(1).reverse()) {
+    try {
+      const value = JSON.parse(line);
+      if (typeof value.ok === 'boolean') { result = value; break; }
+    } catch { /* progress text */ }
+  }
+  return { record, result };
+}
+
+export function resolveJob(target) {
+  if (!target) throw new Error('cancel requires a job ID or log path.');
+  const directory = jobsDir();
+  const prefix = path.basename(target).replace(/\.(?:log|pid|events\.jsonl|status\.json)$/, '');
+  const files = fs.existsSync(directory) ? fs.readdirSync(directory) : [];
+  let names = files.filter(name => name.endsWith('.log') && name.startsWith(prefix));
+  if (!names.length) {
+    // An attempt ID from watch resolves to its owning job, never directly to a PID.
+    const events = files.filter(name => name.endsWith('.events.jsonl') && name.startsWith(prefix))
+      .sort((a, b) => fs.statSync(path.join(directory, b)).mtimeMs - fs.statSync(path.join(directory, a)).mtimeMs);
+    let pid;
+    try { pid = JSON.parse(fs.readFileSync(path.join(directory, events[0].replace('.events.jsonl', '.status.json')), 'utf8')).pid; } catch { /* no matching status */ }
+    if (pid) names = files.filter(name => name.endsWith('.log') && readJob(path.join(directory, name)).record?.pid === pid);
+  }
+  const exact = names.find(name => name === `${prefix}.log`);
+  if (!names.length) throw new Error(`No job log matches ${target}.`);
+  if (!exact && names.length > 1) throw new Error(`More than one job matches ${target}. Use a longer job ID.`);
+  const log = path.join(directory, exact || names[0]);
+  return { id: path.basename(log, '.log'), log, ...readJob(log) };
+}
+
+export async function cancelJob(target, { timeoutMs = 60_000, pollMs = 100 } = {}) {
+  const job = resolveJob(target);
+  if (job.result) throw new Error(`Job ${job.id} has finished${job.result.cancelled ? ' (cancelled)' : ''}.`);
+  const pidFile = path.join(jobsDir(), `${job.id}.pid`);
+  let pid;
+  try { pid = Number(fs.readFileSync(pidFile, 'utf8').trim()); } catch { /* stale or old job */ }
+  if (!Number.isSafeInteger(pid) || pid <= 1 || job.record?.pid !== pid || job.record?.job !== job.id) {
+    throw new Error(`Job ${job.id} has no active PID record.`);
+  }
+  try { process.kill(pid, 'SIGTERM'); }
+  catch (error) { throw new Error(`Cannot cancel job ${job.id}: ${error.code === 'ESRCH' ? 'the process has stopped' : error.message}.`); }
+  const deadline = Date.now() + Math.min(timeoutMs, 60_000);
+  do {
+    const { result } = readJob(job.log);
+    if (result) {
+      if (!result.cancelled) throw new Error(`Job ${job.id} finished before it could be cancelled.`);
+      return { ...result, job: job.id, log: job.log };
+    }
+    await new Promise(resolve => setTimeout(resolve, pollMs));
+  } while (Date.now() < deadline);
+  throw new Error(`Job ${job.id} did not report cancellation within ${Math.min(timeoutMs, 60_000) / 1000} seconds. Log: ${job.log}`);
+}

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

@@ -2,7 +2,6 @@
  * Execution receipts and the learning loop.
  * Receipts are an append-only SSSS ledger. Scorecards, quota walls and proposals fold from it.
  */
-import { spawnSync } from 'node:child_process';
 import { computeEmpiricalScorecard } from '../capability/index.mjs';
 import { receiptsFile } from './paths.mjs';
 import { classifyFailure } from './worker.mjs';
@@ -49,6 +48,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,
@@ -102,18 +104,10 @@ export function activeCredentialBlocks(entries = [], now = Date.now(), holdMs =
   return blocks;
 }
 
-/** With `emit`, proposals are written through the memory owner. A failed write is reported, never hidden. */
-export async function learnFromHistory({ emit = false, runner = spawnSync } = {}) {
+/** Read the same receipts the router uses. Proposals stay in this report. */
+export async function learnFromHistory() {
   const entries = await readReceipts();
   const scorecard = computeEmpiricalScorecard(entries);
   const proposals = proposalsFrom(scorecard, entries);
-  const emitted = [];
-  if (emit) for (const proposal of proposals) {
-    const result = runner(process.env.TOTAL_RECALL_BIN || 'total-recall', ['remember', 'fact', `${proposal.reason} ${proposal.recommendation}`, '--project', '--slug', proposal.id, '--tags', `meta-harness,${proposal.id}`], { encoding: 'utf8', timeout: 30000 });
-    const output = `${result.stdout || ''}\n${result.stderr || ''}`;
-    // The slug is the proposal's identity, so an open proposal is reported once, however often learn runs.
-    const existing = result.status !== 0 && /already exists/i.test(output);
-    emitted.push({ id: proposal.id, ok: result.status === 0 || existing, ...(existing ? { existing: true } : {}), error: result.status === 0 || existing ? undefined : String(result.stderr || result.error || 'remember failed').slice(0, 300) });
-  }
-  return { ok: emitted.every(row => row.ok), totalHistoryRuns: entries.length, scorecard, walls: activeQuotaWalls(entries), credentialBlocks: activeCredentialBlocks(entries), proposals, ...(emit ? { emitted } : {}) };
+  return { ok: true, totalHistoryRuns: entries.length, scorecard, walls: activeQuotaWalls(entries), credentialBlocks: activeCredentialBlocks(entries), proposals };
 }

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

@@ -0,0 +1,17 @@
+/** Run each maintenance owner even when another owner fails. The daemon records the result. */
+import { setupIntegrations } from './setup.mjs';
+import { maintainDocumentation } from './documentation.mjs';
+
+export async function maintainIntegrations(options = {}, owners = {}) {
+  const steps = {
+    setup: owners.setup || (() => setupIntegrations()),
+    gates: owners.gates || (async () => (await import('./gate-adapters/index.mjs')).installAll()),
+    docs: owners.docs || (() => maintainDocumentation(options)),
+  };
+  const result = {};
+  for (const [name, execute] of Object.entries(steps)) {
+    try { result[name] = await execute(); }
+    catch (error) { result[name] = { ok: false, error: error.message }; }
+  }
+  return { ...result, ok: Object.values(result).every(step => step?.ok === true) };
+}

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

@@ -0,0 +1,228 @@
+/**
+ * MCP stdio (JSONL), with the initialize lifecycle used by Claude and Codex.
+ * Protocol: https://modelcontextprotocol.io/specification/2025-11-25
+ * Approval result: https://code.claude.com/docs/en/agent-sdk/user-input
+ */
+import { createInterface } from 'node:readline';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { brainDir } from './paths.mjs';
+import { appendEvent, jobPaths, tailInbox } from './control.mjs';
+
+const execute = promisify(execFile);
+export const QUESTION_TIMEOUT_MS = 10 * 60_000;
+export const NO_ANSWER = 'No answer; proceed on your best judgment';
+const versions = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const textResult = text => ({ content: [{ type: 'text', text }] });
+const fault = (code, message) => Object.assign(new Error(message), { code });
+
+export const MCP_TOOLS = [
+  { name: 'ask', description: 'Ask the operator questions and wait for a reply.', inputSchema: {
+    type: 'object', properties: { questions: { type: 'array', minItems: 1, items: { oneOf: [{ type: 'string', minLength: 1 }, { type: 'object' }] } } }, required: ['questions'], additionalProperties: false,
+  } },
+  { name: 'approve', description: 'Answer a Claude Code permission prompt under the job approval policy.', inputSchema: {
+    type: 'object', properties: { tool_name: { type: 'string', minLength: 1 }, input: { type: 'object' }, tool_use_id: { type: 'string' } }, required: ['tool_name', 'input'],
+  } },
+];
+
+/** Return Claude's --mcp-config object and Codex's -c arguments. No shell parses these values. */
+export function mcpConfigFor(job, options = {}) {
+  const id = jobPaths(job).id;
+  const command = process.execPath;
+  const args = [fileURLToPath(import.meta.url), '--approvals', options.approvalPolicy || 'auto',
+    '--question-timeout-ms', String(options.questionTimeoutMs ?? options.timeoutMs ?? QUESTION_TIMEOUT_MS)];
+  const env = { TR_METAHARNESS_JOB: id, TR_SECRETS_BRAIN: brainDir() };
+  if (process.env.TOTAL_RECALL_BIN) env.TOTAL_RECALL_BIN = process.env.TOTAL_RECALL_BIN;
+  const claude = { mcpServers: { metaharness: { command, args, env } } };
+  const tomlEnv = `{ ${Object.entries(env).map(([key, value]) => `${key} = ${JSON.stringify(value)}`).join(', ')} }`;
+  const codex = ['-c', `mcp_servers.metaharness.command=${JSON.stringify(command)}`,
+    '-c', `mcp_servers.metaharness.args=${JSON.stringify(args)}`, '-c', `mcp_servers.metaharness.env=${tomlEnv}`,
+    '-c', `mcp_servers.metaharness.tool_timeout_sec=${Math.ceil(Number(args.at(-1)) / 1000) + 60}`];
+  return { claude, codex, claudeArgs: ['--mcp-config', JSON.stringify(claude), '--permission-prompt-tool', 'mcp__metaharness__approve'], codexArgs: codex };
+}
+
+/** The decision owner returns a typed choice. Missing or failed decisions deny the call. */
+async function decideApproval(request, { signal } = {}) {
+  const questions = { approval: { type: 'choice', instructions: 'Apply Total Recall rules to this tool request. Allow only if the request is authorized. Deny if authorization is unclear.',
+    criteria: { allow: 'Authorized by the operator and the applicable rules.', deny: 'Not authorized or prohibited by a rule.' } } };
+  const { stdout } = await execute(process.env.TOTAL_RECALL_BIN || 'total-recall',
+    ['decision', 'run', '--state', JSON.stringify({ request }), '--questions', JSON.stringify(questions), '--json'],
+    { encoding: 'utf8', timeout: 60_000, maxBuffer: 1024 * 1024, signal });
+  const record = JSON.parse(stdout);
+  if (record.ok === false) throw new Error(record.error || 'The decision owner failed.');
+  const answer = record.answers?.approval ?? record.decision?.answers?.approval ?? record.result?.approval;
+  const value = typeof answer === 'string' ? answer : answer?.choice;
+  if (!['allow', 'deny'].includes(value)) throw new Error('The decision owner returned no allow or deny answer.');
+  return { value, record };
+}
+
+/** Resolve all pending calls on close; no poll timer or child command outlives the server. */
+export function createMcpTools({ job = process.env.TR_METAHARNESS_JOB, approvalPolicy = 'auto',
+  questionTimeoutMs = QUESTION_TIMEOUT_MS, timeoutMs, decisionFn = decideApproval, alertFn,
+  deferQuestions = process.env.TR_METAHARNESS_DEFER_QUESTIONS !== '0' } = {}) {
+  jobPaths(job);
+  if (!['auto', 'operator', 'rules'].includes(approvalPolicy)) throw new Error('Approval policy must be auto, operator, or rules.');
+  questionTimeoutMs = timeoutMs ?? questionTimeoutMs;
+  if (!Number.isSafeInteger(questionTimeoutMs) || questionTimeoutMs < 1) throw new Error('Question timeout must be a positive number of milliseconds.');
+  const pending = new Map();
+  const lifetime = new AbortController();
+  const children = new Set();
+  const notify = event => {
+    const task = alertFn ? Promise.resolve().then(() => alertFn(event)) : execute(process.env.TOTAL_RECALL_BIN || 'total-recall',
+      ['alerts', 'send', '--title', `Metaharness: ${event.kind}`, '--message', `Job ${job}: ${event.text}`, '--severity', 'info', '--source', 'meta-harness'],
+      { timeout: 15_000, maxBuffer: 65536, signal: lifetime.signal });
+    children.add(task);
+    task.catch(() => {}).finally(() => children.delete(task));
+  };
+  const watcher = tailInbox(job, command => {
+    const wait = pending.get(command.requestId);
+    if (!wait || command.type !== (wait.kind === 'question' ? 'reply' : 'approve')) return false;
+    wait.finish({ value: wait.kind === 'question' ? command.text : command.value, commandId: command.id });
+    return { via: 'metaharness' };
+  }, { recipient: 'mcp', onError: error => {
+    for (const wait of pending.values()) wait.fail(error);
+  } });
+
+  const waitFor = (event, signal) => new Promise((resolve, reject) => {
+    let timer;
+    const cleanup = () => { clearTimeout(timer); pending.delete(event.requestId); signal?.removeEventListener('abort', abort); };
+    const finish = value => { cleanup(); resolve(value); };
+    const fail = error => { cleanup(); reject(error); };
+    const abort = () => fail(new Error('The request was cancelled.'));
+    pending.set(event.requestId, { kind: event.kind, finish, fail });
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted || lifetime.signal.aborted) { abort(); return; }
+    timer = setTimeout(() => finish({ value: event.kind === 'question' ? NO_ANSWER : 'deny', timeout: true }), questionTimeoutMs);
+  });
+
+  return {
+    async call(name, args, { signal, defer = deferQuestions } = {}) {
+      if (lifetime.signal.aborted) throw new Error('The MCP server has closed.');
+      if (name === 'ask') {
+        if (!object(args) || !Array.isArray(args.questions) || !args.questions.length ||
+            args.questions.some(q => typeof q === 'string' ? !q.trim() : !object(q))) throw fault(-32602, 'ask requires a non-empty questions array.');
+      } else if (name === 'approve') {
+        if (!object(args) || typeof args.tool_name !== 'string' || !args.tool_name.trim() || !object(args.input) ||
+            (args.tool_use_id !== undefined && typeof args.tool_use_id !== 'string')) throw fault(-32602, 'approve requires tool_name and input.');
+      } else throw fault(-32602, `Unknown tool: ${name}`);
+      const requestId = randomUUID();
+      if (name === 'ask' && defer) {
+        // A question costs nothing while it waits (A-125): record it, tell the agent to end its turn,
+        // and let the session runner start the next turn with the operator's answer. Holding the tool
+        // call open made Codex call the model every few seconds while it waited.
+        const event = { kind: 'question', source: 'deferred', requestId, text: JSON.stringify(args.questions), questions: args.questions };
+        appendEvent(job, event);
+        notify(event);
+        return textResult(`Your question went to the operator (request ${requestId}). End your turn now and do no other work. The operator's answer arrives as the next message in this session.`);
+      }
+      const event = { kind: name === 'ask' ? 'question' : 'approval', source: 'mcp', requestId,
+        text: name === 'ask' ? JSON.stringify(args.questions) : `${args.tool_name}: ${JSON.stringify(args.input)}`,
+        ...(name === 'ask' ? { questions: args.questions } : { request: args, policy: approvalPolicy }) };
+      appendEvent(job, event);
+      let answer;
+      try {
+        if (name === 'ask' || approvalPolicy === 'operator') {
+          // Register the waiter before notifying the operator.
+          const waiting = waitFor(event, signal);
+          notify(event);
+          answer = await waiting;
+        } else if (approvalPolicy === 'auto') answer = { value: 'allow', policy: 'auto' };
+        else {
+          try { answer = { ...await decisionFn(args, { signal: signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal }), policy: 'rules' }; }
+          catch (error) { answer = { value: 'deny', policy: 'rules', error: error.message }; }
+          if (!['allow', 'deny'].includes(answer.value)) answer = { value: 'deny', policy: 'rules', error: 'Invalid decision answer.' };
+        }
+      } catch (error) {
+        appendEvent(job, { kind: 'ack', command: name, requestId, ok: true, cancelled: true, text: error.message });
+        throw error;
+      }
+      // tailInbox records delivery; this event records the actual answer and policy decision.
+      appendEvent(job, { kind: 'ack', command: name, requestId, ok: true, ...answer, text: String(answer.value) });
+      if (name === 'ask') return textResult(String(answer.value));
+      const result = answer.value === 'allow' ? { behavior: 'allow', updatedInput: args.input }
+        : { behavior: 'deny', message: answer.timeout ? 'Approval timed out.' : answer.error || 'The request was denied.' };
+      return textResult(JSON.stringify(result));
+    },
+    async close() {
+      lifetime.abort();
+      for (const wait of pending.values()) wait.fail(new Error('The MCP server has closed.'));
+      await watcher.close();
+      await Promise.allSettled(children);
+    },
+  };
+}
+
+/** Never log on stdout here: every line must be a JSON-RPC message. */
+export async function runMcpServer({ input = process.stdin, output = process.stdout, ...options } = {}) {
+  const tools = createMcpTools(options);
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  const calls = new Map();
+  let initialized = false, ready = false, closed = false;
+  const write = message => { if (!closed) output.write(JSON.stringify(message) + '\n'); };
+  const respond = (id, result) => write({ jsonrpc: '2.0', id, result });
+  const error = (id, code, message) => write({ jsonrpc: '2.0', id, error: { code, message } });
+  const handle = async message => {
+    if (!object(message) || message.jsonrpc !== '2.0' || typeof message.method !== 'string' ||
+        (Object.hasOwn(message, 'id') && typeof message.id !== 'string' && typeof message.id !== 'number') ||
+        (message.params !== undefined && !object(message.params))) {
+      error(null, -32600, 'Invalid Request'); return;
+    }
+    const { id, method, params = {} } = message;
+    if (id === undefined) {
+      if (method === 'notifications/initialized' && initialized) ready = true;
+      if (method === 'notifications/cancelled') calls.get(params.requestId)?.controller.abort();
+      return;
+    }
+    if (calls.has(id)) { error(id, -32600, 'Duplicate request ID'); return; }
+    if (method === 'initialize') {
+      if (initialized) { error(id, -32600, 'Already initialized'); return; }
+      if (typeof params.protocolVersion !== 'string' || !object(params.capabilities) || !object(params.clientInfo)) {
+        error(id, -32602, 'initialize requires protocolVersion, capabilities, and clientInfo'); return;
+      }
+      initialized = true;
+      respond(id, { protocolVersion: versions.includes(params.protocolVersion) ? params.protocolVersion : versions[0],
+        capabilities: { tools: {} }, serverInfo: { name: 'metaharness', version: '1.0.0' } });
+      return;
+    }
+    if (method === 'ping') { respond(id, {}); return; }
+    if (!ready) { error(id, -32002, 'Initialize the MCP session first'); return; }
+    if (method === 'tools/list') { respond(id, { tools: MCP_TOOLS }); return; }
+    if (method !== 'tools/call') { error(id, -32601, 'Method not found'); return; }
+    if (typeof params.name !== 'string') { error(id, -32602, 'tools/call requires a tool name'); return; }
+    const controller = new AbortController();
+    const call = { controller };
+    calls.set(id, call);
+    call.done = (async () => {
+      try { respond(id, await tools.call(params.name, params.arguments, { signal: controller.signal })); }
+      catch (failure) {
+        if (typeof failure.code === 'number') error(id, failure.code, failure.message);
+        else respond(id, { ...textResult(failure.message), isError: true });
+      } finally { calls.delete(id); }
+    })();
+  };
+  lines.on('line', line => {
+    let message;
+    try { message = JSON.parse(line); } catch { error(null, -32700, 'Parse error'); return; }
+    void handle(message).catch(failure => error(message?.id ?? null, -32603, failure.message));
+  });
+  try { await new Promise((resolve, reject) => { lines.once('close', resolve); input.once('error', reject); output.once('error', reject); }); }
+  finally {
+    closed = true;
+    lines.close();
+    for (const call of calls.values()) call.controller.abort();
+    await tools.close();
+    await Promise.allSettled([...calls.values()].map(call => call.done));
+  }
+}
+
+export const startMcpServer = runMcpServer;
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const value = flag => { const i = process.argv.indexOf(flag); return i < 0 ? undefined : process.argv[i + 1]; };
+  await runMcpServer({ approvalPolicy: value('--approvals') || 'auto',
+    questionTimeoutMs: value('--question-timeout-ms') === undefined ? QUESTION_TIMEOUT_MS : Number(value('--question-timeout-ms')) })
+    .catch(error => { console.error(`Metaharness MCP: ${error.message}`); process.exitCode = 1; });
+}

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

@@ -161,7 +161,7 @@ export async function executeProcessTask(job, dependencies = {}) {
       tools: job.options.tools, settingSources: job.options.settingSources, model: job.options.model,
       allowUnknownAuth: job.options.allowUnknownAuth === true, timeoutMs: job.options.timeoutMs,
     }, { role: 'Process', node: 'local' });
-    if (result.ok && worktree) commit = commitAll(worktree, 'Meta Harness managed agent work');
+    if (result.ok && worktree) commit = commitAll(worktree, 'Metaharness managed agent work');
   } catch (error) {
     result = { ok: false, error: error.message };
   }
@@ -169,8 +169,18 @@ export async function executeProcessTask(job, dependencies = {}) {
     if (worktree) { (dependencies.removeWorktree || removeWorktree)(job.cwd, worktree); worktree = null; }
     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,
+  const record = 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() });
+  return {
+    ...record,
+    ...(Array.isArray(result.toolResults) ? {
+      toolResults: result.toolResults,
+      toolExecutionVerified: result.toolExecutionVerified,
+      commandExecutionVerified: result.commandExecutionVerified,
+    } : {}),
+    ...(result.toolEvidenceError ? { toolEvidenceError: result.toolEvidenceError } : {}),
+  };
 }
 
 export async function killAgent(idOrPid, dependencies = {}) {
@@ -210,6 +220,20 @@ export async function getAgentLogs(idOrPid, tailLines = 50, dependencies = {}) {
   if (record.remote) {
     const result = await remoteCall(record.node, record.cwd, ['logs', record.id, '--tail', String(tailLines)], dependencies);
     if (typeof result.logs !== 'string') throw new Error('Remote owner returned no logs');
+    if (['starting', 'running'].includes(record.status)) {
+      for (const line of result.logs.trimEnd().split('\n').reverse()) {
+        let terminal;
+        try { terminal = JSON.parse(line); } catch { continue; }
+        if (terminal?.id !== record.id || !['completed', 'failed', 'killed'].includes(terminal.status) ||
+            typeof terminal.endedAt !== 'string' || !Number.isFinite(Date.parse(terminal.endedAt))) continue;
+        updateAgentRecord(record.id, {
+          status: terminal.status,
+          exitCode: Number.isInteger(terminal.exitCode) ? terminal.exitCode : null,
+          endedAt: terminal.endedAt,
+        });
+        break;
+      }
+    }
     return result.logs;
   }
   if (path.dirname(record.logFile || '') !== logDirectory()) throw new Error('Invalid managed log path');

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

@@ -1,4 +1,4 @@
-/** Headless reasoning belongs to Meta Harness, including config, readiness and receipts. */
+/** Headless reasoning belongs to Metaharness, including config, readiness and receipts. */
 import fs from 'node:fs';
 import path from 'node:path';
 import { brainDir } from './paths.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

@@ -9,6 +9,7 @@ const BOOLEAN_FLAGS = {
 };
 const VALUE_FLAGS = {
   mode: '--mode', orchestrator: '--orchestrator', explorer: '--explorer', architect: '--architect', implementer: '--implementer',
+  goal: '--goal', maxTurns: '--max-turns', maxBudgetUsd: '--max-budget-usd', maxTokens: '--max-tokens', approvalPolicy: '--approvals', questionTimeoutMs: '--question-timeout-ms', resultSchema: '--result-schema',
   verifier: '--verifier', reviewer: '--reviewer', author: '--author', threadId: '--thread', branch: '--branch',
 };
 const OPERATION_KEYS = {
@@ -33,9 +34,12 @@ export async function forwardRemoteOperation(operation, task, options = {}) {
     if (typeof task !== 'string' || !task.trim()) throw new Error('Remote operation requires a task description');
     argv.push(task);
   }
-  for (const key of OPERATION_KEYS[operation]) {
+  const controls = ['route', 'coordinate'].includes(operation) ? ['goal', 'maxTurns', 'maxBudgetUsd', 'maxTokens', 'approvalPolicy', 'questionTimeoutMs', 'resultSchema'] : [];
+  for (const key of [...OPERATION_KEYS[operation], ...controls]) {
     if (BOOLEAN_FLAGS[key]) { if (options[key] === true) argv.push(BOOLEAN_FLAGS[key]); }
     else if (options[key] !== undefined && options[key] !== null) {
+      if (['maxTurns', 'maxBudgetUsd', 'maxTokens', 'questionTimeoutMs'].includes(key)) { argv.push(VALUE_FLAGS[key], String(options[key])); continue; }
+      if (key === 'resultSchema' && typeof options[key] !== 'string') { argv.push('--result-schema-json', JSON.stringify(options[key])); continue; }
       if (typeof options[key] !== 'string' || !options[key] || /\0/.test(options[key])) throw new Error(`Invalid remote ${key}`);
       argv.push(VALUE_FLAGS[key], options[key]);
     }
@@ -60,7 +64,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/review.mjs

@@ -1,5 +1,5 @@
 /**
- * Meta Harness Universal Cross-Model Adversarial Code Review Engine
+ * Metaharness Universal Cross-Model Adversarial Code Review Engine
  *
  * Runs automated code reviews across integrated agent platforms (claude, codex, agy,
  * grok, dsh, hermes, etc.).
@@ -19,6 +19,7 @@ import { resolvePool, localExecutionNode } from './pool.mjs';
 import { lastJsonWith } from './json-reply.mjs';
 import { createWorktree, removeWorktree, commitAll, headCommit } from './worktree.mjs';
 import { forwardRemoteOperation } from './remote-operation.mjs';
+import { recordReview } from './reviews.mjs';
 
 const MAX_DIFF = 30000;
 // Generated surfaces say nothing a reviewer can act on, and they crowd out the source.
@@ -129,11 +130,13 @@ export function buildReviewPrompt(diff, context = {}) {
 You are an independent, highly critical senior security and architecture engineer performing an adversarial code review.
 You did NOT write this code. Do not rubber-stamp. Look for vulnerabilities, silent failures, regressions, anti-patterns, and test coverage gaps.
 
-${task}${branch}${context.stat ? `Files changed:\n${context.stat}\n\n` : ''}${context.untracked?.length ? `New untracked files, not in the diff; read them too:\n${context.untracked.slice(0, 100).join('\n')}\n\n` : ''}${diff.length > MAX_DIFF ? `This diff is cut at ${MAX_DIFF} of ${diff.length} characters. Read the remainder from the repository and say so if you could not.\n` : ''}GIT DIFF TO REVIEW:
+${task}${branch}${context.evidence ? `Job evidence (recorded by Metaharness, not by the author):\n${JSON.stringify(context.evidence, null, 2).slice(0, 8000)}\n\n` : ''}${context.stat ? `Files changed:\n${context.stat}\n\n` : ''}${context.untracked?.length ? `New untracked files, not in the diff; read them too:\n${context.untracked.slice(0, 100).join('\n')}\n\n` : ''}${diff.length > MAX_DIFF ? `This diff is cut at ${MAX_DIFF} of ${diff.length} characters. Read the remainder from the repository and say so if you could not.\n` : ''}GIT DIFF TO REVIEW:
 \`\`\`diff
 ${diff.slice(0, MAX_DIFF)}
 \`\`\`
 
+Judge the diff. Use the job evidence for claims about how the job ran (questions asked, replies, the goal check, the gate). A claim you cannot verify from the diff or the evidence is a "suggestion" marked unverified in its issue text; it is never "critical" or blocking. Mark a finding "critical" only for a defect in the diff itself.
+
 Evaluate the diff against these strict criteria:
 1. Security & Blast Radius (privilege escalation, token leakage, unhandled exceptions)
 2. Invariant & Rule Adherence (does it break existing contracts or introduce silent side effects?)
@@ -166,14 +169,39 @@ export function parseReviewVerdict(response) {
   return { verdict: 'NEEDS_DISCUSSION', parsed: false, riskScore: null, summary: text.slice(0, 300) || 'The reviewer returned nothing readable.', findings: [] };
 }
 
+export function reviewBlocksPush(result) {
+  if (result?.ok !== true) return true;
+  if (result.verdict === 'NO_DIFF') return false;
+  const review = result.review;
+  // R45.8: only blocking findings stop the push; other findings go to the job result.
+  // An unreadable review cannot clear a push, so it blocks.
+  return !review || review.parsed === false ||
+    review.findings?.some(f => f.blocking === true || ['blocking', 'critical'].includes(f.severity)) === true;
+}
+
 export async function executeCodeReview(options = {}) {
   const remote = await forwardRemoteOperation('review', null, options);
   if (remote) return remote;
   localExecutionNode(options);
+  const selection = { workspace: options.cwd || process.cwd(), target: options.target || (options.staged ? '--staged' : 'working tree'), reviewer: options.reviewer || null };
+  let result;
+  try { result = await executeLocalReview(options, selection); }
+  catch (error) {
+    // Preserve the existing CLI error contract, but retain failed attempts too.
+    try { recordReview({ ok: false, error: error.message }, selection); }
+    catch (storeError) { throw new Error(`${error.message}; review store failed: ${storeError.message}`); }
+    throw error;
+  }
+  try { return { ...result, reviewId: recordReview(result, selection).id }; }
+  catch (error) { return { ...result, ok: false, reviewStoreError: error.message }; }
+}
+
+async function executeLocalReview(options, selection) {
   const cwd = options.cwd || process.cwd();
   const author = options.author || null;
   const diffResult = extractGitDiff({ cwd, target: options.target, staged: options.staged });
   if (!diffResult.ok) throw new Error(`Failed to read the diff: ${diffResult.error}`);
+  Object.assign(selection, { diff: diffResult.diff, untracked: diffResult.untracked, target: diffResult.target, commit: headCommit(cwd) });
   if (!diffResult.diff && !diffResult.untracked?.length) return { ok: true, verdict: 'NO_DIFF', target: diffResult.target, summary: `Nothing to review for ${diffResult.target}.` };
 
   const { ready, excluded } = await resolvePool(options);
@@ -184,13 +212,16 @@ export async function executeCodeReview(options = {}) {
   const reviewerFamily = ADAPTER_CATALOG[reviewer.id]?.family || reviewer.family || null;
   if (author && (reviewer.id === author || (authorFamily && authorFamily === reviewerFamily))) throw new Error(`${reviewer.id} shares a model family with the author ${author}, so it cannot review this independently`);
   const independence = author ? 'verified' : 'unverified: the author was not named';
+  selection.reviewer = reviewer.id;
   const truncated = diffResult.diff.length > MAX_DIFF;
   const snapshot = reviewSnapshot(cwd, diffResult);
+  selection.commit = snapshot.commit;
   let result;
   try { result = await dispatchWithReceipt({
     agent: reviewer.id, node: 'local', cwd: snapshot.directory, contextCwd: cwd, contextTask: options.task || `Review the code changes in ${diffResult.target}`,
-    prompt: buildReviewPrompt(diffResult.diff, { task: options.task, branch: options.branch || diffResult.target, stat: diffResult.stat, untracked: diffResult.untracked }),
+    prompt: buildReviewPrompt(diffResult.diff, { task: options.task, evidence: options.evidence, branch: options.branch || diffResult.target, stat: diffResult.stat, untracked: diffResult.untracked }),
     permissions: { read: true, write: false }, allowUnknownAuth: options.allowUnknownAuth === true,
+    ...(reviewer.id === 'codex' ? { reviewTarget: { type: 'custom', instructions: buildReviewPrompt(diffResult.diff, { task: options.task, evidence: options.evidence, branch: diffResult.target }) } } : {}),
   }, { dispatchFn: options.dispatchFn, role: 'Reviewer' }); }
   finally { removeWorktree(cwd, snapshot.directory); }
   if (!result.ok) return { ok: false, target: diffResult.target, reviewer: reviewer.id, error: result.error, failureKind: result.failureKind, excluded };

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

@@ -0,0 +1,25 @@
+/** Review results are append-only SSSS records, independent of thread lifetime. */
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { threadsFile } from './paths.mjs';
+import { PluginStateStore } from './ssss-store.mjs';
+
+const store = () => new PluginStateStore(path.join(path.dirname(threadsFile()), 'meta-harness-reviews.jsonl'), 'meta-harness');
+const dispositions = { APPROVE: 'approved', REQUEST_CHANGES: 'changes_requested', NEEDS_DISCUSSION: 'needs_discussion', NO_DIFF: 'no_diff', FAILED: 'failed' };
+
+export function readReviews() { return store().read([]); }
+export function recordReview(result, selection = {}) {
+  const review = result.review;
+  const verdict = review?.verdict || result.verdict || 'FAILED';
+  if (!dispositions[verdict]) throw new Error('Invalid review verdict');
+  const entry = {
+    id: `review-${crypto.randomUUID()}`, timestamp: new Date().toISOString(),
+    workspace: selection.workspace, target: review?.target || result.target || selection.target || null,
+    commit: review?.snapshotCommit || selection.commit || null,
+    diff: selection.diff || '', untracked: selection.untracked || [],
+    reviewer: review?.reviewer || result.reviewer || selection.reviewer || null,
+    verdict, disposition: dispositions[verdict], result,
+  };
+  store().append(entry);
+  return entry;
+}