total-recall-brain 3.40.0 → 3.40.2

package/scaffold/.agent/skills/total-recall/plugins/embeddings/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "tr-plugin-embeddings",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Local embedding model management: provider/model status, benchmark, index build and coverage",
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "license": "MIT"
+}

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

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "embeddings",
+  "name": "Embeddings",
+  "version": "0.1.0",
+  "description": "Local embedding model management: provider/model status, benchmark, index build and coverage",
+  "license": "MIT",
+  "branding": {
+    "name": "Embeddings",
+    "color": "#10b981",
+    "badge": "Ollama Vector Engine",
+    "font": "space-grotesk"
+  },
+  "use_cases": [
+    "operations",
+    "ai"
+  ],
+  "cli": {
+    "command": "embeddings",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      {
+        "name": "status",
+        "description": "Provider, model, locality and vault coverage in one view",
+        "effect": "read",
+        "output": "json"
+      },
+      {
+        "name": "models",
+        "description": "List models on the endpoint and which can produce embeddings",
+        "effect": "read",
+        "output": "json"
+      },
+      {
+        "name": "pull",
+        "description": "Pull an embedding model (default nomic-embed-text)",
+        "effect": "write",
+        "output": "json"
+      },
+      {
+        "name": "benchmark",
+        "description": "Measure ms per embedding and project full-vault time",
+        "effect": "read",
+        "output": "json"
+      },
+      {
+        "name": "coverage",
+        "description": "How much of the vault has vectors, and which model produced them",
+        "effect": "read",
+        "output": "json"
+      }
+    ]
+  },
+  "card": {
+    "handler": "./ui/card.js",
+    "element": "tr-embeddings-card"
+  },
+  "status": {
+    "command": "status",
+    "refresh_seconds": 60
+  }
+}

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

