total-recall-brain 3.44.0 → 3.46.0

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

@@ -1,24 +1,25 @@
 #!/usr/bin/env node
-import { execFileSync } from 'node:child_process';
-import { realpathSync } from 'node:fs';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
 
 const GIT_TIMEOUT_MS = 15000;
 const GIT_MAX_BUFFER = 64 * 1024 * 1024;
-const VERBS = ['audit', 'diff', 'identity', 'worktree-list', 'worktree-create', 'worktree-remove', 'help'];
+const VERBS = ['audit', 'diff', 'identity', 'worktree-list', 'worktree-create', 'worktree-remove'];
 
 /**
  * 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()) {
+export function git(args, cwd = process.cwd(), input) {
   try {
     const stdout = execFileSync('git', args, {
       cwd,
       encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
+      ...(input === undefined ? { stdio: ['ignore', 'pipe', 'pipe'] } : { input, stdio: ['pipe', 'pipe', 'pipe'] }),
       timeout: GIT_TIMEOUT_MS,
       maxBuffer: GIT_MAX_BUFFER,
       env: { ...process.env, LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' },
@@ -210,14 +211,20 @@ function printIdentity(r) {
   console.log('');
 }
 
-function usage() {
-  return `Usage: total-recall git-sentinel [operation] [--json]
-  audit | identity
-  diff [--patch] [--cached] [--base <ref>]
-  worktree list
-  worktree create <path> [--base <ref>]
-  worktree remove <path> [--force]
-  worktree-list | worktree-create | worktree-remove (separate operation effects)`;
+function usage(operations = {}) {
+  const features = Object.entries(operations).sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, op]) => `  ${(op.usage || name).split('\n')[0].padEnd(46)} ${op.summary}`).join('\n');
+  return `Usage: total-recall git <command> [arguments] [--json]
+
+Every git command works here: anything that is not listed below runs git itself, with your
+arguments, git's hooks, output and exit status. Example: total-recall git pull --rebase.
+Git's own help for a command: total-recall git help <command>.
+
+Plugin operations:
+  audit | identity                               Repository state; commit identity and its history
+  diff --json [--patch] [--cached] [--base <ref>]  The card's diff (plain diff is git's)
+  worktree-list | worktree-create <path> [--base <ref>] | worktree-remove <path> [--force]
+${features ? features + '\n' : ''}  --help                                         This help; <operation> --help for one operation`;
 }
 
 function gitResult(args, cwd) {
@@ -247,7 +254,11 @@ function worktrees(cwd) {
 }
 
 function worktreeOperation(action, values, target, cwd) {
-  if (action === 'worktree-list') return { ok: true, worktrees: worktrees(cwd) };
+  if (action === 'worktree-list') {
+    const registered = worktrees(cwd);
+    const root = git(['rev-parse', '--show-toplevel'], cwd);
+    return { ok: true, worktrees: registered, current: root.ok ? root.stdout.replace(/\n$/, '') : null };
+  }
   const targetPath = path.resolve(cwd, target);
   if (action === 'worktree-create') {
     const commit = resolveCommit(values.base ?? 'HEAD', cwd);
@@ -303,36 +314,141 @@ function printAudit(r) {
   console.log(`  Head Commit:        ${fmt(r.lastCommit, unk)}\n`);
 }
 
+/**
+ * Feature operations live in src/ops/<name>.mjs, one file per feature. Each module may export:
+ * - `operations`: { <name>: { summary, usage, run(args, ctx) } }; `run` returns an exit status.
+ * - `guards`: [{ name, before(args, ctx) }] run before git's own commands, in file order. `before`
+ *   returns nothing to allow, `{ args }` to rewrite the arguments, or `{ refuse: <message> }`.
+ *   An optional `after(args, ctx, status)` runs after git finishes; its failure is reported, never fatal.
+ * `ctx` is { cwd, env, json, git(args) -> spawnSync result with captured output }.
+ * Help is built from this registry, so every operation is in `--help`.
+ */
+const OPS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'src', 'ops');
+let GIT_COMMANDS;
+function isGitCommand(name) {
+  if (!GIT_COMMANDS) GIT_COMMANDS = new Set(String(spawnSync('git', ['--list-cmds=main,others,alias,nohelpers'], { encoding: 'utf8' }).stdout || '').split('\n').filter(Boolean));
+  return GIT_COMMANDS.has(name);
+}
+
+export async function loadRegistry(dir = OPS_DIR) {
+  const operations = {}, guards = [];
+  let files = [];
+  try { files = readdirSync(dir).filter(f => f.endsWith('.mjs') && !f.includes('.spec.') && !f.includes('.test.')).sort(); } catch { /* no feature modules */ }
+  for (const file of files) {
+    // One module that fails to load disables only its own operations; git and every other operation keep working.
+    let mod;
+    try { mod = await import(pathToFileURL(path.join(dir, file)).href); }
+    catch (error) {
+      const name = file.replace(/\.mjs$/, '');
+      if (!operations[name]) operations[name] = { summary: `unavailable: ${String(error.message).split('\n')[0]}`, usage: name, file, broken: true,
+        run: () => { console.error(`${name} is unavailable: ${error.message.split('\n')[0]}`); return 1; } };
+      continue;
+    }
+    for (const [name, op] of Object.entries(mod.operations || {})) {
+      if (operations[name]) throw new Error(`Operation "${name}" is defined twice (${file})`);
+      operations[name] = { ...op, file };
+    }
+    for (const guard of mod.guards || []) guards.push({ ...guard, file });
+  }
+  return { operations, guards };
+}
+
+function context(cwd, json) {
+  return {
+    cwd, env: process.env, json,
+    git: (args, options = {}) => spawnSync('git', args, { cwd, env: process.env, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER, ...options }),
+  };
+}
+
+/**
+ * Plugin operations: audit, identity, help, the checked commit, the hyphenated worktree-* operations
+ * and `diff` with --json or --base (the card's diff). Everything else is git's own CLI.
+ * `commit` stays a plugin operation only in its checked form (-m/--message, -a/--all, paths).
+ * Any other git commit flag (--amend, --fixup, -S and the rest) goes to git's own commit.
+ */
+export function isPassthrough(args, featureOps = []) {
+  const [first] = args;
+  if (first === undefined) return false;
+  if (featureOps.includes(first)) return false;
+  if (first.startsWith('-')) return !['--json', '--help', '-h'].includes(first);
+  if (['audit', 'identity', 'worktree-list', 'worktree-create', 'worktree-remove'].includes(first)) return false;
+  if (first === 'diff') return !args.includes('--json') && !args.some(a => a === '--base' || a.startsWith('--base='));
+  return true;
+}
+
 export async function run(argv = []) {
-  // argv: ["node", "total-recall", "git-sentinel", "<subcommand>", ...flags]
+  // argv: ["node", "total-recall", "git", "<subcommand>", ...flags]
   // Never process.exit(): a host running this in-process would be stopped too.
   const clean = Array.isArray(argv) ? argv.slice(3) : [];
+  const registry = await loadRegistry();
+  const cwd0 = process.cwd();
+  const featureOp = registry.operations[clean[0]];
+  const wantsOpHelp = clean.includes('--help') || clean.includes('-h');
+  // Guards see every command, plugin operations included (a plugin `commit` is still a commit).
+  // Each guard decides from args[0] whether the command concerns it.
+  const runGuards = async (args, phase, status) => {
+    for (const guard of registry.guards) {
+      if (phase === 'before') {
+        const verdict = await guard.before?.(args, context(cwd0, false));
+        if (verdict?.refuse) return { refuse: `${args[0]} refused by ${guard.name}: ${verdict.refuse}` };
+        if (verdict?.args) args = verdict.args;
+      } else if (guard.after) {
+        try { await guard.after(args, context(cwd0, false), status); }
+        catch (error) { console.error(`${guard.name} after ${args[0]}: ${error.message}`); }
+      }
+    }
+    return { args };
+  };
+  // `-h` on a plugin operation that is also a git command (commit, bundle) is git's own usage;
+  // `--help` shows the plugin operation's help.
+  const gitUsage = featureOp && clean.includes('-h') && !clean.includes('--help') && isGitCommand(clean[0]);
+  if (featureOp && !wantsOpHelp || gitUsage) {
+    if (gitUsage) {
+      const ran = spawnSync('git', clean, { cwd: cwd0, stdio: 'inherit', env: process.env });
+      process.exitCode = ran.status ?? 1;
+      return;
+    }
+    const checked = await runGuards(clean, 'before');
+    if (checked.refuse) { console.error(checked.refuse); process.exitCode = 1; return; }
+    const status = await featureOp.run(checked.args.slice(1).filter(a => a !== '--json'), context(cwd0, clean.includes('--json')));
+    process.exitCode = typeof status === 'number' ? status : 0;
+    await runGuards(checked.args, 'after', process.exitCode);
+    return;
+  }
+  if (featureOp) { console.log(`total-recall git ${clean[0]} — ${featureOp.summary}\n${featureOp.usage || ''}`.trimEnd()); return; }
+  // The whole git CLI: every command that is not a plugin operation runs git itself, with the
+  // caller's arguments unchanged (unless a guard rewrites them), git's own hooks, output and exit status.
+  if (isPassthrough(clean, Object.keys(registry.operations))) {
+    const checked = await runGuards(clean, 'before');
+    if (checked.refuse) { console.error(`git ${checked.refuse}`); process.exitCode = 1; return; }
+    const ran = spawnSync('git', checked.args, { cwd: cwd0, stdio: 'inherit', env: process.env });
+    if (ran.error) console.error(`git could not start: ${ran.error.message}`);
+    process.exitCode = ran.status ?? 1;
+    await runGuards(checked.args, 'after', process.exitCode);
+    return;
+  }
   const isJson = clean.includes('--json');
   const wantsHelp = clean.includes('--help') || clean.includes('-h');
   let [action = 'audit', ...args] = clean.filter(arg => arg !== '--json');
-  if (action === 'worktree') {
-    const [verb = 'list', ...rest] = args;
-    action = `worktree-${verb}`;
-    args = rest;
-  }
   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());
