total-recall-brain 3.43.3 → 3.45.0

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

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