total-recall-brain 3.26.0 → 3.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.26.0",
+  "version": "3.28.0",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [

package/scaffold/.agent/plugins/code-quality/README.md

@@ -0,0 +1,16 @@
+# Code Quality & SSSS Conformance
+
+> Local-first code quality gates, SSSS schema verification, and invariant enforcement
+
+## Installation
+
+```bash
+npx total-recall plugin install ./.agent/plugins/code-quality --link
+```
+
+## Features
+
+- **Identifier**: `code-quality`
+- **Version**: 1.0.0
+- **SSSS Category**: `quality-gates`
+- **CLI Command**: `npx total-recall code-quality`

package/scaffold/.agent/plugins/code-quality/cli.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+
+export async function run(argv = []) {
+  const scriptPath = path.resolve(process.cwd(), '.agent/skills/code-quality/scripts/report.mjs');
+  try {
+    const out = execFileSync('node', [scriptPath], { encoding: 'utf8' });
+    console.log(out);
+  } catch (err) {
+    console.error('Failed to run code-quality report:', err.message);
+  }
+}
+
+export default run;

package/scaffold/.agent/plugins/code-quality/plugin.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://github.com/total-recall/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "code-quality",
+  "name": "Code Quality & SSSS Conformance",
+  "version": "1.0.0",
+  "description": "Local-first code quality gates, SSSS schema verification, and invariant enforcement",
+  "author": "Total Recall Ecosystem",
+  "license": "MIT",
+  "ssss_schemas": {
+    "categories": [
+      {
+        "name": "quality-gates",
+        "description": "Custom quality-gates memory nodes for Code Quality & SSSS Conformance",
+        "node_type": "memory"
+      }
+    ]
+  },
+  "cli": {
+    "command": "code-quality",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      {
+        "name": "status",
+        "description": "Show Code Quality & SSSS Conformance status"
+      }
+    ]
+  },
+  "tasks": [
+    {
+      "intent": "Periodic health verification for code-quality",
+      "schedule": "0 * * * *"
+    }
+  ]
+}

package/scaffold/.agent/plugins/git-sentinel/README.md

@@ -0,0 +1,16 @@
+# Git Sentinel & Repo Watchdog
+
+> Continuous repository auditor checking dirty worktrees, unpushed commits, and stale branches
+
+## Installation
+
+```bash
+npx total-recall plugin install ./.agent/plugins/git-sentinel --link
+```
+
+## Features
+
+- **Identifier**: `git-sentinel`
+- **Version**: 1.0.0
+- **SSSS Category**: `repo-audits`
+- **CLI Command**: `npx total-recall git-sentinel`

