total-recall-brain 3.44.0 → 3.46.0

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

@@ -0,0 +1,81 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { parseArgs } from 'node:util';
+import { collectAudit, collectIdentity, isPassthrough } from '../../cli.mjs';
+import { checkSecrets } from './secret-firewall.mjs';
+import { failure, gitText, helpOnly, invocation, outgoingCommits, output, prospectiveCommit, repoId, stateStore } from './_support.mjs';
+
+export const machineEmail = address => {
+  const domain = address.split('@')[1]?.toLowerCase();
+  return !domain || !domain.includes('.') || /\.(local|lan|home|internal|localdomain)$/.test(domain) || domain === 'localhost';
+};
+
+async function visibility(ctx) {
+  // No remote: nothing can be published, so the repository is local, not public.
+  if (!String(ctx.git(['remote']).stdout || '').trim()) return 'LOCAL';
+  const repository = repoId(ctx);
+  // Remote URLs can contain credentials. Cache only the URL fingerprint.
+  const remote = createHash('sha256').update(ctx.git(['config', '--get', 'remote.origin.url']).stdout?.trim() || '').digest('hex');
+  let store;
+  let cached;
+  try {
+    store = await stateStore(ctx, 'visibility');
+    cached = store.read({})[repository];
+  } catch { /* Live visibility can still prove the rule. */ }
+  const result = spawnSync(ctx.env?.GIT_PLUGIN_GH_BIN || 'gh', ['repo', 'view', '--json', 'visibility'], {
+    cwd: gitText(ctx, ['rev-parse', '--show-toplevel']).trim(), env: ctx.env, encoding: 'utf8', shell: false, timeout: 15000,
+  });
+  let value;
+  try { if (result.status === 0) value = JSON.parse(result.stdout).visibility?.toUpperCase(); } catch { /* refuse unknown */ }
+  if (['PUBLIC', 'PRIVATE', 'INTERNAL'].includes(value)) {
+    if (store) {
+      const cache = store.read({});
+      cache[repository] = { value, remote, checkedAt: new Date().toISOString() };
+      store.write(cache);
+    }
+    return value;
+  }
+  if (cached?.remote === remote && ['PUBLIC', 'PRIVATE', 'INTERNAL'].includes(cached.value) &&
+      Date.now() - Date.parse(cached.checkedAt) < 24 * 60 * 60 * 1000) return cached.value;
+  throw new Error('Cannot verify repository visibility for internal project records');
+}
+
+export async function checkRules(args, ctx) {
+  const call = invocation(args, ctx);
+  if (!['commit', 'push'].includes(call.command) || helpOnly(args)) return;
+  let prospective;
+  try {
+    const paths = new Set();
+    const checkIdentity = text => {
+      const emails = [...text.matchAll(/<([^<>\s]+)>/g)].map(m => m[1]);
+      if (!emails.length || emails.some(machineEmail)) throw new Error('Refusing a machine-derived identity');
+    };
+    if (call.command === 'commit') {
+      prospective = prospectiveCommit(call.ctx, call.args);
+      call.ctx = prospective.ctx;
+      for (const type of ['GIT_AUTHOR_IDENT', 'GIT_COMMITTER_IDENT']) checkIdentity(gitText(call.ctx, ['var', type]));
+      const authorAt = call.args.findIndex(a => a === '--author');
+      const author = authorAt >= 0 ? call.args[authorAt + 1] : call.args.find(a => a.startsWith('--author='))?.slice(9);
+      if (author) checkIdentity(author);
+      // --amend and -C/-c reuse identities from history unless reset-author is set.
+      if (!call.args.includes('--reset-author')) {
+        const reuseAt = call.args.findIndex(a => ['-C', '-c', '--reuse-message', '--reedit-message'].includes(a));
+        const reuse = reuseAt >= 0 ? call.args[reuseAt + 1] : call.args.find(a => /^--(reuse|reedit)-message=/.test(a))?.split('=').slice(1).join('=');
+        if (reuse || call.args.includes('--amend')) checkIdentity(gitText(call.ctx, ['show', '-s', '--format=%an <%ae>', reuse || 'HEAD']));
+      }
+      for (const file of gitText(call.ctx, ['diff', '--cached', '--name-only', '--diff-filter=ACMRT', '-z', '--']).split('\0').filter(Boolean)) paths.add(file);
+    } else {
+      for (const commit of outgoingCommits(call.ctx, call.args)) {
+        checkIdentity(gitText(call.ctx, ['show', '-s', '--format=%an <%ae>%n%cn <%ce>', commit]));
+        for (const file of gitText(call.ctx, ['ls-tree', '-r', '--name-only', '-z', commit]).split('\0').filter(Boolean)) paths.add(file);
+      }
+    }
+    if ([...paths].some(file => file === '.github/workflows' || file.startsWith('.github/workflows/'))) return { refuse: 'Workflow files are prohibited (.github/workflows)' };
+    if ([...paths].some(file => file.startsWith('docs/projects/')) && await visibility(call.ctx) === 'PUBLIC') {
+      return { refuse: 'Internal project records cannot enter a public repository (docs/projects)' };
+    }
+  } catch (error) { return { refuse: error.message }; }
+  finally { prospective?.cleanup(); }
+}
+
+export const guards = [{ name: 'rules', before: checkRules }];

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

