total-recall-brain 3.41.2 → 3.41.4

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

@@ -8,11 +8,26 @@
       "name": "tr-plugin-git-sentinel",
       "version": "1.1.2",
       "license": "MIT",
+      "dependencies": {
+        "@gregiteen/ssss-cli": "0.14.3"
+      },
       "devDependencies": {
-        "total-recall-brain": "3.41.1",
+        "total-recall-brain": "3.41.3",
         "vitest": "^4.1.10"
       }
     },
+    "node_modules/@gregiteen/ssss-cli": {
+      "version": "0.14.3",
+      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.14.3.tgz",
+      "integrity": "sha512-vvGgiNLjus3/xp+iotiGqbSG0R7+Q/bP5cP2Psa7Rhtm/vrMuM5B4LebYu7bPf3TzgCyTbv96PcxGWf6gxbW0Q==",
+      "license": "ISC",
+      "bin": {
+        "ssss": "scripts/ssss.mjs"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@hexagon/base64": {
       "version": "1.1.28",
       "resolved": "https://registry.npmjs.org/@hexagon/base64/-/base64-1.1.28.tgz",
@@ -647,9 +662,9 @@
     },
     "node_modules/@ssss/cli": {
       "name": "@gregiteen/ssss-cli",
-      "version": "0.11.2",
-      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.11.2.tgz",
-      "integrity": "sha512-DTkBPCOv9uN79YoRtsa/GnXPbbeHOU5PQcQ995axHg+SLWdkL6xmrTRs5Xxshcje/Iv6+lKkYOc9UL+Arn9kHg==",
+      "version": "0.12.1",
+      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.12.1.tgz",
+      "integrity": "sha512-ff0L2LV4db1CfD4W3VmIJwT9fvrpuKDGDfhe6gtjrrgtRmo7BP7jYjRtH7yuQipKikyiP9LIvmVIaxvbjLTwkA==",
       "dev": true,
       "license": "ISC",
       "bin": {
@@ -3560,9 +3575,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.41.1",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.1.tgz",
-      "integrity": "sha512-QraXzcZpCTMssx1gaz8xjvSKf5KqirAaxzzER/ICBrWvawdNTLUDDMsVEYQUA/7thgwtL1QVIxU4dpfCGZwp+g==",
+      "version": "3.41.3",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.3.tgz",
+      "integrity": "sha512-0uIh3WZE3dHxrKFTtRMxvSBLx7aV3j7ry9H9NxRShtCycwQ38T7+70Q/GJAqsdpwt894h8B6AAmWJnHwsFG3XQ==",
       "dev": true,
       "license": "MIT",
       "workspaces": [
@@ -3570,7 +3585,7 @@
       ],
       "dependencies": {
         "@simplewebauthn/server": "^13.3.2",
-        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.11.2",
+        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.12.1",
         "bcrypt": "^6.0.0",
         "better-sqlite3": "^12.11.1",
         "cookie-parser": "^1.4.7",

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

@@ -4,7 +4,8 @@
   "type": "module",
   "description": "Reports the state of the current git repository: branch, dirty files, unpushed commits and stashes.",
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "ssss": "ssss"
   },
   "license": "MIT",
   "files": [
@@ -16,5 +17,8 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@gregiteen/ssss-cli": "0.14.3"
   }
 }

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

@@ -410,14 +410,26 @@ export class GitSentinelCard extends HTMLElement {
           --face-ok: #047857;
           --face-warn: #b45309;
           --face-danger: #b91c1c;
+          --face-text-default: #111827;
+          --face-muted-default: #6b7280;
+          --face-line-default: #e5e7eb;
+          --face-surface-default: #f9fafb;
+          --face-accent-default: #b45309;
+          --face-dark-ok: #34d399;
+          --face-dark-warn: #fbbf24;
+          --face-dark-danger: #f87171;
+          --face-dark-text: #e8eaf0;
+          --face-dark-muted: #a2a8b8;
+          --face-dark-line: #2a3040;
+          --face-dark-surface: #171a23;
           --face-radius: 6px;
           --face-motion: 140ms ease-out;
           --face-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
-          --face-text: var(--text-primary, #111827);
-          --face-muted: var(--text-secondary, #6b7280);
-          --face-line: var(--border, #e5e7eb);
-          --face-surface: var(--bg-secondary, #f9fafb);
-          --face-accent: var(--card-color, #b45309);
+          --face-text: var(--text-primary, var(--face-text-default));
+          --face-muted: var(--text-secondary, var(--face-muted-default));
+          --face-line: var(--border, var(--face-line-default));
+          --face-surface: var(--bg-secondary, var(--face-surface-default));
+          --face-accent: var(--card-color, var(--face-accent-default));
           font-family: 'Space Grotesk', var(--font-sans, system-ui, sans-serif);
           color: var(--face-text);
         }
@@ -425,25 +437,25 @@ export class GitSentinelCard extends HTMLElement {
            verdict line, so they are retuned whenever the host is dark. */
         @media (prefers-color-scheme: dark) {
           :host {
-            --face-ok: #34d399;
-            --face-warn: #fbbf24;
-            --face-danger: #f87171;
-            --face-text: var(--text-primary, #e8eaf0);
-            --face-muted: var(--text-secondary, #a2a8b8);
-            --face-line: var(--border, #2a3040);
-            --face-surface: var(--bg-secondary, #171a23);
+            --face-ok: var(--face-dark-ok);
+            --face-warn: var(--face-dark-warn);
+            --face-danger: var(--face-dark-danger);
+            --face-text: var(--text-primary, var(--face-dark-text));
+            --face-muted: var(--text-secondary, var(--face-dark-muted));
+            --face-line: var(--border, var(--face-dark-line));
+            --face-surface: var(--bg-secondary, var(--face-dark-surface));
           }
         }
         :host-context([data-theme="dark"]),
         :host-context(.theme-dark),
         :host-context(.dark) {
-          --face-ok: #34d399;
-          --face-warn: #fbbf24;
-          --face-danger: #f87171;
-          --face-text: var(--text-primary, #e8eaf0);
-          --face-muted: var(--text-secondary, #a2a8b8);
-          --face-line: var(--border, #2a3040);
-          --face-surface: var(--bg-secondary, #171a23);
+          --face-ok: var(--face-dark-ok);
+          --face-warn: var(--face-dark-warn);
+          --face-danger: var(--face-dark-danger);
+          --face-text: var(--text-primary, var(--face-dark-text));
+          --face-muted: var(--text-secondary, var(--face-dark-muted));
+          --face-line: var(--border, var(--face-dark-line));
+          --face-surface: var(--bg-secondary, var(--face-dark-surface));
         }
         * { box-sizing: border-box; }
         .top { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin-bottom: 12px; }

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

@@ -1,20 +1,21 @@
 {
   "name": "tr-plugin-mesh",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-mesh",
-      "version": "0.2.4",
+      "version": "0.2.6",
       "license": "MIT",
       "dependencies": {
+        "@gregiteen/ssss-cli": "0.14.3",
         "express": "^5.2.1"
       },
       "devDependencies": {
         "jsdom": "^29.1.1",
         "supertest": "^7.3.1",
-        "total-recall-brain": "3.41.1",
+        "total-recall-brain": "3.41.3",
         "vitest": "^4.1.12"
       }
     },
@@ -240,6 +241,18 @@
         }
       }
     },
+    "node_modules/@gregiteen/ssss-cli": {
+      "version": "0.14.3",
+      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.14.3.tgz",
+      "integrity": "sha512-vvGgiNLjus3/xp+iotiGqbSG0R7+Q/bP5cP2Psa7Rhtm/vrMuM5B4LebYu7bPf3TzgCyTbv96PcxGWf6gxbW0Q==",
+      "license": "ISC",
+      "bin": {
+        "ssss": "scripts/ssss.mjs"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@hexagon/base64": {
       "version": "1.1.28",
       "resolved": "https://registry.npmjs.org/@hexagon/base64/-/base64-1.1.28.tgz",
@@ -897,9 +910,9 @@
     },
     "node_modules/@ssss/cli": {
       "name": "@gregiteen/ssss-cli",
-      "version": "0.11.2",
-      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.11.2.tgz",
-      "integrity": "sha512-DTkBPCOv9uN79YoRtsa/GnXPbbeHOU5PQcQ995axHg+SLWdkL6xmrTRs5Xxshcje/Iv6+lKkYOc9UL+Arn9kHg==",
+      "version": "0.12.1",
+      "resolved": "https://registry.npmjs.org/@gregiteen/ssss-cli/-/ssss-cli-0.12.1.tgz",
+      "integrity": "sha512-ff0L2LV4db1CfD4W3VmIJwT9fvrpuKDGDfhe6gtjrrgtRmo7BP7jYjRtH7yuQipKikyiP9LIvmVIaxvbjLTwkA==",
       "dev": true,
       "license": "ISC",
       "bin": {
@@ -4216,9 +4229,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.41.1",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.1.tgz",
-      "integrity": "sha512-QraXzcZpCTMssx1gaz8xjvSKf5KqirAaxzzER/ICBrWvawdNTLUDDMsVEYQUA/7thgwtL1QVIxU4dpfCGZwp+g==",
+      "version": "3.41.3",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.3.tgz",
+      "integrity": "sha512-0uIh3WZE3dHxrKFTtRMxvSBLx7aV3j7ry9H9NxRShtCycwQ38T7+70Q/GJAqsdpwt894h8B6AAmWJnHwsFG3XQ==",
       "dev": true,
       "license": "MIT",
       "workspaces": [
@@ -4226,7 +4239,7 @@
       ],
       "dependencies": {
         "@simplewebauthn/server": "^13.3.2",
-        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.11.2",
+        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.12.1",
         "bcrypt": "^6.0.0",
         "better-sqlite3": "^12.11.1",
         "cookie-parser": "^1.4.7",

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

@@ -1,14 +1,16 @@
 {
   "name": "tr-plugin-mesh",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "description": "Headscale and Tailscale SSH control-server mesh administration and node discovery",
   "scripts": {
-    "test": "node --test test/*.test.mjs && vitest run"
+    "test": "node --test test/*.test.mjs && vitest run",
+    "ssss": "ssss"
   },
   "license": "MIT",
   "dependencies": {
-    "express": "^5.2.1"
+    "express": "^5.2.1",
+    "@gregiteen/ssss-cli": "0.14.3"
   },
   "files": [
     "cli.mjs",

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

@@ -2,7 +2,7 @@
   "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
   "id": "mesh",
   "name": "Headscale",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Control-server mesh administration, Tailscale SSH, and peer node discovery.",
   "license": "MIT",
   "requires": [

package/scaffold/.agent/skills/total-recall/plugins/mesh/src/cli/grants.mjs

@@ -2,10 +2,12 @@
  * `mesh grants` — which enrolled machines may read which secret keys.
  *
  *   mesh grants list
- *   mesh grants add    (--node <name> | --tag <tag:x> | --user <login>) KEY [KEY...]
+ *   mesh grants add    (--node <name> | --tag <tag:x> | --user <login>) (KEY | --repo <name>)...
  *   mesh grants remove (--node <name> | --tag <tag:x> | --user <login>) [KEY...]
  *
- * Keys may end in `*` to match a prefix. Nothing is granted by default.
+ * Keys may end in `*` to match a prefix. `--repo <name>` grants every secret whose `repos`
+ * metadata names that repository (stored as `repo:<name>`, resolved on the leader). Prefer it to
+ * `*`: a node that leaks then exposes only what its repositories use. Nothing is granted by default.
  */
 import { grantKeys, loadPolicy, revokeKeys, savePolicy, policyPath } from '../core/mesh-identity.mjs';
 
@@ -15,13 +17,14 @@ function parse(args) {
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (arg === '--node' || arg === '--tag' || arg === '--user') selector[arg.slice(2)] = args[(i += 1)];
+    else if (arg === '--repo') keys.push(`repo:${args[(i += 1)]}`);
     else if (arg.startsWith('--')) throw new Error(`Unknown option ${arg}`);
     else keys.push(arg);
   }
   return { selector, keys };
 }
 
-export async function grantsCli(args, brainDir, out = console.log) {
+export async function grantsCli(args, brainDir, out = console.log, warn = console.error) {
   const action = args[0] || 'list';
   if (action === 'list') {
     out(JSON.stringify({ path: policyPath(brainDir), ...loadPolicy(brainDir) }));
@@ -29,6 +32,7 @@ export async function grantsCli(args, brainDir, out = console.log) {
   }
   if (action !== 'add' && action !== 'remove') throw new Error('Usage: mesh grants list|add|remove');
   const { selector, keys } = parse(args.slice(1));
+  if (action === 'add' && keys.includes('*')) warn('Warning: "*" gives this machine every secret; if it leaks, every secret must be rotated. Prefer --repo <name> or named keys.');
   const current = loadPolicy(brainDir);
   const next = action === 'add' ? grantKeys(current, selector, keys) : revokeKeys(current, selector, keys);
   savePolicy(brainDir, next);

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

@@ -26,9 +26,10 @@ import {
   buildMeshSshPolicy,
 } from '../core/headscale-client.mjs';
 import {
-  findMeshNode,
+  isSelfNode,
   listEnrichedMeshNodes,
   meshVaultRoot,
+  resolveMeshNode,
   setMeshNodeAccess,
 } from '../core/mesh.mjs';
 import {
@@ -51,6 +52,9 @@ function printHelp() {
     nodes                  List mesh nodes and how to reach each one
     ssh <node> [cmd…]      Open a session using the node's recorded access
     exec <node> <cmd…>     Execute a command on a node non-interactively (--json)
+    leader [--json]        Show the elected leader and its server port
+    leader pin <ip> [--port <n>]
+                           Pin the leader node and the port its server answers on
     access <node>          Show resolved access for a node
     access <node> --user <u> [--port <n>] [--host <h>] [--identity <path>]
                            Record how to reach a node
@@ -368,22 +372,19 @@ export default async function meshCli(argv = []) {
         return;
       }
 
-      // Try enriched nodes first, then fall back to the Headscale registry
-      // for givenName matches (the friendly name shown in `mesh nodes`).
-      let node = findMeshNode(target, vaultRoot);
-      if (!node) {
-        let registry = null;
-        try {
-          const data = await headscaleFetch(
-            '/api/v1/node', {}, brainDir,
-          );
-          registry = data?.nodes || [];
-        } catch {}
-        node = findMeshNode(target, vaultRoot, registry);
+      let node;
+      try {
+        node = await resolveMeshNode(target, { vaultRoot, brainDir });
+      } catch (err) {
+        fail(err.message, 'Run `total-recall mesh nodes` to list them.');
+        return;
       }
 
-      if (!node) {
-        fail(`No mesh node matches "${target}".`, 'Run `total-recall mesh nodes` to list them.');
+      if (isSelfNode(node)) {
+        fail(
+          `"${node.hostname}" is this machine — the mesh never tunnels a node into itself.`,
+          'Run the command locally; `mesh ssh`/`mesh exec` address peers.',
+        );
         return;
       }
 
@@ -416,7 +417,7 @@ export default async function meshCli(argv = []) {
 
       try {
         const { execMeshCommand } = await import('../core/mesh.mjs');
-        const res = await execMeshCommand(target, cmd, { vaultRoot });
+        const res = await execMeshCommand(target, cmd, { vaultRoot, brainDir });
         if (jsonMode) {
           console.log(JSON.stringify(res, null, 2));
         } else {
@@ -446,14 +447,21 @@ export default async function meshCli(argv = []) {
       if (target === 'discover') {
         const { discoverNodeAccess } = await import('../core/mesh-discover.mjs');
         const wanted = args.find((a) => !a.startsWith('-'));
-        const targets = wanted
-          ? [findMeshNode(wanted, vaultRoot)].filter(Boolean)
-          : listEnrichedMeshNodes(vaultRoot).filter(
-              (n) => !n.self && n.ip && n.online !== false && !n.access?.verified_at,
-            );
+        let targets;
+        if (wanted) {
+          try {
+            targets = [await resolveMeshNode(wanted, { vaultRoot, brainDir })];
+          } catch (err) {
+            fail(err.message, 'Run `total-recall mesh nodes` to list them.');
+            return;
+          }
+        } else {
+          targets = listEnrichedMeshNodes(vaultRoot).filter(
+            (n) => !n.self && n.ip && n.online !== false && !n.access?.verified_at,
+          );
+        }
         if (!targets.length) {
-          console.log(wanted ? `No mesh node matches "${wanted}".` : 'Every online node already has a verified login.');
-          if (wanted) process.exitCode = 1;
+          console.log('Every online node already has a verified login.');
           return;
         }
         let missing = 0;
@@ -545,9 +553,11 @@ export default async function meshCli(argv = []) {
       const identity = readOption('--identity');
 
       if (!user && !port && !host && !identity) {
-        const node = findMeshNode(target, vaultRoot);
-        if (!node) {
-          fail(`No mesh node matches "${target}".`);
+        let node;
+        try {
+          node = await resolveMeshNode(target, { vaultRoot, brainDir });
+        } catch (err) {
+          fail(err.message, 'Run `total-recall mesh nodes` to list them.');
           return;
         }
         console.log(JSON.stringify(resolveNodeAccess(node), null, 2));
@@ -560,13 +570,12 @@ export default async function meshCli(argv = []) {
       if (host) patch.ssh_host = host;
       if (identity) patch.identity_file = identity;
 
-      const result = await setMeshNodeAccess(target, patch, { vaultRoot });
+      const result = await setMeshNodeAccess(target, patch, { vaultRoot, brainDir });
       if (!result.written) {
+        const unresolved = result.reason === 'node-not-found' || result.reason === 'node-ambiguous';
         fail(
-          `Could not record access for "${target}".`,
-          result.reason === 'node-not-found'
-            ? 'Run `total-recall mesh nodes` to see known nodes.'
-            : 'The vault write was rejected.',
+          unresolved ? result.error : `Could not record access for "${target}".`,
+          unresolved ? 'Run `total-recall mesh nodes` to see known nodes.' : 'The vault write was rejected.',
         );
         return;
       }
@@ -591,7 +600,19 @@ export default async function meshCli(argv = []) {
     }
 
     if (command === 'leader') {
-      const { getLeaderInfo, isLeader } = await import('../core/leader-election.mjs');
+      const { getLeaderInfo, isLeader, setLeaderPin } = await import('../core/leader-election.mjs');
+      if (args[0] === 'pin') {
+        const ip = args[1];
+        const portIndex = args.indexOf('--port');
+        const port = portIndex >= 0 ? args[portIndex + 1] : undefined;
+        if (!ip || ip.startsWith('-')) {
+          fail('Usage: total-recall mesh leader pin <mesh-ip> [--port <leader server port>]');
+          return;
+        }
+        const pinned = setLeaderPin({ ip, port });
+        console.log(`Leader pinned to ${pinned.leaderIp}${pinned.leaderPort ? `:${pinned.leaderPort}` : ''} in ${pinned.file}`);
+        return;
+      }
       const leaderInfo = await getLeaderInfo();
       const thisIsLeader = await isLeader();
       if (args.includes('--json')) {
@@ -602,7 +623,7 @@ export default async function meshCli(argv = []) {
         console.log('No leader elected (no mesh nodes online).');
         return;
       }
-      console.log(`👑 Current Cluster Leader: ${leaderInfo.hostname} (${leaderInfo.ip})`);
+      console.log(`👑 Current Cluster Leader: ${leaderInfo.hostname} (${leaderInfo.ip}${leaderInfo.port ? `:${leaderInfo.port}` : ''})`);
       console.log(`   Strategy: ${leaderInfo.strategy}`);
       console.log(`   Local node: ${thisIsLeader ? 'LEADER (this node runs cluster workloads)' : 'FOLLOWER'}`);
       return;
@@ -611,18 +632,20 @@ export default async function meshCli(argv = []) {
     if (command === 'ping' || command === 'latency') {
       const target = args.find((a) => !a.startsWith('-'));
       const isJson = args.includes('--json');
-      const { getMeshPeers, findMeshNode } = await import('../core/mesh.mjs');
+      const { getMeshPeers } = await import('../core/mesh.mjs');
       const { throttledFetch } = await import('../core/throttled-fetch.mjs');
 
       const port = Number(process.env.TR_SERVER_PORT || process.env.PORT || 3000);
 
       if (target) {
-        const node = findMeshNode(target, vaultRoot);
-        if (!node) {
-          fail(`No mesh node matches "${target}".`);
+        let node;
+        try {
+          node = await resolveMeshNode(target, { vaultRoot, brainDir });
+        } catch (err) {
+          fail(err.message, 'Run `total-recall mesh nodes` to list them.');
           return;
         }
-        if (node.self) {
+        if (isSelfNode(node)) {
           if (isJson) {
             console.log(JSON.stringify({ node: node.hostname, ip: node.ip, latency_ms: 0, self: true, reachable: true }, null, 2));
           } else {

package/scaffold/.agent/skills/total-recall/plugins/mesh/src/core/leader-election.mjs

@@ -60,6 +60,58 @@ export function leaderPin(brain = brainDir) {
   }
 }
 
+function validPort(value) {
+  const port = Number(value);
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+}
+
+/**
+ * Port the pinned leader's Total Recall server answers on.
+ *
+ * Followers used to reach the leader on their OWN configured port, which only
+ * works when every node happens to use the same one. The droplet serves on 3900
+ * while devices default to 3000, so every follower's secrets sync failed with a
+ * bare "fetch failed" once a minute, forever. The pin names the port alongside
+ * the IP (`TR_LEADER_PORT`, or `leaderPort` in config/leader.json).
+ */
+export function leaderPort(brain = brainDir) {
+  const raw = String(process.env.TR_LEADER_PORT || '').trim();
+  if (raw) return validPort(raw);
+  try {
+    const file = path.join(brain, 'config', 'leader.json');
+    if (!fs.existsSync(file)) return null;
+    return validPort(JSON.parse(fs.readFileSync(file, 'utf8'))?.leaderPort);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record the operator pin in <brain>/config/leader.json, keeping any note.
+ * The env vars still win when the supervisor sets them.
+ */
+export function setLeaderPin({ ip, port } = {}, brain = brainDir) {
+  const octets = String(ip || '').split('.').map(Number);
+  if (octets.length !== 4 || octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    throw new Error(`Leader pin needs a mesh IPv4 address, got "${ip}"`);
+  }
+  if (port !== undefined && port !== null && !validPort(port)) throw new Error(`Invalid leader port "${port}"`);
+  const file = path.join(brain, 'config', 'leader.json');
+  let current = {};
+  try { current = JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch {}
+  const next = { ...current, leaderIp: String(ip).trim(), updated_at: new Date().toISOString() };
+  if (port !== undefined && port !== null) next.leaderPort = validPort(port);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`);
+  fs.renameSync(temporary, file);
+  return { file, ...next };
+}
+
+function withPort(info, port) {
+  return port ? { ...info, port } : info;
+}
+
 function compareNodes(a, b) {
   const ipOrder = String(a.ip || '').localeCompare(String(b.ip || ''), undefined, { numeric: true });
   return ipOrder || String(a.hostname || '').localeCompare(String(b.hostname || ''));
@@ -77,11 +129,14 @@ export async function getLeaderInfo() {
   if (pin) {
     const pinned = nodes.find((node) => node.ip === pin);
     if (!pinned) return null;
-    return { hostname: pinned.hostname, ip: pinned.ip, strategy: 'pinned-mesh-ip' };
+    return withPort(
+      { hostname: pinned.hostname, ip: pinned.ip, strategy: 'pinned-mesh-ip' },
+      leaderPort() || validPort(pinned.brain_port),
+    );
   }
 
   const leader = [...nodes].sort(compareNodes)[0];
-  return { hostname: leader.hostname, ip: leader.ip, strategy: 'lowest-mesh-ip' };
+  return withPort({ hostname: leader.hostname, ip: leader.ip, strategy: 'lowest-mesh-ip' }, validPort(leader.brain_port));
 }
 
 /**