total-recall-brain 3.41.5 → 3.41.6

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/plugin.json

@@ -130,10 +130,17 @@
       },
       {
         "name": "maintenance",
-        "description": "Total Recall daemon maintenance: current official documentation and integration surfaces",
+        "description": "Daemon maintenance: official documentation and integration surfaces, or the model catalog with --models",
         "effect": "write",
         "output": "json",
-        "args": [],
+        "args": [
+          {
+            "name": "models",
+            "flag": "--models",
+            "type": "boolean",
+            "label": "Refresh the model and benchmark catalog"
+          }
+        ],
         "timeout_ms": 600000
       },
       {
@@ -259,16 +266,17 @@
       },
       {
         "name": "benchmarks",
-        "description": "Inspect SWE-bench Pro, Terminal-Bench 2.0, and local empirical pass rates",
+        "description": "Sourced model pricing, coding index and leaderboard results, with pass rates measured on this machine",
         "effect": "read",
         "output": "json",
         "args": []
       },
       {
         "name": "route",
-        "description": "Evaluate task complexity and select optimal harness via two-stage RouteLLM classifier",
-        "effect": "read",
+        "description": "Choose the harness for a task; with --execute, run it on its own branch and escalate on failure",
+        "effect": "write",
         "output": "json",
+        "timeout_ms": 600000,
         "args": [
           {
             "name": "task",
@@ -276,6 +284,30 @@
             "label": "Task description",
             "required": true,
             "positional": true
+          },
+          {
+            "name": "execute",
+            "flag": "--execute",
+            "type": "boolean",
+            "label": "Run the task on its own branch"
+          },
+          {
+            "name": "gate",
+            "flag": "--gate",
+            "type": "boolean",
+            "label": "Require the code-quality gate, escalating when it fails"
+          },
+          {
+            "name": "jev",
+            "flag": "--jev",
+            "type": "boolean",
+            "label": "Classify through the decision plugin"
+          },
+          {
+            "name": "tier",
+            "flag": "--tier",
+            "type": "string",
+            "label": "Gate tier: fast | full | remote"
           }
         ]
       },
@@ -297,15 +329,194 @@
             "flag": "--mode",
             "type": "string",
             "label": "pipeline | council | race"
+          },
+          {
+            "name": "execute",
+            "flag": "--execute",
+            "type": "boolean",
+            "label": "Run the agents; without this the plan is only reported"
+          },
+          {
+            "name": "gate",
+            "flag": "--gate",
+            "type": "boolean",
+            "label": "Require the code-quality gate"
+          },
+          {
+            "name": "autoReview",
+            "flag": "--auto-review",
+            "type": "boolean",
+            "label": "Add a cross-model code review"
+          },
+          {
+            "name": "allowSameFamily",
+            "flag": "--allow-same-family",
+            "type": "boolean",
+            "label": "Accept a Verifier from the Implementer's model family"
           }
