total-recall-brain 3.41.4 → 3.41.6

package/src/cli/harness.mjs

@@ -1,6 +1,19 @@
 #!/usr/bin/env node
 
-import { detectHarnesses, detectHarnessesWithAuth, queryHarnessUsage, dispatchTask, runCouncil, HARNESS_SPECS } from '../core/meta-harness.mjs';
+import { checkReceipt, findRoot, ACK_COMMAND } from '../core/preflight-receipt.mjs';
+
+/** Harness work belongs to the meta-harness plugin. These commands are a thin door to it. */
+async function callPlugin(subcommand, args, options = {}) {
+  const { getPlugin } = await import('../core/plugin-loader.mjs');
+  const plugin = getPlugin('meta-harness', process.cwd());
+  if (!plugin?.valid) throw new Error('The meta-harness plugin is not installed. Run: total-recall plugin install meta-harness');
+  const { runPluginCommand } = await import('../core/plugin-runner.mjs');
+  const result = await runPluginCommand(plugin, { subcommand, args: [...args, '--json'], timeoutMs: 600000, ...options });
+  let data = null;
+  try { data = JSON.parse(result.output); } catch { /* reported below */ }
+  if (!data) throw new Error(`meta-harness ${subcommand} returned no result: ${String(result.output).trim().slice(0, 300)}`);
+  return { ok: result.ok, data };
+}
 
 function printHelp() {
   console.log(`
@@ -10,10 +23,10 @@ Usage:
   npx total-recall harness <command> [options]
 
 Commands:
-  list                      Inspect all external developer harnesses, versions & auth
-  usage                     Query harness account APIs for 5h & weekly quota remaining %
-  dispatch <id> "<task>"    Headlessly invoke a specific agent harness
+  list, usage               Harness readiness, versions and measured usage
+  dispatch <id> "<task>"    Headlessly invoke a specific agent harness (read-only by default)
                             Options: --node <name> to execute remotely on a mesh node
+                                     --write to let the agent change files
   council "<task>"          Run concurrent multi-harness consensus deliberation
 
 Available Harness IDs:
@@ -49,45 +62,32 @@ export async function run(argv) {
   const asJson = args.includes('--json');
 
   if (!command || command === 'list' || command === 'status' || command === 'usage') {
-    const reports = await queryHarnessUsage();
-    if (asJson) {
-      console.log(JSON.stringify(reports, null, 2));
-      return;
+    let report;
+    try { ({ data: report } = await callPlugin('quota', [])); }
+    catch (err) { console.error(`\n❌ ${err.message}`); process.exit(1); }
+    if (asJson) { console.log(JSON.stringify(report, null, 2)); return; }
+    const pad = (value, width) => String(value ?? '—').padEnd(width).slice(0, width);
+    console.log(`\n🎮 Total Recall — Agent Harnesses (${report.node})\n`);
+    console.log(`${pad('Harness', 12)} ${pad('Version', 12)} ${pad('Status', 14)} ${pad('5h used', 9)} ${pad('Week used', 10)} Note`);
+    for (const [id, quota] of Object.entries(report.quotas || {})) {
+      if (id === 'system' || id === 'metered') continue;
+      console.log(`${pad(id, 12)} ${pad(quota.version, 12)} ${pad(quota.status, 14)} ${pad(quota.rolling5hUsedPercent, 9)} ${pad(quota.weeklyUsedPercent, 10)} ${quota.quotaNote || ''}`);
     }
-
-    console.log(`\n🎮 Total Recall — Connected Agent Harnesses, Versions & Quotas\n`);
-
-    const pad = (s, l) => String(s || '').padEnd(l).slice(0, l);
-    console.log('┌──────────────┬──────────────────────────────┬──────────────┬──────────────┬──────────────────────────┬──────────────────────┬──────────────────────┬──────────────┐');
-    console.log(`│ ${pad('Harness ID', 12)} │ ${pad('Name', 28)} │ ${pad('Version', 12)} │ ${pad('Current?', 12)} │ ${pad('Auth Route', 24)} │ ${pad('5h Quota Rem. %', 20)} │ ${pad('Weekly Rem. %', 20)} │ ${pad('Status', 12)} │`);
-    console.log('├──────────────┼──────────────────────────────┼──────────────┼──────────────┼──────────────────────────┼──────────────────────┼──────────────────────┼──────────────┤');
-
-    for (const h of reports) {
-      const ver = h.version || '—';
-      const cur = h.isCurrent ? 'Current ✅   ' : (h.latestVersion ? `Update (${h.latestVersion.slice(0, 5)})` : 'Check ⚠️     ');
-      const auth = h.authRoute || '—';
-      const q5h = h.rolling5hRemainingPct || '—';
-      const qWeek = h.weeklyRemainingPct || '—';
-      let statusStr = '\x1b[31mNot Found ❌\x1b[0m';
-      if (h.available) {
-        if (h.status === 'ready') statusStr = '\x1b[32mReady ✅\x1b[0m     ';
-        else if (h.status === 'update_available') statusStr = '\x1b[33mUpdate 🔄\x1b[0m   ';
-        else statusStr = '\x1b[33mNo Auth ⚠️\x1b[0m   ';
-      }
-      console.log(`│ \x1b[1m${pad(h.id, 12)}\x1b[0m │ ${pad(h.name, 28)} │ ${pad(ver, 12)} │ ${pad(cur, 12)} │ ${pad(auth, 24)} │ ${pad(q5h, 20)} │ ${pad(qWeek, 20)} │ ${statusStr} │`);
-    }
-    console.log('└──────────────┴──────────────────────────────┴──────────────┴──────────────┴──────────────────────────┴──────────────────────┴──────────────────────┴──────────────┘\n');
+    console.log('');
     return;
   }
 
   if (command === 'dispatch') {
     let targetNode = null;
+    let write = false;
     const filteredRest = [];
     for (let i = 0; i < rest.length; i++) {
       if (rest[i] === '--node' || rest[i] === '-n') {
         targetNode = rest[i + 1];
         i++;
-      } else {
+      } else if (rest[i] === '--write') {
+        write = true;
+      } else if (rest[i] !== '--json') {
         filteredRest.push(rest[i]);
       }
     }
@@ -100,13 +100,24 @@ export async function run(argv) {
       process.exit(1);
     }
 
+    if (!targetNode) {
+      const root = findRoot(process.cwd());
+      const receipt = checkReceipt(root);
+      if (!receipt.ok) {
+        console.error(`\n❌ Dispatch refused by TR-PREFLIGHT gate: ${receipt.problems[0] || 'check failed'} (directory: ${root}).`);
+        console.error(`   Read the complete context capsule, then run: ${ACK_COMMAND}\n`);
+        process.exit(1);
+      }
+    }
+
     const nodeStr = targetNode ? ` on mesh node \x1b[1;33m${targetNode}\x1b[0m` : '';
     console.log(`\n🚀 Dispatching task to \x1b[1;36m${harnessId}\x1b[0m${nodeStr}...`);
     try {
-      const res = await dispatchTask(harnessId, task, { node: targetNode });
-      console.log(`\n--- [Response from ${res.harnessName}${targetNode ? ' (' + targetNode + ')' : ''}] ---\n`);
-      console.log(res.response);
-      console.log(`\n✅ Exit code: ${res.exitCode}`);
+      const { ok, data } = await callPlugin('dispatch', [], { stdinText: JSON.stringify({ agent: harnessId, cwd: process.cwd(), prompt: task, node: targetNode || 'local', permissions: { read: true, write }, allowUnknownAuth: true }) });
+      if (asJson) { console.log(JSON.stringify(data, null, 2)); if (!ok) process.exit(1); return; }
+      if (!ok) throw new Error(data.error || 'The agent failed');
+      console.log(`\n--- [Response from ${harnessId}${targetNode ? ' (' + targetNode + ')' : ''}] ---\n`);
+      console.log(data.response);
     } catch (err) {
       console.error(`\n❌ Dispatch failed: ${err.message}`);
       process.exit(1);
@@ -115,7 +126,14 @@ export async function run(argv) {
   }
 
   if (command === 'council') {
-    const task = rest.join(' ').trim();
+    const root = findRoot(process.cwd());
+    const receipt = checkReceipt(root);
+    if (!receipt.ok) {
+      console.error(`\n❌ Council deliberation refused by TR-PREFLIGHT gate: ${receipt.problems[0] || 'check failed'} (directory: ${root}).`);
+      console.error(`   Read the complete context capsule, then run: ${ACK_COMMAND}\n`);
+      process.exit(1);
+    }
+    const task = rest.filter(arg => arg !== '--json').join(' ').trim();
     if (!task) {
       console.error('Error: Please specify task prompt for council deliberation.');
       console.error('Usage: npx total-recall harness council "<task>"');
@@ -126,20 +144,14 @@ export async function run(argv) {
     console.log(`   Task: "${task}"\n`);
 
     try {
-      const councilRes = await runCouncil(task);
-      console.log(`Participating Harnesses: ${councilRes.participants.join(', ')}\n`);
-
-      for (const r of councilRes.results) {
-        console.log(`================================================================`);
-        console.log(`● Harness: \x1b[1;36m${r.harnessName}\x1b[0m (${r.harnessId})`);
-        console.log(`================================================================`);
-        if (r.success) {
-          console.log(r.response);
-        } else {
-          console.log(`\x1b[31mError: ${r.error || r.stderr || 'Execution failed'}\x1b[0m`);
-        }
-        console.log('');
+      const { data } = await callPlugin('coordinate', [task, '--mode', 'council', '--execute']);
+      if (!data.votes) throw new Error(data.error || 'No votes returned');
+      if (asJson) { console.log(JSON.stringify(data, null, 2)); return; }
+      for (const vote of data.votes) {
+        console.log(`● \x1b[1;36m${vote.harness}\x1b[0m: ${vote.vote}${vote.error ? ` (${vote.error})` : ''}`);
+        if (vote.feedback) console.log(`${vote.feedback}\n`);
       }
+      console.log(`Consensus: ${data.consensus}`);
     } catch (err) {
       console.error(`\n❌ Council deliberation failed: ${err.message}`);
       process.exit(1);

package/src/cli/memory-entry.mjs

@@ -69,10 +69,10 @@ Installed capabilities:`);
     return;
   }
   const plugins = discoverPlugins(process.cwd()).filter(p => p.valid);
-  const plugin = plugins.find(p => p.manifest.cli?.handler && (p.manifest.cli.command || p.id) === command)
+  const plugin = plugins.find(p => p.manifest.cli?.handler && ((p.manifest.cli.command || p.id) === command || p.manifest.cli.alias === command))
     || plugins.find(p => p.manifest.commands?.some(entry => entry.name === command));
   if (!plugin) throw new Error(`Unknown command '${command}'. Install its capability plugin or run total-recall --help.`);
-  const declared = plugin.manifest.cli?.handler && (plugin.manifest.cli.command || plugin.id) === command
+  const declared = plugin.manifest.cli?.handler && ((plugin.manifest.cli.command || plugin.id) === command || plugin.manifest.cli.alias === command)
     ? null : plugin.manifest.commands.find(entry => entry.name === command);
   if (declared && rest.some(arg => ['--help', '-h'].includes(arg))) {
     console.log(`Usage: total-recall ${command} [args] [--json]\n${declared.description || ''}`);

package/src/cli/preflight.mjs

@@ -1,13 +1,14 @@
 import fs from 'node:fs';
 import { decide, SWEEP_CONSULT_MS } from '../core/preflight-gate.mjs';
-import { ACK_COMMAND, acknowledge, checkReceipt, findRoot, lastConsultMs } from '../core/preflight-receipt.mjs';
+import { ACK_COMMAND, acknowledge, checkReceipt, findRoot, lastConsultMs, recordDecision, readDecisions } from '../core/preflight-receipt.mjs';
 
 const USAGE = `Usage: total-recall preflight <command>
   ack --task "<task>" [--action read,edit,test] [--json]   Record a receipt after context ready:true and rules verify
   check [--json]                                            Exit 1 unless a fresh receipt exists for this directory
   gate [--harness <id>]                                     Hook entry: read a call on stdin, answer allow or deny (exit 2 on deny)
   remind [--json]                                           Prompt-hook entry: advisory text when the receipt is missing; always exits 0
-  install | verify | report                                 Harness adapters, owned by the cli-agents plugin
+  install [--harness <id>] [--dry-run]                      Install the gate for a harness. The gate has no off switch.
+  verify | report                                           Harness adapters, owned by the cli-agents plugin
 Aliases: total-recall tr-preflight --ack | --check. A receipt lasts 30 minutes (config preflight_max_age_minutes).`;
 
 /** An explicit override only. The configured window is read once, by `ack`, and recorded in the receipt. */
@@ -76,6 +77,15 @@ async function ack(args) {
   console.log(`  receipt: ${result.file}`);
 }
 
+async function loadGateAdapters() {
+  let adapters;
+  try { adapters = await (await import('../core/plugin-runtime.mjs')).loadPluginModule('meta-harness', 'gate-adapters'); } catch { adapters = null; }
+  if (!adapters) {
+    try { adapters = await (await import('../core/plugin-runtime.mjs')).loadPluginModule('cli-agents', 'gate-adapters'); } catch { adapters = null; }
+  }
+  return adapters;
+}
+
 /**
  * Hook entry. It starts at exit 2 and only an explicit allow clears it, so any
  * failure, including one nobody anticipated, denies: most harnesses let the
@@ -91,19 +101,15 @@ async function gate(args) {
     if (!call || typeof call !== 'object' || Array.isArray(call)) return deny('gate-error', 'TR-PREFLIGHT gate input must be a JSON object.');
     const harness = flag(args, '--harness');
     if (harness) {
-      let adapters;
-      try { adapters = await (await import('../core/plugin-runtime.mjs')).loadPluginModule('meta-harness', 'gate-adapters'); } catch { adapters = null; }
-      if (!adapters) {
-        try { adapters = await (await import('../core/plugin-runtime.mjs')).loadPluginModule('cli-agents', 'gate-adapters'); } catch { adapters = null; }
-      }
+      const adapters = await loadGateAdapters();
       const adapter = adapters?.get?.(harness);
       if (!adapter) return deny('gate-error', `No gate adapter for harness "${harness}": adapters are owned by the meta-harness plugin and it does not provide one. The gate fails closed.`);
-      const out = await adapter.run({ stdin: call, decideWith: evaluate });
+      const out = await adapter.run({ stdin: call, decideWith: (c) => evaluate(c, { harness, readablePaths: adapter.readablePaths }) });
       if (out?.stdout) process.stdout.write(out.stdout);
       process.exitCode = Number.isInteger(out?.exitCode) ? out.exitCode : 2;
       return;
     }
-    const answer = evaluate(call);
+    const answer = evaluate(call, { harness: 'generic' });
     process.stdout.write(`${JSON.stringify(answer)}\n`);
     if (answer.decision === 'allow') process.exitCode = 0;
   } catch (err) {
@@ -111,10 +117,128 @@ async function gate(args) {
   }
 }
 
-function evaluate(call) {
+async function install(args) {
+  const harness = flag(args, '--harness') || 'claude';
+  const dryRun = args.includes('--dry-run');
+  if (args.includes('--remove') || args.includes('--off')) {
+    console.error('✖ The preflight gate has no off switch. If it blocks work, fix the cause: `total-recall tr-preflight --ack` names it, and `total-recall rules` stays open to repair it.');
+    process.exitCode = 1;
+    return;
+  }
+  const adapters = await loadGateAdapters();
+  if (!adapters) {
+    console.error('✖ Gate adapters are owned by the meta-harness (cli-agents) plugin and are not available.');
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const res = adapters.install(harness, { dryRun });
+    if (args.includes('--json')) {
+      console.log(JSON.stringify({ ok: true, harness, action: 'installed', ...res }));
+    } else {
+      console.log(`✔ Installed preflight gate for ${harness}`);
+      if (res.added?.length) console.log(`  added: ${res.added.join(', ')}`);
+      if (res.removed?.length) console.log(`  removed: ${res.removed.join(', ')}`);
+      console.log(`  settings: ${res.settings}`);
+    }
+  } catch (err) {
+    console.error(`✖ Failed to install preflight gate for ${harness}: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function verify(args) {
+  const harness = flag(args, '--harness') || 'claude';
+  const adapters = await loadGateAdapters();
+  if (!adapters) {
+    console.error('✖ Gate adapters are owned by the meta-harness (cli-agents) plugin and are not available.');
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const res = adapters.verify(harness);
+    const ok = Boolean(res.installed && res.exercised);
+    if (args.includes('--json')) {
+      console.log(JSON.stringify({ ok, harness, ...res }));
+    } else {
+      if (ok) {
+        console.log(`✔ Preflight gate for ${harness} is verified (${res.level || 'enforced'})`);
+      } else {
+        console.error(`✖ Preflight gate for ${harness} verification failed`);
+        if (!res.installed) console.error('  hook is not installed in harness configuration');
+        if (!res.exercised) console.error('  synthetic deny exercise failed');
+      }
+    }
+    if (!ok) process.exitCode = 1;
+  } catch (err) {
+    console.error(`✖ Failed to verify preflight gate for ${harness}: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function report(args) {
+  const adapters = await loadGateAdapters();
+  if (!adapters) {
+    console.error('✖ Gate adapters are owned by the meta-harness (cli-agents) plugin and are not available.');
+    process.exitCode = 1;
+    return;
+  }
+  const all = adapters.list();
+  const results = all.map(a => ({
+    id: a.id,
+    level: a.level,
+    verification: adapters.verify(a.id)
+  }));
+
+  const decisions = readDecisions();
+  const summary = {
+    total: decisions.length,
+    allowed: decisions.filter(d => d.decision === 'allow').length,
+    denied: decisions.filter(d => d.decision === 'deny').length,
+    byHarness: {},
+    byRepo: {}
+  };
+  for (const d of decisions) {
+    const h = d.harness || 'generic';
+    summary.byHarness[h] ??= { total: 0, allowed: 0, denied: 0 };
+    summary.byHarness[h].total++;
+    if (d.decision === 'allow') summary.byHarness[h].allowed++;
+    else summary.byHarness[h].denied++;
+
+    const r = d.repo || 'unknown';
+    summary.byRepo[r] ??= { total: 0, allowed: 0, denied: 0 };
+    summary.byRepo[r].total++;
+    if (d.decision === 'allow') summary.byRepo[r].allowed++;
+    else summary.byRepo[r].denied++;
+  }
+
+  if (args.includes('--json')) {
+    console.log(JSON.stringify({ adapters: results, compliance: summary }, null, 2));
+  } else {
+    for (const r of results) {
+      console.log(`- ${r.id}: ${r.level} (installed: ${r.verification.installed}, exercised: ${r.verification.exercised})`);
+    }
+    if (summary.total > 0) {
+      console.log(`\nCompliance summary (${summary.total} real gate decisions observed):`);
+      const pct = ((summary.allowed / summary.total) * 100).toFixed(1);
+      console.log(`  Allowed: ${summary.allowed} | Denied: ${summary.denied} | Rate: ${pct}%`);
+      console.log('  By harness:');
+      for (const [hId, stats] of Object.entries(summary.byHarness)) {
+        const hPct = ((stats.allowed / stats.total) * 100).toFixed(1);
+        console.log(`    ${hId.padEnd(14)}: ${stats.allowed}/${stats.total} allowed (${hPct}%)`);
+      }
+    } else {
+      console.log('\nCompliance summary:');
+      console.log('  No gate decisions recorded yet (live gate traffic has not been observed).');
+    }
+  }
+}
+
+function evaluate(call, { harness, readablePaths } = {}) {
   const root = findRoot(call.cwd || process.cwd());
   const limit = envMaxAgeMs();
-  return decide(call, {
+  const decision = decide(call, {
+    readablePaths,
     check: () => checkReceipt(root, { maxAgeMs: limit }),
     recentConsult: () => {
       const now = Date.now();
@@ -123,6 +247,18 @@ function evaluate(call) {
       return Boolean(receipt && now - Date.parse(receipt.at) < SWEEP_CONSULT_MS);
     },
   });
+  recordDecision({
+    harness: harness || call.harness || 'generic',
+    cwd: call.cwd || process.cwd(),
+    repo: root,
+    tool: call.tool || 'other',
+    command: call.command || null,
+    path: call.path || null,
+    decision: decision.decision,
+    rule: decision.rule,
+    reason: decision.reason || null
+  });
+  return decision;
 }
 
 /**
@@ -149,13 +285,13 @@ export default async function preflight(args = []) {
   // Original `tr-preflight` forms.
   if (first === '--ack' || first === 'ack') return ack(args);
   if (first === '--check' || first === 'check') return check(args);
+  // Help never performs the subcommand: `install --help` once rewrote the harness settings (C-019).
+  if (args.includes('--help') || args.includes('-h')) return console.log(USAGE);
   if (first === 'gate') return gate(args.slice(1));
   if (first === 'remind') return remind(args);
-  if (['install', 'verify', 'report'].includes(first)) {
-    console.error(`preflight ${first}: harness adapters are owned by the meta-harness (cli-agents) plugin and are not installed yet (ENFORCE-01 EN-03 onward).`);
-    process.exitCode = 1;
-    return;
-  }
+  if (first === 'install') return install(args.slice(1));
+  if (first === 'verify') return verify(args.slice(1));
+  if (first === 'report') return report(args.slice(1));
   console.error(`Unknown preflight command: ${first}\n\n${USAGE}`);
   process.exitCode = 1;
 }