total-recall-brain 3.28.2 → 3.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.28.2",
+  "version": "3.30.1",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [
@@ -22,6 +22,7 @@
     "frontend/index.html",
     "frontend/src/",
     "extension/",
+    "plugins/",
     "templates/",
     "scaffold/",
     "docs/ARCHITECTURE.md",

package/plugins/code-quality/README.md

@@ -0,0 +1,25 @@
+# Code Quality Report
+
+Prints the latest report from the `code-quality` skill's background gates in the current repository. It only reads results; it never starts a typecheck or lint run. Requires `.agent/skills/code-quality/` in the repository.
+
+**Use cases:** software-development
+
+## Install
+
+```bash
+npx total-recall plugin install code-quality
+```
+
+## Use
+
+```bash
+npx total-recall code-quality report
+```
+
+## Share with your other nodes
+
+```bash
+npx total-recall plugin share code-quality
+# on another node on the mesh:
+npx total-recall plugin install peer:<this-node>/code-quality
+```

package/plugins/code-quality/cli.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Prints the latest report written by the code-quality skill's background
+// gates. The report script only reads results; it never starts a check.
+export async function run() {
+  const scriptPath = path.resolve(process.cwd(), '.agent/skills/code-quality/scripts/report.mjs');
+  if (!fs.existsSync(scriptPath)) {
+    console.error(`No code-quality skill in ${process.cwd()} (expected ${scriptPath}).`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const out = execFileSync(process.execPath, [scriptPath], { encoding: 'utf8', cwd: process.cwd() });
+    console.log(out);
+  } catch (err) {
+    if (err.stdout) console.log(err.stdout);
+    console.error(err.stderr || err.message);
+    process.exitCode = err.status || 1;
+  }
+}
+
+export default run;

package/plugins/code-quality/plugin.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "code-quality",
+  "name": "Code Quality Report",
+  "version": "1.1.0",
+  "description": "Shows the latest code-quality gate report for a repository that has the code-quality skill installed.",
+  "author": "Total Recall",
+  "license": "MIT",
+  "use_cases": ["software-development"],
+  "cli": {
+    "command": "code-quality",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      { "name": "report", "description": "Print the latest gate report from .agent/skills/code-quality" }
+    ]
+  }
+}

package/plugins/git-sentinel/README.md

@@ -0,0 +1,27 @@
+# Git Sentinel
+
+Reports the state of the git repository you run it in: current branch, staged / unstaged / untracked files, commits not yet pushed to upstream, and stashes.
+
+**Use cases:** software-development
+
+## Install
+
+```bash
+npx total-recall plugin install git-sentinel
+```
+
+## Use
+
+```bash
+npx total-recall git-sentinel audit          # human summary
+npx total-recall git-sentinel audit --json   # machine output for agents
+npx total-recall git-sentinel diff           # diffstat of unstaged changes
+```
+
+## Share with your other nodes
+
+```bash
+npx total-recall plugin share git-sentinel
+# on another node on the mesh:
+npx total-recall plugin install peer:<this-node>/git-sentinel
+```

package/{scaffold/.agent/plugins → plugins}/git-sentinel/cli.mjs

@@ -15,8 +15,8 @@ function git(args, cwd = process.cwd()) {
 }
 
 export async function run(argv = []) {
-  const args = Array.isArray(argv) ? argv.slice(2) : [];
-  const clean = args.filter(a => a !== 'git-sentinel' && a !== 'sentinel');
+  // argv: ["node", "total-recall", "git-sentinel", "<subcommand>", ...flags]
+  const clean = Array.isArray(argv) ? argv.slice(3) : [];
   const isJson = clean.includes('--json');
   const action = clean.find(a => !a.startsWith('--')) || 'audit';
 
@@ -24,8 +24,11 @@ export async function run(argv = []) {
   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);
+    // Report and set the exit code; never process.exit() — a host that runs
+    // this in-process would be stopped with it.
+    console.error(`${cwd} is not inside a git repository.`);
+    process.exitCode = 1;
+    return;
   }
 
   const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd) || 'unknown';
@@ -70,7 +73,7 @@ export async function run(argv = []) {
     return;
   }
 
