total-recall-brain 3.41.6 → 3.42.0

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

@@ -6,20 +6,26 @@ import { evaluateGateCascade } from '../capability/index.mjs';
 import { dispatchWithReceipt } from './dispatch.mjs';
 import { notifyAlert } from './alerts.mjs';
 import { recordRunReceipt } from './learner.mjs';
-import { resolvePool } from './pool.mjs';
+import { resolvePool, localExecutionNode } from './pool.mjs';
 import { routeTask } from './router.mjs';
 import { runQualityGate } from './gate.mjs';
 import { isGitRepo, createWorktree, removeWorktree, commitAll, linkDependencies, deleteBranch } from './worktree.mjs';
+import { forwardRemoteOperation } from './remote-operation.mjs';
 
 export async function executeRoutedTask(task, options = {}) {
+  const remote = await forwardRemoteOperation('route', task, { ...options, execute: true });
+  if (remote) return remote;
+  if (options.node) localExecutionNode(options);
   const cwd = options.cwd || process.cwd();
   if (!isGitRepo(cwd)) throw new Error('Routed execution writes on its own branch, so it must run inside a git repository');
   const route = options.route || await routeTask(task, options);
   if (!route.selected) return { ok: false, route, attempts: [], error: 'No harness can take this task right now.' };
+  const node = localExecutionNode(options, route.placement);
   const pool = options.pool || (await resolvePool(options)).ready.map(h => h.id);
   const maxAttempts = options.maxAttempts || 3;
   const id = `route-${Date.now().toString(36)}`;
   const attempts = [];
+  const alerts = [];
   const tried = new Set();
   let harness = route.selected, diagnostic = null, previous = null;
 
@@ -31,23 +37,30 @@ export async function executeRoutedTask(task, options = {}) {
     attempts.push(attempt);
     try {
       const prompt = `Work only in this checkout. Do not commit; the harness commits your changes.\nTask:\n${task}${diagnostic ? `\n\nA previous attempt by ${previous} failed. Diagnostic:\n${diagnostic}` : ''}`;
-      const result = await dispatchWithReceipt({ agent: harness, cwd: directory, contextCwd: cwd, contextTask: task, prompt, permissions: { read: true, write: true }, allowUnknownAuth: true }, { dispatchFn: options.dispatchFn, role: 'Routed', complexityScore: route.complexity?.score, escalatedFrom: previous });
+      const result = await dispatchWithReceipt({ agent: harness, node, cwd: directory, contextCwd: cwd, contextTask: task, prompt, permissions: { read: true, write: true }, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Routed', complexityScore: route.complexity?.score, escalatedFrom: previous });
       attempt.ok = result.ok === true;
       attempt.durationMs = result.durationMs;
       attempt.output = result.response || null;
       if (result.ok) {
         attempt.commit = commitAll(directory, `meta-harness: ${task.slice(0, 60)}\n\nAgent: ${harness}`);
         if (attempt.commit) attempt.branch = branch;
-        else { attempt.ok = false; attempt.error = 'The agent reported success but changed no files.'; }
+        else {
+          attempt.ok = false; attempt.error = 'The agent reported success but changed no files.';
+          await recordRunReceipt({ harness, role: 'Implementer', task, success: false, failureKind: 'no-change', error: attempt.error });
+        }
       } else {
         attempt.error = result.error;
         attempt.failureKind = result.failureKind;
       }
       if (attempt.ok && options.gate) {
         linkDependencies(cwd, directory);
-        attempt.gate = (options.gateFn || runQualityGate)(directory, options.gateOptions);
+        attempt.gate = await (options.gateFn || runQualityGate)(directory, options.gateOptions);
         // A gate that could not run says nothing about this agent's work, so it does not escalate.
-        if (['unavailable', 'unconfigured'].includes(attempt.gate.status)) return { ok: false, route, attempts, error: `The quality gate is ${attempt.gate.status}: ${attempt.gate.summary}` };
+        if (['unavailable', 'unconfigured'].includes(attempt.gate.status)) {
+          attempt.ok = false;
+          attempt.error = `The quality gate is ${attempt.gate.status}: ${attempt.gate.summary}`;
+          return { ok: false, route, attempts, error: attempt.error };
+        }
         await recordRunReceipt({ harness, role: 'Gate', task, success: attempt.gate.passed, failureKind: attempt.gate.passed ? null : 'gate', error: attempt.gate.passed ? null : attempt.gate.summary, gate: attempt.gate.status });
         attempt.ok = attempt.gate.passed;
       }
@@ -60,14 +73,14 @@ export async function executeRoutedTask(task, options = {}) {
       if (!attempt.ok) { deleteBranch(cwd, branch); attempt.branch = null; }
     }
 
-    if (attempt.ok) return { ok: true, route, gateApplied: Boolean(options.gate), branch: attempt.branch, commit: attempt.commit, harness, attempts };
+    if (attempt.ok) return { ok: true, route, gateApplied: Boolean(options.gate), branch: attempt.branch, commit: attempt.commit, harness, attempts, alerts };
 
     const remaining = pool.filter(item => !tried.has(item));
     const next = remaining.length ? evaluateGateCascade(harness, { testsPassed: false }, remaining) : null;
     diagnostic = attempt.gate?.summary || attempt.error || 'The previous attempt failed.';
     previous = harness;
     harness = next?.recommendedHarness && !tried.has(next.recommendedHarness) ? next.recommendedHarness : null;
-    if (harness) await notifyAlert({ title: 'Meta Harness: escalating', message: `${previous} failed on "${task.slice(0, 60)}"; escalating to ${harness}.`, severity: 'warning' });
+    if (harness) alerts.push(await notifyAlert({ title: 'Meta Harness: escalating', message: `${previous} failed on "${task.slice(0, 60)}"; escalating to ${harness}.`, severity: 'warning' }));
   }
-  return { ok: false, route, gateApplied: Boolean(options.gate), attempts, error: 'No attempt passed.' };
+  return { ok: false, route, gateApplied: Boolean(options.gate), attempts, alerts, error: 'No attempt passed.' };
 }

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

@@ -0,0 +1,110 @@
+/** Compatibility interfaces for native hosts. All execution uses the plugin's common boundary. */
+import path from 'node:path';
+import { getActiveAdapters, findBinary, inspectAgents, agentEnvironment } from './worker.mjs';
+import { getInstalledVersion, getLatestVersion } from './tracker.mjs';
+
+export const HARNESS_SPECS = Object.fromEntries(getActiveAdapters().map(adapter => [adapter.id, {
+  ...adapter, defaultFlags: adapter.args, execType: adapter.input === 'stdin' ? 'pipe_stdin' : 'flag_last',
+  enforcement: 'advisory', enforcementEvidence: 'Use the measured preflight adapter report for enforcement evidence',
+}]));
+
+export function normalizeToolSelection(tools) {
+  if (tools === undefined || tools === null) return null;
+  const values = (Array.isArray(tools) ? tools : String(tools).split(',')).map(value => String(value).trim()).filter(Boolean);
+  if (!values.length || (values.length === 1 && values[0] === 'none')) return '';
+  if (values.length === 1 && ['all', 'default'].includes(values[0])) return null;
+  return values.join(',');
+}
+
+export function validateHarnessOptions(id, options = {}) {
+  const adapter = getActiveAdapters().find(item => item.id === id);
+  if (!adapter) throw new Error(`Unknown harness ID "${id}"`);
+  if ((normalizeToolSelection(options.tools) !== null || options.settingSources !== undefined) && id !== 'claude') {
+    throw new Error(`Harness "${adapter.name}" does not support choosing its tool set or --setting-sources`);
+  }
+  if (options.settingSources !== undefined && (typeof options.settingSources !== 'string' || !/^(user|project|local)(,(user|project|local))*$/.test(options.settingSources))) throw new Error('Invalid --setting-sources');
+  if (options.allowUnknownAuth !== undefined && typeof options.allowUnknownAuth !== 'boolean') throw new Error('allowUnknownAuth must be an explicit boolean');
+  return adapter;
+}
+
+/** Legacy inspection helper only; execution flags are built by worker.mjs. */
+export function buildHarnessArgs(spec, options = {}) {
+  const adapter = validateHarnessOptions(spec.id, options);
+  const args = [...adapter.args], extra = [];
+  const tools = normalizeToolSelection(options.tools);
+  if (tools !== null) extra.push('--tools', tools);
+  if (options.settingSources !== undefined) extra.push('--setting-sources', options.settingSources);
+  const promptFlag = args.at(-1) === '-p' ? args.pop() : null;
+  return [...args, ...extra, ...(promptFlag ? [promptFlag] : [])];
+}
+
+export const shellQuote = value => "'" + String(value).replaceAll("'", "'\\''") + "'";
+
+export function detectHarnesses() {
+  return getActiveAdapters().map(adapter => {
+    const binaryPath = findBinary(adapter.binary);
+    return { id: adapter.id, name: adapter.name, available: Boolean(binaryPath), binaryPath, description: adapter.docs, execType: adapter.input };
+  });
+}
+
+export async function detectHarnessesWithAuth(options = {}) {
+  const result = await (options.inspect || inspectAgents)(options);
+  return result.agents.map(agent => ({ ...agent, available: agent.installed, authed: agent.authenticated === true && !agent.blockedBy, authRoute: agent.authenticated === 'unknown' ? 'unknown' : agent.authenticated ? 'measured-login' : 'needs-auth' }));
+}
+
+/** Kept for callers preparing environments; only an adapter's declared credentials may be resolved. */
+export async function resolveHarnessEnv(spec, baseEnv = process.env, { readSecret } = {}) {
+  const adapter = validateHarnessOptions(spec.id);
+  const env = agentEnvironment(baseEnv);
+  if (!Object.keys(adapter.credentials || {}).length) return env;
+  if (!readSecret) {
+    const { runProcess } = await import('./worker.mjs');
+    const binary = findBinary(baseEnv.TOTAL_RECALL_BIN || 'total-recall', baseEnv);
+    if (!binary) throw new Error('Total Recall auth owner is unavailable');
+    readSecret = async key => {
+      const result = await runProcess(binary, ['auth', 'secret', 'get', key], { env: agentEnvironment(baseEnv) });
+      return result.exitCode === 0 ? result.stdout.trim() : null;
+    };
+  }
+  for (const [name, keys] of Object.entries(adapter.credentials)) {
+    for (const key of keys) { const value = await readSecret(key); if (value) { env[name] = value; break; } }
+    if (!env[name]) throw new Error(`Configure ${name} through auth before dispatch`);
+  }
+  return env;
+}
+
+export async function dispatchTask(id, prompt, options = {}, dependencies = {}) {
+  validateHarnessOptions(id, options);
+  const remote = options.node && options.node !== 'local';
+  if (remote && (typeof options.cwd !== 'string' || (!path.posix.isAbsolute(options.cwd) && !path.win32.isAbsolute(options.cwd)))) throw new Error('Choose an explicit absolute workspace on the remote node');
+  const { dispatchWithReceipt } = await import('./dispatch.mjs');
+  const result = await (dependencies.dispatch || dispatchWithReceipt)({
+    agent: id, cwd: remote ? options.cwd : path.resolve(options.cwd || process.cwd()), prompt,
+    node: options.node || 'local', permissions: { read: true, write: options.write === true },
+    allowUnknownAuth: options.allowUnknownAuth === true, timeoutMs: options.timeoutMs,
+    tools: options.tools, settingSources: options.settingSources, model: options.model,
+  }, { node: options.node || 'local', role: options.role || 'Dispatch' });
+  return { ...result, harnessId: id, harnessName: HARNESS_SPECS[id]?.name || id, success: result.ok === true };
+}
+
+export async function runCouncil(prompt, ids, options = {}) {
+  const { coordinateTask } = await import('./coordinator.mjs');
+  return coordinateTask(prompt, { ...options, mode: 'council', execute: true, ...(ids ? { availableHarnesses: ids } : {}) });
+}
+
+export const getInstalledHarnessVersion = id => getInstalledVersion(id) || 'unknown';
+export const getLatestHarnessVersion = (id, installed) => getLatestVersion(id, installed);
+
+export async function queryHarnessUsage(options = {}) {
+  const { inspectQuotas } = await import('./router.mjs');
+  const report = await (options.inspectQuotas || inspectQuotas)(options);
+  if (!report.ok) throw new Error(report.error || 'Harness usage is unavailable');
+  const remaining = value => typeof value === 'number' ? `${Math.max(0, 100 - value)}%` : '—';
+  return Object.entries(report.quotas || {}).filter(([id]) => !['system', 'metered'].includes(id)).map(([id, quota]) => ({
+    id, name: HARNESS_SPECS[id]?.name || id, available: quota.installed === true,
+    authed: quota.status === 'ready', authRoute: quota.status, status: quota.status,
+    version: quota.version || 'unknown', latestVersion: quota.latestVersion || null, isCurrent: quota.latestVersion ? quota.version === quota.latestVersion : null,
+    rolling5hRemainingPct: remaining(quota.rolling5hUsedPercent), weeklyRemainingPct: remaining(quota.weeklyUsedPercent),
+    quotaRemaining: quota.quotaNote || 'No usage source', enforcement: 'advisory', enforcementEvidence: null,
+  }));
+}

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

@@ -4,19 +4,33 @@
  * branch in its own worktree, and the Verifier inspects that exact commit from a different model
  * family. Nothing merges into the operator's branch; the branch is the deliverable.
  */
-import { ADAPTER_CATALOG, classifyTaskComplexity, synthesizeOneWayValve } from '../capability/index.mjs';
+import { recordRunReceipt } from './learner.mjs';
+import { classifyTaskComplexity, synthesizeOneWayValve } from '../capability/index.mjs';
 import { notifyAlert } from './alerts.mjs';
 import { dispatchWithReceipt } from './dispatch.mjs';
-import { resolvePool } from './pool.mjs';
+import { resolvePool, localExecutionNode } from './pool.mjs';
 import { createThread, appendThreadTurn, updateThread } from './threads.mjs';
 import { executeCodeReview } from './review.mjs';
 import { isGitRepo, isDirty, headCommit, createWorktree, removeWorktree, commitAll, diffBetween, linkDependencies, deleteBranch } from './worktree.mjs';
 import { lastJsonWith } from './json-reply.mjs';
 import { runQualityGate } from './gate.mjs';
+import { forwardRemoteOperation } from './remote-operation.mjs';
+
+const OPEN_THREADS = new Set();
+const MAX_BLUEPRINT = 20000;
+/** A stopped pipeline must not leave its thread reading as active. */
+export function failOpenThreads(summary = 'The run was stopped before it finished.') {
+  for (const id of OPEN_THREADS) { try { updateThread(id, { status: 'failed', summary }); } catch { /* the thread store reports its own failure */ } }
+  OPEN_THREADS.clear();
+}
 
 export function assignPipelineRoles(pool = [], options = {}) {
   const sorted = [...pool].sort((a, b) => b.qualityScore - a.qualityScore);
-  const findById = id => sorted.find(h => h.id === id) || (ADAPTER_CATALOG[id] ? { ...ADAPTER_CATALOG[id], id } : { id, name: id, family: 'custom' });
+  const findById = id => {
+    const harness = sorted.find(h => h.id === id);
+    if (!harness) throw new Error(`Selected harness ${id} is not ready for this task`);
+    return harness;
+  };
   // The session's own harness leads only when it can take work; TR_ACTIVE_HARNESS is advisory.
   const active = process.env.TR_ACTIVE_HARNESS;
   const orchestrator = options.orchestrator ? findById(options.orchestrator) : sorted.find(h => h.id === active) || sorted[0] || null;
@@ -78,13 +92,15 @@ async function runPipeline(task, poolInfo, options) {
 
   const verifier = roles.verifier || roles.implementer;
   const complexity = classifyTaskComplexity(task);
-  const thread = createThread({ title: task.slice(0, 80), task, platform: roles.orchestrator.id, model: roles.orchestrator.name, status: 'active' });
+  // Validate the repository before creating lifecycle state: an unborn repository has no usable base.
   const baseCommit = headCommit(cwd);
-  const branch = options.branch || `meta-harness/${thread.id}`;
   const warnings = isDirty(cwd) ? ['The working tree has uncommitted changes; the branch starts from the last commit and does not include them.'] : [];
+  const thread = createThread({ title: task.slice(0, 80), task, platform: roles.orchestrator.id, model: roles.orchestrator.name, status: 'active' });
+  OPEN_THREADS.add(thread.id);
+  const branch = options.branch || `meta-harness/${thread.id}`;
   const run = async (stage, harness, prompt, { workdir = cwd, permissions, role = stage.role } = {}) => {
     stage.status = 'running';
-    const result = await dispatchWithReceipt({ agent: harness.id, cwd: workdir, contextCwd: cwd, contextTask: task, prompt, permissions: permissions || stage.permissions, allowUnknownAuth: true }, { dispatchFn: options.dispatchFn, role, complexityScore: complexity.score });
+    const result = await dispatchWithReceipt({ agent: harness.id, node: 'local', cwd: workdir, contextCwd: cwd, contextTask: task, prompt, permissions: permissions || stage.permissions, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role, complexityScore: complexity.score });
     stage.status = result.ok ? 'completed' : 'failed';
     stage.output = result.response || result.error || null;
     stage.failureKind = result.ok ? undefined : result.failureKind;
@@ -104,13 +120,15 @@ async function runPipeline(task, poolInfo, options) {
     }
     const architect = await run(stage('Architect'), roles.architect, `[ROLE: ARCHITECT]\nDo not change any file. Task:\n${task}\n\nExplorer digest:\n${digest || 'None.'}\n\nProduce a concise blueprint, the files to change, and how to verify the result.`);
     if (!architect.ok) { ok = false; return finish(); }
+    const blueprint = architect.response.length > MAX_BLUEPRINT ? `${architect.response.slice(0, MAX_BLUEPRINT)}\n[Blueprint shortened to ${MAX_BLUEPRINT} characters.]` : architect.response;
 
     implementerDir = createWorktree(cwd, { branch });
-    const implementer = await run(stage('Implementer'), roles.implementer, `[ROLE: IMPLEMENTER]\nWork only in this checkout. Implement the task and its tests. Do not commit; the harness commits your changes.\nTask:\n${task}\n\nBlueprint:\n${architect.response}`, { workdir: implementerDir });
+    const implementer = await run(stage('Implementer'), roles.implementer, `[ROLE: IMPLEMENTER]\nWork only in this checkout. Implement the task and its tests. Do not commit; the harness commits your changes.\nTask:\n${task}\n\nBlueprint:\n${blueprint}`, { workdir: implementerDir });
     if (!implementer.ok) { ok = false; return finish(); }
     commit = commitAll(implementerDir, `meta-harness: ${task.slice(0, 60)}\n\nImplementer: ${roles.implementer.id}`);
     if (!commit) {
       Object.assign(stage('Implementer'), { status: 'failed', failureKind: 'agent', output: 'The Implementer reported success but changed no files.' });
+      await recordRunReceipt({ harness: roles.implementer.id, role: 'Implementer', task, success: false, failureKind: 'no-change', error: 'The Implementer reported success but changed no files.' });
       ok = false; return finish();
     }
     stage('Implementer').commit = commit;
@@ -118,21 +136,21 @@ async function runPipeline(task, poolInfo, options) {
 
     if (options.gate) {
       linkDependencies(cwd, implementerDir);
-      gate = runQualityGate(implementerDir, options.gateOptions);
+      gate = await (options.gateFn || runQualityGate)(implementerDir, options.gateOptions);
       if (!gate.passed) { ok = false; stage('Verifier').status = 'skipped'; stage('Verifier').output = `Quality gate did not pass: ${gate.summary}`; return finish(); }
     }
 
     const diff = diffBetween(cwd, baseCommit, commit);
     const verifyDir = createWorktree(cwd, { ref: commit, prefix: 'meta-harness-verify-' });
     try {
-      const verification = await run(stage('Verifier'), verifier, `[ROLE: INDEPENDENT VERIFIER]\nYou did not write this code. Do not change any file. Run the checks you can and audit commit ${commit} for this task:\n${task}\n\nBlueprint:\n${architect.response}\n\nDiff${diff.length > 30000 ? ' (first 30000 characters; read the rest from this checkout)' : ''}:\n${diff.slice(0, 30000)}\n\nEnd your reply with exactly one JSON object: {"verdict":"PASS"|"FAIL","findings":["..."]}`, { workdir: verifyDir });
+      const verification = await run(stage('Verifier'), verifier, `[ROLE: INDEPENDENT VERIFIER]\nYou did not write this code. Do not change any file. Run the checks you can and audit commit ${commit} for this task:\n${task}\n\nBlueprint:\n${blueprint}\n\nDiff${diff.length > 30000 ? ' (first 30000 characters; read the rest from this checkout)' : ''}:\n${diff.slice(0, 30000)}\n\nEnd your reply with exactly one JSON object: {"verdict":"PASS"|"FAIL","findings":["..."]}`, { workdir: verifyDir });
       const parsed = verification.ok ? parseVerification(verification.response) : { parsed: false, verdict: 'NOT_RUN', findings: [] };
       Object.assign(stage('Verifier'), { commit, verdict: parsed.verdict, findings: parsed.findings, passed: parsed.verdict === 'PASS' });
-      if (parsed.verdict !== 'PASS') ok = false;
+      if (parsed.verdict !== 'PASS') { ok = false; return finish(); }
     } finally { removeWorktree(cwd, verifyDir); }
 
     if (options.autoReview) {
-      const review = await executeCodeReview({ cwd, author: roles.implementer.id, threadId: thread.id, task, target: `${baseCommit}...${commit}`, dispatchFn: options.dispatchFn, reviewer: options.reviewer });
+      const review = await executeCodeReview({ cwd, author: roles.implementer.id, threadId: thread.id, task, target: `${baseCommit}...${commit}`, dispatchFn: options.dispatchFn, reviewer: options.reviewer, allowUnknownAuth: options.allowUnknownAuth === true, availableHarnesses: options.availableHarnesses });
       stages.push({ role: 'Reviewer', harness: review.review?.reviewer || null, status: review.ok ? 'completed' : 'failed', verdict: review.review?.verdict || null, riskScore: review.review?.riskScore ?? null, output: review.review?.summary || review.error || null });
       if (!review.ok || review.review?.verdict !== 'APPROVE') ok = false;
     }
@@ -145,14 +163,16 @@ async function runPipeline(task, poolInfo, options) {
     return finish();
   } finally {
     removeWorktree(cwd, implementerDir);
-    if (implementerDir && !commit) deleteBranch(cwd, branch);
+    if (implementerDir && (!commit || !ok)) deleteBranch(cwd, branch);
   }
 
   function finish() {
     return (async () => {
-      updateThread(thread.id, { status: ok ? 'completed' : 'failed', ...(commit ? { branch } : {}) });
+      for (const item of stages) if (item.status === 'planned') item.status = 'skipped';
+      OPEN_THREADS.delete(thread.id);
+      updateThread(thread.id, { status: ok ? 'completed' : 'failed', branch: ok && commit ? branch : null, commit, baseCommit });
       const alert = await notifyAlert({ title: ok ? 'Meta Harness: pipeline passed' : 'Meta Harness: pipeline failed', message: `${task.slice(0, 80)}${commit ? ` (branch ${branch})` : ''}`, severity: ok ? 'info' : 'warning' });
-      return { ...base, ok, threadId: thread.id, branch: commit ? branch : null, commit, baseCommit, gate, warnings, durationMs: Date.now() - started, alert };
+      return { ...base, ok, threadId: thread.id, branch: ok && commit ? branch : null, commit, baseCommit, gate, warnings, durationMs: Date.now() - started, alert };
     })();
   }
 }
@@ -165,7 +185,7 @@ async function runCouncil(task, poolInfo, options) {
   if (!seats.length) throw new Error('No harness can take work right now');
   const cwd = options.cwd || process.cwd();
   const votes = await Promise.all(seats.map(async harness => {
-    const result = await dispatchWithReceipt({ agent: harness, cwd, contextTask: task, prompt: `[ROLE: COUNCIL MEMBER]\nDo not change any file. Assess this proposal, with its trade-offs and risks:\n${task}\n\nEnd your reply with exactly one JSON object: {"vote":"APPROVE"|"REJECT","reason":"..."}`, permissions: READ, allowUnknownAuth: true }, { dispatchFn: options.dispatchFn, role: 'Council' });
+    const result = await dispatchWithReceipt({ agent: harness, node: 'local', cwd, contextTask: task, prompt: `[ROLE: COUNCIL MEMBER]\nDo not change any file. Assess this proposal, with its trade-offs and risks:\n${task}\n\nEnd your reply with exactly one JSON object: {"vote":"APPROVE"|"REJECT","reason":"..."}`, permissions: READ, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Council' });
     return { harness, ok: result.ok === true, ...(result.ok ? parseVote(result.response) : { vote: 'ABSTAIN', reason: null, error: result.error }), feedback: result.response || null };
   }));
   const count = vote => votes.filter(item => item.vote === vote).length;
@@ -178,20 +198,23 @@ async function runRace(task, poolInfo, options) {
   const seats = options.candidates || [...poolInfo.ready].sort((a, b) => b.qualityScore - a.qualityScore).slice(0, 2).map(h => h.id);
   if (options.execute !== true) return { ok: seats.length > 1, mode: 'race', task, executedLive: false, excluded: poolInfo.excluded, candidates: seats.map(harness => ({ harness, status: 'planned' })) };
   if (seats.length < 2) throw new Error('A race needs at least two harnesses that can take work');
+  if (!options.gate) return { ok: false, mode: 'race', task, executedLive: false, verification: 'unverified', gateApplied: false, error: 'A race requires a deterministic quality gate before any candidate can win.' };
   const cwd = options.cwd || process.cwd();
   if (!isGitRepo(cwd)) throw new Error('A race writes on separate branches, so it must run inside a git repository');
   const id = `race-${Date.now().toString(36)}`;
   const entries = await Promise.all(seats.map(async harness => {
     const branch = `meta-harness/${id}-${harness}`;
-    const directory = createWorktree(cwd, { branch });
+    let directory;
     let keep = false;
     try {
-      const result = await dispatchWithReceipt({ agent: harness, cwd: directory, contextCwd: cwd, contextTask: task, prompt: `[ROLE: IMPLEMENTER]\nWork only in this checkout. Implement the task and its tests. Do not commit.\nTask:\n${task}`, permissions: WRITE, allowUnknownAuth: true }, { dispatchFn: options.dispatchFn, role: 'Race' });
+      const started = Date.now();
+      directory = createWorktree(cwd, { branch });
+      const result = await dispatchWithReceipt({ agent: harness, node: 'local', cwd: directory, contextCwd: cwd, contextTask: task, prompt: `[ROLE: IMPLEMENTER]\nWork only in this checkout. Implement the task and its tests. Do not commit.\nTask:\n${task}`, permissions: WRITE, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Race' });
       const commit = result.ok ? commitAll(directory, `meta-harness race: ${task.slice(0, 60)}\n\nAgent: ${harness}`) : null;
       if (commit && options.gate) linkDependencies(cwd, directory);
-      const gate = commit && options.gate ? runQualityGate(directory, options.gateOptions) : null;
-      keep = Boolean(commit) && (!gate || gate.passed);
-      return { harness, branch: keep ? branch : null, commit: keep ? commit : null, ok: keep, gate, durationMs: result.durationMs, error: result.ok ? (commit ? (keep ? undefined : 'The quality gate failed') : 'No files changed') : result.error };
+      const gate = commit ? await (options.gateFn || runQualityGate)(directory, options.gateOptions) : null;
+      keep = Boolean(commit) && gate?.passed === true;
+      return { harness, branch: keep ? branch : null, commit: keep ? commit : null, ok: keep, gate, completedAt: Date.now(), durationMs: Date.now() - started, error: result.ok ? (commit ? (keep ? undefined : 'The quality gate failed') : 'No files changed') : result.error };
     } catch (error) {
       return { harness, branch: null, commit: null, ok: false, gate: null, durationMs: null, error: String(error.message) };
     } finally {
@@ -199,15 +222,18 @@ async function runRace(task, poolInfo, options) {
       if (!keep) deleteBranch(cwd, branch);
     }
   }));
-  const finishers = entries.filter(entry => entry.ok).sort((a, b) => a.durationMs - b.durationMs);
-  return { ok: finishers.length > 0, mode: 'race', task, executedLive: true, gateApplied: Boolean(options.gate), winner: finishers[0]?.harness || null, excluded: poolInfo.excluded, candidates: entries };
+  const finishers = entries.filter(entry => entry.ok).sort((a, b) => a.completedAt - b.completedAt);
+  return { ok: finishers.length > 0, mode: 'race', task, executedLive: true, gateApplied: true, verification: finishers.length ? 'passed' : 'failed', winner: finishers[0]?.harness || null, excluded: poolInfo.excluded, candidates: entries };
 }
 
 export async function coordinateTask(taskDescription, options = {}) {
   const task = String(taskDescription || '').trim();
   if (!task) throw new Error('Task description is required for coordination');
+  const remote = await forwardRemoteOperation('coordinate', task, options);
+  if (remote) return remote;
   const mode = options.mode || 'pipeline';
   if (!['pipeline', 'orchestrate', 'council', 'race'].includes(mode)) throw new Error(`Unsupported coordination mode: ${mode}`);
+  localExecutionNode(options);
   const poolInfo = await resolvePool(options);
   if (mode === 'council') return runCouncil(task, poolInfo, options);
   if (mode === 'race') return runRace(task, poolInfo, options);

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

@@ -4,7 +4,7 @@ import { classifyFailure, READ_ONLY_ADAPTERS } from './worker.mjs';
 import { recordRunReceipt } from './learner.mjs';
 import { isGitRepo, createWorktree, removeWorktree } from './worktree.mjs';
 
-export async function dispatchWithReceipt(request, { dispatchFn, node = request.node || 'local', role, complexityScore, escalatedFrom } = {}) {
+export async function dispatchWithReceipt(request, { dispatchFn, node = request.node || 'local', role, complexityScore, escalatedFrom, record = recordRunReceipt } = {}) {
   const started = Date.now();
   // A harness that cannot be told not to write does read-only work in a checkout that is thrown away.
   const contain = node === 'local' && request.permissions?.write !== true && !READ_ONLY_ADAPTERS.includes(request.agent) && request.isolated !== true && isGitRepo(request.cwd);
@@ -24,10 +24,15 @@ export async function dispatchWithReceipt(request, { dispatchFn, node = request.
     if (scratch) removeWorktree(request.cwd, scratch);
   }
   const durationMs = Date.now() - started;
-  await recordRunReceipt({
+  // A finished run keeps its result: the worktree and any cost are real even when bookkeeping fails.
+  let receiptError;
+  try {
+    await record({
     harness: request.agent, role, node, task: request.contextTask || request.prompt, complexityScore,
+    model: result.model ?? null, exitCode: result.exitCode ?? null, finishedReason: result.finishedReason ?? null,
     success: result.ok === true, durationMs, failureKind: result.ok ? null : result.failureKind || 'agent',
     error: result.ok ? null : result.error, resetsAt: result.resetsAt, escalatedFrom,
-  });
-  return { ...result, durationMs };
+    });
+  } catch (error) { receiptError = String(error?.message || error); }
+  return { ...result, durationMs, ...(receiptError ? { receiptError } : {}) };
 }

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

@@ -3,6 +3,7 @@ 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';
 
 export const DOC_SOURCES = [
   { id: 'claude', index: 'https://code.claude.com/docs/llms.txt', prefix: 'https://code.claude.com/docs/', catalog:true },
@@ -19,12 +20,22 @@ export const DOC_SOURCES = [
   { id: 'cline', index: 'https://docs.cline.bot/llms.txt', prefix: 'https://docs.cline.bot/', catalog:true },
   { id: 'openclaw', index: 'https://docs.openclaw.ai/llms.txt', prefix: 'https://docs.openclaw.ai/', catalog:true },
   { id: 'aider', index: 'https://aider.chat/docs/', prefix: 'https://aider.chat/docs/' },
-  { id: 'goose', index: 'https://block.github.io/goose/docs/quickstart', prefix: 'https://block.github.io/goose/docs/' },
+  { id: 'goose', index: 'https://goose-docs.ai/llms.txt', prefix: 'https://goose-docs.ai/', catalog:true },
   { id: 'openhands', index: 'https://docs.openhands.dev/llms.txt', prefix: 'https://docs.openhands.dev/', catalog:true },
   { id: 'replit', index: 'https://docs.replit.com/llms.txt', prefix: 'https://docs.replit.com/', catalog:true },
   { id: 'lovable', index: 'https://docs.lovable.dev/llms.txt', prefix: 'https://docs.lovable.dev/', catalog:true },
   { id: 'ollama', index: 'https://docs.ollama.com/llms.txt', prefix: 'https://docs.ollama.com/', catalog:true },
 ];
+function sourcesFor(agent) {
+  const sources = new Map(DOC_SOURCES.map(source => [source.id, source]));
+  for (const adapter of loadCustomAdapters()) if (adapter.docs) {
+    const url = new URL(adapter.docs);
+    sources.set(adapter.id, { id: adapter.id, index: url.href, prefix: new URL('.', url).href, origin: url.hostname });
+  }
+  const selected = agent ? [sources.get(agent)].filter(Boolean) : [...sources.values()];
+  if (!selected.length) throw new Error('Unknown documentation adapter or missing declared documentation URL');
+  return selected;
+}
 const hash = value => crypto.createHash('sha256').update(value).digest('hex');
 const TTL = 24 * 60 * 60 * 1000;
 function pageFile(directory,id,file){if(!/^[a-f0-9]{64}-[a-f0-9]{64}\.txt$/.test(file || ''))throw new Error('Invalid cached documentation filename');return path.join(directory,id,file);}
@@ -39,11 +50,11 @@ export function documentationDirectory() {
 }
 function metadata(directory, id) { try { return JSON.parse(fs.readFileSync(path.join(directory,id,'index.json'),'utf8')); } catch { return null; } }
 export function documentationStatus({ directory = documentationDirectory(), agent, now = Date.now() } = {}) {
-  const sources = agent ? DOC_SOURCES.filter(source => source.id === agent) : DOC_SOURCES;
+  const sources = sourcesFor(agent);
   if (!sources.length) throw new Error('Unknown documentation adapter');
   const agents = sources.map(source => {
     const saved = metadata(directory,source.id);
-    const complete = saved?.complete === true && saved.pages?.length > 0 && saved.pages.every(page => {
+    const complete = saved?.complete === true && saved.pages?.some(page => page.url === source.index) && saved.pages.every(page => {
       try { return hash(fs.readFileSync(pageFile(directory,source.id,page.file))) === page.sha256; } catch { return false; }
     });
     const age=now-Date.parse(saved?.checkedAt);
@@ -52,9 +63,10 @@ export function documentationStatus({ directory = documentationDirectory(), agen
   });
   return { ok:agents.every(row=>row.fresh), directory, agents };
 }
-async function download(url, fetchImpl) {
-  const allowed = new Set(['code.claude.com','claude.com','platform.claude.com','docs.anthropic.com','anthropic.com','developers.openai.com','openai.com','help.openai.com','learn.chatgpt.com','chatgpt.com','antigravity.google','cursor.com','docs.x.ai','dev.meta.ai','docs.devin.ai','docs.windsurf.com','windsurf.com','docs.cline.bot','docs.openclaw.ai','aider.chat','docs.replit.com','docs.lovable.dev','docs.ollama.com','block.github.io','docs.openhands.dev','raw.githubusercontent.com','api.github.com']);
+async function download(url, fetchImpl, declaredOrigin) {
+  const allowed = new Set(['code.claude.com','claude.com','platform.claude.com','docs.anthropic.com','anthropic.com','developers.openai.com','openai.com','help.openai.com','learn.chatgpt.com','chatgpt.com','antigravity.google','cursor.com','docs.x.ai','dev.meta.ai','docs.devin.ai','docs.windsurf.com','windsurf.com','docs.cline.bot','docs.openclaw.ai','aider.chat','docs.replit.com','docs.lovable.dev','docs.ollama.com','goose-docs.ai','block.github.io','docs.openhands.dev','raw.githubusercontent.com','api.github.com']);
   let target = new URL(url);
+  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':'*/*'}});
@@ -80,7 +92,7 @@ function links(text,base,prefix) {
     .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 } = {}) {
-  const sources=agent?DOC_SOURCES.filter(source=>source.id===agent):DOC_SOURCES;
+  const sources=sourcesFor(agent);
   if(!sources.length)throw new Error('Unknown documentation adapter');
   const reports=[];
   for(const source of sources) {
@@ -98,7 +110,7 @@ export async function refreshDocumentation({ directory = documentationDirectory(
         const batch=[];
         while(queue.length && batch.length<4){const url=queue.shift();if(!seen.has(url)){seen.add(url);batch.push(url);}}
         if(seen.size>maxPages)throw new Error('Official documentation exceeds configured page budget');
-        const downloads=await Promise.allSettled(batch.map(async url=>({url,text:await download(url,fetchImpl)})));
+        const downloads=await Promise.allSettled(batch.map(async url=>({url,text:await download(url,fetchImpl,source.origin)})));
         for(let index=0;index<downloads.length;index++) {
           const result=downloads[index];
           if(result.status==='rejected'){
@@ -152,7 +164,7 @@ export async function maintainDocumentation(options={}) {
 }
 
 export function readDocumentation({agent,url,directory=documentationDirectory()}) {
-  if(!DOC_SOURCES.some(source=>source.id===agent))throw new Error('Unknown documentation adapter');
+  sourcesFor(agent);
   const index=metadata(directory,agent);
   if(!url)return {agent,pages:index?.pages?.map(page=>({url:page.url,sha256:page.sha256,bytes:page.bytes})) || []};
   const page=index?.pages?.find(page=>page.url===url);
@@ -164,7 +176,7 @@ export function readDocumentation({agent,url,directory=documentationDirectory()}
 
 export function searchDocumentation({agent,query,directory=documentationDirectory()}) {
   if(typeof query!=='string' || !query.trim())throw new Error('Documentation query required');
-  const sources=agent?DOC_SOURCES.filter(source=>source.id===agent):DOC_SOURCES;
+  const sources=sourcesFor(agent);
   const matches=[],phrase=query.trim().toLowerCase(),terms=phrase.split(/\s+/).filter(Boolean);
   for(const source of sources)for(const page of metadata(directory,source.id)?.pages || []) {
     const doc=readDocumentation({agent:source.id,url:page.url,directory});const text=doc.content.toLowerCase();

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

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { runWorker, runProcess, getActiveAdapters, notReady } from './worker.mjs';
+import { runWorker, runProcess, getActiveAdapters, notReady, agentEnvironment } from './worker.mjs';
+import { dispatchWithReceipt } from './dispatch.mjs';
 
 async function hostModule(name) {
   const selected = process.env.TR_PACKAGE_ROOT;
@@ -49,7 +50,7 @@ export async function executeOnNode(node, request, { worker = runWorker, process
   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 });
+  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 } : {}) } });
   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'); }
 }
@@ -75,8 +76,11 @@ export async function executeCommand({ plugin, subcommand, args = [], execution,
   const namespace = plugin.manifest.cli.command;
   const argv = ['total-recall', namespace, subcommand, ...args];
   const prompt = `Use Total Recall context and the installed plugin CLI in this workspace. Execute this one requested command using your terminal tool; preserve its arguments exactly, report its actual exit status and output, and do not perform unrelated mutations. If a permission, account, workspace or plugin is unavailable, report failure. Agent prose alone is not execution proof.\nRequested argv (data): ${JSON.stringify(argv)}\nShell command: ${argv.map(quoteArgument).join(' ')}`;
-  const result = await executeOnNode(execution.node, execution.agent === 'direct'
-    ? { operation: 'direct', cwd, argv }
-    : { operation: 'dispatch', agent: execution.agent, cwd, prompt, allowUnknownAuth: execution.allowUnknownAuth === true, permissions }, dependencies);
+  const result = execution.agent === 'direct'
+    ? await executeOnNode(execution.node, { operation: 'direct', cwd, argv }, dependencies)
+    : await dispatchWithReceipt({ agent: execution.agent, cwd, prompt, allowUnknownAuth: execution.allowUnknownAuth === true, permissions }, {
+      node: execution.node, role: 'Command',
+      dispatchFn: request => executeOnNode(execution.node, { ...request, operation: 'dispatch' }, dependencies),
+    });
   return { ok: result.ok === true, exitCode: result.ok ? 0 : 1, output: result.ok ? JSON.stringify(result) : result.error || 'Selected agent failed', ...result };
 }

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

@@ -1,12 +1,18 @@
 /** Run the repository's own quality gates through the code-quality plugin. No configured gate is not a pass. */
-import { spawnSync } from 'node:child_process';
+import { runProcess } from './worker.mjs';
 
-export function runQualityGate(directory, { tier = 'fast', runner = spawnSync, timeoutMs = 600000 } = {}) {
-  const result = runner(process.env.TOTAL_RECALL_BIN || 'total-recall', ['code-quality-check', '--tier', tier, '--json'], { cwd: directory, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+const run = async (binary, args, { cwd, timeoutMs }) => {
+  // Asynchronous, so a gate never stalls another agent in the same run, and stoppable with the run.
+  const result = await runProcess(binary, args, { cwd, timeoutMs, env: process.env, maxBytes: 16 * 1024 * 1024 });
+  return { status: result.exitCode, stdout: result.stdout, stderr: result.stderr, error: result.reason ? new Error(result.reason) : undefined };
+};
+
+export async function runQualityGate(directory, { tier = 'fast', runner = run, timeoutMs = 600000 } = {}) {
+  const result = await runner(process.env.TOTAL_RECALL_BIN || 'total-recall', ['code-quality-check', '--tier', tier, '--json'], { cwd: directory, timeoutMs });
   const output = `${result.stdout || ''}\n${result.stderr || ''}`.trim();
   if (result.error || result.status === null) return { status: 'unavailable', passed: false, tier, summary: `The gate did not run: ${result.error?.message || 'terminated'}` };
   let report = null;
   try { report = JSON.parse(result.stdout); } catch { /* a text report */ }
-  if (/No code-quality state/.test(report?.error || output)) return { status: 'unconfigured', passed: false, tier, summary: String(report?.error || output).slice(0, 500) };
+  if (/No code-quality state|No checks at tier/.test(output)) return { status: 'unconfigured', passed: false, tier, summary: String(report?.error || output).slice(0, 500) };
   return { status: result.status === 0 ? 'passed' : 'failed', passed: result.status === 0, tier, summary: output.slice(-2000), report };
 }