package/scaffold/.agent/plugins/git-sentinel/cli.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+
+function git(args, cwd = process.cwd()) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    }).trim();
+  } catch (err) {
+    return null;
+  }
+}
+
+export async function run(argv = []) {
+  const args = Array.isArray(argv) ? argv.slice(2) : [];
+  const clean = args.filter(a => a !== 'git-sentinel' && a !== 'sentinel');
+  const isJson = clean.includes('--json');
+  const action = clean.find(a => !a.startsWith('--')) || 'audit';
+
+  const cwd = process.cwd();
+  const isInsideWorkTree = git(['rev-parse', '--is-inside-work-tree'], cwd) === 'true';
+
+  if (!isInsideWorkTree) {
+    console.error('❌ Current directory is not a Git repository.');
+    process.exit(1);
+  }
+
+  const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd) || 'unknown';
+  const statusOutput = git(['status', '--porcelain'], cwd) || '';
+  const lines = statusOutput.split('\n').filter(Boolean);
+
+  const staged = lines.filter(l => l.match(/^[MADRC]/)).length;
+  const unstaged = lines.filter(l => l.match(/^.[MADRCU?]/) && !l.startsWith('??')).length;
+  const untracked = lines.filter(l => l.startsWith('??')).length;
+  const isClean = lines.length === 0;
+
+  const unpushedOutput = git(['log', '@{u}..HEAD', '--oneline'], cwd);
+  const unpushedCount = unpushedOutput ? unpushedOutput.split('\n').filter(Boolean).length : 0;
+
+  const stashOutput = git(['stash', 'list'], cwd);
+  const stashCount = stashOutput ? stashOutput.split('\n').filter(Boolean).length : 0;
+
+  const lastCommit = git(['log', '-1', '--format=%h — %s (%cr)'], cwd) || 'No commits yet';
+
+  const auditReport = {
+    branch,
+    isClean,
+    unpushedCommits: unpushedCount,
+    stagedFiles: staged,
+    unstagedFiles: unstaged,
+    untrackedFiles: untracked,
+    totalDirty: lines.length,
+    stashCount,
+    lastCommit,
+    timestamp: new Date().toISOString()
+  };
+
+  if (isJson) {
+    console.log(JSON.stringify(auditReport, null, 2));
+    return;
+  }
+
+  if (action === 'diff') {
+    const diffStat = git(['diff', '--stat'], cwd);
+    console.log('\n🔍 Git Sentinel — Working Tree Changes:\n');
+    console.log(diffStat || '  No unstaged changes.\n');
+    return;
+  }
+
+  console.log('\n🛡️  Total Recall — Git Sentinel Repository Health\n');
+  console.log(`  Active Branch:      \x1b[36m${branch}\x1b[0m`);
+  console.log(`  Worktree State:     ${isClean ? '\x1b[32mClean ✅\x1b[0m' : `\x1b[33mDirty (${lines.length} modified/untracked files) ⚠️\x1b[0m`}`);
+  if (!isClean) {
+    console.log(`    - Staged files:   ${staged}`);
+    console.log(`    - Unstaged files: ${unstaged}`);
+    console.log(`    - Untracked:      ${untracked}`);
+  }
+  console.log(`  Unpushed Commits:   ${unpushedCount === 0 ? 'Up to date with upstream ✅' : `\x1b[33m${unpushedCount} commit(s) ahead ⬆️\x1b[0m`}`);
+  console.log(`  Stash Stack:        ${stashCount} saved stashes`);
+  console.log(`  Head Commit:        ${lastCommit}\n`);
+}
+
+export default run;

package/scaffold/.agent/plugins/git-sentinel/plugin.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://github.com/total-recall/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "git-sentinel",
+  "name": "Git Sentinel & Repo Watchdog",
+  "version": "1.0.0",
+  "description": "Continuous repository auditor checking dirty worktrees, unpushed commits, and stale branches",
+  "author": "Total Recall Ecosystem",
+  "license": "MIT",
+  "ssss_schemas": {
+    "categories": [
+      {
+        "name": "repo-audits",
+        "description": "Custom repo-audits memory nodes for Git Sentinel & Repo Watchdog",
+        "node_type": "memory"
+      }
+    ]
+  },
+  "cli": {
+    "command": "git-sentinel",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      {
+        "name": "status",
+        "description": "Show Git Sentinel & Repo Watchdog status"
+      }
+    ]
+  },
+  "tasks": [
+    {
+      "intent": "Periodic health verification for git-sentinel",
+      "schedule": "0 * * * *"
+    }
+  ]
+}

package/scaffold/.agent/plugins/meta-harness/README.md

@@ -0,0 +1,16 @@
+# Meta Harness & Agent Orchestrator
+
+> Orchestrates and delegates tasks across connected AI harnesses (Antigravity, Claude Code, Codex, Ollama)
+
+## Installation
+
+```bash
+npx total-recall plugin install ./.agent/plugins/meta-harness --link
+```
+
+## Features
+
+- **Identifier**: `meta-harness`
+- **Version**: 1.0.0
+- **SSSS Category**: `mesh-delegations`
+- **CLI Command**: `npx total-recall meta-harness`

package/scaffold/.agent/plugins/meta-harness/cli.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { auditClusterCapabilities, HARNESS_SPECS } from '../../../src/core/meta-harness.mjs';
+
+export async function run(argv = []) {
+  const args = Array.isArray(argv) ? argv.slice(2) : [];
+  const clean = args.filter(a => a !== 'meta-harness' && a !== 'harness');
+  const isJson = clean.includes('--json');
+  const sub = clean.find(a => !a.startsWith('--')) || 'status';
+
+  if (sub === 'status' || sub === 'audit' || sub === 'list') {
+    const report = auditClusterCapabilities();
+    if (isJson) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+
+    console.log('\n🤖 Total Recall — Meta Harness Runtimes & Agent Ecosystem\n');
+    console.log(`  Local Host Architecture: ${report.local.arch}`);
+    console.log(`  Total Harnesses Known:   ${report.local.harnesses.length}\n`);
+
+    for (const h of report.local.harnesses) {
+      const icon = h.available ? '✅ Available  ' : '❌ Not Found  ';
+      const pathStr = h.binaryPath ? `(${h.binaryPath})` : '';
+      console.log(`  ${icon} \x1b[1;36m${h.id.padEnd(8)}\x1b[0m ${h.name} ${pathStr}`);
+      console.log(`             Role: ${h.category} | ${h.description}`);
+    }
+    console.log('\n  Run dispatch: npx total-recall harness dispatch <harness> "<prompt>"\n');
+    return;
+  }
+
+  console.log('\nUsage: npx total-recall harness [status|audit]\n');
+}
+
+export default run;

package/scaffold/.agent/plugins/meta-harness/plugin.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://github.com/total-recall/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "meta-harness",
+  "name": "Meta Harness & Agent Orchestrator",
+  "version": "1.0.0",
+  "description": "Orchestrates and delegates tasks across connected AI harnesses (Antigravity, Claude Code, Codex, Ollama)",
+  "author": "Total Recall Ecosystem",
+  "license": "MIT",
+  "ssss_schemas": {
+    "categories": [
+      {
+        "name": "mesh-delegations",
+        "description": "Custom mesh-delegations memory nodes for Meta Harness & Agent Orchestrator",
+        "node_type": "memory"
+      }
+    ]
+  },
+  "cli": {
+    "command": "meta-harness",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      {
+        "name": "status",
+        "description": "Show Meta Harness & Agent Orchestrator status"
+      }
+    ]
+  },
+  "tasks": [
+    {
+      "intent": "Periodic health verification for meta-harness",
+      "schedule": "0 * * * *"
+    }
+  ]
+}

