total-recall-brain 3.44.0 → 3.45.0

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

@@ -0,0 +1,201 @@
+import { readFileSync, existsSync, unlinkSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { emit, jsonResult, stateStore, tr } from '../lib/runtime.mjs';
+
+export const HELPER = '!total-recall git credential-helper';
+const DEFAULT_MAP = { 'github.com': 'github_token' };
+
+function hostName(value) {
+  if (typeof value !== 'string' || !/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::[0-9]+)?$/i.test(value)) {
+    throw new Error('Supply a host name with an optional port');
+  }
+  return value.toLowerCase();
+}
+
+async function mappings(ctx) {
+  if (!ctx.env.TR_PLUGIN_STATE_DIR) return { ...DEFAULT_MAP };
+  const store = await stateStore(ctx, 'auth.json');
+  const saved = store.read({ hosts: {} });
+  return { ...DEFAULT_MAP, ...saved.hosts };
+}
+
+/** Append config to the caller's environment. No credential enters argv or env. */
+export async function authGitEnv(ctx) {
+  const env = { ...ctx.env };
+  let index = Number(env.GIT_CONFIG_COUNT || 0);
+  if (!Number.isSafeInteger(index) || index < 0 || index > 10000) throw new Error('Invalid GIT_CONFIG_COUNT');
+  for (const host of Object.keys(await mappings(ctx))) {
+    hostName(host);
+    for (const value of ['', HELPER]) {
+      env[`GIT_CONFIG_KEY_${index}`] = `credential.https://${host}.helper`;
+      env[`GIT_CONFIG_VALUE_${index}`] = value;
+      index += 1;
+    }
+  }
+  env.GIT_CONFIG_COUNT = String(index);
+  return env;
+}
+
+// The current dispatcher creates a fresh ctx for after(). Restore only our config keys.
+const pending = new WeakMap();
+export const guards = [{
+  name: 'auth-store',
+  async before(_args, ctx) {
+    try {
+      const next = await authGitEnv(ctx);
+      const previous = new Map();
+      for (const [key, value] of Object.entries(next)) {
+        if (key === 'GIT_CONFIG_COUNT' || /^GIT_CONFIG_(KEY|VALUE)_\d+$/.test(key)) {
+          previous.set(key, ctx.env[key]);
+          ctx.env[key] = value;
+        }
+      }
+      const stack = pending.get(ctx.env) || [];
+      stack.push(previous);
+      pending.set(ctx.env, stack);
+    } catch { return { refuse: 'Credential helper configuration is unavailable' }; }
+  },
+  after(_args, ctx) {
+    for (const [key, value] of pending.get(ctx.env)?.pop() || []) {
+      if (value === undefined) delete ctx.env[key]; else ctx.env[key] = value;
+    }
+  },
+}];
+
+async function credential(args, ctx) {
+  // Unsupported actions are silent, as the Git protocol requires.
+  if (args.length !== 1 || args[0] !== 'get') return 0;
+  try {
+    const input = readFileSync(0, 'utf8');
+    if (input.length > 65536) throw new Error('Invalid credential request');
+    const attributes = {};
+    for (const line of input.split(/\r?\n/)) {
+      if (!line) break;
+      const at = line.indexOf('=');
+      if (at > 0) attributes[line.slice(0, at)] = line.slice(at + 1);
+    }
+    if (attributes.protocol !== 'https' || !attributes.host) return 0;
+    const hosts = await mappings(ctx);
+    const host = hostName(attributes.host);
+    if (!Object.hasOwn(hosts, host)) return 0;
+    const key = hosts[host];
+    const result = jsonResult(tr(['auth', 'secret', 'get', key, '--json'], ctx), 'Auth store is unavailable');
+    if (!result.found || typeof result.value !== 'string' || !result.value || /[\r\n\0]/.test(result.value)) {
+      throw new Error('Auth key is unavailable');
+    }
+    if (ctx.env.GIT_PLUGIN_AUTH_PROBE_ID) {
+      const probes = await stateStore(ctx, 'auth-probes.jsonl');
+      probes.append({ probe: ctx.env.GIT_PLUGIN_AUTH_PROBE_ID, host, key, timestamp: new Date().toISOString() });
+    }
+    // This is the only credential output. Git reads this pipe.
+    process.stdout.write(`username=x-access-token\npassword=${result.value}\nquit=true\n\n`);
+    return 0;
+  } catch {
+    process.stdout.write('quit=true\n\n');
+    console.error('Git credential is unavailable from the auth store');
+    return 1;
+  }
+}
+
+async function remoteCheck(ctx) {
+  const remote = ctx.env.GIT_PLUGIN_AUTH_REMOTE || ctx.git(['remote', 'get-url', 'origin']).stdout?.trim();
+  let url;
+  try { url = new URL(remote); } catch { throw new Error('Set an HTTPS origin for the private repository to verify'); }
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) {
+    throw new Error('The verification remote must be HTTPS without credentials');
+  }
+  const hosts = await mappings(ctx);
+  const key = Object.hasOwn(hosts, url.host.toLowerCase()) ? hosts[url.host.toLowerCase()] : null;
+  if (!key) throw new Error('No auth key is mapped to the verification host');
+  const listed = jsonResult(tr(['auth', 'secret', 'list', '--json'], ctx), 'Cannot read auth key metadata');
+  if (!Array.isArray(listed.keys) || !listed.keys.some(row => row.key === key || row.name === key)) {
+    throw new Error('The mapped auth key is not present');
+  }
+  const probe = randomUUID();
+  const env = { ...await authGitEnv(ctx), GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never', GIT_PLUGIN_AUTH_PROBE_ID: probe };
+  const live = ctx.git(['ls-remote', '--', url.href], { env, timeout: 30000, stdio: ['ignore', 'pipe', 'pipe'] });
+  const probes = await stateStore(ctx, 'auth-probes.jsonl');
+  const credentialUsed = probes.readTail(1000).some(row => row.probe === probe && row.host === url.host && row.key === key);
+  const remoteRead = live.status === 0 && !live.error && !live.signal;
+  return { host: url.host, key, key_present: true, remote_read: remoteRead, credential_used: credentialUsed, verified: remoteRead && credentialUsed };
+}
+
+async function setup(ctx) {
+  const config = 'credential.https://github.com.helper';
+  const previous = ctx.git(['config', '--global', '--get-all', config]);
+  if (![0, 1].includes(previous.status)) throw new Error('Cannot read global credential helpers');
+  const old = previous.status === 0 ? previous.stdout.trimEnd().split('\n') : [];
+  const set = args => {
+    if (ctx.git(['config', '--global', ...args]).status !== 0) throw new Error('Cannot write global credential helpers');
+  };
+  try {
+    set(['--replace-all', config, '']);
+    set(['--add', config, HELPER]);
+    const result = await remoteCheck(ctx);
+    if (!result.verified) throw new Error('Auth-store sign-in was not verified; plaintext credentials were kept. Use a private HTTPS origin');
+    if (result.host !== 'github.com') throw new Error('Setup must verify an HTTPS github.com private repository');
+    // Remove only gh helper values. Keep unrelated host and global helpers.
+    const helpers = ctx.git(['config', '--global', '--get-regexp', String.raw`^credential\..*helper$`]);
+    if (![0, 1].includes(helpers.status)) throw new Error('Cannot read legacy helper entries');
+    for (const line of (helpers.stdout || '').split('\n')) {
+      const match = line.match(/^(\S+)\s+(.+)$/);
+      if (match && /(?:^|[\s/!])gh\s+auth\s+git-credential(?:\s|$)/.test(match[2])) {
+        set(['--fixed-value', '--unset-all', match[1], match[2]]);
+      }
+    }
+    const file = path.join(ctx.env.HOME || os.homedir(), '.git-credentials');
+    if (existsSync(file)) {
+      console.error(`Removing verified plaintext credential file: ${file}`);
+      unlinkSync(file);
+    }
+    return { ...result, helper_wired: true, setup: true };
+  } catch (error) {
+    const cleared = ctx.git(['config', '--global', '--unset-all', config]);
+    let restored = [0, 5].includes(cleared.status);
+    for (const value of old) restored = ctx.git(['config', '--global', '--add', config, value]).status === 0 && restored;
+    if (!restored) throw new Error('Setup failed; global credential helper restoration failed');
+    throw error;
+  }
+}
+
+export const operations = {
+  'credential-helper': {
+    summary: 'Read a Git credential from the auth store',
+    usage: 'credential-helper get|store|erase',
+    run: credential,
+  },
+  auth: {
+    summary: 'Verify sign-in or configure the auth-store helper',
+    usage: 'auth status | auth map <host> <KEY> | auth setup',
+    async run(args, ctx) {
+      try {
+        const [action = 'status', host, key] = args;
+        if (action === 'map' && args.length === 3) {
+          const normalized = hostName(host);
+          if (!/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(key)) throw new Error('Supply an auth key name');
+          const store = await stateStore(ctx, 'auth.json');
+          const saved = store.read({ hosts: {} });
+          store.write({ ...saved, hosts: { ...saved.hosts, [normalized]: key } });
+          emit(ctx, { host: normalized, key }, `Mapped ${normalized} to ${key}`);
+          return 0;
+        }
+        if (args.length > 1 || !['status', 'setup'].includes(action)) throw new Error('Use auth status, auth map <host> <KEY>, or auth setup');
+        const result = action === 'setup' ? await setup(ctx) : await remoteCheck(ctx);
+        if (action === 'status') {
+          const row = ctx.git(['config', '--get-all', `credential.https://${result.host}.helper`]);
+          const helpers = row.status === 0 ? row.stdout.trimEnd().split('\n') : [];
+          result.helper_wired = helpers.at(-1) === HELPER && helpers.includes('');
+        }
+        emit(ctx, result, `${result.host}: auth key ${result.key} is present; live remote read ${result.remote_read ? 'passed' : 'failed'}; auth-store sign-in ${result.verified ? 'verified' : 'not verified (use a private HTTPS origin)'}`);
+        return result.verified ? 0 : 1;
+      } catch (error) {
+        // All errors here are fixed messages. Never forward subprocess output.
+        const reason = error.message.startsWith('Plugin state') || error.message.startsWith('SSSS') ? 'Plugin state is unavailable' : error.message;
+        emit(ctx, { ok: false, error: reason }, `Auth failed: ${reason}`);
+        return 1;
+      }
+    },
+  },
+};

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

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, tr, operation, output } from '../lib/context.mjs';
+
+// Git treats 1..127 (except 125) as a bad revision. Abort on runner failures.
+const RUNNER = `const {spawnSync}=require('node:child_process');
+const r=spawnSync(process.env.GIT_PLUGIN_TR_BIN||'total-recall',['code-quality','check','--json'],{encoding:'utf8',shell:false,maxBuffer:16777216});
+let data;try{data=JSON.parse(r.stdout)}catch{}
+const valid=data&&typeof data.ok==='boolean';
+process.exitCode=r.error||!valid||![0,1,125].includes(r.status)?128:r.status===125?125:r.status===0&&data.ok?0:1;`;
+
+export const operations = {
+  'bisect-agent': operation('Find the first bad commit with the repository quality gate', 'bisect-agent <good> <bad> [--json]', async (args, ctx) => {
+    if (args.length !== 2 || args.some(arg => arg.startsWith('-'))) throw new Error('Supply good and bad revisions');
+    if (git(ctx, ['status', '--porcelain=v1', '-z']).length) throw new Error('Bisect requires a clean tree');
+    const bisectStart = git(ctx, ['rev-parse', '--git-path', 'BISECT_START']).trim();
+    if (fs.existsSync(path.resolve(ctx.cwd, bisectStart))) throw new Error('A bisect session is already active');
+    const refs = args.map(ref => git(ctx, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]).trim());
+    if (refs[0] === refs[1]) throw new Error('Good and bad revisions must differ');
+    git(ctx, ['merge-base', '--is-ancestor', ...refs]);
+    // Probe the contract before changing HEAD. A failing gate is a valid probe.
+    const probe = tr(ctx, ['code-quality', 'check', '--json']);
+    let report;
+    try { report = JSON.parse(probe.stdout); } catch { /* invalid below */ }
+    if (probe.error || ![0, 1].includes(probe.status) || typeof report?.ok !== 'boolean') throw new Error('Repository code-quality check is unavailable or returned an invalid report');
+    let started = false;
+    try {
+      git(ctx, ['bisect', 'start', refs[1], refs[0]]);
+      started = true;
+      const result = ctx.git(['bisect', 'run', process.execPath, '-e', RUNNER], { env: ctx.env, timeout: 30 * 60 * 1000 });
+      if ((result.status ?? result.code) !== 0 || result.error) throw new Error('Bisect did not identify one bad commit. The gate failed, aborted or skipped revisions.');
+      const firstBad = git(ctx, ['rev-parse', '--verify', 'refs/bisect/bad']).trim();
+      const message = git(ctx, ['show', '-s', '--format=%s', firstBad]).trim();
+      output(ctx, { ok: true, firstBad, message, gate: 'total-recall code-quality check --json' }, `First bad commit: ${firstBad}\n${message}`);
+      return 0;
+    } finally {
+      if (started) git(ctx, ['bisect', 'reset']);
+    }
+  }),
+};

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