-        ]
+        ],
+        "timeout_ms": 600000
       },
       {
         "name": "learn",
-        "description": "Summarize empirical run scorecards and generate memory friction proposals",
+        "description": "Summarize run receipts into scorecards and quota walls; --emit writes proposals to memory",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "emit",
+            "flag": "--emit",
+            "type": "boolean",
+            "label": "Write proposals through the memory owner"
+          }
+        ]
+      },
+      {
+        "name": "alerts",
+        "description": "Send operator alerts for quota walls and usage over the threshold",
+        "effect": "send",
+        "output": "json",
+        "args": [
+          {
+            "name": "action",
+            "type": "string",
+            "label": "check | test",
+            "positional": true
+          },
+          {
+            "name": "threshold",
+            "flag": "--threshold",
+            "type": "number",
+            "label": "Usage percent that triggers an alert"
+          },
+          {
+            "name": "dryRun",
+            "flag": "--dry-run",
+            "type": "boolean",
+            "label": "Report without sending"
+          }
+        ]
+      },
+      {
+        "name": "decompose",
+        "description": "Decompose complex multi-step tasks into specialized Explorer, Architect, Implementer, and Verifier subagent stages",
         "effect": "read",
         "output": "json",
-        "args": []
+        "args": [
+          {
+            "name": "task",
+            "type": "string",
+            "label": "Task description",
+            "required": true,
+            "positional": true
+          }
+        ]
+      },
+      {
+        "name": "orchestrate",
+        "description": "Orchestrate multi-step tasks using subagent fan-out, one-way valve context compression, and cross-model verification",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "task",
+            "type": "string",
+            "label": "Task description",
+            "required": true,
+            "positional": true
+          },
+          {
+            "name": "orchestrator",
+            "flag": "--orchestrator",
+            "type": "string",
+            "label": "Active orchestrator harness (claude, codex, agy, hermes, cursor)"
+          },
+          {
+            "name": "execute",
+            "flag": "--execute",
+            "type": "boolean",
+            "label": "Execute live stages"
+          },
+          {
+            "name": "autoReview",
+            "flag": "--auto-review",
+            "type": "boolean",
+            "label": "Trigger adversarial code review upon completion"
+          },
+          {
+            "name": "gate",
+            "flag": "--gate",
+            "type": "boolean",
+            "label": "Require the code-quality gate"
+          },
+          {
+            "name": "allowSameFamily",
+            "flag": "--allow-same-family",
+            "type": "boolean",
+            "label": "Accept a Verifier from the Implementer's model family"
+          }
+        ],
+        "timeout_ms": 600000
+      },
+      {
+        "name": "threads",
+        "description": "Manage multi-platform agent threads, PR branch tracking, and turn history across all connected platforms",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "action",
+            "type": "string",
+            "label": "list | show | create | close | delete",
+            "required": true,
+            "positional": true
+          },
+          {
+            "name": "target",
+            "type": "string",
+            "label": "Thread ID or title",
+            "positional": true
+          }
+        ]
+      },
+      {
+        "name": "review",
+        "description": "Execute automated adversarial cross-model code review on Git diffs, PR branches, or staged changes",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "target",
+            "type": "string",
+            "label": "Target branch, PR commit, or empty for working-tree",
+            "positional": true
+          },
+          {
+            "name": "reviewer",
+            "flag": "--reviewer",
+            "type": "string",
+            "label": "Adversarial reviewer harness"
+          },
+          {
+            "name": "staged",
+            "flag": "--staged",
+            "type": "boolean",
+            "label": "Review staged diffs"
+          },
+          {
+            "name": "author",
+            "flag": "--author",
+            "type": "string",
+            "label": "Harness that wrote the code, excluded with its model family"
+          },
+          {
+            "name": "thread",
+            "flag": "--thread",
+            "type": "string",
+            "label": "Thread to attach the review to"
+          }
+        ],
+        "timeout_ms": 600000
       }
     ]
   },
@@ -314,7 +525,8 @@
       "command-executor": "src/executor.mjs",
       "documentation": "src/documentation.mjs",
       "agent-runtime": "src/runtime.mjs",
-      "tracker": "src/tracker.mjs"
+      "tracker": "src/tracker.mjs",
+      "gate-adapters": "src/gate-adapters/index.mjs"
     },
     "setup_command": "setup"
   },
@@ -371,6 +583,13 @@
       "command": "maintenance",
       "placement": "selected-node",
       "timeout_ms": 600000
+    },
+    {
+      "intent": "Automated daily model and benchmark catalog refresh into offline living documents",
+      "schedule": "0 3 * * *",
+      "command": "maintenance --models",
+      "placement": "selected-node",
+      "timeout_ms": 300000
     }
   ]
 }

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/skills/meta-harness/SKILL.md

@@ -1,37 +1,31 @@
 ---
 name: meta-harness
-description: Discover, configure, document, track, route, coordinate, and run coding agent harnesses through Total Recall across mesh nodes.
+description: Discover, route, coordinate, review and run coding agent harnesses through Total Recall across mesh nodes.
 repo_scoped: false
 ---
 
 # Meta Harness
 
