total-recall-brain 3.40.4 → 3.40.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.40.4",
+  "version": "3.40.6",
   "description": "The Vibe Coding Brain & Autonomous Software Factory: memory, rules, secrets, and 33 visual plugins automatically managed across all your devices.",
   "type": "module",
   "bin": {

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

@@ -1,5 +1,7 @@
 # Auth plugin
 
+Noninteractive agents use the existing host password carriers in this order: process environment, macOS Keychain, the private TR environment file, then the private `com.totalrecall.brain` LaunchAgent. The LaunchAgent must be an owned regular file at mode 0600 in an owned directory without group/other write permission. `TR_SECRETS_LAUNCH_AGENT` selects an explicit carrier; `TR_SECRETS_NO_HOST_CARRIER=1` disables it. Auth captures the password internally and never copies it into argv, logs or another machine. Missing carriers and decryption failures remain errors.
+
 Auth owns encrypted provider credentials, dashboard and collaboration passwords, purpose-bound session signing, passkey storage, and scoped API-key lifecycle. Core adapters require its manifest exports and have no credential implementation fallback.
 
 ## Operations

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

@@ -342,6 +342,31 @@ export async function run(argv = []) {
       else throw new Error('Use auth key list|issue <name> --scopes <csv> [--role role] [--expires date]|revoke <id>|usage [id]|roles|role-set <name> --scopes <csv>');
       console.log(JSON.stringify(result)); break;
     }
+    case 'agent': {
+      // Sign in an agent CLI that authenticates on its own terminal. The pty lives in
+      // scripts/agent-login-pty.py because Node has none and this plugin carries no pty library;
+      // this routes the plugin's own surface to it.
+      const { loginAgent, AGENT_LOGIN_PROFILES } = await import('./src/agent-login.mjs');
+      const [action = 'list', name] = rest;
+      const flag = (n) => { const at = rest.indexOf(n); return at < 0 ? undefined : rest[at + 1]; };
+      if (action === 'list') {
+        console.log(JSON.stringify(Object.keys(AGENT_LOGIN_PROFILES).map((id) => ({ id, ...AGENT_LOGIN_PROFILES[id] }))));
+        break;
+      }
+      if (action !== 'login') throw new Error('Use auth agent list | auth agent login <agent> [--code <code>] [--code-file <path>] [--url-file <path>]');
+      const result = await loginAgent({
+        agent: name,
+        code: flag('--code'),
+        codeFile: flag('--code-file'),
+        urlFile: flag('--url-file'),
+        onEvent: (event) => { if (!isJson && event.event === 'url') console.log('\nOpen this URL and approve it:\n' + event.url + '\n'); },
+      });
+      if (isJson) console.log(JSON.stringify(result));
+      else if (result.ok) console.log(result.alreadySignedIn ? `${name} is already signed in.` : `${name} signed in.`);
+      else console.log(`${name} is not signed in. ${result.error || result.reason || ''} ${result.hint || ''}`.trim());
+      if (!result.ok) process.exitCode = 2;
+      break;
+    }
     case 'google':
       await handleGoogle(rest, isJson);
       break;
@@ -370,6 +395,7 @@ export async function run(argv = []) {
       console.log('  key list|issue|revoke|usage|roles|role-set   Scoped tokens and role policies');
       console.log('  secret   Inspect and manage Total Recall secrets store keys');
       console.log('  password set --stdin [--force-reset]   Set encrypted dashboard credential');
+      console.log('  agent list|login <agent>   Sign in an agent CLI that authenticates on its own terminal');
       break;
     default:
       console.error(`Unknown subcommand: ${command}. Run 'total-recall auth --help' for guidance.`);

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

@@ -1,12 +1,12 @@
 {
   "name": "tr-plugin-auth",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-auth",
-      "version": "1.0.4",
+      "version": "1.1.0",
       "license": "MIT",
       "dependencies": {
         "@simplewebauthn/server": "^13.3.2",
@@ -18,7 +18,7 @@
       },
       "devDependencies": {
         "supertest": "^7.2.2",
-        "total-recall-brain": "3.40.3",
+        "total-recall-brain": "3.40.4",
         "vitest": "^5.0.3"
       }
     },
@@ -3669,9 +3669,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.3.tgz",
-      "integrity": "sha512-E5elOF/OvGAvDdXVDUQaV1xa7hWDOVYmK3z8V+zPNYVEtEoGhJplY1Rtqu76oHezwJDQRIhc4+3HhpvjH5fIww==",
+      "version": "3.40.4",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.4.tgz",
+      "integrity": "sha512-/9JfUWyzXcgHu3kV/rqsOvclMY25PpfW4jSrunsCrkt2MPDUDfGD+z22AoA/OG/jSHE4ZvD/A9QV4IYE2+O99w==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/auth/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "main": "cli.mjs",
   "scripts": {
-    "test": "node --test test/auth.test.mjs && vitest run --exclude '**/auth.test.mjs'"
+    "test": "node --test test/*.test.mjs"
   },
   "keywords": [
     "total-recall-plugin",

package/scaffold/.agent/skills/total-recall/plugins/auth/plugin.json

@@ -122,6 +122,11 @@
         "description": "Inspect active session tokens",
         "effect": "read"
       },
+      {
+        "name": "agent",
+        "description": "Sign in an agent CLI that authenticates on its own terminal",
+        "effect": "destructive"
+      },
       {
         "name": "secret",
         "description": "Manage and inspect auth secrets in the Total Recall store",

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

@@ -0,0 +1,127 @@
+/**
+ * Agent CLI sign-in, as an auth-plugin capability.
+ *
+ * Some agent CLIs authenticate on their own terminal — Antigravity (`agy`) prints a Google consent
+ * URL and then blocks reading the authorization code. There was no way to do that through the auth
+ * plugin, so it was being hand-rolled beside it and the code ended up nowhere.
+ *
+ * The pty lives in scripts/agent-login-pty.py, owned by this plugin, because Node has no built-in
+ * pty and this plugin carries no pty library. This module is the plugin-facing surface: it resolves
+ * the agent, runs the helper, relays its events, and reports a result the CLI can act on.
+ *
+ * It never claims success from the transcript alone — the helper re-runs the CLI's own login probe
+ * and reports `ok` only when the session actually exists.
+ */
+
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const HELPER = path.join(HERE, '..', 'scripts', 'agent-login-pty.py');
+
+/** Only the facts that differ between CLIs are declared. */
+export const AGENT_LOGIN_PROFILES = {
+  agy: {
+    binary: 'agy',
+    consentHost: 'accounts.google.com',
+    probeArgs: 'models',
+    signedOutPattern: 'please sign in',
+    signIn: 'Run `agy` with no arguments, open the URL it prints, and approve with the Google account the agent should use.',
+  },
+};
+
+export function agentLoginProfile(agent) {
+  return AGENT_LOGIN_PROFILES[String(agent || '').trim().toLowerCase()];
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.agent
+ * @param {string} [options.code]      authorization code if already in hand
+ * @param {string} [options.codeFile]  path polled for the code (unattended flows)
+ * @param {string} [options.urlFile]   where to write the consent URL
+ * @param {number} [options.timeoutMs]
+ * @param {(event: object) => void} [options.onEvent]
+ */
+export async function loginAgent({ agent, code, codeFile, urlFile, timeoutMs = 900_000, onEvent = () => {} }) {
+  const profile = agentLoginProfile(agent);
+  if (!profile) {
+    return {
+      ok: false,
+      agent,
+      error: `No sign-in flow is defined for '${agent}'. Known agents: ${Object.keys(AGENT_LOGIN_PROFILES).join(', ') || '(none)'}.`,
+    };
+  }
+
+  return new Promise((resolve) => {
+    const args = [
+      HELPER,
+      '--agent', agent,
+      '--binary', profile.binary,
+      '--consent-host', profile.consentHost,
+      '--probe-args', profile.probeArgs,
+      '--signed-out-pattern', profile.signedOutPattern,
+      '--timeout', String(Math.floor(timeoutMs / 1000)),
+    ];
+    if (code) args.push('--code', code);
+    if (codeFile) args.push('--code-file', codeFile);
+    if (urlFile) args.push('--url-file', urlFile);
+
+    const child = spawn('python3', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let buffer = '';
+    let url = '';
+    let sawDone = false;
+    let probe = null;
+    let helperError = '';
+
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk.toString();
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        let event;
+        try {
+          event = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        onEvent(event);
+        if (event.event === 'url') url = event.url || url;
+        if (event.event === 'probe') probe = event.probe || probe;
+        if (event.event === 'already_signed_in') probe = event.probe || probe;
+        if (event.event === 'done') {
+          sawDone = true;
+          resolve({
+            ok: Boolean(event.ok),
+            agent,
+            url,
+            probe,
+            alreadySignedIn: Boolean(probe && probe.signed_in),
+            reason: event.reason,
+            hint: event.ok ? undefined : profile.signIn,
+          });
+        }
+      }
+    });
+
+    child.stderr.on('data', (chunk) => { helperError += chunk.toString(); });
+
+    child.on('error', (error) => {
+      resolve({ ok: false, agent, error: `Could not start the sign-in helper: ${error.message}` });
+    });
+
+    child.on('close', (code_) => {
+      if (sawDone) return;
+      resolve({
+        ok: false,
+        agent,
+        url,
+        probe,
+        error: helperError.trim() || `The sign-in helper exited (${code_}) without reporting a result.`,
+        hint: profile.signIn,
+      });
+    });
+  });
+}

package/scaffold/.agent/skills/total-recall/plugins/auth/src/provider-api-rotation.mjs

@@ -0,0 +1,140 @@
+/**
+ * Provider-API rotation.
+ *
+ * Some providers let an account mint and revoke its own keys over their API, given a credential
+ * with management rights. Until this module existed, no such path existed in the plugin at all:
+ * rotation-capability classified keys as `provider_api` and described them as "fully automatic",
+ * but rotateAuto sent `provider_api` down the browser path with everything else, so a provider
+ * that could rotate itself in one request was instead driven through a console login. A
+ * management key therefore had no consumer anywhere in the code.
+ *
+ * Recipes are data: a provider declares the endpoints and which stored secret holds the
+ * management credential (provider-catalog.mjs `rotation.api`). Nothing here is provider-specific
+ * beyond those declarations, and no secret value is ever logged or returned.
+ */
+
+/**
+ * @typedef {{
+ *   create: { method: string, path: string, body?: (label: string) => object, value_path: string, id_path?: string, revoke_path?: string },
+ *   revoke?: { method: string, path: (id: string, hash: string) => string },
+ *   probe?: string,
+ * }} ProviderApiRecipe
+ */
+
+/** Read a dotted path out of a response body. */
+function pick(obj, dotted) {
+  return String(dotted || '').split('.').reduce((acc, part) => (acc == null ? acc : acc[part]), obj);
+}
+
+/**
+ * Rotate a key by calling the provider's own key-management API.
+ *
+ * Order matters and mirrors the supervised browser flow on purpose: mint the new credential, store
+ * it, and only then revoke the old one. If revoking happened first and storing failed, the account
+ * would be left with a live key nobody holds; this way a failure leaves an extra key rather than
+ * none.
+ *
+ * @param {object} deps
+ * @param {string} deps.brainDir
+ * @param {string} deps.key              stored secret being rotated
+ * @param {string} deps.managementKeyName stored secret holding management rights
+ * @param {ProviderApiRecipe} deps.recipe
+ * @param {string} deps.baseUrl
+ * @param {(brain:string, name:string) => Promise<string|null>} deps.readSecret
+ * @param {(brain:string, key:string, value:string, opts:object) => Promise<object>} deps.storeSecret
+ * @param {(brain:string, name:string) => Promise<object|null>} deps.secretMeta
+ * @param {typeof fetch} [deps.fetchImpl]
+ */
+export async function rotateViaProviderApi({
+  brainDir, key, managementKeyName, recipe, baseUrl,
+  readSecret, storeSecret, secretMeta, recordKeyId, fetchImpl = fetch,
+}) {
+  const management = await readSecret(brainDir, managementKeyName);
+  if (!management) {
+    return {
+      ok: false,
+      error: `No management credential in the store: ${managementKeyName}. `
+        + 'This provider rotates itself over its API, so it needs a key with management rights '
+        + 'stored under that name; without one there is nothing to authenticate the request.',
+      needs: managementKeyName,
+    };
+  }
+
+  const auth = { Authorization: `Bearer ${management}` };
+  const label = `${key.toLowerCase().replace(/[^a-z0-9]+/g, '-')}-${new Date().toISOString().slice(0, 10)}`;
+
+  let created;
+  try {
+    const res = await fetchImpl(`${baseUrl}${recipe.create.path}`, {
+      method: recipe.create.method || 'POST',
+      headers: { ...auth, 'Content-Type': 'application/json' },
+      body: JSON.stringify(recipe.create.body ? recipe.create.body(label) : { name: label }),
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: `Provider refused to mint a key (HTTP ${res.status}). `
+          + 'A credential without management rights gets 401 or 403 here, which is the usual cause.',
+        status: res.status,
+      };
+    }
+    const value = pick(body, recipe.create.value_path);
+    if (!value) return { ok: false, error: `Provider response carried no new key at ${recipe.create.value_path}` };
+    const id = recipe.create.id_path ? pick(body, recipe.create.id_path) : null;
+    created = { value, id, label };
+  } catch (error) {
+    return { ok: false, error: `Could not reach the provider API: ${error.message}` };
+  }
+
+  // Store first, revoke second.
+  let exports;
+  try {
+    const result = await storeSecret(brainDir, key, created.value, { actor: 'provider-api-rotation' });
+    exports = result && result.exports;
+    // Keep the provider's id for the key we just minted, so the next rotation can revoke it.
+    if (created.id && recordKeyId) await recordKeyId(brainDir, key, created.id);
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Minted a key but could not store it (${error.message}); the old key is untouched `
+        + 'and the new one should be revoked by hand.',
+      minted: created.label,
+    };
+  }
+
+  const revoked = await revokeOld({ auth, recipe, created, secretMeta, brainDir, key, fetchImpl, baseUrl });
+
+  return {
+    ok: true,
+    key,
+    class: 'provider_api',
+    method: 'provider_api',
+    label: created.label,
+    revoked,
+    exports,
+  };
+}
+
+/** Best-effort revoke of the previous credential; never fails the rotation. */
+async function revokeOld({ auth, recipe, created, secretMeta, brainDir, key, fetchImpl, baseUrl }) {
+  if (!recipe.revoke) return { attempted: false, reason: 'provider declares no revoke endpoint' };
+  const prior = await secretMeta(brainDir, key);
+  const priorId = prior?.provider_key_id || prior?.key_id || null;
+  if (!priorId) {
+    return {
+      attempted: false,
+      reason: 'the store does not record the previous key id, so the old key cannot be addressed; '
+        + 'revoke it in the provider console',
+    };
+  }
+  try {
+    const res = await fetchImpl(`${baseUrl}${recipe.revoke.path(priorId, created.id)}`, {
+      method: recipe.revoke.method || 'DELETE',
+      headers: auth,
+    });
+    return res.ok ? { attempted: true, revoked: true } : { attempted: true, revoked: false, status: res.status };
+  } catch (error) {
+    return { attempted: true, revoked: false, error: error.message };
+  }
+}

package/scaffold/.agent/skills/total-recall/plugins/auth/src/provider-catalog.mjs

@@ -15,6 +15,15 @@
  *     class?: 'provider_api' | 'provider_browser' | 'self_generated' | 'manual',
  *     high_risk?: boolean,
  *     manual_keys?: string[],
+ *     // A provider that lets the account mint and revoke its own keys over its API. The management
+ *     // credential is a separate stored secret; without it the provider cannot rotate itself, which
+ *     // is what made 'provider_api' a class with no implementation.
+ *     management_key?: string,
+ *     api?: {
+ *       base_url: string,
+ *       create: { method?: string, path: string, body?: (label: string) => object, value_path: string, id_path?: string },
+ *       revoke?: { method?: string, path: (id: string, hash: string) => string },
+ *     },
  *   },
  *   default_monthly_cap_usd?: number | null,
  *   tiers?: { id: string, label: string, monthly_usd?: number | null }[],
@@ -93,6 +102,28 @@ export const PROVIDER_CATALOG = [
       env_keys: ['OPENROUTER_API_KEY'],
       notes: 'OpenAI-compatible base URL https://openrouter.ai/api/v1',
     },
+    // OpenRouter issues and revokes keys over its own API, but only to a credential that carries
+    // management rights. The inference key the store already holds cannot do it — the API answers
+    // is_management_key:false and 401 on GET /api/v1/keys — so the management credential lives
+    // under its own name and this declaration says where to find it.
+    rotation: {
+      class: 'provider_api',
+      management_key: 'OPENROUTER_MANAGEMENT_KEY',
+      api: {
+        base_url: 'https://openrouter.ai/api/v1',
+        create: {
+          method: 'POST',
+          path: '/keys',
+          body: (label) => ({ name: label }),
+          value_path: 'key',
+          id_path: 'data.hash',
+        },
+        revoke: {
+          method: 'DELETE',
+          path: (id) => `/keys/${id}`,
+        },
+      },
+    },
     default_monthly_cap_usd: 30,
     tiers: [{ id: 'payg', label: 'Pay as you go', monthly_usd: null }],
   },

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

@@ -10,6 +10,7 @@ import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
 import os from 'os';
+import { spawnSync } from 'node:child_process';
 import { encryptSecrets, decryptSecrets, encryptSecretsSync, decryptSecretsSync } from './crypto.mjs';
 import { DEFAULT_KEYCHAIN_SERVICE, readKeychainPassword } from './secrets-keychain.mjs';
 import { writeFileSecure, appendFileSecure } from './secure-file.mjs';
@@ -58,6 +59,7 @@ export function secretsPassword({
   env = process.env,
   readKeychain = readTrKeychainPassword,
   readEnvFile = readTrEnvFilePassword,
+  readLaunchAgent = readTrLaunchAgentPassword,
 } = {}) {
   const fromEnv = env.TR_SECRETS_PASSWORD || env.TR_MASTER_PASSWORD;
   if (fromEnv) return fromEnv;
@@ -70,7 +72,25 @@ export function secretsPassword({
     }
     if (fromKeychain) return fromKeychain;
   }
-  return readEnvFile(env) || null;
+  return readEnvFile(env) || readLaunchAgent(env) || null;
+}
+
+/** Existing owner-only launchd carrier, also usable by noninteractive agents.
+ * No password is copied into another store, environment, argv or output.
+ */
+export function readTrLaunchAgentPassword(env=process.env,{platform=process.platform,exec=spawnSync}={}) {
+  if(platform!=='darwin' || env.TR_SECRETS_NO_HOST_CARRIER==='1')return null;
+  const home=env.HOME || (env===process.env?os.homedir():null);
+  const file=env.TR_SECRETS_LAUNCH_AGENT || (home?path.join(home,'Library/LaunchAgents/com.totalrecall.brain.plist'):null);
+  if(!file)return null;
+  try {
+    const stat=fs.lstatSync(file),directory=fs.lstatSync(path.dirname(file));
+    const uid=process.getuid?.();
+    if(!stat.isFile() || !directory.isDirectory() || (stat.mode & 0o077)!==0 || (directory.mode & 0o022)!==0 || (uid!==undefined && (stat.uid!==uid || directory.uid!==uid)))return null;
+    const result=exec('/usr/bin/plutil',['-extract','EnvironmentVariables.TR_SECRETS_PASSWORD','raw','-o','-',file],{encoding:'utf8',timeout:5000,maxBuffer:65536});
+    if(result.status!==0)return null;
+    return (result.stdout || '').replace(/\r?\n$/,'') || null;
+  }catch{return null;}
 }
 
 /**

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

@@ -23,6 +23,7 @@ import { getProvider, providerForKeyName } from './provider-catalog.mjs';
 import { atomicWrite, safeStringify } from './vault.mjs';
 import { getRotationPlan, generateSecretValue } from './rotation-capability.mjs';
 import { getRecipe, valueLooksValid } from './provider-rotation-recipes.mjs';
+import { rotateViaProviderApi } from './provider-api-rotation.mjs';
 import {
   launchRotationContext,
   openConsole,
@@ -440,7 +441,45 @@ export async function rotateAuto(brainDir, key, opts = {}) {
     return { ok: true, key, class: plan.class, method: 'self_generated', exports: result.exports };
   }
 
-  if (plan.class === 'provider_browser' || plan.class === 'provider_api') {
+  // A provider that can mint and revoke its own keys must not be driven through a browser. This
+  // branch used to send provider_api down the browser path with everything else, which is why a
+  // management credential had no consumer anywhere in the code and a rotation that needed no human
+  // instead waited on a console login.
+  const provider = row.provider ? getProvider(row.provider) : providerForKeyName(key);
+  const api = provider?.rotation?.api;
+  if (plan.class === 'provider_api' && api?.create) {
+    const attempt = await rotateViaProviderApi({
+      brainDir,
+      key,
+      managementKeyName: provider.rotation.management_key,
+      recipe: api,
+      baseUrl: api.base_url,
+      // getSecret returns an object even for a key it does not hold, so 'truthy' is not the test.
+      // Reading a missing management key as present sent the request out with a bogus credential
+      // and surfaced the provider's 401, which reads as "wrong key" when the real answer is
+      // "no management key is stored at all".
+      readSecret: async (brain, name) => {
+        try {
+          const found = await getSecret(brain, name);
+          if (!found || found.found === false) return null;
+          const value = found.value ?? found;
+          return typeof value === 'string' && value ? value : null;
+        } catch { return null; }
+      },
+      storeSecret: (brain, name, value, o) => rotateSecretAndExport(brain, name, value, {
+        actor: o.actor, exportEnv: opts.exportEnv !== false,
+      }),
+      secretMeta: async (brain, name) => (await listSecretsMeta(brain)).find((r) => r.key === name) || null,
+      // Remember which key the provider minted, so the next rotation can revoke this one instead of
+      // reporting that the previous credential cannot be addressed.
+      recordKeyId: async (brain, name, id) => {
+        try { await updateSecretMeta(brain, name, { provider_key_id: id }); } catch { /* metadata is best-effort */ }
+      },
+    });
+    return { ...attempt, class: plan.class, method: 'provider_api' };
+  }
+
+  if (plan.class === 'provider_browser') {
     return { ...(await rotateViaBrowser(brainDir, key, opts)), class: plan.class, method: 'browser' };
   }
 

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

@@ -7,20 +7,17 @@ import { resolveSecretsPath, loadSecrets, saveSecrets, ensureMeta, appendAudit,
 
 const REQUEST_TIMEOUT_MS = 10_000;
 
-function serverPort(override) {
-  // The leader's port is whatever it advertised on the mesh. Assuming the local
-  // default made sync fail with "fetch failed" against a leader that was up and
-  // reachable on a different port (the cloud brain serves on 3900, not 3000).
-  const candidate = Number(override ?? process.env.TR_SERVER_PORT ?? process.env.PORT ?? 3000);
-  return Number.isInteger(candidate) && candidate > 0 && candidate <= 65535 ? candidate : 3000;
+function serverPort() {
+  const value = Number(process.env.TR_SERVER_PORT || process.env.PORT || 3000);
+  return Number.isInteger(value) && value > 0 && value <= 65535 ? value : 3000;
 }
 
-function meshUrl(ip, route, port) {
+function meshUrl(ip, route) {
   const octets = String(ip || '').split('.').map(Number);
   if (octets.length !== 4 || octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255) || octets[0] !== 100 || octets[1] < 64 || octets[1] > 127) {
     throw new Error('Leader IP is outside the Tailscale CGNAT range');
   }
-  return `http://${ip}:${serverPort(port)}${route}`;
+  return `http://${ip}:${serverPort()}${route}`;
 }
 
 export function getSecretsChecksum() {
@@ -42,8 +39,8 @@ export function secretsSyncMode(env = process.env) {
  * anything. The node's store is never replaced wholesale and the node keeps
  * its own master password.
  */
-export async function syncGrantedSecrets(leaderIp, { dir = brainDir, fetchImpl = fetch, port } = {}) {
-  const base = meshUrl(leaderIp, '/api/secrets/mesh', port);
+export async function syncGrantedSecrets(leaderIp, { dir = brainDir, fetchImpl = fetch } = {}) {
+  const base = meshUrl(leaderIp, '/api/secrets/mesh');
   const listResponse = await fetchImpl(base, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
   if (!listResponse.ok) throw new Error(`Leader returned ${listResponse.status}`);
   const { keys } = await listResponse.json();
@@ -79,6 +76,6 @@ export async function syncLoop() {
   if (await isLeader()) return;
   const leaderInfo = await getLeaderInfo();
   if (!leaderInfo?.ip) return;
-  try { await syncGrantedSecrets(leaderInfo.ip, { port: leaderInfo.brain_port }); }
-  catch (err) { logger.error('secrets-sync', 'Failed to sync granted secrets', { error: err.message, leader: leaderInfo.ip, port: leaderInfo.brain_port ?? 'default' }); }
+  try { await syncGrantedSecrets(leaderInfo.ip); }
+  catch (err) { logger.error('secrets-sync', 'Failed to sync granted secrets', { error: err.message }); }
 }

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

@@ -1,18 +1,18 @@
 {
   "name": "tr-plugin-code-quality",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-code-quality",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "license": "MIT",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.11.2"
       },
       "devDependencies": {
-        "total-recall-brain": "3.40.3"
+        "total-recall-brain": "3.40.4"
       }
     },
     "node_modules/@gregiteen/ssss-cli": {
@@ -2595,9 +2595,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.3.tgz",
-      "integrity": "sha512-E5elOF/OvGAvDdXVDUQaV1xa7hWDOVYmK3z8V+zPNYVEtEoGhJplY1Rtqu76oHezwJDQRIhc4+3HhpvjH5fIww==",
+      "version": "3.40.4",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.4.tgz",
+      "integrity": "sha512-/9JfUWyzXcgHu3kV/rqsOvclMY25PpfW4jSrunsCrkt2MPDUDfGD+z22AoA/OG/jSHE4ZvD/A9QV4IYE2+O99w==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/composable-cli/package-lock.json

@@ -1,18 +1,18 @@
 {
   "name": "tr-plugin-composable-cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-composable-cli",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "license": "MIT",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.11.2"
       },
       "devDependencies": {
-        "total-recall-brain": "3.40.3"
+        "total-recall-brain": "3.40.4"
       }
     },
     "node_modules/@gregiteen/ssss-cli": {
@@ -2595,9 +2595,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.3.tgz",
-      "integrity": "sha512-E5elOF/OvGAvDdXVDUQaV1xa7hWDOVYmK3z8V+zPNYVEtEoGhJplY1Rtqu76oHezwJDQRIhc4+3HhpvjH5fIww==",
+      "version": "3.40.4",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.4.tgz",
+      "integrity": "sha512-/9JfUWyzXcgHu3kV/rqsOvclMY25PpfW4jSrunsCrkt2MPDUDfGD+z22AoA/OG/jSHE4ZvD/A9QV4IYE2+O99w==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

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

@@ -9,7 +9,7 @@
       "version": "0.1.0",
       "license": "MIT",
       "devDependencies": {
-        "total-recall-brain": "3.40.3"
+        "total-recall-brain": "3.40.4"
       }
     },
     "node_modules/@hexagon/base64": {
@@ -2566,9 +2566,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.3.tgz",
-      "integrity": "sha512-E5elOF/OvGAvDdXVDUQaV1xa7hWDOVYmK3z8V+zPNYVEtEoGhJplY1Rtqu76oHezwJDQRIhc4+3HhpvjH5fIww==",
+      "version": "3.40.4",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.4.tgz",
+      "integrity": "sha512-/9JfUWyzXcgHu3kV/rqsOvclMY25PpfW4jSrunsCrkt2MPDUDfGD+z22AoA/OG/jSHE4ZvD/A9QV4IYE2+O99w==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/git-sentinel/package-lock.json

@@ -1,15 +1,15 @@
 {
   "name": "tr-plugin-git-sentinel",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-git-sentinel",
-      "version": "1.1.1",
+      "version": "1.1.2",
       "license": "MIT",
       "devDependencies": {
-        "total-recall-brain": "3.40.3",
+        "total-recall-brain": "3.40.4",
         "vitest": "^4.1.10"
       }
     },
@@ -3560,9 +3560,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.3.tgz",
-      "integrity": "sha512-E5elOF/OvGAvDdXVDUQaV1xa7hWDOVYmK3z8V+zPNYVEtEoGhJplY1Rtqu76oHezwJDQRIhc4+3HhpvjH5fIww==",
+      "version": "3.40.4",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.4.tgz",
+      "integrity": "sha512-/9JfUWyzXcgHu3kV/rqsOvclMY25PpfW4jSrunsCrkt2MPDUDfGD+z22AoA/OG/jSHE4ZvD/A9QV4IYE2+O99w==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

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

@@ -9,7 +9,7 @@
       "version": "0.1.1",
       "license": "MIT",
       "devDependencies": {
-        "total-recall-brain": "3.40.3"
+        "total-recall-brain": "3.40.4"
       }
     },
     "node_modules/@hexagon/base64": {
@@ -2556,9 +2556,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.3.tgz",
-      "integrity": "sha512-E5elOF/OvGAvDdXVDUQaV1xa7hWDOVYmK3z8V+zPNYVEtEoGhJplY1Rtqu76oHezwJDQRIhc4+3HhpvjH5fIww==",
+      "version": "3.40.4",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.4.tgz",
+      "integrity": "sha512-/9JfUWyzXcgHu3kV/rqsOvclMY25PpfW4jSrunsCrkt2MPDUDfGD+z22AoA/OG/jSHE4ZvD/A9QV4IYE2+O99w==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/openwiki/ui/card.js

@@ -454,5 +454,5 @@ if (!customElements.get('tr-openwiki-card')) {
   customElements.define('tr-openwiki-card', OpenWikiCard);
 }
 if (!customElements.get('openwiki-card')) {
-  customElements.define('openwiki-card', OpenWikiCard);
+  customElements.define('openwiki-card', class extends OpenWikiCard {});
 }

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

@@ -1,16 +1,16 @@
 {
   "name": "tr-plugin-security",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-security",
-      "version": "0.3.1",
+      "version": "0.3.2",
       "license": "MIT",
       "devDependencies": {
         "jsdom": "^26.1.0",
-        "total-recall-brain": "3.40.3"
+        "total-recall-brain": "3.40.4"
       }
     },
     "node_modules/@asamuzakjp/css-color": {
@@ -2916,9 +2916,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.3.tgz",
-      "integrity": "sha512-E5elOF/OvGAvDdXVDUQaV1xa7hWDOVYmK3z8V+zPNYVEtEoGhJplY1Rtqu76oHezwJDQRIhc4+3HhpvjH5fIww==",
+      "version": "3.40.4",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.4.tgz",
+      "integrity": "sha512-/9JfUWyzXcgHu3kV/rqsOvclMY25PpfW4jSrunsCrkt2MPDUDfGD+z22AoA/OG/jSHE4ZvD/A9QV4IYE2+O99w==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/src/cli/init.mjs

@@ -198,6 +198,59 @@ function printHelp() {
 `);
 }
 
+// ─── Bootstrap token store resolution ───────────────────────────────────────
+
+/**
+ * The brain directory whose key store the server answering `brainUrl` reads.
+ *
+ * A server process derives its store from `AGENT_DIR` alone (`core/config.mjs`
+ * → `brainDir`), and the launchd service starts it with the GLOBAL agent dir.
+ * So a token written into a project brain's `brain.json` is only usable when
+ * it was minted into that global store. Minting into the project's own store
+ * produced a token no running server would accept, while init still reported
+ * success — the failure surfaced later as `startup check` reporting
+ * `brain failed` (`instructions-http-401`) for every project.
+ *
+ * Loopback URLs therefore resolve to the store the local server reads. A
+ * remote brain's store is not reachable from here, so the target brain keeps
+ * its own store.
+ *
+ * Two constraints pull against each other and both must hold:
+ *   1. `AGENT_DIR` (and the `_TR_TEST_AGENT_DIR` fixture override) honours an
+ *      explicitly selected root, so the serving store must not be derived by
+ *      blindly re-reading it — when it is pinned at the project the two stores
+ *      collapse and the bug returns untouched.
+ *   2. An explicit root owns its whole layout: init must never create
+ *      `$HOME/.agent` behind a caller that named a different root (a test, or
+ *      an isolated install). So `globalBrainDir` is used only when it is
+ *      genuinely distinct AND already exists; otherwise the target store is
+ *      kept rather than a new one being created.
+ */
+export function resolveServingBrainDir({ brainDir, isProject, brainUrl, globalBrainDir = null }) {
+  if (!isProject) return brainDir;
+  let loopback = false;
+  try {
+    const host = new URL(brainUrl).hostname;
+    loopback = ['localhost', '127.0.0.1', '[::1]', '::1'].includes(host);
+  } catch { /* unparseable URL: treat as remote and keep the target store */ }
+  if (!loopback) return brainDir;
+  // `globalBrainDir` is the caller's explicit answer and is preferred. Only
+  // when it names nothing usable do we consider the home-relative global
+  // brain — and never when an explicit root owns the layout, because that
+  // root's server is the one being served and $HOME belongs to someone else.
+  const explicitRoot = Boolean(process.env.AGENT_DIR || process.env._TR_TEST_AGENT_DIR);
+  const candidates = [globalBrainDir];
+  if (!explicitRoot) candidates.push(path.join(os.homedir(), '.agent', 'skills', 'total-recall'));
+  for (const candidate of candidates) {
+    if (!candidate || candidate === brainDir) continue;
+    // Only adopt a store that is already established; adopting a missing one
+    // would make init responsible for creating it, which constraint 2 forbids.
+    if (fs.existsSync(path.join(candidate, 'config', 'keys.jsonl'))
+      || fs.existsSync(path.join(candidate, 'config', '.ssss'))) return candidate;
+  }
+  return brainDir;
+}
+
 // ─── Main ───────────────────────────────────────────────────────────────────
 
 export default async function init(args) {
@@ -207,6 +260,10 @@ export default async function init(args) {
   const cwd = process.cwd();
   const globalAgentDir = getGlobalAgentDir();
   const globalBrainDir = path.join(globalAgentDir, 'skills', 'total-recall');
+  // The HOME-relative global brain, which is what a background server reads.
+  // `globalAgentDir` above honours AGENT_DIR and can therefore point at the
+  // project being initialised; the serving store must not be derived from it.
+  const servingGlobalBrainDir = path.join(os.homedir(), '.agent', 'skills', 'total-recall');
 
   // Determine target based on --project flag
   const isProject = opts.project;
@@ -705,12 +762,26 @@ export default async function init(args) {
 
     if (needsBootstrap) {
       try {
-        const { issueKey } = await import('../server/keys.mjs');
-        const keyData = issueKey('Default Local Developer Key', { scopes: ['*'] });
+        const { keyStoreFor } = await import('../server/keys.mjs');
         brainCfg.url = brainCfg.url || 'http://localhost:3000';
+        // Mint the bootstrap token into the store the SERVER reads, which is
+        // the store under `AGENT_DIR` — not necessarily the brain this init run
+        // targets. A project brain's token is validated by whatever server
+        // process answers `brainCfg.url`, and that process resolves its store
+        // from `AGENT_DIR` (launchd starts it with the global one). Issuing
+        // into the project's own store wrote a token no running server could
+        // match: init reported "pre-authorized" and every request answered 401,
+        // so `startup check` said `brain failed` on project after project.
+        // When the target IS the store the server reads this is a no-op branch.
+        const servingBrainDir = resolveServingBrainDir({ brainDir, isProject, brainUrl: brainCfg.url, globalBrainDir: servingGlobalBrainDir });
+        const { issueKey } = keyStoreFor(servingBrainDir);
+        const keyData = issueKey('Default Local Developer Key', { scopes: ['*'] });
         brainCfg.token = brainCfg.token || keyData.token;
         writeFileSecure(brainJsonPath, JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
         logOk(`Bootstrap configuration successfully generated and pre-authorized at ${brainCfg.url}`);
+        if (isProject && servingBrainDir !== brainDir) {
+          logOk(`Bootstrap token issued to the serving brain store at ${servingBrainDir}`);
+        }
         if (brainCfg.project_id) {
           logOk(`Assigned project UUID ${brainCfg.project_id} to project brain`);
         }

package/src/server/keys.mjs

@@ -2,4 +2,30 @@
 import { brainDir } from '../core/config.mjs';
 import { loadPluginModule } from '../core/plugin-runtime.mjs';
 const { createKeyStore } = await loadPluginModule('auth', 'access-keys');
+
+/**
+ * The default store is the one under `AGENT_DIR`. That is the store a server
+ * process reads, because `core/config.mjs` derives `brainDir` from
+ * `AGENT_DIR` alone. Anything that mints a token a *server* must accept has to
+ * use this store — see `keyStoreFor`.
+ */
 export const { ALL_SCOPES, KNOWN_SCOPES, normalizeScopes, isExpiredKey, keyHasScope, keyHasAnyScope, loadKeys, issueKey, revokeKey, recordKeyUsage, isValidToken, findValidKeyByToken, loadRoles, setRole, listKeyUsage, recordKeyOutcome } = createKeyStore({ brainDir });
+
+/**
+ * A key store bound to an explicit brain directory.
+ *
+ * `init` writes a bootstrap PAT into a brain's `config/brain.json`, and the
+ * server that answers that brain's URL validates it against whatever store its
+ * own `AGENT_DIR` produced. When the two differ, `init` used to mint the token
+ * into a store no running server reads: it printed "pre-authorized", and every
+ * request with that token then answered 401. Callers that need a token the
+ * server will accept resolve the serving brain first and pass it here.
+ *
+ * @param {string} targetBrainDir absolute brain directory (…/skills/total-recall)
+ */
+export function keyStoreFor(targetBrainDir) {
+  if (typeof targetBrainDir !== 'string' || !targetBrainDir) {
+    throw new Error('Explicit auth key store brain directory required');
+  }
+  return createKeyStore({ brainDir: targetBrainDir });
+}