total-recall-brain 3.40.1 → 3.40.2

package/scaffold/.agent/skills/total-recall/plugins/cli-agents/src/executor.mjs

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { runWorker, runProcess, ADAPTERS } 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() {
+  const mesh = await hostModule('mesh');
+  return { 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) })), adapters: ADAPTERS.map(({ id, name, docs }) => ({ id, name, docs })) };
+}
+
+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 };
+}

package/scaffold/.agent/skills/total-recall/plugins/cli-agents/src/runtime.mjs

@@ -0,0 +1,36 @@
+/** One native runtime-management boundary for every installed agent. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ADAPTERS, findBinary, runProcess, agentEnvironment } from './worker.mjs';
+
+export async function manageRuntime(agent, args = [], { env = process.env, probe = runProcess, cwd = process.cwd() } = {}) {
+  const adapter = ADAPTERS.find(item => item.id === agent);
+  if (!adapter) throw new Error('Unknown agent adapter');
+  if (!Array.isArray(args) || args.length > 64 || args.some(arg => typeof arg !== 'string' || arg.length > 8192)) throw new Error('Invalid native runtime arguments');
+  if (args.some(arg => /(?:api[-_]?key|password|secret|access[-_]?token|refresh[-_]?token)/i.test(arg))) throw new Error('Credential values and mutations belong to the auth owner, never runtime argv');
+  if (agent === 'dsh' && ['status','sessions','tools','models','model','plugins','help','--help','-h'].includes(args[0] || 'status')) {
+    const { run } = await import('./adapters/dsh.mjs');
+    const lines = [], errors = [], log = console.log, error = console.error;
+    const previous = process.exitCode;
+    let result, code;
+    try {
+      console.log = (...parts) => lines.push(parts.join(' ')); console.error = (...parts) => errors.push(parts.join(' '));
+      result = await run([process.execPath, 'cli-agents', 'dsh', ...args]);
+      code = process.exitCode || 0;
+    } finally { console.log = log; console.error = error; process.exitCode = previous; }
+    return { ok:code === 0, agent, exitCode:code, data:result?.data, output:lines.join('\n'), error:errors.join('\n') || undefined };
+  }
+  if (agent === 'hermes' && args[0] === 'auth') {
+    const binary = findBinary('total-recall', env);
+    if (!binary) throw new Error('Total Recall auth CLI is unavailable');
+    const home = env.HERMES_HOME || path.join(env.HOME || os.homedir(), '.hermes');
+    fs.mkdirSync(home, { recursive:true, mode:0o700 });
+    const result = await probe(binary, ['auth','secret','export-env','--path',home,'--keys','OPENROUTER_API_KEY,TELEGRAM_BOT_TOKEN,TELEGRAM_ALLOWED_USERS'], { cwd, timeoutMs:30000, env:agentEnvironment(env) });
+    return { ok:result.exitCode===0 && !result.reason, agent, authority:'auth', exitCode:result.exitCode, output:result.stdout, error:result.reason || (result.exitCode ? 'Auth projection failed' : undefined) };
+  }
+  const binary = findBinary(adapter.binary, env);
+  if (!binary) throw new Error(`${adapter.name} is not installed on the selected node`);
+  const result = await probe(binary, args.length ? args : ['--help'], { cwd, timeoutMs:60000, env:agentEnvironment(env) });
+  return { ok:result.exitCode===0 && !result.reason, agent, exitCode:result.exitCode, output:result.stdout, error:result.reason || (result.exitCode ? result.stderr || 'Runtime command failed' : undefined) };
+}

package/scaffold/.agent/skills/total-recall/plugins/cli-agents/src/setup.mjs

@@ -0,0 +1,35 @@
+/** Configure through Total Recall's existing connect, compilation and plugin-record owners. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { findBinary, runProcess, agentEnvironment } from './worker.mjs';
+
+export async function setupIntegrations({ node, cwd = process.cwd(), env = process.env, probe = runProcess } = {}) {
+  const binary=findBinary('total-recall',env);
+  if(!binary)throw new Error('Total Recall CLI is unavailable');
+  const connected=[];
+  for(const client of ['claude-code','codex','antigravity','cursor','dsh','grok','muse','pi','hermes']) {
+    const result=await probe(binary,['connect',client],{cwd,env:agentEnvironment(env),timeoutMs:120000});
+    if(result.exitCode!==0 || result.reason) {
+      if(/Unknown client/i.test(result.stderr || result.stdout || '')) continue;
+      throw new Error(`Total Recall connect ${client} failed`);
+    }
+    connected.push(client);
+  }
+  const root=env.TR_PACKAGE_ROOT;
+  if(!root || !path.isAbsolute(root) || JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8')).name!=='total-recall-brain')throw new Error('Verified native Total Recall host is required');
+  let placement=null;
+  if(node) {
+    const {getPlugin}=await import(pathToFileURL(path.join(root,'src/core/plugin-loader.mjs')));
+    const {patchPluginRecord,ensurePluginRecord}=await import(pathToFileURL(path.join(root,'src/core/plugin-store.mjs')));
+    const mesh=await import(pathToFileURL(path.join(root,'src/core/mesh.mjs')));
+    const target=mesh.findMeshNode(node);
+    if(!target)throw new Error('Maintenance node is not recorded in the mesh');
+    const plugin=getPlugin('cli-agents',cwd);
+    if(!plugin?.valid)throw new Error('CLI-agents is not installed in the selected workspace');
+    await ensurePluginRecord(plugin);
+    placement=target.hostname;
+    await patchPluginRecord(plugin,{task_nodes:{maintenance:placement}});
+  }
+  return {ok:true,connected,universalInstructions:'AGENTS.md; every dispatch also receives a freshly generated bootstrap',maintenanceNode:placement};
+}

package/scaffold/.agent/skills/total-recall/plugins/cli-agents/src/worker.mjs

@@ -0,0 +1,175 @@
+/** Portable read-only discovery / bounded dispatch worker; streamed to SSH stdin. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+export const ADAPTERS = [
+  { id: 'claude', name: 'Claude Code', binary: 'claude', args: ['--output-format', 'json', '--permission-mode', 'acceptEdits', '-p'], input: 'stdin', auth: ['auth', 'status'], docs: 'https://code.claude.com/docs/en/headless' },
+  { id: 'codex', name: 'Codex', binary: 'codex', args: ['exec', '--sandbox', 'workspace-write', '--json', '-'], input: 'stdin', auth: ['login', 'status'], docs: 'https://developers.openai.com/codex/noninteractive' },
+  { id: 'agy', name: 'Antigravity', binary: 'agy', args: ['--mode', 'accept-edits', '--sandbox', '--output-format', 'json', '-p'], input: 'argument', docs: 'https://antigravity.google/docs/cli/headless/' },
+  { id: 'cursor', name: 'Cursor', binary: 'cursor-agent', args: ['--print', '--output-format', 'json'], input: 'argument', auth: ['status'], docs: 'https://docs.cursor.com/en/cli/reference/parameters' },
+  { id: 'dsh', name: 'DSH', binary: 'dsh', args: ['--profile', 'headless', '--json', '-'], input: 'stdin', docs: 'https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/README.md' },
+  { id: 'grok', name: 'Grok', binary: 'grok', args: ['--output-format', 'json', '-p'], input: 'argument', docs: 'https://docs.x.ai/build/cli/headless-scripting' },
+  { id: 'muse', name: 'Muse', binary: 'muse', args: ['exec', '--json'], input: 'file', docs: 'https://dev.meta.ai/docs/muse-code/' },
+  { id: 'pi', name: 'Pi', binary: 'pi', args: ['--print', '--mode', 'json', '--tools', 'read,bash', '--no-mcp', '--no-extensions'], input: 'stdin', docs: 'https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/docs/cli.md' },
+  { id: 'hermes', name: 'Hermes', binary: 'hermes', args: ['chat', '--oneshot', '--format', 'stream-json', '--query-file', '-'], input: 'stdin', docs: 'https://github.com/NousResearch/hermes-agent/blob/main/website/docs/reference/cli-commands.md' },
+];
+
+export function agentEnvironment(source = process.env) {
+  const allowed = ['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'TMP', 'TEMP', 'LANG', 'LC_ALL', 'TERM', 'SYSTEMROOT', 'SystemRoot', 'APPDATA', 'LOCALAPPDATA', 'USERPROFILE', 'CODEX_HOME', 'CLAUDE_CONFIG_DIR', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'DSH_HOME', 'HERMES_HOME', 'PI_CODING_AGENT_DIR'];
+  return Object.fromEntries(allowed.filter(key => typeof source[key] === 'string').map(key => [key, source[key]]));
+}
+
+export function findBinary(name, env = process.env) {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  const installed = [path.dirname(process.execPath), path.join(home, '.local/bin'), path.join(home, '.npm-global/bin'), path.join(home, 'bin')];
+  const versions = path.join(home, '.nvm/versions/node');
+  try { for (const version of fs.readdirSync(versions).sort().reverse()) installed.push(path.join(versions, version, 'bin')); } catch {}
+  for (const dir of [...new Set([...(env.PATH || '').split(path.delimiter), ...installed].filter(Boolean))]) {
+    const file = path.join(dir, name);
+    try { if (fs.statSync(file).isFile()) { fs.accessSync(file, fs.constants.X_OK); return file; } } catch {}
+  }
+  return null;
+}
+
+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;
+    const kill = signal => { try { if (process.platform !== 'win32') process.kill(-child.pid, signal); else child.kill(signal); } catch {} };
+    const finish = (exitCode, signal) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer);
+      // 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) {
+        clearTimeout(escalation);
+        escalation = setTimeout(() => { kill('SIGKILL'); resolve({ exitCode, signal, stdout, stderr, reason }); }, 500);
+      } else resolve({ exitCode, signal, stdout, stderr, reason });
+    };
+    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; }
+    timer = setTimeout(() => stop('timeout'), timeoutMs);
+    child.on('error', () => { reason = 'spawn-error'; finish(null); });
+    child.stdin.on('error', () => {});
+    for (const [stream, output] of [[child.stdout, true], [child.stderr, false]]) stream.on('data', chunk => {
+      const part = chunk.subarray(0, Math.max(0, maxBytes - bytes)).toString(); bytes += chunk.length;
+      if (output) stdout += part; else stderr += part;
+      if (bytes > maxBytes) stop('output-limit');
+    });
+    child.on('close', finish); child.stdin.end(input);
+  });
+}
+
+export function parseAgentResult(id, result) {
+  if (result.reason || result.exitCode !== 0) return { ok: false, error: result.reason || 'Agent process failed' };
+  let frames;
+  try { const value = JSON.parse(result.stdout); frames = Array.isArray(value) ? value : [value]; }
+  catch { try { frames = result.stdout.trim().split('\n').filter(Boolean).map(line => JSON.parse(line)); } catch { return { ok: false, error: 'Agent output is not valid structured data' }; } }
+  if (!frames.length || frames.some(frame => !frame || typeof frame !== 'object')) return { ok: false, error: 'Agent returned no result' };
+  if (frames.some(frame => frame.error || frame.is_error || ['error', 'turn.failed'].includes(frame.type) || ['FAILED', 'ERROR', 'CANCELED', 'WAITING'].includes(frame.status))) return { ok: false, error: 'Agent reported failure' };
+  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;
+  if (id === 'agy' && last.status === 'SUCCESS') text = last.response;
+  if (id === 'dsh' && last.type === 'final') text = last.text;
+  if (id === 'hermes' && last.type === 'result' && last.exit_code === 0) text = last.text;
+  if (id === 'pi' && last.type === 'agent_end') {
+    const messages = last.messages || [];
+    if (messages.some(message => ['error', 'aborted'].includes(message.stopReason))) return { ok: false, error: 'Pi turn failed' };
+    text = messages.filter(message => message.role === 'assistant').flatMap(message => message.content || []).filter(part => part.type === 'text').map(part => part.text).join('\n');
+  }
+  // The official headless contract documents JSONL plus exit status, not MSP
+  // 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' };
+}
+
+/** Rebuild the instruction payload from the selected node/workspace, never a cached prompt. */
+export async function totalRecallBootstrap(request, { probe = runProcess, env = process.env } = {}) {
+  const binary = findBinary('total-recall', env);
+  if (!binary) throw new Error('Total Recall is not installed on the selected node');
+  const invoke = async args => {
+    const result = await probe(binary, args, { cwd: request.cwd, timeoutMs: 120000, maxBytes: 4 * 1024 * 1024, env: agentEnvironment(env) });
+    if (result.reason || result.exitCode !== 0) throw new Error(`Total Recall ${args[0]} failed; dispatch refused`);
+    return result.stdout;
+  };
+  const actions = request.permissions?.write ? 'read,edit,test' : 'read';
+  await invoke(['cli-agents','setup','--json']);
+  const capsule = JSON.parse(await invoke(['context', request.prompt.slice(0,2000), '--action', actions, '--budget', '24000', '--format', 'json']));
+  if (capsule.ready !== true || typeof capsule.context !== 'string') throw new Error('Required Total Recall context is not ready');
+  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(['cli-agents', 'docs-ensure', '--agent', request.agent, '--json']));
+  if (docs.ok !== true) throw new Error('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}`;
+}
+
+export async function inspectAgents({ probe = runProcess, env = process.env, ids } = {}) {
+  const agents = [];
+  for (const adapter of ADAPTERS) {
+    if (ids && !ids.includes(adapter.id)) continue;
+    const binary = findBinary(adapter.binary, env);
+    const item = { id: adapter.id, name: adapter.name, installed: Boolean(binary), authenticated: 'unknown', executionVerified: false, docs: adapter.docs };
+    if (binary) {
+      const version = await probe(binary, ['--version'], { timeoutMs: 8000 });
+      item.version = version.exitCode === 0 ? (version.stdout || version.stderr).match(/\b\d+\.\d+(?:\.\d+)?\b/)?.[0] || null : null;
+      item.versionVerified = Boolean(item.version);
+      if (adapter.auth) {
+        const auth = await probe(binary, adapter.auth, { timeoutMs: 15000 });
+        if (adapter.id === 'codex') item.authenticated = auth.exitCode === 0 && /Logged in using ChatGPT/i.test(auth.stdout + auth.stderr);
+        if (adapter.id === 'claude') {
+          try { const value = JSON.parse(auth.stdout); item.authenticated = auth.exitCode === 0 && value.loggedIn === true && value.authMethod === 'claude.ai' && value.apiProvider === 'firstParty' && !value.apiKeySource && Boolean(value.subscriptionType); } catch { item.authenticated = false; }
+        }
+        if (adapter.id === 'cursor') item.authenticated = auth.exitCode === 0 && /logged in|authenticated/i.test(auth.stdout) && !/not authenticated|not logged in/i.test(auth.stdout);
+      }
+    }
+    agents.push(item);
+  }
+  return { agents, evidence: 'Installed version/auth metadata; actual command execution requires a separate completed run' };
+}
+
+export async function dispatchAgent(request, { probe = runProcess, env = process.env, bootstrap = totalRecallBootstrap } = {}) {
+  const adapter = ADAPTERS.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 (!fs.statSync(request.cwd).isDirectory()) throw new Error('Selected workspace is not a directory');
+  const binary = findBinary(adapter.binary, env);
+  if (!binary) throw new Error(`${adapter.name} is not installed on the selected node`);
+  const inspected = await inspectAgents({ probe, env, ids: [adapter.id] });
+  const state = inspected.agents.find(item => item.id === adapter.id);
+  if (!state.versionVerified || state.authenticated === false) throw new Error('Selected agent version or account is not ready');
+  if (state.authenticated === 'unknown' && request.allowUnknownAuth !== true) throw new Error('Selected account authentication is unknown; explicitly select this agent to verify it through execution');
+  const prompt = await bootstrap(request, { probe, env });
+  const args = [...adapter.args];
+  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';
+  if (adapter.id === 'agy') args[args.indexOf('--mode') + 1] = allowWrites ? 'accept-edits' : 'plan';
+  if (adapter.id === 'muse' && !allowWrites) args.push('--disable-write');
+  let input = adapter.input === 'stdin' ? prompt : '', temporary;
+  if (adapter.input === 'argument' || adapter.input === 'file') {
+    temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'cli-agent-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.`);
+  }
+  try { return { agent: adapter.id, ...parseAgentResult(adapter.id, await probe(binary, args, { cwd: request.cwd, input, timeoutMs: 300000 })) }; }
+  finally { if (temporary) fs.rmSync(temporary, { recursive: true, force: true }); }
+}
+
+export async function runWorker(request) {
+  if (request.operation === 'inspect') return { ...await inspectAgents(), defaultCwd: os.homedir() };
+  if (request.operation === 'dispatch') return dispatchAgent(request);
+  if (request.operation === 'direct') {
+    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 });
+    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 CLI-agent worker operation');
+}