@@ -0,0 +1,92 @@
+import { spawnSync } from 'node:child_process';
+import { gitText, helpOnly, invocation, outgoingCommits, prospectiveCommit } from './_support.mjs';
+
+/**
+ * Ask the auth plugin which stored values occur in the text. One call per check; values never
+ * enter this process, only key names come back (`auth secret scan --stdin`, exit 1 on a match).
+ */
+export function scanText(ctx, text) {
+  const result = spawnSync(ctx.env?.GIT_PLUGIN_TR_BIN || 'total-recall', ['auth', 'secret', 'scan', '--stdin', '--json'], {
+    cwd: ctx.cwd, env: ctx.env, input: text, encoding: 'utf8', shell: false, timeout: 120000, maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.error) throw new Error(`auth secret scan could not start (${result.error.code || 'spawn failed'})`);
+  if (result.signal) throw new Error(`auth secret scan was stopped (${result.signal})`);
+  let reply = null;
+  try { reply = JSON.parse(result.stdout); } catch { /* named below; a parse error can quote the output */ }
+  if (![0, 1].includes(result.status) || !reply) throw new Error(scanFailure(result));
+  if (!Array.isArray(reply.keys)) throw new Error('auth secret scan returned no key list');
+  return reply.keys;
+}
+
+/**
+ * Name why the scan gave no result without forwarding the child's output,
+ * which can hold credential material. A generic "could not complete" hid that
+ * auth was simply turned off for the repository (2026-11-12).
+ */
+function scanFailure(result) {
+  const stderr = String(result.stderr || '');
+  if (/Plugin auth is inactive/.test(stderr)) return 'the auth plugin is turned off for this repository; run total-recall plugin on auth';
+  if (/Unknown (plugin|command)|not installed/i.test(stderr)) return 'the auth plugin is not installed here or has no secret scan';
+  return `auth secret scan exited ${result.status} without a result`;
+}
+
+/**
+ * The publishable part of a patch: everything except removed lines. A removed line is content the
+ * commit takes out; scanning it blocked the very commit that redacts a secret already in history
+ * (a project tracker, 2026-11-12). Added lines, headers, binary patches and the commit message
+ * are still scanned, and every staged or outgoing blob is scanned whole.
+ */
+export function publishedPatchText(patch) {
+  return String(patch).split('\n').filter((line) => !(line.startsWith('-') && !line.startsWith('---'))).join('\n');
+}
+
+export function checkSecrets(args, ctx) {
+  const call = invocation(args, ctx);
+  if (!['commit', 'push'].includes(call.command) || helpOnly(args)) return;
+  let prospective;
+  try {
+    if (call.command === 'commit') { prospective = prospectiveCommit(call.ctx, call.args); call.ctx = prospective.ctx; }
+    // Collect what would be published, then scan it in one auth call.
+    const chunks = [];
+    const add = value => chunks.push(Buffer.isBuffer(value) ? value.toString('utf8') : value);
+    if (call.command === 'commit') {
+      add(publishedPatchText(gitText(call.ctx, ['diff', '--cached', '--no-ext-diff', '--no-textconv', '--binary', '--'])));
+      const paths = gitText(call.ctx, ['diff', '--cached', '--name-only', '--diff-filter=ACMRT', '-z', '--']).split('\0').filter(Boolean);
+      for (const file of paths) {
+        const row = call.ctx.git(['show', `:${file}`], { encoding: null });
+        if (row.error || row.status !== 0) throw new Error('Cannot scan a staged object');
+        add(row.stdout);
+      }
+    } else {
+      const scanned = new Set();
+      for (const commit of outgoingCommits(call.ctx, call.args)) {
+        add(publishedPatchText(gitText(call.ctx, ['show', '--format=fuller', '--root', '--no-ext-diff', '--no-textconv', '--binary', commit, '--'])));
+        // Raw blobs of the files this commit changed: a binary patch does not contain the original bytes.
+        const changed = gitText(call.ctx, ['diff-tree', '-r', '-z', '--root', '--no-commit-id', commit]).split('\0').filter(Boolean);
+        for (const entry of changed) {
+          const m = entry.match(/^:\d+ \d+ [a-f0-9]+ ([a-f0-9]+) [ACMRT]/);
+          if (!m || /^0+$/.test(m[1]) || scanned.has(m[1])) continue;
+          scanned.add(m[1]);
+          const row = call.ctx.git(['cat-file', 'blob', m[1]], { encoding: null });
+          if (row.error || row.status !== 0) throw new Error('Cannot scan an outgoing object');
+          add(row.stdout);
+        }
+      }
+    }
+    // Batches stay under the auth scan input limit (64 MB) with room to spare.
+    const matches = new Set();
+    let batch = [], size = 0;
+    const flush = () => { if (batch.length) for (const key of scanText(call.ctx, batch.join('\n'))) matches.add(key); batch = []; size = 0; };
+    for (const chunk of chunks) {
+      if (size + chunk.length > 32 * 1024 * 1024) flush();
+      batch.push(chunk); size += chunk.length + 1;
+    }
+    flush();
+    if (matches.size) return { refuse: `Auth secret match: ${[...matches].sort().join(', ')}` };
+  } catch (error) {
+    // Our own messages only: git failures and scanFailure never carry file or secret content.
+    return { refuse: `Secret firewall could not complete: ${error.message}. Check auth store and repository access.` };
+  } finally { prospective?.cleanup(); }
+}
+
+export const guards = [{ name: 'secret-firewall', before: checkSecrets }];

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

@@ -0,0 +1,156 @@
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { failure, gitText, helpOnly, invocation, output, repoId, stateStore } from './_support.mjs';
+
+export function destructive(args) {
+  const [command, ...tail] = args;
+  if (helpOnly(tail)) return false;
+  const options = tail.slice(0, tail.indexOf('--') < 0 ? tail.length : tail.indexOf('--'));
+  return (command === 'reset' && options.some(a => a === '--hard' || a.startsWith('--hard='))) ||
+    (command === 'checkout' && tail.includes('--') && tail.indexOf('--') < tail.length - 1) ||
+    command === 'restore' ||
+    (command === 'clean' && !options.some(a => a === '--dry-run' || /^-[^-]*n/.test(a))) ||
+    (command === 'branch' && options.some(a => a === '--delete' && options.includes('--force') || /^-[^-]*D/.test(a))) ||
+    (command === 'stash' && ['drop', 'clear'].includes(tail[0])) ||
+    ['rebase', 'filter-branch'].includes(command) ||
+    (command === 'update-ref' && options.includes('-d'));
+}
+
+const backupPrefix = 'refs/git-plugin/undo/';
+const objectEnv = ctx => ({ ...ctx.env,
+  GIT_AUTHOR_NAME: 'Git undo', GIT_AUTHOR_EMAIL: 'git-undo@example.invalid',
+  GIT_COMMITTER_NAME: 'Git undo', GIT_COMMITTER_EMAIL: 'git-undo@example.invalid' });
+
+/** Use a private index. Do not stage files in the user's index. */
+function untrackedSnapshot(ctx, includeIgnored) {
+  const files = gitText(ctx, ['ls-files', '--others', ...(includeIgnored ? [] : ['--exclude-standard']), '-z']).split('\0').filter(Boolean);
+  if (!files.length) return null;
+  const dir = mkdtempSync(path.join(os.tmpdir(), 'git-undo-index-'));
+  const env = { ...objectEnv(ctx), GIT_INDEX_FILE: path.join(dir, 'index') };
+  try {
+    gitText(ctx, ['read-tree', '--empty'], { env });
+    // Bounded argv also supports names that start with a dash.
+    for (let i = 0; i < files.length; i += 100) gitText(ctx, ['add', '--force', '--', ...files.slice(i, i + 100)], { env });
+    const tree = gitText(ctx, ['write-tree'], { env }).trim();
+    return gitText(ctx, ['commit-tree', tree, '-m', 'Git undo untracked files'], { env }).trim();
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}
+
+/**
+ * Tracked working-tree content as a commit on HEAD, through a private index. `git stash create`
+ * refuses while the index has unmerged paths, which blocked every conflict resolution
+ * (`checkout --theirs -- <file>`) with "Cannot save an undo snapshot". This keeps the content;
+ * an undo restores the files, not the merge state itself.
+ */
+function trackedSnapshot(ctx) {
+  const dir = mkdtempSync(path.join(os.tmpdir(), 'git-undo-tracked-'));
+  const env = { ...objectEnv(ctx), GIT_INDEX_FILE: path.join(dir, 'index') };
+  try {
+    gitText(ctx, ['read-tree', 'HEAD'], { env });
+    gitText(ctx, ['add', '--update', '--', '.'], { env });
+    const tree = gitText(ctx, ['write-tree'], { env }).trim();
+    return gitText(ctx, ['commit-tree', tree, '-p', 'HEAD', '-m', 'Git undo working tree'], { env }).trim();
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}
+
+export async function snapshot(ctx, command, { includeIgnored = false } = {}) {
+  const store = await stateStore(ctx);
+  const repository = repoId(ctx);
+  const worktree = gitText(ctx, ['rev-parse', '--show-toplevel']).trim();
+  const originalCtx = ctx;
+  ctx = { ...ctx, git: (args, options) => originalCtx.git(['-C', worktree, ...args], options) };
+  const id = randomUUID();
+  const refs = gitText(ctx, ['for-each-ref', '--format=%(refname) %(objectname)']).trim().split('\n')
+    .filter(row => row && !row.startsWith(backupPrefix)).map(row => {
+      const [name, oid] = row.split(' '); return { name, oid };
+    });
+  const head = gitText(ctx, ['rev-parse', '--verify', 'HEAD']).trim();
+  const sym = ctx.git(['symbolic-ref', '-q', 'HEAD']);
+  const status = gitText(ctx, ['status', '--porcelain=v1', '-z']);
+  let stash = null, tracked = null;
+  if (status) {
+    const created = ctx.git(['stash', 'create'], { env: objectEnv(ctx) });
+    if (!created.error && created.status === 0) stash = String(created.stdout).trim() || null;
+    // Only a conflicted index makes stash create refuse for a reason a content snapshot answers.
+    else if (gitText(ctx, ['ls-files', '--unmerged']).trim()) tracked = trackedSnapshot(ctx);
+    else throw new Error('git stash create failed');
+  }
+  const untracked = untrackedSnapshot(ctx, includeIgnored);
+  const stashes = gitText(ctx, ['stash', 'list', '--format=%H%x00%gs']).trim().split('\n').filter(Boolean).map(row => {
+    const [oid, message] = row.split('\0'); return { oid, message };
+  });
+  const objects = [...new Set([head, stash, tracked, untracked, ...refs.map(r => r.oid), ...stashes.map(r => r.oid)].filter(Boolean))];
+  // Pin objects before the event is durable. Git GC must not remove a snapshot.
+  for (let i = 0; i < objects.length; i += 1) gitText(ctx, ['update-ref', `${backupPrefix}${id}/${i}`, objects[i]]);
+  const event = { id, type: 'git.snapshot', timestamp: new Date().toISOString(), repository, worktree,
+    command: [command[0]], refs, head, symbolicHead: sym.status === 0 ? sym.stdout.trim() : null,
+    stash, tracked, untracked, stashes, includeIgnored };
+  store.append(event);
+  return event;
+}
+
+async function before(args, ctx) {
+  const call = invocation(args, ctx);
+  if (helpOnly(args)) return;
+  if (!destructive([call.command, ...call.args])) return;
+  try {
+    await snapshot(call.ctx, [call.command, ...call.args], {
+      includeIgnored: call.command === 'clean' && call.args.some(a => a === '-X' || a === '-x' || /^-[^-]*[xX]/.test(a)),
+    });
+  } catch { return { refuse: 'Cannot save an undo snapshot. No destructive command was run.' }; }
+}
+
+async function restore(ctx, event) {
+  // Keep the current state recoverable if restoration fails or the user changes their mind.
+  await snapshot(ctx, ['undo', event.id], { includeIgnored: event.includeIgnored });
+  const current = gitText(ctx, ['for-each-ref', '--format=%(refname) %(objectname)']).trim().split('\n').filter(Boolean);
+  const desired = new Map(event.refs.map(row => [row.name, row.oid]));
+  for (const row of current) {
+    const [name, oid] = row.split(' ');
+    if (!name.startsWith(backupPrefix) && !desired.has(name)) gitText(ctx, ['update-ref', '-d', name, oid]);
+  }
+  for (const [name, oid] of desired) gitText(ctx, ['update-ref', name, oid]);
+  if (event.symbolicHead) gitText(ctx, ['symbolic-ref', 'HEAD', event.symbolicHead]);
+  else gitText(ctx, ['update-ref', '--no-deref', 'HEAD', event.head]);
+  gitText(ctx, ['reset', '--hard', event.head]);
+  if (event.stash) gitText(ctx, ['stash', 'apply', '--index', event.stash]);
+  for (const commit of [event.tracked, event.untracked].filter(Boolean)) {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'git-undo-restore-'));
+    const env = { ...ctx.env, GIT_INDEX_FILE: path.join(dir, 'index') };
+    try {
+      gitText(ctx, ['read-tree', commit], { env });
+      gitText(ctx, ['checkout-index', '--all', '--force'], { env });
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  }
+  // A ref alone cannot recover entries removed with stash clear.
+  gitText(ctx, ['update-ref', '-d', 'refs/stash']);
+  for (const row of [...event.stashes].reverse()) gitText(ctx, ['stash', 'store', '-m', row.message || 'Recovered stash', row.oid]);
+  const store = await stateStore(ctx);
+  store.append({ id: randomUUID(), type: 'git.undo', event: event.id, repository: event.repository, timestamp: new Date().toISOString() });
+}
+
+async function run(args, ctx) {
+  try {
+    if (args.length > 1 || args.some(a => a.startsWith('-') && a !== '--list')) throw new Error('Use undo [<event>] or undo --list');
+    const store = await stateStore(ctx);
+    const repository = repoId(ctx);
+    const worktree = gitText(ctx, ['rev-parse', '--show-toplevel']).trim();
+    const history = store.read([]);
+    const events = history.filter(e => e.type === 'git.snapshot' && e.repository === repository && e.worktree === worktree);
+    if (args[0] === '--list') {
+      output(ctx, { ok: true, events }, events.map(e => `${e.id} ${e.timestamp} ${e.command[0]}`).join('\n') || 'No undo snapshots.');
+      return 0;
+    }
+    const used = new Set(history.filter(e => e.type === 'git.undo').map(e => e.event));
+    const event = args[0] ? events.find(e => e.id === args[0]) : events.findLast(e => !used.has(e.id) && e.command[0] !== 'undo');
+    if (!event) throw new Error('No matching undo snapshot for this worktree');
+    await restore(ctx, event);
+    output(ctx, { ok: true, restored: event.id }, `Restored snapshot ${event.id}.`);
+    return 0;
+  } catch (error) { return failure(ctx, error); }
+}
+
+export const guards = [{ name: 'undo', before }];
+export const operations = { undo: { summary: 'Restore refs, the index and files from an undo snapshot', usage: 'undo [<event>] [--list] [--json]', run } };

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

@@ -0,0 +1,182 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { failure, gitText, output } from './_support.mjs';
+import { registeredPathState, registeredRepositories } from './fleet.mjs';
+
+/**
+ * Work that never reached the default branch: local branches with commits the
+ * default branch does not contain, linked worktrees with uncommitted changes,
+ * and detached worktrees holding commits no branch contains (removing such a
+ * worktree loses them).
+ *
+ * Nothing reported this before. A week of drawer UI work sat on an unpushed
+ * branch with 256 uncommitted files in a worktree, and about 35 plugin
+ * worktrees sat beside it, while every status said the repositories were fine.
+ *
+ * A commit counts as landed when the default branch (local or origin) reaches
+ * it, or holds an equivalent patch (`git cherry`), so rebased and
+ * cherry-picked work is not reported. A squash merge is a different patch and
+ * still shows; delete the branch once it has landed. A branch the operator
+ * keeps on purpose (`git config --add totalrecall.keepBranch <name>`) is
+ * listed as kept and not counted.
+ */
+
+const SUMMARY_LIMIT = 480;
+
+function localCtx(ctx, directory) {
+  return { ...ctx, git: (args, options) => ctx.git(['-C', directory, ...args], options) };
+}
+
+const refExists = (local, ref) => local.git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]).status === 0;
+
+/** The default branch: origin's HEAD, else local main or master, else init.defaultBranch. */
+export function defaultBranch(local) {
+  const originHead = local.git(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']);
+  const fromOrigin = originHead.status === 0 ? originHead.stdout.trim().replace(/^refs\/remotes\/origin\//, '') : null;
+  const configured = local.git(['config', '--get', 'init.defaultBranch']);
+  const candidates = [fromOrigin, 'main', 'master', configured.status === 0 ? configured.stdout.trim() : null].filter(Boolean);
+  for (const name of candidates) {
+    const localRef = `refs/heads/${name}`, remoteRef = `refs/remotes/origin/${name}`;
+    const refs = [localRef, remoteRef].filter(ref => refExists(local, ref));
+    if (refs.length) return { name, refs };
+  }
+  return null;
+}
+
+/** Non-merge commits on `tip` that no default ref reaches and whose patch the default branch lacks. */
+function uniqueCommits(local, tip, base) {
+  const unreached = gitText(local, ['rev-list', '--no-merges', tip, '--not', ...base.refs, '--']).split('\n').filter(Boolean);
+  if (!unreached.length) return [];
+  const cherry = new Set(gitText(local, ['cherry', base.refs[0], tip]).split('\n')
+    .filter(line => line.startsWith('+ ')).map(line => line.slice(2).trim()));
+  return unreached.filter(commit => cherry.has(commit));
+}
+
+function parseWorktrees(text) {
+  return text.split('\0\0').filter(Boolean).map(record => 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)];
+  })));
+}
+
+/** Inspect one repository. Never fetches: remote refs are as of the last fetch. */
+export function inspectUnmerged(directory, ctx) {
+  const local = localCtx(ctx, directory);
+  const report = { path: directory, defaultBranch: null, outstanding: 0, branches: [], kept: [], worktrees: [], prunable: [] };
+  const state = registeredPathState(directory, ctx);
+  if (state === 'missing') return { ...report, error: 'Registered path does not exist' };
+  if (state === 'not-a-repository') return { ...report, notRepository: true };
+  const root = gitText(local, ['rev-parse', '--path-format=absolute', '--show-toplevel']).trim();
+  report.path = root;
+  const base = defaultBranch(local);
+  if (!base) return { ...report, error: 'No default branch (no origin/HEAD, main, master or init.defaultBranch)' };
+  report.defaultBranch = base.name;
+  const keep = new Set(local.git(['config', '--get-all', 'totalrecall.keepBranch']).stdout?.split('\n').map(s => s.trim()).filter(Boolean) || []);
+
+  const trees = parseWorktrees(gitText(local, ['worktree', 'list', '--porcelain', '-z']));
+  const checkedOut = new Map(trees.filter(t => typeof t.branch === 'string').map(t => [t.branch.replace(/^refs\/heads\//, ''), t.worktree]));
+
+  const rows = gitText(local, ['for-each-ref', '--format=%(refname:short)%00%(objectname)%00%(committerdate:iso-strict)%00%(upstream:short)%00%(subject)', 'refs/heads']).split('\n').filter(Boolean);
+  for (const row of rows) {
+    const [branch, tip, lastCommitAt, upstream, subject] = row.split('\0');
+    if (branch === base.name) continue;
+    const unique = uniqueCommits(local, tip, base);
+    if (!unique.length) continue;
+    const onRemote = Number(gitText(local, ['rev-list', '--count', tip, '--not', '--remotes', '--']).trim()) === 0;
+    const entry = { branch, commits: unique.length, lastCommitAt, subject, upstream: upstream || null, pushed: onRemote, worktree: checkedOut.get(branch) || null };
+    if (keep.has(branch)) report.kept.push(entry); else report.branches.push(entry);
+  }
+
+  trees.forEach((tree, index) => {
+    const primary = index === 0;
+    const branch = typeof tree.branch === 'string' ? tree.branch.replace(/^refs\/heads\//, '') : null;
+    if (tree.prunable || !existsSync(tree.worktree)) {
+      if (!primary) report.prunable.push({ path: tree.worktree, branch, reason: 'directory is gone; git worktree prune removes the record' });
+      return;
+    }
+    // The primary checkout on the default branch is ongoing work on that branch, which audit and fleet report.
+    if (primary && branch === base.name) return;
+    const tctx = localCtx(ctx, tree.worktree);
+    const status = gitText(tctx, ['status', '--porcelain=v1', '-z']);
+    const uncommitted = status.split('\0').filter(entry => /^[ MADRCU?!]{2} /.test(entry)).length;
+    const orphanCommits = branch ? 0 : Number(gitText(tctx, ['rev-list', '--count', 'HEAD', '--not', '--branches', '--tags', '--remotes', '--']).trim());
+    if (!uncommitted && !orphanCommits) return;
+    report.worktrees.push({ path: tree.worktree, branch, detached: !branch, uncommitted, orphanCommits, locked: Boolean(tree.locked), primary });
+  });
+  report.outstanding = report.branches.length + report.worktrees.length;
+  return report;
+}
+
+function describeRepo(repo, home) {
+  const rel = p => (home && p.startsWith(`${home}${path.sep}`) ? `~${p.slice(home.length)}` : p);
+  const parts = [
+    ...repo.branches.map(b => `branch ${b.branch} (+${b.commits}${b.pushed ? '' : ', not pushed'})`),
+    ...repo.worktrees.map(w => `worktree ${rel(w.path)} (${[w.uncommitted ? `${w.uncommitted} uncommitted` : '', w.orphanCommits ? `${w.orphanCommits} commits on no branch` : ''].filter(Boolean).join(', ')})`),
+  ];
+  return `${rel(repo.path)}: ${parts.join('; ')}`;
+}
+
+export function summarize(repositories, home = process.env.HOME) {
+  const outstanding = repositories.reduce((n, repo) => n + repo.outstanding, 0);
+  const failed = repositories.filter(repo => repo.error);
+  if (!outstanding) {
+    const count = repositories.filter(repo => !repo.notRepository).length;
+    const scope = repositories.length === 1 ? 'in this repository' : `in ${count} repositories`;
+    return `No branch or worktree holds work outside the default branch ${scope}${failed.length ? `; ${failed.length} could not be read` : ''}.`;
+  }
+  const head = `${outstanding} branch${outstanding === 1 ? '' : 'es'} or worktree${outstanding === 1 ? '' : 's'} hold work not in the default branch: `;
+  let text = head;
+  const withWork = repositories.filter(repo => repo.outstanding);
+  for (let i = 0; i < withWork.length; i++) {
+    const next = `${i ? ' | ' : ''}${describeRepo(withWork[i], home)}`;
+    if (text.length + next.length > SUMMARY_LIMIT) { text += ` | and ${withWork.length - i} more repositor${withWork.length - i === 1 ? 'y' : 'ies'}`; break; }
+    text += next;
+  }
+  return `${text}${failed.length ? `. ${failed.length} repositor${failed.length === 1 ? 'y' : 'ies'} could not be read` : ''}. Details: total-recall git unmerged${repositories.length > 1 ? ' --registered' : ''}.`;
+}
+
+function textReport(repositories, summary) {
+  const lines = [];
+  for (const repo of repositories) {
+    if (repo.error) { lines.push(`${repo.path}: ${repo.error}`); continue; }
+    if (repo.notRepository) continue;
+    if (!repo.outstanding && !repo.kept.length && !repo.prunable.length) continue;
+    lines.push(`${repo.path} (default ${repo.defaultBranch})`);
+    for (const b of repo.branches) lines.push(`  branch ${b.branch}: ${b.commits} commit${b.commits === 1 ? '' : 's'} not in ${repo.defaultBranch}${b.pushed ? '' : ', not pushed'}; last ${b.lastCommitAt} "${b.subject}"${b.worktree ? `; checked out at ${b.worktree}` : ''}`);
+    for (const w of repo.worktrees) lines.push(`  worktree ${w.path} (${w.branch || 'detached HEAD'}${w.locked ? ', locked' : ''}): ${w.uncommitted} uncommitted file${w.uncommitted === 1 ? '' : 's'}${w.orphanCommits ? `, ${w.orphanCommits} commit${w.orphanCommits === 1 ? '' : 's'} on no branch` : ''}`);
+    for (const b of repo.kept) lines.push(`  kept ${b.branch}: ${b.commits} commit${b.commits === 1 ? '' : 's'} not in ${repo.defaultBranch} (totalrecall.keepBranch)`);
+    for (const p of repo.prunable) lines.push(`  stale worktree record ${p.path}${p.branch ? ` (${p.branch})` : ''}: ${p.reason}`);
+  }
+  return [...lines, summary].join('\n');
+}
+
+async function run(args, ctx) {
+  try {
+    const unknown = args.filter(a => a !== '--registered');
+    if (unknown.length) throw new Error('Use unmerged [--registered] [--json]');
+    let directories;
+    if (args.includes('--registered')) directories = registeredRepositories(ctx);
+    else {
+      const top = ctx.git(['rev-parse', '--path-format=absolute', '--show-toplevel']);
+      if (top.status !== 0) throw new Error('Not inside a git repository; use --registered for every registered repository');
+      directories = [top.stdout.trim()];
+    }
+    const repositories = directories.map(directory => {
+      try { return inspectUnmerged(directory, ctx); }
+      catch (error) { return { path: directory, error: error.message, outstanding: 0, branches: [], kept: [], worktrees: [], prunable: [] }; }
+    });
+    const ok = repositories.every(repo => !repo.error);
+    const outstanding = repositories.reduce((n, repo) => n + repo.outstanding, 0);
+    const summary = summarize(repositories);
+    output(ctx, { ok, outstanding, summary, repositories }, textReport(repositories, summary));
+    return ok ? 0 : 1;
+  } catch (error) { return failure(ctx, error); }
+}
+
+export const operations = {
+  unmerged: {
+    summary: 'Branches and worktrees whose commits or changes are not in the default branch',
+    usage: 'unmerged [--registered] [--json]   keep a branch on purpose: git config --add totalrecall.keepBranch <name>',
+    run,
+  },
+};

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

@@ -0,0 +1,16 @@
+import { git, commitContext, operation, output } from '../lib/context.mjs';
+
+export const operations = {
+  why: operation('Show the recorded intent for one line', 'why <file>:<line> [--json]', async (args, ctx) => {
+    const match = args.length === 1 && /^(.*):([1-9]\d*)$/.exec(args[0]);
+    if (!match || !match[1]) throw new Error('Supply one file:line');
+    const [, file, line] = match;
+    const blame = git(ctx, ['blame', '--line-porcelain', '-L', `${line},${line}`, 'HEAD', '--', file]);
+    const sha = blame.match(/^([a-f0-9]{40,64})\s/m)?.[1];
+    if (!sha) throw new Error('Blame did not return a commit');
+    const context = await commitContext(ctx, sha);
+    const result = { ok: true, file, line: Number(line), blame, ...context, reason: context.recorded ? null : 'No commit record. Only commit trailers are available.' };
+    output(ctx, result, `${file}:${line} — ${sha}\n${context.message}\nSession: ${context.session || 'unknown'}\nTracker: ${context.trackerItems.join(', ') || 'unknown'}\nDecision: ${context.decisions.join('; ') || 'unknown'}\nRules: ${context.rules.join('; ') || 'unknown'}${result.reason ? `\n${result.reason}` : ''}`);
+    return 0;
+  }),
+};

package/scaffold/.agent/skills/total-recall/plugins/git/ui/chunks/change-comparison.md

@@ -0,0 +1,27 @@
+---
+type: ui-chunk:chunk
+title: Git change comparison
+description: Compare unstaged, staged, or base-relative changes using the owner diff operation.
+timestamp: "2026-11-08T09:20:00Z"
+plugin: git
+id: change-comparison
+intents: [review git diff, check staged files, compare branch to base, read diff stats, show a patch]
+surfaces: [page, right]
+operations: [diff]
+data: ["diff:/ok", "diff:/cached", "diff:/diffStat", "diff:/timestamp"]
+---
+
+<style>
+  .sentinel-diff { padding:var(--spacing-md); border-block:1px solid var(--color-border); background:var(--color-surface); }
+  .sentinel-diff h2 { margin-top:0; }
+  .sentinel-diff dt { color:var(--color-accent); }
+  .sentinel-diff dd { margin:0 0 .45em; }
+</style>
+<section class="sentinel-diff">
+  <h2>Choose a comparison</h2>
+  <dl>
+    <dt>Working tree</dt><dd>Read the current changes against the index.</dd>
+    <dt>Staged</dt><dd>Review the index against the selected base.</dd>
+    <dt>Patch</dt><dd>Use <code>--patch</code> for line changes. The Home displays file statistics.</dd>
+  </dl>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/git/ui/chunks/commit-identity.md

@@ -0,0 +1,22 @@
+---
+type: ui-chunk:chunk
+title: Commit identity audit
+description: Check whether a commit identity is configured and count machine addresses recorded in local history.
+timestamp: "2026-11-08T09:20:00Z"
+plugin: git
+id: commit-identity
+intents: [check git author identity, verify commit email, audit machine addresses, git author history]
+surfaces: [page]
+operations: [identity]
+data: ["identity:/ok", "identity:/machineCommits"]
+---
+
+<style>
+  .sentinel-identity { padding:var(--spacing-md); border-inline-start:3px solid var(--color-accent); background:var(--color-surface); }
+  .sentinel-identity h2 { margin-top:0; }
+  .sentinel-identity p { color:var(--color-muted); }
+</style>
+<section class="sentinel-identity">
+  <h2>Check the configured author</h2>
+  <p>The identity audit checks Git’s current author configuration and counts commits with a machine-derived address. Review the count separately from the current configuration.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/git/ui/chunks/create-worktree.md

@@ -0,0 +1,25 @@
+---
+type: ui-chunk:chunk
+title: Create a detached worktree
+description: Create a linked Git worktree from an explicit base ref and verify its resulting revision.
+timestamp: "2026-11-08T09:20:00Z"
+plugin: git
+id: create-worktree
+intents: [create git worktree, isolate git checkout, add detached worktree, choose worktree base]
+surfaces: [page]
+operations: [worktree-create]
+data: ["worktree-create:/ok", "worktree-create:/head", "worktree-create:/detached"]
+---
+
+<style>
+  .sentinel-create { padding:var(--spacing-md); background:var(--color-surface); border-radius:var(--radius-md); }
+  .sentinel-create h2 { margin-top:0; }
+  .sentinel-create li::marker { color:var(--color-accent); }
+</style>
+<section class="sentinel-create">
+  <h2>Prepare an isolated checkout</h2>
+  <ol>
+    <li>Choose a destination and a base ref.</li>
+    <li>Confirm the destination before creation, then verify the detached revision.</li>
+  </ol>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/git/ui/chunks/registered-worktrees.md

@@ -0,0 +1,22 @@
+---
+type: ui-chunk:chunk
+title: Registered Git worktrees
+description: List the repository's main and linked worktrees and inspect their checked-out revisions.
+timestamp: "2026-11-08T09:20:00Z"
+plugin: git
+id: registered-worktrees
+intents: [list git worktrees, inspect linked worktrees, find detached worktree, show active checkouts]
+surfaces: [page, right]
+operations: [worktree-list]
+data: ["worktree-list:/ok", "worktree-list:/worktrees/0/head"]
+---
+
+<style>
+  .sentinel-index { padding:var(--spacing-md); border:1px solid var(--color-border); background:var(--color-surface); }
+  .sentinel-index h2 { margin-top:0; }
+  .sentinel-index b { color:var(--color-accent); }
+</style>
+<section class="sentinel-index">
+  <h2>Read the worktree register</h2>
+  <p>Compare the revision and branch of each registered checkout. The Home labels <b>Main</b> and <b>Current</b> separately.</p>
+</section>