+  if (wantsHelp) {
+    console.log(usage(registry.operations));
     return;
   }
   if (!VERBS.includes(action)) {
-    fail(`Unknown git-sentinel command "${action}". ${usage()}`, 2);
+    fail(`Unknown git plugin command "${action}". ${usage()}`, 2);
     return;
   }
 
   const options = action === 'diff' ? { patch: { type: 'boolean' }, cached: { type: 'boolean' }, base: { type: 'string' } }
     : action === 'worktree-create' ? { base: { type: 'string' } }
-    : action === 'worktree-remove' ? { force: { type: 'boolean' } } : {};
+    : action === 'worktree-remove' ? { force: { type: 'boolean' } }
+    : {};
   const targetRequired = action === 'worktree-create' || action === 'worktree-remove';
   let parsed;
   try {

package/scaffold/.agent/skills/total-recall/plugins/{git-sentinel → git}/package-lock.json

@@ -1,18 +1,18 @@
 {
-  "name": "tr-plugin-git-sentinel",
-  "version": "1.1.5",
+  "name": "tr-plugin-git",
+  "version": "2.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "tr-plugin-git-sentinel",
-      "version": "1.1.5",
+      "name": "tr-plugin-git",
+      "version": "2.2.0",
       "license": "MIT",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.14.5"
       },
       "devDependencies": {
-        "total-recall-brain": "3.43.3",
+        "total-recall-brain": "3.45.0",
         "vitest": "^4.1.10"
       }
     },
