total-recall-brain 3.41.3 → 3.41.5

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.4"
   },
   "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));
 }
 
 /**

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

@@ -86,7 +86,13 @@ export function meshNodeKey(hostname) {
 function normalizeNode(node, self = false) {
   return {
     hostname: normalizeHostname(node?.DNSName) || node?.HostName || null,
+    // The name the machine reports for itself, which is what the control
+    // server lists it under. It differs from the DNS name whenever the node was
+    // renamed (a droplet listed as `portfolio-site` answers as `cloud.mesh…`),
+    // and it is not unique, so it is an identity to match, never a key.
+    os_hostname: node?.HostName || null,
     ip: node?.TailscaleIPs?.[0] || null,
+    ips: Array.isArray(node?.TailscaleIPs) ? node.TailscaleIPs : [],
     online: !!node?.Online,
     self,
     os: node?.OS || null,
@@ -226,7 +232,9 @@ function enrichPeerWithEntity(peer, ent, extra = {}) {
         : [];
   return {
     hostname: peer.hostname,
+    os_hostname: peer.os_hostname || null,
     ip: peer.ip || ent?.ip || null,
+    ips: Array.isArray(peer.ips) && peer.ips.length ? peer.ips : [peer.ip || ent?.ip].filter(Boolean),
     lan_ip: peer.lan_ip || ent?.lan_ip || null,
     brain_port: ent?.brain_port || null,
     online: !!peer.online,
@@ -308,47 +316,178 @@ function findEntityForSelf(self, vaultRoot) {
   return entityForPeer(self, entities, otherHosts);
 }
 
-/** Find an enriched node (live + vault) by hostname, registry name, or address. */
-export function findMeshNode(nameOrAddress, vaultRoot = meshVaultRoot(), registry = null) {
-  const wanted = String(nameOrAddress || '').trim();
-  if (!wanted) return null;
-  const key = meshNodeKey(wanted);
-  const nodes = listEnrichedMeshNodes(vaultRoot);
+const isAddressLike = (value) => value.includes(':') || /^\d{1,3}(\.\d{1,3}){3}$/.test(value);
+const cleanName = (value) => String(value).trim().replace(/\.$/, '').toLowerCase();
 
-  // 1. Match by Tailscale IP or LAN IP
-  let found = nodes.find((n) => String(n.ip) === wanted || String(n.lan_ip) === wanted);
-  if (found) return found;
+function meshNodeError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
 
-  // 2. Match by key derived from enriched hostname (Tailscale DNSName first part)
-  found = nodes.find((n) => meshNodeKey(n.hostname) === key);
-  if (found) return found;
+/** A control-server entry no live peer or entity accounts for. */
+function registryOnlyNode(entry) {
+  const addresses = (entry.ipAddresses || []).map(String);
+  const name = entry.givenName || entry.name || null;
+  return {
+    hostname: name,
+    os_hostname: entry.name || null,
+    ip: addresses[0] || null,
+    ips: addresses,
+    lan_ip: null,
+    online: entry.online === true,
+    self: false,
+    title: name,
+    has_entity: false,
+    vault_only: false,
+    registry_only: true,
+    registry_id: entry.id == null ? null : String(entry.id),
+    access: null,
+  };
+}
 
-  // 3. Match by entity title
-  found = nodes.find((n) => n.title && meshNodeKey(n.title) === key);
-  if (found) return found;
+/**
+ * Every node reference can be resolved against, each with the identities an
+ * operator might type: what the local daemon reports (DNS name, the machine's
+ * own hostname, every address), what the vault records (title, LAN address),
+ * and what the control server lists (`name`, `givenName`, `id`).
+ *
+ * Registry entries join a node by a shared address. An entry nothing claims
+ * becomes a node of its own, so a machine only the control server knows about
+ * still resolves; it carries no access, which callers report as such.
+ */
+function meshNodeCandidates(nodes = [], registry = null) {
+  const entries = Array.isArray(registry) ? registry : [];
+  const claimed = new Set();
+  const identities = (node, entry) => {
+    const names = [node.hostname, node.os_hostname, node.title, entry?.name, entry?.givenName].filter(Boolean);
+    return {
+      addresses: new Set(
+        [node.ip, node.lan_ip, ...(node.ips || []), ...(entry?.ipAddresses || [])]
+          .filter(Boolean)
+          .map((v) => String(v).toLowerCase()),
+      ),
+      names: new Set(names.map(cleanName)),
+      keys: new Set(names.map(meshNodeKey).filter(Boolean)),
+      id: entry?.id == null || entry.id === '' ? null : String(entry.id),
+    };
+  };
 
-  // 4. When a registry (Headscale API) is available, match by givenName or name
-  if (registry && Array.isArray(registry)) {
-    const entry = registry.find(
-      (r) => (r.givenName && meshNodeKey(r.givenName) === key) ||
-            (r.name && meshNodeKey(r.name) === key)
+  const candidates = nodes.map((node) => {
+    const own = new Set([node.ip, ...(node.ips || [])].filter(Boolean).map(String));
+    const index = entries.findIndex(
+      (e, i) => !claimed.has(i) && (e.ipAddresses || []).some((ip) => own.has(String(ip))),
     );
-    if (entry) {
-      const addresses = entry.ipAddresses || [];
-      found = addresses.map((ip) => nodes.find((n) => String(n.ip) === String(ip))).find(Boolean);
-      if (found) return found;
-      // Return a synthetic node from registry details
-      return {
-        hostname: entry.givenName || entry.name || wanted,
-        ip: addresses[0] || null,
-        title: entry.givenName || entry.name || '',
-      };
+    if (index !== -1) claimed.add(index);
+    return { node, ids: identities(node, index === -1 ? null : entries[index]) };
+  });
+  entries.forEach((entry, i) => {
+    if (claimed.has(i)) return;
+    const node = registryOnlyNode(entry);
+    candidates.push({ node, ids: identities(node, entry) });
+  });
+  return candidates;
+}
+
+/**
+ * Resolve a node reference against every identity `mesh nodes` can print.
+ *
+ * Precedence, first tier with a match wins: exact address, exact whole name,
+ * first-label key (never for an address, whose first label is shared by every
+ * node on the range), then the control server's node id.
+ *
+ * A machine's own hostname is not unique (two phones both report `localhost`),
+ * so a reference that matches two machines in the deciding tier is refused
+ * rather than resolved to whichever came first: `exec` would otherwise run on
+ * the wrong host. A vault-only record that shares a match with a live or
+ * registered node is set aside first — Headscale reassigns a freed address, so
+ * a stale record at that address describes the machine that held it before.
+ *
+ * Pure: callers supply the nodes and, optionally, the registry.
+ *
+ * @returns {object|null} the matching node; throws MESH_NODE_AMBIGUOUS
+ */
+export function matchMeshNode(nameOrAddress, nodes = [], registry = null) {
+  const wanted = String(nameOrAddress || '').trim();
+  if (!wanted) return null;
+  const lower = wanted.toLowerCase();
+  const exact = cleanName(wanted);
+  const key = isAddressLike(wanted) ? '' : meshNodeKey(wanted);
+  const candidates = meshNodeCandidates(nodes, registry);
+
+  const tiers = [
+    (ids) => ids.addresses.has(lower),
+    (ids) => ids.names.has(exact),
+    (ids) => !!key && ids.keys.has(key),
+    (ids) => ids.id === wanted,
+  ];
+
+  for (const matches of tiers) {
+    const hits = candidates.filter((c) => matches(c.ids));
+    if (!hits.length) continue;
+    const current = hits.filter((c) => !c.node.vault_only);
+    const pool = current.length ? current : hits;
+    if (pool.length > 1) {
+      const names = pool.map((c) => `${c.node.hostname || '?'} (${c.node.ip || 'no address'})`);
+      throw meshNodeError(
+        'MESH_NODE_AMBIGUOUS',
+        `"${wanted}" matches more than one mesh node: ${names.join(', ')}. Use its address or full name.`,
+      );
     }
+    return pool[0].node;
   }
-
   return null;
 }
 
+/** Find an enriched node (live + vault, plus `registry` when given) synchronously. */
+export function findMeshNode(nameOrAddress, vaultRoot = meshVaultRoot(), registry = null) {
+  return matchMeshNode(nameOrAddress, listEnrichedMeshNodes(vaultRoot), registry);
+}
+
+async function fetchMeshRegistry(brainDir) {
+  const { headscaleFetch } = await import('./headscale-client.mjs');
+  const data = await headscaleFetch('/api/v1/node', {}, brainDir);
+  return Array.isArray(data?.nodes) ? data.nodes : [];
+}
+
+/**
+ * The one resolver every command that takes a node goes through.
+ *
+ * Local discovery and the vault answer first, so a name this machine already
+ * knows never needs the control-server credential. Only on a miss is the
+ * control server asked — that is where registry-only names and node ids live.
+ * When it cannot be asked, the not-found error says why, so a locked secrets
+ * store is never reported as a machine that does not exist.
+ *
+ * @param {string} nameOrAddress
+ * @param {{vaultRoot?: string, brainDir?: string, nodes?: object[], fetchRegistry?: Function}} [options]
+ * @returns {Promise<object>} the node; throws MESH_NODE_NOT_FOUND or MESH_NODE_AMBIGUOUS
+ */
+export async function resolveMeshNode(nameOrAddress, options = {}) {
+  const wanted = String(nameOrAddress || '').trim();
+  if (!wanted) throw meshNodeError('MESH_NODE_NOT_FOUND', 'A mesh node name or address is required.');
+  const nodes = options.nodes || listEnrichedMeshNodes(options.vaultRoot || meshVaultRoot());
+
+  const local = matchMeshNode(wanted, nodes);
+  if (local) return local;
+
+  let registry = null;
+  let registryError = null;
+  try {
+    registry = await (options.fetchRegistry || fetchMeshRegistry)(options.brainDir);
+  } catch (err) {
+    registryError = err;
+  }
+  const found = registry ? matchMeshNode(wanted, nodes, registry) : null;
+  if (found) return found;
+
+  throw meshNodeError(
+    'MESH_NODE_NOT_FOUND',
+    `No mesh node matches "${wanted}".` +
+      (registryError ? ` The control server could not be asked: ${registryError.message}` : ''),
+  );
+}
+
 /**
  * Record how to reach a node.
  *
@@ -358,8 +497,14 @@ export function findMeshNode(nameOrAddress, vaultRoot = meshVaultRoot(), registr
  */
 export async function setMeshNodeAccess(nameOrAddress, accessPatch, options = {}) {
   const vaultRoot = options.vaultRoot || meshVaultRoot();
-  const node = findMeshNode(nameOrAddress, vaultRoot);
-  if (!node) return { written: false, reason: 'node-not-found' };
+  let node;
+  try {
+    node = await resolveMeshNode(nameOrAddress, { vaultRoot, brainDir: options.brainDir });
+  } catch (err) {
+    if (err.code === 'MESH_NODE_NOT_FOUND') return { written: false, reason: 'node-not-found', error: err.message };
+    if (err.code === 'MESH_NODE_AMBIGUOUS') return { written: false, reason: 'node-ambiguous', error: err.message };
+    throw err;
+  }
 
   const entities = listMeshNodeEntities(vaultRoot);
   const otherHosts = new Set(
@@ -679,11 +824,50 @@ export async function patchOwnMeshNode(options = {}) {
  * @param {boolean} [options.loginShell=true]
  * @returns {Promise<{ node: string, hostname: string, ip: string, exitCode: number, success: boolean, stdout: string, stderr: string }>}
  */
+/**
+ * Is `node` the machine running this command?
+ *
+ * Every host reaches itself through its own sshd, so `mesh ssh`/`mesh exec`
+ * aimed at self is a misconfiguration, not a remote call: it burns an auth
+ * round-trip, fails under `BatchMode` when this host holds no key for its own
+ * account, and hides the real intent (work that belongs to the local machine).
+ *
+ * Identity comes only from what the local daemon and registry report: the
+ * `self` flag, an exact address, or a whole hostname under any of its MagicDNS
+ * forms. Short labels are compared for HOSTNAMES ONLY — applied to an address
+ * they would compare the first octet, which every node on a shared range has
+ * in common, and match unrelated peers. Never key on a device name, a tailnet
+ * domain or an address range.
+ */
+export function isSelfNode(node, selfOverride) {
+  if (!node) return false;
+  if (node.self) return true;
+  const self = selfOverride === undefined ? getMeshSelf() : selfOverride;
+  if (!self) return false;
+
+  const isAddress = (value) => value.includes(':') || /^\d{1,3}(\.\d{1,3}){3}$/.test(value);
+  const clean = (v) => String(v || '').replace(/\.$/, '').toLowerCase();
+  const selfValues = [self.hostname, self.ip, self.name].filter(Boolean).map(clean);
+  const selfAddresses = new Set(selfValues.filter(isAddress));
+  const selfNames = new Set(selfValues.filter((v) => !isAddress(v)));
+  const selfLabels = new Set([...selfNames].map((v) => v.split('.')[0]));
+
+  return [node.hostname, node.ip, node.name].filter(Boolean).map(clean).some((candidate) => {
+    if (selfAddresses.has(candidate)) return true;
+    if (selfNames.has(candidate)) return true;
+    // A hostname may arrive fully qualified or bare; an address may not.
+    return !isAddress(candidate) && selfLabels.has(candidate.split('.')[0]);
+  });
+}
+
 export async function execMeshCommand(target, command, options = {}) {
   const { vaultRoot = meshVaultRoot(), timeoutMs = 60_000, loginShell = true } = options;
-  const node = findMeshNode(target, vaultRoot);
-  if (!node) {
-    throw new Error(`No mesh node matches "${target}".`);
+  const node = await resolveMeshNode(target, { vaultRoot, brainDir: options.brainDir });
+  if (isSelfNode(node)) {
+    throw new Error(
+      `"${node.hostname}" is this machine, and the mesh never tunnels a node into itself. `
+      + 'Run the command locally; the mesh CLI addresses peers.',
+    );
   }
   const resolved = resolveNodeAccess(node);
   if (!resolved.complete) {

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

@@ -172,9 +172,14 @@ router.post('/api/mesh/access', requireAuth, requireScope('config:write'), async
     const result = await setMeshNodeAccess(target, patch, { vaultRoot: meshVaultRoot() });
     if (!result.written) {
       const notFound = result.reason === 'node-not-found';
-      res.status(notFound ? 404 : 500).json({
+      const ambiguous = result.reason === 'node-ambiguous';
+      res.status(notFound ? 404 : ambiguous ? 409 : 500).json({
         success: false,
-        message: notFound ? `No mesh node matches "${target}".` : 'The vault write was rejected.',
+        message: notFound
+          ? `No mesh node matches "${target}".`
+          : ambiguous
+            ? result.error
+            : 'The vault write was rejected.',
         reason: result.reason || null,
       });
       return;