total-recall-brain 3.44.0 → 3.45.0

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

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "git",
+  "name": "Git",
+  "version": "2.0.1",
+  "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": "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"
+      }
+    ]
+  },
+  "card_face": {
+    "skin": "copper-obsidian",
+    "theme": "copper",
+    "headline": "Worktree Hygiene & Repository Watch",
+    "primary_color": "#b45309",
+    "secondary_color": "#0c0a09",
+    "accent_color": "#f59e0b",
+    "touch_layout": "comfortable",
+    "interactive": true,
+    "quick_actions": [
+      {
+        "subcommand": "audit",
+        "label": "AUDIT"
+      },
+      {
+        "subcommand": "diff",
+        "label": "DIFFSTAT"
+      }
+    ]
+  },
+  "ui": {
+    "design_tokens": "ui/DESIGN.md",
+    "elements": [
+      {
+        "id": "card",
+        "kind": "card",
+        "tag": "tr-git-card",
+        "module": "ui/card.js",
+        "description": "Git Hygiene Repository Hygiene Card Face"
+      }
+    ]
+  },
+  "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"
+  },
+  "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);
+}

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

@@ -0,0 +1,51 @@
+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';
+
+export function fixture() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'git-plugin-spec-'));
+  const bin = path.join(dir, 'bin');
+  fs.mkdirSync(bin);
+  const calls = path.join(dir, 'calls.jsonl');
+  const writeBin = (name, source) => {
+    const file = path.join(bin, name);
+    fs.writeFileSync(file, `#!${process.execPath}\n${source}`, { mode: 0o700 });
+    return file;
+  };
+  const tr = writeBin('tr-stub', `
+    import fs from 'node:fs';
+    const args = process.argv.slice(2);
+    fs.appendFileSync(process.env.SPEC_CALLS, JSON.stringify(args) + '\\n');
+    if (args[0] === 'auth' && args[2] === 'get') {
+      if (process.env.SPEC_AUTH_FAIL) { console.error('fixture-sensitive-diagnostic'); process.exitCode = 1; }
+      else console.log(JSON.stringify({ found: !process.env.SPEC_AUTH_MISSING, value: process.env.SPEC_TOKEN || 'fixture-token' }));
+    } else if (args[0] === 'auth' && args[2] === 'list') {
+      console.log(JSON.stringify({ keys: [{ key: 'github_token' }, { key: 'GITLAB_TOKEN' }] }));
+    } else if (args[0] === 'mesh' && args[1] === 'nodes') {
+      console.log(JSON.stringify({ nodes: [{ name: 'alpha' }, { name: 'beta' }] }));
+    } else if (args[0] === 'mesh' && args[1] === 'exec') {
+      if (process.env.SPEC_NODE_FAIL && args[2] === 'beta') process.exitCode = 1;
+      else console.log(JSON.stringify({ version: '2.52.0', hostname: args[2], versions_behind: 0 }));
+    } else if (args[0] !== 'alerts') process.exitCode = 1;
+  `);
+  const env = { ...process.env, HOME: dir, GIT_CONFIG_GLOBAL: path.join(dir, 'gitconfig'),
+    GIT_CONFIG_NOSYSTEM: '1', TR_PLUGIN_STATE_DIR: path.join(dir, 'state'),
+    TR_PACKAGE_ROOT: fileURLToPath(new URL('../../node_modules/total-recall-brain', import.meta.url)),
+    GIT_PLUGIN_TR_BIN: tr, SPEC_CALLS: calls, PATH: `${bin}${path.delimiter}${process.env.PATH}`,
+    GIT_AUTHOR_NAME: 'Fixture Person', GIT_AUTHOR_EMAIL: 'fixture@example.com',
+    GIT_COMMITTER_NAME: 'Fixture Person', GIT_COMMITTER_EMAIL: 'fixture@example.com',
+  };
+  for (const key of Object.keys(env)) if (/^GIT_CONFIG_(COUNT|KEY_\d+|VALUE_\d+)$/.test(key)) delete env[key];
+  return { dir, bin, env, writeBin,
+    calls: () => fs.existsSync(calls) ? fs.readFileSync(calls, 'utf8').trim().split('\n').filter(Boolean).map(JSON.parse) : [],
+    cleanup: () => fs.rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+export function realContext(f) {
+  return { cwd: f.dir, env: f.env, json: false,
+    git: (args, options = {}) => spawnSync('git', args, { cwd: f.dir, env: f.env, encoding: 'utf8', ...options }),
+  };
+}

package/scaffold/.agent/skills/total-recall/plugins/git/src/ops/_support.mjs

@@ -0,0 +1,195 @@
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const require = createRequire(import.meta.url);
+export function helpOnly(args) {
+  const values = new Set(['-C', '-c', '-m', '-F', '-o', '--message', '--file', '--author', '--date',
+    '--reuse-message', '--reedit-message', '--fixup', '--squash', '--trailer', '--cleanup',
+    '--repo', '--receive-pack', '--exec', '--push-option', '--reason', '--git-dir', '--work-tree', '--namespace', '--config-env', '--pathspec-from-file']);
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--') return false;
+    if (values.has(args[i])) { i += 1; continue; }
+    if (args[i] === '--help' || args[i] === '-h') return true;
+    if (/^-[aneqvsiop]*[mFCc]$/.test(args[i])) i += 1;
+  }
+  return false;
+}
+
+/** Keep global git options attached to every inspection of the command. */
+export function invocation(args, ctx) {
+  let i = 0;
+  while (i < args.length && args[i].startsWith('-')) {
+    if (['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env'].includes(args[i])) i += 2;
+    else i += 1;
+  }
+  const prefix = args.slice(0, i);
+  return { command: args[i], args: args.slice(i + 1), prefix,
+    ctx: { ...ctx, git: (tail, options) => ctx.git([...prefix, ...tail], options) } };
+}
+
+export function gitText(ctx, args, options) {
+  const row = ctx.git(args, options);
+  if (row.error || (row.status ?? row.code) !== 0) throw new Error(`Git ${args[0]} failed`);
+  return Buffer.isBuffer(row.stdout) ? row.stdout.toString('utf8') : String(row.stdout ?? '');
+}
+
+/** Do not forward child diagnostics: an auth failure can contain a credential. */
+export function tr(ctx, args) {
+  const result = spawnSync(ctx.env?.GIT_PLUGIN_TR_BIN || 'total-recall', args, {
+    cwd: ctx.cwd, env: ctx.env, encoding: 'utf8', shell: false,
+    timeout: 30000, maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) throw new Error(`Total Recall ${args.slice(0, 3).join(' ')} failed`);
+  return result.stdout;
+}
+export function trJson(ctx, args) {
+  try { return JSON.parse(tr(ctx, args)); }
+  catch { throw new Error(`Total Recall ${args.slice(0, 3).join(' ')} returned no valid result`); }
+}
+
+export async function stateStore(ctx, name = 'events') {
+  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}.jsonl`), 'git');
+}
+
+export function repoId(ctx) {
+  return gitText(ctx, ['rev-parse', '--path-format=absolute', '--git-common-dir']).trim();
+}
+
+/** Inspect the index git would commit. Never change the user's index here. */
+export function prospectiveCommit(ctx, args) {
+  const paths = [];
+  const pathFlags = [];
+  const valueOptions = new Set(['--message', '--file', '--author', '--date', '--reuse-message', '--reedit-message', '--fixup', '--squash', '--trailer', '--cleanup']);
+  let all = false, include = false, only = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--') { paths.push(...args.slice(i + 1)); break; }
+    if (['--interactive', '--patch'].includes(arg)) throw new Error('Stage interactive changes before commit so the guards can inspect them');
+    if (arg === '--all') { all = true; continue; }
+    if (arg === '--include') { include = true; continue; }
+    if (arg === '--only') { only = true; continue; }
+    if (arg === '--pathspec-from-file') { pathFlags.push(arg, args[++i]); continue; }
+    if (arg.startsWith('--pathspec-from-file=') || arg === '--pathspec-file-nul') { pathFlags.push(arg); continue; }
+    if (valueOptions.has(arg)) { i += 1; continue; }
+    if (arg.startsWith('--')) continue;
+    if (arg.startsWith('-')) {
+      for (let j = 1; j < arg.length; j += 1) {
+        const flag = arg[j];
+        if ('mFCc'.includes(flag)) { if (j === arg.length - 1) i += 1; break; }
+        if (flag === 'a') all = true;
+        if (flag === 'i') include = true;
+        if (flag === 'o') only = true;
+        if (flag === 'p') throw new Error('Stage interactive changes before commit so the guards can inspect them');
+        // -S/-u take an optional attached value. It is not a flag cluster.
+        if ('Su'.includes(flag)) break;
+      }
+    } else paths.push(arg);
+  }
+  if (!all && !only && !include && !paths.length && !pathFlags.length) return { ctx, cleanup() {} };
+  if (pathFlags.some(a => a === '--pathspec-from-file=-' || a === '-')) throw new Error('Stage stdin pathspecs before commit');
+  const dir = mkdtempSync(path.join(os.tmpdir(), 'git-prospective-index-'));
+  const env = { ...ctx.env, GIT_INDEX_FILE: path.join(dir, 'index') };
+  const local = { ...ctx, git: (a, options = {}) => ctx.git(a, { ...options, env }) };
+  const cleanup = () => rmSync(dir, { recursive: true, force: true });
+  try {
+    const index = gitText(ctx, ['rev-parse', '--path-format=absolute', '--git-path', 'index']).trim();
+    if ((paths.length || pathFlags.length || only) && !include) {
+      const head = ctx.git(['rev-parse', '--verify', 'HEAD']);
+      gitText(local, ['read-tree', ...(head.status === 0 ? ['HEAD'] : ['--empty'])]);
+    } else if (existsSync(index)) copyFileSync(index, env.GIT_INDEX_FILE);
+    else gitText(local, ['read-tree', '--empty']);
+    if (all) gitText(local, ['add', '-u']);
+    if (paths.length || pathFlags.length) gitText(local, ['add', '--all', ...pathFlags, '--', ...paths]);
+    return { ctx: local, cleanup };
+  } catch (error) { cleanup(); throw error; }
+}
+
+/** Scan every local branch and tag that the selected remote does not contain.
+ * A missing remote object is not an exclusion. This can over-scan, never under-scan.
+ */
+/**
+ * The commits this push would publish: exactly the refs git itself would update
+ * (`git push --dry-run --porcelain` with the same arguments), minus what the remote already has.
+ * Local branches the push does not send are never counted.
+ */
+export function outgoingCommits(ctx, args = []) {
+  const dry = ctx.git(['push', '--dry-run', '--porcelain', ...args.filter(a => a !== '--porcelain' && a !== '--dry-run')]);
+  if (dry.error || ![0, 1].includes(dry.status)) return allUnpushedCommits(ctx, args);
+  const tips = [];
+  let remote = null;
+  for (const line of String(dry.stdout || '').split('\n')) {
+    if (line.startsWith('To ')) { remote = line.slice(3).trim(); continue; }
+    const m = line.match(/^([ +\-*=!])\t([^:\t]*):([^\t]+)\t/);
+    if (!m || m[1] === '=' || m[1] === '-' || m[1] === '!' || !m[2]) continue;
+    const resolved = ctx.git(['rev-parse', '--verify', '--end-of-options', `${m[2]}^{commit}`]);
+    if (resolved.status === 0) tips.push(resolved.stdout.trim());
+  }
+  if (!tips.length) return [];
+  const advertised = remote ? ctx.git(['ls-remote', '--', remote]) : { status: 1, stdout: '' };
+  const excluded = [...new Set(String(advertised.stdout || '').split('\n').map(line => line.split(/\s+/)[0]).filter(oid => /^[a-f0-9]{40,64}$/.test(oid)))]
+    .filter(oid => ctx.git(['cat-file', '-e', `${oid}^{commit}`]).status === 0);
+  return gitText(ctx, ['rev-list', ...new Set(tips), ...(excluded.length ? ['--not', ...excluded] : []), '--']).trim().split('\n').filter(Boolean);
+}
+
+/** Every unpushed local commit: the conservative superset used when git cannot say what a push sends. */
+function allUnpushedCommits(ctx, args = []) {
+  const takesValue = new Set(['--repo', '--receive-pack', '--exec', '--push-option', '-o']);
+  const positional = [];
+  let remoteOption;
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (takesValue.has(a)) { if (a === '--repo') remoteOption = args[i + 1]; i += 1; }
+    else if (a.startsWith('--repo=')) remoteOption = a.slice(7);
+    else if (a === '--') positional.push(...args.slice(i + 1));
+    else if (!a.startsWith('-')) positional.push(a);
+    if (a === '--') break;
+  }
+  const branch = ctx.git(['symbolic-ref', '--short', '-q', 'HEAD']);
+  const config = key => {
+    const result = ctx.git(['config', '--get', key]);
+    return result.status === 0 ? result.stdout.trim() : '';
+  };
+  const remote = remoteOption || positional[0] ||
+    config(`branch.${branch.stdout?.trim()}.pushRemote`) || config('remote.pushDefault') ||
+    config(`branch.${branch.stdout?.trim()}.remote`) || 'origin';
+  const advertised = gitText(ctx, ['ls-remote', '--', remote]);
+  const excluded = [...new Set(advertised.split('\n').map(line => line.split(/\s+/)[0]).filter(oid => /^[a-f0-9]{40,64}$/.test(oid)))].filter(oid =>
+    ctx.git(['cat-file', '-e', `${oid}^{commit}`]).status === 0);
+  const tips = gitText(ctx, ['for-each-ref', '--format=%(objectname)', 'refs/heads', 'refs/tags']).trim().split('\n').filter(Boolean);
+  const head = ctx.git(['rev-parse', '--verify', 'HEAD']);
+  if (head.status === 0) tips.push(head.stdout.trim());
+  // Explicit source expressions may name commits outside branches and tags.
+  for (const spec of positional.slice(remoteOption ? 0 : 1)) {
+    const source = spec.replace(/^\+/, '').split(':')[0];
+    if (!source || source.includes('*')) continue;
+    const result = ctx.git(['rev-parse', '--verify', '--end-of-options', `${source}^{commit}`]);
+    if (result.status === 0) tips.push(result.stdout.trim());
+  }
+  if (!tips.length) return [];
+  return gitText(ctx, ['rev-list', ...new Set(tips), ...(excluded.length ? ['--not', ...excluded] : []), '--']).trim().split('\n').filter(Boolean);
+}
+
+export function output(ctx, value, text) {
+  if (ctx.json) console.log(JSON.stringify(value, null, 2));
+  else console.log(text);
+}
+export function failure(ctx, error) {
+  if (ctx.json) console.log(JSON.stringify({ ok: false, error: error.message }));
+  else console.error(error.message);
+  return 1;
+}