total-recall-brain 3.43.3 → 3.45.0

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

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

@@ -0,0 +1,58 @@
+import { randomUUID } from 'node:crypto';
+import { helpOnly, invocation, repoId, stateStore } from './_support.mjs';
+
+export async function guardPush(args, ctx) {
+  const call = invocation(args, ctx);
+  if (call.command !== 'push' || helpOnly(args)) return;
+  const rewritten = [];
+  let reason;
+  let deletion = false;
+  let force = false;
+  let options = true;
+  let remoteSeen = false;
+  for (let i = 0; i < call.args.length; i += 1) {
+    const a = call.args[i];
+    if (options && ['--repo', '--receive-pack', '--exec', '--push-option', '-o'].includes(a)) {
+      if (a === '--repo') remoteSeen = true;
+      rewritten.push(a);
+      if (call.args[i + 1] !== undefined) rewritten.push(call.args[++i]);
+      continue;
+    }
+    if (options && a === '--reason') {
+      if (reason !== undefined || !call.args[i + 1] || call.args[i + 1].startsWith('-')) return { refuse: 'Supply one --reason <text>' };
+      reason = call.args[++i]; continue;
+    }
+    if (options && a.startsWith('--reason=')) {
+      if (reason !== undefined) return { refuse: 'Supply one --reason <text>' };
+      reason = a.slice(9); continue;
+    }
+    if (a === '--') options = false;
+    if (a.startsWith('--repo=')) remoteSeen = true;
+    if (options && ['--delete', '-d'].includes(a)) deletion = true;
+    if (remoteSeen && /^\+?:[^:]+$/.test(a)) deletion = true;
+    if (options && ['--force', '-f'].includes(a)) { force = true; continue; }
+    if (options && /^-[fvdqnu]+$/.test(a)) {
+      if (a.includes('f')) force = true;
+      if (a.includes('d')) deletion = true;
+      const remaining = a.slice(1).replaceAll('f', '');
+      if (remaining) rewritten.push(`-${remaining}`);
+      continue;
+    }
+    if (options && a === '--mirror') return { refuse: '--mirror can delete remote refs without a lease. Use explicit refs.' };
+    if (remoteSeen && a.startsWith('+') && a.length > 1) { force = true; rewritten.push(a.slice(1)); }
+    else rewritten.push(a);
+    if (!a.startsWith('-') && !remoteSeen) remoteSeen = true;
+  }
+  if (deletion) {
+    if (!reason?.trim()) return { refuse: 'Remote branch deletion requires --reason <text>' };
+    try {
+      const store = await stateStore(call.ctx);
+      store.append({ id: randomUUID(), type: 'git.remote_delete', timestamp: new Date().toISOString(),
+        repository: repoId(call.ctx), reason: reason.trim(), status: 'requested' });
+    } catch { return { refuse: 'Cannot record the remote deletion reason' }; }
+  }
+  if (force && !rewritten.some(a => a === '--force-with-lease' || a.startsWith('--force-with-lease='))) rewritten.unshift('--force-with-lease');
+  return { args: [...call.prefix, 'push', ...rewritten] };
+}
+
+export const guards = [{ name: 'force-push', before: guardPush }];

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

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { git, tr, operation, output } from '../lib/context.mjs';
+
+function changeRows(ctx, head) {
+  let rows;
+  if (ctx.env.GIT_PLUGIN_CHANGE_LOG) {
+    const text = fs.readFileSync(ctx.env.GIT_PLUGIN_CHANGE_LOG, 'utf8');
+    rows = text.trim().startsWith('[') ? JSON.parse(text) : text.split('\n').filter(Boolean).map(row => JSON.parse(row));
+  } else {
+    const result = tr(ctx, ['recall', 'file-change agent session records', '--project', '--local', '--format', 'json']);
+    if (result.status !== 0 || result.error) return [];
+    try { rows = JSON.parse(result.stdout); } catch { return []; }
+  }
+  if (!Array.isArray(rows)) throw new Error('File-change records must be an array or JSONL');
+  const root = git(ctx, ['rev-parse', '--show-toplevel']).trim();
+  const since = Number(git(ctx, ['show', '-s', '--format=%ct', head]).trim()) * 1000;
+  return rows.flatMap(row => {
+    let data = row;
+    if (row.type === 'session' && typeof row.body === 'string') {
+      try { data = { ...row, ...JSON.parse(row.body) }; } catch { return []; }
+    }
+    return (data.changes || [data]).map(change => ({ ...data, ...change, session: change.session || data.session || data.session_id, file: change.file || change.path }));
+  }).filter(row => row.file && row.session &&
+    (row.repository || row.cwd) && fs.existsSync(row.repository || row.cwd) && fs.realpathSync(row.repository || row.cwd) === fs.realpathSync(root) &&
+    (row.base === head || (!row.base && Date.parse(row.timestamp) >= since)))
+    .map(row => ({ ...row, file: path.relative(root, path.resolve(root, row.file)), start: Number(row.startLine ?? row.start_line), end: Number(row.endLine ?? row.end_line ?? row.startLine ?? row.start_line) }));
+}
+function dirtyFiles(ctx) {
+  return [...new Set([...git(ctx, ['diff', 'HEAD', '--name-only', '-z', '--no-renames']).split('\0'), ...git(ctx, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0')].filter(Boolean))];
+}
+const overlap = (a, b) => Number.isInteger(a.start) && Number.isInteger(a.end) && Number.isInteger(b.start) && Number.isInteger(b.end) && a.start <= b.end && b.start <= a.end;
+function fingerprint(root, file) {
+  const target = path.join(root, file);
+  const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+  if (!stat) return 'deleted';
+  if (!stat.isFile() && !stat.isSymbolicLink()) throw new Error('Submodule and directory changes need manual grouping');
+  return `${stat.mode}:${crypto.createHash('sha256').update(stat.isSymbolicLink() ? fs.readlinkSync(target) : fs.readFileSync(target)).digest('hex')}`;
+}
+
+export const operations = {
+  group: operation('Group dirty changes by the session that wrote them', 'group [--apply] [--json]', async (args, ctx) => {
+    if (args.some(arg => arg !== '--apply') || args.length > 1) throw new Error('Use group [--apply]');
+    if (git(ctx, ['diff', '--name-only', '--diff-filter=U', '-z'])) throw new Error('Resolve conflicts before grouping');
+    const head = git(ctx, ['rev-parse', '--verify', 'HEAD']).trim();
+    const root = git(ctx, ['rev-parse', '--show-toplevel']).trim();
+    const sourceGit = ctx.git;
+    ctx = { ...ctx, cwd: root, git: (args, options) => sourceGit(args, { ...options, cwd: root }) };
+    const files = dirtyFiles(ctx);
+    const fingerprints = new Map(files.map(file => [file, fingerprint(root, file)]));
+    const records = changeRows(ctx, head);
+    const warnings = [];
+    for (let i = 0; i < records.length; i++) for (const other of records.slice(i + 1)) {
+      const row = records[i];
+      if (row.file === other.file && row.session !== other.session && overlap(row, other)) warnings.push(`${row.file}:${Math.max(row.start, other.start)}-${Math.min(row.end, other.end)}: sessions ${row.session} and ${other.session} touch the same lines`);
+    }
+    const groups = new Map();
+    const add = (session, unit, reason = null) => {
+      const group = groups.get(session) || { session, files: [], units: [], reasons: [] };
+      if (!group.files.includes(unit.file)) group.files.push(unit.file);
+      if (reason && !group.reasons.includes(reason)) group.reasons.push(reason);
+      group.units.push(unit); groups.set(session, group);
+    };
+    for (const file of files) {
+      const changes = records.filter(row => row.file === file);
+      const sessions = [...new Set(changes.map(row => row.session))];
+      const patch = git(ctx, ['diff', 'HEAD', '--no-ext-diff', '--no-textconv', '--no-renames', '--binary', '--unified=0', '--', file]);
+      if (sessions.length <= 1) { add(sessions[0] || 'unknown', { file, whole: true }, sessions.length ? null : 'No current session record identifies this change'); continue; }
+      const first = patch.indexOf('@@ ');
+      if (first < 0 || patch.includes('GIT binary patch')) { add('unknown', { file, whole: true }, 'Multiple sessions wrote this file. The changes have no separate text hunks'); continue; }
+      const header = patch.slice(0, first);
+      const chunks = patch.slice(first).split(/(?=^@@ )/m).filter(Boolean);
+      for (const chunk of chunks) {
+        const match = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@([^\n]*)\n/.exec(chunk);
+        if (!match) throw new Error('Cannot parse a changed hunk');
+        const oldStart = Number(match[1]), oldCount = Number(match[2] ?? 1), start = Number(match[3]), count = Number(match[4] ?? 1);
+        const owners = [...new Set(changes.filter(row => overlap(row, { start, end: start + Math.max(count, 1) - 1 })).map(row => row.session))];
+        add(owners.length === 1 ? owners[0] : 'unknown', { file, header, oldStart, oldCount, start, count, suffix: match[5], body: chunk.slice(match[0].length) }, owners.length === 1 ? null : 'A hunk has missing or shared session attribution');
+      }
+    }
+    const publicGroups = [...groups.values()].map(({ units, ...row }) => ({ ...row, hunks: units.length }));
+    if (args.includes('--apply')) {
+      if (warnings.length || [...groups.values()].some(row => row.session === 'unknown' && row.reasons.some(reason => !reason.startsWith('No current')))) throw new Error(`Shared changes need manual grouping. ${warnings.join('; ')}`);
+      const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'git-group-'));
+      const applied = [];
+      const completed = [];
+      const initialIndex = git(ctx, ['write-tree']).trim();
+      try {
+        for (const group of groups.values()) {
+          const env = { ...ctx.env, GIT_INDEX_FILE: path.join(tmp, 'index'), CLAUDE_SESSION_ID: group.session, CODEX_SESSION_ID: group.session };
+          git(ctx, ['read-tree', 'HEAD'], { env });
+          for (const unit of group.units) {
+            if (fingerprint(root, unit.file) !== fingerprints.get(unit.file)) throw new Error(`File ${unit.file} changed during grouping. Completed groups: ${completed.join(', ') || 'none'}`);
+            if (unit.whole) git(ctx, ['add', '--all', '--', unit.file], { env });
+            else {
+              const before = applied.filter(row => row.file === unit.file && row.oldStart < unit.oldStart).reduce((sum, row) => sum + row.count - row.oldCount, 0);
+              const patch = `${unit.header}@@ -${unit.oldStart + before},${unit.oldCount} +${unit.oldStart + before + (unit.oldCount === 0 ? 1 : 0) - (unit.count === 0 ? 1 : 0)},${unit.count} @@${unit.suffix}\n${unit.body}`;
+              git(ctx, ['apply', '--cached', '--unidiff-zero', '--recount', '-'], { env, input: patch });
+              applied.push(unit);
+            }
+          }
+          const message = `Update ${group.files.join(', ')}\n\nAgent-Session: ${group.session}\n`;
+          const result = tr({ ...ctx, env }, ['git', 'commit', '--file=-'], { input: message });
+          if (result.status !== 0 || result.error) throw new Error(`Session ${group.session} could not commit. Completed groups: ${completed.join(', ') || 'none'}`);
+          completed.push(group.session);
+        }
+      } finally {
+        // Synchronize the real index with completed commits. Keep worktree content.
+        if (completed.length && git(ctx, ['write-tree']).trim() === initialIndex) git(ctx, ['read-tree', 'HEAD']);
+        else if (completed.length) warnings.push('The index changed during grouping. The index was left intact.');
+        fs.rmSync(tmp, { recursive: true, force: true });
+      }
+    }
+    output(ctx, { ok: true, groups: publicGroups, warnings, applied: args.includes('--apply') }, [...publicGroups.map(row => `${row.session}: ${row.files.join(', ')}${row.reasons.length ? ` (${row.reasons.join('; ')})` : ''}`), ...warnings.map(row => `Warning: ${row}`)].join('\n') || 'The tree is clean.');
+    return 0;
+  }),
+};

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

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { exportBundle, validateBundle } from '@gregiteen/ssss-cli/bundle';
+import { serializeDocument } from '@gregiteen/ssss-cli/frontmatter';
+import { git, trJSON, activePlan, ledger, operation, output } from '../lib/context.mjs';
+
+export const operations = {
+  handoff: operation('Pack a branch, project tracker and related memory in an SSSS bundle', 'handoff <branch> [--out <file>] [--json]', async (args, ctx) => {
+    if (['create', 'verify', 'list-heads', 'unbundle'].includes(args[0])) {
+      const result = ctx.git(['bundle', ...args]);
+      if (result.stdout) process.stdout.write(result.stdout);
+      if (result.stderr) process.stderr.write(result.stderr);
+      return result.status ?? result.code ?? 1;
+    }
+    const [branch, flag, name] = args;
+    if (!branch || branch.startsWith('-') || (args.length !== 1 && !(args.length === 3 && flag === '--out' && name))) throw new Error('Use bundle <branch> [--out <file>]');
+    git(ctx, ['check-ref-format', '--branch', branch]);
+    const ref = `refs/heads/${branch}`;
+    const sha = git(ctx, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]).trim();
+    let plan;
+    if (git(ctx, ['branch', '--show-current']).trim() === branch) plan = activePlan(ctx);
+    else {
+      const paths = git(ctx, ['ls-tree', '-r', '--name-only', '-z', ref, '--', 'docs/projects/in-progress']).split('\0').filter(file => file.endsWith('_PROJECT_TRACKER.md'));
+      if (paths.length !== 1) throw new Error('The branch must contain one active tracker');
+      plan = { tracker: paths[0], body: git(ctx, ['show', `${ref}:${paths[0]}`]) };
+    }
+    if (!plan.tracker) throw new Error('A hand-off bundle requires an active tracker');
+    const commits = new Set(git(ctx, ['rev-list', ref]).trim().split('\n'));
+    const store = await ledger(ctx);
+    const records = store?.read([]).filter(row => commits.has(row.sha)) || [];
+    const memory = trJSON(ctx, ['recall', `${branch} ${records.flatMap(row => row.trackerItems || []).join(' ')}`, '--local', '--project', '--format', 'json']);
+    if (!Array.isArray(memory)) throw new Error('Related memory must be a result array');
+    const out = path.resolve(ctx.cwd, name || `${branch.replace(/[^\w.-]/g, '-')}.ucw.json`);
+    if (fs.existsSync(out)) throw new Error('The output file already exists');
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'git-handoff-'));
+    try {
+      const pack = path.join(tmp, 'branch.bundle');
+      git(ctx, ['bundle', 'create', pack, ref]);
+      git(ctx, ['bundle', 'verify', pack]);
+      const vault = path.join(tmp, 'vault');
+      fs.mkdirSync(vault);
+      const asset = (file, title, content, encoding = 'utf-8', mime = 'text/plain') => {
+        const bytes = encoding === 'base64' ? Buffer.from(content, 'base64') : Buffer.from(content);
+        fs.writeFileSync(path.join(vault, file), serializeDocument({ type: 'asset', name: title, title, description: `Git hand-off: ${title}`, timestamp: new Date().toISOString(), mime_type: mime, encoding, x_portability: 'tenant_private', hash: `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`, size_bytes: bytes.length }, content));
+      };
+      asset('branch.md', `${branch}.bundle`, fs.readFileSync(pack).toString('base64'), 'base64', 'application/x-git-bundle');
+      asset('tracker.md', path.basename(plan.tracker), plan.body, 'utf-8', 'text/markdown');
+      asset('memory.md', 'Related repository memory', JSON.stringify({ branch, sha, records, memory }, null, 2), 'utf-8', 'application/json');
+      const bundle = exportBundle(vault, { name: `Git hand-off: ${branch}`, description: 'Branch, active tracker and related repository memory', profile: 'backup', exportedAt: new Date().toISOString() });
+      const check = validateBundle(bundle);
+      if (!check.valid) throw new Error(`Invalid SSSS hand-off bundle: ${check.errors.join('; ')}`);
+      fs.writeFileSync(out, JSON.stringify(bundle, null, 2), { flag: 'wx', mode: 0o600 });
+      output(ctx, { ok: true, file: out, branch, sha, manifest: bundle.manifest }, `Saved ${out}`);
+      return 0;
+    } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+  }),
+};