package/scaffold/.agent/plugins/system-monitor/README.md

@@ -0,0 +1,16 @@
+# System Monitor & Telemetry
+
+> Real-time host resource metrics, memory watchdog, and dynamic system telemetry context generator
+
+## Installation
+
+```bash
+npx total-recall plugin install ./.agent/plugins/system-monitor --link
+```
+
+## Features
+
+- **Identifier**: `system-monitor`
+- **Version**: 1.0.0
+- **SSSS Category**: `system-metrics`
+- **CLI Command**: `npx total-recall system-monitor`

package/scaffold/.agent/plugins/system-monitor/cli.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import os from 'node:os';
+import process from 'node:process';
+
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+
+function formatUptime(seconds) {
+  const d = Math.floor(seconds / (3600 * 24));
+  const h = Math.floor((seconds % (3600 * 24)) / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = Math.floor(seconds % 60);
+  const parts = [];
+  if (d > 0) parts.push(`${d}d`);
+  if (h > 0) parts.push(`${h}h`);
+  if (m > 0) parts.push(`${m}m`);
+  parts.push(`${s}s`);
+  return parts.join(' ');
+}
+
+export async function run(argv = []) {
+  const args = Array.isArray(argv) ? argv.slice(2) : [];
+  const sub = (args[0] === 'system-monitor' || args[0] === 'monitor') ? (args[1] || 'status') : (args[0] || 'status');
+
+  if (sub === 'status' || sub === 'stats' || sub === 'info') {
+    const totalMem = os.totalmem();
+    const freeMem = os.freemem();
+    const usedMem = totalMem - freeMem;
+    const memPercent = ((usedMem / totalMem) * 100).toFixed(1);
+    const load = os.loadavg().map(l => l.toFixed(2)).join(', ');
+    const cpus = os.cpus();
+    const memUsage = process.memoryUsage();
+
+    console.log('\n📊 Total Recall — System Monitor Telemetry\n');
+    console.log(`  Host OS:         ${os.type()} ${os.release()} (${os.arch()})`);
+    console.log(`  Hostname:        ${os.hostname()}`);
+    console.log(`  CPU Cores:       ${cpus.length} cores (${cpus[0]?.model || 'Unknown CPU'})`);
+    console.log(`  Load Average:    ${load} (1m, 5m, 15m)`);
+    console.log(`  System Uptime:   ${formatUptime(os.uptime())}`);
+    console.log(`  RAM Usage:       ${formatBytes(usedMem)} / ${formatBytes(totalMem)} (${memPercent}% used)`);
+    console.log(`  Free RAM:        ${formatBytes(freeMem)}`);
+    console.log(`  Process RSS:     ${formatBytes(memUsage.rss)} (Heap: ${formatBytes(memUsage.heapUsed)} / ${formatBytes(memUsage.heapTotal)})`);
+    console.log(`  Node.js:         ${process.version}\n`);
+    return;
+  }
+
+  if (sub === 'sample' || sub === 'record' || sub === '--json') {
+    const totalMem = os.totalmem();
+    const freeMem = os.freemem();
+    const usedMem = totalMem - freeMem;
+    const memPercent = ((usedMem / totalMem) * 100).toFixed(1);
+    const load = os.loadavg();
+
+    const sample = {
+      timestamp: new Date().toISOString(),
+      hostname: os.hostname(),
+      platform: os.platform(),
+      uptimeSeconds: os.uptime(),
+      loadAvg: load,
+      memory: {
+        total: totalMem,
+        free: freeMem,
+        usedPercent: Number(memPercent)
+      }
+    };
+
+    console.log(JSON.stringify(sample, null, 2));
+    return;
+  }
+
+  console.log(`\nUsage: npx total-recall system-monitor [status|sample]\n`);
+}
+
+export default run;

package/scaffold/.agent/plugins/system-monitor/generator.mjs

@@ -0,0 +1,20 @@
+import os from 'node:os';
+
+/**
+ * Context generator for System Monitor & Telemetry.
+ * Invoked during evolving context compilation.
+ */
+export async function generateContext({ projectRoot, nodes = [] }) {
+  const load = os.loadavg().map(l => l.toFixed(2)).join(', ');
+  const freeMb = Math.round(os.freemem() / (1024 * 1024));
+  const totalMb = Math.round(os.totalmem() / (1024 * 1024));
+  const usedPercent = Math.round(((totalMb - freeMb) / totalMb) * 100);
+
+  return `#### System Telemetry & Resource Status
+- Host Platform: ${os.type()} ${os.arch()} (${os.cpus().length} vCPUs)
+- CPU Load Avg: ${load} (1m, 5m, 15m)
+- Host Memory: ${freeMb} MB free / ${totalMb} MB total (${usedPercent}% utilized)
+- Monitored SSSS Metrics Nodes: ${nodes.length}
+`;
+}
+export default generateContext;

package/scaffold/.agent/plugins/system-monitor/plugin.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://github.com/total-recall/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "system-monitor",
+  "name": "System Monitor & Telemetry",
+  "version": "1.0.0",
+  "description": "Real-time host resource metrics, memory watchdog, and dynamic system telemetry context generator",
+  "author": "Total Recall Ecosystem",
+  "license": "MIT",
+  "ssss_schemas": {
+    "categories": [
+      {
+        "name": "system-metrics",
+        "description": "Custom system-metrics memory nodes for System Monitor & Telemetry",
+        "node_type": "memory"
+      }
+    ]
+  },
+  "cli": {
+    "command": "system-monitor",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      {
+        "name": "status",
+        "description": "Show System Monitor & Telemetry status"
+      }
+    ]
+  },
+  "compile": {
+    "generator": "./generator.mjs",
+    "auto": true
+  },
+  "tasks": [
+    {
+      "intent": "Periodic health verification for system-monitor",
+      "schedule": "0 * * * *"
+    }
+  ]
+}