-  console.log('\n🛡️  Total Recall — Git Sentinel Repository Health\n');
+  console.log('\n🛡️  Git Sentinel — Repository State\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) {

package/plugins/git-sentinel/plugin.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "git-sentinel",
+  "name": "Git Sentinel",
+  "version": "1.1.0",
+  "description": "Reports the state of the current git repository: branch, dirty files, unpushed commits and stashes.",
+  "author": "Total Recall",
+  "license": "MIT",
+  "use_cases": ["software-development"],
+  "cli": {
+    "command": "git-sentinel",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      { "name": "audit", "description": "Summarise branch, worktree, upstream and stash state (--json for machine output)" },
+      { "name": "diff", "description": "Show a diffstat of unstaged changes" }
+    ]
+  }
+}

package/plugins/system-monitor/README.md

@@ -0,0 +1,26 @@
+# System Monitor
+
+Adds a host-resources block (load average, free memory) to the compiled agent context, and records one JSON telemetry sample every 15 minutes. Samples are kept in the brain's `plugin.task_run` event log.
+
+**Use cases:** operations, self-hosting
+
+## Install
+
+```bash
+npx total-recall plugin install system-monitor
+```
+
+## Use
+
+```bash
+npx total-recall system-monitor status   # human summary
+npx total-recall system-monitor sample   # one JSON sample
+```
+
+## Share with your other nodes
+
+```bash
+npx total-recall plugin share system-monitor
+# on another node on the mesh:
+npx total-recall plugin install peer:<this-node>/system-monitor
+```

package/{scaffold/.agent/plugins → plugins}/system-monitor/cli.mjs

@@ -24,8 +24,8 @@ function formatUptime(seconds) {
 }
 
 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');
+  // argv: ["node", "total-recall", "system-monitor", "<subcommand>"]
+  const sub = (Array.isArray(argv) ? argv[3] : null) || 'status';
 
   if (sub === 'status' || sub === 'stats' || sub === 'info') {
     const totalMem = os.totalmem();
@@ -36,7 +36,7 @@ export async function run(argv = []) {
     const cpus = os.cpus();
     const memUsage = process.memoryUsage();
 
-    console.log('\n📊 Total Recall — System Monitor Telemetry\n');
+    console.log('\n📊 System Monitor\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'})`);
@@ -73,7 +73,8 @@ export async function run(argv = []) {
     return;
   }
 
-  console.log(`\nUsage: npx total-recall system-monitor [status|sample]\n`);
+  console.error(`Unknown subcommand '${sub}'. Usage: npx total-recall system-monitor [status|sample]`);
+  process.exitCode = 1;
 }
 
 export default run;

package/{scaffold/.agent/plugins → plugins}/system-monitor/generator.mjs

@@ -1,20 +1,19 @@
 import os from 'node:os';
 
 /**
- * Context generator for System Monitor & Telemetry.
- * Invoked during evolving context compilation.
+ * Context generator for System Monitor.
+ * Invoked during surface compilation, so values are as of the last compile.
  */
-export async function generateContext({ projectRoot, nodes = [] }) {
+export async function generateContext() {
   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
+  return `#### Host Resources (as of ${new Date().toISOString()})
 - 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/plugins/system-monitor/plugin.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "system-monitor",
+  "name": "System Monitor",
+  "version": "1.1.0",
+  "description": "Host load and memory in the compiled agent context, plus a telemetry sample recorded every 15 minutes.",
+  "author": "Total Recall",
+  "license": "MIT",
+  "use_cases": ["operations", "self-hosting"],
+  "cli": {
+    "command": "system-monitor",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      { "name": "status", "description": "Human-readable host resource summary" },
+      { "name": "sample", "description": "One JSON telemetry sample" }
+    ]
+  },
+  "compile": {
+    "generator": "./generator.mjs",
+    "auto": true
+  },
+  "tasks": [
+    {
+      "intent": "Record a host telemetry sample (kept in the plugin.task_run event log)",
+      "schedule": "*/15 * * * *",
+      "command": "sample"
+    }
+  ]
+}

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

@@ -43,8 +43,8 @@ npx total-recall harness dispatch codex "Generate unit tests for src/core/contex
 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"