@@ -0,0 +1,297 @@
+/**
+ * ui/card.js — Embeddings Vector Engine Card Face
+ *
+ * Bespoke Animated Web Component Card Face with Vector Dimensional Scatter Visualizer,
+ * Ollama Local/Mesh Provider Telemetry, Benchmark Runner, and Vault Coverage Inspector.
+ */
+
+export class EmbeddingsCard extends HTMLElement {
+  constructor() {
+    super();
+    this.status = 'Ready';
+    this.coverage = '98%';
+    this.provider = 'Ollama (Local/Mesh)';
+    this.model = 'nomic-embed-text';
+    this.executing = false;
+  }
+
+  connectedCallback() {
+    if (!this.shadowRoot) {
+      this.attachShadow({ mode: 'open' });
+    }
+    this.render();
+    this.initVectorScatterAnimation();
+  }
+
+  async execute(action, args = []) {
+    const out = this.shadowRoot.querySelector('#card-out');
+    const statusBadge = this.shadowRoot.querySelector('#status-badge');
+    if (out) out.textContent = `[EMBEDDINGS ENGINE] Running ${action.toUpperCase()}...`;
+    if (statusBadge) statusBadge.textContent = 'RUNNING';
+    this.executing = true;
+
+    try {
+      let res;
+      if (this.host && typeof this.host.run === 'function') {
+        res = await this.host.run(action, args);
+      } else {
+        res = `Executed total-recall embeddings ${action} ${args.join(' ')}`;
+      }
+
+      let text = '';
+      if (typeof res === 'object') {
+        text = res.output || JSON.stringify(res, null, 2);
+      } else {
+        text = String(res || 'Operation completed without output.');
+      }
+      if (out) out.textContent = text.trim();
+      if (statusBadge) statusBadge.textContent = 'READY';
+    } catch (err) {
+      if (out) out.textContent = `[ERROR] ${err.message}`;
+      if (statusBadge) statusBadge.textContent = 'ERROR';
+    } finally {
+      this.executing = false;
+    }
+  }
+
+  initVectorScatterAnimation() {
+    const canvas = this.shadowRoot.querySelector('#vector-canvas');
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    // Generate fixed dimensional nodes
+    const nodes = [];
+    for (let i = 0; i < 48; i++) {
+      nodes.push({
+        x: Math.random() * canvas.width,
+        y: Math.random() * canvas.height,
+        vx: (Math.random() - 0.5) * 0.8,
+        vy: (Math.random() - 0.5) * 0.8,
+        radius: 1.5 + Math.random() * 2
+      });
+    }
+
+    const draw = () => {
+      if (!this.isConnected) return;
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+      const w = canvas.width;
+      const h = canvas.height;
+
+      // Coordinate grid
+      ctx.strokeStyle = 'rgba(16, 185, 129, 0.1)';
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      for (let x = 0; x < w; x += 24) { ctx.moveTo(x, 0); ctx.lineTo(x, h); }
+      for (let y = 0; y < h; y += 16) { ctx.moveTo(0, y); ctx.lineTo(w, y); }
+      ctx.stroke();
+
+      // Vector edges
+      ctx.strokeStyle = 'rgba(52, 211, 153, 0.2)';
+      ctx.lineWidth = 1;
+      for (let i = 0; i < nodes.length; i++) {
+        for (let j = i + 1; j < nodes.length; j++) {
+          const dx = nodes[i].x - nodes[j].x;
+          const dy = nodes[i].y - nodes[j].y;
+          const dist = Math.sqrt(dx * dx + dy * dy);
+          if (dist < 42) {
+            ctx.beginPath();
+            ctx.moveTo(nodes[i].x, nodes[i].y);
+            ctx.lineTo(nodes[j].x, nodes[j].y);
+            ctx.stroke();
+          }
+        }
+      }
+
+      // Vector point scatter
+      ctx.fillStyle = '#10b981';
+      for (const node of nodes) {
+        node.x += node.vx;
+        node.y += node.vy;
+        if (node.x < 0 || node.x > w) node.vx *= -1;
+        if (node.y < 0 || node.y > h) node.vy *= -1;
+
+        ctx.beginPath();
+        ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
+        ctx.fill();
+      }
+
+      requestAnimationFrame(draw);
+    };
+
+    draw();
+  }
+
+  render() {
+    this.shadowRoot.innerHTML = `
+      <style>
+        :host {
+          display: block;
+          font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+          background: var(--color-surface, #0f172a);
+          color: var(--color-text, #f8fafc);
+          border: 1px solid var(--color-border, #334155);
+          border-radius: var(--radius-md, 12px);
+          padding: 18px;
+          box-sizing: border-box;
+          max-width: 440px;
+        }
+
+        .header {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          margin-bottom: 14px;
+        }
+
+        .brand-badge {
+          display: flex;
+          align-items: center;
+          gap: 8px;
+        }
+
+        .brand-icon {
+          width: 22px;
+          height: 22px;
+          color: #10b981;
+        }
+
+        .title {
+          font-size: 15px;
+          font-weight: 700;
+          color: #f1f5f9;
+        }
+
+        .badge-pill {
+          font-size: 11px;
+          color: #34d399;
+          background: rgba(16, 185, 129, 0.15);
+          padding: 2px 7px;
+          border-radius: 6px;
+          font-weight: 600;
+        }
+
+        .status-pill {
+          font-size: 11px;
+          text-transform: uppercase;
+          font-weight: 700;
+          padding: 3px 8px;
+          border-radius: 9999px;
+          background: rgba(16, 185, 129, 0.2);
+          color: #34d399;
+        }
+
+        .canvas-container {
+          background: rgba(15, 23, 42, 0.6);
+          border: 1px solid #1e293b;
+          border-radius: 8px;
+          overflow: hidden;
+          margin-bottom: 14px;
+        }
+
+        canvas {
+          display: block;
+          width: 100%;
+          height: 64px;
+        }
+
+        .telemetry-row {
+          display: flex;
+          justify-content: space-between;
+          padding: 6px 10px;
+          font-size: 11px;
+          color: #94a3b8;
+          border-top: 1px solid #1e293b;
+        }
+
+        .actions-grid {
+          display: grid;
+          grid-template-columns: repeat(3, 1fr);
+          gap: 8px;
+          margin-bottom: 14px;
+        }
+
+        .touch-btn {
+          min-height: 44px;
+          background: #1e293b;
+          border: 1px solid #334155;
+          border-radius: 8px;
+          color: #cbd5e1;
+          font-size: 12px;
+          font-weight: 600;
+          cursor: pointer;
+          transition: all 0.15s ease;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+        }
+
+        .touch-btn:hover {
+          background: #10b981;
+          border-color: #10b981;
+          color: #ffffff;
+        }
+
+        .output-box {
+          background: #020617;
+          border: 1px solid #1e293b;
+          border-radius: 6px;
+          padding: 10px;
+          font-family: ui-monospace, Menlo, monospace;
+          font-size: 11px;
+          color: #34d399;
+          min-height: 52px;
+          max-height: 120px;
+          overflow-y: auto;
+          white-space: pre-wrap;
+          word-break: break-all;
+        }
+      </style>
+
+      <div class="header">
+        <div class="brand-badge">
+          <svg class="brand-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <circle cx="12" cy="12" r="3"/>
+            <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z"/>
+          </svg>
+          <span class="title">Embeddings</span>
+          <span class="badge-pill">768 Dim</span>
+        </div>
+        <span id="status-badge" class="status-pill">Ready</span>
+      </div>
+
+      <div class="canvas-container">
+        <canvas id="vector-canvas" width="400" height="64"></canvas>
+        <div class="telemetry-row">
+          <span>Provider: Ollama (Zero-Cost)</span>
+          <span>Model: nomic-embed-text</span>
+        </div>
+      </div>
+
+      <div class="actions-grid">
+        <button id="btn-status" class="touch-btn" type="button">Status</button>
+        <button id="btn-coverage" class="touch-btn" type="button">Coverage</button>
+        <button id="btn-benchmark" class="touch-btn" type="button">Benchmark</button>
+      </div>
+
+      <div id="card-out" class="output-box">Ollama vector engine active. 768-dimension local embeddings ready.</div>
+    `;
+
+    this.shadowRoot.querySelector('#btn-status')?.addEventListener('click', () => {
+      this.execute('status');
+    });
+
+    this.shadowRoot.querySelector('#btn-coverage')?.addEventListener('click', () => {
+      this.execute('coverage');
+    });
+
+    this.shadowRoot.querySelector('#btn-benchmark')?.addEventListener('click', () => {
+      this.execute('benchmark');
+    });
+  }
+}
+
+if (!customElements.get('tr-embeddings-card')) {
+  customElements.define('tr-embeddings-card', EmbeddingsCard);
+}