-The Meta Harness plugin coordinates 15+ coding agent runtimes (`agy`, `claude`, `codex`, `grok`, `ollama`, `hermes`, `dsh`, `openclaw`, `aider`, `goose`, `openhands`, `cline`, and IDE runners) across local and remote mesh nodes.
-
-## Golden Rules
-1. **Never Hardcode Credential Logic**: All API keys resolve via `total-recall auth secret get <KEY>` using the global encrypted vault.
-2. **Total Recall First**: Every dispatched agent run enforces `total-recall context "<task>"` with `ready:true` and writes a verified preflight receipt.
-3. **Deterministic Complexity Routing**: Use `meta-harness route "<task>"` to classify task complexity and avoid burning frontier quotas on mechanical edits.
-4. **Isolated Verification**: In multi-agent pipelines (`Architect -> Implementer -> Verifier`), the Verifier must execute in an isolated git worktree and employ a distinct model family.
-
-## Command Reference
-
-### Discovery & Upstream Version Tracking
-- `total-recall meta-harness status [--node <id>]`: Check installed binaries, versions, and auth status.
-- `total-recall meta-harness tracking [--node <id>]`: Compare installed versions against upstream release tags and changelogs.
-- `total-recall meta-harness catalog`: List all built-in and custom declarative adapter contracts.
-
-### Smart Routing & Telemetry
-- `total-recall meta-harness quota [--node <id>]`: Inspect 5-hour rolling/weekly quotas, credit balances, and free RAM.
-- `total-recall meta-harness benchmarks`: View SWE-bench Pro, Terminal-Bench 2.0, and local empirical pass rates.
-- `total-recall meta-harness route "<task>"`: Two-stage RouteLLM classifier and gate cascade evaluation.
-
-### Multi-Agent Coordination & Mesh Dispatch
-- `total-recall meta-harness coordinate "<task>" --mode pipeline`: Run Architect -> Implementer -> Verifier pipeline.
-- `total-recall meta-harness coordinate "<task>" --mode council`: Run multi-model consensus review.
-- `total-recall meta-harness dispatch <harness> "<prompt>" [--node <id>]`: Dispatch a single task with preflight receipt.
-
-### Self-Learning & Adapters
-- `total-recall meta-harness learn`: Ingest recent run receipts, update scorecards, and propose memory friction improvements.
-- `total-recall meta-harness adapter add <json-or-file>`: Register custom third-party agent harnesses dynamically.
-- `total-recall meta-harness adapter list`: View custom registered adapters.
+Coordinates coding agent harnesses across mesh nodes. `cli-agents` is an alias of `meta-harness`. Run `total-recall meta-harness --help` for flags.
+
+## Rules
+1. **Believe the status words.** `ready` was proved by a login probe. `unverified` has no probe, so only a completed run proves it. `needs_auth`, `blocked` and `exhausted` cannot take work; the reason is in `quotaNote` and in `excluded`.
+2. **No figure without a source.** `benchmarks` shows only fetched figures with their source and time. A dash means nobody measured it. Adapter quality and cost scores are configured priors, not measurements.
+3. **Writing happens on a branch.** `route --execute`, `coordinate --execute` and race work in their own worktree on a `meta-harness/...` branch. Nothing merges into your branch; review the branch and merge it yourself.
+4. **Long runs go to the background.** The host stops plugin commands after 10 minutes, so add `--background` to any multi-stage `--execute` and follow it with `threads list`.
+5. **Cost.** dsh, hermes and other metered harnesses bill per token, and `route` warns when it picks one. `--jev` also makes a metered call.
+
+## Commands
+- `status`, `inspect --node <id>`, `upstream`, `changelog <agent>`, `catalog`, `nodes`: what is installed, signed in and current.
+- `quota [--node <id>]`: readiness, measured usage and walls, OpenRouter balance, and memory across the fleet.
+- `benchmarks`: pricing, Artificial Analysis indices, SWE-bench Pro, and pass rates from this machine's receipts. Refresh with `maintenance --models`.
+- `route "<task>" [--jev] [--execute [--gate] [--tier fast|full|remote] [--background]]`: pick a harness; with `--execute`, run it and escalate on failure.
+- `coordinate "<task>" --mode pipeline|council|race [--execute] [--gate] [--auto-review] [--allow-same-family] [--background]`: without `--execute` it only reports the plan and its blockers.
+- `decompose "<task>"`: the stages and which ready harness takes each.
+- `review [<git-range>] [--staged] [--author <id>] [--reviewer <id>] [--thread <id>]`: review by another model family. `NO_DIFF` means there was nothing to review.
+- `dispatch --stdin` with JSON `{agent, cwd, prompt, permissions, node, allowUnknownAuth}`: one bootstrapped run with a receipt.
+- `threads list|show|create|close|delete`, `learn [--emit]`, `alerts check|test [--dry-run]`, `adapter list|add|remove`.
+- `docs-status`, `docs-refresh`, `docs-search --query <q>`, `docs-read`, `maintenance`, `setup`, `runtime <agent> <args>`.
+
+## When something fails
+Read `failureKind` on the result. `quota` carries `resetsAt`, and routing avoids that harness until then. `auth` and `not-ready` mean the operator must sign in or install something. These do not count against a harness's pass rate; `agent` and `gate` failures do.

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

