total-recall-brain 3.44.0 → 3.46.0

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;
+}

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;
+      }
+    },
+  },
+};