package/scaffold/.agent/skills/meta-harness/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: meta-harness
+description: Meta Harness & Agent Management Layer to orchestrate and delegate tasks across all connected IDE harnesses (Antigravity, Claude Code, Codex, Gemini, Ollama) and the computer generally.
+---
+
+# Meta Harness & Agent Management Layer
+
+The **Meta Harness** provides a unified agent management layer across all connected developer environments, CLI runtimes, and the computer generally.
+
+## 🎯 Architectural Concept
+
+Total Recall connects to every major IDE, CLI harness, and local neural runtime:
+- **Google Antigravity (`agy`)**: Frontier multi-step reasoning, web grounding, and deep research on AI Ultra.
+- **Claude Code (`claude`)**: Direct terminal codebase refactoring, bash tool execution, and complex Unix tasks.
+- **OpenAI Codex (`codex`)**: Program synthesis, sandboxed workspace mutations, and isolated code generation.
+- **Google Gemini CLI (`gemini`)**: Fast utility completions and lightweight tool chaining.
+- **Ollama Local LLM (`ollama`)**: Zero-token-cost local neural reasoning (e.g. `gemma4:latest`) running non-interactively via standard input piping (`pipe_stdin`).
+- **IDE Surfaces**: Cursor (`.cursorrules`), Cline (`.clinerules`), VS Code (`copilot-instructions.md`), DeepSeek Harness (`dsh`).
+
+### The Shared Brain Principle
+Because all harnesses operate over the **same portable brain**:
+- Every harness reads the same auto-compiled instruction surface (`AGENTS.md`, `GEMINI.md`, `CLAUDE.md`).
+- Every harness writes directly into the shared SSSS memory vault (`memory-vault/`).
+- Knowledge or solutions learned by one agent in one harness are immediately accessible to every other harness across the computer and mesh.
+
+---
+
+## 🛠️ CLI Operations
+
+### 1. Inspect Active Harnesses
+Inspect all available developer harnesses and their local binary paths:
+```bash
+npx total-recall harness list
+```
+
+### 2. Headless Task Dispatch
+Dispatch a specific coding or research task to any external harness (locally or remotely over the mesh):
+```bash
+# Local dispatches
+npx total-recall harness dispatch claude "Inspect src/core/surface.mjs and run lint checks"
+npx total-recall harness dispatch agy "Analyze latest preprints on room temperature diamond NV registers"
+npx total-recall harness dispatch codex "Generate unit tests for src/core/context-cache.mjs"
+npx total-recall harness dispatch ollama "Summarize the core invariants of SSSS"
+
+# Cross-mesh remote dispatches
+npx total-recall harness dispatch ollama --node macmini "What is test-time compute scaling?"
+npx total-recall harness dispatch claude --node macmini "Run git status and lint tests"
+```
+
+### 3. Multi-Harness Council
+Run a task across multiple harnesses concurrently to obtain comparative solutions and consensus:
+```bash
+npx total-recall harness council "Propose architecture for decentralized research mesh"
+```
+
+---
+
+## 🤖 Agent Process Management
+
+Manage background subagent tasks across the local machine and remote mesh nodes:
+
+### 1. Spawn a Background Agent
+```bash
+# Local background agent
+npx total-recall agent spawn claude "Refactor error handling in src/cli/harness.mjs" --name "Refactor Worker"
+
+# Remote background agent on a mesh node
+npx total-recall agent spawn agy --node macmini "Crawl recent preprints on quantum shuttling" --name "Quantum Scout"
+```
+
+### 2. Inspect Running Agents
+```bash
+npx total-recall agent list
+npx total-recall agent list --json
+```
+
+### 3. Stream Agent Logs
+```bash
+npx total-recall agent logs <agent-id> --tail 100
+```
+
+### 4. Terminate an Agent
+```bash
+npx total-recall agent kill <agent-id>
+```
+
+---
+
+## 🌐 Headscale Mesh Diagnostics & Remote Execution
+
+The Meta Harness integrates directly with your private Headscale WireGuard mesh network:
+
+### 1. Cluster Capability Audit (`mesh doctor`)
+Concurrently audit reachability, developer runtimes (`node`, `docker`, `git`), and AI harnesses (`agy`, `claude`, `codex`, `gemini`, `ollama`) across all cluster nodes:
+```bash
+npx total-recall mesh doctor
+npx total-recall mesh doctor --json
+```
+
+### 2. Non-Interactive Remote Command Execution (`mesh exec`)
+Execute commands on remote nodes with automatic `$PATH` sanitization and structured outputs:
+```bash
+npx total-recall mesh exec macmini uname -m
+npx total-recall mesh exec cloud docker ps
+```
+
+---
+
+## 💻 General Computer & OS Management
+The Meta Harness controls the computer generally:
+- **Activity Monitoring ("Follow the User")**: Tracks interaction timestamps and routes dispatches to the active device across the Headscale WireGuard mesh.
+- **Process Orchestration**: Spawns background worker loops, monitors task completion, and terminates runaway processes.
+- **Surface Sync**: Recompiles instruction surfaces across all IDE directories automatically upon graph updates.