@@ -6533,9 +6533,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.43.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.43.3.tgz",
-      "integrity": "sha512-yjfPN/BQxEEa+iodyFXQov/6fRt1pZg/7RcmgsbpALwBt6Ki3JJjT3tzArBC7NxHQmXgGYyKnCYId6xe/W2rPg==",
+      "version": "3.45.0",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.45.0.tgz",
+      "integrity": "sha512-HDYfROazZbsLHQsFPnlBcSpe1HL1QEi7JG8x/eNRUI06RxVQsZWl8LwBo2lTWjWRDrKmCy7BUmSXQDuWF3lrEw==",
       "dev": true,
       "license": "MIT",
       "workspaces": [
@@ -6543,7 +6543,7 @@
       ],
       "dependencies": {
         "@simplewebauthn/server": "^13.3.2",
-        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.4",
+        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.5",
         "bcrypt": "^6.0.0",
         "better-sqlite3": "^12.11.1",
         "cookie-parser": "^1.4.7",

package/scaffold/.agent/skills/total-recall/plugins/{git-sentinel → git}/package.json

@@ -1,6 +1,6 @@
 {
-  "name": "tr-plugin-git-sentinel",
-  "version": "1.1.5",
+  "name": "tr-plugin-git",
+  "version": "2.2.0",
   "type": "module",
   "description": "Reports the state of the current git repository: branch, dirty files, unpushed commits and stashes.",
   "scripts": {
@@ -11,6 +11,8 @@
   "files": [
     "cli.mjs",
     "plugin.json",
+    "DESIGN.md",
+    "src/",
     "README.md",
     "LICENSE",
     "ui/"

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

@@ -0,0 +1,151 @@
+{
+  "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "git",
+  "name": "Git",
+  "version": "2.2.0",
+  "description": "The whole git CLI through Total Recall: sign-in from the auth store, guarded commits and pushes, undo, fleet state, and the intent behind every change.",
+  "author": "Total Recall",
+  "license": "MIT",
+  "use_cases": [
+    "software-development"
+  ],
+  "gate": {
+    "tasks": ["Run any git command", "Commit or push with identity, secret and rule checks", "Sign git in through the auth store", "Undo a destructive git command", "Check repository state across the mesh", "Keep the git CLI current on every node"],
+    "owned_commands": [
+      { "pattern": "(^|[;&|(]\\s*)git(\\s+-C\\s+\\S+)?\\s+[a-z]", "use": "total-recall git <same git command and arguments>" }
+    ]
+  },
+  "tasks": [
+    { "intent": "Check and update the git CLI", "schedule": "17 6 * * *", "command": "cli update --scheduled", "placement": "per-node" }
+  ],
+  "cli": {
+    "answers_help": true,
+    "command": "git",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      {
+        "name": "audit",
+        "description": "Summarise branch, worktree, upstream and stash state (--json for machine output)",
+        "effect": "read"
+      },
+      {
+        "name": "diff",
+        "description": "Read a stat or patch for unstaged, staged or base-relative changes",
+        "effect": "read",
+        "args": [
+          { "name": "patch", "flag": "--patch", "type": "boolean", "label": "Show patch" },
+          { "name": "cached", "flag": "--cached", "type": "boolean", "label": "Use staged changes" },
+          { "name": "base", "flag": "--base", "type": "string", "label": "Base ref" }
+        ]
+      },
+      { "name": "commit", "description": "Check identity, conflicts, HEAD, secrets and repository rules, then run git's own commit with your arguments", "effect": "write", "timeout_ms": 600000, "args": [
+        { "name": "args", "type": "string", "label": "git commit arguments", "positional": true }
+      ] },
+      { "name": "push", "description": "Check outgoing commits for secrets and rules, turn --force into --force-with-lease, then run git's own push", "effect": "write", "timeout_ms": 600000, "args": [
+        { "name": "args", "type": "string", "label": "git push arguments", "positional": true }
+      ] },
+      { "name": "credential-helper", "description": "Git credential helper: give git the mapped auth-store credential (get); store and erase do nothing", "effect": "read" },
+      { "name": "auth", "description": "Sign-in: status (live check, no secret shown), map <host> <KEY>, setup (helper entries for this machine)", "effect": "write", "args": [
+        { "name": "action", "type": "string", "label": "status | map | setup", "positional": true }
+      ] },
+      { "name": "cli", "description": "Git CLI metadata (version, path, install source, upstream, release notes); --all-nodes for the mesh; cli update updates git through its installer", "effect": "write", "timeout_ms": 600000 },
+      { "name": "undo", "description": "Restore refs, index and files from the snapshot taken before a destructive git command; --list shows snapshots", "effect": "destructive", "args": [
+        { "name": "event", "type": "string", "label": "Snapshot", "positional": true },
+        { "name": "list", "flag": "--list", "type": "boolean", "label": "List snapshots" }
+      ] },
+      { "name": "fleet", "description": "Dirty, unpushed, behind, diverged, stale stashes and abandoned worktrees across registered repositories; --all-nodes for the mesh", "effect": "read", "timeout_ms": 600000 },
+      { "name": "unmerged", "description": "Branches with commits not in the default branch, worktrees with uncommitted changes and detached worktrees holding commits on no branch; --registered for every registered repository", "effect": "read", "output": "json", "timeout_ms": 600000, "args": [
+        { "name": "registered", "flag": "--registered", "type": "boolean", "label": "Every registered repository" }
+      ] },
+      { "name": "where", "description": "Machines and checkouts that contain a commit", "effect": "read", "args": [
+        { "name": "commit", "type": "string", "label": "Commit", "required": true, "positional": true }
+      ] },
+      { "name": "why", "description": "Blame one line plus the session, tracker item, decision and rules recorded when it was committed", "effect": "read", "args": [
+        { "name": "location", "type": "string", "label": "file:line", "required": true, "positional": true }
+      ] },
+      { "name": "group", "description": "Group a dirty tree into commits by the agent session that wrote each change; --apply commits the groups", "effect": "write" },
+      { "name": "message", "description": "Draft a commit message from the staged diff, the active tracker and its action log", "effect": "read" },
+      { "name": "bisect-agent", "description": "Find the first bad commit with the repository's quality gate as the test", "effect": "write", "timeout_ms": 600000, "args": [
+        { "name": "good", "type": "string", "label": "Good commit", "required": true, "positional": true },
+        { "name": "bad", "type": "string", "label": "Bad commit", "required": true, "positional": true }
+      ] },
+      { "name": "resolve", "description": "Propose a resolution for each conflicted file from both sides' recorded intent; --apply writes it", "effect": "write" },
+      { "name": "handoff", "description": "Pack a branch, its tracker and related memory into one SSSS bundle for another agent or machine", "effect": "write", "args": [
+        { "name": "branch", "type": "string", "label": "Branch", "required": true, "positional": true },
+        { "name": "out", "flag": "--out", "type": "string", "label": "Output file" }
+      ] },
+      { "name": "worktree-list", "description": "Read registered worktrees for the current repository", "effect": "read" },
+      { "name": "worktree-create", "description": "Create a detached worktree at a specified path and base ref", "effect": "write", "args": [
+        { "name": "path", "type": "string", "label": "Worktree path", "required": true, "positional": true },
+        { "name": "base", "flag": "--base", "type": "string", "label": "Base ref" }
+      ] },
+      { "name": "worktree-remove", "description": "Remove an owned linked worktree, with explicit force for dirty content", "effect": "destructive", "args": [
+        { "name": "path", "type": "string", "label": "Worktree path", "required": true, "positional": true },
+        { "name": "force", "flag": "--force", "type": "boolean", "label": "Allow removal of dirty content" }
+      ] },
+      { "name": "worktree", "description": "Compatibility form: worktree list, create or remove", "effect": "destructive" },
+      {
+        "name": "identity",
+        "description": "Show who commits here and which identities the history publishes; exits 1 on a missing or machine-derived identity (--json for machine output)",
+        "effect": "read"
+      }
+    ]
+  },
+  "ui": {
+    "design_tokens": "DESIGN.md",
+    "home": "repository",
+    "elements": [
+      {
+        "id": "repository",
+        "kind": "panel",
+        "tag": "tr-git-home",
+        "module": "ui/home.js",
+        "description": "Repository audit, diff stats, and linked worktrees",
+        "tokens": ["color-text", "color-surface", "color-border", "spacing-md", "radius-md"],
+        "optional_tokens": [
+          "color-background", "color-accent", "color-muted", "color-danger",
+          "typography-body-font-family", "typography-heading-font-family", "typography-mono-font-family"
+        ]
+      }
+    ]
+  },
+  "auth": {
+    "plugin": "auth",
+    "methods": [
+      "passkey",
+      "google-oauth2"
+    ],
+    "session_verification": true
+  },
+  "deploy": {
+    "targets": [
+      "ssss-app",
+      "nextjs",
+      "react",
+      "flask"
+    ],
+    "required_ssss_version": ">=0.9.3",
+    "access_grants": [
+      "auth:session:verify",
+      "ssss:vault:read",
+      "ssss:vault:write",
+      "ssss:events:append"
+    ]
+  },
+  "branding": {
+    "name": "Git Hygiene",
+    "color": "#b45309",
+    "accent": "#f59e0b",
+    "badge": "Repository Hygiene",
+    "font": "space-grotesk"
+  },
+  "startup_check": { "command": "unmerged", "args": ["--json"], "timeout_ms": 20000 },
+  "status": {
+    "command": "audit",
+    "refresh_seconds": 60
+  },
+  "distribution": {
+    "tier": "official",
+    "license": "open"
+  }
+}

package/scaffold/.agent/skills/total-recall/plugins/git/src/lib/context.mjs

@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+const require = createRequire(import.meta.url);
+export function git(ctx, args, options) {
+  const result = ctx.git(args, options);
+  if ((result.status ?? result.code) !== 0 || result.error) throw new Error(`Git ${args[0]} failed`);
+  return String(result.stdout ?? '');
+}
+export function tr(ctx, args, options = {}) {
+  return spawnSync(ctx.env.GIT_PLUGIN_TR_BIN || 'total-recall', args, {
+    cwd: ctx.cwd, env: ctx.env, encoding: 'utf8', shell: false,
+    timeout: 30000, maxBuffer: 16 * 1024 * 1024, ...options,
+  });
+}
+export function trJSON(ctx, args) {
+  const result = tr(ctx, args);
+  if (result.error || result.status !== 0) throw new Error(`Total Recall ${args[0]} failed`);
+  try { return JSON.parse(result.stdout); } catch { throw new Error(`Total Recall ${args[0]} returned invalid JSON`); }
+}
+export function repository(ctx) {
+  return git(ctx, ['rev-parse', '--path-format=absolute', '--git-common-dir']).trim();
+}
+export async function ledger(ctx, kind = 'commits', required = false) {
+  const dir = ctx.env.TR_PLUGIN_STATE_DIR;
+  if (!dir) {
+    if (required) throw new Error('TR_PLUGIN_STATE_DIR must be supplied by the Total Recall host');
+    return null;
+  }
+  if (!path.isAbsolute(dir)) throw new Error('TR_PLUGIN_STATE_DIR must be absolute');
+  let modulePath;
+  const root = ctx.env.TR_PACKAGE_ROOT;
+  if (root) {
+    if (!path.isAbsolute(root) || JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name !== 'total-recall-brain') throw new Error('Invalid Total Recall state host');
+    modulePath = path.join(root, 'src/core/plugin-state-store.mjs');
+  } else modulePath = require.resolve('total-recall-brain/src/core/plugin-state-store.mjs');
+  const { PluginStateStore } = await import(pathToFileURL(modulePath).href);
+  const key = crypto.createHash('sha256').update(repository(ctx)).digest('hex');
+  return new PluginStateStore(path.join(dir, `${kind}-${key}.jsonl`), 'git');
+}
+export function session(env) { return env.CLAUDE_SESSION_ID || env.CODEX_SESSION_ID || env.TR_SESSION_ID || null; }
+export function trailers(message) {
+  // Trailers must be in the final paragraph. Body prose is not attribution.
+  const block = message.trim().split(/\n\s*\n/).at(-1) || '';
+  const result = {};
+  let key;
+  for (const line of block.split('\n')) {
+    const match = /^([\w-]+):\s*(.*)$/.exec(line);
+    if (match) { key = match[1].toLowerCase(); (result[key] ||= []).push(match[2]); }
+    else if (/^\s+/.test(line) && key) result[key][result[key].length - 1] += ` ${line.trim()}`;
+    else return {};
+  }
+  return result;
+}
+export function intent(message) {
+  const rows = trailers(message);
+  return {
+    session: rows['agent-session']?.[0] || rows['session-id']?.[0] || rows.session?.[0] || null,
+    trackerItems: [...new Set(message.match(/\b(?:[A-Z][A-Z0-9_]*-[A-Z]*\d[\w.-]*|P\d+\.\d+|R\d+)\b/g) || [])],
+    decisions: [...(rows.decision || []), ...message.split('\n').filter(row => /^Decision\s*:/i.test(row)).map(row => row.replace(/^Decision\s*:\s*/i, ''))].filter((row, i, all) => all.indexOf(row) === i),
+    rules: rows.rules || rows.rule || [], trailers: rows,
+  };
+}
+export async function commitContext(ctx, sha) {
+  const message = git(ctx, ['show', '-s', '--format=%B', sha]);
+  const store = await ledger(ctx);
+  const record = store?.read([]).findLast(row => row.type === 'git.commit_context' && row.sha === sha) || null;
+  return { sha, message: message.trimEnd(), recorded: record, trailers: trailers(message), ...intent(message),
+    ...(record ? { session: record.session, trackerItems: record.trackerItems, decisions: record.decisions, rules: record.rules } : {}) };
+}
+export function output(ctx, value, text) { console.log(ctx.json ? JSON.stringify(value, null, 2) : text); }
+export function operation(summary, usage, run) {
+  return { summary, usage, async run(args, ctx) {
+    try { return await run(args, ctx); }
+    catch (error) { if (ctx.json) console.log(JSON.stringify({ ok: false, error: error.message })); else console.error(error.message); return 1; }
+  } };
+}
+export function activePlan(ctx) {
+  const root = git(ctx, ['rev-parse', '--show-toplevel']).trim();
+  const base = path.join(root, 'docs/projects/in-progress');
+  if (!fs.existsSync(base)) return { tracker: null, plan: null, items: [], actionLog: '', reason: 'No active plan' };
+  const dirs = fs.readdirSync(base, { withFileTypes: true }).filter(row => row.isDirectory());
+  const trackers = dirs.flatMap(dir => fs.readdirSync(path.join(base, dir.name)).filter(name => name.endsWith('_PROJECT_TRACKER.md')).map(name => path.join(base, dir.name, name)));
+  if (trackers.length !== 1) throw new Error('Expected one active project tracker');
+  const tracker = trackers[0];
+  const plan = tracker.replace('_PROJECT_TRACKER.md', '_DEVELOPMENT_PLAN.md');
+  const body = fs.readFileSync(tracker, 'utf8');
+  const planBody = fs.existsSync(plan) ? fs.readFileSync(plan, 'utf8') : '';
+  return { tracker, plan, body, planBody, items: body.split('\n').filter(row => /^- \[[ xX]\]/.test(row)), actionLog: body.split(/^## Action Log\s*$/m)[1]?.trim() || '' };
+}

package/scaffold/.agent/skills/total-recall/plugins/git/src/lib/phase3-spec-support.mjs

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { vi } from 'vitest';
+
+export function fixture() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'git-phase3-spec-'));
+  const repo = path.join(tmp, 'repo'); fs.mkdirSync(repo);
+  const cwd = fs.realpathSync(repo);
+  const env = { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_AUTHOR_NAME: 'Test Agent', GIT_AUTHOR_EMAIL: 'agent@example.com', GIT_COMMITTER_NAME: 'Test Agent', GIT_COMMITTER_EMAIL: 'agent@example.com', TR_PLUGIN_STATE_DIR: path.join(tmp, 'state'), TR_PACKAGE_ROOT: fileURLToPath(new URL('../../node_modules/total-recall-brain', import.meta.url)), CODEX_SESSION_ID: 'session-one' };
+  delete env.CLAUDE_SESSION_ID;
+  delete env.GIT_INDEX_FILE;
+  // Specs run this checkout's CLI, never whatever version happens to be installed.
+  const CLI = new URL('../../cli.mjs', import.meta.url).href;
+  const RUN = `import(${JSON.stringify(CLI)}).then(m => m.run(['node', 'total-recall', 'git', ...process.argv.slice(1)])).then(() => process.exit(process.exitCode ?? 0))`;
+  const git = (args, options = {}) => spawnSync(process.execPath, ['--input-type=module', '-e', RUN, ...args], { cwd, env, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, ...options });
+  // Fixture setup uses plain git: setup is not the code under test, so no guard or record runs for it.
+  const raw = (args, options = {}) => spawnSync('git', args, { cwd, env, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, ...options });
+  const g = (...args) => { const r = raw(args); if (r.status !== 0) throw new Error(`Fixture git ${args[0]}: ${r.stderr}`); return r.stdout; };
+  g('init', '-q', '-b', 'main');
+  g('config', '--local', 'user.name', 'Test Agent');
+  g('config', '--local', 'user.email', 'agent@example.com');
+  g('config', '--local', 'commit.gpgsign', 'false');
+  const write = (name, content) => { fs.mkdirSync(path.dirname(path.join(cwd, name)), { recursive: true }); fs.writeFileSync(path.join(cwd, name), content); };
+  const commit = (message = 'Initial', file = 'a.txt', body = 'one\ntwo\nthree\nfour\nfive\n') => { write(file, body); g('add', '--', file); g('commit', '-qm', message); return g('rev-parse', 'HEAD').trim(); };
+  const responses = path.join(tmp, 'responses.json');
+  const calls = path.join(tmp, 'calls.jsonl');
+  const bin = path.join(tmp, 'total-recall-stub');
+  fs.writeFileSync(responses, '{}');
+  fs.writeFileSync(bin, `#!/usr/bin/env node
+const fs=require('node:fs'),cp=require('node:child_process');
+const args=process.argv.slice(2);fs.appendFileSync(${JSON.stringify(calls)},JSON.stringify(args)+'\\n');
+const map=JSON.parse(fs.readFileSync(${JSON.stringify(responses)},'utf8'));
+if(args[0]==='git'){const r=cp.spawnSync(process.execPath,['--input-type=module','-e',${JSON.stringify(RUN)},...args.slice(1)],{env:process.env,encoding:'utf8',input:fs.readFileSync(0)});process.stdout.write(r.stdout||'');process.stderr.write(r.stderr||'');process.exitCode=r.status??1;}
+else if(args[0]==='auth'&&args[2]==='list'&&!map['auth secret']){process.stdout.write(JSON.stringify({keys:[]}));}
+else if(args[0]==='auth'&&args[2]==='scan'&&!map['auth secret']){fs.readFileSync(0);process.stdout.write(JSON.stringify({ok:true,leak:false,keys:[]}));}
+else if(args[0]==='code-quality'&&map.gateFile){const ok=fs.readFileSync(map.gateFile,'utf8').includes('good');process.stdout.write(JSON.stringify({ok}));process.exitCode=ok?0:1;}
+else{const r=map[args.slice(0,2).join(' ')]||map[args[0]]||{status:0,body:{}};process.stdout.write(typeof r.body==='string'?r.body:JSON.stringify(r.body));process.exitCode=r.status??0;}
+`, { mode: 0o755 });
+  env.GIT_PLUGIN_TR_BIN = bin;
+  const set = map => fs.writeFileSync(responses, JSON.stringify(map));
+  const readCalls = () => fs.existsSync(calls) ? fs.readFileSync(calls, 'utf8').trim().split('\n').filter(Boolean).map(row => JSON.parse(row)) : [];
+  const out = vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+  const ctx = { cwd, env, json: true, git };
+  const result = () => JSON.parse(out.mock.calls.at(-1)[0]);
+  return { tmp, cwd, env, ctx, g, git, write, commit, set, readCalls, result, cleanup() { vi.restoreAllMocks(); fs.rmSync(tmp, { recursive: true, force: true }); } };
+}

package/scaffold/.agent/skills/total-recall/plugins/git/src/lib/runtime.mjs

@@ -0,0 +1,40 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+/** The host owns the state path and the SSSS implementation. */
+export async function stateStore(ctx, name) {
+  const dir = ctx.env.TR_PLUGIN_STATE_DIR;
+  if (!dir || !path.isAbsolute(dir)) throw new Error('TR_PLUGIN_STATE_DIR must be supplied by the Total Recall host');
+  const root = ctx.env.TR_PACKAGE_ROOT;
+  let modulePath;
+  if (root) {
+    if (!path.isAbsolute(root) || JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')).name !== 'total-recall-brain') {
+      throw new Error('Invalid Total Recall state host');
+    }
+    modulePath = path.join(root, 'src/core/plugin-state-store.mjs');
+  } else modulePath = require.resolve('total-recall-brain/src/core/plugin-state-store.mjs');
+  const { PluginStateStore } = await import(pathToFileURL(modulePath).href);
+  return new PluginStateStore(path.join(dir, name), 'git');
+}
+
+/** Never forward service output or errors. Auth output can contain a secret. */
+export function tr(args, ctx) {
+  return spawnSync(ctx.env.GIT_PLUGIN_TR_BIN || 'total-recall', args, {
+    cwd: ctx.cwd, env: ctx.env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 30000, maxBuffer: 16 * 1024 * 1024, shell: false,
+  });
+}
+
+export function jsonResult(result, reason) {
+  if (result.status !== 0 || result.error || result.signal) throw new Error(reason);
+  try { return JSON.parse(result.stdout); } catch { throw new Error(reason); }
+}
+
+export function emit(ctx, value, text) {
+  console.log(ctx.json ? JSON.stringify(value, null, 2) : text);
+}