package/scaffold/.agent/skills/total-recall/plugins/cli-agents/ui/card.js

@@ -0,0 +1,18 @@
+export class CommandFleetCard extends HTMLElement {
+  connectedCallback() {
+    if (!this.shadowRoot) this.attachShadow({ mode: 'open' });
+    this.shadowRoot.innerHTML = `<style>:host{display:block;color:#143d38;font-family:var(--font-sans,system-ui)}.fleet{padding:18px;border-radius:18px;background:#f3eee3;border:1px solid #dbb76a}.mark{display:flex;align-items:center;gap:12px}svg{width:36px;height:36px;stroke:#184e47;fill:none;stroke-width:2}h2{font-size:24px;margin:0;letter-spacing:-1px}p{font-size:12px;opacity:.8}.agents{display:flex;overflow-x:auto;gap:9px;scroll-snap-type:x mandatory}.agent{flex:0 0 140px;scroll-snap-align:start;border-left:3px solid #dbb76a;padding:12px;background:#fff9}.agent b{display:block}.agent span{font-size:11px}button{margin-top:12px;padding:10px;border:1px solid #184e47;border-radius:8px;background:#184e47;color:#f3eee3;cursor:pointer}button:disabled{opacity:.6}.working svg{animation:orbit 1.4s ease-in-out infinite}@keyframes orbit{50%{transform:rotate(12deg)}}@media(prefers-reduced-motion:reduce){.working svg{animation:none}}</style><section class="fleet"><div class="mark"><svg viewBox="0 0 40 40" aria-hidden="true"><path d="M6 10h28M6 20h28M6 30h28"/><circle cx="12" cy="10" r="4"/><circle cx="28" cy="20" r="4"/><circle cx="18" cy="30" r="4"/></svg><h2>Command Fleet</h2></div><p>Choose an agent and its workspace for each command.</p><div class="agents" aria-live="polite">No inspection yet.</div><button>Inspect local agents</button><p class="error" role="alert"></p></section>`;
+    this.shadowRoot.querySelector('button').onclick = () => this.inspect();
+  }
+  async inspect() {
+    const button = this.shadowRoot.querySelector('button'); button.disabled = true; this.shadowRoot.querySelector('.fleet').classList.add('working');
+    try {
+      if (!this.host?.run) throw new Error('Connect this card to its command host');
+      const result = await this.host.run('status'); const list = this.shadowRoot.querySelector('.agents'); list.replaceChildren();
+      for (const agent of result.agents || []) { const entry = document.createElement('div'); entry.className = 'agent'; const title = document.createElement('b'); title.textContent = agent.name; const state = document.createElement('span'); state.textContent = agent.installed ? `Installed · ${agent.version || 'version unknown'} · ${agent.authenticated === true ? 'signed in' : agent.authenticated === false ? 'sign in needed' : 'account unchecked'}` : 'Not installed'; entry.append(title, state); list.append(entry); }
+      this.shadowRoot.querySelector('.error').textContent = '';
+    } catch (error) { this.shadowRoot.querySelector('.error').textContent = error.message; }
+    finally { button.disabled = false; this.shadowRoot.querySelector('.fleet').classList.remove('working'); }
+  }
+}
+if (!customElements.get('command-fleet-card')) customElements.define('command-fleet-card', CommandFleetCard);