package/scaffold/.agent/skills/total-recall/references/cli-reference.md

@@ -38,6 +38,29 @@ Run system diagnostic suites and heal environment inconsistencies.
 Manually resolve quarantined memory conflicts.
 *   **Syntax**: `npx total-recall resolve --supersede <node-slug> | --keep <node-slug>`
 
+### 1.6 `mesh`
+Control-server (Headscale) mesh administration, cluster capability auditing, and remote execution.
+*   **Syntax**: `npx total-recall mesh <status|doctor|nodes|ssh|exec|access|preauthkey|policy> [options]`
+*   **Key Subcommands**:
+    *   `mesh doctor [--json]`: Audit SSH reachability, runtimes (`node`, `docker`, `git`), and AI harnesses across all mesh nodes.
+    *   `mesh exec <node> [--json] <cmd…>`: Non-interactive remote command execution over WireGuard SSH.
+    *   `mesh ssh <node> [cmd…]`: Interactive or one-shot SSH session using recorded node credentials.
+
+### 1.7 `harness`
+Meta-harness orchestration layer across connected IDEs, CLI agents, and local neural runtimes.
+*   **Syntax**: `npx total-recall harness <list|dispatch|council> [options]`
+*   **Supported Harnesses**: `agy` (Google Antigravity), `claude` (Claude Code), `codex` (OpenAI Codex), `gemini` (Google Gemini), `ollama` (Local Neural Models via `pipe_stdin`).
+*   **Options**:
+    *   `--node <node>`: Route harness execution remotely to a target mesh node.
+
+### 1.8 `agent`
+Process controller for background agent tasks across the local machine and remote mesh nodes.
+*   **Syntax**: `npx total-recall agent <list|spawn|status|logs|kill> [options]`
+*   **Key Subcommands**:
+    *   `agent spawn <harness> [--node <node>] [--name <label>] "<task>"`: Spawn a background subagent task.
+    *   `agent logs <id> [--tail <n>]`: Stream agent execution logs locally or over mesh SSH.
+    *   `agent kill <id|pid>`: Terminate an active agent process locally or across the mesh.
+
 ---
 
 ## 2. REST API Specification