total-recall-brain 3.41.6 → 3.42.0

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

@@ -30,7 +30,7 @@ export const EXTENDED_ADAPTERS = [
   { id: 'ollama', name: 'Ollama', binary: 'ollama', args: ['run'], input: 'stdin', docs: 'https://ollama.com/library' },
   { id: 'openclaw', name: 'OpenClaw', binary: 'openclaw', args: ['agent', '--message'], input: 'argument', docs: 'https://openclaw.ai/docs' },
   { id: 'aider', name: 'Aider', binary: 'aider', args: ['--yes', '--message'], input: 'argument', docs: 'https://aider.chat/docs' },
-  { id: 'goose', name: 'Goose', binary: 'goose', args: ['run', '--text'], input: 'argument', docs: 'https://block.github.io/goose/' },
+  { id: 'goose', name: 'Goose', binary: 'goose', args: ['run', '--text'], input: 'argument', docs: 'https://goose-docs.ai/' },
   { id: 'openhands', name: 'OpenHands', binary: 'openhands', args: ['run'], input: 'argument', docs: 'https://docs.openhands.dev/' },
   { id: 'cline', name: 'Cline', binary: 'cline', args: ['task', '--json'], input: 'argument', docs: 'https://cline.bot/docs' }
 ];
@@ -43,6 +43,35 @@ export function getCustomAdaptersDirs() {
   ];
 }
 
+export function adapterPath(directory, id) {
+  if (typeof id !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(id)) throw new Error('Invalid adapter identifier');
+  const file = path.join(directory, `${id}.json`);
+  try { if (fs.lstatSync(file).isSymbolicLink()) throw new Error('Adapter files cannot be symbolic links'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return file;
+}
+
+/** Validate executable declarations before persisting or loading them; preserve their scoped contracts. */
+export function validateCustomAdapter(spec) {
+  if (!spec || typeof spec !== 'object' || Array.isArray(spec)) throw new Error('Adapter specification must be an object');
+  adapterPath('.', spec.id);
+  if (typeof spec.binary !== 'string' || !spec.binary.trim() || /[\0\r\n]/.test(spec.binary)) throw new Error('Adapter must declare a binary');
+  for (const key of ['args', 'auth']) if (spec[key] !== undefined && (!Array.isArray(spec[key]) || spec[key].some(arg => typeof arg !== 'string' || /\0/.test(arg)))) throw new Error(`Invalid adapter ${key}`);
+  if (spec.input !== undefined && !['stdin', 'argument', 'file'].includes(spec.input)) throw new Error('Invalid adapter input mode');
+  if (spec.credentials !== undefined) {
+    if (!spec.credentials || typeof spec.credentials !== 'object' || Array.isArray(spec.credentials)) throw new Error('Invalid adapter credentials');
+    for (const [name, keys] of Object.entries(spec.credentials)) {
+      if (!/^[A-Z][A-Z0-9_]*$/.test(name) || !Array.isArray(keys) || !keys.length || keys.some(key => typeof key !== 'string' || !/^[A-Za-z0-9_.-]+$/.test(key))) throw new Error('Adapter credentials must map environment names to auth-store key names');
+    }
+  }
+  if (spec.docs != null) {
+    const url = new URL(spec.docs);
+    if (url.protocol !== 'https:' || url.username || url.password) throw new Error('Adapter documentation must use an HTTPS URL without credentials');
+  }
+  for (const key of ['costScore', 'qualityScore']) if (spec[key] !== undefined && !Number.isFinite(spec[key])) throw new Error(`Invalid adapter ${key}`);
+  return { ...spec, name: spec.name || spec.id, args: spec.args || ['-p'], input: spec.input || 'argument', docs: spec.docs || null };
+}
+
 export function loadCustomAdapters() {
   const custom = [];
   for (const dir of getCustomAdaptersDirs()) {
@@ -52,22 +81,18 @@ export function loadCustomAdapters() {
         if (!file.endsWith('.json')) continue;
         const fullPath = path.join(dir, file);
         try {
-          const spec = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-          if (spec && typeof spec.id === 'string' && typeof spec.binary === 'string') {
+          if (fs.lstatSync(fullPath).isSymbolicLink()) throw new Error('Adapter files cannot be symbolic links');
+          const spec = validateCustomAdapter(JSON.parse(fs.readFileSync(fullPath, 'utf8')));
+          if (spec) {
             custom.push({
-              id: spec.id,
-              name: spec.name || spec.id,
-              binary: spec.binary,
-              args: Array.isArray(spec.args) ? spec.args : ['-p'],
-              input: spec.input || 'argument',
-              docs: spec.docs || null,
+              ...spec,
               custom: true,
               sourcePath: fullPath
             });
           }
-        } catch {}
+        } catch (error) { throw new Error(`Invalid adapter declaration ${file}: ${error.message}`); }
       }
-    } catch {}
+    } catch (error) { throw new Error(`Cannot load adapters from ${dir}: ${error.message}`); }
   }
   return custom;
 }
@@ -99,6 +124,13 @@ export function findBinary(name, env = process.env) {
   return null;
 }
 