package/scaffold/.agent/skills/total-recall/plugins/code-quality/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Total Recall contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/scaffold/.agent/skills/total-recall/plugins/code-quality/README.md

@@ -0,0 +1,84 @@
+# Code Quality — a Total Recall plugin
+
+One-shot, fail-closed code-quality gates for any repository. The plugin ships a shared **core** (gate runner, report reader, repo detector, config contract). Each repository keeps its own **gate list**, customized through the Total Recall CLI instead of hand-edited files.
+
+## What it does
+
+- Runs each configured gate once, as a background job, and writes `reports/latest.json`. There is no daemon.
+- Gate kinds: a command (typecheck, lint, tests, conformance suites) with an output parser (`tsc`, `eslint-stylish`, `eslint-compact`, `biome`, `flake8`, `mypy`, `black`, `generic`), or `grep-forbid`, which turns a written repository invariant into a failing gate.
+- Tiers (`fast`, `full`, `remote`) keep heavy work off small machines. A bounded run lists the gates it skipped.
+- Locking is fail-closed and machine-wide, so only one check runs per host. `--steal-lock` recovers a dead or unverifiable lock and refuses to take one from a verified running check.
+- Reports record coverage, the git head and source freshness. A gate that scans zero files, or a tool that fails without parseable output, is never reported as clean.
+
+## Install into a repository
+
+Requires Total Recall and a project brain in the target repository (`total-recall init --project`). There is no skill to deploy: the runner stays in this plugin and the repository keeps only its state.
+
+```bash
+total-recall plugin install https://github.com/gregiteen/tr-plugin-code-quality
+total-recall code-quality detect            # review the proposal
+total-recall code-quality detect --apply    # or: init (prompts for missing fields)
+total-recall code-quality gate add id=types tier=fast cmd='["npx","tsc","--noEmit"]' parser=tsc
+total-recall code-quality config check      # contract, drift, and gate-command checks
+```
+
+```bash
+total-recall code-quality gate list
+total-recall code-quality-check --tier fast # run the gates once; background job
+total-recall code-quality report            # latest report; never starts a check
+total-recall code-quality report file src/  # findings for one path
+```
+
+## Running on a test node
+
+```bash
+total-recall code-quality config set remoteNode build-box
+total-recall code-quality snapshot --node build-box --name my-repo --install
+```
+
+`snapshot` copies the exact source (git file lists of the repo and its linked plugins, secrets refused) plus the gate config, with a SHA-256 manifest. `--install` runs `npm ci` beside it. On the node, run `node .agent/skills/total-recall/plugins/code-quality/core/check.mjs`.
+
+## Where things live
+
+| Path | Owner |
+|:--|:--|
+| `core/` (runner, report reader, detector, config contract) | this plugin |
+| `.agent/skills/code-quality/config.json`, `reports/`, lock | the repository (state only, no skill content) |
+
+The canonical gate list is a `skill_config` record in the repository's Total Recall project vault. `config.json` is regenerated from it, and hand edits are reported as drift.
+
+## Data and network access
+
+The core runs only the commands in the repository's own config, with the repository as working directory. It reads tracked source files for `grep-forbid` gates and writes only `reports/` and lock files. It makes no network requests. Commands you configure may.
+
+## Development
+
+```bash
+npm test
+```
+
+MIT licensed.
+
+
+## Readiness reconciliation — 2026-09-30
+
+[Canonical correction plan](docs/projects/completed/CODE_QUALITY_PLUGIN/CODE_QUALITY_PLUGIN_PROJECT_TRACKER.md). No fresh suite was run against this external repository HEAD during the documentation review. Run `npm test` and configured gates on the Mac mini in a bounded background job. The Total Recall central preview is unwired static UI and is not an operational demonstration of this plugin.
+
+- **PIC-040:** The Total Recall host CodeQualityPreview.tsx:81 fabricates 42/42 tests and fixed passing gates; it is unwired, and is not proof of this plugin runner.
+- **PIC-041:** Existing architecture names core/config.schema.json, but the tracked file is skills/code-quality/core/config.schema.json; cli.mjs uses host skill-config support, not a self-contained gate configuration store.
+
+Durable capability state must use validated SSSS operations. Delivery requires a real clean-install command/UI walkthrough, explicit unavailable/error states and actual result provenance. Tests may use synthetic fixtures; shipped capability behavior may not.
+
+## Use it two ways
+
+This plugin is a reusable brick, so a new project does not start from zero.
+
+**Add it to a project (for apps you build and ship).** From the project directory:
+
+```sh
+total-recall plugin vendor https://github.com/gregiteen/tr-plugin-code-quality.git 
+```
+
+This copies the plugin's source, skills, tests and docs into `bricks/code-quality` and records it in `tr-bricks.json`. Your project then owns that code: edit it, test it in your own gates, and ship it with no runtime dependency on this plugin or on Total Recall. Combine as many bricks as the project needs. List them with `total-recall plugin bricks`.
+
+**Use it directly with Total Recall (for your own machines and workflow).** Install it with `total-recall plugin install https://github.com/gregiteen/tr-plugin-code-quality.git` and run `total-recall code-quality`. Manage its credentials with `total-recall auth secret` and its skills with `total-recall skill`.

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