+npx total-recall harness dispatch ollama --node build-box "What is test-time compute scaling?"
+npx total-recall harness dispatch claude --node build-box "Run git status and lint tests"
 ```
 
 ### 3. Multi-Harness Council
@@ -65,7 +65,7 @@ Manage background subagent tasks across the local machine and remote mesh nodes:
 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"
+npx total-recall agent spawn agy --node build-box "Crawl recent preprints on quantum shuttling" --name "Quantum Scout"
 ```
 
 ### 2. Inspect Running Agents
@@ -100,7 +100,7 @@ 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 build-box uname -m
 npx total-recall mesh exec cloud docker ps
 ```
 

package/scaffold/.agent/skills/plugins/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: plugins
+description: Create, validate, install, run, and share Total Recall plugins. Use when a user wants a plugin that adds a useful command, scheduled task, agent context, or SSSS memory category.
+---
+
+# Total Recall plugins
+
+Build a plugin for a concrete user job. Start by stating the command, context, task, or memory category it adds and how a user will tell that it works. Do not add a plugin solely to populate a gallery.
+
+## Where to work
+
+Run `total-recall plugin create <id> --name "..." --description "..." --use-case <tag> --with-cli` to scaffold an installed plugin. The CLI creates a directory under the current project's `.agent/skills/total-recall/plugins/`; `--global` creates a machine-wide plugin. A plugin is a folder containing `plugin.json` and the files its manifest names. For a plugin intended to ship with Total Recall itself, use the package's `plugins/<id>/` folder and add a real install and use test.
+
+Inspect the installed package's `metadata.plugin.schema.json` and `src/core/plugin-loader.mjs` for the current executable contract before changing a manifest. The schema supports:
+
+```json
+{
+  "id": "example-plugin",
+  "name": "Example Plugin",
+  "version": "1.0.0",
+  "description": "The specific job this plugin does.",
+  "author": "Author name",
+  "license": "MIT",
+  "use_cases": ["research"],
+  "cli": {
+    "command": "example-plugin",
+    "handler": "./cli.mjs",
+    "subcommands": [{ "name": "status", "description": "Show current status" }]
+  }
+}
+```
+
+An ID is lowercase kebab case, starts with a letter, and is 2–64 characters. `use_cases` are descriptive kebab-case tags. Keep the manifest honest: declare only features the plugin implements. `README.md` should explain the user job, prerequisites, commands, outputs, and any data or network access.
+
+## Implement a capability
+
+- **Command:** export `async function run(argv)` from the `cli.handler` module. It receives `['node', 'total-recall', '<command>', '<subcommand>', ...]`. A default-exported function is also supported and receives arguments after the command. Return a result or set `process.exitCode` on failure. The runner isolates the handler in a child process, with a timeout and output cap.
+- **Scheduled task:** add `tasks: [{ "intent": "...", "schedule": "*/15 * * * *", "command": "sample" }]`. `command` is a subcommand implemented by the plugin's CLI handler. The daemon runs it once per due minute slot and records the outcome as a `plugin.task_run` event. Keep tasks bounded and idempotent.
+- **Agent context:** add `compile: { "generator": "./generator.mjs", "auto": true }` and export `generateContext()` from that file. Only include information useful to the agent; avoid secrets and noisy telemetry.
+- **Memory category:** declare it under `ssss_schemas.categories` using the current manifest schema. Preserve SSSS Markdown and operation-contract writes; do not write vault documents directly.
+
+## Validate the actual job
+
+1. Validate `plugin.json` against the installed schema and `total-recall plugin info <id>`.
+2. Install in a clean temporary project, then run the declared command through `total-recall <command> <subcommand>`. For tasks, verify one due run and its event. For context generators, compile and inspect the resulting block.
+3. Exercise failure paths: missing prerequisite, invalid input, timeout, and any network failure. A plugin that installs but cannot do its advertised job is unfinished.
+4. Review the plugin's file set before sharing. Plugin code has the recipient's process permissions when run. Never bundle secrets, browser profiles, vault data, or machine-specific paths.
+
+## Share with another user
+
+`total-recall plugin share <id>` marks an installed plugin shareable. Configure `TR_PUBLIC_BASE_URL` as the node's externally reachable HTTPS origin; the command and dashboard then show a direct link ending in `#sha256=<content hash>`. Send that link to the recipient. They install with `total-recall plugin install '<link>'`. The installer requires HTTPS, rejects private destination addresses and redirects, caps the bundle size, and verifies the pinned SHA-256 before writing files. There is no central catalog. The hosting node must actually be reachable at its configured HTTPS origin.
+
+`total-recall plugin unshare <id>` stops serving the bundle. Existing installations remain on recipients' machines. Users on one private mesh may also use `peer:<host>/<id>`; mesh membership is not required for public sharing.

