total-recall-brain 3.43.3 → 3.45.0

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

@@ -294,6 +294,8 @@ function printHelp() {
     carriers              Find shell profiles and /etc files that export the master
                            password to every process; --remove-ambient deletes them
                            once an owner-only carrier holds the same password.
+    scan --stdin          Name the keys whose stored values occur in the text on stdin
+                           (values are never printed; exit 1 when one occurs)
     fingerprint           Identify a credential without printing it: length, type
                            prefix, fingerprint and the store keys holding the same
                            value. --from-clipboard | --stdin; --expect-prefix <p>
@@ -311,6 +313,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 +438,7 @@ function parseArgs(args) {
       'rotate-auto',
       'provider-keys',
       'revoke',
+      'gh-login',
       'rm',
       'generate',
       'account-sync',
@@ -629,6 +639,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 +720,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++;
   }
@@ -762,7 +775,7 @@ export default async function secretCli(argv) {
   }
   const brainDir = secretsStoreDir();
 
-  if (opts.stdin && opts.command !== 'fingerprint') {
+  if (opts.stdin && opts.command !== 'fingerprint' && opts.command !== 'scan') {
     if (!['set', 'rotate', 'rekey'].includes(opts.command)) {
       console.error('❌ --stdin is only valid with `set`, `rotate`, `rekey`, or `fingerprint`');
       await exitAfterFlush(1);
@@ -1281,6 +1294,23 @@ export default async function secretCli(argv) {
       return;
     }
 
+    if (opts.command === 'scan') {
+      // Name every store key whose value occurs in the text on stdin. Values never leave this
+      // process: callers (the git plugin's secret firewall) get key names only. One call per scan.
+      if (!opts.stdin) {
+        console.error('Usage: total-recall auth secret scan --stdin [--json]   (exit 1 when a stored value occurs)');
+        await exitAfterFlush(2);
+      }
+      // Diffs and staged files are large; one value check is not, so scan alone gets 64 MB.
+      const text = readAllStdinSync({ maxBytes: 64 * 1024 * 1024 }).toString();
+      const { textContainsSecrets } = await import('./secrets-store.mjs');
+      const result = await textContainsSecrets(brainDir, text);
+      if (opts.json) console.log(JSON.stringify({ ok: !result.leak, leak: result.leak, keys: result.keys, scanned_bytes: Buffer.byteLength(text) }));
+      else console.log(result.leak ? `  ❌ stored values found for: ${result.keys.join(', ')}` : '  ✅ no stored value found');
+      if (result.leak) process.exitCode = 1;
+      return;
+    }
+
     if (opts.command === 'fingerprint') {
       // Identify a credential without seeing it: which store keys hold the same
       // value, its length and its non-secret type prefix. Lets an operator check
@@ -1637,6 +1667,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-store.mjs

@@ -771,13 +771,24 @@ export function listUsageEvents(brainDir, { limit = 100, key_ref = null, days =
 /**
  * True if any secret value appears in text (for surface/openwiki conformance).
  */
+export function isSettingValue(val) {
+  if (/^[a-z]+$/.test(val)) return true;
+  if (/^(?=.{4,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i.test(val)) return true;
+  if (/^[^\s@:/]+@([a-z0-9-]+\.)+[a-z]{2,63}$/i.test(val)) return true;
+  if (/^https?:\/\/[^\s@/]+(\/[^\s@]*)?$/i.test(val)) return true;
+  return false;
+}
+
 export async function textContainsSecrets(brainDir, text) {
   if (!text) return { leak: false, keys: [] };
   const secrets = await loadSecrets(brainDir);
   const leaked = [];
   for (const [key, val] of Object.entries(secrets)) {
     if (key === META_KEY) continue;
-    if (typeof val === 'string' && val.length >= 8 && text.includes(val)) {
+    // Settings, not credentials: a single lowercase word (DEPLOY_ENV=production), a hostname
+    // (MAILCOW_HOST), an email address, or a URL without user info. Matching them would refuse
+    // ordinary text. A URL that carries user:password@ is still checked, as is every other value.
+    if (typeof val === 'string' && val.length >= 8 && !isSettingValue(val) && text.includes(val)) {
       leaked.push(key);
     }
   }

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/automations/BRICK.md

@@ -0,0 +1,7 @@
+# Automation source collection
+
+Copy `capability/` into your application. Import `collectSources` from `./capability/index.mjs` and supply unique source IDs, an adapter map, an ISO check timestamp and an optional positive record limit.
+
+Each adapter returns records or `{records,status,error?}`. Status is `ok`, `partial`, `unsupported`, `disabled`, `error` or `unauthorized`. The collector returns `automations`, independent source `coverage`, and `checked_at`; one failed source does not erase successful evidence. Missing adapters stay unsupported and oversized inventories become partial.
+
+Your application owns authorization, data shape, adapter timeouts, execution and persistence. Supply transports and credentials directly to your own adapters. This capability performs no filesystem, network, process or environment access and prints nothing.

package/scaffold/.agent/skills/total-recall/plugins/automations/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Greg Iteen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,66 @@
+# Automations
+
+Inspect automation sources, triggers, observed outcomes and source coverage across the Total Recall mesh. Composable CLI remains the owner of reusable commands; a command definition is labelled as a manual definition until an explicit automation binding exists.
+
+```
+total-recall automations --help
+total-recall automations list --json
+total-recall automations list --local --source task-queue
+total-recall automations status --node <node>
+total-recall automations show <automation-id>
+total-recall automations cancel <local-task-id>
+total-recall automations dream --all-brains --json
+```
+
+Inventory includes plugin schedules, durable tasks, research queue work, daemon maintenance/watchers, SSSS workflow/trigger declarations, reusable composed commands, and operating-system automation declarations. macOS reads user/system launchd definitions and the current user’s crontab. Linux reads installed and loaded system/user timer units and the current user’s crontab. Commands, environment variables, queued payloads and secret values are excluded from OS summaries.
+
+Each source reports its own coverage. A missing integration, unreadable definition, denied peer, offline node or old collector remains explicit. External agent-platform automation providers have no authenticated inventory contract in this runtime and report unsupported; the plugin does not invent their state. Inventory can therefore be partial even when visible automation records are valid.
+
+A declared schedule does not prove a running scheduler. Last handled slot is not a successful run. Observed execution outcomes come from source-owned records/events; unavailable telemetry stays unknown. Individual daemon watcher registration is not reported by the current owner, so those records remain unknown even when the daemon itself is running.
+
+Selected-node tasks report `selected_node` and `placement_state`. A task without a canonical selection is `unplaced`. Peer metadata without selection evidence stays `unknown`. `last_run` includes the observed slot. `last_handled_outcome` reports the event for the exact stored handled slot. It stays unknown when no matching event exists.
+
+Full peer reads use mesh's authenticated command transport with a fixed local inventory command. If that read is unavailable, the plugin requests mesh-authenticated plugin metadata and marks coverage partial. It never sends a mesh-sync token to the PAT-protected plugin-run route.
+
+The card and panel use the same CLI contracts. Cancellation requires a pending local durable task and an owner that supports a conditional pending-to-cancelled transition. The plugin checks the saved owner state before reporting success. Older hosts can still inventory automations. Mesh peers use the plugin's local inventory operation and can report incomplete coverage. [Owner acceptance tracker](docs/projects/in-progress/ALL_AUTOMATIONS/ALL_AUTOMATIONS_PROJECT_TRACKER.md)
+
+## Scheduled plugin tasks
+
+This plugin runs the `tasks` every plugin declares in its manifest. Total Recall core has no scheduler of its own: the daemon starts this plugin's `scheduler` module through `runtime.daemon`, and it ships bundled with Total Recall.
+
+- `command` is a subcommand followed by its arguments, so `cleanup --auto --json` runs `cleanup` with `--auto --json`.
+- The timeout is the task's `timeout_ms`, else the subcommand's declared `timeout_ms`, else 60 seconds.
+- Scheduling runs against the global brain in the home folder, so run records and `plugin.task_run` events are where `list` reads them.
+- A failed run logs its reason and the end of its output, and alerts the operator through operator-alerts once per task per day.
+- A plugin switched off runs no tasks; a missed slot within the last day runs once; the first run is the first matching slot after the task is first seen.
+
+## Installation and ownership
+
+Use `total-recall plugin install <path-to-this-checkout>` for your own Total Recall workflow. Credentials belong to shared auth. The plugin id and CLI command are `automations`. The package name is `tr-plugin-automations`. The GitHub repository name and folder name change separately.
+
+For an application you ship, `total-recall plugin vendor <path-to-this-checkout>` selects the declared capability. Its `collectSources` export takes explicit source adapters and configuration. The Total Recall CLI wrapper, scheduler and platform accounts are host dependencies.
+
+## Dream and decay
+
+Automations owns one dream task at `40 3 * * *` in each node's local time. Its placement is `per-node`. Its command is `dream --all-brains`. Decay is a phase of dream. It has no separate schedule.
+
+The plugin calls `total-recall dream --all-brains --json` through `spawnSync` with no shell. It checks core's help for `--all-brains` first. Older core versions can ignore unknown flags. The operation fails before execution if core lacks the flag. It also fails for process errors, signals, invalid output and failed brain results. The JSON response reports `exit_code`, `child_exit_code` and `results`. Core must return a nonempty results array, either directly or in a `results` or `brains` field. The child timeout is 30 minutes. The host timeout is 31 minutes.
+
+`list` shows the dream task on each node. It reads the last real outcome from that node's task events. A handled slot stays separate from a real outcome. The cloud daemon must coordinate tasks across the mesh through Automations. This checkout change adds no new transport or deployment. Fleet execution requires a compatible core and an installed plugin on each node.
+
+## Development
+
+`npm test` runs only owner root/UI specs through `vitest.config.mjs`. Injected skill evaluations run independently in their owner and are not Vitest suites. Tests must use isolated/injected state and must not cancel real tasks. Plugin state is derived; persistent source state and controls stay with their owning APIs.
+
+## Using this from an agent
+
+Send questions about what is scheduled here: tasks, triggers and real outcomes across the mesh. A declared schedule does not prove anything ran, so read the outcome. To create a reusable command, use Composable CLI.
+
+```bash
+total-recall automations list --json
+total-recall automations status --node <node>
+total-recall automations show <automation-id>
+total-recall automations cancel <local-task-id>
+```
+
+Raw commands this plugin owns: `crontab -l` and `launchctl list`.