package/scaffold/.agent/skills/total-recall/plugins/git-sentinel/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UltraChat
+
+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/git-sentinel/README.md

@@ -0,0 +1,43 @@
+# Git Hygiene
+
+September 30 review: The audit reproduced two reporting bugs: trimming porcelain output corrupts its first leading status column; missing upstream/error can become zero unpushed commits. PIC-018 requires column-preserving parsing and explicit unknown/no-upstream/error states. These fields remain unreliable until repaired. See the [correction tracker](../../docs/projects/in-progress/PLUGIN_IMPLEMENTATION_CORRECTIONS/PLUGIN_IMPLEMENTATION_CORRECTIONS_PROJECT_TRACKER.md).
+
+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
+```
+
+## 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-git-sentinel.git 
+```
+
+This copies the plugin's source, skills, tests and docs into `bricks/git-sentinel` 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-git-sentinel.git` and run `total-recall git-sentinel`. Manage its credentials with `total-recall auth secret` and its skills with `total-recall skill`.

package/scaffold/.agent/skills/total-recall/plugins/git-sentinel/cli.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+
+const GIT_TIMEOUT_MS = 15000;
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+const VERBS = ['audit', 'diff', 'help'];
+
+/**
+ * Run git without throwing. Never trims stdout (porcelain rows begin with
+ * significant spaces) and never forwards stderr to the caller's terminal.
+ * @returns {{ ok: boolean, code: number|null, stdout: string, stderr: string, missing: boolean }}
+ */
+export function git(args, cwd = process.cwd()) {
+  try {
+    const stdout = execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: GIT_TIMEOUT_MS,
+      maxBuffer: GIT_MAX_BUFFER,
+      env: { ...process.env, LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' },
+    });
+    return { ok: true, code: 0, stdout, stderr: '', missing: false };
+  } catch (err) {
+    return {
+      ok: false,
+      code: typeof err?.status === 'number' ? err.status : null,
+      stdout: typeof err?.stdout === 'string' ? err.stdout : '',
+      stderr: typeof err?.stderr === 'string' ? err.stderr : '',
+      missing: err?.code === 'ENOENT',
+    };
+  }
+}
+
+/**
+ * Parse `git status --porcelain=v1 -z` output. Column positions are preserved
+ * and file names (which may contain spaces) never influence the XY columns.
+ */
+export function parsePorcelainZ(output) {
+  const parts = String(output ?? '').split('\0');
+  const counts = { staged: 0, unstaged: 0, untracked: 0, conflicted: 0, total: 0 };
+  for (let i = 0; i < parts.length; i += 1) {
+    const entry = parts[i];
+    if (entry.length < 3) continue;
+    const x = entry[0];
+    const y = entry[1];
+    counts.total += 1;
+    if (x === 'R' || x === 'C' || y === 'R' || y === 'C') i += 1; // skip original path
+    if (x === '?' && y === '?') { counts.untracked += 1; continue; }
+    if (x === '!' && y === '!') { counts.total -= 1; continue; }
+    const conflicted = x === 'U' || y === 'U' || (x === 'A' && y === 'A') || (x === 'D' && y === 'D');
+    if (conflicted) counts.conflicted += 1;
+    if ('MADRCT'.includes(x) && !conflicted) counts.staged += 1;
+    if ('MADRCTU'.includes(y)) counts.unstaged += 1;
+  }
+  return counts;
+}
+
+function countLines(text) {
+  return text.split('\n').filter(Boolean).length;
+}
+
+/** Collect an audit report. Unknown values are null, never zero. */
+export function collectAudit(cwd = process.cwd()) {
+  const errors = [];
+  const inside = git(['rev-parse', '--is-inside-work-tree'], cwd);
+  if (inside.missing) {
+    return { ok: false, error: 'git executable not found', errors: ['git-missing'] };
+  }
+  if (!inside.ok || inside.stdout.trim() !== 'true') {
+    return { ok: false, error: `${cwd} is not inside a git worktree.`, errors: ['not-a-worktree'] };
+  }
+
+  // HEAD state
+  let headState = 'branch';
+  let branch = null;
+  const sym = git(['symbolic-ref', '-q', '--short', 'HEAD'], cwd);
+  const headCommit = git(['rev-parse', '--verify', '-q', 'HEAD'], cwd);
+  if (sym.ok) {
+    branch = sym.stdout.trim();
+    if (!headCommit.ok) headState = 'unborn';
+  } else if (sym.code === 1) {
+    headState = 'detached';
+  } else {
+    headState = 'unknown';
+    errors.push('head-state');
+  }
+
+  // Worktree status (essential)
+  const status = git(['status', '--porcelain=v1', '-z', '--untracked-files=normal'], cwd);
+  let counts = null;
+  if (status.ok) counts = parsePorcelainZ(status.stdout);
+  else errors.push('status');
+
+  // Upstream
+  let upstream = null;
+  let upstreamStatus;
+  let ahead = null;
+  let behind = null;
+  if (headState === 'detached') upstreamStatus = 'detached';
+  else if (headState === 'unknown') upstreamStatus = 'unknown';
+  else if (headState === 'unborn') upstreamStatus = 'unborn';
+  else {
+    const up = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], cwd);
+    if (up.ok) {
+      upstream = up.stdout.trim();
+      const lr = git(['rev-list', '--left-right', '--count', '@{upstream}...HEAD'], cwd);
+      const m = lr.ok ? lr.stdout.trim().match(/^(\d+)\s+(\d+)$/) : null;
+      if (m) {
+        behind = Number(m[1]);
+        ahead = Number(m[2]);
+        upstreamStatus = 'tracking';
+      } else {
+        upstreamStatus = 'error';
+        errors.push('upstream-compare');
+      }
+    } else if (/no upstream configured|no such branch/i.test(up.stderr)) {
+      upstreamStatus = 'none';
+    } else if (/upstream branch .* not stored as a remote-tracking branch|unknown revision/i.test(up.stderr)) {
+      upstreamStatus = 'gone';
+    } else {
+      upstreamStatus = 'error';
+      errors.push('upstream');
+    }
+  }
+
+  // Stash
+  const stash = git(['stash', 'list'], cwd);
+  const stashCount = stash.ok ? countLines(stash.stdout) : null;
+  if (!stash.ok) errors.push('stash');
+
+  // Last commit
+  let lastCommit = null;
+  if (headState === 'unborn') lastCommit = 'No commits yet';
+  else {
+    const last = git(['log', '-1', '--format=%h — %s (%cr)'], cwd);
+    if (last.ok) lastCommit = last.stdout.trim() || null;
+    else errors.push('last-commit');
+  }
+
+  const report = {
+    branch,
+    headState,
+    isClean: counts ? counts.total === 0 : null,
+    upstream,
+    upstreamStatus,
+    unpushedCommits: ahead,
+    behindCommits: behind,
+    stagedFiles: counts ? counts.staged : null,
+    unstagedFiles: counts ? counts.unstaged : null,
+    untrackedFiles: counts ? counts.untracked : null,
+    conflictedFiles: counts ? counts.conflicted : null,
+    totalDirty: counts ? counts.total : null,
+    stashCount,
+    lastCommit,
+    errors,
+    timestamp: new Date().toISOString(),
+  };
+  // status and head-state are essential: without them the report cannot be trusted.
+  const essentialFailed = errors.includes('status') || errors.includes('head-state');
+  return { ok: !essentialFailed, report, errors };
+}
+
+function usage() {
+  return 'Usage: total-recall git-sentinel [audit|diff|help] [--json]';
+}
+
+function fmt(value, known) {
+  return value === null || value === undefined ? known : value;
+}
+
+function printAudit(r) {
+  const unk = '\x1b[31munknown (command failed)\x1b[0m';
+  console.log('\n  Git Hygiene — Repository State\n');
+  const branchLabel = r.headState === 'detached' ? 'detached HEAD'
+    : r.headState === 'unborn' ? `${r.branch} (no commits yet)` : fmt(r.branch, 'unknown');
+  console.log(`  Active Branch:      \x1b[36m${branchLabel}\x1b[0m`);
+  if (r.isClean === null) console.log(`  Worktree State:     ${unk}`);
+  else {
+    console.log(`  Worktree State:     ${r.isClean ? '\x1b[32mClean\x1b[0m' : `\x1b[33mDirty (${r.totalDirty} modified/untracked files)\x1b[0m`}`);
+    if (!r.isClean) {
+      console.log(`    - Staged files:   ${r.stagedFiles}`);
+      console.log(`    - Unstaged files: ${r.unstagedFiles}`);
+      console.log(`    - Untracked:      ${r.untrackedFiles}`);
+      if (r.conflictedFiles) console.log(`    - Conflicted:     ${r.conflictedFiles}`);
+    }
+  }
+  let upstreamLine;
+  switch (r.upstreamStatus) {
+    case 'tracking':
+      upstreamLine = r.unpushedCommits === 0 && r.behindCommits === 0
+        ? `Up to date with ${r.upstream}`
+        : `\x1b[33m${r.unpushedCommits} ahead, ${r.behindCommits} behind ${r.upstream}\x1b[0m`;
+      break;
+    case 'none': upstreamLine = 'No upstream configured (sync state unknown)'; break;
+    case 'gone': upstreamLine = 'Upstream branch is missing (sync state unknown)'; break;
+    case 'detached': upstreamLine = 'Detached HEAD (no upstream)'; break;
+    case 'unborn': upstreamLine = 'No commits yet (no upstream)'; break;
+    default: upstreamLine = unk;
+  }
+  console.log(`  Upstream:           ${upstreamLine}`);
+  console.log(`  Stash Stack:        ${r.stashCount === null ? unk : `${r.stashCount} saved stashes`}`);
+  console.log(`  Head Commit:        ${fmt(r.lastCommit, unk)}\n`);
+}
+
+export async function run(argv = []) {
+  // argv: ["node", "total-recall", "git-sentinel", "<subcommand>", ...flags]
+  // Never process.exit(): a host running this in-process would be stopped too.
+  const clean = Array.isArray(argv) ? argv.slice(3) : [];
+  const isJson = clean.includes('--json');
+  const wantsHelp = clean.includes('--help') || clean.includes('-h');
+  const action = clean.find((a) => !a.startsWith('-')) || 'audit';
+  const fail = (message, code = 1, extra = {}) => {
+    process.exitCode = code;
+    if (isJson) console.log(JSON.stringify({ ok: false, error: message, ...extra }, null, 2));
+    else console.error(message);
+  };
+
+  if (wantsHelp || action === 'help') {
+    console.log(usage());
+    return;
+  }
+  if (!VERBS.includes(action)) {
+    fail(`Unknown git-sentinel command "${action}". ${usage()}`, 2);
+    return;
+  }
+
+  const cwd = process.cwd();
+  const audit = collectAudit(cwd);
+  if (audit.report === undefined) {
+    fail(audit.error, 1, { errors: audit.errors });
+    return;
+  }
+
+  if (action === 'diff') {
+    const diff = git(['diff', '--stat'], cwd);
+    if (!diff.ok) {
+      fail('git diff failed; working tree changes are unknown.', 1, { errors: ['diff'] });
+      return;
+    }
+    if (isJson) console.log(JSON.stringify({ ok: true, diffStat: diff.stdout.trimEnd(), timestamp: new Date().toISOString() }, null, 2));
+    else {
+      console.log('\n  Git Hygiene — Working Tree Changes:\n');
+      console.log(diff.stdout.trimEnd() || '  No unstaged changes.\n');
+    }
+    return;
+  }
+
+  if (!audit.ok) process.exitCode = 1;
+  if (isJson) {
+    console.log(JSON.stringify(audit.report, null, 2));
+    return;
+  }
+  printAudit(audit.report);
+  if (!audit.ok) console.error(`Audit incomplete: ${audit.errors.join(', ')} failed.`);
+}
+
+export default run;