total-recall-brain 3.43.2 → 3.44.0

package/scaffold/.agent/skills/total-recall/plugins/auth/src/cli-secret.mjs

@@ -311,6 +311,13 @@ function printHelp() {
                            the provider rejects the key; a value another key shares is refused.
       --yes               Revoke it
       --json              Machine-readable output
+    gh-login status       Compare this machine's gh login with github_token (no values)
+    gh-login adopt        Save gh's token as github_token for every machine that holds a grant.
+                           Shows the scope change unless --yes is given.
+      --yes               Do it
+      --revoke-old        Also end the previous token at GitHub, once the new one is in place
+    gh-login use-store    Give up this machine's own gh login and sign in from github_token.
+                           Shows the plan unless --yes is given.
     rotation-status       Rotation coverage for every key in the vault
       --json              Machine-readable output
     browser-logout        Delete TR's persistent browser profile (all sessions)
@@ -429,6 +436,7 @@ function parseArgs(args) {
       'rotate-auto',
       'provider-keys',
       'revoke',
+      'gh-login',
       'rm',
       'generate',
       'account-sync',
@@ -629,6 +637,9 @@ function parseArgs(args) {
       case '--revoke':
         out.revokeHash = args[++i];
         break;
+      case '--revoke-old':
+        out.revokeOld = true;
+        break;
       case '--yes':
         out.yes = true;
         break;
@@ -707,7 +718,7 @@ function parseArgs(args) {
           out.keys.push(a);
         } else if (!a.startsWith('--') && !out.key) out.key = a;
         else if (!a.startsWith('--') && !out.value) out.value = a;
-        else if (a.startsWith('--') && out.command === 'revoke') out.unknownOption = a;
+        else if (a.startsWith('--') && ['revoke', 'gh-login'].includes(out.command)) out.unknownOption = a;
     }
     i++;
   }
@@ -1637,6 +1648,12 @@ export default async function secretCli(argv) {
       return;
     }
 
+    if (opts.command === 'gh-login') {
+      const { runGhLogin } = await import('./cli-gh-login.mjs');
+      if ((await runGhLogin(brainDir, opts)) !== 0) await exitAfterFlush(1);
+      return;
+    }
+
     if (opts.command === 'delete' || opts.command === 'rm') {
       if (!opts.key) {
         console.error('Usage: total-recall auth secret delete <key>');

package/scaffold/.agent/skills/total-recall/plugins/auth/src/login-projections.mjs

@@ -4,16 +4,32 @@
  * A secret that reaches a node (see secrets-sync.mjs) is only useful to people and
  * agents there once the tool that uses it is signed in. This signs `gh` in from
  * `github_token`, and wires git to it, so a token rotated once lands on every machine
- * without anyone logging in by hand. Nothing here prints or logs the token.
+ * without anyone logging in by hand.
+ *
+ * A login changed on the machine itself (`gh auth refresh -s workflow`) belongs to the operator,
+ * and comparing values cannot tell that from a rotation. So each node keeps the pair of tokens it
+ * last looked at, as fingerprints. Store token moved: rotation, sign in. `gh` token moved: someone
+ * else wrote it, so check both with GitHub first, and overwrite only when nothing would be lost.
+ *
+ * Nothing here prints or logs a token.
  */
 import { execFile } from 'node:child_process';
+import crypto from 'node:crypto';
 
 const TIMEOUT_MS = 20_000;
+const HOST = 'github.com';
+const REVOKE_URL = 'https://api.github.com/credentials/revoke';
+const NO_LOGIN = /no oauth token/i;
 
 /** Run a command, optionally feeding stdin; never rejects. */
-export function defaultRun(cmd, args, input) {
+export function defaultRun(cmd, args, input, env = {}) {
   return new Promise((resolve) => {
-    const child = execFile(cmd, args, { timeout: TIMEOUT_MS, env: { ...process.env, GH_PROMPT_DISABLED: '1', GH_NO_UPDATE_NOTIFIER: '1' } }, (error, stdout, stderr) => {
+    const childEnv = { ...process.env, GH_PROMPT_DISABLED: '1', GH_NO_UPDATE_NOTIFIER: '1' };
+    // Either of these outranks gh's stored login, so a daemon that inherited one would
+    // report it as the login and could not sign in at all.
+    delete childEnv.GH_TOKEN;
+    delete childEnv.GITHUB_TOKEN;
+    const child = execFile(cmd, args, { timeout: TIMEOUT_MS, env: { ...childEnv, ...env } }, (error, stdout, stderr) => {
       resolve({ ok: !error, code: error?.code ?? 0, stdout: String(stdout || ''), stderr: String(stderr || '') });
     });
     child.stdin?.end(input === undefined ? undefined : String(input));
@@ -22,21 +38,149 @@ export function defaultRun(cmd, args, input) {
 
 const firstLine = (text) => String(text || '').split('\n').map((l) => l.trim()).find(Boolean) || 'unknown error';
 
+/** The same value `auth secret list` shortens to its fingerprint. */
+export const tokenFingerprint = (value) => crypto.createHash('sha256').update(String(value)).digest('hex');
+
+/** What `gh` holds on this machine. The token stays in memory, for the caller to compare. */
+export async function readGhToken(run = defaultRun) {
+  const res = await run('gh', ['auth', 'token', '--hostname', HOST]);
+  if (res.code === 'ENOENT') return { state: 'gh-missing' };
+  if (res.ok && res.stdout.trim()) return { state: 'token', token: res.stdout.trim() };
+  if (res.ok || NO_LOGIN.test(res.stderr)) return { state: 'none' };
+  // A locked keychain or a timeout is not an empty login: signing in over it could lose one.
+  return { state: 'unreadable', error: firstLine(res.stderr) };
+}
+
 /**
- * Sign `gh` in with `token` when it is not already, then point git at it.
- * @returns {{ status: 'no-token'|'gh-missing'|'current'|'logged-in'|'failed', error?: string }}
+ * Ask GitHub about one token, which travels in this child's environment only.
+ * `gh api --include` prints the status line even for a 401 and nothing at all when offline,
+ * which separates a dead token from a dead network without matching error text.
+ * @returns {Promise<{ state: 'ok'|'rejected'|'unknown', scopes: string[], login?: string }>}
  */
-export async function projectGithubLogin({ token, run = defaultRun } = {}) {
+export async function probeGithubToken(token, run = defaultRun) {
+  const res = await run('gh', ['api', '--hostname', HOST, '--include', 'user'], undefined, { GH_TOKEN: token });
+  const [head] = res.stdout.split(/\r?\n\r?\n/, 1);
+  const status = Number(head.match(/^HTTP\/\S+ (\d{3})/)?.[1]);
+  if (status === 401) return { state: 'rejected', scopes: [] };
+  if (status !== 200) return { state: 'unknown', scopes: [] };
+  let login = null;
+  try { login = JSON.parse(res.stdout.slice(head.length)).login; } catch { /* reported as unknown below */ }
+  if (!login) return { state: 'unknown', scopes: [] };
+  const scopes = (head.match(/^x-oauth-scopes:(.*)$/im)?.[1] || '').split(',').map((s) => s.trim()).filter(Boolean).sort();
+  return { state: 'ok', login, scopes };
+}
+
+/** What a `gh` token can do that the store's cannot, and the reverse. */
+export function compareScopes(gh, store) {
+  return {
+    added: gh.scopes.filter((scope) => !store.scopes.includes(scope)),
+    removed: store.scopes.filter((scope) => !gh.scopes.includes(scope)),
+  };
+}
+
+/** Sign `gh` in with `token` on stdin, then point git at it. */
+export async function signInGh(token, run = defaultRun) {
+  const login = await run('gh', ['auth', 'login', '--hostname', HOST, '--git-protocol', 'https', '--with-token'], token);
+  if (!login.ok) return { status: 'failed', error: firstLine(login.stderr).replaceAll(token, '***') };
+  await run('gh', ['auth', 'setup-git', '--hostname', HOST]);
+  return { status: 'logged-in' };
+}
+
+/**
+ * Bring `gh` in step with the store, unless that would lose something the operator holds.
+ *
+ * @param {{ token?: string, record?: { store: string, gh: string }, run?: Function }} options
+ *   `record` is the pair this node last looked at; pass back the `record` of the result.
+ * @returns {Promise<{
+ *   status: 'no-token'|'gh-missing'|'current'|'logged-in'|'diverged'|'failed',
+ *   reason?: string, first?: boolean, login?: string, store_login?: string|null,
+ *   added?: string[], removed?: string[], replaced?: object, record?: object, error?: string,
+ * }>} `diverged` left `gh` alone; `first` is true only when this is news, and `record` is
+ *   missing or unchanged when GitHub could not be asked.
+ */
+export async function projectGithubLogin({ token, record, run = defaultRun } = {}) {
   const wanted = String(token || '').trim();
   if (!wanted) return { status: 'no-token' };
 
-  const current = await run('gh', ['auth', 'token']);
-  if (current.code === 'ENOENT') return { status: 'gh-missing' };
-  if (current.ok && current.stdout.trim() === wanted) return { status: 'current' };
+  const held = await readGhToken(run);
+  if (held.state === 'gh-missing') return { status: 'gh-missing' };
+  if (held.state === 'unreadable') return { status: 'failed', error: held.error.replaceAll(wanted, '***') };
 
-  const login = await run('gh', ['auth', 'login', '--hostname', 'github.com', '--git-protocol', 'https', '--with-token'], wanted);
-  if (!login.ok) return { status: 'failed', error: firstLine(login.stderr).replaceAll(wanted, '***') };
+  const storeFp = tokenFingerprint(wanted);
+  const inStep = { store: storeFp, gh: storeFp };
+  const signIn = async (reason, extra = {}) => {
+    const result = await signInGh(wanted, run);
+    return result.status === 'logged-in' ? { ...result, reason, ...extra, record: inStep } : result;
+  };
 
-  await run('gh', ['auth', 'setup-git', '--hostname', 'github.com']);
-  return { status: 'logged-in' };
+  if (held.state === 'none') return signIn('no-login');
+  if (held.token === wanted) return { status: 'current', record: inStep };
+
+  const ghFp = tokenFingerprint(held.token);
+  if (record?.gh === ghFp) {
+    // Nothing moved: this difference was already reported, so stay quiet and off the network.
+    if (record.store === storeFp) return { status: 'diverged', first: false, reason: record.reason, login: record.login, store_login: record.store_login, added: record.added, removed: record.removed, record };
+    // Only the store moved. A rotation is deliberate, so it lands, over a local login too.
+    return signIn('rotation', record.gh === record.store ? {} : { replaced: { reason: record.reason, login: record.login, added: record.added, removed: record.removed } });
+  }
+
+  const [gh, store] = await Promise.all([probeGithubToken(held.token, run), probeGithubToken(wanted, run)]);
+  if (gh.state === 'rejected') return signIn('gh-token-rejected');
+  // Offline, or GitHub answered oddly: not knowing is no reason to overwrite. Look again next cycle.
+  if (gh.state !== 'ok' || store.state === 'unknown') return { status: 'diverged', first: false, reason: 'unverified', record };
+
+  const keep = (reason, scopes = { added: [], removed: [] }) => {
+    const next = { store: storeFp, gh: ghFp, reason, login: gh.login, store_login: store.login ?? null, ...scopes };
+    return { status: 'diverged', first: true, reason, login: next.login, store_login: next.store_login, ...scopes, record: next };
+  };
+  if (store.state === 'rejected') return keep('store-token-rejected');
+  if (gh.login !== store.login) return keep('different-account');
+  const scopes = compareScopes(gh, store);
+  const sameScopes = !scopes.added.length && !scopes.removed.length;
+  // A local grant was removed again: same account, same powers, so nothing to lose.
+  if (sameScopes && record && record.gh !== record.store) return signIn('same-scopes');
+  // Otherwise someone asked for this new token on purpose, usually to rotate. Keep it.
+  return keep(sameScopes ? 'new-token' : 'different-scopes', scopes);
+}
+
+/** Read-only comparison for operators. Holds fingerprints only, never a token. */
+export async function inspectGithubLogin({ token, run = defaultRun } = {}) {
+  const wanted = String(token || '').trim();
+  if (!wanted) return { state: 'no-token' };
+  const held = await readGhToken(run);
+  if (held.state === 'gh-missing') return { state: 'gh-missing' };
+  if (held.state === 'unreadable') return { state: 'unreadable', error: held.error.replaceAll(wanted, '***') };
+  const store = { fingerprint: tokenFingerprint(wanted).slice(0, 12), ...(await probeGithubToken(wanted, run)) };
+  if (held.state === 'none') return { state: 'no-login', store };
+  if (held.token === wanted) return { state: 'same', store };
+  const gh = { fingerprint: tokenFingerprint(held.token).slice(0, 12), ...(await probeGithubToken(held.token, run)) };
+  // A rejected or unreachable token reports no scopes, which is not the same as holding none.
+  return { state: 'diverged', gh, store, ...(gh.state === 'ok' && store.state === 'ok' ? compareScopes(gh, store) : { added: [], removed: [] }) };
+}
+
+/**
+ * End a token at GitHub. This endpoint refuses authenticated requests, so it goes out without `gh`,
+ * and it answers 202 before anything happens: only GitHub rejecting the token afterwards is proof.
+ */
+export async function revokeGithubToken(token, {
+  run = defaultRun,
+  fetchImpl = fetch,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  attempts = 5,
+  waitMs = 2000,
+} = {}) {
+  let requestStatus = null;
+  try {
+    const res = await fetchImpl(REVOKE_URL, {
+      method: 'POST',
+      headers: { accept: 'application/vnd.github+json', 'content-type': 'application/json', 'user-agent': 'total-recall' },
+      body: JSON.stringify({ credentials: [token] }),
+    });
+    requestStatus = res.status;
+  } catch { /* the check below decides */ }
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (attempt) await sleep(waitMs);
+    if ((await probeGithubToken(token, run)).state === 'rejected') return { revoked: true, request_status: requestStatus };
+  }
+  return { revoked: false, request_status: requestStatus };
 }

package/scaffold/.agent/skills/total-recall/plugins/auth/src/secrets-sync.mjs

@@ -3,8 +3,18 @@ import crypto from 'node:crypto';
 import { getLeaderInfo, isLeader } from './leader-election.mjs';
 import { logger } from './logger.mjs';
 import { brainDir } from './config.mjs';
-import { resolveSecretsPath, loadSecrets, saveSecrets, ensureMeta, appendAuditAsync, META_KEY } from './secrets-store.mjs';
-import { projectGithubLogin } from './login-projections.mjs';
+import { resolveSecretsPath, loadSecrets, saveSecrets, ensureMeta, appendAuditAsync, rotateSecret, META_KEY } from './secrets-store.mjs';
+import {
+  compareScopes,
+  defaultRun,
+  inspectGithubLogin,
+  probeGithubToken,
+  projectGithubLogin,
+  readGhToken,
+  revokeGithubToken,
+  signInGh,
+  tokenFingerprint,
+} from './login-projections.mjs';
 
 const REQUEST_TIMEOUT_MS = 10_000;
 const FETCH_CONCURRENCY = 8;
@@ -33,6 +43,21 @@ export function secretsSyncMode(env = process.env) {
   return 'mesh-identity';
 }
 
+/** The keys the leader says this machine may read. */
+async function listGrantedKeys(base, fetchImpl) {
+  let listResponse;
+  try {
+    listResponse = await fetchImpl(base, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+  } catch (err) {
+    // "fetch failed" alone named neither the address nor the reason.
+    throw new Error(`No Total Recall server answered at ${base}: ${err.cause?.code || err.message}`);
+  }
+  if (!listResponse.ok) throw new Error(`Leader returned ${listResponse.status}`);
+  const { keys } = await listResponse.json();
+  if (!Array.isArray(keys)) throw new Error('Invalid grant list');
+  return keys;
+}
+
 /**
  * Grant-based sync: ask the leader which keys this machine may read, fetch
  * only those, and merge them into this node's own encrypted store. Keys that
@@ -45,16 +70,7 @@ export async function syncGrantedSecrets(leaderIp, { dir = brainDir, fetchImpl =
   // The leader's port, never this node's: the droplet serves on 3900 while devices
   // default to 3000, and assuming our own port made every sync fail.
   const base = meshUrl(leaderIp, '/api/secrets/mesh', port || serverPort());
-  let listResponse;
-  try {
-    listResponse = await fetchImpl(base, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
-  } catch (err) {
-    // "fetch failed" alone named neither the address nor the reason.
-    throw new Error(`No Total Recall server answered at ${base}: ${err.cause?.code || err.message}`);
-  }
-  if (!listResponse.ok) throw new Error(`Leader returned ${listResponse.status}`);
-  const { keys } = await listResponse.json();
-  if (!Array.isArray(keys)) throw new Error('Invalid grant list');
+  const keys = await listGrantedKeys(base, fetchImpl);
 
   // Each key costs the leader a store decryption plus a mesh round trip (2-3 s from a laptop),
   // so a few at a time keeps a full sync under a minute instead of several.
@@ -93,15 +109,143 @@ export async function syncGrantedSecrets(leaderIp, { dir = brainDir, fetchImpl =
   return { granted: keys.length, updated, removed: removed.length };
 }
 
-/** Sign in the tools that use synced secrets (today: gh from github_token). */
-export async function projectLogins({ dir = brainDir, run } = {}) {
-  const secrets = await loadSecrets(dir);
-  const github = await projectGithubLogin({ token: secrets.github_token || secrets.GITHUB_TOKEN, run });
-  if (github.status === 'logged-in') await appendAuditAsync(dir, { action: 'login_projection', key: 'github_token -> gh', actor: 'mesh-sync' });
+const githubKeyName = (secrets) => (secrets.GITHUB_TOKEN && !secrets.github_token ? 'GITHUB_TOKEN' : 'github_token');
+
+/** Reloads first: the checks take seconds, and a key saved meanwhile must survive. */
+async function saveGithubRecord(dir, record) {
+  const secrets = ensureMeta(await loadSecrets(dir));
+  secrets[META_KEY].login_projections = { ...secrets[META_KEY].login_projections, gh: { ...record, at: new Date().toISOString() } };
+  await saveSecrets(dir, secrets);
+}
+
+/** One line on what a kept `gh` login holds that the store does not. */
+function describeDifference({ reason, login, store_login: storeLogin, added = [], removed = [] }) {
+  if (reason === 'store-token-rejected') return 'GitHub rejects the stored token';
+  if (reason === 'different-account') return `gh is signed in as ${login}, the stored token belongs to ${storeLogin}`;
+  if (reason === 'new-token') return 'a new token with the same scopes';
+  return [added.length ? `adds ${added.join(', ')}` : '', removed.length ? `drops ${removed.join(', ')}` : ''].filter(Boolean).join('; ');
+}
+
+/** A desktop notice, once per token. Best effort: the audit log is the record. */
+async function alertOperator(run, eventId, title, message) {
+  await run('total-recall', ['alerts', 'send', '--title', title, '--message', message, '--channels', 'os', '--severity', 'info', '--source', 'auth', '--event-id', eventId]);
+}
+
+async function reportGithubLogin(dir, github, run) {
   if (github.status === 'failed') logger.error('secrets-sync', 'gh login from github_token failed', { error: github.error });
+  if (github.status === 'logged-in') {
+    await appendAuditAsync(dir, { action: 'login_projection', key: `github_token -> gh (${github.reason})`, actor: 'mesh-sync' });
+    if (github.replaced) {
+      const message = `A rotated github_token replaced this machine's own gh login (${describeDifference(github.replaced)}).`;
+      logger.warn('secrets-sync', message);
+      await alertOperator(run, `gh-login-replaced-${github.record.store.slice(0, 12)}`, 'gh login replaced by rotation', message);
+    }
+  }
+  if (github.status === 'diverged' && github.first) {
+    const difference = describeDifference(github);
+    await appendAuditAsync(dir, { action: 'login_projection_kept', key: `gh differs from github_token (${difference})`, actor: 'mesh-sync' });
+    const message = `gh on this machine differs from github_token (${difference}), so the sync left it alone. See: total-recall auth secret gh-login status`;
+    logger.warn('secrets-sync', message);
+    await alertOperator(run, `gh-login-kept-${github.record.gh.slice(0, 12)}`, 'gh login kept', message);
+  }
+}
+
+/** Sign in the tools that use synced secrets (today: gh from github_token). */
+export async function projectLogins({ dir = brainDir, run = defaultRun } = {}) {
+  const secrets = ensureMeta(await loadSecrets(dir));
+  const record = secrets[META_KEY].login_projections?.gh;
+  const github = await projectGithubLogin({ token: secrets.github_token || secrets.GITHUB_TOKEN, record, run });
+  if (github.record && (github.record.store !== record?.store || github.record.gh !== record?.gh)) await saveGithubRecord(dir, github.record);
+  await reportGithubLogin(dir, github, run);
   return { github };
 }
 
+/** How `gh` on this machine compares with the store. Changes nothing. */
+export async function githubLoginStatus({ dir = brainDir, run = defaultRun } = {}) {
+  const secrets = await loadSecrets(dir);
+  return inspectGithubLogin({ token: secrets.github_token || secrets.GITHUB_TOKEN, run });
+}
+
+/** Give up this machine's own `gh` login and sign in from the store. Plans unless `yes`. */
+export async function useStoreGithubLogin({ dir = brainDir, yes = false, run = defaultRun } = {}) {
+  const secrets = await loadSecrets(dir);
+  const token = secrets.github_token || secrets.GITHUB_TOKEN;
+  if (!token) throw new Error('The store holds no github_token');
+  const status = await inspectGithubLogin({ token, run });
+  if (status.state === 'same') return { ok: true, changed: false, ...status };
+  if (!yes) return { ok: true, planned: true, ...status };
+  const result = await signInGh(token, run);
+  if (result.status !== 'logged-in') return { ok: false, changed: false, error: result.error };
+  const fingerprint = tokenFingerprint(token);
+  await saveGithubRecord(dir, { store: fingerprint, gh: fingerprint });
+  await appendAuditAsync(dir, { action: 'login_projection', key: 'github_token -> gh (operator)', actor: 'cli' });
+  return { ok: true, changed: true, ...status };
+}
+
+/**
+ * Save this machine's `gh` token as the mesh's `github_token`. This is what widens a credential
+ * across the mesh, so it plans unless `yes`. Only the leader's store reaches other nodes, and the
+ * next sync would overwrite a follower's own copy, so a follower writes to the leader over the mesh.
+ */
+export async function adoptGithubLogin({ dir = brainDir, yes = false, revokeOld = false, run = defaultRun, exec, fetchImpl = fetch, sleep } = {}) {
+  const secrets = await loadSecrets(dir);
+  const key = githubKeyName(secrets);
+  const previous = secrets[key];
+  const held = await readGhToken(run);
+  if (held.state !== 'token') throw new Error(held.error || 'gh holds no token to adopt. Sign in with gh first; nothing changed.');
+  if (!previous) throw new Error(`The store holds no ${key}; nothing changed. Save it with: total-recall auth secret set ${key} --stdin`);
+  const fingerprint = tokenFingerprint(held.token);
+  if (held.token === previous) return { ok: true, adopted: false, state: 'same', key, fingerprint: fingerprint.slice(0, 12) };
+
+  const [gh, store] = await Promise.all([probeGithubToken(held.token, run), probeGithubToken(previous, run)]);
+  if (gh.state === 'rejected') throw new Error("GitHub rejects gh's token; nothing changed. Sign in with gh again first.");
+  if (gh.state !== 'ok' || store.state === 'unknown') throw new Error('Could not check both tokens with GitHub; nothing changed.');
+  if (store.state === 'ok' && store.login !== gh.login) throw new Error(`gh is signed in as ${gh.login}, but ${key} belongs to ${store.login}; nothing changed.`);
+
+  const leader = await isLeader();
+  const leaderInfo = leader ? null : await getLeaderInfo();
+  if (!leader && !leaderInfo?.ip) throw new Error('No leader found to write to; nothing changed.');
+  const plan = {
+    key,
+    login: gh.login,
+    target: leader ? 'this machine' : leaderInfo.ip,
+    gh: { fingerprint: fingerprint.slice(0, 12), scopes: gh.scopes },
+    store: { fingerprint: tokenFingerprint(previous).slice(0, 12), state: store.state, scopes: store.scopes },
+    // A rejected token reports no scopes, which is not the same as holding none.
+    ...(store.state === 'ok' ? compareScopes(gh, store) : { added: [], removed: [] }),
+    revoke_old: revokeOld,
+  };
+  if (!yes) return { ok: true, planned: true, ...plan };
+
+  if (leader) {
+    await rotateSecret(dir, key, held.token, { actor: 'gh-login-adopt' });
+  } else {
+    // Checked first: without a grant the leader would change and this machine would never catch up.
+    const granted = await listGrantedKeys(meshUrl(leaderInfo.ip, '/api/secrets/mesh', leaderInfo.port || serverPort()), fetch);
+    if (!granted.includes(key)) throw new Error(`This machine holds no grant for ${key}, so it would not receive the token back; nothing changed.`);
+    const runOnLeader = exec || (await import('./mesh.mjs')).execMeshCommand;
+    const rotated = await runOnLeader(leaderInfo.ip, `total-recall auth secret rotate ${key} --stdin`, { input: held.token, timeoutMs: 60_000 });
+    if (!rotated.success) throw new Error(`The leader did not take the token, so nothing changed: ${String(rotated.stderr || 'no detail').split('\n')[0].replaceAll(held.token, '***')}`);
+    // Prove it came back through the sync every other node uses.
+    await syncGrantedSecrets(leaderInfo.ip, { dir, port: leaderInfo.port });
+    if ((await loadSecrets(dir))[key] !== held.token) throw new Error(`The leader took the token, but this machine did not get it back. Check that its grant includes ${key}. The old token was left working.`);
+    // The leader runs no sync of its own, so its gh would keep the old token.
+    const leaderLogin = await runOnLeader(leaderInfo.ip, 'gh auth login --hostname github.com --git-protocol https --with-token && gh auth setup-git --hostname github.com', { input: held.token, timeoutMs: 60_000 });
+    plan.leader_gh = leaderLogin.success ? 'signed-in' : 'failed';
+  }
+  await saveGithubRecord(dir, { store: fingerprint, gh: fingerprint });
+  await appendAuditAsync(dir, { action: 'login_adopted', key: `gh -> ${key}${plan.added.length ? ` (adds ${plan.added.join(', ')})` : ''}`, actor: 'cli' });
+
+  if (!revokeOld || store.state !== 'ok') return { ok: plan.leader_gh !== 'failed', adopted: true, ...plan };
+  // Never end the old token while a machine still signs in with it.
+  if (plan.leader_gh === 'failed') return { ok: false, adopted: true, ...plan, revocation: { revoked: false, skipped: "the leader's gh still uses the old token" } };
+  const revocation = await revokeGithubToken(previous, { run, fetchImpl, ...(sleep ? { sleep } : {}) });
+  await appendAuditAsync(dir, { action: revocation.revoked ? 'revoke' : 'revoke_failed', key: `${key} (previous value)`, actor: 'cli' });
+  // GitHub does not say whether this ends only the one token, so check the new one still works.
+  revocation.new_token_works = (await probeGithubToken(held.token, run)).state === 'ok';
+  return { ok: revocation.revoked && revocation.new_token_works, adopted: true, ...plan, revocation };
+}
+
 export async function syncLoop() {
   secretsSyncMode();
   if (!(await isLeader())) {

package/scaffold/.agent/skills/total-recall/plugins/code-quality/README.md

@@ -5,7 +5,7 @@ One-shot, fail-closed code-quality gates for any repository. The plugin ships a
 ## What it does
 
 - Runs each configured gate once, as a background job, and writes `reports/latest.json`. There is no daemon.
-- Gate kinds: a command (typecheck, lint, tests, conformance suites) with an output parser (`tsc`, `eslint-stylish`, `eslint-compact`, `biome`, `flake8`, `mypy`, `black`, `generic`), or `grep-forbid`, which turns a written repository invariant into a failing gate.
+- Gate kinds: a command (typecheck, lint, tests, conformance suites) with an output parser (`tsc`, `eslint-stylish`, `eslint-compact`, `biome`, `flake8`, `mypy`, `black`, `generic`), or `grep-forbid`, which turns a written repository invariant into a failing gate. A `grep-forbid` pattern can read its terms from a file with `patternFile`, for words a published config must not contain.
 - Tiers (`fast`, `full`, `remote`) keep heavy work off small machines. A bounded run lists the gates it skipped.
 - Locking is fail-closed and machine-wide, so only one check runs per host. `--steal-lock` recovers a dead or unverifiable lock and refuses to take one from a verified running check.
 - Reports record coverage, the git head and source freshness. A gate that scans zero files, or a tool that fails without parseable output, is never reported as clean.
@@ -44,7 +44,7 @@ The canonical gate list is a `skill_config` record in the repository's Total Rec
 
 ## Data and network access
 
-The core runs only the commands in the repository's own config, with the repository as working directory. It reads tracked source files for `grep-forbid` gates and writes only `reports/` and lock files. It makes no network requests. Commands you configure may.
+The core runs only the commands in the repository's own config, with the repository as working directory. It reads tracked source files and any `patternFile` for `grep-forbid` gates and writes only `reports/` and lock files. It makes no network requests. Commands you configure may.
 
 ## Development
 

package/scaffold/.agent/skills/total-recall/plugins/code-quality/core/check.mjs

@@ -104,8 +104,11 @@ function loadConfig() {
     if (c.kind === 'grep-forbid') {
       if (!Array.isArray(c.patterns) || c.patterns.length === 0) problems.push(`${where}: grep-forbid needs a non-empty "patterns" array`);
       else c.patterns.forEach((p, j) => {
-        if (!p.pattern) problems.push(`${where}.patterns[${j}]: missing "pattern"`);
-        else if (/^\(\?[a-z]+\)/.test(p.pattern)) {
+        if (!p.pattern === !p.patternFile) problems.push(`${where}.patterns[${j}]: needs exactly one of "pattern" and "patternFile"`);
+        else if (p.patternFile) {
+          try { new RegExp('x', p.flags || ''); }
+          catch (e) { problems.push(`${where}.patterns[${j}]: invalid flags — ${e.message}`); }
+        } else if (/^\(\?[a-z]+\)/.test(p.pattern)) {
           problems.push(`${where}.patterns[${j}]: JS RegExp has no inline (?i) flags — use "flags": "i" instead`);
         } else {
           try { new RegExp(p.pattern, p.flags || ''); }
@@ -503,11 +506,41 @@ function applyFallbackViolationBaseline(check, findings) {
   return retained;
 }
 
+/**
+ * Reads a pattern's terms from a file, for words the config must not contain because the config
+ * is published and the words are private. Each line is a literal term; a # line is a comment.
+ */
+function readPatternFile(file) {
+  let text;
+  try { text = readFileSync(path.resolve(REPO_ROOT, file), 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return { absent: true }; throw error; }
+  const terms = text.split('\n').map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
+  return { terms };
+}
+
 function runGrepForbid(check) {
   let findings = [];
-  const patterns = (check.patterns || []).map((p) => ({
-    re: new RegExp(p.pattern, p.flags || ''), message: p.message, code: p.code || 'FORBIDDEN'
-  }));
+  const notes = [];
+  const patterns = [];
+  for (const p of check.patterns || []) {
+    const rule = { message: p.message, code: p.code || 'FORBIDDEN' };
+    if (!p.patternFile) { patterns.push({ ...rule, re: new RegExp(p.pattern, p.flags || '') }); continue; }
+    const { absent, terms } = readPatternFile(p.patternFile);
+    if (absent) {
+      // A public clone has no private list. Say the rule did not run; never call that a pass.
+      const note = `${check.id}: ${rule.code} did not run, ${p.patternFile} is not present.`;
+      notes.push(note);
+      console.error(`  [code-quality] ${note}`);
+    } else if (!terms.length) {
+      findings.push({
+        file: '.agent/skills/code-quality/config.json', line: 1, col: 1,
+        code: 'CQ-EMPTY-LIST', check: check.id, severity: 'error',
+        message: `grep-forbid check "${check.id}" reads no terms from ${p.patternFile}.`, snippet: p.patternFile
+      });
+    } else {
+      patterns.push({ ...rule, re: new RegExp(terms.map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), p.flags || '') });
+    }
+  }
   const exts = new Set(check.extensions || config.sourceExtensions || ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py']);
   const ignore = (check.ignorePaths || []).map((p) => new RegExp(p));
   // Optional allowlist: when present, ONLY files matching one of these path
@@ -556,7 +589,7 @@ function runGrepForbid(check) {
   return Promise.resolve({
     id: check.id, ok: findings.length === 0, exitCode: findings.length ? 1 : 0,
     timedOut: false, durationMs: 0, findings, scanned,
-    raw: findings.map((f) => `${f.file}:${f.line}: ${f.code} ${f.message}`).join('\n')
+    raw: [...notes, ...findings.map((f) => `${f.file}:${f.line}: ${f.code} ${f.message}`)].join('\n')
   });
 }
 

package/scaffold/.agent/skills/total-recall/plugins/code-quality/core/config.schema.json

@@ -67,9 +67,10 @@
             "items": {
               "type": "object",
               "additionalProperties": false,
-              "required": ["pattern"],
+              "oneOf": [{ "required": ["pattern"] }, { "required": ["patternFile"] }],
               "properties": {
                 "pattern": { "type": "string", "minLength": 1 },
+                "patternFile": { "type": "string", "minLength": 1, "description": "Repo-relative file of literal terms, one a line, for words the published config must not contain. The rule reports that it did not run when the file is absent." },
                 "flags": { "type": "string", "pattern": "^[dgimsuvy]*$" },
                 "code": { "type": "string" },
                 "message": { "type": "string" }

package/scaffold/.agent/skills/total-recall/plugins/code-quality/package-lock.json

@@ -1,18 +1,18 @@
 {
   "name": "tr-plugin-code-quality",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-code-quality",
-      "version": "0.2.4",
+      "version": "0.2.6",
       "license": "MIT",
       "dependencies": {
-        "@gregiteen/ssss-cli": "0.14.4"
+        "@gregiteen/ssss-cli": "0.14.5"
       },
       "devDependencies": {
-        "total-recall-brain": "3.42.1"
+        "total-recall-brain": "3.43.3"
       }
     },
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -715,9 +715,9 @@
       "license": "MIT"
     },
     "node_modules/@gregiteen/ssss-cli": {
-      "version": "0.14.4",
-      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.14.4.tgz",
-      "integrity": "sha512-R6JIgPRvS9xXp0xb6BYO3rauv+72r35GIiDrJcvbjPdTSHFZXr8/jRxFOgoF8yTed/5xyGFF3ey3DI9bOjmHVA==",
+      "version": "0.14.5",
+      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.14.5.tgz",
+      "integrity": "sha512-qVEYOocnwn97uJ0eDzmuwN06CYsYWr2t3+iKylpisBHX4wlLWk7P8EmFFdBlx7NyKVIZDDeYT164Gd7/T8UGgw==",
       "license": "ISC",
       "bin": {
         "ssss": "scripts/ssss.mjs"
@@ -1580,9 +1580,9 @@
     },
     "node_modules/@ssss/cli": {
       "name": "@gregiteen/ssss-cli",
-      "version": "0.14.4",
-      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.14.4.tgz",
-      "integrity": "sha512-R6JIgPRvS9xXp0xb6BYO3rauv+72r35GIiDrJcvbjPdTSHFZXr8/jRxFOgoF8yTed/5xyGFF3ey3DI9bOjmHVA==",
+      "version": "0.14.5",
+      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.14.5.tgz",
+      "integrity": "sha512-qVEYOocnwn97uJ0eDzmuwN06CYsYWr2t3+iKylpisBHX4wlLWk7P8EmFFdBlx7NyKVIZDDeYT164Gd7/T8UGgw==",
       "dev": true,
       "license": "ISC",
       "bin": {
@@ -5543,9 +5543,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.42.1",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.42.1.tgz",
-      "integrity": "sha512-woH7mdkGwPFYlKPZurhE8L3BPe+cSeIruNGaPOjGZJm/O8C92Bbr1gsdOY0tTLg5QHlgPHcXG1GMtsm9lPDz8w==",
+      "version": "3.43.3",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.43.3.tgz",
+      "integrity": "sha512-yjfPN/BQxEEa+iodyFXQov/6fRt1pZg/7RcmgsbpALwBt6Ki3JJjT3tzArBC7NxHQmXgGYyKnCYId6xe/W2rPg==",
       "dev": true,
       "license": "MIT",
       "workspaces": [
@@ -5576,6 +5576,7 @@
         "antigravity": "bin/antigravity.mjs",
         "total-recall": "bin/total-recall.mjs",
         "total-recall-memory": "bin/total-recall-memory.mjs",
+        "total-recall-server-release": "bin/total-recall-server-release.mjs",
         "vibebrain": "bin/total-recall.mjs"
       },
       "optionalDependencies": {