tr-plugin-meta-harness 0.0.0-stage → 0.3.0

package/src/coordinator.mjs

@@ -0,0 +1,398 @@
+/**
+ * Meta Harness Multi-Agent Coordinator
+ * Orchestrates role-specialized multi-agent execution pipelines:
+ * - Pipeline: Architect -> Implementer -> Verifier (cross-model family, worktree-isolated)
+ * - Council: Multi-model consensus voting
+ * - Race: Speculative concurrent execution
+ *
+ * Works with any user's installed harness pool:
+ * - Dynamically discovers installed harnesses and assigns distinct model families
+ *   for Architect, Implementer, and Verifier so confirmation bias is avoided.
+ * - Supports plan generation (default safe inspection) and live execution (`execute: true`)
+ *   via `dispatchAgent` with real git worktree isolation for the Verifier stage.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { ADAPTER_CATALOG, classifyTaskComplexity } from '../capability/index.mjs';
+import { inspectAgents, dispatchAgent, getActiveAdapters } from './worker.mjs';
+import { notifyAlert } from './alerts.mjs';
+import { recordRunReceipt } from './learner.mjs';
+
+/**
+ * Resolve installed or available harnesses with their model family metadata
+ */
+async function resolvePool(options = {}) {
+  const active = getActiveAdapters();
+  let installedIds = [];
+  if (Array.isArray(options.availableHarnesses) && options.availableHarnesses.length > 0) {
+    installedIds = options.availableHarnesses;
+  } else {
+    try {
+      const inspected = await inspectAgents({ env: process.env });
+      installedIds = (inspected.agents || []).filter(a => a.installed).map(a => a.id);
+    } catch {}
+  }
+
+  const candidateIds = installedIds.length > 0 ? installedIds : active.map(a => a.id);
+  return candidateIds.map(id => {
+    const cap = ADAPTER_CATALOG[id] || {};
+    const workerSpec = active.find(a => a.id === id) || {};
+    return {
+      id,
+      name: cap.name || workerSpec.name || id,
+      family: cap.family || 'custom',
+      tier: cap.tier || 'budget',
+      qualityScore: cap.qualityScore ?? 7.5,
+      costScore: cap.costScore ?? 4
+    };
+  });
+}
+
+/**
+ * Select three role-specialized harnesses preferring distinct model families
+ */
+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] ? { id, ...ADAPTER_CATALOG[id] } : { id, name: id, family: 'custom' });
+
+  const architect = options.architect
+    ? findById(options.architect)
+    : (sorted[0] || findById('claude'));
+
+  const implementer = options.implementer
+    ? findById(options.implementer)
+    : (sorted.find(h => h.id !== architect.id) || sorted[0] || findById('agy'));
+
+  // Verifier must use a distinct model family from Implementer whenever more than 1 family is available
+  const verifier = options.verifier
+    ? findById(options.verifier)
+    : (sorted.find(h => h.family !== implementer.family && h.id !== implementer.id)
+      || sorted.find(h => h.id !== implementer.id)
+      || implementer);
+
+  return {
+    architect,
+    implementer,
+    verifier,
+    heterogeneousFamilies: verifier.family !== implementer.family || pool.length <= 1
+  };
+}
+
+/**
+ * Coordinate a task across specialized roles and model families
+ */
+export async function coordinateTask(taskDescription, options = {}) {
+  const mode = options.mode || 'pipeline';
+  const task = String(taskDescription || '').trim();
+  if (!task) throw new Error('Task description is required for coordination');
+
+  const pool = await resolvePool(options);
+
+  if (mode === 'pipeline') {
+    return await runSpecializedPipeline(task, pool, options);
+  } else if (mode === 'council') {
+    return await runCouncilCoordination(task, pool, options);
+  } else if (mode === 'race') {
+    return await runRaceCoordination(task, pool, options);
+  } else {
+    throw new Error(`Unsupported coordination mode: ${mode}`);
+  }
+}
+
+/**
+ * Create a temporary detached git worktree if inside a git repository
+ */
+function createVerifierWorktree(cwd) {
+  try {
+    const check = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd, encoding: 'utf8', timeout: 3000 });
+    if (check.status !== 0) return null;
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'meta-harness-verify-'));
+    const add = spawnSync('git', ['worktree', 'add', '--detach', tmpDir], { cwd, encoding: 'utf8', timeout: 10000 });
+    if (add.status !== 0) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+      return null;
+    }
+    return tmpDir;
+  } catch {
+    return null;
+  }
+}
+
+function removeVerifierWorktree(cwd, worktreeDir) {
+  if (!worktreeDir) return;
+  try {
+    spawnSync('git', ['worktree', 'remove', '--force', worktreeDir], { cwd, encoding: 'utf8', timeout: 5000 });
+  } catch {}
+  try {
+    fs.rmSync(worktreeDir, { recursive: true, force: true });
+  } catch {}
+}
+
+/**
+ * Architect -> Implementer -> Verifier Pipeline
+ * Enforces heterogeneous model families to eliminate confirmation bias.
+ */
+async function runSpecializedPipeline(task, pool, options = {}) {
+  const startTime = Date.now();
+  const roles = assignPipelineRoles(pool, options);
+  const executeLive = options.execute === true;
+  const cwd = options.cwd || process.cwd();
+  const dispatchFn = options.dispatchFn || dispatchAgent;
+  const complexity = classifyTaskComplexity(task);
+
+  const stages = [
+    {
+      role: 'Architect',
+      harness: roles.architect.id,
+      harnessName: roles.architect.name,
+      modelFamily: roles.architect.family,
+      permissions: { read: true, write: false },
+      status: executeLive ? 'pending' : 'planned',
+      action: 'Analyze requirements, design modular contracts, and formulate verification plan.',
+      output: null
+    },
+    {
+      role: 'Implementer',
+      harness: roles.implementer.id,
+      harnessName: roles.implementer.name,
+      modelFamily: roles.implementer.family,
+      permissions: { read: true, write: true },
+      status: executeLive ? 'pending' : 'planned',
+      action: 'Author implementation files and unit tests following Architectural blueprint.',
+      output: null
+    },
+    {
+      role: 'Verifier',
+      harness: roles.verifier.id,
+      harnessName: roles.verifier.name,
+      modelFamily: roles.verifier.family,
+      permissions: { read: true, write: false },
+      worktreeIsolated: true,
+      status: executeLive ? 'pending' : 'planned',
+      action: 'Execute deterministic test gates, audit diffs, and verify invariant compliance in isolated worktree.',
+      passed: executeLive ? null : true,
+      output: null
+    }
+  ];
+
+  let allSucceeded = true;
+
+  if (executeLive) {
+    // Stage 1: Architect (Read-Only Plan)
+    const archStart = Date.now();
+    const archRes = await dispatchFn({
+      agent: roles.architect.id,
+      cwd,
+      prompt: `[ROLE: ARCHITECT]\nProduce a concise architectural blueprint, file list, and verification steps for:\n${task}`,
+      permissions: { read: true, write: false },
+      allowUnknownAuth: options.allowUnknownAuth === true
+    });
+    stages[0].status = archRes.ok ? 'completed' : 'failed';
+    stages[0].output = archRes.response || archRes.error || null;
+    recordRunReceipt({
+      harness: roles.architect.id,
+      task: `[Architect] ${task}`,
+      complexityScore: complexity.score,
+      success: Boolean(archRes.ok),
+      durationMs: Date.now() - archStart
+    });
+
+    if (!archRes.ok) {
+      allSucceeded = false;
+    } else {
+      // Stage 2: Implementer
+      const implStart = Date.now();
+      const implRes = await dispatchFn({
+        agent: roles.implementer.id,
+        cwd,
+        prompt: `[ROLE: IMPLEMENTER]\nFollow this Architect blueprint:\n${archRes.response}\n\nImplement the requested task:\n${task}`,
+        permissions: { read: true, write: true },
+        allowUnknownAuth: options.allowUnknownAuth === true
+      });
+      stages[1].status = implRes.ok ? 'completed' : 'failed';
+      stages[1].output = implRes.response || implRes.error || null;
+      recordRunReceipt({
+        harness: roles.implementer.id,
+        task: `[Implementer] ${task}`,
+        complexityScore: complexity.score,
+        success: Boolean(implRes.ok),
+        durationMs: Date.now() - implStart
+      });
+
+      if (!implRes.ok) {
+        allSucceeded = false;
+      } else {
+        // Stage 3: Verifier (Isolated git worktree when available)
+        const verifyStart = Date.now();
+        const worktreeDir = createVerifierWorktree(cwd);
+        const verifyCwd = worktreeDir || cwd;
+        try {
+          const verRes = await dispatchFn({
+            agent: roles.verifier.id,
+            cwd: verifyCwd,
+            prompt: `[ROLE: INDEPENDENT VERIFIER]\nAudit the implementation and run verification checks for:\n${task}\n\nArchitect Blueprint:\n${archRes.response}\n\nImplementer Summary:\n${implRes.response}`,
+            permissions: { read: true, write: false },
+            allowUnknownAuth: options.allowUnknownAuth === true
+          });
+          stages[2].status = verRes.ok ? 'completed' : 'failed';
+          stages[2].passed = Boolean(verRes.ok);
+          stages[2].output = verRes.response || verRes.error || null;
+          stages[2].worktreePath = worktreeDir || null;
+          recordRunReceipt({
+            harness: roles.verifier.id,
+            task: `[Verifier] ${task}`,
+            complexityScore: complexity.score,
+            success: Boolean(verRes.ok),
+            durationMs: Date.now() - verifyStart
+          });
+          if (!verRes.ok) allSucceeded = false;
+        } finally {
+          removeVerifierWorktree(cwd, worktreeDir);
+        }
+      }
+    }
+  } else {
+    stages[0].output = `Planned Architect stage (${roles.architect.name}) for: ${task.slice(0, 80)}`;
+    stages[1].output = `Planned Implementer stage (${roles.implementer.name}) following Architect blueprint.`;
+    stages[2].output = `Planned cross-family Verifier stage (${roles.verifier.name}, family: ${roles.verifier.family}) in isolated git worktree.`;
+  }
+
+  const durationMs = Date.now() - startTime;
+  const result = {
+    ok: allSucceeded,
+    mode: 'pipeline',
+    executedLive: executeLive,
+    task,
+    stages,
+    durationMs,
+    heterogeneousFamiliesVerified: roles.heterogeneousFamilies
+  };
+
+  if (executeLive) {
+    await notifyAlert({
+      title: allSucceeded ? 'Meta Harness: Pipeline Completed' : 'Meta Harness: Pipeline Failed',
+      message: `Multi-agent pipeline ${allSucceeded ? 'succeeded' : 'failed'} for task: ${task.slice(0, 60)}`,
+      severity: allSucceeded ? 'info' : 'warning'
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Council Consensus (Multi-model deliberation across available harnesses)
+ */
+async function runCouncilCoordination(task, pool, options = {}) {
+  const councilHarnesses = options.harnesses
+    || pool.slice(0, 3).map(h => h.id);
+  const executeLive = options.execute === true;
+  const cwd = options.cwd || process.cwd();
+  const dispatchFn = options.dispatchFn || dispatchAgent;
+
+  if (executeLive) {
+    const dispatches = await Promise.all(councilHarnesses.map(async (h) => {
+      try {
+        const res = await dispatchFn({
+          agent: h,
+          cwd,
+          prompt: `[COUNCIL DELIBERATION]\nProvide your independent engineering assessment and recommendation for:\n${task}`,
+          permissions: { read: true, write: false },
+          allowUnknownAuth: options.allowUnknownAuth === true
+        });
+        return {
+          harness: h,
+          ok: Boolean(res.ok),
+          recommendation: res.ok ? 'completed' : 'failed',
+          response: res.response || res.error || null
+        };
+      } catch (err) {
+        return {
+          harness: h,
+          ok: false,
+          recommendation: 'error',
+          response: err.message
+        };
+      }
+    }));
+
+    const passedCount = dispatches.filter(d => d.ok).length;
+    return {
+      ok: passedCount > 0,
+      mode: 'council',
+      executedLive: true,
+      task,
+      council: councilHarnesses,
+      consensus: passedCount === councilHarnesses.length ? 'unanimous' : (passedCount > 0 ? 'majority' : 'failed'),
+      votes: dispatches
+    };
+  }
+
+  const votes = councilHarnesses.map(h => ({
+    harness: h,
+    status: 'planned',
+    recommendation: 'ready',
+    reasoning: `Scheduled independent read-only deliberation on ${h}.`
+  }));
+
+  return {
+    ok: true,
+    mode: 'council',
+    executedLive: false,
+    task,
+    council: councilHarnesses,
+    consensus: 'planned',
+    votes
+  };
+}
+
+/**
+ * Speculative Concurrent Race
+ */
+async function runRaceCoordination(task, pool, options = {}) {
+  const contenders = options.harnesses
+    || pool.slice(0, 2).map(h => h.id);
+  const executeLive = options.execute === true;
+  const cwd = options.cwd || process.cwd();
+  const dispatchFn = options.dispatchFn || dispatchAgent;
+
+  if (executeLive) {
+    const results = await Promise.all(contenders.map(async (h) => {
+      const start = Date.now();
+      try {
+        const res = await dispatchFn({
+          agent: h,
+          cwd,
+          prompt: task,
+          permissions: { read: true, write: false },
+          allowUnknownAuth: options.allowUnknownAuth === true
+        });
+        return { harness: h, ok: Boolean(res.ok), durationMs: Date.now() - start, response: res.response || null };
+      } catch (err) {
+        return { harness: h, ok: false, durationMs: Date.now() - start, error: err.message };
+      }
+    }));
+    const winners = results.filter(r => r.ok).sort((a, b) => a.durationMs - b.durationMs);
+    return {
+      ok: winners.length > 0,
+      mode: 'race',
+      executedLive: true,
+      task,
+      contenders,
+      winner: winners[0]?.harness || null,
+      results
+    };
+  }
+
+  return {
+    ok: true,
+    mode: 'race',
+    executedLive: false,
+    task,
+    contenders,
+    winner: contenders[0] || null,
+    reason: 'Planned concurrent race across selected contenders.'
+  };
+}

package/src/documentation.mjs

@@ -0,0 +1,152 @@
+/** Official documentation downloads. Cache files are disposable projections, never credentials. */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+export const DOC_SOURCES = [
+  { id: 'claude', index: 'https://code.claude.com/docs/llms.txt', prefix: 'https://code.claude.com/docs/', catalog:true },
+  { id: 'codex', index: 'https://developers.openai.com/codex/llms.txt', prefix: 'https://learn.chatgpt.com/docs/', catalog:true },
+  { id: 'agy', index: 'https://antigravity.google/docs/cli/reference', prefix: 'https://antigravity.google/docs/' },
+  { id: 'cursor', index: 'https://cursor.com/llms.txt', prefix: 'https://cursor.com/docs', catalog:true },
+  { id: 'dsh', repo: 'deepseek-ai/deepseek-harness', branch: 'master', directories: ['docs/', 'apps/cli/', 'packages/boot/'], index: 'https://raw.githubusercontent.com/deepseek-ai/deepseek-harness/master/apps/cli/README.md' },
+  { id: 'grok', index: 'https://docs.x.ai/llms.txt', prefix: 'https://docs.x.ai/build/', catalog:true },
+  { id: 'muse', index: 'https://dev.meta.ai/docs/muse-code', prefix: 'https://dev.meta.ai/docs/muse-code' },
+  { id: 'pi', repo: 'badlogic/pi-mono', branch: 'main', directories: ['packages/coding-agent/docs/'], index: 'https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/README.md' },
+  { id: 'hermes', repo: 'NousResearch/hermes-agent', branch: 'main', directories: ['website/docs/'], index: 'https://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/docs/reference/cli-commands.md' },
+];
+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);}
+function atomic(file, value) { fs.mkdirSync(path.dirname(file), { recursive: true }); const temp = `${file}.${process.pid}.tmp`; fs.writeFileSync(temp, value, { mode: 0o600 }); fs.renameSync(temp, file); }
+export function documentationDirectory() {
+  const brain = process.env.TR_SECRETS_BRAIN || path.join(process.env.AGENT_DIR || path.join(os.homedir(), '.agent'), 'skills/total-recall');
+  return path.join(brain, 'memory-derived/cli-agents/docs');
+}
+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;
+  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 => {
+      try { return hash(fs.readFileSync(pageFile(directory,source.id,page.file))) === page.sha256; } catch { return false; }
+    });
+    const age=now-Date.parse(saved?.checkedAt);
+    const fresh = complete && Number.isFinite(age) && age>=-300000 && age<=TTL && !saved.error;
+    return { id:source.id, complete, fresh, pages:saved?.pages?.length || 0, checkedAt:saved?.checkedAt || null, lastAttempt:saved?.lastAttempt || null, error:saved?.error || null };
+  });
+  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','raw.githubusercontent.com','api.github.com']);
+  let target = new URL(url);
+  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-CLI-Agents-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.
+    if(response.status===404 && ['cursor.com','docs.x.ai'].includes(target.hostname) && target.pathname.endsWith('.md')){target.pathname=target.pathname.slice(0,-3);continue;}
+    if(!response.ok)throw new Error(`Documentation HTTP ${response.status}: ${target.origin}${target.pathname}`);
+    const chunks=[];let size=0;
+    for await(const chunk of response.body){size+=chunk.byteLength;if(size>8*1024*1024){throw new Error('Documentation page exceeds download budget');}chunks.push(chunk);}
+    const bytes=Buffer.concat(chunks);
+    const text=new TextDecoder().decode(bytes);
+    if(text.trim().length<40)throw new Error('Empty documentation response');
+    return text;
+  }
+  throw new Error('Too many documentation redirects');
+}
+function links(text,base,prefix) {
+  const values=base.endsWith('llms.txt')?[...text.matchAll(/https:\/\/[^\s<>"'\])]+/g)].map(match=>match[0]):[];
+  for(const match of text.matchAll(/\]\(([^\s)]+)(?:\s+[^)]*)?\)/g)){try{values.push(new URL(match[1],base).href);}catch{}}
+  for(const match of text.matchAll(/href=["']([^"']+)["']/g)) {try{values.push(new URL(match[1],base).href);}catch{}}
+  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) && !/\.(png|jpg|jpeg|svg|gif|css|js|woff2?|ico|pdf)$/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;
+  if(!sources.length)throw new Error('Unknown documentation adapter');
+  const reports=[];
+  for(const source of sources) {
+    const previous=metadata(directory,source.id), pages=[], queue=[source.index], seen=new Set(), queued=new Set(queue), errors=[];
+    const enqueue=url=>{if(!queued.has(url)){queued.add(url);queue.push(url);}};
+    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}`);
+      }
+      // Bounded batches; follow the official index/navigation to cover agent features.
+      while(queue.length) {
+        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)})));
+        for(let index=0;index<downloads.length;index++) {
+          const result=downloads[index];if(result.status==='rejected'){errors.push({url:batch[index],error:result.reason.message});continue;}
+          const {url,text}=result.value;
+          const sha256=hash(text),file=`${hash(url)}-${sha256}.txt`;
+          atomic(path.join(directory,source.id,file),text);
+          pages.push({url,file,sha256,bytes:Buffer.byteLength(text)});
+          // A published llms index is the authoritative documentation catalog.
+          // HTML navigation also contains unrelated and obsolete marketing links.
+          if(source.prefix && (!source.catalog || url.endsWith('llms.txt')))for(const link of links(text,url,source.prefix))enqueue(link);
+        }
+      }
+      const checkedAt=now().toISOString();
+      if(errors.length){
+        const error=`${errors.length} official document(s) failed: ${errors[0].error}`;
+        const preserved=previous?.complete?previous:{id:source.id,complete:false,pages};
+        atomic(path.join(directory,source.id,'index.json'),JSON.stringify({...preserved,lastAttempt:checkedAt,error,failedCount:errors.length,failures:errors},null,2));
+        reports.push({id:source.id,ok:false,error,pages:preserved.pages?.length || 0,downloadedPages:pages.length,failedCount:errors.length,failures:errors});continue;
+      }
+      atomic(path.join(directory,source.id,'index.json'),JSON.stringify({id:source.id,complete:true,checkedAt,lastAttempt:checkedAt,pages},null,2));
+      reports.push({id:source.id,ok:true,pages:pages.length});
+    } 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});
+    }
+  }
+  return {ok:reports.every(row=>row.ok),directory,agents:reports};
+}
+export async function ensureDocumentation(options={}) {
+  const status=documentationStatus(options);
+  if(status.ok)return status;
+  const refresh=[];
+  for(const row of status.agents.filter(row=>!row.fresh))refresh.push(await refreshDocumentation({...options,agent:row.id}));
+  return {...documentationStatus(options),refresh};
+}
+
+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 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)};
+}
+
+export function readDocumentation({agent,url,directory=documentationDirectory()}) {
+  if(!DOC_SOURCES.some(source=>source.id===agent))throw new Error('Unknown documentation adapter');
+  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);
+  if(!page)throw new Error('Official document is not cached');
+  const content=fs.readFileSync(pageFile(directory,agent,page.file),'utf8');
+  if(hash(content)!==page.sha256)throw new Error('Cached documentation integrity mismatch');
+  return {agent,url,sha256:page.sha256,checkedAt:index.checkedAt,content};
+}
+
+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 matches=[];
+  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 index=doc.content.toLowerCase().indexOf(query.toLowerCase());
+    if(index>=0)matches.push({agent:source.id,url:page.url,excerpt:doc.content.slice(Math.max(0,index-120),index+600)});
+    if(matches.length>=30)return {matches,truncated:true};
+  }
+  return {matches,truncated:false};
+}

package/src/executor.mjs

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { runWorker, runProcess, getActiveAdapters } from './worker.mjs';
+
+async function hostModule(name) {
+  const selected = process.env.TR_PACKAGE_ROOT;
+  if (!selected || !path.isAbsolute(selected)) throw new Error('Verified native Total Recall host required');
+  const root = fs.realpathSync(selected);
+  if (JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name !== 'total-recall-brain') throw new Error('Host package identity mismatch');
+  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');
+    const nodes = mesh.listEnrichedMeshNodes().map(node => ({ id: node.hostname, name: node.title || node.hostname, online: node.online, self: node.self, accessConfigured: Boolean(node.access?.ssh_user) }));
+    return {
+      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 {
+    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) }))
+    };
+  }
+}
+
+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(()=>{console.error("Selected agent worker failed");process.exitCode=1;});\n';
+}
+
+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');
+  const target = mesh.findMeshNode(node);
+  if (!target) throw new Error('Selected mesh node is not recorded');
+  if (target.self) return worker(request);
+  if (target.online === false) throw new Error('Selected mesh node is offline');
+  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 : 330000 });
+  if (result.reason || result.exitCode !== 0) throw new Error('Selected mesh worker failed; verify node access, workspace and agent installation');
+  try { return JSON.parse(result.stdout); } catch { throw new Error('Selected mesh worker returned invalid data'); }
+}
+
+export async function inspectNode(node = 'local', dependencies) {
+  return executeOnNode(node, { operation: 'inspect' }, dependencies);
+}
+
+export function quoteArgument(value) { return "'" + String(value).replaceAll("'", "'\\''") + "'"; }
+
+export async function executeCommand({ plugin, subcommand, args = [], execution, projectRoot = process.cwd() }, dependencies = {}) {
+  if (!plugin?.valid || !execution || typeof execution.agent !== 'string' || typeof execution.node !== 'string') throw new Error('Choose an installed agent and mesh node');
+  if (!Array.isArray(args) || args.length > 64 || args.some(arg => typeof arg !== 'string' || arg.length > 8192)) throw new Error('Invalid command arguments');
+  const command = ['on', 'off'].includes(subcommand) ? { effect: 'write', args: [] } : plugin.manifest.cli?.subcommands?.find(item => item.name === subcommand);
+  if (!command) throw new Error('Selected command is not declared by its owner');
+  if (command.sensitive_output === true && execution.agent !== 'direct') throw new Error('Commands that issue credentials require direct execution; tokens cannot enter agent prompts or transcripts');
+  if (command.args?.some(arg => arg.secret)) throw new Error('Credential operations use direct execution, never an agent prompt');
+  const permissions = commandPermissions(execution.permissions);
+  const effect = ['read', 'write', 'send', 'destructive'].includes(command.effect) ? command.effect : 'write';
+  if (!permissions[effect]) throw new Error(`The ${effect} command permission is off`);
+  const cwd = execution.node === 'local' ? execution.cwd || projectRoot : execution.cwd;
+  if (!path.isAbsolute(cwd || '')) throw new Error('Choose the absolute workspace on the selected node');
+  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);
+  return { ok: result.ok === true, exitCode: result.ok ? 0 : 1, output: result.ok ? JSON.stringify(result) : result.error || 'Selected agent failed', ...result };
+}