+/** Process groups this process started and has not finished, so termination can stop them. */
+const ACTIVE_GROUPS = new Set();
+export function stopActiveProcesses(signal = 'SIGTERM') {
+  for (const pid of ACTIVE_GROUPS) { try { process.kill(process.platform === 'win32' ? pid : -pid, signal); } catch { /* already gone */ } }
+  return ACTIVE_GROUPS.size;
+}
+
 export function runProcess(binary, args, { cwd, input = '', timeoutMs = 300000, env = agentEnvironment(), maxBytes = 2 * 1024 * 1024 } = {}) {
   return new Promise(resolve => {
     let stdout = '', stderr = '', bytes = 0, reason = null, child, timer, escalation, settled = false;
@@ -106,6 +138,7 @@ export function runProcess(binary, args, { cwd, input = '', timeoutMs = 300000,
     const finish = (exitCode, signal) => {
       if (settled) return;
       settled = true; clearTimeout(timer);
+      if (child?.pid) ACTIVE_GROUPS.delete(child.pid);
       // A parent can exit on TERM while a descendant still holds the process group.
       // Finish the owned group cleanup before releasing an aborted operation.
       if (reason && escalation) {
@@ -116,6 +149,7 @@ export function runProcess(binary, args, { cwd, input = '', timeoutMs = 300000,
     const stop = cause => { if (reason) return; reason = cause; kill('SIGTERM'); escalation = setTimeout(() => kill('SIGKILL'), 500); };
     try { child = spawn(binary, args, { cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] }); }
     catch { finish(null); return; }
+    if (child.pid) ACTIVE_GROUPS.add(child.pid);
     timer = setTimeout(() => stop('timeout'), timeoutMs);
     child.on('error', () => { reason = 'spawn-error'; finish(null); });
     child.stdin.on('error', () => {});
@@ -133,7 +167,12 @@ const frameReason = frame => frame.finished_reason || frame.status || frame.type
 export function parseResetTime(text, now = new Date()) {
   const span = String(text).match(/resets? in\s+(?:(\d+)h)?\s*(?:(\d+)m)?\s*(?:(\d+)s)?/i);
   if (span && (span[1] || span[2] || span[3])) return new Date(now.getTime() + ((+span[1] || 0) * 3600 + (+span[2] || 0) * 60 + (+span[3] || 0)) * 1000).toISOString();
-  const clock = String(text).match(/try again at\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)/i);
+  const dated = String(text).match(/(?:try again at|resets)\s+([A-Z][a-z]{2,8})\s+(\d{1,2})(?:st|nd|rd|th)?,?\s+(\d{4}),?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)/i);
+  if (dated) {
+    const at = new Date(`${dated[1]} ${dated[2]}, ${dated[3]} ${dated[4]}:${dated[5] || '00'} ${dated[6]}`);
+    if (!Number.isNaN(at.getTime())) return at.toISOString();
+  }
+  const clock = String(text).match(/(?:try again at|resets)\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)/i);
   if (clock) {
     const at = new Date(now); at.setSeconds(0, 0);
     at.setHours((+clock[1] % 12) + (/pm/i.test(clock[3]) ? 12 : 0), +clock[2] || 0);
@@ -144,7 +183,7 @@ export function parseResetTime(text, now = new Date()) {
 }
 export function classifyFailure(message, now) {
   const text = String(message || '');
-  if (/resource_exhausted|quota|usage limit|rate.?limit|too many requests|\b429\b|out of credits|insufficient credits/i.test(text)) return { failureKind: 'quota', resetsAt: parseResetTime(text, now) };
+  if (/resource_exhausted|quota|usage limit|rate.?limit|too many requests|\b429\b|out of credits|insufficient credits|session limit|requires more credits|can only afford|\b402\b/i.test(text)) return { failureKind: 'quota', resetsAt: parseResetTime(text, now) };
   if (/not logged in|not authenticated|unauthenticated|please (log|sign) in|\b401\b|invalid api key|missing_credential|no api key/i.test(text)) return { failureKind: 'auth' };
   return { failureKind: 'agent' };
 }
@@ -172,11 +211,16 @@ export function parseAgentResult(id, result) {
     catch { return result.exitCode === 0 ? { ok: false, error: 'Agent output is not valid structured data', failureKind: 'agent' } : agentFailure(null, stderr || `Agent process exited ${result.exitCode}`); }
   }
   frames = (frames || []).filter(frame => frame && typeof frame === 'object');
+  const last = frames.at(-1);
+  const metadata = {
+    exitCode: result.exitCode ?? null,
+    model: frames.findLast(frame => typeof frame.model === 'string')?.model ?? null,
+    finishedReason: last?.finished_reason ?? last?.messages?.at(-1)?.stopReason ?? last?.stopReason ?? last?.type ?? null,
+  };
   const failed = frames.find(frame => frameError(frame) || frame.is_error || ['error', 'turn.failed'].includes(frame.type) || ['FAILED', 'ERROR', 'CANCELED', 'WAITING'].includes(frame.status) || ['print_timeout', 'interrupted', 'error'].includes(frame.finished_reason));
-  if (failed) return agentFailure(frameError(failed) || frameReason(failed), stderr);
+  if (failed) return { ...agentFailure(frameError(failed) || frameReason(failed), stderr), ...metadata };
   if (result.exitCode !== 0) return agentFailure(null, stderr || `Agent process exited ${result.exitCode}`);
   if (!frames.length) return { ok: false, error: 'Agent returned no result', failureKind: 'agent' };
-  const last = frames.at(-1);
   let text;
   if (id === 'codex' && last.type === 'turn.completed') text = frames.filter(frame => frame.type === 'item.completed' && frame.item?.type === 'agent_message').map(frame => frame.item.text).join('\n');
   if (['claude', 'cursor', 'grok'].includes(id) && last.type === 'result' && last.subtype === 'success') text = last.result;
@@ -192,7 +236,7 @@ export function parseAgentResult(id, result) {
   // notifications. Preserve the actual log rather than invent a headless schema.
   // Exit zero certifies a finished turn only; it never certifies the requested work.
   if (id === 'muse') return { ok: true, response: result.stdout.trim(), events: frames, completionEvidence: 'headless-process-exit', commandExecutionVerified: false };
-  return typeof text === 'string' && text.trim() ? { ok: true, response: text, commandExecutionVerified: false } : { ok: false, error: 'Agent did not produce a recognized completed result', failureKind: 'agent' };
+  return typeof text === 'string' && text.trim() ? { ok: true, response: text, commandExecutionVerified: false, ...metadata } : { ok: false, error: 'Agent did not produce a recognized completed result', failureKind: 'agent', ...metadata };
 }
 
 /** Rebuild the instruction payload from the selected node/workspace, never a cached prompt. */
@@ -201,26 +245,34 @@ export async function totalRecallBootstrap(request, { probe = runProcess, env =
   if (!binary) throw notReady('Total Recall is not installed on the selected node');
   // Rules come from the operator's project, even when the agent itself works in a temporary worktree.
   const cwd = request.contextCwd || request.cwd;
-  const invoke = async args => {
-    const result = await probe(binary, args, { cwd, timeoutMs: 120000, maxBytes: 4 * 1024 * 1024, env: agentEnvironment(env) });
+  const invoke = async (args, at = cwd) => {
+    const result = await probe(binary, args, { cwd: at, timeoutMs: 120000, maxBytes: 4 * 1024 * 1024, env: agentEnvironment(env) });
     if (result.reason || result.exitCode !== 0) {
       let detail = String(result.stderr || '').trim();
       try { detail = JSON.parse(result.stdout).problems?.join('; ') || detail; } catch { /* plain output */ }
-      throw notReady(`Total Recall ${args[0]} failed in ${cwd}, so dispatch was refused${detail ? `: ${detail.slice(0, 300)}` : ''}`);
+      throw notReady(`Total Recall ${args[0]} failed in ${at}, so dispatch was refused${detail ? `: ${detail.slice(0, 300)}` : ''}`);
     }
     return result.stdout;
   };
   const actions = request.permissions?.write ? 'read,edit,test' : 'read';
   const task = String(request.contextTask || request.prompt).slice(0, 2000);
-  const capsule = JSON.parse(await invoke(['context', task, '--action', actions, '--budget', '24000', '--format', 'json']));
+  const capsule = JSON.parse(await invoke(['context', task, '--action', actions, '--format', 'json']));
   if (capsule.ready !== true || typeof capsule.context !== 'string') throw notReady('Required Total Recall context is not ready');
   await invoke(['preflight', 'ack', '--task', task, '--action', actions, '--json']);
+  // A receipt is per checkout, and the agent's own gate reads the one where it works.
+  if (request.cwd !== cwd) await invoke(['preflight', 'ack', '--task', task, '--action', actions, '--json'], request.cwd);
   const help = await invoke(['--help']);
   const plugins = JSON.parse(await invoke(['plugin', 'library', '--json']));
   const commands = JSON.parse(await invoke(['composable-cli', 'library', '--json']));
   const docs = JSON.parse(await invoke(['meta-harness', 'docs-ensure', '--agent', request.agent, '--json']));
   if (docs.ok !== true) throw notReady('Official agent documentation is unavailable or stale');
-  return `Requester: the operator of this Total Recall workspace.\nUse Total Recall and its owning plugin CLI for this task. The following context and command inventories were obtained automatically on this node before dispatch. Official documentation is cached at ${docs.directory}. Read the applicable cached references before changing an integration.\n\nTask context:\n${capsule.context}\n\nComplete CLI help:\n${help}\n\nInstalled plugin command library:\n${JSON.stringify(plugins)}\n\nComposed command library:\n${JSON.stringify(commands)}\n\nRequested task:\n${request.prompt}`;
+  let references;
+  if (request.bootstrapDirectory) {
+    const file = path.join(request.bootstrapDirectory, 'cli-reference.json');
+    fs.writeFileSync(file, JSON.stringify({ help, plugins, commands }), { mode: 0o600 });
+    references = `Complete CLI, installed-plugin and composed-command inventories: ${file}. Retrieve only the applicable operations; use total-recall <namespace> --help for current arguments.`;
+  } else references = `Complete CLI help:\n${help}\nInstalled plugin command library:\n${JSON.stringify(plugins)}\nComposed command library:\n${JSON.stringify(commands)}`;
+  return `Requester: the operator of this Total Recall workspace.\nThe Total Recall preflight is already acknowledged for this checkout, so do not run it again; a sandboxed session cannot write its receipt.\nUse Total Recall and its owning plugin CLI for this task. Context was assembled automatically for this task on this node. Official documentation is cached at ${docs.directory}; read applicable references before changing an integration.\n\nTask context:\n${capsule.context}\n\nCLI reference:\n${references}\n\nRequested task:\n${request.prompt}`;
 }
 
 /** Authentication is `true` or `false` only when a real probe says so. Everything else stays 'unknown' until a run proves it. */
@@ -250,6 +302,9 @@ export async function inspectAgents({ probe = runProcess, env = process.env, ids
         const names = String(list.stdout || '').split('\n').slice(1).map(line => line.trim().split(/\s+/)[0]).filter(Boolean);
         item.chatModels = names.filter(name => !/embed|bge-|minilm|rerank/i.test(name));
         if (!item.chatModels.length) item.blockedBy = 'no-chat-model';
+      } else if (adapter.auth?.length) {
+        const auth = await probe(binary, adapter.auth, { timeoutMs: 15000, env: agentEnvironment(env) });
+        item.authenticated = auth.reason ? 'unknown' : auth.exitCode === 0;
       }
     }
     agents.push(item);
@@ -259,7 +314,8 @@ export async function inspectAgents({ probe = runProcess, env = process.env, ids
 
 export async function dispatchAgent(request, { probe = runProcess, env = process.env, bootstrap = totalRecallBootstrap } = {}) {
   const adapter = getActiveAdapters().find(item => item.id === request.agent);
-  if (!adapter || !path.isAbsolute(request.cwd || '') || typeof request.prompt !== 'string' || !request.prompt.trim() || Buffer.byteLength(request.prompt) > 65536) throw new Error('Explicit supported agent, absolute workspace and bounded prompt required');
+  if (!adapter || !path.isAbsolute(request.cwd || '') || typeof request.prompt !== 'string' || !request.prompt.trim()) throw new Error('Explicit supported agent, absolute workspace and prompt required');
+  if (Buffer.byteLength(request.prompt) > 65536) throw notReady(`The prompt is ${Buffer.byteLength(request.prompt)} bytes and the limit is 65536, so it was not sent`);
   if (!fs.statSync(request.cwd).isDirectory()) throw new Error('Selected workspace is not a directory');
   const binary = findBinary(adapter.binary, env);
   if (!binary) throw notReady(`${adapter.name} is not installed on the selected node`);
@@ -270,7 +326,9 @@ export async function dispatchAgent(request, { probe = runProcess, env = process
   if (state.blockedBy === 'no-chat-model') throw notReady(`${adapter.name} has no chat model installed on this node`);
   if (state.authenticated === 'unknown' && request.allowUnknownAuth !== true) throw notReady(`${adapter.name} has no login probe; select it explicitly to verify it through execution`);
   if (request.permissions?.write !== true && !READ_ONLY_ADAPTERS.includes(adapter.id) && request.isolated !== true) throw notReady(`${adapter.name} has no read-only mode, so a read-only run must use a disposable checkout`);
-  const prompt = await bootstrap(request, { probe, env });
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'meta-harness-prompt-'));
+  try {
+  const prompt = await bootstrap({ ...request, bootstrapDirectory: temporary }, { probe, env });
   const credentials = {};
   for (const [name, candidates] of Object.entries(adapter.credentials || {})) {
     const auth = findBinary('total-recall', env);
@@ -283,6 +341,23 @@ export async function dispatchAgent(request, { probe = runProcess, env = process
     credentials[name] = value;
   }
   const args = [...adapter.args];
+  if (request.model !== undefined) {
+    if (typeof request.model !== 'string' || !request.model.trim() || /[\0\r\n]/.test(request.model)) throw new Error('Invalid requested model');
+    if (adapter.id === 'ollama') throw new Error('Select the local chat model through its configured runtime');
+    args.push('--model', request.model);
+  }
+  if (request.tools !== undefined || request.settingSources !== undefined) {
+    if (adapter.id !== 'claude') throw notReady(`${adapter.name} cannot enforce the requested tools/settings restriction`);
+    const tools = request.tools;
+    if (tools !== undefined) {
+      if (typeof tools !== 'string' && (!Array.isArray(tools) || tools.some(tool => typeof tool !== 'string'))) throw new Error('Invalid tool restriction');
+      args.push('--tools', tools === 'none' ? '' : Array.isArray(tools) ? tools.join(',') : tools);
+    }
+    if (request.settingSources !== undefined) {
+      if (typeof request.settingSources !== 'string' || request.settingSources.split(',').some(source => !['', 'user', 'project', 'local'].includes(source))) throw new Error('Invalid setting sources');
+      args.push('--setting-sources', request.settingSources);
+    }
+  }
   const allowWrites = request.permissions?.write === true;
   if (adapter.id === 'codex') args[args.indexOf('--sandbox') + 1] = allowWrites ? 'workspace-write' : 'read-only';
   if (adapter.id === 'claude') args[args.indexOf('--permission-mode') + 1] = allowWrites ? 'acceptEdits' : 'plan';
@@ -290,15 +365,19 @@ export async function dispatchAgent(request, { probe = runProcess, env = process
   if (adapter.id === 'muse' && !allowWrites) args.push('--disable-write');
   if (adapter.id === 'pi') args[args.indexOf('--tools') + 1] = allowWrites ? 'read,bash,edit,write' : 'read';
   if (adapter.id === 'ollama') args.push(env.TR_OLLAMA_MODEL || state.chatModels[0]);
-  let input = adapter.input === 'stdin' ? prompt : '', temporary;
+  const input = adapter.input === 'stdin' ? prompt : '';
   if (adapter.input === 'argument' || adapter.input === 'file') {
-    temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'meta-harness-prompt-'));
     const file = path.join(temporary, 'prompt.txt'); fs.writeFileSync(file, prompt, { mode: 0o600 });
     if (adapter.input === 'file') args.push('--prompt-file', file);
-    else args.push(`Read ${file} completely before taking action. It contains the required Total Recall task context, full CLI/plugin/composed-command inventories, official documentation location and the requested task. Carry out that task using the supplied context.`);
+    else args.push(`Read ${file} completely before taking action. It contains the required Total Recall task context, CLI reference location, official documentation location and the requested task. Carry out that task using the supplied context.`);
   }
-  try { return { agent: adapter.id, ...parseAgentResult(adapter.id, await probe(binary, args, { cwd: request.cwd, input, timeoutMs: request.timeoutMs || 900000, env: { ...agentEnvironment(env), ...credentials } })) }; }
-  finally { if (temporary) fs.rmSync(temporary, { recursive: true, force: true }); }
+  const execution = await probe(binary, args, { cwd: request.cwd, input, timeoutMs: request.timeoutMs || 900000, env: { ...agentEnvironment(env), ...credentials } });
+  const parsed = parseAgentResult(adapter.id, execution);
+  const frames = parsed.events || [];
+  return { agent: adapter.id, ...parsed, exitCode: execution.exitCode ?? null,
+    model: parsed.model ?? frames.find(frame => frame.model)?.model ?? null,
+    finishedReason: parsed.finishedReason ?? frames.findLast(frame => frame.finished_reason || frame.stopReason)?.finished_reason ?? execution.reason ?? null };
+  } finally { fs.rmSync(temporary, { recursive: true, force: true }); }
 }
 
 export async function runWorker(request) {
@@ -308,7 +387,9 @@ export async function runWorker(request) {
     if (!path.isAbsolute(request.cwd || '') || !Array.isArray(request.argv) || request.argv.some(arg => typeof arg !== 'string')) throw new Error('Explicit workspace and argv required');
     const binary = findBinary('total-recall');
     if (!binary) throw new Error('Total Recall CLI is not installed on the selected node');
-    const result = await runProcess(binary, request.argv.slice(1), { cwd: request.cwd });
+    const timeoutMs = request.timeoutMs ?? 300000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 3600000) throw new Error('Direct operation timeout must be between 1 ms and one hour');
+    const result = await runProcess(binary, request.argv.slice(1), { cwd: request.cwd, timeoutMs, maxBytes: 16 * 1024 * 1024 });
     return { ok: result.exitCode === 0 && !result.reason, output: result.stdout, error: result.reason || (result.exitCode ? 'CLI command failed' : undefined), exitCode: result.exitCode, commandExecutionVerified: result.exitCode === 0 && !result.reason };
   }
   throw new Error('Unknown meta-harness worker operation');

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

@@ -16,6 +16,9 @@ export const headCommit = cwd => must(cwd, ['rev-parse', 'HEAD'], 'Reading HEAD'
 export const isDirty = cwd => git(cwd, ['status', '--porcelain']).stdout.trim().length > 0;
 export const diffBetween = (cwd, base, head) => must(cwd, ['diff', `${base}...${head}`], 'Reading the diff');
 
+/** Checkouts this process created and has not removed, so termination can clean them up. */
+const ACTIVE_WORKTREES = new Map();
+
 /** `branch` creates a new branch from `ref`. Without it, the checkout is detached at `ref` (read-only use). */
 export function createWorktree(cwd, { branch, ref = 'HEAD', prefix = 'meta-harness-' } = {}) {
   const directory = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
@@ -25,16 +28,39 @@ export function createWorktree(cwd, { branch, ref = 'HEAD', prefix = 'meta-harne
     fs.rmSync(directory, { recursive: true, force: true });
     throw new Error(`Creating a worktree failed: ${String(result.stderr).trim().slice(0, 300)}`);
   }
+  ACTIVE_WORKTREES.set(directory, { cwd, branch: branch || null });
+  seedMandatorySkills(cwd, directory);
   return directory;
 }
+/**
+ * An agent's own Total Recall preflight needs these two files at the repository root, and they are
+ * usually gitignored, so a fresh checkout lacks them and every agent inside it would report itself blocked.
+ */
+const MANDATORY_SKILLS = ['.agent/skills/total-recall/SKILL.md', '.agent/skills/ssss/SKILL.md'];
+function seedMandatorySkills(cwd, directory) {
+  const root = git(cwd, ['rev-parse', '--show-toplevel']).stdout.trim();
+  for (const file of MANDATORY_SKILLS) {
+    const source = path.join(root, file), target = path.join(directory, file);
+    if (fs.existsSync(source) && !fs.existsSync(target)) {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(source, target);
+    }
+  }
+}
 /** Gates need dependencies. Link them only for the gate, after the agent has finished, so no agent can write through the link. */
 export function linkDependencies(cwd, directory) {
   const modules = path.join(cwd, 'node_modules');
   if (fs.existsSync(modules) && !fs.existsSync(path.join(directory, 'node_modules'))) fs.symlinkSync(modules, path.join(directory, 'node_modules'));
+  // The repository's gate configuration is usually gitignored too, and without it the gate could not run here.
+  const root = git(cwd, ['rev-parse', '--show-toplevel']).stdout.trim();
+  const quality = path.join(root, '.agent/skills/code-quality');
+  const target = path.join(directory, '.agent/skills/code-quality');
+  if (fs.existsSync(quality) && !fs.existsSync(target)) fs.cpSync(quality, target, { recursive: true, filter: source => !source.includes(`${path.sep}reports`) });
 }
 export const deleteBranch = (cwd, branch) => git(cwd, ['branch', '-D', branch]).status === 0;
 export function removeWorktree(cwd, directory) {
   if (!directory) return;
+  ACTIVE_WORKTREES.delete(directory);
   try { if (fs.lstatSync(path.join(directory, 'node_modules')).isSymbolicLink()) fs.rmSync(path.join(directory, 'node_modules')); } catch { /* no link */ }
   git(cwd, ['worktree', 'remove', '--force', directory], 60000);
   fs.rmSync(directory, { recursive: true, force: true });
@@ -42,6 +68,8 @@ export function removeWorktree(cwd, directory) {
 /** Commit whatever the agent left. Returns the commit, or null when it changed nothing. */
 export function commitAll(directory, message) {
   must(directory, ['add', '-A', '--', '.', ':!node_modules'], 'Staging agent changes');
+  // Seeded skills are scaffolding, not the agent's work. A repository that tracks them keeps normal history.
+  for (const file of MANDATORY_SKILLS) if (git(directory, ['cat-file', '-e', `HEAD:${file}`]).status !== 0) git(directory, ['rm', '--cached', '-q', '--ignore-unmatch', '--', file]);
   if (git(directory, ['diff', '--cached', '--quiet']).status === 0) return null;
   const staged = git(directory, ['diff', '--cached', '--name-only']).stdout.split('\n').filter(Boolean);
   const secret = staged.filter(file => SECRET_FILE.test(path.basename(file)));
@@ -49,3 +77,10 @@ export function commitAll(directory, message) {
   must(directory, ['commit', '-m', message], 'Committing agent changes');
   return headCommit(directory);
 }
+/** A stopped run's checkouts and unfinished branches go with it. A branch already handed back has no active checkout. */
+export function removeActiveWorktrees() {
+  for (const [directory, { cwd, branch }] of [...ACTIVE_WORKTREES]) {
+    removeWorktree(cwd, directory);
+    if (branch) deleteBranch(cwd, branch);
+  }
+}

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/ui/card.js

@@ -37,6 +37,12 @@ export class CommandFleetCard extends HTMLElement {
     this.reviewVerdict = null;
     this.reviewing = false;
     this.reviewBase = 'main';
+    this.reviewAuthor = '';
+    this.coordinationInput = '';
+    this.coordinationMode = 'pipeline';
+    this.coordinationResult = null;
+    this.documentation = null;
+    this.changelog = null;
   }
 
   connectedCallback() {
@@ -56,13 +62,15 @@ export class CommandFleetCard extends HTMLElement {
       await this.refreshBenchmarks();
     } else if (screen === 'threads' && this.threads.length === 0) {
       await this.refreshThreads();
+    } else if (screen === 'docs') {
+      await this.refreshDocsPanel();
     }
   }
 
   async refreshFleet() {
     if (!this.host) return;
     try {
-      const res = await this.host.run('status', ['--json']);
+      const res = await this.host.run('status', ['--node', this.selectedNode, '--json']);
       let parsed = [];
       if (Array.isArray(res)) {
         parsed = res;
@@ -110,6 +118,7 @@ export class CommandFleetCard extends HTMLElement {
     if (this.screen === 'quotas') return this.refreshQuotas();
     if (this.screen === 'benchmarks') return this.refreshBenchmarks();
     if (this.screen === 'threads') return this.refreshThreads();
+    if (this.screen === 'docs') return this.refreshDocsPanel();
     return this.refreshFleet();
   }
 
@@ -144,12 +153,12 @@ export class CommandFleetCard extends HTMLElement {
     }
   }
 
-  async executeRoute(task) {
+  async executeRoute(task, execute = false) {
     if (!this.host || !task) return;
     this.executing = true;
     this.render();
     try {
-      const res = await this.host.run('route', [task, '--json']);
+      const res = await this.host.run('route', [task, '--node', this.selectedNode, ...(execute ? ['--execute', '--gate', '--background'] : []), '--json']);
       this.routeResult = typeof res === 'string' ? JSON.parse(res) : res;
     } catch (err) {
       this.routeResult = { ok: false, error: err.message };
@@ -182,7 +191,11 @@ export class CommandFleetCard extends HTMLElement {
     this.reviewing = true;
     this.render();
     try {
-      const res = await this.host.run('review', [`${base}...HEAD`, '--json']);
+      const thread = this.threads.find(item => item.id === this.selectedThreadId);
+      const implementer = thread?.turns?.findLast(turn => /implementer/i.test(turn.role || ''))?.agent;
+      const author = this.reviewAuthor || implementer || (thread?.platform !== 'universal' ? thread?.platform : null);
+      if (!author) throw new Error('Select the author before requesting independent review');
+      const res = await this.host.run('review', [`${base}...HEAD`, '--author', author, '--node', this.selectedNode, ...(thread ? ['--thread', thread.id] : []), '--json']);
       this.reviewVerdict = typeof res === 'string' ? JSON.parse(res) : res;
     } catch (err) {
       this.reviewVerdict = { ok: false, error: err.message };
@@ -216,7 +229,8 @@ export class CommandFleetCard extends HTMLElement {
     this.executing = true;
     this.render();
     try {
-      await this.host.run('docs-ensure', ['--json']);
+      await this.host.run('docs-ensure', [...(this.selectedAgent ? ['--agent', this.selectedAgent] : []), '--json']);
+      if (this.screen === 'docs') await this.refreshDocsPanel();
       await this.refreshFleet();
     } catch {
       await this.refreshFleet();
@@ -226,6 +240,36 @@ export class CommandFleetCard extends HTMLElement {
     }
   }
 
+  async executeCoordination(execute = false) {
+    if (!this.host || !this.coordinationInput.trim() || this.executing) return;
+    this.executing = true;
+    this.render();
+    try {
+      const value = await this.host.run('coordinate', [this.coordinationInput, '--mode', this.coordinationMode, '--node', this.selectedNode, ...(execute ? ['--execute', '--gate', '--background'] : []), '--json']);
+      this.coordinationResult = typeof value === 'string' ? JSON.parse(value) : value;
+    } catch (error) { this.coordinationResult = { ok: false, error: error.message }; }
+    finally { this.executing = false; this.render(); }
+  }
+
+  async refreshDocsPanel() {
+    if (!this.host) return;
+    this.loadError = null;
+    // docs-status exits 1 while any source is stale. That is a real status to show, not a failure to read it.
+    const asStatus = text => { try { const parsed = JSON.parse(String(text).trim()); return Array.isArray(parsed?.agents) ? parsed : null; } catch { return null; } };
+    try {
+      const value = await this.host.run('docs-status', ['--json']);
+      this.documentation = typeof value === 'string' ? JSON.parse(value) : value;
+    } catch (error) {
+      this.documentation = asStatus(error?.message);
+      if (!this.documentation) this.loadError = error?.message || 'Documentation status could not be read';
+    }
+    try {
+      const changelog = this.selectedAgent ? await this.host.run('changelog', [this.selectedAgent, '--json']) : null;
+      this.changelog = typeof changelog === 'string' ? JSON.parse(changelog) : changelog;
+    } catch (error) { this.changelog = null; this.loadError = this.loadError || error?.message || 'Changelog could not be read'; }
+    this.render();
+  }
+
   render() {
     const root = this.shadowRoot;
     if (!root) return;
@@ -332,6 +376,7 @@ export class CommandFleetCard extends HTMLElement {
         /* Screen Navigation Tabs */
         .tabs-bar {
           display: flex;
+          flex-wrap: wrap;
           gap: 8px;
           margin-bottom: 14px;
           border-bottom: 1px solid var(--border, var(--face-line));
@@ -625,8 +670,11 @@ export class CommandFleetCard extends HTMLElement {
 
         .input-row {
           display: flex;
+          flex-wrap: wrap;
+          align-items: center;
           gap: 8px;
         }
+        .input-row .task-input { min-width: 0; }
 
         .task-input {
           flex: 1;
@@ -831,6 +879,8 @@ export class CommandFleetCard extends HTMLElement {
         <button class="tab-btn" data-active="${this.screen === 'benchmarks'}" data-screen="benchmarks" type="button">Benchmarks</button>
         <button class="tab-btn" data-active="${this.screen === 'router'}" data-screen="router" type="button">Smart Router</button>
         <button class="tab-btn" data-active="${this.screen === 'threads'}" data-screen="threads" type="button">Threads & Review</button>
+        <button class="tab-btn" data-active="${this.screen === 'coordination'}" data-screen="coordination" type="button">Coordination</button>
+        <button class="tab-btn" data-active="${this.screen === 'docs'}" data-screen="docs" type="button">Docs & Changes</button>
       </div>
 
       <div class="node-bar">
@@ -1001,6 +1051,7 @@ export class CommandFleetCard extends HTMLElement {
           <div class="input-row">
             <input class="task-input" id="task-input" type="text" placeholder="Enter task to evaluate complexity and optimal harness..." value="${escapeHtml(this.routeInput)}" />
             <button class="btn-action" id="btn-route" type="button" ${this.executing ? 'disabled' : ''}>Evaluate Route</button>
+            <button class="btn-action" id="btn-route-run" type="button" ${this.executing ? 'disabled' : ''}>Run with gates</button>
           </div>
 
           ${this.routeResult ? `
@@ -1029,6 +1080,36 @@ export class CommandFleetCard extends HTMLElement {
         </div>
       ` : ''}
 
+      ${this.screen === 'coordination' ? `
+        <div class="router-panel">
+          <label for="coordination-task">Task</label>
+          <textarea class="task-input" id="coordination-task" rows="3">${escapeHtml(this.coordinationInput)}</textarea>
+          <div class="input-row">
+            <label for="coordination-mode">Workflow</label>
+            <select class="task-input" id="coordination-mode">${['pipeline', 'council', 'race'].map(mode => `<option value="${mode}" ${this.coordinationMode === mode ? 'selected' : ''}>${mode === 'pipeline' ? 'Plan, implement and verify' : mode === 'council' ? 'Parallel independent assessment' : 'Parallel verified candidates'}</option>`).join('')}</select>
+            <button class="btn-action" id="btn-coordinate-plan" ${this.executing ? 'disabled' : ''}>Preview plan</button>
+            <button class="btn-action" id="btn-coordinate-run" ${this.executing ? 'disabled' : ''}>Run with gates</button>
+          </div>
+          ${this.coordinationResult ? `<div class="inspector-panel">
+            <h4>${escapeHtml(this.coordinationResult.error || (this.coordinationResult.background ? 'Run started' : this.coordinationResult.ok ? 'Workflow ready' : 'Workflow failed'))}</h4>
+            ${this.coordinationResult.pid ? `<p>Process ${escapeHtml(this.coordinationResult.pid)}. Follow its progress in Threads.</p>` : ''}
+            ${(this.coordinationResult.stages || []).map(stage => `<div class="property-box"><strong>${escapeHtml(stage.role || stage.name || stage.agent)}</strong><span>${escapeHtml(stage.agent || DASH)} · ${stage.passed === true ? 'Passed' : stage.passed === false ? 'Failed' : 'Planned'}</span></div>`).join('')}
+            ${this.coordinationResult.branch ? `<p>Branch: ${escapeHtml(this.coordinationResult.branch)}</p>` : ''}
+          </div>` : '<p>Preview the assigned agents, then start isolated work with verification.</p>'}
+        </div>
+      ` : ''}
+
+      ${this.screen === 'docs' ? `
+        <div class="router-panel">
+          <h4>Documentation coverage</h4>
+          <div class="property-grid">${(this.documentation?.agents || []).map(agent => `<div class="property-box"><strong>${escapeHtml(agent.id)}</strong><span>${agent.fresh ? 'Current' : agent.complete ? 'Stale' : 'Unavailable'} · ${escapeHtml(agent.pages)} pages</span><span>${escapeHtml(agent.error || agent.checkedAt || DASH)}</span></div>`).join('') || '<p>No documentation report loaded.</p>'}</div>
+          <label for="docs-agent">Harness</label>
+          <select class="task-input" id="docs-agent">${this.agents.map(agent => `<option value="${escapeHtml(agent.id)}" ${this.selectedAgent === agent.id ? 'selected' : ''}>${escapeHtml(agent.name || agent.id)}</option>`).join('')}</select>
+          <button class="btn-action" id="btn-changelog">Read changes</button>
+          ${this.changelog ? `<div class="inspector-panel"><h4>Upstream changes</h4><pre style="white-space:pre-wrap;overflow-wrap:anywhere;max-height:260px;overflow:auto">${escapeHtml(this.changelog.error || this.changelog.changelog || this.changelog.content || this.changelog.output || this.changelog.note || 'No changelog content returned')}</pre></div>` : ''}
+        </div>
+      ` : ''}
+
       ${this.screen === 'threads' ? `
         <div class="threads-grid">
           <div class="threads-list">
@@ -1055,6 +1136,7 @@ export class CommandFleetCard extends HTMLElement {
               <p class="plugin-subtitle" style="margin:0 0 10px 0;">Audits branch diff against base using a strictly distinct model family to eliminate confirmation bias.</p>
               <div class="input-row">
                 <input class="task-input" id="review-base-input" type="text" placeholder="Base branch (default: main)" value="${escapeHtml(this.reviewBase)}" />
+                <select class="task-input" id="review-author" aria-label="Code author"><option value="">Author from selected thread</option>${this.agents.map(agent => `<option value="${escapeHtml(agent.id)}" ${this.reviewAuthor === agent.id ? 'selected' : ''}>${escapeHtml(agent.name || agent.id)}</option>`).join('')}</select>
                 <button class="btn-action" id="btn-run-review" type="button" ${this.reviewing ? 'disabled' : ''}>
                   ${this.reviewing ? 'Auditing...' : 'Run Review'}
                 </button>
@@ -1157,6 +1239,13 @@ export class CommandFleetCard extends HTMLElement {
     root.querySelector('#btn-route')?.addEventListener('click', () => {
       if (this.routeInput) this.executeRoute(this.routeInput);
     });
+    root.querySelector('#btn-route-run')?.addEventListener('click', () => this.executeRoute(this.routeInput, true));
+    root.querySelector('#coordination-task')?.addEventListener('input', event => { this.coordinationInput = event.target.value; });
+    root.querySelector('#coordination-mode')?.addEventListener('change', event => { this.coordinationMode = event.target.value; });
+    root.querySelector('#btn-coordinate-plan')?.addEventListener('click', () => this.executeCoordination());
+    root.querySelector('#btn-coordinate-run')?.addEventListener('click', () => this.executeCoordination(true));
+    root.querySelector('#docs-agent')?.addEventListener('change', event => { this.selectedAgent = event.target.value; });
+    root.querySelector('#btn-changelog')?.addEventListener('click', () => this.refreshDocsPanel());
 
     root.querySelectorAll('.thread-card-btn').forEach(btn => {
       btn.addEventListener('click', () => {
@@ -1175,6 +1264,7 @@ export class CommandFleetCard extends HTMLElement {
     root.querySelector('#btn-run-review')?.addEventListener('click', () => {
       this.executeReview(this.reviewBase);
     });
+    root.querySelector('#review-author')?.addEventListener('change', event => { this.reviewAuthor = event.target.value; });
   }
 }
 

package/scaffold/.agent/skills/total-recall/plugins/openwiki/cli.mjs

@@ -15,6 +15,7 @@ import { buildKnowledgeGraph } from './src/graph.mjs';
 import { getTokenStatus, setTokenValue } from './src/token.mjs';
 import { lintWikiHubs } from './src/lint.mjs';
 import { generateWiki } from './src/generate.mjs';
+import { retrieveContext } from './src/context-provider.mjs';
 
 /**
  * Regenerate the generated pages of every registered project that carries them.
@@ -611,6 +612,16 @@ async function autoRefreshCommand(args = []) {
 }
 
 const IMPLEMENTED = {};
+IMPLEMENTED.context = async args => {
+  if (args.includes('--help') || args.includes('-h')) { console.log('Usage: total-recall openwiki context <task> [--json]'); return; }
+  try {
+    if (args.some(arg => arg.startsWith('--') && arg !== '--json')) throw new Error('context accepts a task and --json');
+    const task = args.filter(arg => arg !== '--json').join(' ').trim();
+    if (!task) throw new Error('context requires a task');
+    const result = await retrieveContext({ task });
+    console.log(args.includes('--json') ? JSON.stringify({ ok: true, ...result }) : result.candidates.map(row => `${row.source.path}:${row.source.startLine}-${row.source.endLine}\n${row.text}`).join('\n\n'));
+  } catch (error) { console.log(JSON.stringify({ ok: false, error: error.message })); process.exitCode = 1; }
+};
 IMPLEMENTED.probe = probeCommand;
 IMPLEMENTED.hubs = hubsCommand;
 IMPLEMENTED.ingest = ingestCommand;
@@ -675,9 +686,10 @@ export async function run(argv = process.argv) {
                               List indexed documentation hubs across workspace, all vaults, or mesh
     search <query> [--all-vaults] [--node <node>] [--limit <n>] [--json]
                               Evidence passage search across knowledge hubs and vaults
+    context <task> [--json]    Task evidence with useful linked vicinity, provenance and freshness
     graph [--all-vaults] [--node <node>] [--format json|mermaid|dot] [--json]
                               Extract knowledge graph topology, nodes, and inter-hub links
-    generate [--repo <name>] [--path <dir>] [--output <dir>] [--force] [--dry-run] [--node <node>] [--json]
+    generate [--repo <name>] [--force] [--dry-run] [--node <node>] [--json]
                               Targeted on-demand documentation generation
     token [status|set <provider> <value>] [--stdin] [--json]
                               Check or securely configure Total Recall secrets store keys