@@ -1,23 +1,36 @@
-/**
- * Operator Alerts Dispatcher
- * Bridges to Total Recall alerts plugin or system notifications.
- */
-
+/** Operator alerts go through the alerts plugin. A failed send is reported as failed. */
 import { execFileSync } from 'node:child_process';
+import { readReceipts, activeQuotaWalls } from './learner.mjs';
 
-export async function notifyAlert(alert = {}) {
-  const { title = 'Meta Harness Notification', message = '', severity = 'info' } = alert;
+const SEVERITY = { info: 'info', warning: 'high', high: 'high', critical: 'critical' };
 
-  // Attempt to invoke total-recall alerts if present
+export async function notifyAlert({ title = 'Meta Harness', message = '', severity = 'info', eventId, dryRun = false } = {}) {
+  const args = ['alerts', 'send', '--title', title, '--message', message, '--severity', SEVERITY[severity] || 'info', '--source', 'meta-harness'];
+  if (eventId) args.push('--event-id', eventId);
+  if (dryRun) args.push('--dry-run');
   try {
-    const totalRecallBin = process.env.TOTAL_RECALL_BIN || 'total-recall';
-    execFileSync(totalRecallBin, ['alerts', 'send', '--title', title, '--message', message, '--severity', severity], {
-      stdio: 'pipe',
-      timeout: 5000
+    execFileSync(process.env.TOTAL_RECALL_BIN || 'total-recall', args, { stdio: 'pipe', timeout: 15000 });
+    return { ok: true, title };
+  } catch (error) {
+    return { ok: false, title, error: String(error.stderr || error.message).slice(0, 300) };
+  }
+}
+
+/** Alert on quota walls and on measured usage over the threshold. Event ids keep a wall from alerting twice. */
+export async function checkAlerts({ quotas = {}, threshold = 85, dryRun = false } = {}) {
+  const walls = activeQuotaWalls(await readReceipts());
+  const candidates = Object.entries(walls).map(([harness, wall]) => ({
+    title: `Meta Harness: ${harness} is out of quota`,
+    message: `${wall.message || 'Quota wall observed.'} Routing avoids ${harness} until ${wall.until}.`,
+    severity: 'warning', eventId: `meta-harness-wall-${harness}-${wall.until}`,
+  }));
+  for (const [id, quota] of Object.entries(quotas)) {
+    if (typeof quota?.usagePercent === 'number' && quota.usagePercent > threshold && quota.billingModel !== 'local') candidates.push({
+      title: `Meta Harness: ${id} is at ${quota.usagePercent}%`, message: `Measured usage on ${id} is above ${threshold}%.`,
+      severity: 'warning', eventId: `meta-harness-usage-${id}-${new Date().toISOString().slice(0, 10)}`,
     });
-    return { ok: true, dispatchedVia: 'total-recall-alerts' };
-  } catch {
-    // Fallback: console log without crashing
-    return { ok: true, dispatchedVia: 'fallback-logged', logged: { title, message, severity } };
   }
+  const sent = [];
+  for (const alert of candidates) sent.push(await notifyAlert({ ...alert, dryRun }));
+  return { ok: sent.every(row => row.ok), threshold, walls, alerts: sent };
 }

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

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