@@ -0,0 +1,79 @@
+/**
+ * `total-recall code-quality <verb>` for the repository you run it from.
+ *
+ *   report [view] [arg]      read the latest gate report; never starts a check
+ *   snapshot --node <name>   put the exact source under test on the test node (git file list only)
+ *   gate list|add|remove     edit the repo's gate list
+ *   config get|set|…, detect [--apply], init
+ *                            the rest of the repo-layer config verbs
+ *
+ * Config verbs are Total Recall's own `skill config code-quality …`: every
+ * write is validated against core/config.schema.json and recorded in the
+ * repo's project vault. Gates run once, in the background, through the
+ * `code-quality-check` command or core/check.mjs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { CORE_DIR, findSkillDir, runCore } from './commands/run-core.mjs';
+
+const SHORTHAND = new Set(['get', 'set', 'unset', 'validate', 'schema', 'rebuild', 'import', 'check']);
+
+// The Total Recall install running this plugin: the bin on the command line,
+// or the package root the plugin runner passes to dashboard runs.
+function skillConfigModule() {
+  const roots = [];
+  try {
+    const bin = fs.realpathSync(process.argv[1]);
+    if (path.basename(bin) === 'total-recall.mjs') roots.push(path.dirname(path.dirname(bin)));
+  } catch { /* not started from the bin */ }
+  if (process.env.TR_PACKAGE_ROOT) roots.push(process.env.TR_PACKAGE_ROOT);
+  for (const root of roots) {
+    const candidate = path.join(root, 'src', 'cli', 'skill-config.mjs');
+    if (fs.existsSync(candidate)) return pathToFileURL(candidate).href;
+  }
+  return null;
+}
+
+function fail(message, exitCode) {
+  console.error(message);
+  process.exitCode = exitCode;
+}
+
+export async function run(argv = []) {
+  const args = argv.slice(3);
+  const [verb, ...rest] = args;
+
+  if (verb === 'snapshot') {
+    try {
+      const { default: snapshot } = await import('./commands/snapshot.mjs');
+      const r = snapshot(rest);
+      console.log(rest.includes('--json') ? JSON.stringify(r) : `${r.dryRun ? 'Would copy' : 'Copied'} ${r.files} files${r.node ? ` to ${r.node}:${r.dest} (manifest sha256 ${r.manifestSha256})` : ''}${r.warnings.length ? `\n  ${r.warnings.join('\n  ')}` : ''}`);
+    } catch (err) {
+      fail(err.message, 1);
+    }
+    return;
+  }
+
+  if (verb === 'report') {
+    try {
+      const { exitCode } = runCore('report.mjs', rest);
+      if (exitCode) process.exitCode = exitCode;
+    } catch (err) {
+      fail(err.message, err.exitCode || 1);
+    }
+    return;
+  }
+
+  const moduleUrl = skillConfigModule();
+  if (!moduleUrl) {
+    return fail('Run this through the total-recall CLI: config verbs need a Total Recall install with skill config support.', 2);
+  }
+  const skillDir = findSkillDir();
+  const repoRoot = path.resolve(skillDir, '..', '..', '..');
+  const { runSkillConfig } = await import(moduleUrl);
+  const configArgs = SHORTHAND.has(verb) ? ['config', ...args] : args;
+  const result = await runSkillConfig('code-quality', configArgs, { repoRoot, prefix: 'total-recall code-quality', coreDir: CORE_DIR });
+  if (!verb || verb === 'help' || args.includes('--help')) console.log('  total-recall code-quality report [worst [skip]|type|file <pattern>|count|raw <checkId>]');
+  return result;
+}