package/scaffold/.agent/skills/total-recall/SKILL.md

@@ -181,6 +181,10 @@ npx total-recall compile
 ```
 Synchronously rebuild the entire memory index (derived embeddings) and regenerate prompt instruction shims (such as `INSTRUCTIONS.md`, `GEMINI.md`, `AGENTS.md`, etc.).
 
+*   **Rules are global + local.** Every project's shims carry the global brain's invariants, preferences and corrections plus the project's own; a project node with the same slug overrides the global one.
+*   `compile --global` (what `remember --global` runs) and `compile --all` also recompile every registered project, so a global rule reaches every repo at once.
+*   A client gets a shim only once it is connected (`total-recall connect claude-code|codex|antigravity|…` in that repo). No `CLAUDE.md` in a repo means Claude Code was never connected there.
+
 ### 5. Ingest OKF Bundle
 ```bash
 npx total-recall ingest okf <path> [options]
@@ -394,11 +398,23 @@ transcript. `set`, `rotate` and `rekey` all accept it.
 ### Master password and `rekey`
 
 The store is AES-256-GCM; the key is scrypt-derived (N=2^16, ~64 MB) from
-`TR_SECRETS_PASSWORD`. On macOS the password belongs in the **Keychain**
-(`security add-generic-password -s total-recall-secrets`), not in a dotfile —
-`rekey` picks the Keychain entry up automatically and rotates every carrier
-(LaunchAgent plist, env file, Keychain) in one transaction, verifying the
-retired password no longer decrypts before it commits.
+the master password, resolved in this order:
+
+1. `TR_SECRETS_PASSWORD` / `TR_MASTER_PASSWORD` in the environment (a
+   LaunchAgent plist injects it for launchd jobs);
+2. macOS: the **Keychain** entry `total-recall-secrets`
+   (`security add-generic-password -s total-recall-secrets`). An ssh or mesh
+   session cannot read a locked login Keychain;
+3. Linux and headless hosts: the env file `~/.agent/tr.env` (or `TR_ENV_FILE`)
+   containing `export TR_SECRETS_PASSWORD='…'`. It is used only when it is a
+   regular file, mode 0600, owned by you, in a directory (keep `~/.agent` 0700)
+   nobody else can write. Do not also export it from `.bashrc` — every process
+   started from the shell would inherit it.
+
+`rekey` rotates every carrier (LaunchAgent plist, `--env-file`, Keychain) in one
+transaction, verifying the retired password no longer decrypts before it
+commits. No carrier on a machine means every command fails with "Secrets file
+is not valid JSON" and `mesh` falls back to local discovery.
 
 > **Processes hold the old password until restarted.** After a rekey, anything
 > still running with the retired value fails with `Failed to decrypt secrets
@@ -584,7 +600,7 @@ npm test                    # vitest run — whole suite
 npx vitest run <path>       # one spec file
 ```
 
-Current baseline: **288 spec files / 1493 tests, ~160 s** on the Mac Mini.
+Current baseline (3.30.1): **349 spec files / 2024 tests, ~160 s** on the Mac Mini.
 
 > **Never run the full suite, a full typecheck, or a production build on the
 > laptop.** These go to the Mac Mini or the droplet — local runs cause slowdowns

package/scaffold/.agent/skills/total-recall/scripts/brain-state.json

@@ -29,6 +29,7 @@
     "backups",
     "browser-profile",
     "skills-registry",
+    "plugins",
     ".snapshots",
     ".git",
     "node_modules"

package/src/cli/agent.mjs

@@ -18,7 +18,7 @@ Commands:
   kill <id|pid>             Terminate an active agent process
 
 Options:
-  --node <name>             Target a remote mesh node (macmini, cloud, etc.)
+  --node <name>             Target a remote mesh node (build-box, cloud, etc.)
   --json                    Output machine-readable JSON for Unix pipelines
   --detach                  Spawn process detached in background (default: true)
   --name <label>            Assign a human-readable name to the agent session