@@ -0,0 +1,159 @@
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, realpathSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { emit, jsonResult, stateStore, tr } from '../lib/runtime.mjs';
+import { authGitEnv } from './auth.mjs';
+
+const UPSTREAM = 'https://github.com/git/git';
+const DAY = 24 * 60 * 60 * 1000;
+const compare = (a, b) => {
+  const left = a.split('.').map(Number), right = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (left[i] !== right[i]) return left[i] - right[i];
+  return 0;
+};
+
+export function executable(name, ctx) {
+  for (const dir of (ctx.env.PATH || '').split(path.delimiter)) {
+    const file = path.resolve(ctx.cwd, dir, name);
+    try { accessSync(file, constants.X_OK); if (statSync(file).isFile()) return file; } catch { /* try next PATH entry */ }
+  }
+  return null;
+}
+
+function tool(name, args, ctx, timeout = 15000) {
+  const file = executable(name, ctx);
+  if (!file) return { status: null };
+  return spawnSync(file, args, { cwd: ctx.cwd, env: ctx.env, encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'], timeout, maxBuffer: 16 * 1024 * 1024, shell: false });
+}
+
+function installSource(file, build, ctx) {
+  if (/[/\\](?:Cellar|Homebrew|linuxbrew)[/\\]/i.test(file)) return 'brew';
+  const brew = tool('brew', ['--prefix'], ctx);
+  if (brew.status === 0 && brew.stdout?.trim()) {
+    try { if (file.startsWith(`${realpathSync(brew.stdout.trim())}${path.sep}`)) return 'brew'; } catch { /* invalid prefix */ }
+  }
+  const apt = tool('dpkg-query', ['-S', file], ctx);
+  if (apt.status === 0 && /^git(?::[^:\s]+)?:\s/m.test(apt.stdout || '')) return 'apt';
+  if (file === '/usr/bin/git' && /Apple Git/i.test(build)) return 'apple-clt';
+  return 'other';
+}
+
+async function upstream(ctx, force) {
+  const store = await stateStore(ctx, 'upstream.json');
+  const cached = store.read(null);
+  const age = Date.now() - Date.parse(cached?.checked_at);
+  if (!force && age >= 0 && age < DAY && Array.isArray(cached?.versions) && cached.versions.length &&
+    cached.versions.every(v => /^\d+\.\d+\.\d+$/.test(v))) return { ...cached, cached: true, stale: false };
+  const result = ctx.git(['ls-remote', '--tags', '--refs', UPSTREAM], {
+    env: { ...await authGitEnv(ctx), GIT_TERMINAL_PROMPT: '0' }, timeout: 30000,
+  });
+  const versions = [...new Set((result.stdout || '').split('\n').flatMap(line => {
+    const match = line.match(/^[0-9a-f]+\s+refs\/tags\/v(\d+\.\d+\.\d+)$/);
+    return match ? [match[1]] : [];
+  }))].sort(compare);
+  if (result.status !== 0 || result.error || !versions.length) {
+    return { versions: [], checked_at: cached?.checked_at ?? null, cached: false, stale: true, error: 'Cannot read stable upstream Git releases' };
+  }
+  const value = { versions, checked_at: new Date().toISOString() };
+  store.write(value);
+  return { ...value, cached: false, stale: false };
+}
+
+export async function collectCli(ctx, { force = false } = {}) {
+  const command = executable('git', ctx);
+  if (!command) throw new Error('Git executable was not found in PATH');
+  const resolved = realpathSync(command);
+  const versionRow = ctx.git(['--version']);
+  const build = ctx.git(['version', '--build-options']);
+  const version = versionRow.status === 0 && versionRow.stdout?.match(/^git version (\d+\.\d+\.\d+)(?:\D.*)?\s*$/)?.[1];
+  if (!version || build.status !== 0) throw new Error('Cannot read the Git version and build options');
+  const releases = await upstream(ctx, force);
+  const latest = releases.versions.at(-1) ?? null;
+  const hostname = os.hostname();
+  const report = {
+    version, resolved_path: resolved, install_source: installSource(resolved, versionRow.stdout, ctx),
+    build_options: build.stdout.trimEnd(), latest_upstream: latest,
+    release_notes_url: latest ? `${UPSTREAM}/blob/master/Documentation/RelNotes/${latest}.adoc` : null,
+    versions_behind: latest ? releases.versions.filter(v => compare(v, version) > 0).length : null,
+    checked_at: new Date().toISOString(), hostname,
+    upstream_checked_at: releases.checked_at, upstream_cached: releases.cached, upstream_stale: releases.stale,
+    ...(releases.error ? { error: releases.error } : {}),
+  };
+  const id = Buffer.from(hostname).toString('hex');
+  const store = await stateStore(ctx, `cli-${id}.json`);
+  store.read(null);
+  store.write(report);
+  const events = await stateStore(ctx, 'cli-events.jsonl');
+  events.append({ type: 'git.cli_checked', timestamp: report.checked_at, ...report });
+  return report;
+}
+
+async function allNodes(ctx) {
+  const inventory = jsonResult(tr(['mesh', 'nodes', '--json'], ctx), 'Cannot read mesh nodes');
+  if (!Array.isArray(inventory.nodes) || !inventory.nodes.length) throw new Error('Mesh returned no nodes');
+  const nodes = [];
+  for (const node of inventory.nodes) {
+    const name = node.name || node.hostname || node.id;
+    if (typeof name !== 'string' || !name || name.startsWith('-')) {
+      nodes.push({ ok: false, error: 'Mesh node has no usable name' }); continue;
+    }
+    try {
+      const result = jsonResult(tr(['mesh', 'exec', name, 'total-recall git cli --json'], ctx), 'Node CLI check failed');
+      if (!result.version || !result.hostname || result.error || result.upstream_stale) throw new Error('Node CLI metadata is incomplete');
+      nodes.push({ node: name, ok: true, ...result });
+    } catch { nodes.push({ node: name, ok: false, error: 'Node CLI check failed' }); }
+  }
+  return { ok: nodes.every(node => node.ok), nodes };
+}
+
+async function update(ctx) {
+  const before = await collectCli(ctx, { force: true });
+  if (before.error) throw new Error(before.error);
+  if (before.versions_behind === 0) return { ok: true, updated: false, cli: before };
+  let result;
+  switch (before.install_source) {
+    case 'brew': result = tool('brew', ['upgrade', 'git'], ctx, 15 * 60 * 1000); break;
+    case 'apt': result = tool('apt-get', ['install', '--only-upgrade', '-y', 'git'], ctx, 15 * 60 * 1000); break;
+    case 'apple-clt':
+      if (!executable('brew', ctx)) throw new Error('Apple Command Line Tools Git needs Homebrew; no installer is available');
+      result = tool('brew', ['install', 'git'], ctx, 15 * 60 * 1000); break;
+    default: throw new Error('Git install source is other; no supported updater is available');
+  }
+  if (result.status !== 0 || result.error || result.signal) throw new Error('The Git installer failed; check installer permissions and configured sources');
+  const after = await collectCli(ctx);
+  if (after.error || after.versions_behind !== 0) throw new Error('Git is still behind upstream; the configured source or PATH has no current Git');
+  return { ok: true, updated: after.version !== before.version, previous_version: before.version, cli: after };
+}
+
+export const operations = {
+  cli: {
+    summary: 'Record Git CLI metadata or update Git through its installer',
+    usage: 'cli [--json] [--all-nodes] | cli update [--scheduled]',
+    async run(args, ctx) {
+      const json = ctx.json || args.includes('--json');
+      ctx = { ...ctx, json };
+      const rest = args.filter(a => a !== '--json');
+      const isUpdate = rest[0] === 'update';
+      try {
+        let report;
+        if (!rest.length) report = await collectCli(ctx);
+        else if (rest.length === 1 && rest[0] === '--all-nodes') report = await allNodes(ctx);
+        else if (isUpdate && (rest.length === 1 || (rest.length === 2 && rest[1] === '--scheduled'))) report = await update(ctx);
+        else throw new Error('Use cli [--all-nodes] or cli update [--scheduled]');
+        emit(ctx, report, JSON.stringify(report, null, 2));
+        return report.error || report.ok === false ? 1 : 0;
+      } catch (error) {
+        const reason = error.message;
+        emit(ctx, { ok: false, error: reason, checked_at: new Date().toISOString(), hostname: os.hostname() }, `Git CLI check failed: ${reason}`);
+        if (isUpdate) {
+          // Fixed message only. Installer and service output can contain private data.
+          const alert = tr(['alerts', 'send', '--title', 'Git update failed', '--message', 'Git remains out of date. Run total-recall git cli --json for details.'], ctx);
+          if (alert.status !== 0) console.error('The operator alert could not be delivered');
+        }
+        return 1;
+      }
+    },
+  },
+};

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

@@ -0,0 +1,30 @@
+import { git, tr, ledger, intent, session } from '../lib/context.mjs';
+
+export const guards = [{
+  name: 'commit-memory',
+  before() {},
+  async after(args, ctx, status) {
+    if (args[0] !== 'commit' || status !== 0 || args.some(arg => ['--dry-run', '--short', '--porcelain', '--long'].includes(arg))) return;
+    const sha = git(ctx, ['rev-parse', '--verify', 'HEAD']).trim();
+    const store = await ledger(ctx, 'commits', true);
+    if (store.read([]).some(row => row.sha === sha)) return;
+    const message = git(ctx, ['show', '-s', '--format=%B', sha]).trimEnd();
+    const files = git(ctx, ['diff-tree', '--root', '--no-commit-id', '--name-only', '-r', '-m', '-z', sha]).split('\0').filter(Boolean);
+    const record = { type: 'git.commit_context', sha, message, ...intent(message), files: [...new Set(files)], timestamp: new Date().toISOString() };
+    record.session = session(ctx.env) || record.session;
+    // Save the commit before any optional provider call.
+    store.append(record, { idempotencyKey: `commit-${sha}` });
+    const memory = record.decisions.length ? tr(ctx, ['remember', 'decision', `${record.decisions.join('\n')}\nCommit: ${sha}`, '--project', '--slug', `git-decision-${sha}`]) : null;
+    const available = tr(ctx, ['openwiki', '--help']);
+    let wiki;
+    if (available.status !== 0 || available.error) wiki = { status: 'skipped', reason: 'OpenWiki is unavailable' };
+    else {
+      // The current OpenWiki CLI accepts a refresh request, but has no queue verb.
+      const refresh = tr(ctx, ['openwiki', 'refresh', '--repo', ctx.cwd, '--apply', '--json']);
+      wiki = { status: refresh.status === 0 && !refresh.error ? 'requested' : 'failed', command: 'openwiki refresh' };
+    }
+    store.append({ type: 'git.commit_memory', sha, timestamp: new Date().toISOString(), memory: memory === null ? 'skipped: no named decision' : memory.status === 0 && !memory.error ? 'recorded' : 'failed', openwiki: wiki });
+    if (memory && (memory.status !== 0 || memory.error)) console.error('Commit saved. Repository decision memory failed.');
+    if (wiki.status === 'failed') console.error('Commit saved. OpenWiki refresh failed.');
+  },
+}];

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

@@ -0,0 +1,46 @@
+import { authGitEnv } from './auth.mjs';
+
+const machineEmail = /@(?:localhost|[^@\s]+\.(?:local|lan|home|internal))$|@[^@.\s]+$/i;
+
+export function checkCommit(ctx) {
+  for (const key of ['user.name', 'user.email']) {
+    const row = ctx.git(['config', '--get', key]);
+    if (row.status !== 0 || !row.stdout?.trim()) return `${key} is not configured or cannot be read`;
+    if (key === 'user.email' && machineEmail.test(row.stdout.trim())) return 'user.email names a machine';
+  }
+  // Check the effective identity too. Environment variables can override config.
+  for (const role of ['AUTHOR', 'COMMITTER']) {
+    const identity = ctx.git(['var', `GIT_${role}_IDENT`]);
+    if (identity.status !== 0) return `Cannot read the ${role.toLowerCase()} identity`;
+    const match = identity.stdout?.match(/^(.+) <([^<>]+)> \d+ [+-]\d+\s*$/);
+    if (!match || !match[1].trim()) return `Missing ${role.toLowerCase()} identity`;
+    if (machineEmail.test(match[2])) return `${role.toLowerCase()} email names a machine`;
+  }
+  const head = ctx.git(['symbolic-ref', '-q', 'HEAD']);
+  if (head.status === 1) return 'Refusing to commit on a detached HEAD';
+  if (head.status !== 0) return 'Cannot read HEAD';
+  const conflicts = ctx.git(['ls-files', '--unmerged', '-z']);
+  if (conflicts.status !== 0) return 'Cannot read unresolved conflicts';
+  if (conflicts.stdout) return 'Refusing to commit with unresolved conflicts';
+}
+
+export const operations = {
+  commit: {
+    summary: 'Check identity, conflicts and HEAD, then run git commit',
+    usage: 'commit [git commit arguments]',
+    async run(args, ctx) {
+      try {
+        const reason = checkCommit(ctx);
+        if (reason) { console.error(`Commit refused: ${reason}`); return 1; }
+        const env = await authGitEnv(ctx);
+        // Keep the editor, stdin, hooks and Git output attached to the terminal.
+        const result = ctx.git(['commit', ...args], { env, stdio: 'inherit' });
+        if (result.error || result.signal) return 1;
+        return result.status ?? 1;
+      } catch {
+        console.error('Commit refused: credential helper configuration is unavailable');
+        return 1;
+      }
+    },
+  },
+};

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

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { failure, gitText, output, trJson } from './_support.mjs';
+
+const STALE_MS = 30 * 24 * 60 * 60 * 1000;
+
+export function registeredRepositories(ctx) {
+  let data;
+  try { data = trJson(ctx, ['brain', 'list', '--json']); } catch { /* Older brain list has no JSON mode. */ }
+  const normalize = value => {
+    const rows = Array.isArray(value) ? value : value?.projects || value?.brains || value?.repositories;
+    if (!Array.isArray(rows)) return null;
+    const paths = rows.map(row => typeof row === 'string' ? row : row?.path || row?.root || row?.projectPath);
+    if (paths.some(p => typeof p !== 'string' || !path.isAbsolute(p))) throw new Error('Project registry contains an invalid repository path');
+    return [...new Set(paths)];
+  };
+  const rows = normalize(data);
+  if (rows) return rows;
+  const file = ctx.env?.GIT_PLUGIN_REGISTRY_FILE || path.join(ctx.env?.TR_GLOBAL_BRAIN || ctx.env?.TR_SECRETS_BRAIN || path.join(os.homedir(), '.agent', 'skills', 'total-recall'), 'config', 'project-registry.json');
+  const fallback = normalize(JSON.parse(readFileSync(file, 'utf8')));
+  if (!fallback) throw new Error('Project registry has no repository list');
+  return fallback;
+}
+
+export function inspectRepository(directory, ctx, now = Date.now()) {
+  const local = { ...ctx, git: (args, options) => ctx.git(['-C', directory, ...args], options) };
+  const errors = [];
+  const report = { path: directory, dirty: null, unpushed: null, behind: null, diverged: null,
+    staleStashes: null, abandonedWorktrees: null, upstream: null, errors };
+  const get = args => {
+    try { return gitText(local, args); } catch { errors.push(args[0]); return null; }
+  };
+  if (get(['rev-parse', '--is-inside-work-tree'])?.trim() !== 'true') return { ...report, error: 'Repository is unavailable' };
+  const status = get(['status', '--porcelain=v1', '-z']);
+  if (status !== null) report.dirty = status.length > 0;
+  const upstream = local.git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+  if (upstream.status === 0) {
+    report.upstream = upstream.stdout.trim();
+    const counts = get(['rev-list', '--left-right', '--count', '@{upstream}...HEAD'])?.trim().match(/^(\d+)\s+(\d+)$/);
+    if (counts) { report.behind = Number(counts[1]); report.unpushed = Number(counts[2]); report.diverged = report.behind > 0 && report.unpushed > 0; }
+  } else {
+    // No upstream is unknown sync state, not zero unpushed commits.
+    report.upstreamStatus = 'unavailable';
+    if (!/no upstream configured|no such branch|does not point to a branch|unknown revision/i.test(upstream.stderr || '')) errors.push('upstream');
+  }
+  const stashes = get(['stash', 'list', '--format=%H%x00%ct%x00%gs']);
+  if (stashes !== null) report.staleStashes = stashes.split('\n').filter(Boolean).flatMap(row => {
+    const [commit, timestamp, message] = row.split('\0');
+    return Number(timestamp) * 1000 < now - STALE_MS ? [{ commit, timestamp: Number(timestamp), message }] : [];
+  });
+  const trees = get(['worktree', 'list', '--porcelain', '-z']);
+  if (trees !== null) report.abandonedWorktrees = trees.split('\0\0').filter(Boolean).slice(1).flatMap(record => {
+    const fields = Object.fromEntries(record.split('\0').filter(Boolean).map(row => {
+      const i = row.indexOf(' '); return i < 0 ? [row, true] : [row.slice(0, i), row.slice(i + 1)];
+    }));
+    if (fields.locked) return [];
+    if (fields.prunable || !existsSync(fields.worktree)) return [{ path: fields.worktree, reason: 'missing-or-prunable' }];
+    const treeCtx = { ...ctx, git: (a, options) => ctx.git(['-C', fields.worktree, ...a], options) };
+    const state = treeCtx.git(['status', '--porcelain=v1', '-z']);
+    const last = treeCtx.git(['log', '-1', '--format=%ct']);
+    if (state.status !== 0 || last.status !== 0) { errors.push('worktree-inspection'); return []; }
+    return !state.stdout && Number(last.stdout.trim()) * 1000 < now - STALE_MS
+      ? [{ path: fields.worktree, reason: 'clean-with-old-head', candidate: true }] : [];
+  });
+  return report;
+}
+
+function containingCheckouts(directory, commit, ctx) {
+  const local = { ...ctx, git: (args, options) => ctx.git(['-C', directory, ...args], options) };
+  const oid = gitText(local, ['rev-parse', '--verify', '--end-of-options', `${commit}^{commit}`]).trim();
+  const refs = gitText(local, ['for-each-ref', `--contains=${oid}`, '--format=%(refname)', 'refs/heads', 'refs/remotes', 'refs/tags']).trim().split('\n').filter(Boolean);
+  const records = gitText(local, ['worktree', 'list', '--porcelain', '-z']).split('\0\0').filter(Boolean);
+  const checkouts = [];
+  for (const record of records) {
+    const file = record.split('\0').find(row => row.startsWith('worktree '))?.slice(9);
+    if (!file) continue;
+    const contains = ctx.git(['-C', file, 'merge-base', '--is-ancestor', oid, 'HEAD']);
+    if (contains.status === 0) checkouts.push(file);
+    else if (contains.status !== 1) throw new Error('Cannot inspect a registered checkout');
+  }
+  return { path: directory, commit: oid, objectPresent: true, refs, checkouts };
+}
+
+function localReport(ctx, commit) {
+  const errors = [];
+  const repositories = [];
+  for (const directory of registeredRepositories(ctx)) {
+    try {
+      if (commit) {
+        const contains = ctx.git(['-C', directory, 'cat-file', '-e', `${commit}^{commit}`]);
+        if (contains.status !== 0) {
+          if (ctx.git(['-C', directory, 'rev-parse', '--git-dir']).status !== 0) errors.push({ path: directory, error: 'Repository is unavailable' });
+          continue;
+        }
+        repositories.push(containingCheckouts(directory, commit, ctx));
+      } else {
+        const report = inspectRepository(directory, ctx);
+        repositories.push(report);
+        if (report.error || report.errors.length) errors.push({ path: directory, error: report.error || report.errors.join(', ') });
+      }
+    } catch { errors.push({ path: directory, error: 'Repository inspection failed' }); }
+  }
+  return { node: os.hostname(), repositories, errors, observedAt: new Date().toISOString(), syncSource: 'local refs; no fetch' };
+}
+
+function remoteReports(ctx, commit) {
+  const inventory = trJson(ctx, ['mesh', 'nodes', '--json']);
+  const rows = Array.isArray(inventory) ? inventory : inventory.nodes;
+  if (!Array.isArray(rows)) throw new Error('Mesh returned no node list');
+  const reports = [];
+  const seen = new Set();
+  for (const node of rows) {
+    const name = typeof node === 'string' ? node : node.hostname || node.name || node.id;
+    if (!name || seen.has(name) || name === os.hostname() || node.self || node.isLocal || node.isCurrentNode) continue;
+    seen.add(name);
+    try {
+      if (node.online === false || node.status === 'offline') throw new Error('Node is offline');
+      // Mesh joins words for remote execution. Quote the whole fixed command once.
+      const quote = word => `'${word.replaceAll("'", "'\\''")}'`;
+      const namespace = 'git';
+      const command = ['total-recall', namespace, commit ? 'where' : 'fleet', ...(commit ? [commit, '--local'] : []), '--json'].map(quote).join(' ');
+      const response = trJson(ctx, ['mesh', 'exec', name, command, '--json']);
+      if (response.exitCode !== 0 || typeof response.stdout !== 'string') throw new Error('Remote command failed');
+      const parsed = JSON.parse(response.stdout);
+      if (!Array.isArray(parsed.nodes) || typeof parsed.ok !== 'boolean') throw new Error('Remote report is invalid');
+      reports.push(...parsed.nodes);
+    } catch { reports.push({ node: name, repositories: [], errors: [{ error: 'Node is unavailable or returned no valid report' }] }); }
+  }
+  return reports;
+}
+
+async function run(args, ctx, where = false) {
+  try {
+    const flags = new Set(where ? ['--local', '--all-nodes'] : ['--all-nodes']);
+    const words = args.filter(a => !a.startsWith('-'));
+    if (args.some(a => a.startsWith('-') && !flags.has(a)) || words.length !== (where ? 1 : 0)) throw new Error(where ? 'Use where <commit> [--local]' : 'Use fleet [--all-nodes]');
+    const commit = words[0];
+    if (where && !/^[a-f0-9]{4,64}$/i.test(commit)) throw new Error('Supply a commit object id (4 to 64 hexadecimal characters)');
+    const nodes = [localReport(ctx, commit)];
+    if (args.includes('--all-nodes') || where && !args.includes('--local')) nodes.push(...remoteReports(ctx, commit));
+    const ok = nodes.every(node => !node.errors?.length);
+    const result = { ok, ...(where ? { commit } : {}), nodes };
+    const lines = nodes.flatMap(node => [node.node, ...node.repositories.map(repo => where
+      ? `  ${repo.path}: ${repo.checkouts.length} checkouts; ${repo.refs.length} refs`
+      : `  ${repo.path}: dirty=${repo.dirty ?? 'unknown'} unpushed=${repo.unpushed ?? 'unknown'} behind=${repo.behind ?? 'unknown'} diverged=${repo.diverged ?? 'unknown'} stale-stashes=${repo.staleStashes?.length ?? 'unknown'} abandoned-worktrees=${repo.abandonedWorktrees?.length ?? 'unknown'}`),
+    ...(node.errors || []).map(e => `  unavailable: ${e.path || node.node}`)]);
+    output(ctx, result, lines.join('\n'));
+    return ok ? 0 : 1;
+  } catch (error) { return failure(ctx, error); }
+}
+
+export const operations = {
+  fleet: { summary: 'Report repository state on this node or every mesh node', usage: 'fleet [--all-nodes] [--json]', run: (args, ctx) => run(args, ctx) },
+  where: { summary: 'Find machines and checkouts that contain a commit', usage: 'where <commit> [--local] [--json]', run: (args, ctx) => run(args, ctx, true) },
+};