package/scaffold/.agent/skills/total-recall/plugins/code-quality/commands/check.mjs

@@ -0,0 +1,6 @@
+import { runCore } from './run-core.mjs';
+
+/** total-recall code-quality-check [--tier fast|full|remote] [--only <id>] */
+export default function check(args = []) {
+  return runCore('check.mjs', args);
+}

package/scaffold/.agent/skills/total-recall/plugins/code-quality/commands/report.mjs

@@ -0,0 +1,6 @@
+import { runCore } from './run-core.mjs';
+
+/** total-recall code-quality-report [summary|errors|raw <id>|…] */
+export default function report(args = []) {
+  return runCore('report.mjs', args);
+}

package/scaffold/.agent/skills/total-recall/plugins/code-quality/commands/run-core.mjs

@@ -0,0 +1,27 @@
+/**
+ * Run one of this plugin's core scripts against the current repository. The
+ * core is never copied into a repo; the repo keeps only its state directory
+ * (config.json, reports), found by core/state.mjs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { stateDir } from '../core/state.mjs';
+
+export const CORE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'core');
+
+export function findSkillDir(start = process.cwd()) {
+  return stateDir(start);
+}
+
+export function runCore(script, args) {
+  if (!fs.existsSync(stateDir())) {
+    const error = new Error('No code-quality state in this repository (.agent/skills/code-quality). Create it: total-recall code-quality init');
+    error.exitCode = 2;
+    throw error;
+  }
+  const result = spawnSync(process.execPath, [path.join(CORE_DIR, script), ...args], { stdio: 'inherit' });
+  if (result.error) throw result.error;
+  return { exitCode: result.status ?? 1, data: { state_dir: stateDir(), script } };
+}